8. Software Rendering - DataBuf,RendBuf

VglTools Programmer Manual

The DataBuf and RendBuf modules perform software rendering of "data" and standard primitives to memory resident data buffers and color frame buffers. The intent is to provide a complete off-screen rendering capability for visible surface data query and standard color frame buffer generation. Both modules use software z-buffering and scan conversion techniques which closely replicate the z-buffering and scan conversion performed in hardware by modern 3D graphics workstations. The resulting software generated images are therefore of a similar quality to that which would have been generated by a complete hardware rendering implementation.

8.1 Data Buffer - DataBuf

The data buffer module, DataBuf is designed to be a memory resident "data" buffer which renders general integer or floating point data rather than color to a frame buffer. The DataBuf module is sensitive to all geometric and "data" graphics primitives and attributes. Attributes such as color are ignored as well as all lighting, pixel level operations and graphics input. Hidden surface calculations are performed using a z-buffering technique. The goal of the DataBuf module is to generate one or more software frame buffers which contain useful data about the visible rendered entity at each pixel.

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

    *vgl_DataBufBegin         - create an instance of a DataBuf object
    vgl_DataBufEnd            - destroy an instance of a DataBuf object
    vgl_DataBufError          - return DataBuf object error flag

Drawing functions, attributes, query

    vgl_DataBufDrawFun        - fill DrawFun object
    vgl_DataBufGetData        - get floating point frame buffer contents
    vgl_DataBufGetDataIndex   - get integer frame buffer contents
    vgl_DataBufSetBuffers     - set frame buffer configuration
    vgl_DataBufSetObject      - set attribute objects
    vgl_DataBufSetRender      - set standard graphics primitive sensitivity
    vgl_DataBufSetResolution  - set memory frame buffer resolution
    vgl_DataBufLinePixels     - return line pixels
    vgl_DataBufTriPixels      - return triangle pixels

The DataBuf module renders data attributes rather than color attributes. The data attribute drawing functions are Data and DataIndex. The data primitive drawing functions are PolyPointData, PolyLineData, PolygonData and the optional data input to PolyPointArray, PolyLineArray, PolygonArray, PolyPointBuffer, PolyLineBuffer and PolygonBuffer. Color graphics attributes such as Color, ColorIndex, BackColor and BackColorIndex are ignored. In addition, the color, normal and texture data associated with PolyPointColor, PolyLineColor, PolygonColor, PolyPointArray, PolyLineArray, PolygonArray, PolyPointBuffer, PolyLineBuffer and PolygonBuffer is ignored.

The current Data and DataIndex attributes are rendered as constant values over any standard (non "data") graphics primitive. The user may enable or disable the rendering sensitivity of DataBuf to standard primitives using vgl_DataBufSetRender.

The type and number of software frame buffers used by the DataBuf module is configurable using vgl_DataBufSetBuffers. The module has been designed to simultaneously render the current DataIndex attributes to one or more integer frame buffers and the current floating point Data attribute to one or more floating point frame buffers. The Data attribute may be Gouraud shaded over points, lines and polygons using the PolyPointData, PolyLineData and PolygonData drawing functions as well as the PolyPointArray, PolyLineArray and PolygonArray and PolyPointBuffer, PolyLineBuffer and PolygonBuffer drawing functions. The current DataIndex values are rendered over any data primitive if one or more integer data buffers are enabled. The functions vgl_DataBufGetData and vgl_DataBufGetDataIndex are provided to quickly query the contents of the integer and floating point frame buffers at any pixel.

Note that if the DataBuf drawing functions PolyPointBuffer, PolyLineBuffer and PolygonBuffer are used then the primitive data is stored in graphics memory in a hardware graphics interface such as OpenGLDev. In this case the drawing functions to the hardware interface which has been used to store the graphics primitives in graphics memory (for example, Vertex Buffer Objects in OpenGL) must be registered using the vgl_DataBufSetObject function.

Use the helper functions vgl_DataBufLinePixels and vgl_DataBufTriPixels to return the pixels along a line or within a triangle.

