GA_queryFunctions

Returns the function pointers for the specified function group.

Declaration

ibool NAPI GA_queryFunctions(
    GA_devCtx *dc,
    N_uint32 id,
    void _FAR_ *funcs)

Prototype In

snap/graphics.h

Parameters

dc

Device driver to return the functions for

id

Identifier for the function group to get pointers for

funcs

Pointer to function block to fill in

 

Return Value

True if the requested function group is available, false if not.

Description

This function is the main function that is used by the graphics application code to get a block of function pointers for a specified function group. The function groups are defined GA_funcGroupsType enumeration, and breaks up the functions in the device driver API into groups of logically similar functions. For instance to get the block of functions for the hardware cursor, you would call this function with the GA_GET_CURSORFUNCS identifier.

All application and device driver code must call this function and never call the GA_devCtx->loader.QueryFunctions member directly. This is important because in many cases special procedures must be followed to allow ring 3 application code to directly call the function pointers returned by the internal function. The GA_devCtx version always returns the actual device driver functions which may require that they be called at ring 0 on some platforms. This function insulates the developer from worrying about this as the functions returned by this function are always safe to be called from the context that the code is compiled (ie: this function should be used for all ring 0 device driver and ring 3 application level code).

Note:    To allow for future compatibility, all function blocks begin with a dwSize member. The caller is expected to fill in the dwSize member with the size of the function block being retrieved before calling GA_queryFunctions. If the driver exports more functions than the application knows about, only a subset of the functions are copied to the application. If the application expects more functions than the driver provides, the non-existant functions are set to NULL pointers by GA_queryFunctions, and the remainder copies from the driver.

Note:    This mechanism also provides for a clean and simple upgrade path for future drivers, while ensuring maximum compatibility with existing specifications. New functions for a particular group can simply be added to the end of the function group to extend that group. Totally new function groups can be added by defining new identifiers for that function group, and older drivers will return a NULL if that function group is requested. Finally if a function group requires a complete redesign to achieve maximum peformance for next generation hardware, a new extended function group can be defined (and drivers can continue to export the older and slower function group for backwards compatibility).

See Also

REF2D_queryFunctions

Copyright © 2002 SciTech Software, Inc. Visit our web site at http://www.scitechsoft.com