PocketFrog guide chapter 1

What is PocketFrog Simply put PocketFrog is a Windows CE game development toolkit which gives you a set of tools to access the PocketPC's screen in a fast and device independent way. PocketFrog provides some graphics 'primitives' such as line & rectangle functions together with PocketPC button & screen tap handling. By looking after the low level stuff PocketFrog lets the game programmer get on with game design without the need to be concerned about the hardware too much. This toolkit is the work of Thierry Tremblay

What does it do PocketFrog looks after all the basics of setting up GAPI and creating screen buffers as well as providing many of the most commonly used graphics functions such as line, circle, rectangle, pixel and similar functions. Existing Windows CE GDI functions can also be used. It handles differences between hardware for you saving lots of extra coding.

Note: GAPI is a set of functions to give direct access to the PocketPC's screen allowing game's programmers to ignore regular windows. This gives the games programmer 2 important things, 1 performance & 2 a clean sheet to create their own game interface on. You lose out on all the built-in Windows functions like dialogue boxes and control sliders etc but most games do their own thing in these areas anyway as part of making the game an immersive experience. Here is a link to Microsoft's GAPI download page
http://www.microsoft.com/mobile/developer/downloads/gapi.asp (please report broken links) Note: Microsoft may change their links so if you get a broken link go to Microsoft.com & search.

What doesn't it do PocketFrog does not include built-in sprite functionality nor does the toolkit provide a sound library ( on the grounds that these features are readily available elsewhere ). Also it does not have any screen based input of characters such as the SIP keyboard used in regular windows applications.

