7. Display List, File and Tee, - DList,DFile,DTee

VglTools Programmer Manual

The display list, file and tee modules act as drawing function filters. They accept drawing functions as input, perform some action and then pass along drawing functions as output. The DList module is meant to implement a "retained mode" or display list interface to the graphics subsystem. A DList object caches all graphics primitives in a memory resident display list. It can then be asked to traverse the display list, generating drawing functions as output. The DFile module acts in a manner similar to a display list except that graphics primitives are written to a file. The DFile object can then be asked to read the file, generating drawing functions as output. The DTee module acts as a drawing function splitter. It accepts drawing functions as input and will call two drawing function, DrawFun, objects as output. In this way graphics primitives may be directed simultaneously to two different outputs such as to a display list and to a graphics device.

7.1 Display List - DList

Use a DList object to group, retain and traverse a sequence of graphics primitives. The display list has been designed for traversal speed, there are no general provisions for editing or looping. A display list may be hierarchical in that a display list may call other display lists. A general capability is also included to call user functions (ie. "callbacks") with a user object as an argument.

There are a number of useful traversal methods in addition to complete traversal and rendering. Graphics primitive counts may be retrieved from a display list. Graphics primitives may be conditionally rendered or rendered in reduced modes. For example any graphics primitive may be rendered as point primitives at its vertices. The user may specify the visibility of a display list and apply a transformation to a display list. The transformation is pushed/popped immediately before/after the display list is traversed. The user may also specify that certain graphics primitive attributes be overridden with constant values. For example, a constant line width may be specified for an entire display list, in which case all other line width graphics primitives present in the display list are ignored. Color, transparency, specularity, line width, line style and point size are subject to these overrides. The attribute stack is pushed/popped immediately before/after the display list is traversed if any attribute overrides are in effect.

Instance a DList object using vgl_DListBegin. Once a DList object is instanced, set the drawing function attribute object using vgl_DListSetObject. The drawing function attribute object is invoked whenever the display list is traversed using vgl_DListCall. Register the drawing functions in a DrawFun object for incoming graphics primitives using vgl_DListDrawFun.

7.2 Display List Sorting

The DList module supports back to front sorting of graphics primitives. This is useful for drawing primitives which include transparency and are being rendered using alpha blending. First, all graphics primitives and attributes must be entered into the display list. Note that only graphics primtives and graphics primitive attributes should be entered in a display list which is to be sorted and it is important to include initial values of all primitive attributes which appear in the display list. Second, the function vgl_DListSort must be called to generate data structures to be used during execution of vgl_DListCall to sort the graphics primtives. Finally, use vgl_DListSetParami with parameter DLIST_SORT_BACKTOFRONT to enable/disable back to front sorting during vgl_DListCall.

7.3 Display List Culling

The DList module support four types of elementary culling: 1) viewport culling, 2) detail culling, 3) mouse movement culling and 4) time culling. Each of these culling techniques can be used separately or in any combination to reduce the rendering burden to the underlying graphics hardware or to otherwise control frame rate. Viewport and detail culling increase frame rate by avoiding drawing graphics primitives which are either invisible or insignificantly small. These culling techniques generally retain image quality without guaranteeing a given frame rate. Mouse movement and time culling on the other hand guarantee interactivity at the expense of image quality. The display list traversal is simply terminated due to a given time budget being exceeded or a mouse movement exceeding a given screen distance. All parameters and flags which control culling are set using the functions vgl_DListSetParami, vgl_DListSetParamf and vgl_DListSetParamfv. Note that only graphics primtives and graphics primitive attributes should be entered in a display list which is to be culled.

The current culling options are described in detail below:

  • Viewport culling is a technique in which graphics primitives are eliminated which are outside of the viewing frustum or viewport. This type of culling requires a spatialization of the graphics primitives in the display list. In the DList module a hierarchal octree approach is used. A bounding box is maintained for each node in the hierarchy and entire nodes of graphics primitives are checked for viewport culling very efficiently. The spatialization of the display list and subsequent viewport culling during display list traversal are enabled using vgl_DListSetParami with the parameter types DLIST_VIEWPORT_CULL and DLIST_SPATIALIZE. The bounding box of the root display list must be set by calling vgl_DListSetParamfv with the parameter DLIST_BOUNDBOX.
  • Detail culling is a technique in which the contents of a display list are rendered only if the bounding box of the graphics primitives contained in the display list projects to a device coordinate size which lies within a user defined range. This culling technique is well suited to the straight forward implementation of level of detail switching. Detail culling is enabled by calling vgl_DListSetParami with the parameter type DLIST_DETAIL_CULL. The minimum and maximum limits of the device coordinate range are set using vgl_DListSetParami with the parameter types DLIST_DETAIL_MINSIZE and DLIST_DETAIL_MAXSIZE. If a particular size is set to zero then the device coordinate range is open at that end.
  • Mouse movement culling terminates display list traversal if the change in the device coordinate location of the mouse exceeds a user defined value. The mouse location is polled at the beginning of display list traversal and is subseqently polled periodically during display list traversal to determine mouse movement. This culling technique adjusts frame rate to ensure interactivity by truncating the graphics primitives to be displayed. Mouse movement culling is enabled by calling vgl_DListSetParami with the parameter type DLIST_MOVE_CULL. The maximum mouse movement allowed before the display list traversal is terminated is set using vgl_DListSetParamf with the parameter type DLIST_MOVE_DELTA.
  • Time culling terminates display list traversal if a user defined time "budget" has been exceeded during display list traversal. This culling technique, like mouse movement culling, ensures frame rate by truncating the geometry to be displayed. Time culling is enabled by calling vgl_DListSetParami with the parameter type DLIST_TIME_CULL. The time budget in seconds allowed before the display list traversal is terminated is set using vgl_DListSetParamf with the parameter type DLIST_TIME_BUDGET.

7.4 Attribute Objects

A DList object requires a conventional DrawFun object to render its contents to a graphics device. Use vgl_DListSetObject to set a DrawFun object as an attribute. A display list object only caches graphics attribute, graphics primitive and modelling and viewing transformation drawing functions. (see Chapter 7 Drawing Functions). All other drawing functions input to a DList object are passed transparently though the DrawFun object set as an attribute.

