11. Graphics Primitive Processing, - DOpt

VglTools Programmer Manual

The DOpt module is designed to transform a stream of graphics primitives into a form which may be efficiently rendered by high performance 3D graphics hardware.

11.1 Graphics Primitive Sorting and Grouping - DOpt

A critical step in optimizing graphics performance is to present sets of similar graphics primitives to the graphics hardware. This optimization has a tendency to reduce procedure call overhead as well as take advantage of features in the underlying 3D graphics API (eg. OpenGL) for processing groups of graphics primitives. The graphics stream is optimized by implementing the following strategies:

Combine independent point, line and polygonal graphics primitives into sets of similar type. These sets are sent in turn to the graphics hardware and are rendered more efficiently than the equivalent graphics primitives sent one at a time to the graphics hardware. This operation is performed by the DOpt module.
Store the optimized graphics primitives in a display list data structure which is optimized for traversal speed. The DList module is designed for this purpose.

The incoming graphics primitives from the PolyPoint, PolyPointColor, PolyLine, PolyLineColor, Polygon and PolygonColor are sorted and stored in buffers of similar type. The buffer size may be set by using vgl_DOptSetParami. The buffers are flushed when appropriate using the PolyPointArray, PolyLineArray and PolygonArray drawing functions respectively. Any graphics attributes such as line style, line width, point size, lighting or transformation flush all buffers. Redundant graphics attributes are filtered and removed without causing the buffers to be flushed. Care must be taken to use an explicit Flush drawing function when the graphics scene is complete to flush any remaining buffers. Note that the sorting operations performed by the DOpt module will, in general, result in a reordering of graphics primitives. The DOpt module contains the following functions.

Begin and end an instance of an object, return object error flag

    *vgl_DOptBegin         - create an instance of a DOpt object
    vgl_DOptEnd            - destroy an instance of a DOpt object
    vgl_DOptError          - return DOpt object error flag

Set objects, drawing functions, etc.

    vgl_DOptDrawFun        - fill DrawFun object
    vgl_DOptFlush          - flush internal graphics buffers
    vgl_DOptReset          - reset current graphics attributes
    vgl_DOptSetObject      - set pointers to attribute objects.
    vgl_DOptSetParami      - set optimization parameters

The DOpt module is a filter which temporarily retains a moderate number of graphics primitives to sort and group them before passing them to the output drawing function object. To embed an object into the graphics stream, instance a DOpt object using vgl_DOptBegin. Register the drawing functions in a DrawFun object for incoming graphics primitives using vgl_DOptDrawFun. Set the drawing function object for output graphics using vgl_DOptSetObject.

The current base color and data index are stored in DOpt. The base color is used to optimize small sets of graphics primitives with changing base color to a vertex color primitive. Use vgl_DOptReset to set the current base color to an undefined state. This is useful if several indepenent graphics objects (such as several DList objects) are being optimized with a single DOpt object. Call vgl_DOptReset before streaming graphics through DOpt to the object and call vgl_DOptFlush when then graphics streaming is complete.

11.2 Attribute Objects

A DOpt object requires a conventional DrawFun object to render its contents to a graphics device. Use vgl_DOptSetObject to set a DrawFun object as an attribute.

11.3 Function Descriptions

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

DOpt

NAME

*vgl_DOptBegin - create an instance of a DOpt object

C SPECIFICATION

    vgl_DOpt *vgl_DOptBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a DOpt object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a DOpt object using

         void vgl_DOptEnd (vgl_DOpt *dopt)

Return the current value of a DOpt object error flag using

         Vint vgl_DOptError (vgl_DOpt *dopt)

DOpt

NAME

vgl_DOptDrawFun - return pointers to drawing functions

C SPECIFICATION

    void vgl_DOptDrawFun (vgl_DOpt *dopt,
                          vgl_DrawFun *drawfun)

INPUT ARGUMENTS

    dopt         Pointer to DOpt object.
    drawfun      Pointer to DrawFun object to be filled with
                 drawing functions.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Fill a DrawFun object with display file drawing functions.

DOpt

NAME

vgl_DOptFlush - flush internal graphics buffers

C SPECIFICATION

    void vgl_DOptFlush (vgl_DOpt *dopt)

INPUT ARGUMENTS

    dopt         Pointer to DOpt object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Flush internal graphics buffers. This function should be called at the conclusion of drawing a graphics object to ensure that all graphics primitives have been flushed from the internal graphics buffers.

DOpt

NAME

vgl_DOptReset - reset current graphics attributes

C SPECIFICATION

    void vgl_DOptReset (vgl_DOpt *dopt)

INPUT ARGUMENTS

    dopt         Pointer to DOpt object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Reset graphics state. The base color and dataindex are returned to an undefined state.

DOpt

NAME

vgl_DOptSetObject - set pointers to attribute objects

C SPECIFICATION

    void vgl_DOptSetObject (vgl_DOpt *dopt,
                            Vint objecttype,
                            Vobject *object)

INPUT ARGUMENTS

    dopt         Pointer to DOpt 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.

DOpt

NAME

vgl_DOptSetParami - set optimization parameters

C SPECIFICATION

    void vgl_DOptSetParami (vgl_DOpt *dopt,
                            Vint ptype,
                            Vint iparam)

INPUT ARGUMENTS

    dopt         Pointer to DOpt object.
    ptype        Type of parameter to set
                 =DOPT_MAXBUFFER          Buffer size in vertices
                 =DOPT_DECOMPOSE          Decompose strips and loops
    iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

    None

ERRORS

VIS_ERROR_ENUM is generated if an improper node ptype is specified.

DESCRIPTION

Set optimization parameters. The DOPT_MAXBUFFER parameter sets the buffer size in vertices. By default the buffer size is 16*1024 vertices.

The DOPT_DECOMPOSE parameter toggles the decomposition of triangle strips to triangles and line strips and line loops to lines. By default the toggle is off.