9. Graphics Device Interfaces - Dev,OpenGLDev

VglTools Programmer Manual

The graphics device and file interface modules are responsible for rendering to windows on hardware graphics devices or to industry standard file formats. Currently VglTools supports rendering to graphics windows in either a X window or Microsoft Windows environment. In a X windows environment, File formats supported include Scalable Vector Graphics (SVG) format. the user is responsible for opening the X window display and selecting a display screen. Each graphics window module must be informed of the X window display and screen to which it is expected to draw. The device interface modules currently include the following,

Graphics window

    GDIDev       Interface to GDI (Microsoft Windows)
    OpenGLDev    Interface to OpenGL (X window, Microsoft Windows)
    X11Dev       Interface to X Windows (X window)
    SVGDev       Interface to Scalable Vector Graphics format

In the following, for each graphics interface, graphics functionality issues are discussed. These include the functionality assumed to be provided by the underlying API such as OpenGL. the graphics functionality specifically provided in software by VglTools and the functionality enabled only if supported by the underlying graphics hardware. In general all interfaces present a virtual true color visual to the application programmer. The virtual true color visual allows color to be specified as full RGB triples independent of the frame buffer depth.

All *Dev modules behave much alike. The functions of the OpenGLDev module will be used as representative of all graphics window modules.

9.1 Silicon Graphics OpenGL - OpenGLDev

The OpenGL device interface may be currently used on X windows and Microsoft windows platforms. It may also be used in a windowless environment using Mesa support. The mutually exclusive conditional compilation definitions to select one of these platforms are:

    VKI_WIND_WIN32      Microsoft Windows
    VKI_WIND_X11        X windows
    VKI_WIND_MESA       Mesa windowless

Note that currently shaders may not be activated when using Mesa.

The VglTools interface to OpenGL assumes a true color visual. OpenGL guarantees that such a visual will be present. Color dithering is performed by OpenGL in either hardware or software to support the visual. All VglTools graphics functionality is supported by OpenGL on all platforms. OpenGL ideally uses hardware acceleration when available and otherwise emulates functionality in software.

Note that on Microsoft Windows windows platforms the OpenGL interface is guaranteed to work correctly only if the Color palette of the Display is set to True Color. Set this using Settings->Control Panel->Display->Settings dialog. Other Color palette settings may work but low color or zbuffer resolution may result.

In the case that multiple OpenGLDev objects have been instanced, it is essential that the SetWindow function be called before drawing is to be directed to a particular window through the associated OpenGLDev object. This situation occurs when using a multiple view interface with Microsoft Foundation Classes (MFC).

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

    *vgl_OpenGLDevBegin      - create an instance of a OpenGLDev object
    vgl_OpenGLDevEnd         - destroy an instance of a OpenGLDev object
    vgl_OpenGLDevError       - return OpenGLDev object error flag

Get drawing functions

    vgl_OpenGLDevDrawFun     - fill DrawFun object

Test and connect to window system

    vgl_OpenGLDevConnectWIN  - connect to Microsoft Windows
    vgl_OpenGLDevConnectX    - connect to X windows display and screen
    vgl_OpenGLDevDisconnect  - disconnect from window system
    vgl_OpenGLDevBestVisualX - return pointer to best X window visual
    vgl_OpenGLDevTestWIN     - test for Microsoft Windows support
    vgl_OpenGLDevTestX       - test for X windows support

Buffers

    vgl_OpenGLDevShareBuffers - share OpenGL vertex buffers

Query

    vgl_OpenGLDevFBufferDataIndex - access data index

9.2 Function Descriptions

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

OpenGLDev

NAME

*vgl_OpenGLDevBegin - create an instance of a OpenGLDev object

C SPECIFICATION

    vgl_OpenGLDev *vgl_OpenGLDevBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a OpenGLDev object. Memory is allocated for the object private data and the pointer to the data is returned. All graphics attributes are set to the default values.

