Using DirectDraw Externally

While Fastgraph shields you from the DirectDraw API, there still might be times when you need to call a DirectDraw method yourself. The fg_ddgetobj() function is provided to help do this. It returns a pointer to any of the DirectDraw objects that Fastgraph creates internally; you can then use this pointer to call one of the object's methods. The fg_ddgetobj() function has one integer parameter that identifies the specific DirectDraw object:

The different versions of the DirectDraw and DirectDrawSurface objects correspond to the version of DirectX being used. For example, fg_ddgetobj(0) returns a pointer to a DirectDraw2 object if we are using DirectX 5 or earlier, a DirectDraw4 object for DirectX 6, and a DirectDraw7 object for DirectX 7. The DirectDrawClipper object is only used in windowed programs, and the DirectDrawPalette object is only used in full screen programs.

In Fastgraph's DirectX libraries, fg_vbinit() normally performs the initialization and other setup work needed for DirectX. Similarly, fg_vbfin() releases the DirectX resources created during a program's execution and shuts down DirectX in an orderly fashion. This is all hidden from your application so you don't have to call DirectX methods yourself. There may be times, however, when you need to initialize and shut down DirectX outside of Fastgraph, such as when interfacing with third party tools, or when adding Fastgraph code to an existing DirectX program. You can do this with fg_ddsetobj() and fg_ddapply() and then call other Fastgraph functions just as if fg_vbinit() had performed the DirectX initialization itself.

The fg_ddsetobj() function tells Fastgraph about an externally created DirectX object. Its first parameter is a pointer to that object, while its second parameter is a code that specifies the object type, using the same codes as fg_ddgetobj(). Any DirectDraw objects defined through fg_ddsetobj() must be defined before you call fg_vbinit(). Once you have created all the required DirectDraw objects and used fg_ddsetobj() to tell Fastgraph about them, use fg_ddapply() to activate these objects. This must be done after calling fg_vbinit(), but before you create any virtual buffers. The fg_ddapply() function has a single parameter that specifies the DirectX version number (5, 6, or 7). It is available only in Fastgraph's DirectX libraries.

Programs that create DirectX objects themselves rather than doing so through fg_vbinit() must explicitly release these objects immediately before calling fg_vbfin(). When you do this, you must also call fg_ddsetobj() again, passing a NULL object and the numeric code for that object. This tells Fastgraph the DirectX object no longer exists. For example, the code snippet shown here illustrates how you might release the DirectDraw7 object (code 0):

C/C++:

LPDIRECTDRAW7 lpDD;
if (lpDD != NULL)
{
   lpDD->Release();
   lpDD = NULL;
   fg_ddsetobj(NULL,0);
}

The SetupDD example shows how to externally manage DirectDraw for both windowed and full screen DirectDraw programs. Source code for SetupDD will not be presented here but is installed along with Fastgraph's other C/C++ examples (SetupDD is available only for C/C++).