DDraw Interface

Describes the DDrawInterface and all its constants

Summary

DDraw Interface	Describes the DDrawInterface and all its constants
Enumerations
DDRAW_SURFACEFLAG_TYP	Used when calling DDrawInterface::CreateSurface
DDRAW_STATE_TYP	Describes the state of the DDrawInterface
Macros
DD_CLR	Clears out a DirectDraw structure and sets the dwSize member
DDrawInterface	Controls DirectDraw and provides a common interface to all of its functions.
Contructors
DDrawInterface	Attempts to query an IDirectDraw7 interface and initialize it for use.
~DDrawInterface	Does nothing except keep track of an internal count of created classes
Display Functions	All the functions that setup and maintain the display.
EnumDisplayModes	Enumerates the valid display modes for the device
InitDisplay	Initializes the display for rendering.
RestoreDisplay	Restores the display back to initialized settings.
ResizeBackBuffer	Resizes the back buffer in the interface to match the window after a resize.
ShutdownInterface	Shutdown the interface.
Utility Functions
WaitForVerticalBlank	Waits for the Vertical Blank to begin, then returns
CreateClipper	Creates a clipper object using the provided parameters.
CreateSurface	Creates a surface using the provided parameters.
Accessor Functions
getState	Returns the current state of the interface
TestState	Tests the interface and makes adjustments to the state as neccessary
getDDraw	Grabs the main DDraw inerface pointer.
getBackBuffer	Get the interface to the main BackBuffer.
getPrimaryBuffer	Get the interface to the Primary Buffer.
Exception Classes
xDDrawCreateFailed	Throws when unable to query an interface to IDirectDraw7
XDDrawEnumFailed	Throws when unable to enumerated the display modes
xDDrawBadMode	Throws when attempting to initialize into a display mode that is not valid

Enumerations

DDRAW_SURFACEFLAG_TYP

Used when calling DDrawInterface::CreateSurface

DDRAW_SURFACEFLAG_VIDMEM	Video Memory
DDRAW_SURFACEFLAG_SYSMEM	System Memory
DDRAW_SURFACEFLAG_WRITEONLY	Surface is WriteOnly
DDRAW_SURFACEFLAG_READONLY	Surface is optimized for reads. This sets NONLOCALVIDMEMORY in the creation flags

DDRAW_STATE_TYP

Describes the state of the DDrawInterface

DDRAW_CLEAN	A clean state means that nothing has been done yet
DDRAW_ERROR	There has been an unrecoverable error
DDRAW_INVALID	The DDraw Interface pointers are no longer valid
DDRAW_EXIT_FULLSCREEN	Temporary state while beginning to exit fullscreen mode
DDRAW_RESTORE	Ready to restore the DDrawInterface
DDRAW_WAIT	Not yet ready to retore the DDrawInterface
DDRAW_READY	Ready and initialized

Macros

DD_CLR

Clears out a DirectDraw structure and sets the dwSize member

DD_CLR(x)   memset(&(x),0,sizeof(x)); (x).dwSize=sizeof(x);

Parameters

x	This is the structure name that you want to be cleared

DDrawInterface

class DDrawInterface

Controls DirectDraw and provides a common interface to all of its functions. Mainly used by startup to setup of the window and maintain a working runtime environment.

Summary

Contructors
DDrawInterface	Attempts to query an IDirectDraw7 interface and initialize it for use.
~DDrawInterface	Does nothing except keep track of an internal count of created classes
Display Functions	All the functions that setup and maintain the display.
EnumDisplayModes	Enumerates the valid display modes for the device
InitDisplay	Initializes the display for rendering.
RestoreDisplay	Restores the display back to initialized settings.
ResizeBackBuffer	Resizes the back buffer in the interface to match the window after a resize.
ShutdownInterface	Shutdown the interface.
Utility Functions
WaitForVerticalBlank	Waits for the Vertical Blank to begin, then returns
CreateClipper	Creates a clipper object using the provided parameters.
CreateSurface	Creates a surface using the provided parameters.
Accessor Functions
getState	Returns the current state of the interface
TestState	Tests the interface and makes adjustments to the state as neccessary
getDDraw	Grabs the main DDraw inerface pointer.
getBackBuffer	Get the interface to the main BackBuffer.
getPrimaryBuffer	Get the interface to the Primary Buffer.
Exception Classes
xDDrawCreateFailed	Throws when unable to query an interface to IDirectDraw7
XDDrawEnumFailed	Throws when unable to enumerated the display modes
xDDrawBadMode	Throws when attempting to initialize into a display mode that is not valid

Contructors

DDrawInterface

DDrawInterface()

