ENH: Added documentation.

include/ActorC.hh

@@ -13,6 +13,12 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 
 =========================================================================*/
+// .NAME vlActorCollection - a list of actors
+// .SECTION Description
+// vlActorCollection represents and provides methods to manipulate list of
+// actors (i.e., vlActor and subclasses). The list is unsorted and duplicate
+// entries are not prevented.
+
 #ifndef __vlActorC_hh
 #define __vlActorC_hh
 
@@ -22,16 +28,43 @@ Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 class vlActorCollection : public vlCollection
 {
  public:
-  void AddItem(vlActor *a) {this->vlCollection::AddItem((vlObject *)a);};
-  void RemoveItem(vlActor *a) 
-    {this->vlCollection::RemoveItem((vlObject *)a);};
-  int IsItemPresent(vlActor *a) 
-    {return this->vlCollection::IsItemPresent((vlObject *)a);};
-  vlActor *GetItem(int num) 
-    { return (vlActor *)(this->vlCollection::GetItem(num));};
   char *GetClassName() {return "vlActorCollection";};
+
+  void AddItem(vlActor *a);
+  void RemoveItem(vlActor *a);
+  int IsItemPresent(vlActor *a);
+  vlActor *GetItem(int num);
 };
 
+// Description:
+// Add an actor to the list.
+inline void vlActorCollection::AddItem(vlActor *a) 
+{
+  this->vlCollection::AddItem((vlObject *)a);
+}
+
+// Description:
+// Remove an actor from the list.
+inline void vlActorCollection::RemoveItem(vlActor *a) 
+{
+  this->vlCollection::RemoveItem((vlObject *)a);
+}
+
+// Description:
+// Determine whether a particular actor is present. Returns its position
+// in the list.
+inline int vlActorCollection::IsItemPresent(vlActor *a) 
+{
+  return this->vlCollection::IsItemPresent((vlObject *)a);
+}
+
+// Description:
+// Get an actor in the list at a particular location (1<=num<=number items).
+inline vlActor *vlActorCollection::GetItem(int num) 
+{ 
+  return (vlActor *)(this->vlCollection::GetItem(num));
+}
+
 #endif
 
 

include/Camera.hh

@@ -13,6 +13,15 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 
 =========================================================================*/
+// .NAME vlCamera - a virtual camera for 3D rendering
+// .SECTION Description
+// vlCamera is a virtual camera for 3D rendering. It provides methods
+// to position and orient the view point and focal point. Convenience 
+// methods for moving about the focal point are also provided. More 
+// complex methods allow the manipulation of the computer graphics
+// graphics model including view up vector, clipping planes, and 
+// camera perspective.
+
 #ifndef __vlCamera_hh
 #define __vlCamera_hh
 
