Table of Contents

9. Graphics Device Interfaces - *Dev,OpenGLDev

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, 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.

Table of Contents

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).

Table of Contents

9.2 Function Descriptions

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

Table of Contents , 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)

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents , 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.

Table of Contents

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.

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.

Table of Contents

9.4 Function Descriptions
The non standard X11Dev functions are described in detail in this section.
Table of Contents , 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.

Table of Contents

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.

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.

Table of Contents

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

Table of Contents , 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.

Table of Contents

9.7 Scalable Vector Graphics Format - SVGDev

This object supports rendering to the Scalable Vector Graphics format.

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.

Table of Contents

9.8 Function Descriptions

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

Table of Contents , 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)

Table of Contents , 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.

Table of Contents , 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.