14. Drawing Functions - `DrawFun`

The drawing function module implements an interface between the displayable geometry output by VisTools objects and the graphics subsystem. The DrawFun module is designed to be an "immediate mode" interface to the graphics subsystem. The DrawFun module is formally a member of the VglTools library. It is included as a support module to VisTools. A summary of the drawing functions used by VisTools appears below, see the VglTools Programmer Manual for a complete description of DrawFun.

Table of Contents

14.1 Drawing Function Summary

A DrawFun object defines function pointers to the graphics subsystem. Function pointers are required by each visualization object to direct the graphics device to draw lines, annotation text, polygons, and set transparency, line widths, etc. Generally a single draw function object is shared by all visualization objects. In addition to function pointers to the underlying graphics subsystem, each drawing function object maintains an auxiliary object pointer which is passed as the first argument to each drawing function. This auxiliary object pointer may be assigned by a module or by the user. The user defined object may be used to hang any information required to implement the drawing functions for a particular graphics subsystem.

Begin and end an instance of an object, generic object functions

*vgl_DrawFunBegin       - create an instance of a DrawFun object
vgl_DrawFunEnd          - destroy an instance of a DrawFun object
vgl_DrawFunError        - return DrawFun object error flag
vgl_DrawFunCopy         - make a copy of a DrawFun object

Set function pointers

vgl_DrawFunSet          - set function pointers
vgl_DrawFunSetObj       - set auxiliary object

Get built-in application programming interface (API) function pointers
```
vgl_DrawFunAPI          - get built-in API
```

Set pointers to the necessary drawing functions using vgl_DrawFunSet. Get pointers to drawing functions using vgl_DrawFunGet.

Table of Contents

14.2 Function Descriptions

The currently available DrawFun functions are described in detail in this section.

Table of Contents , DrawFun

NAME

*vgl_DrawFunBegin - create an instance of a DrawFun object

C SPECIFICATION

vgl_DrawFun *vgl_DrawFunBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created DrawFun object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a DrawFun object. Memory is allocated for the object private data and the pointer to the data is returned. By default all function pointers are NULL.

Destroy an instance of a DrawFun object using

     void vgl_DrawFunEnd (vgl_DrawFun *drawfun)

Return the current value of a DrawFun object error flag using

     Vint vgl_DrawFunError (vgl_DrawFun *drawfun)

Make a copy of a DrawFun object. The private data from the fromdrawfun object is copied to the drawfun object. Any previous private data in drawfun is lost.

     void vgl_DrawFunCopy (vgl_DrawFun *drawfun,
                           vgl_DrawFun *fromdrawfun)

Table of Contents , DrawFun

NAME

vgl_DrawFunSet - set pointer to drawing function

C SPECIFICATION

void vgl_DrawFunSet (vgl_DrawFun *drawfun,
                     Vint type,
                     void (*function)())

INPUT ARGUMENTS

drawfun      Pointer to DrawFun object.
type         Function type being set
             =DRAWFUN_COLORINDEX     Set ColorIndex function
             =DRAWFUN_COLOR          Set Color function
             =DRAWFUN_LINESTYLE      Set LineStyle function
             =DRAWFUN_LINEWIDTH      Set LineWidth function
             =DRAWFUN_POINTSIZE      Set PointSize function
             =DRAWFUN_TRANS          Set Trans function
             =DRAWFUN_TRANSINDEX     Set TransIndex function
             =DRAWFUN_POLYPOINT      Set PolyPoint function
             =DRAWFUN_POLYPOINTCOLOR Set PolyPointColor function
             =DRAWFUN_POLYPOINTDC    Set PolyPointDC function
             =DRAWFUN_POLYPOINTDATA  Set PolyPointData function
             =DRAWFUN_POLYLINE       Set PolyLine function
             =DRAWFUN_POLYLINECOLOR  Set PolyLineColor function
             =DRAWFUN_POLYLINEDC     Set PolyLineDC function
             =DRAWFUN_POLYLINEDATA   Set PolyLineData function
             =DRAWFUN_POLYGON        Set Polygon function
             =DRAWFUN_POLYGONCOLOR   Set PolygonColor function
             =DRAWFUN_POLYGONDC      Set PolygonDC function
             =DRAWFUN_POLYGONDATA    Set PolygonData function
             =DRAWFUN_TEXT           Set PolygonText function
             =DRAWFUN_TEXTDC         Set PolygonTextDC function
             =DRAWFUN_DATAINDEX      Set DataIndex function
             =DRAWFUN_DATA           Set Data function
function     Pointer to drawing function

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper type is input.