@@ -23,46 +32,42 @@ class vlRenderer;
 
 class vlCamera : public vlObject
 {
- protected:
-  float FocalPoint[3];
-  float Position[3];
-  float ViewUp[3];
-  float ViewAngle;
-  float ClippingRange[2];
-  float EyeAngle;
-  int   LeftEye;
-  int   Switch;
-  float Thickness;
-  float Distance;
-  float ViewPlaneNormal[3];
-  vlTransform Transform;
-  vlTransform PerspectiveTransform;
-  float Orientation[3];
-
  public:
   vlCamera();
+  void PrintSelf(ostream& os, vlIndent indent);
+  char *GetClassName() {return "vlCamera";};
 
-  void SetPosition(float , float, float);
+  void SetPosition(float x, float y, float z);
   void SetPosition(float a[3]);
   vlGetVectorMacro(Position,float);
 
-  void SetFocalPoint(float , float, float);
+  void SetFocalPoint(float x, float y, float z);
   void SetFocalPoint(float a[3]);
   vlGetVectorMacro(FocalPoint,float);
 
-  void SetViewUp(float , float, float);
+  void SetViewUp(float vx, float vy, float vz);
   void SetViewUp(float a[3]);
   vlGetVectorMacro(ViewUp,float);
 
-  void SetClippingRange(float , float);
+  void SetClippingRange(float front, float back);
   void SetClippingRange(float a[2]);
   vlGetVectorMacro(ClippingRange,float);
 
+  // Description:
+  // Abstract interface to renderer. Each concrete subclass of vlCamera
+  // will load its data into graphics system in response to this method
+  // invocation.
   virtual void Render(vlRenderer *ren) = 0;
 
+  // Description:
+  // Set the camera view angle (i.e., the width of view in degrees). Larger
+  // values yield greater perspective ditortion.
   vlSetClampMacro(ViewAngle,float,1.0,179.0);
   vlGetMacro(ViewAngle,float);
 
+  // Description:
+  // Set the seperation between eyes (in degrees). Used to generate stereo
+  // images.
   vlSetMacro(EyeAngle,float);
   vlGetMacro(EyeAngle,float);
 
@@ -72,13 +77,15 @@ class vlCamera : public vlObject
   void SetDistance(float);
   vlGetMacro(Distance,float);
 
+  // Description:
+  // Turn the camera on/off.
   vlSetMacro(Switch,int);
   vlGetMacro(Switch,int);
   vlBooleanMacro(Switch,int);
 
   float GetTwist();
   void SetViewPlaneNormal(float a[3]);
-  void SetViewPlaneNormal(float x,float y,float z);
+  void SetViewPlaneNormal(float x, float y, float z);
   void CalcViewPlaneNormal();
   void CalcDistance();
   void CalcPerspectiveTransform();
@@ -98,8 +105,22 @@ class vlCamera : public vlObject
 
   float *GetOrientation();
 
-  void PrintSelf(ostream& os, vlIndent indent);
-  char *GetClassName() {return "vlCamera";};
+ protected:
+  float FocalPoint[3];
+  float Position[3];
+  float ViewUp[3];
+  float ViewAngle;
+  float ClippingRange[2];
+  float EyeAngle;
+  int   LeftEye;
+  int   Switch;
+  float Thickness;
+  float Distance;
+  float ViewPlaneNormal[3];
+  vlTransform Transform;
+  vlTransform PerspectiveTransform;
+  float Orientation[3];
+
 };
 
 #endif

include/Light.hh

@@ -13,6 +13,11 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 
 =========================================================================*/
+// .NAME vlLight - a virtual light for 3D rendering
+// .SECTION Description
+// vlLight is a virtual light for 3D rendering. It provides methods to locate
+// and point the light, turn it on and off, and set its brightness and color.
+
 #ifndef __vlLight_hh
 #define __vlLight_hh
 
@@ -23,35 +28,50 @@ class vlRenderer;
 
 class vlLight : public vlObject
 {
-protected:
-  float FocalPoint[3];
-  float Position[3];
-  float Intensity;
-  float Color[3];
-  int   Switch;
-
 public:
   vlLight();
   char *GetClassName() {return "vlLight";};
   void PrintSelf(ostream& os, vlIndent indent);
+
+  // Description:
+  // Abstract interface to renderer. Each concrete subclass of vlLight
+  // will load its data into graphics system in response to this method
+  // invocation.
   virtual void Render(vlRenderer *ren,int light_index) = 0;
 
+  // Description:
+  // Set the color of the light.
   vlSetVector3Macro(Color,float);
   vlGetVectorMacro(Color,float);
 
+  // Description:
+  // Set the position of the light.
   vlSetVector3Macro(Position,float);
   vlGetVectorMacro(Position,float);
 
+  // Description:
+  // Set the point at which the light is shining.
   vlSetVector3Macro(FocalPoint,float);
   vlGetVectorMacro(FocalPoint,float);
 
+  // Description:
+  // Set the brightness of the light.
   vlSetMacro(Intensity,float);
   vlGetMacro(Intensity,float);
 
+  // Description:
+  // Turn the light on/off.
   vlSetMacro(Switch,int);
   vlGetMacro(Switch,int);
   vlBooleanMacro(Switch,int);
 
+protected:
+  float FocalPoint[3];
+  float Position[3];
+  float Intensity;
+  float Color[3];
+  int   Switch;
+
 };
 
 #endif

include/LightC.hh

@@ -13,6 +13,12 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 
 =========================================================================*/
+// .NAME vlLightCollection - a list of lights
+// .SECTION Description
+// vlLightCollection represents and provides methods to manipulate list of
+// lights (i.e., vlLight and subclasses). The list is unsorted and duplicate
+// entries are not prevented.
+
 #ifndef __vlLightC_hh
 #define __vlLightC_hh
 