Attempts to query an IDirectDraw7 interface and initialize it for use.

Throws

xDDrawCreateFailed if unable to find IDirectDraw7.

~DDrawInterface

~DDrawInterface()

Does nothing except keep track of an internal count of created classes

Display Functions

All the functions that setup and maintain the display. The modes are put into the control in the window provided and are enumerated into the following format.

Mode: WidthxHeightxBpp Hz

EnumDisplayModes

int EnumDisplayModes( const HWND hwnd,
const int rcResource ) const

Enumerates the valid display modes for the device

Parameters

hwnd	HWND The window that will receive the display modes
rcResource	INT The control ID of the control that will be filled

Returns

False if successful, error code otherwise

Throws

<xDDrawEnumFailed> If unable to find any valid modes

InitDisplay

int InitDisplay()

Initializes the display for rendering. It uses the information from CStartup to determine how to setup the mode.

Returns

False if successful, errorcode otherwise.

RestoreDisplay

int RestoreDisplay()

Restores the display back to initialized settings. Do not use for changing Fullscreen to Windowed or it will crash.

Returns

False if successful, error code otherwise.

Throws

xDDrawBadMode if unable to use the specified display mode options in CStartup

ResizeBackBuffer

static int ResizeBackBuffer()

Resizes the back buffer in the interface to match the window after a resize. This should not be used in Fullscreen mode or there will be problems!

Returns

False if successful, error code otherwise

Throws

xDDrawBadMode if unable to use the specified display mode options

ShutdownInterface

static void ShutdownInterface()

Shutdown the interface. It will close all handles and release all memory that it has allocated. It will put the interface into DDRAW_CLEAN

Utility Functions

WaitForVerticalBlank

void WaitForVerticalBlank( void ) const

Waits for the Vertical Blank to begin, then returns

CreateClipper

LPDIRECTDRAWCLIPPER CreateClipper( const int num_rects,
const LPRECT clip_list ) const

Creates a clipper object using the provided parameters. It must be released before a device restore or shutdown.

Parameters

num_rects	INT This is the number of rectangles defined in the clip_list
clip_list	LPRECT This is a pointer to an array of rectangles equal to num_rects

Returns

LPDIRECTDRAWCLIPPER with the provided parameters. NULL if unsuccessful

CreateSurface

LPDIRECTDRAWSURFACE7 CreateSurface(
    const int width,
    const int height,
    const DWORD mem_flag = DDRAW_SURFACEFLAG_SYSMEM,
    const int bpp = 0
) const

Creates a surface using the provided parameters. It must be released before a device restore or shutdown.

Parameters

width	INT The width of the surface
height	INT The height of the surface
mem_flag	DWORD DDRAW_SURFACEFLAG_TYP flags describing how to store the surface in memory. Defaults to DDRAW_SURFACEFLAG_SYSMEM.
bpp	INT Specifies the bits per pixel to use for the surface. Defaults to 0 which will match the backbuffer’s bpp.

Returns

LPDIRECTDRAWSURFACE7 with the provided parameters. NULL if unsuccessful

Accessor Functions

getState

static DDRAW_STATE_TYP getState()

Returns the current state of the interface

Returns

DDRAW_STATE_TYP with the current state

TestState

static DDRAW_STATE_TYP TestState()

Tests the interface and makes adjustments to the state as neccessary

Returns

DDRAW_STATE_TYP with the determined state

getDDraw

const LPDIRECTDRAW7 getDDraw( void ) const

Grabs the main DDraw inerface pointer. This will need to be encapsulated into a checkout class to avoid problems with exceptions and thread safety issues.

Returns

LPDIRECTDRAW7 for the current running mode. NULL if none exists yet. (which would be an assertion error)

getBackBuffer

const LPDIRECTDRAWSURFACE7 getBackBuffer( void ) const

Get the interface to the main BackBuffer. This should be put into a checkout class to avoid problems.

Returns

LPDIRECTDRAWSURFACE7 of the current back buffer. NULL if errors.

getPrimaryBuffer

const LPDIRECTDRAWSURFACE7 getPrimaryBuffer( void ) const

Get the interface to the Primary Buffer. This should be put into a checkout class to avoid problems.

Returns

LPDIRECTDRAWSURFACE7 of the primary buffer. NULL if errors.

Exception Classes

xDDrawCreateFailed

Throws when unable to query an interface to IDirectDraw7

class xDDrawCreateFailed : public std::exception

XDDrawEnumFailed

Throws when unable to enumerated the display modes

class xDDrawEnumFailed : public std::exception

xDDrawBadMode

Throws when attempting to initialize into a display mode that is not valid

class xDDrawBadMode : public std::exception