CK_ddEngine

CK_Object
   |
   +----CK_ddEngine

One instance of this object should be created at the beginning of an application. The engine creates the DirectDraw object, the DirectDraw rendering and primary surfaces, and DirectDraw clipper objects. The engine also creates the application's main window. The engine contains the main loop that is the core of the application. The main loop handles screen updates, Windows messages, timed events, and polling for DirectPlay messages.

The engine is capable of starting any application in either a full-screen mode, or a windowed mode. When starting in a windowed mode, the pixel depth of the display surface must be the same as that of the Windows desktop. In full screen mode, any pixel depth can be selected, regardless of the pixel depths of the graphics images used by the application, and regardless of the pixel depth of the desktop.

Full-screen applications can be minimized by pressing ALT-TAB.

All DirectDraw objects created by CK_ddEngine are fully accessible to applications via the CK_DirectDraw class.

Constructors

(The CK_ddEngine object must be created using the create() factory method.)

Factory Methods

create: Creates the CK_ddEngine object for the application.

Public Methods

cleanupMemory: Last function to call in an application. Cleans up all remaining memory that may have been used by the library. (v1.02)
deleteEngine: Deletes the application's CK_ddEngine object. (v1.02)
getLastMouseX: Returns the x screen coordinate of the mouse's last recorded location.
getLastMouseY: Returns the y screen coordinate of the mouse's last recorded location.
getWindow: Returns the handle of the application's main window.
initialize: To be called once and only once after the engine is created.
isMinimized: Returns TRUE if the application is currently minimized.
mainLoop: Runs the application's main loop.
setClassCursor (v1.02): Used to turn off the Windows cursor or to set a different black & white Windows cursor.
setDefaultCursor (v1.02): Sets the default cursor for the application.
setMaxFrameRate: The application can tell the engine that frame rates beyond this are not necessary.
setPollCallback: Allows the application to provide a callback that gets called on each iteration in the main loop.
setSurfaceScenario: Sets the rendering/bltting/flipping scheme to be used by the engine.
setWaitForMessages: The application can have the engine enter a wait state in the main loop when there is nothing to do.
setWindowClassName: The window class can be set by calling this before calling initialize().
setWindowStyle: The window style can be set by calling this before calling initialize().
setWndProc: Allows the application to provide a callback to receive Windows messages.
shutdown: This is called to tell the engine to shutdown the application and exit the main loop.
toFullScreen (v1.02): Switches the display to full-screen mode, also optionally changing the resolution and pixel depth.
toWindow (v1.02): Switches the display to a window on the desktop, also optionally changing the resolution of the window.

static CK_ddEngine &create(const char *windowTitle, int xRes, int yRes, int bitsPerPixel, int startWindowed);

This factory method is used to create the Chilkat DirectDraw engine for the application.

Return Value

Returns a reference to the engine.

Parameters

windowTitle

For windowed applications, this is the text that will appear in the title bar of the main window.

xRes

The resolution of the application's main window in the X direction. (The width of the window)

yRes

The resolution of the application's main window in the Y direction. (The height of the window)

bitsPerPixel

The pixel depth of the application's display surface. For windowed applications, this parameter is actually igored and the pixel depth is forced to match the pixel depth of the desktop. All applications using the library can run at any pixel depth without changing any code, except for the value of this parameter.

startWindowed

If TRUE, then the application will run in a window. If FALSE, the application will run in full screen mode. Any application can run windowed or full screen. Nothing in the application's code needs to be changed except for the value of this parameter when creating the engine.

Remarks

An application using the Chilkat SDK can run at any pixel depth, regardless of the original pixel depth of the artwork incorporated. See CK_Image and CK_Bitmap to find out why.

static void cleanupMemory(void);

Frees all remaining memory used by the library. This should be called last after the engine has shutdown, after the mainloop has exited, and after calling CK_ddEngine::deleteEngine. After calling this function, the library should have cleanup all every bit of memory it might have allocated.

static void deleteEngine(void);

Deletes the application's CK_ddEngine. This can be called after shutdown is called and the mainloop has exited. It is not required to be called.

int getLastMouseX(void) const;

Returns the last recorded X-position of the mouse.

int getLastMouseY(void) const;

Returns the last recorded Y-position of the mouse.

HWND getWindow(void) const;

Returns the handle of the application's main window.

BOOL initialize(HINSTANCE hInstance, int nCmdShow);

Must be called after the engine is created using the create() factory method. This method creates the DirectDraw object, surfaces, and clippers. The application's main window is also created. This window can be obtained by calling the getWindow() method. If necessary, all DirectDraw objects created by the engine are accessible from the CK_DirectDraw class.