Note that transparency is implemented using a polygon stipple, also known as "screen door" transparency. This means that, for example, if a 50 percent transparent polygon is drawn, only every other pixel with the polygon will be affected.

8.2 Function Descriptions

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

DataBuf

NAME

*vgl_DataBufBegin - create an instance of a DataBuf object

C SPECIFICATION

    vgl_DataBuf *vgl_DataBufBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a DataBuf object. Memory is allocated for the object private data and the pointer to the data is returned. By default an integer frame buffer is enabled and all standard primitives render the current DataIndex and Data attributes.

Destroy an instance of a DataBuf object using

         void vgl_DataBufEnd (vgl_DataBuf *databuf)

Return the current value of a DataBuf object error flag using

         Vint vgl_DataBufError (vgl_DataBuf *databuf)

DataBuf

NAME

vgl_DataBufDrawFun - return pointers to drawing functions

C SPECIFICATION

    void vgl_DataBufDrawFun (vgl_DataBuf *databuf,
                             vgl_DrawFun *drawfun)

INPUT ARGUMENTS

    databuf      Pointer to DataBuf object.
    drawfun      Pointer to DrawFun object to be filled with 
                 drawing functions.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Fill a DrawFun object with data buffer drawing functions.

DataBuf

NAME

vgl_DataBufGetData,vgl_DataBufGetDataIndex - get data and dataindex values

C SPECIFICATION

    void vgl_DataBufGetData (vgl_DataBuf *databuf,
                             Vint ix,
                             Vint iy,
                             Vint *nrws,
                             Vfloat *d)
    
    void vgl_DataBufGetDataIndex (vgl_DataBuf *databuf,
                                  Vint ix,
                                  Vint iy,
                                  Vint *indices)

INPUT ARGUMENTS

    databuf      Pointer to DataBuf object.
    ix           Horizontal device coordinate of data pixel
    iy           Vertical device coordinate of data pixel

OUTPUT ARGUMENTS

    nrws         Number of floating point values returned
    d            Vector of data values
    indices      Data indices

DESCRIPTION

Return data or data indices at a given pixel. If data or data index buffers are not enabled, the corresponding d vector or indices values are undefined. The number of rows filled in the d vector is returned. If the data buffer is disabled nrws is returned as zero. The number of data indices returned is equal to the number of data index buffers specified with vgl_DataBufSetBuffers. If device coordinates are specified outside of the current viewport limits, then d and indices are undefined.

DataBuf

NAME

vgl_DataBufSetBuffers - set data frame buffer configuration

C SPECIFICATION

    void vgl_DataBufSetBuffers (vgl_DataBuf *databuf,
                                Vint indexflag,
                                Vint dataflag)

INPUT ARGUMENTS

    databuf      Pointer to DataBuf object.
    indexflag    Specify number of integer data index frame buffers
    dataflag     Specify number of floating point data frame buffers

OUTPUT ARGUMENTS

    None

DESCRIPTION

Specify the data buffer configuration. Zero, one or more integer frame buffers for DataIndex attributes and zero, one or more floating point frame buffers for Data attributes and primitives may be enabled.

DataBuf

NAME

vgl_DataBufSetObject - set attribute object

C SPECIFICATION

    void vgl_DataBufSetObject (vgl_DataBuf *databuf,
                               Vint objecttype,
                               Vobject *object)

INPUT ARGUMENTS

    databuf      Pointer to DataBuf 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 to support the PolyPointBuffer, PolyLineBuffer and PolygonBuffer drawing functions. In this case the drawing function must point to the hardware rendering object used to create the memory resident data on the graphics hardware, for example VBO's created by OpenGLDev.

DataBuf

NAME

vgl_DataBufSetRender - set sensitivity to standard primitives.

C SPECIFICATION

    void vgl_DataBufSetRender (vgl_DataBuf *databuf,
                               Vint pointflag,
                               Vint lineflag,
                               Vint polyflag)