Destroy an instance of a OpenGLDev object using

         void vgl_OpenGLDevEnd (vgl_OpenGLDev *opengldev)

Return the current value of a OpenGLDev object error flag using

         Vint vgl_OpenGLDevError (vgl_OpenGLDev *opengldev)

OpenGLDev

NAME

vgl_OpenGLDevDrawFun - return pointers to drawing functions

C SPECIFICATION

    void vgl_OpenGLDevDrawFun (vgl_OpenGLDev *opengldev,
                               vgl_DrawFun *drawfun;

INPUT ARGUMENTS

    opengldev    Pointer to OpenGLDev object.
    drawfun      Pointer to DrawFun object to be filled with display list
                 drawing functions.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Fill a DrawFun object with graphics device drawing functions.

OpenGLDev

NAME

vgl_OpenGLDevConnectWIN - connect to Microsoft Windows

C SPECIFICATION

    void vgl_OpenGLDevConnectWIN ()

INPUT ARGUMENTS

    None

OUTPUT ARGUMENTS

    None

DESCRIPTION

Inform the OpenGLDev module to connect to Microsoft Windows. Note that the argument list does not include a OpenGLDev object. This means that this function is a class function. All subsequent OpenGLDev objects created using vgl_OpenGLDevBegin expect to connect to Microsoft Windows. Terminate the connection to the window system using vgl_OpenGLDevDisconnect.

OpenGLDev

NAME

vgl_OpenGLDevConnectX - connect to X windows display and screen

C SPECIFICATION

    void vgl_OpenGLDevConnectX (Display *display,
                                int screen)

INPUT ARGUMENTS

    display      Pointer to X window Display structure
    screen       Screen number

OUTPUT ARGUMENTS

    None

DESCRIPTION

Inform the OpenGLDev module of X window display and screen. Note that the argument list does not include a OpenGLDev object. This means that this function is a class function. The specified X window display and screen are used for all subsequent OpenGLDev objects created using vgl_OpenGLDevBegin. Terminate the connection to the X window system using vgl_OpenGLDevDisconnect.

OpenGLDev

NAME

vgl_OpenGLDevDisconnect - disconnect from window system

C SPECIFICATION

    void vgl_OpenGLDevDisconnect ()

INPUT ARGUMENTS

    None

OUTPUT ARGUMENTS

    None

DESCRIPTION

Disconnect OpenGLDev module from window system.

OpenGLDev

NAME

vgl_OpenGLDevBestVisualX - determine the best X windows visual for device

C SPECIFICATION

    void vgl_OpenGLDevBestVisualX (vgl_OpenGLDev *opengldev,
                                   Visual **visual)

INPUT ARGUMENTS

    opengldev    Pointer to OpenGLDev object.

OUTPUT ARGUMENTS

    visual       Pointer to best Visual structure for device.

ERRORS

VGL_ERROR_OPERATION is generated if a visual is not found.

DESCRIPTION

Query for the "best" X windows Visual for a device. The best visual is device dependent, however in general, the best visual is presumed to support truecolor graphics and double buffering. This function is useful for the case of the host application opening the X window and then connecting VglTools to the window using vgl_DrawFunConnectWindow.

The visual pointer is returned as NULL if a visual is not found. This often occurs if the X server does not support OpenGL.

OpenGLDev

NAME

vgl_OpenGLDevTestWIN - test for Microsoft Windows support

C SPECIFICATION

    void vgl_OpenGLDevTestWIN (Vint *flag)

INPUT ARGUMENTS

    None

OUTPUT ARGUMENTS

    flag         Flag indicating Microsoft Windows support
                 =VGL_OFF      Not support
                 =VGL_ON       Supported

DESCRIPTION

Query the OpenGLDev module for support under Microsoft Windows. The flag will be returned as VGL_OFF if the module has not been compiled for Microsoft Windows OpenGL support.

OpenGLDev

NAME

vgl_OpenGLDevTestX - test for X Windows support

C SPECIFICATION

    void vgl_OpenGLDevTestX (Vint *flag)

INPUT ARGUMENTS

    None

OUTPUT ARGUMENTS

    flag         Flag indicating X Windows support
                 =VGL_OFF      Not support
                 =VGL_ON       Supported

DESCRIPTION

Query the OpenGLDev module for support under X Windows. The flag will be returned as VGL_OFF if the module has not been compiled for X Windows OpenGL support.

OpenGLDev

NAME

vgl_OpenGLDevShareBuffers - share OpenGL vertex buffers

C SPECIFICATION

    void vgl_OpenGLDevShareBuffers (vgl_OpenGLDev *opengldev,
                                    vgl_OpenGLDev *oglshare)

INPUT ARGUMENTS

    opengldev    Pointer to OpenGLDev object.
    oglshare     Pointer to OpenGLDev object with buffers to share

OUTPUT ARGUMENTS

    None

DESCRIPTION

Share the buffers in OpenGLDev object oglshare. Buffers can not be created, copied, or terminated when sharing buffers from oglshare.

OpenGLDev

NAME

vgl_OpenGLDevFBufferDataIndex - access data index

C SPECIFICATION

    void vgl_OpenGLDevFBufferDataIndex (vgl_OpenGLDev *opengldev,
                                        Vint irow,
                                        vgl_FBuffer *fbuffer)

INPUT ARGUMENTS

    opengldev    Pointer to OpenGLDev object.
    irow         Data index row to read. irow >= 1.
    fbuffer      Pointer to FBuffer object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Read a specific DataIndex row into a FBuffer object. If irow is less than 1 or greater than the current maximum number of dataindex rows set using vgl_DrawFunSetMode with mode VGL_DATAINDEXMAXROWS nothing is read.

9.3 Generic X Windows - X11Dev

The VglTools interface to X windows uses low level Xlib graphics primitive functions to render to a generic X window. All VglTools graphics functionality (eg. z buffering, lighting, color dithering) is performed in software in X11Dev. The X11Dev module has been written to provide 3D graphics functionality for truecolor frame buffers. Double buffering is not supported. A non-standard function is available to set a monitor function in X11Dev. The non standard methods associated with X11Dev are the following.

Non standard

    vgl_X11DevSetFunction        - set callback functions

The rendering options in X11Dev may make it useful to install a monitor function to track the operation of X11Dev. Use vgl_X11DevSetFunction to set a user defined monitor function.

9.4 Function Descriptions

The non standard X11Dev functions are described in detail in this section.

X11Dev

NAME

vgl_X11DevSetFunction - set callback functions

C SPECIFICATION

    void vgl_X11DevSetFunction (vgl_X11Dev *x11dev,
                                Vint funtype,
                                void (*function)(),
                                Vobject *object)

INPUT ARGUMENTS

    x11dev       Pointer to X11Dev object.
    funtype      Type of callback function to set
                 =SYS_FUNCTION_MONITOR     Monitor callback
    function     Pointer to callback function
    object       Pointer to the object to be returned as function argument

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set callback functions. By default the callback functions are NULL. A callback is not invoked if it is NULL.

The monitor callback function prototype is

         void function (vgl_X11Dev *x11dev,
                        Vobject *object)

The first argument is the X11Dev object, x11dev, and the second is a user defined object, object. The monitor function is called in every graphics primitive function just before returning.

9.5 Generic Microsoft Windows Graphics Device Interface - GDIDev

The VglTools interface to Microsoft Windows uses low level GDI graphics primitive functions to render to a generic window. All VglTools graphics functionality (eg. z buffering, lighting) is performed in software in GDIDev. The GDIDev module has been written to provide 3D graphics functionality for truecolor frame buffers. Double buffering is not supported. A non-standard function is available to set a monitor function in GDIDev. The non standard methods associated with GDIDev are the following.

Non standard

    vgl_GDIDevSetFunction        - set callback functions

The rendering options in GDIDev may make it useful to install a monitor function to track the operation of GDIDev. Use vgl_GDIDevSetFunction to set a user defined monitor function.

9.6 Function Descriptions

The non standard GDIDev functions are described in detail in this section.

GDIDev

NAME

vgl_GDIDevSetFunction - set callback functions

C SPECIFICATION

    void vgl_GDIDevSetFunction (vgl_GDIDev *gdidev,
                                Vint funtype,
                                void (*function)(),
                                Vobject *object)

INPUT ARGUMENTS

    gdidev       Pointer to GDIDev object.
    funtype      Type of callback function to set
                 =SYS_FUNCTION_MONITOR     Monitor callback
    function     Pointer to callback function
    object       Pointer to the object to be returned as function argument

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set callback functions. By default the callback functions are NULL. A callback is not invoked if it is NULL.

The monitor callback function prototype is

         void function (vgl_GDIDev *gdidev,
                        Vobject *object)

The first argument is the GDIDev object, gdidev, and the second is a user defined object, object. The monitor function is called in every graphics primitive function just before returning.

9.7 Scalable Vector Graphics Format - SVGDev

This object supports rendering to the Scalable Vector Graphics format.

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

    *vgl_SVGDevBegin   - create an instance of a SVGDev object
    vgl_SVGDevEnd      - destroy an instance of a SVGDev object
    vgl_SVGDevError    - return SVGDev object error flag

Get drawing functions

    vgl_SVGDevDrawFun  - fill DrawFun object

Designate SVG base file name

    vgl_SVGDevOpenWindow  - connect to Microsoft Windows

The SVGDev object is designed to render to Scalable Vector Graphics (SVG) formatted files. An internal integer counter is maintained and incremented each time the vgl_DrawFunClear function is called. The integer is appended to a base file name which is specified in the The vgl_SVGDevOpenWindow function. The counter is initialized to zero. The file is opened when vgl_DrawFunClear is called and closed when vgl_DrawFunSwap is called. If the base file name is myfile.svg, then the first file generated is myfile1.svg, the second is myfile2.svg, etc. The base file name should include the .svg file suffix.

Note that the zbuffer mode is supported by caching and sorting primtives in back to front order to write to the SVG file.

9.8 Function Descriptions

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

SVGDev

NAME

*vgl_SVGDevBegin - create an instance of a SVGDev object

C SPECIFICATION

    vgl_SVGDev *vgl_SVGDevBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a SVGDev object. Memory is allocated for the object private data and the pointer to the data is returned. All graphics attributes are set to the default values.

Destroy an instance of a SVGDev object using

         void vgl_SVGDevEnd (vgl_SVGDev *svgdev)

Return the current value of a SVGDev object error flag using

         Vint vgl_SVGDevError (vgl_SVGDev *svgdev)

SVGDev

NAME

vgl_SVGDevDrawFun - return pointers to drawing functions

C SPECIFICATION

    void vgl_SVGDevDrawFun (vgl_SVGDev *svgdev,
                            vgl_DrawFun *drawfun;

INPUT ARGUMENTS

    svgdev       Pointer to SVGDev object.
    drawfun      Pointer to DrawFun object to be filled with display list
                 drawing functions.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Fill a DrawFun object with graphics device drawing functions.

SVGDev

NAME

vgl_SVGDevOpenWindow - connect to Microsoft Windows

C SPECIFICATION

    void vgl_SVGDevOpenWindow (vgl_SVGDev *svgdev,
                               Vchar *filename);

INPUT ARGUMENTS

    svgdev       Pointer to SVGDev object.
    filename     Base SVG file name

OUTPUT ARGUMENTS

    None

DESCRIPTION

Inform the SVGDev module to use the base filename for writing. Each time vgl_DrawFunClear is called a file is opened with a counter integer appended to the base file name. The file counter is initialized to zero and incremented when vgl_DrawFunClear is called. The file is closed when vgl_DrawFunSwap is called.