@@ -22,15 +28,42 @@ Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 class vlLightCollection : public vlCollection
 {
  public:
-  void AddItem(vlLight *a) {this->vlCollection::AddItem((vlObject *)a);};
-  void RemoveItem(vlLight *a) 
-    {this->vlCollection::RemoveItem((vlObject *)a);};
-  int IsItemPresent(vlLight *a) 
-    {return this->vlCollection::IsItemPresent((vlObject *)a);};
-  vlLight *GetItem(int num) 
-    { return (vlLight *)(this->vlCollection::GetItem(num));};
   char *GetClassName() {return "vlLightCollection";};
+
+  void AddItem(vlLight *a);
+  void RemoveItem(vlLight *a);
+  int IsItemPresent(vlLight *a);
+  vlLight *GetItem(int num);
 };
 
+// Description:
+// Add an light to the list.
+inline void vlLightCollection::AddItem(vlLight *a) 
+{
+  this->vlCollection::AddItem((vlObject *)a);
+}
+
+// Description:
+// Remove an light from the list.
+inline void vlLightCollection::RemoveItem(vlLight *a) 
+{
+  this->vlCollection::RemoveItem((vlObject *)a);
+}
+
+// Description:
+// Determine whether a particular light is present. Returns its position
+// in the list.
+inline int vlLightCollection::IsItemPresent(vlLight *a) 
+{
+  return this->vlCollection::IsItemPresent((vlObject *)a);
+}
+
+// Description:
+// Get an light in the list at a particular location (1<=num<=number items).
+inline vlLight *vlLightCollection::GetItem(int num) 
+{ 
+  return (vlLight *)(this->vlCollection::GetItem(num));
+}
+
 #endif
 

include/Property.hh

@@ -13,6 +13,17 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 
 =========================================================================*/
+// .NAME vlProperty - represent surface properties of a geometric object
+// .SECTION Description
+// vlProperty is an object that represents lighting and other surface
+// properties of a geometric object. The primary properties that can be 
+// set are colors (object, ambient, diffuse, specular, and edge color),
+// specular power, transparency of the object, the representation of the
+// object (points, wireframe, or surface), and the shading method to be 
+// used (flat, Gouraud, and Phong).
+// .SECTION See Also
+// See vlRenderer for definition of #define's.
+
 #ifndef __vlProperty_hh
 #define __vlProperty_hh
 