DESCRIPTION

Set pointers to drawing functions. Note that the function pointer argument should be cast to match the documented prototype above, for example:

     vgl_DrawFunSet (drawfun,DRAWFUN_POLYGON,(void(*)())My_Polygon);

Get function as an output argument using

     void vgl_DrawFunGet (vgl_DrawFun *drawfun,
                          Vint type,
                          void (**function)())

Table of Contents , DrawFun

NAME

vgl_DrawFunSetObj - set pointer to auxiliary object

C SPECIFICATION

void vgl_DrawFunSetObj (vgl_DrawFun *drawfun,
                        Vobject *obj)

INPUT ARGUMENTS

drawfun      Pointer to DrawFun object.
obj          Pointer to auxiliary object

OUTPUT ARGUMENTS

None

DESCRIPTION

Set pointer to drawing function auxiliary object.

Get obj as an output argument using

     void vgl_DrawFunGetObj (vgl_DrawFun *drawfun,
                             Vobject **obj)

Table of Contents , DrawFun

NAME

vgl_DrawFunAPI - get built-in drawing functions

C SPECIFICATION

void vgl_DrawFunAPI (vgl_DrawFun *drawfun,
                     Vint api)

INPUT ARGUMENTS

drawfun      Pointer to DrawFun object.
api          Type of built-in drawing function to return.
             =DRAWFUN_APIPRINT       Set printing drawing functions
             =DRAWFUN_APIRETURN      Set return drawing functions

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper api is input.

DESCRIPTION

Set built-in drawing functions. The DRAWFUN_APIPRINT drawing functions print each graphics primitive to standard output. The DRAWFUN_APIRETURN drawing functions simply return.

Table of Contents

14.3 Summary of Drawing Functions

The interface routines to the graphics subsystem which must be supplied consist of graphics primitives, graphics data primitives and their attributes. All coordinates x, are assumed to be 3D vectors or arrays of 3D vectors. Colors c, are a floating point RGB triple (or arrays of RGB triples) with the RGB components in the interval [0.,1.]. Normal vectors and texture coordinates are packed into the vector v. Normal vectors are assumed to be 3D vectors (or arrays of 3D vectors) normalized to unity. Texture coordinates are assumed to be in the interval [0.,1.]. All normal vectors for the primitive appear first followed by all the texture coordinates for the primitive.

Offset vectors dc are assumed to be integer 3D vectors (or arrays of 3D vectors) in device coordinates, ie pixels. Currently, only the x and y components of an offset vector are used, the z component is ignored. Data arrays d which appear in graphics data primitives, are floating point arrays of row dimension nrws. The generic object pointer variable obj is available to hang any user defined data.

Point, line and polygon primitives are drawn using "poly" type functions. They are designed so that multiple points or a connected set of line segments may be drawn. Current polylinetype options are VGL_LINESTRIP, VGL_LINELOOP and VGL_LINES. VGL_LINESTRIP draws a connected set of straight line segments. VGL_LINELOOP indicates that the last point is to be connected to the first point with a straight line segment. VGL_LINES, indicates that a set of independent lines is to be drawn. Current polygontype options include VGL_POLYGON, which specifies a single polygon to be drawn, VGL_TRISTRIP, which specifies a triangle strip is to be drawn, VGL_TRIANGLES, which specifies that a set of independent triangles is to be drawn, VGL_QUADS, which specifies that a set of independent quadrilaterals is to be drawn and VGL_POLYHEDRON, which specifies a single polyhedron to be drawn. A polyhedron must contain either 4,5,6 or 8 points corresponding to a tetrahedron, pyramid, pentahedron or hexahedron respectively. The point connectivity of polyhedra follow the VisTools convention for linear Serendipity elements.

vgl_DrawFunColorIndex (Vobject *obj,
                       Vint index)

Set the current color in pseudocolor mode to index.

vgl_DrawFunColor (Vobject *obj,
                  Vfloat c[3])

Set the current color in truecolor mode to c.

vgl_DrawFunLineStyle (Vobject *obj,
                      Vint style)

Set the current line style to one of four predefined line styles. A style of 0 implies a solid line style; 1 a dashed line style; 2 a dotted line style; and 3 a dot-dash line style. All subsequent lines are to be draw with this line style.

vgl_DrawFunLineWidth (Vobject *obj,
                      Vint width)

Set the current line width to be an integer multiple width of a single pixel wide line. All subsequent lines are to be draw with this line width.

vgl_DrawFunPointSize (Vobject *obj,
                      Vint size)

Set the current point size to be an integer multiple size of a single pixel point. All subsequent points are to be draw with this point size.

