ENH: Added documentation.

include/SScalars.hh

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -15,11 +13,11 @@ without the express written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-// Short representation of scalars
-//
-//  use internal short array to represent data
-//
+// .NAME vlShortScalars - short integer representation of scalar data
+// .SECTION Description
+// vlShortScalars is a concrete implementation of vlScalars. Scalars are
+// represented using short integer values.
+
 #ifndef __vlShortScalars_h
 #define __vlShortScalars_h
 
@@ -30,21 +28,17 @@ class vlShortScalars : public vlScalars
 {
 public:
   vlShortScalars() {};
-  vlScalars *MakeObject(int sze, int ext=1000);
-  int Allocate(const int sz, const int ext=1000) 
-    {return this->S.Allocate(sz,ext);};
-  void Initialize() {return this->S.Initialize();};
   vlShortScalars(const vlShortScalars& ss) {this->S = ss.S;};
   vlShortScalars(const int sz, const int ext=1000):S(sz,ext){};
   ~vlShortScalars() {};
+  int Allocate(const int sz, const int ext=1000) {return this->S.Allocate(sz,ext);};
+  void Initialize() {return this->S.Initialize();};
   char *GetClassName() {return "vlShortScalars";};
+
+  // vlScalar interface
+  vlScalars *MakeObject(int sze, int ext=1000);
   int GetNumberOfScalars() {return (this->S.GetMaxId()+1);};
-  void Reset() {this->S.Reset();};
   void Squeeze() {this->S.Squeeze();};
-  vlShortScalars &operator=(const vlShortScalars& ss);
-  void operator+=(const vlShortScalars& ss) {this->S += ss.S;};
-
-  // float conversion for abstract computation
   float GetScalar(int i) {return (float)this->S[i];};
   void SetScalar(int i, short s) {this->S[i] = s;};
   void SetScalar(int i, float s) {this->S[i] = (short)s;};
@@ -53,6 +47,11 @@ public:
   int InsertNextScalar(short s) {return S.InsertNextValue(s);};
   int InsertNextScalar(float s) {return S.InsertNextValue((short)s);};
 
+  // miscellaneous
+  vlShortScalars &operator=(const vlShortScalars& ss);
+  void operator+=(const vlShortScalars& ss) {this->S += ss.S;};
+  void Reset() {this->S.Reset();};
+
 private:
   vlShortArray S;
 };

include/Scalars.hh

@@ -13,9 +13,13 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-// Abstract interface to scalar values.
-//
+// .NAME vlScalars - abstract interface to scalar array
+// .SECTION Description
+// vlScalars provides an abstract interface to an array of scalar data. 
+// The data model for vlScalars is an array accessible by point id.
+// The subclasses of vlScalars are concrete data types (float, int, etc.) 
+// that implement the interface of vlScalars.
+
 #ifndef __vlScalars_h
 #define __vlScalars_h
 
@@ -29,17 +33,39 @@ class vlScalars : public vlObject
 public:
   vlScalars();
   virtual ~vlScalars() {};
+  char *GetClassName() {return "vlScalars";};
+  void PrintSelf(ostream& os, vlIndent indent);
+
+  // Description:
+  // Create a copy of this object.
   virtual vlScalars *MakeObject(int sze, int ext=1000) = 0;
+
+  // Description:
+  // Return number of points in array.
   virtual int GetNumberOfScalars() = 0;
+
+  // Description:
+  // Return a float scalar value for a particular point id.
   virtual float GetScalar(int i) = 0;
-  virtual void SetScalar(int i, float s) = 0;     // fast insert
-  virtual void InsertScalar(int i, float s) = 0;  // allocates memory as necessary
+
+  // Description:
+  // Insert scalar into array. No range checking performed (fast!).
+  virtual void SetScalar(int i, float s) = 0;
+
+  // Description:
+  // Insert scalar into array. Range checking performed and memory
+  // allocated as necessary.
+  virtual void InsertScalar(int i, float s) = 0;
+
+  // Description:
+  // Insert scalar into next available slot. Returns point id of slot.
   virtual int InsertNextScalar(float s) = 0;
+
+  // Description:
+  // Reclaim any extra memory.
   virtual void Squeeze() = 0;
 
   void GetScalars(vlIdList& ptId, vlFloatScalars& fs);
-  char *GetClassName() {return "vlScalars";};
-  void PrintSelf(ostream& os, vlIndent indent);
   virtual void ComputeRange();
   float *GetRange();
 

include/TCoords.hh

