Preloading Bitmaps

Palm Programming

Palm Programming Homepage | Sourcecode | Email Us

Support

Palm | Windows | Unix

Subroutines and Snippets

Preloading into an array in memory will allow us to draw and erase bitmaps at high speed, as well as give us the ability use them as masked sprites (discussed in Concepts and Strategies.)

subroutines that simplify using preloaded graphics

The color coding used:
light blue = variables, constants, and subroutines names chosen by the programmer
light green = C defined words, Palm API calls, and all else NOT chosen by the programmer

we will create two global constants for our example
firstBitmapToPreload=bmpSprite01; // set this to the name of the first bitmap you wish to preload
numberOfBitmapsToPreload=50; // set this to the number of bitmaps you wish to preload

a few global variables to hold our graphics in memory
VoidHand    preloadBitmapHandle[numberOfBitmapsToPreload];
BitmapPtr    preloadBitmapPointer[numberOfBitmapsToPreload];
WinHandle preloadWindowHandle[numberOfBitmapsToPreload];
RectangleType preloadBounds[numberOfBitmapsToPreload];

a subroutine to load the graphics into memory
void LoadGraphics (int firstBitmapToPreload, int numberOfBitmapsToPreload)
{
   int i;
   short err;
   for (i=0;i<numberOfBitmapsToPreload; i++)
   {
      preloadBitmapHandle[i] = DmGetResource(bitmapRsc, firstBitmapToPreload+i);
     preloadBitmapPointer[i] = MemHandleLock(preloadBitmapHandle[i]);
   preloadWindowHandle[i] = WinCreateOffscreenWindow(preloadBitmapPointer[i] -> width,
                                                       preloadBitmapPointer[i]->height,screenFormat,&err);
      ErrFatalDisplayIf(err, "Error while loading images"); // ** out of memory is possible here
      WinSetDrawWindow(preloadWindowHandles[i]);
      WinGetWindowBounds(&preloadBounds[i]);
      WinDrawBitmap(preloadBitmapPointer[i],0,0);
   }
}

a subroutine to unload our graphics when our program is finished with them
void UnloadGraphics(void)
{
   int i;
   for ( i = 0 ; i < numberOfBitmapsToPreload; i++)
   {
      MemHandleUnlock(preloadBitmapHandle[i]);
      DmReleaseResource(preloadBitmapHandle[i]);
      WinDeleteWindow(preloadWindowHandles[i],false);
   }
}

a subroutine to draw a preloaded graphic to the screen
void OffscreenGraphic(int bitmapID, int x, int y, int drawType)
{
   WinHandle MainDrawWindowHandle = WinGetDrawWindow(); // draw to the currently active window
   int displayID=bitmapID-firstBitmapToPreload;
   WinCopyRectangle (
         preloadWindowHandle[displayID], MainDrawWindowHandle, &preloadBounds[displayID], x, y, drawType);
}

examples (using the subroutines above to display a bitmap graphic)

first we must load the graphics into memory (at the start of the program) using the subroutine above
LoadGraphics();

To display a bitmap we have called bmpSpaceship (we name our bitmap resources in our IDE) with the upper left corner at col=50, row=80 (the palms screen is 160 cols by 160 rows), and drawType=0 (copy mode)
OffscreenGraphic(bmpSpaceship,50,80,0);

The last argument, drawType, gives us some interesting options:
0 = paint - copy mode
1 = erase - destination cleared where source pixels are off - AND mode
2 = mask - destination cleared where source pixels are on - AND NOT mode
3 = invert - destination inverted where source pixels are on - XOR mode
4 = overlay - destination set only where source pixels are on - OR mode
5 = inverse - destination replaced with inverted source - copy NOT mode
6 = swap - destination forground and background colors are swapped, leaving all others unchanged.

don't forget to unload the graphics from memory at the end of your program
UnloadGraphics();

tech info

When preloading bitmaps:

1) Be careful not to load so many graphics that you overrun the memory. "Popping" the memory can cause strange problems and be hard to diagnose. When testing it can be helpful to reduce the number of grahics you are loading to a very small number and see if the problem goes away.

2) The bitmaps must be sequentially numbered for the LoadGraphics routine to work properly.

IDE notes: Your bitmaps will be sequentially numbered if you load them in order,
or you may manually edit the bitmap id numbers to sequence them properly.
Put all the graphics you wish to load into memory together, sequentially numbered without skipping numbers.
Graphics that won't be preloaded can be in any order or numbering scheme.

Preloading graphic resources into memory for faster display