vgl_DrawFunTransIndex (Vobject *obj,
                       Vint index)

Set the current transparency where index is an integer specifying a level of transparency. Usually index points to a pattern or stipple used to implement "screen door" transparency.

vgl_DrawFunTrans (Vobject *obj,
                  Vfloat transparency)

Set the current transparency where transparency is a floating point value in the interval [0.,1.]. A value of unity being completely transparent.

vgl_DrawFunPolyPoint (Vobject *obj,
                      Vint npts,
                      Vfloat x[][3])

Draw npts points at x in the current color.

vgl_DrawFunPolyPointColor (Vobject *obj,
                           Vint npts,
                           Vfloat x[][3], Vfloat c[][3])

Draw npts points at x with color c.

vgl_DrawFunPolyPointDC (Vobject *obj,
                        Vint npts,
                        Vfloat x[][3],
                        Vint dc[][3])

Draw npts points anchored at x and offset by dc in device coordinates in the current color.

vgl_DrawFunPolyPointData (Vobject *obj,
                          Vint npts,
                          Vfloat x[][3],
                          Vint nrws, Vfloat d[])

Draw npts points at x with data array d of row dimension nrws.

vgl_DrawFunPolyLine (Vobject *obj,
                     Vint polylinetype,
                     Vint npts,
                     Vfloat x[][3])

Draw connected straight line segments passing through npts points at x in the current color.

vgl_DrawFunPolyLineColor (Vobject *obj,
                          Vint polylinetype;
                          Vint npts;
                          Vfloat x[][3], Vfloat c[][3])

Draw connected straight line segments passing through npts points at x with colors c. The colors are to be linearly interpolated along the length of each line segment.

vgl_DrawFunPolyLineDC (Vobject *obj,
                       Vint polylinetype,
                       Vint npts,
                       Vfloat x[][3], Vint dc[][3])

Draw connected straight line segments passing through npts points anchored at x and offset by dc in device coordinates in the current color.

vgl_DrawFunPolyLineData (Vobject *obj,
                         Vint polylinetype,
                         Vint npts,
                         Vfloat x[][3],
                         Vint nrws, Vfloat d[])

Draw connected straight line segments passing through npts points at x with data array d of row dimension nrws.

vgl_DrawFunPolygon (Vobject *obj,
                    Vint polygontype,
                    Vint npts,
                    Vfloat x[][3],
                    Vint vflag, Vfloat v[])

Draw a filled polygon defined by npts points at x in the current color and transparency. Facet or vertex normals and texture coordinates v for light source shading and texture mapping may be optionally specified using the flag vflag.

vgl_DrawFunPolygonColor (Vobject *obj,
                         Vint polygontype,
                         Vint npts,
                         Vfloat x[][3], Vfloat c[][3],
                         Vint vflag, Vfloat v[])

Draw a filled polygon defined by npts points at x with colors c in the current transparency. The colors are assumed to be linearly interpolated over the polygon. Facet or vertex normals and texture coordinates v for light source shading and texture mapping may be optionally specified using the flag vflag.

vgl_DrawFunPolygonDC (Vobject *obj,
                      Vint polygontype,
                      Vint npts,
                      Vfloat x[][3], Vint dc[][3])

Draw a filled polygon defined by npts points anchored at x and offset by dc in device coordinates in the current color and transparency.

vgl_DrawFunPolygonData (Vobject *obj,
                        Vint polygontype,
                        Vint npts,
                        Vfloat x[][3],
                        Vint nrws, Vfloat d[],
                        Vint vflag, Vfloat v[])

Draw a filled polygon defined by npts points at x with data array d of row dimension nrws. Facet or vertex normals and texture coordinates v for light source shading and texture mapping may be optionally specified using the flag vflag.

vgl_DrawFunText (Vobject *obj,
                 Vfloat x[3],
                 Vchar *string)

Draw annotation text string anchored at x in the current color.

vgl_DrawFunTextDC (Vobject *obj,
                   Vfloat x[3],
                   Vint dc[3],
                   Vchar *string)

Draw annotation text string anchored at x and offset by dc in device coordinates in the current color.

vgl_DrawFunDataIndex (Vobject *obj,
                      Vint index)

Set the current data index to index.

vgl_DrawFunData (Vobject *obj,
                 Vint nrws, Vfloat d[])

Set the current data vector to d with row dimension nrws.

Table of Contents

14.4 Draw Function API - OpenGL

The following section illustrates a possible implementation of a subset of the drawing functions using OpenGL from Silicon Graphics. The argument glwin is assumed to be a pointer to a user object.