@@ -13,9 +13,15 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-// Abstract interface to texture coordinates
-//
+// .NAME vlTCoords - abstract interface to 3D texture coordinates
+// .SECTION Description
+// vlTCoords provides an abstract interface to 3D texture coordinates. 
+// Texture coordinates are 2D (u,v) or 3D (u,v,w) parametric values that
+// map geometry into regular 2D or 3D arrays of color and/or transparency
+// values. During rendering the array are mapped onto the geometry for
+// fast image detailing. The subclasses of vlTCoords are concrete data 
+// types (float, int, etc.) that implement the interface of vlTCoords. 
+
 #ifndef __vlTCoords_h
 #define __vlTCoords_h
 
@@ -27,19 +33,42 @@ class vlFloatTCoords;
 class vlTCoords : public vlObject 
 {
 public:
-  vlTCoords(int dim=2) {this->Dimension=dim;};
+  vlTCoords(int dim=2);
   virtual ~vlTCoords() {};
+  char *GetClassName() {return "vlTCoords";};
+  void PrintSelf(ostream& os, vlIndent indent);
+
+  // Description:
+  // Create a copy of this object.
   virtual vlTCoords *MakeObject(int sze, int d=2, int ext=1000) = 0;
+
+  // Description:
+  // Return number of texture coordinates in array.
   virtual int GetNumberOfTCoords() = 0;
+
+  // Description:
+  // Return a float texture coordinate tc[2/3] for a particular point id.
   virtual float *GetTCoord(int i) = 0;
-  virtual void SetTCoord(int i,float *tc) = 0;          // fast insert
-  virtual void InsertTCoord(int i, float *tc) = 0;      // allocates memory as necessary
+
+  // Description:
+  // Insert texture coordinate into object. No range checking performed (fast!).
+  virtual void SetTCoord(int i,float *tc) = 0;
+
+  // Description:
+  // Insert texture coordinate into object. Range checking performed and 
+  // memory allocated as necessary.
+  virtual void InsertTCoord(int i, float *tc) = 0;
+
+  // Description:
+  // Insert texture coordinate into next available slot. Returns point
+  // id of slot.
   virtual int InsertNextTCoord(float *tc) = 0;
+
+  // Description:
+  // Reclaim any extra memory.
   virtual void Squeeze() = 0;
 
   void GetTCoords(vlIdList& ptId, vlFloatTCoords& fp);
-  char *GetClassName() {return "vlTCoords";};
-  void PrintSelf(ostream& os, vlIndent indent);
 
   vlSetClampMacro(Dimension,int,1,3);
   vlGetMacro(Dimension,int);

include/Vectors.hh

@@ -13,9 +13,13 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-// Abstract interface to 3D vectors.
-//
+// .NAME vlPoints - abstract interface to 3D vectors
+// .SECTION Description
+// vlVectors provides an abstract interface to 3D vectors. The data model
+// for vlVectors is an array of vx-vy-vz triplets accessible by point id.
+// The subclasses of vlVectors are concrete data types (float, int, etc.)
+// that implement the interface of vlVectors.
+
 #ifndef __vlVectors_h
 #define __vlVectors_h
 
@@ -27,25 +31,47 @@ class vlFloatVectors;
 class vlVectors : public vlObject 
 {
 public:
- vlVectors();
+  vlVectors();
   virtual ~vlVectors() {};
+  char *GetClassName() {return "vlVectors";};
+  void PrintSelf(ostream& os, vlIndent indent);
+
+  // Description:
+  // Create a copy of this object.
   virtual vlVectors *MakeObject(int sze, int ext=1000) = 0;
+
+  // Description:
+  // Return number of vectors in array.
   virtual int GetNumberOfVectors() = 0;
+
+  // Description:
+  // Return a float vector v[3] for a particular point id.
   virtual float *GetVector(int i) = 0;
-  virtual void SetVector(int i,float v[3]) = 0;       // fast insert
-  virtual void InsertVector(int i, float v[3]) = 0;   // allocates memory as necessary
+
+  // Description:
+  // Insert vector into object. No range checking performed (fast!).
+  virtual void SetVector(int i,float v[3]) = 0;
+
+  // Description:
+  // Insert vector into object. Range checking performed and memory
+  // allocated as necessary.
+  virtual void InsertVector(int i, float v[3]) = 0;
+
+  // Description:
+  // Insert vector into next available slot. Returns point id of slot.
   virtual int InsertNextVector(float v[3]) = 0;
+
+  // Description:
+  // Reclaim any extra memory.
   virtual void Squeeze() = 0;
 
   void GetVectors(vlIdList& ptId, vlFloatVectors& fp);
-  char *GetClassName() {return "vlVectors";};
-  void PrintSelf(ostream& os, vlIndent indent);
   virtual void ComputeMaxNorm();
   float GetMaxNorm();
 
 protected:
   float MaxNorm;
-  vlTimeStamp ComputeTime; // Time at which range computed
+  vlTimeStamp ComputeTime; // Time at which MaxNorm computed
 };
 
 #endif

src/SScalars.cc

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -25,6 +23,8 @@ vlScalars *vlShortScalars::MakeObject(int sze, int ext)
   return new vlShortScalars(sze,ext);
 }
 