How do I use it Firstly you need to download and install the Microsoft embedded toolkit with eVC++ 3. This toolkit comes in CD form and as a download. Following the initial release of the embedded toolkit a number of additional software development kits (SDK's) were released including Handheld PC 2000 and PocketPC 2002 and Windows Mobile 2003. Note: I suggest you ignore the .NET related software (eVC++ 4) from Microsoft as this is not really used for games at present. Here's a link to Microsoft's Windows Mobile developer's site:-
Visual C++ Development Tools Pages (please report broken links) Follow the resources / downloads / developer link for the tools.

Microsoft's toolkit comes with CE device emulators to allow on-PC development without downloading to a PocketPC and PocketFrog supports the PPC and PPC2002 emulators on PC. You can also use VC++6 instead of the embedded toolkit. More about PocketFrog's emulation support in a later chapter.

Once you have installed the embedded toolkit you need to download and unzip the latest version of PocketFrog . Assuming you have installed eVC into C:\Windows CE Tools you should create a folder to hold PocketFrog something like C:\Windows CE Tools\frog. As the PocketFrog toolkit is constantly evolving you will soon have a collection of sub-folders by version number. Also on the PocketFrog download pages you will find STLPort. Download & unzip this into a folder within your Frog setup. You should not need this unless you are going to rebuild the PocketFrog toolkit but you should get it just in case.

Within the current release folder ( as of May 2004 version 0.7 ) there is a folder called Make and in this folder you will find the PocketFrog workspace file (which includes several sample applications including Blit, Plasma and Rotate, Hekkus & SuperSample) and the PocketFrog toolkit. Double-click on the workspace file to open it with eVC++

Note: If you have never used Visual C++ or are totally new to C++ you will need to allow some time to understand the Microsoft tools and C++ as well as using PocketFrog and writing your game. It's impossible to gauge how much time as some people ( me included ) take a long time to absorb material & other just soak it up but you must assume you will have a learning curve and will make lots of mistakes. Don't let any of these frustrations get you down as you will eventually win through & start understanding it all.

Unlike it's big brother Visual C++ 6 eVC allows the code to be built for different device types. In the example below the Blit sample is being built for a PocketPC with an ARM processor in release mode. You can also build in debug mode which stores lots of extra information with the compiled program to allow debugging to work. If you were building for the PC-based emulator it would be necessary to change the settings shown.

It's unlikely that the very first time you try to compile and link a program ( ie: build ) that everything will work. There are quite a few eVC settings which could be wrong one of which is the locations to be searched for dependant files. The screen shot to the right shows the tools / options menu with the directories tab selected. In here you set which folders the compiler / linker looks in for all the related parts of the project. You should follow all the installation advice from the main PocketFrog pages and in the download and also check the PocketFrog message board for solutions to errors found. You can add directories & move them up & down to affect the search order. Note: These settings need to be defined for each platform type. ensure STLport is at the bottom of the list for PPC2002 to build correctly

The build menu within eVC allows you to compile and link the enclosed Blit sample. If everything is installed correctly and all dependancies are set up you should see no errors, possibly a few warnings & if you are working with a connected PocketPC then activesync should start & download the Blit sample to the device. The default settings put the demo on the start menu.

Be aware that I'm not trying to teach you how to use the eVC environment as that would need a couple of dozen lessons. The eVC system comes with lots of help and quite a few books on the use of VC++6 & eVC++3 exist.

If you do get compiler or linker problems & can't figure out what's wrong then post on the forum to get help. Remember to give accurate details of the problem.

By now you should be in a position to open up the PocketFrog project and build the blit sample. You should also be able to download this & run it on the PocketPC. I will deal with using the emulator and creating your own project later. For now lets look at the code to understand it and make some fun changes to the Blit sample to begin learning about the toolkit.
note: with the release of version 0.5.2 the Blit sample includes more of interest than included below. I will update this article later

class MyGame : public Game makes your own game class 'MyGame' based on the class 'Game' defined in the PocketFrog project so MyGame has all sorts of capabilities which it inherits from it's parent class.. You can find the Game class in the framework folder as game.cpp if you want to examine it.

m_config.orientation = ORIENTATION_WEST; The m_config structure contains some variables including screen orientation. In PocketFrog NORTH is normal Portrait mode while WEST is the regular landscape mode with the left edge coming from the bottom of the screen.
m_config.splashScreenTime = 2000; Set this value to control how long the PocketFrog splash screen appears for. Set it to 0 and you won't see the screen.
There are other config options:-
m_config.desktopZoom = 2; used with builds for Windows PCs to draw a zoomed window.
m_config.frameRate = 30; used to control the frame-rste of your game for smooth animations.

MyGame has a pre-defined initialize function virtual bool GameInit() and here you can see the images used in the Blit sample being 'loaded' into the game as 'surfaces' called m_images[] 1 through 4. These images are bitmaps which are loaded into the project as a resource.
The background beach jpg picture is loaded with m_background = LoadImage( display, IDR_IMAGE1 );

m_images[i]->SetColorMask( Color( 255, 255, 255) ); sets the transparent color of the images. A negative number disables the transparency. Note: For most graphics the background color is not drawn so that the backdrop shows through.

The game loop virtual void GameLoop() sets up the display device 'display' which has a number of built-in functions some of which are used in the Blit game loop. eg: display->Clear(Color( 255, 255, 255 ) ); which clears the 'screen' you are drawing on (not the screen being displayed) and display->Blit( x, y, m_images[i] places an image onto the display at random x,y positions. Note the use of GetWidth() and GetHeight() for both display and the m_images[] items.

The 4 pictures are moved around based on screen dragging with the stylus. The built-in PocketFrog functions Stylus_Down() Stylus_Up() and Stylus_Move() are called by the game internals when these events happen allowing you to deal with Stylus actions.
The locations of the images are restricted by the code to stay fully on-screen but otherwise you can move them anywhere. One of the really cool built-in features on view here is if (m_position[i].Contains( stylus )) The m_position[] array items are Rect's which identify where the 4 images are on screen. The Contains function determines whether the stylus is inside the given rectangle. There are lots of uses for this feature. Rect is a built-in PocketFrog feature not to be confused with RECT (C++).

nb: In a similar way the Button_up() & Button_Down() functions deal with the real buttons built-in to the PocketPC device. The Button functions are not used in Blit at present.

Now a few words about the Color() function and the Pixel data type. Most PocketPCs have a color resolution of 65535 colors and to achieve this range each screen pixel needs 16 bits to hold the combined red, green & blue data. The 16 bits are normally divided up into 5 6 5 or 5 bits for red, 6 for green & 5 for blue. The Pixel data type is a 16 bit integer into which the 3 colors are placed. To make this easier the Color() function takes 3 separate values & stuffs them into the Pixel variable in the correct place but you could do all that shifting yourself. See defs.h for more info.

Try adding some additional graphics display->DrawCircle(120,160,,80,Color(255,0,0) ); Draws a red circle.
DrawCircle accepts (Point, int radius, Pixel) or (int x, int y, int radius, Pixel).
Note: that you can find the various options for display just by typing in a line beginning display-> as eVC will drop down a list of possible options including DrawRect DrawLine etc. Remember that the game loop happens continuously so this is where your main game control code will go.

To slow down the Blit sample try inserting the C function Sleep(150); after display->Update();
This is not how you would pace your game code for real as it does not take different speed devices into account. PocketFrog incorporates a frame rate feature which ensures a steady display rate.

The Update() command sends all of the graphics you drew in the game loop to the screen. Until the update happens the screen is unchanged.

Well that about wraps up this first look at PocketFrog. The next chapter will introduce several more built-in features of the toolkit such as reading the screen taps and hard buttons and demonstrate the basics of sprite animation.

You may want to check out the following interesting though out of date article by Thomas Connolly with input from Thierry Tremblay, author of PocketFrog CODE GURU ARTICLE (the source code mentioned is no longer available)
(please report broken links)

disclaimer: This article is the work of Conan of SundialSoft, a user of PocketFrog. I, Conan, have no connection with the toolkit author Thierry Tremblay. I hope this page turns out to be useful & helps people get into this really good toolkit but accept no responsibility for misleading mistakes which waste your valuable time.