@@ -23,27 +34,15 @@ class vlRenderer;
 
 class vlProperty : public vlObject
 {
- protected:
-  float Color[3];
-  float AmbientColor[3];
-  float DiffuseColor[3];
-  float SpecularColor[3];
-  float EdgeColor[3];
-  float Ambient;
-  float Diffuse;
-  float Specular;
-  float SpecularPower;
-  float Transparency;
-  int   Interpolation;   /* gouraud */
-  int   Representation;  /* solid */
-  int   EdgeVisibility;
-  int   Backface;
-  int   Subdivide;
-
- public:
+public:
   vlProperty();
   char *GetClassName() {return "vlProperty";};
   void PrintSelf(ostream& os, vlIndent indent);
+
+  // Description:
+  // Abstract interface to renderer. Each concrete subclass of vlProperty
+  // will load its data into graphics system in response to this method
+  // invocation.
   virtual void Render(vlRenderer *ren) = 0;
 
   void SetFlat (void);
@@ -53,47 +52,95 @@ class vlProperty : public vlObject
   void SetWireframe (void);
   void SetSurface (void);
 
+  // Description:
+  // Get the method of representation for the object.
   vlGetMacro(Representation,int);
+
+  // Description:
+  // Get the shading method for the object.
   vlGetMacro(Interpolation,int);
 
   void SetColor(float r,float g,float b);
   void SetColor(float a[3]) { this->SetColor(a[0], a[1], a[2]); };
   vlGetVectorMacro(Color,float);
 
-  vlGetMacro(Ambient,float);
+  // Description:
+  // Set ambient coefficient.
   vlSetClampMacro(Ambient,float,0.0,1.0);
+  vlGetMacro(Ambient,float);
 
-  vlGetMacro(Diffuse,float);
+  // Description:
+  // Set diffuse coefficient.
   vlSetClampMacro(Diffuse,float,0.0,1.0);
+  vlGetMacro(Diffuse,float);
 
-  vlGetMacro(Specular,float);
+  // Description:
+  // Set specular coefficient.
   vlSetClampMacro(Specular,float,0.0,1.0);
+  vlGetMacro(Specular,float);
 
-  vlGetMacro(SpecularPower,float);
+  // Description:
+  // Set the specular power.
   vlSetClampMacro(SpecularPower,float,0.0,100.0);
+  vlGetMacro(SpecularPower,float);
 
-  vlGetMacro(Transparency,float);
+  // Description:
+  // Set the object transparency.
   vlSetClampMacro(Transparency,float,0.0,1.0);
+  vlGetMacro(Transparency,float);
 
+  // Description:
+  // Turn on/off the visibility of edges. On some renderers it is
+  // possible to render the edges of geometric primitives separately
+  // from the interior.
   vlGetMacro(EdgeVisibility,int);
   vlSetMacro(EdgeVisibility,int);
   vlBooleanMacro(EdgeVisibility,int);
 
+  // Description:
+  // Turn on/off screen subdivision. Screen subdivision is used to perform
+  // aliasing on the image.
   vlGetMacro(Subdivide,int);
   vlSetMacro(Subdivide,int);
   vlBooleanMacro(Subdivide,int);
 
+  // Description:
+  // Set the ambient light color.
   vlSetVector3Macro(AmbientColor,float);
   vlGetVectorMacro(AmbientColor,float);
 
+  // Description:
+  // Set the diffuse light color.
   vlSetVector3Macro(DiffuseColor,float);
   vlGetVectorMacro(DiffuseColor,float);
 
+  // Description:
+  // Set the specular color.
   vlSetVector3Macro(SpecularColor,float);
   vlGetVectorMacro(SpecularColor,float);
 
+  // Description:
+  // Set the color of edges (if edge visibility enabled).
   vlSetVector3Macro(EdgeColor,float);
   vlGetVectorMacro(EdgeColor,float);
+
+protected:
+  float Color[3];
+  float AmbientColor[3];
+  float DiffuseColor[3];
+  float SpecularColor[3];
+  float EdgeColor[3];
+  float Ambient;
+  float Diffuse;
+  float Specular;
+  float SpecularPower;
+  float Transparency;
+  int   Interpolation; 
+  int   Representation;
+  int   EdgeVisibility;
+  int   Backface;
+  int   Subdivide;
+
 };
 
 #endif

include/RenderC.hh

@@ -13,6 +13,12 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 
 =========================================================================*/
+// .NAME vlRendererCollection - a list of renderers
+// .SECTION Description
+// vlRendererCollection represents and provides methods to manipulate list of
+// renderers (i.e., vlRenderer and subclasses). The list is unsorted and 
+// duplicate entries are not prevented.
+
 #ifndef __vlRendererCollection_hh
 #define __vlRendererColleciton_hh
 
@@ -22,17 +28,42 @@ Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 class vlRendererCollection : public vlCollection
 {
  public:
-  void AddItem(vlRenderer *a) 
-    {this->vlCollection::AddItem((vlObject *)a);};
-  void RemoveItem(vlRenderer *a) 
-    {this->vlCollection::RemoveItem((vlObject *)a);};
-  int IsItemPresent(vlRenderer *a) 
-    {return this->vlCollection::IsItemPresent((vlObject *)a);};
-  vlRenderer *GetItem(int num) 
-    { return (vlRenderer *)(this->vlCollection::GetItem(num));};
   char *GetClassName() {return "vlRendererCollection";};
 
+  void AddItem(vlRenderer *a);
+  void RemoveItem(vlRenderer *a);
+  int IsItemPresent(vlRenderer *a);
+  vlRenderer *GetItem(int num);
   void Render();
 };
 
