MAUtil FrameBuffer

MAUtil::FrameBuffer emulates a 4 or 8 bits per pixel, pallettized display using the FrameBuffer API of MoSync. To initialize the library you provide the FrameBuffer_init with information about the size, colour format and orientation of the screen.

You may then set entries in the palette using either FrameBuffer_setPalette or FrameBuffer_setPaletteEntry.

The FrameBuffer_copyRect colour converts, scales and rotates a selected area of the the source, treated as image pixels with the information provided when initializing the library, into the native framebuffer. The function will automatically scale the backbuffer to fit the screen using pixel doubling/halving. When doing pixel halving, the colours of the pixels will be averaged to get a better reproduction of the actual image. It is a very handy API for porting old desktop applications that used the framebuffer of the VGA/EGA display.

There's two important things to keep in mind:

• FrameBuffer_init allocates memory for the native backbuffer (resolution of the screen x the colour depth), which requires the application to be given a larger heap size (If you get a panic saying 'malloc failed', this is most likely the case).
• Whenever a EVENT_TYPE_SCREEN_CHANGED event is sent from the runtime, the native framebuffer gets invalidated, so is the MAUtil::FrameBuffer library, and needs to be reinitialized. Just use FrameBuffer_Close and FrameBuffer_init in sequence and everything should be just fine.

Here is a simple example (written in C) showing how it is used:

#include <ma.h>
#include <MAUtil/FrameBuffer.h>

// We allocate a 160*120 pixels large 8 bits per pixel backbuffer.
unsigned char backbuffer[160*120];

int MAMain()
{
	int i;

	// Initialize the FrameBuffer library with no special flags and the default orientation.
	FrameBuffer_init(160, 120, ORIENTATION_0, 0);

	// Create a greyscale palette.
	for(i = 0; i < 256; i++)
	{
		FrameBuffer_setPaletteEntry(i, i, i, i, 0);
	}

	while(1)
	{
		MAEvent event;

		// Retrieve the time and use it to generate a color index for
		// all pixels in the backbuffer.
		int time = maGetMilliSecondCount()/10;
		memset(backbuffer, time, 160*120);

		while(maGetEvent(&event))
		{
			switch(event.type)
			{
				// Make sure we catch the close event and if we do, exit.
				case EVENT_TYPE_CLOSE:
					maExit(0);
					break;
				// Whenever the screen area or orientation of the screen changes,
				// we reinitialize the FrameBuffer library.
				case EVENT_TYPE_SCREEN_CHANGED:
					FrameBuffer_close();
					FrameBuffer_init(160, 120, ORIENTATION_0, 0);
					break;
			}
		}

	// Copy, convert, scale and rotate the backbuffer to the native backbuffer.
	FrameBuffer_copyRect(0, 0, 160, 120, 0, 0, backbuffer, 160);

	// Update the screen (copy the native backbuffer to the actual screen).
	maUpdateScreen();
	}
	return 0;
}