Difference between revisions of "Pixmaps"

Latest revision as of 16:02, 4 December 2023

Pixmaps provide dynamic frame buffers. A pixmap of any size can by dynamically created and destroyed during runtime. A pixmap represents itself as a virtual display to the user. Hence a pixmap can be treated like a regular display and all the available GDISP drawing routines can be performed inside the pixmap frame buffer. A pixmap can be rendered at any location of a real display at any time.

Note that pixmaps always use the system pixel format. See color formats for more information.

API reference

The API reference of the pixmap can be found here.

Limitations

In µGFX < v3.0, pixmaps are not supported when using the single file inclusion mechanism as pixmaps rely on multi-display capabilities.

Creating and destroying a pixmap

Pixmaps can be created and destroyed at any time during runtime using gdispPixmapCreate() and gdispPixmapDelete().

Accessing the pixmap

A pixmap can be treated as either a virtual display or as a memory frame buffer surface.

Virtual display

gdispPixmapCreate() returns a GDisplay pointer. Hence the pixmap can be treated like a regular display and all the GDISP operations (including orientations) can be used on a pixmap.

Frame buffer surface

The memory of a created pixmap can be accessed directly in order to use it like a regular frame buffer surface. gdispPixmapGetBits() returns a pointer to the first pixel of the pixmap.

Image access

It's possible to treat a pixmap as an image. gdispPixmapGetMemoryImage() returns a pointer to a native GDISP image (gdispImage*). This allows to use a pixmap as the image for image rendering routines.

Displaying a pixmap

A pixmap can be displayed on a real display at any time using the gdispBlitArea() function. Note that this call allows to display the pixmap at any location on the screen, not only at the display origin. Therefore, this can be used to implement scrolling and other animations.

Example

The following example will show how to create a pixmap and access it both as a virtual display and as a frame buffer surface. Once the pixmap is created it will be blitted incrementally across the entire screen (The pixmap will move across the screen).

#include "gfx.h"
 
#define PIXMAP_WIDTH	40
#define PIXMAP_HEIGHT	10
 
static GDisplay* pixmap;
static pixel_t* surface;
 
int main(void)
{
    coord_t		width, height;
    coord_t		i, j;
 
    // Initialize and clear the display
    gfxInit();
 
    // Get the screen size
    width = gdispGetWidth();
    height = gdispGetHeight();
 
    // Create a pixmap and get a pointer to the bits
    pixmap = gdispPixmapCreate(PIXMAP_WIDTH, PIXMAP_HEIGHT);
    surface = gdispPixmapGetBits(pixmap);
 
    // A pixmap can be treated either as a virtual display or as a memory framebuffer surface.
    // We demonstrate writing to it using both methods.
 
    // First demo drawing onto the surface directly
    for(j = 0; j < PIXMAP_HEIGHT; j++)
    	for(i = 0; i < PIXMAP_WIDTH; i++)
    		surface[j*PIXMAP_WIDTH + i] = RGB2COLOR(0, 255-i*(256/PIXMAP_WIDTH), j*(256/PIXMAP_HEIGHT));
 
    // Secondly, show drawing a line on it like a virtual display
    gdispGDrawLine(pixmap, 0, 0, gdispGGetWidth(pixmap)-1, gdispGGetHeight(pixmap)-1, White);
 
    i = j = 0;
    while(TRUE) {
    	// Clear the old position
    	gdispFillArea(i, j, PIXMAP_WIDTH, PIXMAP_HEIGHT, Black);
 
    	// Change the position
    	i += PIXMAP_WIDTH/2;
    	if (i >= width - PIXMAP_WIDTH/2) {
    		i %= width - PIXMAP_WIDTH/2;
    		j = (j + PIXMAP_HEIGHT/2) % (height - PIXMAP_HEIGHT/2);
    	}
 
    	// Blit the pixmap to the real display at the new position
    	gdispBlitArea(i, j, PIXMAP_WIDTH, PIXMAP_HEIGHT, surface);
 
    	// Wait
    	gfxSleepMilliseconds(100);
    }
 
    // Clean up
    gdispPixmapDelete(pixmap);
}

Double buffering

Pixmaps can be used to implement application level double buffering if the underlying hardware doesn't support it. More information can be found in this community forum topic.