7.5 Function Descriptions

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

DList

NAME

*vgl_DListBegin - create an instance of a DList object

C SPECIFICATION

    vgl_DList *vgl_DListBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

ERRORS

VGL_ERROR_MEMORY is generated if the initial display list memory block allocation fails.

DESCRIPTION

Create an instance of a DList object. Memory is allocated for the object private data and the pointer to the data is returned. All rendering modes are zero. The visibility flag is on.

Destroy an instance of a DList object using 

         void vgl_DListEnd (vgl_DList *dlist)

Return the current value of a DList object error flag using 

         Vint vgl_DListError (vgl_DList *dlist)
Make a copy of a DList object. The private data from the fromdlist object is copied to the dlist object. Any previous private data in dlist is lost. 
         void vgl_DListCopy (vgl_DList *dlist,
                             vgl_DList *fromdlist)

DList

NAME

vgl_DListAbort - set abort flag

C SPECIFICATION

    void vgl_DListAbort (vgl_DList *dlist)

INPUT ARGUMENTS

    dlist        Pointer to DList object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set display list traversal abort flag. While a display list is traversed using vgl_DListCall, the abort flag is continually checked. If it is on, the flag is set off and display list traversal is terminated. The abort flag is usually set in the user defined callback function defined by vgl_DListSetFunction.

DList

NAME

vgl_DListDrawFun - return pointers to drawing functions

C SPECIFICATION

    void vgl_DListDrawFun (vgl_DList *dlist,
                           vgl_DrawFun *drawfun)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    drawfun      Pointer to DrawFun object to be filled with display list
                 drawing functions.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Fill a DrawFun object with display list drawing functions. Use the DrawFun object as an attribute object for any visualization objects which are to draw to a display list.

DList

NAME

vgl_DListSetFunction - set user callback function

C SPECIFICATION

    void vgl_DListSetFunction (vgl_DList *dlist,
                               Vint frequency,
                               void (*function)(vgl_DList*, Vobject*),
                               Vobject *object)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    frequency    Frequency with which the function is called.
    function     Pointer to callback function
    object       Pointer to the object to be returned as function argument

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set a callback function attribute and associated call frequency. The callback function is called periodically while the display list is traversed using vgl_DListCall. Specifically, the callback is invoked after a specified number, frequency, of graphics primitives have been traversed since the last time the callback was invoked or since the start of display list traversal. Examples of the uses of this callback are to check for an event which would modify the display list traversal or to report display list traversal progress. The callback function is called with two arguments, the first is the display list object, dlist, and the second is the user defined object, object.

DList

NAME

vgl_DListSetObject - set attribute object