vgl_DrawFunOpenGLColor(GLWin *glwin,
                       Vfloat c[3])
{
   glColor3fv (c);
}

vgl_DrawFunOpenGLLineWidth(GLWin *glwin,
                           Vint lwidth)
{
   glLineWidth ((GLfloat)lwidth);
}

vgl_DrawFunOpenGLPointSize(GLWin *glwin,
                           Vint psize)
{
   glPointSize ((GLfloat)psize);
}

vgl_DrawFunOpenGLPolyPoint(GLWin *glwin,
                           Vint npts,
                           Vfloat x[][3])
{
   int i;

   glBegin (GL_POINTS);
   for(i = 0; i < npts; i++) {
      glVertex3fv (x[i]);
   }
   glEnd ();
}

vgl_DrawFunOpenGLPolyPointColor(GLWin *glwin,
                                Vint npts,
                                Vfloat x[][3], Vfloat c[][3])
{
   int i;

   glBegin (GL_POINTS);
   for(i = 0; i < npts; i++) {
      glColor3fv  (c[i]); 
      glVertex3fv (x[i]);
   }
   glEnd ();
}

vgl_DrawFunOpenGLPolyLine(GLWin *glwin,
                          Vint polylinetype,
                          Vint npts,
                          Vfloat x[][3])
{
   int i;
   if(polylinetype == VGL_LINELOOP) {
      glBegin (GL_LINE_LOOP);
      for(i = 0; i < npts; i++) {
         glVertex3fv (x[i]);
      }
      glEnd ();
   } else if(polylinetype == VGL_LINESTRIP) {
      glBegin (GL_LINE_STRIP);
      for(i = 0; i < npts; i++) {
         glVertex3fv (x[i]);
      }
      glEnd ();
   } else if(polylinetype == VGL_LINES) {
      glBegin (GL_LINES);
      for(i = 0; i < npts; i++) {
         glVertex3fv (x[i]);
      }
      glEnd ();
   }
}

vgl_DrawFunOpenGLPolygon(GLWin *glwin,
                         Vint polygontype,
                         Vint npts,
                         Vfloat x[][3],
                         Vint vflag, Vfloat v[])
{
   int i, k;
   float (*vn)[3];

   vn = (float(*)[3])v;

                   /* no texture coordinates assumed */
   if(polygontype == VGL_POLYGON) {
      glBegin (GL_POLYGON);
      if(vf == VGL_FLATSHADE)  glNormal3fv (vn[0]);
      for(i = 0; i < npts; i++) {
         if(vf == VGL_VERTEXSHADE)  glNormal3fv (vn[i]);
         glVertex3fv (x[i]);
      }
      glEnd ();
   } else if(polygontype == VGL_TRIANGLES) {
      glBegin (GL_TRIANGLES);
      for(i = 0; i < npts; i++) {
         if(vf == VGL_FLATSHADE && i%3 == 0)  glNormal3fv (vn[i/3]);
         if(vf == VGL_VERTEXSHADE)  glNormal3fv (vn[i]);
         glVertex3fv (x[i]);
      }
      glEnd ();
   } else if(polygontype == VGL_QUADS) {
      glBegin (GL_QUADS);
      for(i = 0; i < npts; i++) {
         if(vf == VGL_FLATSHADE && i%4 == 0)  glNormal3fv (vn[i/4]);
         if(vf == VGL_VERTEXSHADE)  glNormal3fv (vn[i]);
         glVertex3fv (x[i]);
      }
      glEnd ();
   } else if(polygontype == VGL_TRISTRIP) {
      glBegin (GL_TRIANGLE_STRIP);
      for(i = 0; i < npts; i++) {
         if(vf == VGL_VERTEXSHADE)  glNormal3fv (vn[i]);
         glVertex3fv (x[i]);
      }
      glEnd ();
   } else if(polygontype == VGL_TRIFAN) {
      glBegin (GL_TRIANGLE_FAN);
      for(i = 0; i < npts; i++) {
         if(vf == VGL_VERTEXSHADE)  glNormal3fv (vn[i]);
         glVertex3fv (x[i]);
      }
      glEnd ();
   } else if(polygontype == VGL_POLYHEDRON) {
   }
}

14. Drawing Functions - DrawFun

14.1 Drawing Function Summary

14.2 Function Descriptions

NAME

C SPECIFICATION

ARGUMENTS

FUNCTION RETURN VALUE

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

ERRORS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

ERRORS

DESCRIPTION

14.3 Summary of Drawing Functions

14.4 Draw Function API - OpenGL

14. Drawing Functions - `DrawFun`