If you're planning on programming with the DirectX SDK, I am assuming that you have a firm grasp on C++ as well as the Platform SDK. Also, for all of these tutorials, you must include DDRAW.H and you must link your compiler to DDRAW.LIB, or add the file to your project. Your DirectDraw applications will not work without them.
Now that you have the compiler set up, we're ready to get programming with DirectDraw. To begin with, you need a Win32 window to attach your DirectDraw application to. You should create three functions: one for initializing things, one for the "actual" coding, and one for shutting down your DirectDraw application. The ideal spots for these functions are: before the main event loop, towards the end of the main even loop, and right after the main event loop ends, respectively. The idea of doing this is that your initialization stuff happens when your window initializes, your code lines will never go out of focus if they're in the main event loop, and you can free up your resources when the program exits.
The first thing that you must do before you can program with DirectDraw is to create a DirectDraw COM object. This can be done with the DirectDrawCreate function, which is defined as such:
HRESULT DirectDrawCreate(GUID FAR *lpGUID, LPDIRECTDRAW FAR *lplpDD, IUnkown FAR *pUnkOuter);
The first parameter is a GUID, a Globally Unique Identifier, which selects the video driver. By entering NULL for this value, the default video driver will be used. The second parameter is where the address of the COM interface is placed (more on that later, it will become clearer when you see the code in action). The last parameter is an advanced feature and is always set to NULL.
In order for the function to work, we need to create a pointer to a COM interface object. This can be accomplished like so:
LPDIRECTDRAW lpdd;
We'll add one more function and then we'll create the code to create a DirectDraw object. This last function is quite logical in it's usage. A DirectDraw object uses resources, as do any objects. To be a kind programmer, you should release these resources after you are done using them so that the resources may be used by other programs. This can be done with this function:
Release();
The Release() function is used to free up the memory allocated to all DirectX components. However, since all COM interfaces are pure virtual, all their functions are stored in a VTABLE. Therefore, to use the function, you must use pointer dereferencing.
Well, I've shown you just about everything now to create a DirectDraw object. For this code, you should download and include the dderr.h header file. The following is the code in all its glory to create the COM object:
if(ddrval = DirectDrawCreate(NULL, &lpdd, NULL) != DD_OK)
if(lpdd)//test to see if the variable equals NULL
LPDIRECTDRAW lpdd; //pointer to interface object
HRESULT ddrval; //used to test if function worked
OutputDebugString(MyErrorToString(ddrval));
lpdd->Release();//if not equal to NULL, release it's memory
I know you must be wondering about some aspects of the code.
Well, that is a lot of information that we covered. I realize that this code doesn't actually do much, but we had to get some concepts put behind us first. Throughout the rest of the tutorials, I will make use of dderr.h, so I suggest that you do as well. In the next tutorial we will cover how to set the cooperation level, display mode, and we'll even create a surface to draw on!
The source files for this lesson can be downloaded here.
ddrval holds a return value. If the value equals DD_OK, the function worked. Comparing DirectDraw functions to OutputDebugString does just like it sounds like. It writes a line of code to the debug line, so while debugging you can see what errors you have. MyErrorToString(), which is what OutputDebugString outputs, is used as header file. I did not write this header file, but rather found it across the Internet. The original author of the code is named in the header, and I think if you're going to use his work (which I recommend), then at least leave his name in the header. If you don't want to use the header, and prefer to check errors in a different manner, at least the following code will give you some information about what the somewhat cryptic error codes mean. Here is the code for that header file:
/*******************************************************************************************
* I got this code from The book The Awesome Power of Direct3D/DirectX
* by Peter J. Kovach
*
* To use this, whenever you get an error in your directdraw functions, do this
*
* OutputDebugString(MyErrorToString(ddrval));
*
* ddrval is an HRESULT that holds the error as you already know, and I wrote it like
* this to reduce overhead. If I used a pointer to a char I would only need it once
* anyway
********************************************************************************************/
MyErrorToString(HRESULT error)
{
switch (error)
{
case DD_OK:
// Also includes D3D_OK and D3DRM_OK
return "No error.\0";
case DDERR_ALREADYINITIALIZED:
return "This object is already initialized.\0";
case DDERR_BLTFASTCANTCLIP:
return "Return if a clipper object is attached to the source surface passed into a BltFast call.\0";
case DDERR_CANNOTATTACHSURFACE:
return "This surface can not be attached to the requested surface.\0";
case DDERR_CANNOTDETACHSURFACE:
return "This surface can not be detached from the requested surface.\0";
case DDERR_CANTCREATEDC:
return "Windows can not create any more DCs.\0";
case DDERR_CANTDUPLICATE:
return "Can't duplicate primary & 3D surfaces, or surfaces that are implicitly created.\0";
case DDERR_CLIPPERISUSINGHWND:
return "An attempt was made to set a cliplist for a clipper object that is already monitoring an hwnd.\0";
case DDERR_COLORKEYNOTSET:
return "No src color key specified for this operation.\0";
case DDERR_CURRENTLYNOTAVAIL:
return "Support is currently not available.\0";
case DDERR_DIRECTDRAWALREADYCREATED:
return "A DirectDraw object representing this driver has already been created for this process.\0";
case DDERR_EXCEPTION:
return "An exception was encountered while performing the requested operation.\0";
case DDERR_EXCLUSIVEMODEALREADYSET:
return "An attempt was made to set the cooperative level when it was already set to exclusive.\0";
case DDERR_GENERIC:
return "Generic failure.\0";
case DDERR_HEIGHTALIGN:
return "Height of rectangle provided is not a multiple of reqd alignment.\0";
case DDERR_HWNDALREADYSET:
return "The CooperativeLevel HWND has already been set. It can not be reset while the process has surfaces or palettes created.\0";
case DDERR_HWNDSUBCLASSED:
return "HWND used by DirectDraw CooperativeLevel has been subclassed, this prevents DirectDraw from restoring state.\0";
case DDERR_IMPLICITLYCREATED:
return "This surface can not be restored because it is an implicitly created surface.\0";
case DDERR_INCOMPATIBLEPRIMARY:
return "Unable to match primary surface creation request with existing primary surface.\0";
case DDERR_INVALIDCAPS:
return "One or more of the caps bits passed to the callback are incorrect.\0";
case DDERR_INVALIDCLIPLIST:
return "DirectDraw does not support the provided cliplist.\0";
case DDERR_INVALIDDIRECTDRAWGUID:
return "The GUID passed to DirectDrawCreate is not a valid DirectDraw driver identifier.\0";
case DDERR_INVALIDMODE:
return "DirectDraw does not support the requested mode.\0";
case DDERR_INVALIDOBJECT:
return "DirectDraw received a pointer that was an invalid DIRECTDRAW object.\0";
case DDERR_INVALIDPARAMS:
return "One or more of the parameters passed to the function are incorrect.\0";
case DDERR_INVALIDPIXELFORMAT:
return "The pixel format was invalid as specified.\0";
case DDERR_INVALIDPOSITION:
return "Returned when the position of the overlay on the destination is no longer legal for that destination.\0";
case DDERR_INVALIDRECT:
return "Rectangle provided was invalid.\0";
case DDERR_LOCKEDSURFACES:
return "Operation could not be carried out because one or more surfaces are locked.\0";
case DDERR_NO3D:
return "There is no 3D present.\0";
case DDERR_NOALPHAHW:
return "Operation could not be carried out because there is no alpha accleration hardware present or available.\0";
case DDERR_NOBLTHW:
return "No blitter hardware present.\0";
case DDERR_NOCLIPLIST:
return "No cliplist available.\0";
case DDERR_NOCLIPPERATTACHED:
return "No clipper object attached to surface object.\0";
case DDERR_NOCOLORCONVHW:
return "Operation could not be carried out because there is no color conversion hardware present or available.\0";
case DDERR_NOCOLORKEY:
return "Surface doesn't currently have a color key\0";
case DDERR_NOCOLORKEYHW:
return "Operation could not be carried out because there is no hardware support of the destination color key.\0";
case DDERR_NOCOOPERATIVELEVELSET:
return "Create function called without DirectDraw object method SetCooperativeLevel being called.\0";
case DDERR_NODC:
return "No DC was ever created for this surface.\0";
case DDERR_NODDROPSHW:
return "No DirectDraw ROP hardware.\0";
case DDERR_NODIRECTDRAWHW:
return "A hardware-only DirectDraw object creation was attempted but the driver did not support any hardware.\0";
case DDERR_NOEMULATION:
return "Software emulation not available.\0";
case DDERR_NOEXCLUSIVEMODE:
return "Operation requires the application to have exclusive mode but the application does not have exclusive mode.\0";
case DDERR_NOFLIPHW:
return "Flipping visible surfaces is not supported.\0";
case DDERR_NOGDI:
return "There is no GDI present.\0";
case DDERR_NOHWND:
return "Clipper notification requires an HWND or no HWND has previously been set as the CooperativeLevel HWND.\0";
case DDERR_NOMIRRORHW:
return "Operation could not be carried out because there is no hardware present or available.\0";
case DDERR_NOOVERLAYDEST:
return "Returned when GetOverlayPosition is called on an overlay that UpdateOverlay has never been called on to establish a destination.\0";
case DDERR_NOOVERLAYHW:
return "Operation could not be carried out because there is no overlay hardware present or available.\0";
case DDERR_NOPALETTEATTACHED:
return "No palette object attached to this surface.\0";
case DDERR_NOPALETTEHW:
return "No hardware support for 16 or 256 color palettes.\0";
case DDERR_NORASTEROPHW:
return "Operation could not be carried out because there is no appropriate raster op hardware present or available.\0";
case DDERR_NOROTATIONHW:
return "Operation could not be carried out because there is no rotation hardware present or available.\0";
case DDERR_NOSTRETCHHW:
return "Operation could not be carried out because there is no hardware support for stretching.\0";
case DDERR_NOT4BITCOLOR:
return "DirectDrawSurface is not in 4 bit color palette and the requested operation requires 4 bit color palette.\0";
case DDERR_NOT4BITCOLORINDEX:
return "DirectDrawSurface is not in 4 bit color index palette and the requested operation requires 4 bit color index palette.\0";
case DDERR_NOT8BITCOLOR:
return "DirectDrawSurface is not in 8 bit color mode and the requested operation requires 8 bit color.\0";
case DDERR_NOTAOVERLAYSURFACE:
return "Returned when an overlay member is called for a non-overlay surface.\0";
case DDERR_NOTEXTUREHW:
return "Operation could not be carried out because there is no texture mapping hardware present or available.\0";
case DDERR_NOTFLIPPABLE:
return "An attempt has been made to flip a surface that is not flippable.\0";
case DDERR_NOTFOUND:
return "Requested item was not found.\0";
case DDERR_NOTLOCKED:
return "Surface was not locked. An attempt to unlock a surface that was not locked at all, or by this process, has been attempted.\0";
case DDERR_NOTPALETTIZED:
return "The surface being used is not a palette-based surface.\0";
case DDERR_NOVSYNCHW:
return "Operation could not be carried out because there is no hardware support for vertical blank synchronized operations.\0";
case DDERR_NOZBUFFERHW:
return "Operation could not be carried out because there is no hardware support for zbuffer blitting.\0";
case DDERR_NOZOVERLAYHW:
return "Overlay surfaces could not be z layered based on their BltOrder because the hardware does not support z layering of overlays.\0";
case DDERR_OUTOFCAPS:
return "The hardware needed for the requested operation has already been allocated.\0";
case DDERR_OUTOFMEMORY:
return "DirectDraw does not have enough memory to perform the operation.\0";
case DDERR_OUTOFVIDEOMEMORY:
return "DirectDraw does not have enough memory to perform the operation.\0";
case DDERR_OVERLAYCANTCLIP:
return "The hardware does not support clipped overlays.\0";
case DDERR_OVERLAYCOLORKEYONLYONEACTIVE:
return "Can only have ony color key active at one time for overlays.\0";
case DDERR_OVERLAYNOTVISIBLE:
return "Returned when GetOverlayPosition is called on a hidden overlay.\0";
case DDERR_PALETTEBUSY:
return "Access to this palette is being refused because the palette is already locked by another thread.\0";
case DDERR_PRIMARYSURFACEALREADYEXISTS:
return "This process already has created a primary surface.\0";
case DDERR_REGIONTOOSMALL:
return "Region passed to Clipper::GetClipList is too small.\0";
case DDERR_SURFACEALREADYATTACHED:
return "This surface is already attached to the surface it is being attached to.\0";
case DDERR_SURFACEALREADYDEPENDENT:
return "This surface is already a dependency of the surface it is being made a dependency of.\0";
case DDERR_SURFACEBUSY:
return "Access to this surface is being refused because the surface is already locked by another thread.\0";
case DDERR_SURFACEISOBSCURED:
return "Access to surface refused because the surface is obscured.\0";
case DDERR_SURFACELOST:
return "Access to this surface is being refused because the surface memory is gone. The DirectDrawSurface object representing this surface should have Restore called on it.\0";
case DDERR_SURFACENOTATTACHED:
return "The requested surface is not attached.\0";
case DDERR_TOOBIGHEIGHT:
return "Height requested by DirectDraw is too large.\0";
case DDERR_TOOBIGSIZE:
return "Size requested by DirectDraw is too large, but the individual height and width are OK.\0";
case DDERR_TOOBIGWIDTH:
return "Width requested by DirectDraw is too large.\0";
case DDERR_UNSUPPORTED:
return "Action not supported.\0";
case DDERR_UNSUPPORTEDFORMAT:
return "FOURCC format requested is unsupported by DirectDraw.\0";
case DDERR_UNSUPPORTEDMASK:
return "Bitmask in the pixel format requested is unsupported by DirectDraw.\0";
case DDERR_VERTICALBLANKINPROGRESS:
return "Vertical blank is in progress.\0";
case DDERR_WASSTILLDRAWING:
return "Informs DirectDraw that the previous Blt which is transfering information to or from this Surface is incomplete.\0";
case DDERR_WRONGMODE:
return "This surface can not be restored because it was created in a different mode.\0";
case DDERR_XALIGN:
return "Rectangle provided was not horizontally aligned on required boundary.\0";
default:
return "Unrecognized error value.\0";
}
}