C SPECIFICATION

    void vgl_DListSetObject (vgl_DList *dlist,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    objecttype   The name of the object type to be set.
                 =VGL_DRAWFUN            DrawFun object
    object       Pointer to the object to be set.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. The DrawFun attribute object is required for traversing the display list with vgl_DListCall or allowing non display listable drawing functions to pass through.

Get object as an output argument using 

         void vgl_DListGetObject (vgl_DList *dlist,
                                  Vint objecttype,
                                  Vobject **object)

DList

NAME

vgl_DListSetRendering - set overall rendering modes

C SPECIFICATION

    void vgl_DListSetRendering (vgl_DList *dlist,
                                Vint pointrend,
                                Vint linerend,
                                Vint polyrend)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    pointrend    Rendering mode for point primitives
    linerend     Rendering mode for line primitives
    polyrend     Rendering mode for polygon primitives

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set the rendering modes for point, line and polygon primitives. A rendering mode is an integer indicating the number of "dimensions" to reduce the rendering of given type of graphics primitive. For example, if polyrend = 1, then all polygon rendering is reduced by one dimension and polygons are rendered by drawing lines connecting their vertices. If polyrend = 2, then all polygons are rendered by drawing their vertices (as points) only. If polyrend = 3, then polygons are not rendered. Point primitives include all text primitives.

DList

NAME

vgl_DListSetParami - set integer parameters

C SPECIFICATION

    void vgl_DListSetParami (vgl_DList *dlist,
                             Vint type,
                             Vint param)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    type         Integer parameter type to set.
                 =DLIST_BALANCE_ATTSTACK    Balance AttPush/AttPop flag
                 =DLIST_BALANCE_PROJSTACK   Balance ProjPush/ProjPop flag
                 =DLIST_BALANCE_XFMSTACK    Balance XfmPush/XfmPop flag
                 =DLIST_BALANCE_MODE        Balance specified mode
                 =DLIST_DETAIL_CULL         Detail cull flag
                 =DLIST_DETAIL_MAXSIZE      Maximum size for detail culling.
                 =DLIST_DETAIL_MINSIZE      Minimum size for detail culling.
                 =DLIST_INIT_BLOCKSIZE      Initial block size in bytes
                 =DLIST_GROW_BLOCKSIZE      Block size growth rate
                 =DLIST_MAXPRIMITIVE        Maximum number of primitives
                                            per spatialization node.
                 =DLIST_MOVE_CULL           Mouse movement cull flag
                 =DLIST_MOVE_DELTA          Mouse movement value
                 =DLIST_MOVE_FREQ           Mouse movement sample frequency
                 =DLIST_PACK                Pack color and normal flag.
                 =DLIST_SORT_BACKTOFRONT    Back to front sorting flag
                 =DLIST_SPATIALIZE          Spatialization flag
                 =DLIST_TIME_CULL           Time cull flag
                 =DLIST_TIME_FREQ           Time cull sample frequency
                 =DLIST_USEBUFFERS          Convert Array to Buffer primitives
                 =DLIST_INIT_BUFFERSIZE     Initial vertex buffer size in bytes
                 =DLIST_VIEWPORT_CULL       Viewport cull flag
    param        Specifies the integer value that type will be set to.
                 =VGL_ON                    Enable
                 =VGL_OFF                   Disable

OUTPUT ARGUMENTS

    none

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified. VIS_ERROR_VALUE is generated if an improper param is specified.

DESCRIPTION

Set display list traversal parameters.

Enable and disable attribute, projection matrix and modelview matrix stack balancing using DLIST_BALANCE_ATTSTACK, DLIST_BALANCE_PROJSTACK and DLIST_BALANCE_XFMSTACK respectively. If enabled, a count is kept of the number of stack push and pop operations. At display list traversal termination, any push operations which have not been matched by an associated pop operation are explicitly balanced by calling the appropriate number of stack pop operations. By default DLIST_BALANCE_ATTSTACK, DLIST_BALANCE_PROJSTACK and DLIST_BALANCE_XFMSTACK are disabled.

Any mode may be saved and restored using DLIST_BALANCE_MODE. The mode to be restored is given by param. A param value of 0 clears the set of modes to be restored. By default no modes are restored.

Enable and disable detail culling using DLIST_DETAIL_CULL. Specify detail culling parameters using DLIST_DETAIL_MINSIZE and DLIST_DETAIL_MAXSIZE. The minimum and maximum sizes define an interval in device coordinates. If the diagonal of the bounding box associated with the display list projects to a device coordinate extent which lies outside the specified interval then the display list is not traversed. If one of the sizes is set to 0 the associated end of the interval is open. Use vgl_DListSetParamfv to specify the bounding box. By default DLIST_DETAIL_MINSIZE is 50 and DLIST_DETAIL_MAXSIZE is 0., DLIST_DETAIL_CULL is disabled.

Set the initial block size in bytes using DLIST_INIT_BLOCKSIZE. The DList module allocates memory in a series of blocks as needed. The size of the first block may be specified using this parameter. This is useful to conserve memory if the user knows that the DList object is going to contain a fixed, small number of graphics primitives. The size of a graphics primitive is the number of bytes in the argument list of the corresponding drawing function plus 12 bytes. There is an additional 12 byte overhead in each block. The size of each allocated block after the initial block is expanded by a user definable growth rate set using DLIST_GROW_BLOCKSIZE. Block size grows until it reaches a maximum which is internally determined by DList. By default DLIST_INIT_BLOCKSIZE is 1024 and DLIST_GROW_BLOCKSIZE is 4.

Enable and disable color and normal packing using DLIST_PACK. If enabled, all color and normal attributes are packed into a single integer each. This can reduce the memory required to store these attributes by a factor of 3. By default DLIST_PACK is disabled.

Enable and disable conversion of "Array" primitives to equivalent "Buffer" primitives using DLIST_USEBUFFERS. Buffer primitives implemented with vgl_OpenGLDev will use Vertex Buffer Objects. By default DLIST_USEBUFFERS is disabled.

Vertex Buffer objects are allocated progressively larger from an initial value in bytes. Set the initial value using DLIST_INIT_BUFFERSIZE. By default DLIST_INIT_BUFFERSIZE is 4096 bytes.

Enable and disable viewport culling using DLIST_VIEWPORT_CULL. To perform viewport culling the display list must be spatialized while graphics primitives are initially inserted into it. Use DLIST_SPATIALIZE to enable spatialization. The number of graphics primitives to place in any one particular node in the spatialization hierarchy is specified using DLIST_MAXPRIMITIVE. This value should be be no more than 5 percent of the total number of geometric graphics primitives for viewport culling to be effective. By default DLIST_SPATIALIZE is disabled and DLIST_MAXPRIMITIVE is 1024, DLIST_VIEWPORT_CULL is disabled.

Enable and disable back to front sorting using DLIST_SORT_BACKTOFRONT. The back to front sorting data structures must have been previously generated using vgl_DListSort. Note that when using back to front sorting it is important to include initial values of all primitive attributes which appear in the display list. By default DLIST_SORT_BACKTOFRONT is disabled.

Enable and disable mouse movement culling using DLIST_MOVE_CULL. Specify maximum mouse movement using DLIST_MOVE_DELTA. Specify the frequency which mouse movement is sampled using DLIST_MOVE_FREQ. Frequency is defined as number of graphics primitives. By default DLIST_MOVE_DELTA is 10 and DLIST_MOVE_FREQ is 1000, DLIST_MOVE_CULL is disabled.

Enable and disable time culling using DLIST_TIME_CULL. Specify the frequency which time is sampled using DLIST_TIME_FREQ. Frequency is defined as number of graphics primitives. Use vgl_DListSetParamf to specify the time budget in seconds. By default DLIST_TIME_FREQ is 1000, DLIST_TIME_CULL is disabled.

DList

NAME

vgl_DListSetParamf - set real parameters

C SPECIFICATION

    void vgl_DListSetParamf (vgl_DList *dlist,
                             Vint type,
                             Vfloat param)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    type         Float parameter type to set.
                 =DLIST_TIME_BUDGET         Time budget in seconds
    param        Specifies the float value that type will be set to.

OUTPUT ARGUMENTS

    none

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified. VIS_ERROR_VALUE is generated if an improper param is specified.

DESCRIPTION

Set display list traversal parameters. Specify the total time allowed for display list traversal. This value is used in conjunction with time culling. DLIST_TIME_BUDGET. By default DLIST_TIME_BUDGET is .1 seconds.

DList

NAME

vgl_DListSetParamfv - set real parameters

C SPECIFICATION

    void vgl_DListSetParamfv (vgl_DList *dlist,
                              Vint type,
                              Vfloat param[])

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    type         Float parameter type to set.
                 =DLIST_BOUNDBOX            Bounding box
    param        Specifies the float values that type will be set to.

OUTPUT ARGUMENTS

    none

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified. VIS_ERROR_VALUE is generated if an improper param is specified.

DESCRIPTION

Set display list traversal parameters. Specify the bounding box characterizing the geometric graphics primitives in the display list. The bounding box is input as six world coordinate values, the minimum x,y,z coordinates followed by the maximum x,y,z coordinates. The bounding box is used in conjunction with spatialization and viewport and detail culling. By default DLIST_BOUNDBOX is 0.,0.,0.,1.,1.,1.

DList

NAME

vgl_DListSetXfm - set transformation

C SPECIFICATION

    void vgl_DListSetXfm (vgl_DList *dlist,
                          Vfloat tm4[4][4])

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    tm4[4][4]    Transformation matrix

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set a transformation matrix to be applied to all graphics primitives in the display list. The transformation stack is pushed and the specified transformation matrix is preconcatenated to the top matrix just before the display list is traversed. The transformation stack is popped just after the display list is traversed. This transformation may be separately enabled/disabled using vgl_DListSetXfmFlag.

DList

NAME

vgl_DListSetXfmFlag - toggle transformation matrix

C SPECIFICATION

    void vgl_DListSetXfmFlag (vgl_DList *dlist,
                              Vint flag)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    flag         Enable/disable application of Xfm
                 =VGL_OFF      Turn Xfm off
                 =VGL_ON       Turn Xfm on

OUTPUT ARGUMENTS

    None

DESCRIPTION

Toggle the application of the transformation specified by vgl_DListSetXfm. This flag is activated internally when vgl_DListSetXfm is called.

Get activation flag as an output argument using 

         void vgl_DListGetXfmFlag (vgl_DList *dlist,
                                      Vint *flag)

DList

NAME

vgl_DListSetVisibility - set visibility

C SPECIFICATION

    void vgl_DListSetVisibility (vgl_DList *dlist,
                                 Vint flag)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    flag         Visibility flag
                 =VGL_OFF      Turn visibility off
                 =VGL_ON       Turn visibility on

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set the visibility flag for a display list. By default the visibility flag is on. If a display list visibility flag is off, it is not traversed.

Get visibility flag as an output argument using 

         void vgl_DListGetVisibility (vgl_DList *dlist,
                                      Vint *flag)

DList

NAME

vgl_DListSetColor,vgl_DListSetColorIndex - set color attribute overrides

C SPECIFICATION

    void vgl_DListSetColor (vgl_DList *dlist,
                            Vint flag,
                            Vfloat c[3])
    
    void vgl_DListSetColorIndex (vgl_DList *dlist,
                                 Vint flag,
                                 Vint index)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    flag         Override flag
                 =VGL_OFF      Do not override attribute primitives
                 =VGL_ON       Override attribute primitives
    c            Color RGB components
    index        Color index

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set color attribute override flags on or off and set overriding color attributes for a display list. If the color index attribute is overridden, then the attribute stack is pushed and the specified color index is passed to the graphics subsystem just before the display list is traversed. All color index graphics primitives in the display list are ignored. The color RGB attributes may be overridden independently in the same way. The attribute stack is popped just after the display list is traversed.

Get flag and c as output arguments using 

         void vgl_DListGetColor (vgl_DList *dlist,
                                 Vint *flag,
                                 Vfloat c[3])

Get flag and index as output arguments using 

         void vgl_DListGetColorIndex (vgl_DList *dlist,
                                      Vint *flag,
                                      Vint *index)

DList

NAME

vgl_DListSetLineStyle,vgl_DListSetLineWidth - set line attribute overrides

C SPECIFICATION

    void vgl_DListSetLineStyle (vgl_DList *dlist,
                                Vint flag,
                                Vint linestyle)
    
    void vgl_DListSetLineWidth (vgl_DList *dlist,
                                Vint flag,
                                Vint linewidth)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    flag         Override flag
                 =VGL_OFF      Do not override attribute primitives
                 =VGL_ON       Override attribute primitives
    linestyle    Line style
                 =VGL_LINESTYLE_SOLID      Solid line style
                 =VGL_LINESTYLE_DASHDASH   Dashed line
                 =VGL_LINESTYLE_DOTDOT     Dotted line
                 =VGL_LINESTYLE_DOTDASH    Dot dash line
    linewidth    Line width, 1 <= linewidth

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set line attribute override flags on or off and set overriding line attributes for a display list. If the line style attribute is overridden, then the attribute stack is pushed and the specified line style is passed to the graphics subsystem just before the display list is traversed. All line style graphics primitives in the display list are ignored. The line width attributes may be overridden independently in the same way. The attribute stack is popped just after the display list is traversed.

Get flag and linestyle as output arguments using 

         void vgl_DListGetLineStyle (vgl_DList *dlist,
                                     Vint *flag,
                                     Vint *linestyle)

Get flag and linewidth as output arguments using 

         void vgl_DListGetLineWidth (vgl_DList *dlist,
                                     Vint *flag,
                                     Vint *linewidth)

DList

NAME

vgl_DListSetPointSize - set point size override

C SPECIFICATION

    void vgl_DListSetPointSize (vgl_DList *dlist,
                                Vint flag,
                                Vint pointsize)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    flag         Override flag
                 =VGL_OFF      Do not override attribute primitives
                 =VGL_ON       Override attribute primitives
    pointsize    Point size

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set point attribute override flags on or off and set overriding point attribute for a display list. If the point size attribute is overridden, then the attribute stack is pushed and the specified point size is passed to the graphics subsystem just before the display list is traversed. All point size graphics primitives in the display list are ignored. The attribute stack is popped just after the display list is traversed.

Get flag and pointsize as output arguments using 

         void vgl_DListGetPointSize (vgl_DList *dlist,
                                     Vint *flag,
                                     Vint *pointsize)

DList

NAME

vgl_DListSetPointStyle - set point style override

C SPECIFICATION

    void vgl_DListSetPointStyle (vgl_DList *dlist,
                                 Vint flag,
                                 Vint pointstyle)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    flag         Override flag
                 =VGL_OFF      Do not override attribute primitives
                 =VGL_ON       Override attribute primitives
    pointstyle   Point style

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set point attribute override flags on or off and set overriding point attribute for a display list. If the point style attribute is overridden, then the attribute stack is pushed and the specified point style is passed to the graphics subsystem just before the display list is traversed. All point style graphics primitives in the display list are ignored. The attribute stack is popped just after the display list is traversed.

Get flag and pointstyle as output arguments using 

         void vgl_DListGetPointStyle (vgl_DList *dlist,
                                     Vint *flag,
                                     Vint *pointstyle)

DList

NAME

vgl_DListSetSpecularity - set specularity attributes overrides

C SPECIFICATION

    void vgl_DListSetSpecularity (vgl_DList *dlist,
                                  Vint flag,
                                  Vfloat intensity,
                                  Vfloat shininess)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    flag         Override flag
                 =VGL_OFF      Do not override attribute primitives
                 =VGL_ON       Override attribute primitives
    intensity    Intensity of specular reflectance.
    shininess    Specular exponent

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set specularity attribute override flags on or off and set overriding specularity attributes for a display list. If the specularity attributes are overridden, then the attribute stack is pushed and the specified specularity attributes are passed to the graphics subsystem just before the display list is traversed. All specularity attribute primitives in the display list are ignored. The attribute stack is popped just after the display list is traversed.

Get flag, intensity and shininess as output arguments using 

         void vgl_DListGetSpecularity (vgl_DList *dlist,
                                       Vint *flag,
                                       Vfloat *intensity,
                                       Vfloat *shininess)

DList

NAME

vgl_DListSetTrans,vgl_DListSetTransIndex - set transparency attribute overrides

C SPECIFICATION

    void vgl_DListSetTrans (vgl_DList *dlist,
                            Vint flag,
                            Vfloat trans)
    
    void vgl_DListSetTransIndex (vgl_DList *dlist,
                                 Vint flag,
                                 Vint index)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    flag         Override flag
                 =VGL_OFF      Do not override attribute primitives
                 =VGL_ON       Override attribute primitives
    trans        Transparency factor
    index        Transparency index

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set transparency attribute override flags on or off and set overriding transparency attributes for a display list. If the transparency index attribute is overridden, then the attribute stack is pushed and the specified transparency index is passed to the graphics subsystem just before the display list is traversed. All transparency index graphics primitives in the display list are ignored. The transparency factor attributes may be overridden independently in the same way. The attribute stack is popped just after the display list is traversed.

Get flag and trans as output arguments using 

         void vgl_DListGetTrans (vgl_DList *dlist,
                                 Vint *flag,
                                 Vfloat *trans)

Get flag and index as output arguments using 

         void vgl_DListGetTransIndex (vgl_DList *dlist,
                                      Vint *flag,
                                      Vint *index)

DList

NAME

vgl_DListAddFunction - add a callback function to display list

C SPECIFICATION

    void vgl_DListAddFunction (vgl_DList *dlist,
                               void (*function)(vgl_DList*, Vobject*),
                               Vobject *object)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    function     Pointer function to add to display list
    object       Pointer to the user object to be passed as an argument.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Add a callback function to a display list. A pointer to an object is also specified. When the display list is traversed the callback function is called with two arguments, the display list object from which the callback is called, dlist, and a user defined object, object.

DList

NAME

vgl_DListAddDList - add a display list to be called from a display list

C SPECIFICATION

    void vgl_DListAddDList (vgl_DList *dlist,
                            vgl_DList *adddlist)

INPUT ARGUMENTS

    dlist        Pointer to DList object.
    adddlist     Pointer to DList object which is to be called from
                 dlist.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Add a display list to a display list. The display list adddlist is called when dlist is traversed. Only a pointer to adddlist is placed in the display list. If the contents of adddlist is changed between traversals of dlist then the output of the traversals will reflect the changes in adddlist.

DList

NAME

vgl_DListCall - traverse and render the contents of a display list

C SPECIFICATION

    void vgl_DListCall (vgl_DList *dlist)

INPUT ARGUMENTS

    dlist        Pointer to DList object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION is generated if an uninitialized attribute is encountered during a back to front traversal.

DESCRIPTION

Render the contents of a display list object. The contents are rendered by calling the appropriate drawing function in the DrawFun object which is required to be set as an attribute of the display list object. Any attributes or overrides which have been set are in effect.

DList

NAME

vgl_DListCompact - free unused memory from a display list

C SPECIFICATION

    void vgl_DListCompact (vgl_DList *dlist)

INPUT ARGUMENTS

    dlist        Pointer to DList object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Free unused memory from a display list. Memory is allocated for a display list in blocks. The display list object allocates new blocks as needed as graphics primitives are added to the display list. The block size starts at 1K bytes, or a user defined value using DLIST_INIT_BLOCKSIZE in function vgl_DListSetParami, and progressively increases to an internally determined maximum. If a small number of graphics primitives are placed in a display list and no more primitives are to be added, it is wise to call this function to release unused memory in the last block. Use the function vgl_DListMemory to determine exactly the amount of unused memory. The amount of memory used by any graphics primitive may be estimated accurately by computing the size in bytes of the arguments to the corresponding drawing function.

DList

NAME

vgl_DListErase - erase the contents of a display list

C SPECIFICATION

    void vgl_DListErase (vgl_DList *dlist)

INPUT ARGUMENTS

    dlist        Pointer to DList object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Erase the contents of a display list. All memory associated with the storage of the contents is freed. This is a convenient way to reuse a display list for another display. All attributes and overrides are unchanged.

DList

NAME

vgl_DListMemory - return current memory usage

C SPECIFICATION

    void vgl_DListMemory (vgl_DList *dlist,
                          Vint *numblocks,
                          Vint *usesize,
                          Vint *totsize)

INPUT ARGUMENTS

    dlist        Pointer to DList object.

OUTPUT ARGUMENTS

    numblocks    Total number of allocated blocks
    usesize      Current number of bytes used by data
    totsize      Current number of bytes total allocated capacity

DESCRIPTION

Return memory usage information. The number of bytes used, usesize, will always be less than or equal to the total number of bytes of allocated capacity, totsize. The difference between usesize and totsize is the number of unused bytes. The function vgl_DListCompact is designed to free the unused memory.

DList

NAME

vgl_DListSort - generate back to front sorting information

C SPECIFICATION

    void vgl_DListSort (vgl_DList *dlist)

INPUT ARGUMENTS

    dlist        Pointer to DList object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Generate data structure required to perform back to front sorting. This function only generates the information required to perform back to front sorting. Use vgl_DListSetParami with type DLIST_SORT_BACKTOFRONT to enable back to front sorting.

DList

NAME

vgl_DListStatistics - return primitive statistics

C SPECIFICATION

    void vgl_DListStatistics (vgl_DList *dlist,
                              Vint primnum[DLIST_MAX],
                              Vint primsiz[DLIST_MAX])

INPUT ARGUMENTS

    dlist        Pointer to DList object.

OUTPUT ARGUMENTS

    primnum      Total number of times each drawing function type is called.
    primsiz      Total size of data associated with each drawing function type.

DESCRIPTION

Accumulate and return statistics for a display list object. The display list is traversed and running total of the total number of times each drawing function type is called and the total amount of data associated with each drawing function type is recorded. The total sizes are in units of the size of the Vint datatype. The output arrays must be dimensioned by DLIST_MAX. Callback functions and child display lists are not called or summarized. All display list attributes and overrides are ignored.

DList

NAME

vgl_DListSummary - traverse and summarize the contents of a display list

C SPECIFICATION

    void vgl_DListSummary (vgl_DList *dlist)

INPUT ARGUMENTS

    dlist        Pointer to DList object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Summarize the contents of a display list object. The display list is traversed and a table summarizing its contents is printed. Callback functions and child display lists are not called or summarized. All display list attributes and overrides are ignored.

7.6 Display File - DFile

Use a DFile object to write and, in some cases, read a sequence of graphics primitives to (from) a disk file.

Two VKI proprietary file formats are supported, an ASCII format and a binary format. The STL ASCII file format and OBJ file formats are supported for reading and writing. The VRML Version 2.0 file format is supported for writing only. For the JT file format, the DFile object may be used to read or write the actual JT file or simply fill user defined JtkPart objects.

There are two main operations to be performed on a display file, 1) writing (drawing) and 2) reading. Before either writing to or reading from a display file, a DFile object must be instanced using vgl_DFileBegin. The file type and file name must be set using vgl_DFileSetFileType and vgl_DFileSetFileName. To write to the display file, instance a DrawFun object, register the display file drawing functions using vgl_DFileDrawFun, and open the display file using vgl_DFileOpen. At this point all subsequent drawing function calls will be written to the display file. When drawing is complete, close the display file with vgl_DFileClose.

