Difference between revisions of "Pixmaps"

From uGFX Wiki
Jump to: navigation, search
(Example)
(Fix broken URL)
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
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.
 
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 [[GDISP#Color_format|color formats]] for more information.
  
 
== API reference ==
 
== API reference ==
The API reference of the pixmap can be found [http://api.ugfx.org/master/group___pixmap.html here].
+
The API reference of the pixmap can be found [https://api.ugfx.io/group___pixmap.html here].
 +
 
 +
== Limitations ==
 +
In µGFX < v3.0, pixmaps are not supported when using the [[Getting_Started#Single_File_Inclusion|single file inclusion]] mechanism as pixmaps rely on multi-display capabilities.
  
 
== Creating and destroying a pixmap ==
 
== Creating and destroying a pixmap ==
Pixmaps can be created and destroyed at any time during runtime using ''gdispPixmapCreate()'' and ''gdispPixmapDelete()''.
+
Pixmaps can be created and destroyed at any time during runtime using <code>gdispPixmapCreate()</code> and <code>gdispPixmapDelete()</code>.
  
 
== Accessing the pixmap ==
 
== Accessing the pixmap ==
Line 11: Line 16:
  
 
=== Virtual display ===
 
=== 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.
+
<code>gdispPixmapCreate()</code> returns a [[GDISP#GDisplay|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 ===
 
=== 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.
+
The memory of a created pixmap can be accessed directly in order to use it like a regular frame buffer surface. <code>gdispPixmapGetBits()</code> returns a pointer to the first pixel of the pixmap.
 +
 
 +
=== Image access ===
 +
It's possible to treat a pixmap as an image. <code>gdispPixmapGetMemoryImage()</code> returns a pointer to a native GDISP image (<code>gdispImage*</code>). This allows to use a pixmap as the image for image rendering routines.
  
 
== Displaying a pixmap ==
 
== Displaying a pixmap ==
A pixmap can be displayed on a real display at any time using the ''gdispBlitArea()'' function. Note that this call allows it to display the pixmap at any location on the screen, not only at the display origin.
+
A pixmap can be displayed on a real display at any time using the <code>gdispBlitArea()</code> 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 ==
 
== Example ==
Line 80: Line 88:
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
== 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 [https://community.ugfx.io/topic/960-flicker community forum topic].
  
 
[[Category:GDISP]]
 
[[Category:GDISP]]

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.