Yaroslav Goncharov (yaroslav@softspb.com), February 28, 2003.
Introduction
The most important aspect of game development is a high-performance graphic interface. Ideally, this interface should grant exclusive direct access to the video frame buffer memory. Fortunately, there is a Game API (GAPI), a high-performance game development interface for Microsoft Windows CE-based devices.
For fast drawing GAPI provides an exclusive access to video frame buffer memory. However, it will take a significant time to write even a simple application using plain GAPI. There are 2 main problems:
The video frame buffer depends on underlying hardware; therefore you need to understand the buffer structure for each target device.
You cannot use standard GDI routines directly with GAPI. For example, you will need to implement your own BitBlt function.
Because of these 2 reasons, standard bitmap (HBITMAP) drawing will be a several screens of code.
The STGapiBuffer class provides a powerful interface to the display buffer and hides hardware specifics. This class provides a high-performance version of GDI primitives - the most important thing for a game developer. The interface is transparent for a developer and does not hide any key GAPI calls. This fact, together with open source code, makes this class easy to use and leave full control of application logic for a developer. STGapiBuffer does not use MFC; therefore, it can be also used on Smartphone 2002 platform. STGapiBuffer is developed by Spb Software House and is free for commercial use.
This article describes STGapiBuffer library and gives code snippets for most common drawing needs.
Download
Native graphic data format
In a typical GAPI application lots of frames use the same images and colors. For example, it means that an image can be drawn several times during a second. It takes significant time to draw a device independent bitmap on the display buffer (you need to get access to the underlying byte array and convert color for each pixel). Color conversion from 24bpp (COLORREF) to a native color takes some time and this is unacceptable since you will need to perform this operation for almost each display pixel.
Therefore, the only way to achieve the maximum performance is to convert images and graphics to the native display format before drawing them. Because of these reasons STGapiBuffer drawing methods take data only in the native format. CreateNativeBitmap and GetNativeColor methods should be used for conversion to the native format.
Installation and initialization
GAPI with STScreenBuffer installation and initialization is very similar to plain GAPI. You can follow the instructions given in this article except for the following points:
You also need to install STGapiBuffer class. Simply extract STGapiBuffer.h and STGapiBuffer.cpp to your project folder and add these files to the project.
Once you have obtained a pointer to the display buffer from GXBeginDraw, you don't need to access it directly as described in the mentioned article. Pass this pointer to the STGapiBuffer instance and use its drawing methods. The following code snippet shows this technique.
...
// CSTGapiBuffer instance can be glabal, local or member of your class
CSTGapiBuffer g_gapiBuffer;
// you can create a native bitmap from HBITMAP
// using CSTGapiBuffer::CreateNativeBitmap
CNativeBitmap* g_pNativeBitmap = NULL;
...
void DrawFrame()
{
// Get a pointer to the display buffer and pass a pointer to the wrapper
void* pDisplayBuffer = GXBeginDraw();
g_gapiBuffer.SetBuffer(pDisplayBuffer);
g_gapiBuffer.BitBlt(0, 0, 100, 100, g_pNativeBitmap);
GXEndDraw();
}
Drawing bitmaps
The main method to draw bitmaps is CSTGapiBuffer::BitBlt. This method has almost the same parameters as the BitBlt API function. Don't forget that all CSTGapiBuffer drawing methods take data in the native format. You will need to convert your bitmaps to the native format; you have to do it only once. For example, to complete the previous snippet you need to create a native bitmap in InitInstance function and delete it in ExitInstance function.
BOOL InitInstance()
{
...
HBITMAP hBitmap = SHLoadDIBitmap(_T("\\image.bmp"));
g_pNativeBitmap = g_gapiBuffer.CreateNativeBitmap(hBitmap);
::DeleteObject(hBitmap);
...
}
int ExitInstance()
{
delete g_pNativeBitmap;
...
}
If you need to draw a full screen bitmap (e. g. background) you should create a memory-based GAPI buffer, draw a native bitmap in this memory buffer and then draw this buffer in your frame drawing code. In this case you will draw a bitmap in one memcpy call. See the sample application for implementation details.
Drawing transparent bitmaps
The library offers 2 techniques to draw transparent bitmaps (sprites): a traditional masked bits transfer and a technique connected with the transparent color.
The masked bits transfer is implemented by CSTGapiBuffer::MaskedBlt method that has parameters similar to MaskedBlt API function.
The transparent color technique does not require an additional mask bitmap for each sprite. This method is comfortable to use with simple sprites when you can guarantee that transparent color is not used in the main image.
Drawing custom shapes
There are several methods for drawing custom shapes. CSTGapiBuffer::SetPixel can be appropriate for tiny graphic objects. For bigger object there is a set of inline methods that use the conception of the current position. This set of methods does not have overheads that are essential for the SetPixel method and for most shapes it has the same perfomance as direct buffer manipulations. For example, you can use this set of methods to draw filled regions, horizontal and vertical lines.
Off-screen buffer
Most games use the off-screen buffer technique to implement high quality flickering-free animation. With this technique you should draw each frame to the memory buffer first and then transfer the whole image from the memory buffer to the display.
To implement off-screen buffer with GAPI you can use STGapiBuffer, a wrapper for a memory buffer, use its methods to draw in the memory and then transfer the whole frame from the memory buffer to the display buffer with one memcpy call. Use STGapiBuffer::CreateMemoryBuffer to create a memory buffer and CSTGapiBuffer::BitBlt(const CSTGapiBuffer *pMemoryBuffer) to copy a memory buffer to the display.
You can find a code snippet for this technique in the sample application.
Support information
STGapiBuffer supports Pocket PC 2000, Pocket PC 2002 and Smartphone 2002 platforms.
The current version of the library does not support 4bpp gray-scale and 8bpp indexed color.
Conclusion
GAPI is very powerful interface for high-performance drawing applications. However, it can be time consuming to start using the plain GAPI. With STGapiBuffer a developer gets interface to a GAPI buffer that is very similar to standard Windows GDI functions; therefore it does not require additional time for learning and a developer does not have to reinvent common drawing functions.
Related resources:
http://www.pocketpcdn.com/sections/gapi.html
Section: GAPI
http://www.pocketpcdn.com/libraries/stgapibuffer.html
Library: STGapiBuffer
http://www.pocketpcdn.com/libraries/gapidraw.html
Library: GapiDraw
http://www.pocketpcdn.com/libraries/easyce.html
Library: EasyCE
http://www.pocketpcdn.com/libraries/gapiemulation.html
Library: GAPI for Emulator
http://www.pocketpcdn.com/libraries/pocketgl.html
Library: Pocket GL (iPAQ and Cassiopeia)
http://www.pocketpcdn.com/libraries/gapitools.html
Library: GapiTools
http://www.pocketpcdn.com/libraries/aspritece.html
Control: ASpriteCE Game Control
http://www.pocketpcdn.com/articles/gapidraw.html
Article: GapiDraw from a DirectDraw developers perspective
http://www.pocketpcdn.com/articles/gapidraw2.html
Article: Creating a new project with GapiDraw
http://www.pocketpcdn.com/articles/dieselengine2.html
Article: Programming DieselEngine 2. Using Diesel3D
http://www.pocketpcdn.com/articles/dieselengine1.html
Article: Programming DieselEngine 1. Close up and personal with DieselEngine, Using DieselGraphics
http://www.microsoft.com/mobile/developer/technicalarticles/gameapi.asp
Article: Getting Started with the Game API
http://www.microsoft.com/mobile/developer/technicalarticles/gapi.asp
Article: Here Comes GAPI!
http://pocketmatrix.com/phantom/tutorial1.htm
Article: PocketPC Advanced Graphics & Games Programming Tutorial. Part 1 - Getting started with EasyCE
http://pocketmatrix.com/phantom/tutorial2.htm
Article: Pocket PC Advanced Graphics & Games Programming Tutorial. Part 2 - Advanced tricks with pixels
http://pocketmatrix.com/phantom/tutorial3.htm
Article: Pocket PC Advanced Graphics & Games Programming Tutorial. Part 3 - Pixel warps and displacement tables
http://pocketmatrix.com/phantom/tutorial4.htm
Article: Pocket PC Advanced Graphics & Games Programming Tutorial. Part 4 - Buffers, pointers and sprites
http://pocketmatrix.com/phantom/tutorial5.htm
Article: Pocket PC Advanced Graphics & Games Programming Tutorial. Part 5 - Rotozooming and fixed point arithmetic
http://www.pocket-g.com/prx/sprite.html
Article: Sprite
http://www.pocket-g.com/prx/animation.html
Article: Animation
http://www.pocket-g.com/prx/timer.html
Article: Timer call back
http://www.pocket-g.com/prx/bckgnd.html
Article: Scrolling background
http://www.pocket-g.com/prx/collision.html
Article: Object collision
http://www.pocket-g.com/prx/offscreen.html
Article: Off-screen technique
(Yaroslav Goncharov) |