Object file formats often do not have a notion of absolute pixel coordinates. Certain drawing functions which contains absolute pixel coordinates, such as Viewport, need some idea of the target window size to effect exporting. Use the function vgl_DFileSetWindowSize to set a window size hint to be used in converting absolute pixel coordinates to other object or screen relative coordinate systems.

To read from an existing display file, it may be useful to use vgl_DFileReadFileType to retrieve the display file type if it is unknown prior to setting it using vgl_DFileSetFileType. The drawing function to be used to render the graphics primitives read from the display file must be set as an attribute object using vgl_DFileSetObject. The display file is read by calling vgl_DFileRead. While a display file is being read the optional user function set with vgl_DFileSetFunction is called.

The functions vgl_DFileSetPosition and vgl_DFileCurPosition allow the user to set and query file positions. This enables the user to place several display "frames" in a single display file and to access them randomly. The capability is only supported for the VKI proprietary file formats.

7.7 JT Open

The support of the JT Open file format depends upon external library support. The JT file format is supported by the DFILE_JT and DFILE_JTPART file types and the vgl_DFileSetJTAssemblyName and vgl_DFileOpenJTPart and vgl_DFileCloseJTPart functions. The interface to JT Open is designed to support geometric content only, specifically graphics primitive and graphics attributes. This excludes lighting, transformations, frame buffer control, etc. The support of all possible VglTools graphics primitives and attributes is limited by the support provided by the feature set of JT Open. Currently supported drawing functions include the following. 
    vgl_DrawFunColor
    vgl_DrawFunPolyPoint
    vgl_DrawFunPolyPointColor
    vgl_DrawFunPolyLine
    vgl_DrawFunPolyLineColor
    vgl_DrawFunPolygon
    vgl_DrawFunPolygonColor