INPUT ARGUMENTS

    databuf      Pointer to DataBuf object.
    pointflag    Specify standard point primitives to be rendered.
                 =VGL_OFF      Turn off point primitives
                 =VGL_ON       Turn on point primitives
    lineflag     Specify standard line primitives to be rendered.
                 =VGL_OFF      Turn off line primitives
                 =VGL_ON       Turn on line primitives
    polyflag     Specify standard polygon primitives to be rendered.
                 =VGL_OFF      Turn off polygon primitives
                 =VGL_ON       Turn on polygon primitives

OUTPUT ARGUMENTS

    None

DESCRIPTION

By default all standard point, line and polygon primitives are rendered using the current constant DataIndex and Data attributes. Use this function to selectively enable or disable the rendering of each of these types of graphics primitives. Text primitives are treated as point primitives.

DataBuf

NAME

vgl_DataBufSetResolution - set pixels per centimeter resolution

C SPECIFICATION

    void vgl_DataBufSetResolution (vgl_DataBuf *databuf,
                                   Vfloat xres,
                                   Vfloat yres)

INPUT ARGUMENTS

    databuf      Pointer to DataBuf object.
    xres         Pixels per centimeter in horizontal direction
    yres         Pixels per centimeter in vertical direction

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set resolution of data frame buffer. By default the resolution is 37.5 pixels per centimeter in both the horizontal and vertical directions.

DataBuf

NAME

vgl_DataBufLinePixels - return line pixels

C SPECIFICATION

    void vgl_DataBufLinePixels (vgl_DataBuf *databuf,
                                Vint ixy1[2],
                                Vint ixy2[2],
                                Vint *npix,
                                Vint pix[][2])

INPUT ARGUMENTS

    databuf      Pointer to DataBuf object.
    ixy1         Pixel coordinate of first line endpoint
    ixy2         Pixel coordinate of second line endpoint

OUTPUT ARGUMENTS

    npix         Number of pixels returned
    pix          Pixel coordinates from first to second endpoint

DESCRIPTION

Return pixels along a line from pixel coordinate ixy1 to ixy2.

DataBuf

NAME

vgl_DataBufTriPixels - return triangle pixels

C SPECIFICATION

    void vgl_DataBufTriPixels (vgl_DataBuf *databuf,
                               Vint ixy1[2],
                               Vint ixy2[2],
                               Vint ixy3[2],
                               Vint *npix,
                               Vint pix[][2])

INPUT ARGUMENTS

    databuf      Pointer to DataBuf object.
    ixy1         Pixel coordinate of first tri corner
    ixy2         Pixel coordinate of second tri corner
    ixy3         Pixel coordinate of third tri corner

OUTPUT ARGUMENTS

    npix         Number of pixels returned
    pix          Pixel coordinates from left to right, bottom to top.

DESCRIPTION

Return pixels within a triangle with corner pixel coordinates ixy1, ixy2 and ixy3 in counter clockwise order.

8.3 Color Buffer - RendBuf

The RendBuf module provides a software rendering capability which is meant to implement the hardware rendering features provided by the *Dev modules. For example, hidden surface removal is preformed using standard z-buffer techniques, all lighting computations use the same lighting model as the "hardware" rendering modules. The RendBuf module provides special functions to return the internal color frame buffer, FBuffer, and z-buffer, ZBuffer, objects.

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

    *vgl_RendBufBegin         - create an instance of a RendBuf object
    vgl_RendBufEnd            - destroy an instance of a RendBuf object
    vgl_RendBufError          - return RendBuf object error flag

Drawing functions, attributes, query

    vgl_RendBufDrawFun        - fill DrawFun object
    vgl_RendBufGetFBuffer     - get internal frame buffer object
    vgl_RendBufGetZBuffer     - get internal z-buffer object
    vgl_RendBufSetObject      - set attribute objects
    vgl_RendBufSetResolution  - set memory frame buffer resolution

