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.
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 objectvgl_DrawFunEnd()- destroy an instance of a DrawFun objectvgl_DrawFunError()- return DrawFun object error flagvgl_DrawFunCopy()- make a copy of a DrawFun object
- Set function pointers
vgl_DrawFunSet()- set function pointersvgl_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().
14.2. Function Descriptions
The currently available DrawFun functions are described in detail in this section.
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.
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) {
}
}
