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,
-
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
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 windowlessNote 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 objectC 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 functionsC 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 WindowsC 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 screenC 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 systemC 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 deviceC 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 supportC 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 supportC 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 buffersC 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 indexC 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
9.4 Function Descriptions
The non standard X11Dev functions are described in detail in this section.
X11Dev
NAME
vgl_X11DevSetFunction - set callback functionsC 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
9.6 Function Descriptions
The non standard GDIDev functions are described in detail in this section.
GDIDev
NAME
vgl_GDIDevSetFunction - set callback functionsC 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
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 objectC 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 functionsC 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 WindowsC 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.