Before rendering to a software frame buffer, a RendBuf object must be instanced using vgl_RendBufBegin. The resolution of the software frame buffer may be set using vgl_RendBufSetResolution if the default resolution must be changed. The default resolution has been chosen to approximate a high resolution 19 inch monitor. In a manner similar to any *Dev module, a DrawFun object should be instanced, registering the RendBuf module drawing functions using vgl_RendBufDrawFun. At this point, the drawing functions may be used to draw to the software renderer.

Note that if the RendBuf drawing functions PolyPointBuffer, PolyLineBuffer and PolygonBuffer are used then the primitive data is stored in graphics memory in a hardware graphics interface such as OpenGLDev. In this case the drawing functions to the hardware interface which has been used to store the graphics primitives in graphics memory (for example, Vertex Buffer Objects in OpenGL) must be registered using the vgl_RendBufSetObject function.

Once rendering is complete use vgl_RendBufGetFBuffer and vgl_RendBufGetZBuffer to return the color buffer, FBuffer and/or z-buffer, ZBuffer objects created by the software renderer. Standard FBuffer and ZBuffer functions may be used to write the image to a file, draw it with a *Dev module, etc.

8.4 Function Descriptions

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

RendBuf

NAME

*vgl_RendBufBegin - create an instance of a RendBuf object

C SPECIFICATION

    vgl_RendBuf *vgl_RendBufBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

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

Destroy an instance of a RendBuf object using

         void vgl_RendBufEnd (vgl_RendBuf *rendbuf)

Return the current value of a RendBuf object error flag using

         Vint vgl_RendBufError (vgl_RendBuf *rendbuf)

RendBuf

NAME

vgl_RendBufDrawFun - return pointers to drawing functions

C SPECIFICATION

    void vgl_RendBufDrawFun (vgl_RendBuf *rendbuf,
                             vgl_DrawFun *drawfun)

INPUT ARGUMENTS

    rendbuf      Pointer to RendBuf object.
    drawfun      Pointer to DrawFun object to be filled with 
                 drawing functions.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Fill a DrawFun object with color buffer drawing functions.

RendBuf

NAME

vgl_RendBufGetFBuffer,vgl_RendBufGetZBuffer - get internal buffers

C SPECIFICATION

    void vgl_RendBufGetFBuffer (vgl_RendBuf *rendbuf,
                                vgl_FBuffer **fbuffer)
    
    void vgl_RendBufGetZBuffer (vgl_RendBuf *rendbuf,
                                vgl_ZBuffer **zbuffer)

INPUT ARGUMENTS

    rendbuf      Pointer to RendBuf object.

OUTPUT ARGUMENTS

    fbuffer      Pointer to internal FBuffer object
    zbuffer      Pointer to internal ZBuffer object

DESCRIPTION

Return internal frame buffer (color), FBuffer, object or z-buffer (depth), ZBuffer object. If these objects are returned before the RendBuf window is opened, NULL is returned. The objects belong to the RendBuf object and must not be destroyed, allocated or freed.

RendBuf

NAME

vgl_RendBufSetObject - set attribute object

C SPECIFICATION

    void vgl_RendBufSetObject (vgl_RendBuf *databuf,
                               Vint objecttype,
                               Vobject *object)

INPUT ARGUMENTS

    rendbuf      Pointer to RendBuf 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 to support the PolyPointBuffer, PolyLineBuffer and PolygonBuffer drawing functions. In this case the drawing function must point to the hardware rendering object used to create the memory resident data on the graphics hardware, for example VBO's created by OpenGLDev.

RendBuf

NAME

vgl_RendBufSetResolution - set pixels per centimeter resolution

C SPECIFICATION

    void vgl_RendBufSetResolution (vgl_RendBuf *rendbuf,
                                   Vfloat xres,
                                   Vfloat yres)

INPUT ARGUMENTS

    rendbuf      Pointer to RendBuf object.
    xres         Pixels per centimeter in horizontal direction
    yres         Pixels per centimeter in vertical direction

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set resolution of color frame buffer. By default the resolution is 37.5 pixels per centimeter in both the horizontal and vertical directions.