The file type DFILE_JTPART restricts the use of DFile to the filling of user defined JT parts using vgl_DFileOpenJTPart and vgl_DFileCloseJTPart. In this case the user is responsible for all JT Open operations up to the creation of JtkPart objects.

The file type DFILE_JT can either read or write a JT Open file and is designed to encapsulate all JT interface requirements. The JT Assembly name is set using vgl_DFileSetJTAssemblyName. The user may create JtkPart objects as an option and insert them using vgl_DFileOpenJTPart and vgl_DFileCloseJTPart. Note that the basic initialization of JT Open JtkEntityFactory::init() and termination of JT Open JtkEntityFactory::fini() are done by DFile.

The symbol VKI_LIBAPI_JT must be defined for the function calls to the underlying JT library to be compiled. For more information on JT Open see the following URL. 

    http://www.jtopen.com

Currently supported drawing functions include the following. 

    vgl_DrawFunAttPop
    vgl_DrawFunAttPush
    vgl_DrawFunColor
    vgl_DrawFunPointSize
    vgl_DrawFunLineWidth
    vgl_DrawFunLineStyle
    vgl_DrawFunPolyPoint
    vgl_DrawFunPolyPointColor
    vgl_DrawFunPolyLine
    vgl_DrawFunPolyLineColor
    vgl_DrawFunPolygon
    vgl_DrawFunPolygonColor
    vgl_DrawFunProjFrustum
    vgl_DrawFunProjOrtho
    vgl_DrawFunProjPop
    vgl_DrawFunProjPush
    vgl_DrawFunRasFontDefine
    vgl_DrawFunRasFontSelect
    vgl_DrawFunText
    vgl_DrawFunTextDC
    vgl_DrawFunViewport