Return Value

Returns TRUE if the initialization succeeded. Otherwise returns FALSE, which is returned if any of the DirectDraw objects couldn't be created, or if the main window could not be created.

Parameters

hInstance

The current instance of the application. This is the first argument to WinMain, as shown in the example below.

nCmdShow

The show state of the window. This is the fourth argument to WinMain, as shown in the example below.

Example
	int PASCAL WinMain( HINSTANCE hInstance, HINSTANCE hPrevInstance,
		LPSTR lpCmdLine, int nCmdShow)
    		{
    		CK_ddEngine &engine = CK_ddEngine::create("Example1",
			640,480,16,FALSE);
	
    		BOOL status = engine.initialize(hInstance,nCmdShow);
    		if (!status)
			{
			printf("engine initialization failed\n");
			return 0;
			}

int isMinimized(void) const;

Returns TRUE if the application's window is currently minimized. Otherwise returns FALSE.

void mainLoop(void);

This member function runs the application's main loop. The main loop handles Windows messages, screen updates, and timed events. The mainLoop returns when the shutdown() method is called.

The main loop will do the following on each iteration:

Check for Windows messages.

Check for screen updates - possibly updating the render surface and bltting to the display surface.

Check for timed events that have expired (CK_Event).

Make a polling callback if the user has defined one using setPollCallback().

void setClassCursor(HCURSOR cursor);

This function should be called to turn off the Windows cursor if a custom cursor is set using setDefaultCursor. Otherwise it can be called to set an alternate Windows cursor. If animated or color cursors are desired, the application should use the custom cursor functions (setDefaultCursor) provided by the library. Color Windows cursors will flicker in a windowed application because Windows and the application are both updating the same primary surface.

Parameters

cursor

Setting this to zero will turn off the class cursor for the application. This is the most common use for this function.

Example
	int PASCAL WinMain( HINSTANCE hInstance, HINSTANCE hPrevInstance,
		LPSTR lpCmdLine, int nCmdShow)
    		{
    		CK_ddEngine &engine = CK_ddEngine::create("Example1",
			640,480,16,FALSE);
		// Always do this if we are using custom cursors.
		// Call this before engine initialization.
    		engine.setClassCursor(0);

    		BOOL status = engine.initialize(hInstance,nCmdShow);
    		if (!status)
			{
			printf("engine initialization failed\n");
			return 0;
			}

void setDefaultCursor(const CK_Cursor *cursor);

A default custom cursor for the application can be set by calling this function. Custom cursors set for a screen (CK_Screen::setCursor) or for a component via the CP_Cursor property have precedence if the mouse pointer is within the given component or the given screen is active.

If this function is called, the setClassCursor function should be called with an argument of 0 before engine initialization. This function can be called at anytime, before or after engine initialization.

Cursors must be 64x64 pixels or less in size.

Parameters

cursor

Points to a CK_Cursor object, which is just a container for a CK_Bitmap and x,y coordinates for the hotspot.

void setMaxFrameRate(int maxRate);

This function is used to tell the engine the maximum number of times per second that it should check for dirty rectangles that need to be bltted to the display surface. By default, the engine allows a maximum of 30 frames per second. When this number is lower, more dirty rectangles will accumulate before bltting the next set of dirty rectangles from the render surface to the display surface. When this number is higher, it is possible for the blts to happen more frequently.

In most cases, this function will not need to be called.

void setPollCallback(CK_Callback *pollCB);

This function tells the engine to make a callback on each iteration in the main loop. The engine will call pollCB->callback() on each iteration.

The user must define a class that "mixes-in" (i.e. inherits) the CK_Callback class, and defines the callback function. The poll callback is typically used to allow for the polling of network (DirectPlay) messages in multi-player games.

void setSurfaceScenario(int scenario);

This function tells the engine which surface scenario to use. Currently, the CK_ddEngine class is capable of running any of three different surface scenarios. An enumeration (SurfaceScenarios) is defined in CK_ddEngine that lists them. They are:

Sysmem_to_Display

Rendering is done in an offscreen surface in system memory that has the same pixel format as the display surface. Each frame is bltted directly from the render surface to the display surface. The display surface (in video memory) is not a complex surface (i.e. there are no back buffers) and there is no flipping involved. This is the default surface scenario used by the engine, and for windowed applications, this is the only surface scenario allowed.

Sysmem_to_Back

Rendering is done in an offscreen surface in system memory that has the same pixel format as the display surface. The display surface (in video memory) has one back buffer. Each frame is bltted to the back buffer. The back buffer is then 'flipped' and becomes the visible surface.

Back_to_Display

Rendering is performed directly onto the back buffer of the display surface (in video memory). The back buffer is the flipped to become the visible surface.

The library developers may add additional surface scenarios based on user feedback. Particularly, scenarios using flipping chains (multiple back buffers) can be added in a future version.

void setWaitForMessages(void);

This tells the engine that when there is nothing to do, the process should enter a wait state until a Windows message arrives, or until a timed event expires. By default, the engine runs a continuous loop and will consume CPU cycles by continually checking for work to do. If a polling callback is used (setPollCallback) then this function should probably not be called since polling would not be occuring while the processor is in a wait state.

void setWindowClassName(const char *className);

If desired, this must be called before the engine is initialized. The engine uses this class name internally when regestering the window class (RegisterClass), and creating the window (CreateWindow).

void setWindowStyle(DWORD windowStyle);

If desired, this must be called before the engine is initialized. The engine uses this for the window style parameter to the CreateWindow function when creating the main window. By default, the engine will use the following window style unless overridden by this function: WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS_BORDER | WS_MINIMIZE_BOX | WS_MAXIMIZE_BOX.

void setWndProc(CK_WndProc *wproc);

This function tells the engine to make a callback for each Windows message received. The engine will call wproc->wndProc() for each Windows message received, and before the Chilkat engine gets a chance to handle the message. If it is desired that the Chilkat engine not see the Windows message, wproc->wndProc() should return FALSE. Otherwise it should return TRUE, and the Chilkat engine will process the message as normal.

The user must define a class that "mixes-in" (i.e. inherits) the CK_WndProc class, and defines the wndProc function.

void shutdown(void);

The shutdown function is called to tell the engine to break out of the main loop and destroy the DirectDraw objects. This causes CK_ddEngine::mainLoop() to return. An application should exit the program after mainLoop() returns.

void toFullScreen(int xRes, int yRes, int bitsPerPixel);

This function will switch the mode to full-screen, if it wasn't already. The resolution and pixel depth can also be changed by setting new values for xRes, yRes, and bitsPerPixel. To switch to full-screen mode without changing either the resolution or pixel depth, set all parameters to zero.

Important: If you change the pixel depth, the application is responsible for reloading all graphics. The library does not keep track of the images used by the application and does not automatically convert them to the new pixel format.

Parameters

xRes

The new width in pixels of the screen. Passing 0 will cause the width to remain unchanged.

yRes

The new height in pixels of the screen. Passing 0 will cause the height to remain unchanged.

bitsPerPixel

The new pixel depth of the application's display surface. Passing 0 will cause the pixel depth to remain unchanged.

Remarks

This function deletes an recreates the DirectX surfaces. If your application keeps a pointer to one of the DirectX surfaces created by the library, it should refetch it using the CK_DirectDraw class.

void toWindow(int xRes, int yRes);

This function will switch the display so the application is running in a window on the desktop, if it wasn't already. The resolution (dimensions of the window) can also be changed by setting xRes and yRes. Passing zero values for both parameters will keep the current resolution. When running in windowed mode, the application must run in the same pixel format as the desktop, therefore there is no parameter for setting the bits-per-pixel.

Important: If the pixel format changes, the application is responsible for reloading all graphics. The library does not keep track of the images used by the application and does not automatically convert them to the new pixel format.

Parameters

xRes

The new width in pixels of the window. Passing 0 will cause the width to remain unchanged.

yRes

The new height in pixels of the window. Passing 0 will cause the height to remain unchanged.

Remarks

This function deletes an recreates the DirectX surfaces. If your application keeps a pointer to one of the DirectX surfaces created by the library, it should refetch it using the CK_DirectDraw class.

CK_ddEngine

Constructors

Factory Methods

Public Methods

static CK_ddEngine &create(const char *windowTitle, int xRes, int yRes, int bitsPerPixel, int startWindowed);

Remarks

static void cleanupMemory(void);

static void deleteEngine(void);

int getLastMouseX(void) const;

int getLastMouseY(void) const;

HWND getWindow(void) const;

BOOL initialize(HINSTANCE hInstance, int nCmdShow);

int isMinimized(void) const;

void mainLoop(void);

void setClassCursor(HCURSOR cursor);

void setDefaultCursor(const CK_Cursor *cursor);

void setMaxFrameRate(int maxRate);

void setPollCallback(CK_Callback *pollCB);

void setSurfaceScenario(int scenario);

void setWaitForMessages(void);

void setWindowClassName(const char *className);

void setWindowStyle(DWORD windowStyle);

void setWndProc(CK_WndProc *wproc);

void shutdown(void);

void toFullScreen(int xRes, int yRes, int bitsPerPixel);

Remarks

void toWindow(int xRes, int yRes);

Remarks