+// Description:
+// Add an renderer to the list.
+inline void vlRendererCollection::AddItem(vlRenderer *a) 
+{
+  this->vlCollection::AddItem((vlObject *)a);
+}
+
+// Description:
+// Remove an renderer from the list.
+inline void vlRendererCollection::RemoveItem(vlRenderer *a) 
+{
+  this->vlCollection::RemoveItem((vlObject *)a);
+}
+
+// Description:
+// Determine whether a particular renderer is present. Returns its position
+// in the list.
+inline int vlRendererCollection::IsItemPresent(vlRenderer *a) 
+{
+  return this->vlCollection::IsItemPresent((vlObject *)a);
+}
+
+// Description:
+// Get an renderer in the list at a particular location (1<=num<=number items).
+inline vlRenderer *vlRendererCollection::GetItem(int num) 
+{
+  return (vlRenderer *)(this->vlCollection::GetItem(num));
+}
+
 #endif

include/RenderW.hh

@@ -13,6 +13,16 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 
 =========================================================================*/
+// .NAME vlRenderWindow - create a window for renderers to draw into
+// .SECTION Description
+// vlRenderWindow is an abstract object to specify the behavior of a
+// rendering window. A rendering window is a window in a graphical user
+// interface where renderers draw their images. Methods are provided to 
+// synchronize the rendering process, set window size, and control double
+// buffering. Another set of important methods allow the creation of
+// device dependent actors, lights, and cameras. These objects are created
+// depending upon the value of the environment variable "VL_RENDERER".
+
 #ifndef __vlRenderWindow_hh
 #define __vlRenderWindow_hh
 
@@ -42,29 +52,64 @@ public:
   vlRendererCollection *GetRenderers() {return &(this->Renderers);};
 
   virtual void Render();
-  virtual void Frame() = 0;
+
+  // Description:
+  // Initialize rendering process.
   virtual void Start() = 0;
+
+  // Description:
+  // Performed at the end of the rendering process to generate image.
+  virtual void Frame() = 0;
+
+  // Description:
+  // Create a device specific renderer.
   virtual vlRenderer  *MakeRenderer() = 0;
+
+  // Description:
+  // Create a device specific actor.
   virtual vlActor     *MakeActor() = 0;
+
+  // Description:
+  // Create a device specific light.
   virtual vlLight     *MakeLight() = 0;
+
+  // Description:
+  // Create a device specific camera.
   virtual vlCamera    *MakeCamera() = 0;
+
+  // Description:
+  // Get the position in screen coordinates of the rendering window.
   virtual int *GetPosition() = 0;
+
+  // Description:
+  // Get the size of the window in screen coordinates.
   virtual int *GetSize() = 0;
+
+  // Description:
+  // Set the size of the window in screen coordinates.
   virtual void SetSize(int,int) = 0;
   virtual void SetSize(int a[2]);
 
+  // Description:
+  // Turn on/off rendering full screen window size.
   virtual void SetFullScreen(int) = 0;
   vlGetMacro(FullScreen,int);
   vlBooleanMacro(FullScreen,int);
 
+  // Description:
+  // Turn on/off window manager borders.
   vlSetMacro(Borders,int);
   vlGetMacro(Borders,int);
   vlBooleanMacro(Borders,int);
 
+  // Description:
+  // Keep track of whether rendering window has been mapped to screen.
   vlSetMacro(Mapped,int);
   vlGetMacro(Mapped,int);
   vlBooleanMacro(Mapped,int);
 
+  // Description:
+  // Turn on/off double buffering.
   vlSetMacro(DoubleBuffer,int);
   vlGetMacro(DoubleBuffer,int);
   vlBooleanMacro(DoubleBuffer,int);

include/Renderer.hh

@@ -13,6 +13,16 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 
 =========================================================================*/
+// .NAME vlRenderer - abstract specification  for renderers
+// .SECTION Description
+// vlRenderer provides an abstract specification for renderers. A renderer
+// is an object that controls the rendering process for objects. Rendering is
+// the process of converting geometry, a specification for lights, and a 
+// camera view into an image. vlRenderer also performs coordinate 
+// transformation between world coordinates, view coordinates (the computer
+// graphics rendering coordinate system), and display coordinates (the actual
+// screen coordinates on the display device).
+
 #ifndef __vlRenderer_hh
 #define __vlRenderer_hh
 
@@ -27,22 +37,6 @@ class vlRenderWindow;
 
 class vlRenderer : public vlObject
 {
-protected:
-  vlCamera *ActiveCamera;
-  vlLightCollection Lights;