7.8 Attribute Objects

A DFile object requires a conventional DrawFun object to read its contents from a display file. Use vgl_DFileSetObject to set a DrawFun object as an attribute. A display file object only caches graphics attribute, graphics primitive and modelling and viewing transformation drawing functions. (see Chapter 7 Drawing Functions). All other drawing functions input to a DFile object are ignored.

7.9 Function Descriptions

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

DFile

NAME

*vgl_DFileBegin - create an instance of a DFile object

C SPECIFICATION

    vgl_DFile *vgl_DFileBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a DFile object. Memory is allocated for the object private data and the pointer to the data is returned. The file type is set to DFILE_ASCII, the file name is a zero length, NULL terminated string.

Destroy an instance of a DFile object using 

         void vgl_DFileEnd (vgl_DFile *dfile)

Return the current value of a DFile object error flag using 

         Vint vgl_DFileError (vgl_DFile *dfile)

DFile

NAME

vgl_DFileAbort - set abort flag

C SPECIFICATION

    void vgl_DFileAbort (vgl_DFile *dfile)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set display file read abort flag. While a display file is read using vgl_DFileRead, the abort flag is continually checked. If it is on, the flag is set off and display file reading is terminated. The abort flag is usually set in the user defined callback function defined by vgl_DFileSetFunction.