+// Description:
+// Deep copy of scalars.
 vlShortScalars& vlShortScalars::operator=(const vlShortScalars& ss)
 {
   this->S = ss.S;

src/Scalars.cc

@@ -13,9 +13,6 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-//  Scalars, abstract representation
-//
 #include "Scalars.hh"
 #include "FScalars.hh"
 #include "IdList.hh"
@@ -26,6 +23,8 @@ vlScalars::vlScalars()
   this->Range[1] = 1.0;
 }
 
+// Description:
+// Given a list of pt ids, return an array of scalar values.
 void vlScalars::GetScalars(vlIdList& ptId, vlFloatScalars& fs)
 {
   for (int i=0; i<ptId.GetNumberOfIds(); i++)
@@ -33,6 +32,9 @@ void vlScalars::GetScalars(vlIdList& ptId, vlFloatScalars& fs)
     fs.InsertScalar(i,this->GetScalar(ptId.GetId(i)));
     }
 }
+
+// Description:
+// Determine (rmin,rmax) range of scalar values.
 void vlScalars::ComputeRange()
 {
   int i;
@@ -53,6 +55,8 @@ void vlScalars::ComputeRange()
     }
 }
 
+// Description:
+// Return the range of scalar values.
 float *vlScalars::GetRange()
 {
   this->ComputeRange();

src/SpherSrc.cc

@@ -13,15 +13,14 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-// Methods for Sphere generator
-//
 #include <math.h>
 #include "SpherSrc.hh"
 #include "FPoints.hh"
 #include "FNormals.hh"
 #include "vlMath.hh"
 
+// Description:
+// Construct sphere with radius=0.5.
 vlSphereSource::vlSphereSource(int res)
 {
   res = res < 4 ? 4 : res;

src/TCoords.cc

@@ -13,13 +13,19 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-//  3D TCoords, abstract representation
-//
 #include "TCoords.hh"
 #include "IdList.hh"
 #include "FTCoords.hh"
 
+// Description:
+// Construct object whose texture coordinates are of specified dimension.
+vlTCoords::vlTCoords(int dim)
+{
+  this->Dimension = dim;
+}
+
+// Description:
+// Given a list of pt ids, return an array of texture coordinates.
 void vlTCoords::GetTCoords(vlIdList& ptId, vlFloatTCoords& ftc)
 {
   for (int i=0; i<ptId.GetNumberOfIds(); i++)

src/Trans.cc

@@ -633,7 +633,7 @@ float *vlTransform::GetPoint()
 // Transformed points are appended to output list (outPts).
 void vlTransform::MultiplyPoints(vlPoints *inPts, vlPoints *outPts)
 {
-  float newX[4];
+  float newX[3];
   float *x;
   int ptId, i;
   int numPts = inPts->GetNumberOfPoints();

src/Vectors.cc

@@ -13,9 +13,6 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-//  3D vectors, abstract representation
-//
 #include "Vectors.hh"
 #include "FVectors.hh"
 #include "IdList.hh"
@@ -26,6 +23,8 @@ vlVectors::vlVectors()
   this->MaxNorm = 0.0;
 }
 
+// Description:
+// Given a list of pt ids, return an array of vectors.
 void vlVectors::GetVectors(vlIdList& ptId, vlFloatVectors& fp)
 {
   for (int i=0; i<ptId.GetNumberOfIds(); i++)
@@ -33,6 +32,9 @@ void vlVectors::GetVectors(vlIdList& ptId, vlFloatVectors& fp)
     fp.InsertVector(i,this->GetVector(ptId.GetId(i)));
     }
 }
+
+// Description:
+// Compute the largest norm for these vectors.
 void vlVectors::ComputeMaxNorm()
 {
   int i;
@@ -53,6 +55,8 @@ void vlVectors::ComputeMaxNorm()
     }
 }
 
+// Description:
+// Return the maximum norm for these vectors.
 float vlVectors::GetMaxNorm()
 {
   this->ComputeMaxNorm();