DFile

NAME

vgl_DFileDrawFun - return pointers to drawing functions

C SPECIFICATION

    void vgl_DFileDrawFun (vgl_DFile *dfile,
                           vgl_DrawFun *drawfun)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    drawfun      Pointer to DrawFun object to be filled with display file
                 drawing functions.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Fill a DrawFun object with display file drawing functions.

DFile

NAME

vgl_DFileSetFunction - set user callback function

C SPECIFICATION

    void vgl_DFileSetFunction (vgl_DFile *dfile,
                               Vint frequency,
                               void (*function)(vgl_DFile*, Vobject*),
                               Vobject *object)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    frequency    Frequency with which the function is called.
    function     Pointer to callback function
    object       Pointer to the object to returned as function argument

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set a callback function attribute and associated call frequency. The callback function is called periodically while the display file is read using vgl_DFileRead. Specifically, the callback is invoked after a specified number, frequency, of graphics primitives have been read since the last time the callback was invoked or since the start of display file reading. Examples of the uses of this callback are to check for an event which would modify the display file reading or to report display file reading progress. The callback function is called with two arguments, the first is the display file object, dfile, and the second is the user defined object, object.

DFile

NAME

vgl_DFileSetObject - set pointers to attribute objects

C SPECIFICATION

    void vgl_DFileSetObject (vgl_DFile *dfile,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    objecttype   The name of the object type to be set.
                 =VGL_DRAWFUN            DrawFun object
    object       Pointer to the object to be set.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. The DrawFun attribute object is required for reading a display file with vgl_DFileRead.

DFile

NAME

vgl_DFileSetParami - set integer parameters

C SPECIFICATION

    void vgl_DFileSetParami (vgl_DFile *dfile,
                             Vint type,
                             Vint param)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    type         Integer parameter type to set.
                 =DFILE_UNITPRECISION       Write extended precision
    param        Specifies the integer value that type will be set to.
                 =DFILE_UNITPRECISION_DEFAULT 4 digits
                 =DFILE_UNITPRECISION_SINGLE7 7 digits
                 =DFILE_UNITPRECISION_SINGLE9 9 digits

OUTPUT ARGUMENTS

    none

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Set display file writing parameters. Set number of digits of precision to output unit vectors to VglTools ASCII file, file type DFILE_ASCII, using DFILE_UNITPRECISION. By default DFILE_UNITPRECISION is DFILE_UNITPRECISION_DEFAULT.

DFile

NAME

vgl_DFileSetFileName - set display file name

C SPECIFICATION

    void vgl_DFileSetFileName (vgl_DFile *dfile,
                               Vchar *filename)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    filename     Path name of display file to write to or read from

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION is generated if the display file is open.

DESCRIPTION

Set the current path name of the display file to be used for file operations such as open, close, read and drawing using DFile drawing functions. Initially filename is a zero length, NULL terminated string. A filename must be specified before using vgl_DFileOpen, vgl_DFileClose, vgl_DFileRead, vgl_DFileReadFileType or using any DFile drawing functions. Use vgl_DFileSetFileType to specify the format of the display file. The filename may not be set if a display file is currently open.

For DFILE_JT file formats, the filename must be an existing directory name under which the JT assembly and part file structure is read or written.

DFile

NAME

vgl_DFileSetFileType - set display file type for format

C SPECIFICATION

    void vgl_DFileSetFileType (vgl_DFile *dfile,
                               Vint filetype)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    filetype     Display file type or format
                 =DFILE_ASCII            VglTools ASCII file format
                 =DFILE_BINARY           VglTools binary file format
                 =DFILE_DAE              DAE file format
                 =DFILE_JT               JT Open file format
                 =DFILE_JTPART           JT Open part filling only
                 =DFILE_OBJ              Wavefront OBJ file format
                 =DFILE_STL_ASCII        STL ASCII file format
                 =DFILE_VRML             VRML Version 2.0 file format
                 =DFILE_X3D              X3D file format

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION is generated if the display file is open. VGL_ERROR_ENUM is generated if an improper filetype is specified.

DESCRIPTION

Set the type or format of the display file. Initially filetype is DFILE_ASCII. Use vgl_DFileReadFileType to determine the file type of an existing display file. The filetype may not be set if a display file is currently open. VRML file format is supported for output only.

The type DFILE_JT allows for the reading and writing of JT Open files. The type DFILE_JTPART does not process a JT file explicitly. It allows for the filling of user specified JT parts using vgl_DFileOpenJTPart and vgl_DFileCloseJTPart only.

The type DFILE_OBJ will write an associated material color file (.mtl) in addition to the graphics primitive (.obj) file. Vertex color interpolated primitives will generate an average color material.

DFile

NAME

vgl_DFileSetWindowSize - set window size hint

C SPECIFICATION

    void vgl_DFileSetWindowSize (vgl_DFile *dfile,
                                 Vint xsize,
                                 Vint ysize)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    xsize        Horizontal window pixel size
    ysize        Vertical window pixel size

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set a window size hint. By default the window size hint is xsize = 1024 and ysize = 780.

DFile

NAME

vgl_DFileSetJTAssemblyName - set JT Assembly name

C SPECIFICATION

    void vgl_DFileSetJTAssemblyName (vgl_DFile *dfile,
                                     Vchar *assemblyname)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    assemblyname Name given to JT Assembly

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set the name of the JT assembly. By default, the assembly name is "Assembly".

DFile

NAME

vgl_DFileOpenJTPart - open JtkPart object

C SPECIFICATION

    void vgl_DFileOpenJTPart (vgl_DFile *dfile,
                              Vobject *jtpart)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.
    jtpart       Pointer to JtkPart object

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_NULLOBJECT is generated if file type is DFILE_JTPART.

DESCRIPTION

Open drawing to the current JtkPart* part object. All subsequent graphics primitives will be entered in this object. If using file type DFILE_JTPART, the jtpart must not be NULL. For file type DFILE_JT, if jtpart is NULL, then an internal JtkPart object is used. The first internal part is given the name "Part_1", the second, "Part_2", etc. An open part must be closed using vgl_DFileCloseJTPart.

DFile

NAME

vgl_DFileCloseJTPart - close JtkPart object

C SPECIFICATION

    void vgl_DFileCloseJTPart (vgl_DFile *dfile)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Close drawing to the current JtkPart* part object. A part must have been previously opened using vgl_DFileOpenJTPart.

DFile

NAME

vgl_DFileClose - close a currently open display file

C SPECIFICATION

    void vgl_DFileClose (vgl_DFile *dfile)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION is generated if file is not open.

DESCRIPTION

Close a display file which has been previously opened with vgl_DFileOpen. A display file should be closed after all drawing (writing) to it has been completed.

DFile

NAME

vgl_DFileOpen - open a display file for drawing

C SPECIFICATION

    void vgl_DFileOpen (vgl_DFile *dfile)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION is generated if the display file is already open. VGL_ERROR_FILE is generated if display file can not be opened.

DESCRIPTION

Open a display file prior to drawing. A display file must be opened before using with DFile drawing functions.

DFile

NAME

vgl_DFileRead - read and render the contents of a display file.

C SPECIFICATION

    void vgl_DFileRead (vgl_DFile *dfile)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if the display file does not exist, the file format is unrecognizable or a file format is current for which reading is not supported. VGL_ERROR_OPERATION is generated if display file is already open or if an error occurs during reading.

DESCRIPTION

Read the contents of a display file. The contents are rendered by calling the appropriate drawing unction in the DrawFun object which is required to be set as an attribute of the display file object. Use vgl_DFileSetObject to set the DrawFun attribute object. The display file must not be open for drawing.

By default reading begins at the beginning of the file. Use vgl_DFileSetPosition to set a file position for reading to begin. An input position equal to zero causes reading to start from the beginning of the file. Reading terminates when the token placed on the file by the vgl_DFileClose function is encountered.

To read a display file of unknown type or format, use vgl_DFileReadFileType and set the returned file type using vgl_DFileSetFileType.

DFile

NAME

vgl_DFileReadFileType - read the file type of a display file

C SPECIFICATION

    void vgl_DFileReadFileType (vgl_DFile *dfile,
                                Vint *filetype)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.

OUTPUT ARGUMENTS

    filetype     Display file type or format.  This argument is undefined if
                 an error is registered.

ERRORS

VGL_ERROR_FILE is generated if display file name is NULL or the file does not exist or the file format is unrecognizable. VGL_ERROR_OPERATION is generated if display file is already open or if an error occurs during reading.

DESCRIPTION

Attempt to read the display file and determine its type, filetype. To set the current filetype, use vgl_DFileSetFileType. The display file must not be open for drawing. The file type is always read from the beginning of the file.

DFile

NAME

vgl_DFileCurPosition - query current file position

C SPECIFICATION

    void vgl_DFileCurPosition (vgl_DFile *dfile,
                               long *position)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.

OUTPUT ARGUMENTS

    position     Current file position.

DESCRIPTION

Query the current file position. If this function is called immediately after a call to vgl_DFileClose, the position is normally the position of the end-of-file.

This position may be used as the position argument to the function vgl_DFileSetPosition to set the current file position. This is normally done immediately before a call to vgl_DFileOpen or vgl_DFileRead to write to / read from a specified file position. Multiple display "frames", each delimited by a vgl_DFileOpen and vgl_DFileClose function, may be placed on a single display file.

DFile

NAME

vgl_DFileSetPosition - set current file position

C SPECIFICATION

    void vgl_DFileSetPosition (vgl_DFile *dfile,
                               long position)

INPUT ARGUMENTS

    dfile        Pointer to DFile object.

OUTPUT ARGUMENTS

    position     Set file position.

DESCRIPTION

Set the current file position. Normally, this function is called immediately before a call to vgl_DFileOpen or vgl_DFileRead with a position argument which has been previously queried using vgl_DFileCurPosition.

7.10 Display Tee - DTee

Use a DTee object to split or tee drawing functions. A DTee object accepts drawing functions as input and immediately calls two drawing function objects as output. In this way a stream of graphics primitives may be split. This feature is useful for directing graphics primitives to two outputs such as a graphics device and an output file or display list.

Use vgl_DTeeBegin to instance a DTee object. Establish the input drawing functions in a DrawFun object using vgl_DTeeDrawFun. Use two calls to vgl_DTeeSetObject to set the DrawFun objects used as output.

7.11 Function Descriptions

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

DTee

NAME

*vgl_DTeeBegin - create an instance of a DTee object

C SPECIFICATION

    vgl_DTee *vgl_DTeeBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a DTee object. Memory is allocated for the object private data and the pointer to the data is returned. The output drawing function objects are set to NULL.

Destroy an instance of a DTee object using 

         void vgl_DTeeEnd (vgl_DTee *DTee)

Return the current value of a DTee object error flag using 

         Vint vgl_DTeeError (vgl_DTee *DTee)

DTee

NAME

vgl_DTeeDrawFun - return pointers to drawing functions

C SPECIFICATION

    void vgl_DTeeDrawFun (vgl_DTee *DTee,
                          vgl_DrawFun *drawfun)

INPUT ARGUMENTS

    DTee         Pointer to DTee object.
    drawfun      Pointer to DrawFun object to be filled with display file
                 drawing functions.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Fill a DrawFun object with display file drawing functions.

DTee

NAME

vgl_DTeeSetObject - set pointers to output drawing function objects

C SPECIFICATION

    void vgl_DTeeSetObject (vgl_DTee *DTee,
                            Vint objecttype,
                            Vobject *object)

INPUT ARGUMENTS

    DTee         Pointer to DTee object.
    objecttype   The name of the object type to be set.
                 =VGL_DRAWFUN            DrawFun object
                 =VGL_DRAWFUN_TEE        DrawFun object
    object       Pointer to the object to be set.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an output drawing function object. This function must be called twice, once with objecttype set to VGL_DRAWFUN and again with objecttype set to VGL_DRAWFUN_TEE. This establishes two separate drawing functions as output from the DTee object.