µGFX  2.9
version 2.9
gdisp_pixmap.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.io/license.html
6  */
7 
8 /**
9  * @file src/gdisp/gdisp_pixmap.h
10  *
11  * @defgroup Pixmap Pixmap
12  * @ingroup GDISP
13  *
14  * @brief Sub-Module for dynamic framebuffers.
15  *
16  * @note A Pixmap is an off-screen virtual display that can be drawn to just like any other
17  * display. It can then be copied to a real display using the standard gdispGBlitArea() call.
18  * @pre GDISP_NEED_PIXMAP must be GFXON in your gfxconf.h
19  * @{
20  */
21 
22 #ifndef _GDISP_PIXMAP_H
23 #define _GDISP_PIXMAP_H
24 
25 #if (GFX_USE_GDISP && GDISP_NEED_PIXMAP) || defined(__DOXYGEN__)
26 
27 /**
28  * @brief Create an off-screen pixmap that can be drawn to just like a normal display
29  *
30  * @param[in] width The width of the pixmap to be created
31  * @param[in] height The height of the pixmap to be created
32  *
33  * @return The created GDisplay representing the pixmap or 0 if the pixmap couldn't be created.
34  *
35  * @note Once created, an off-screen pixmap can be drawn on using the standard gdispGxxxx calls.
36  * @note It must be destroyed using @p gdispDeleteOffscreenPixmap
37  * @note Because the RAM for the display area is allocated, on small micros only very small pixmaps should be considered.
38  * For example a 100x100 at 16 bits per pixel would be 20K of RAM (plus some overheads).
39  */
40 GDisplay *gdispPixmapCreate(gCoord width, gCoord height);
41 
42 /**
43  * @brief Destroy an off-screen pixmap
44  *
45  * @param[in] g The pixmap virtual display to delete
46  *
47  * @note If a normal display is passed to this routine, it will be ignored.
48  */
49 void gdispPixmapDelete(GDisplay *g);
50 
51 /**
52  * @brief Get a pointer to the pixels of the display surface.
53  * @return The pointer to the pixmap display surface or NULL if this display is not a pixmap.
54  *
55  * @param[in] g The pixmap virtual display
56  *
57  * @note The pointer returned can be used for calls to @p gdispGBlitArea() or can be read or written to directly
58  * by the application code. For any one particular pixmap the pointer will not change over the life of the pixmap
59  * (although different pixmaps will have different pixel pointers). Once a pixmap is deleted, the pixel pointer
60  * should not be used by the application.
61  */
62 gPixel *gdispPixmapGetBits(GDisplay *g);
63 
64 #if GDISP_NEED_PIXMAP_IMAGE || defined(__DOXYGEN__)
65  /**
66  * @brief Get a pointer to a native format gImage.
67  * @return A pointer to a NATIVE format gImage in memory or NULL if this display is not a pixmap.
68  * @pre GDISP_NEED_PIXAMP_IMAGE must be GFXON in your gfxconf.h
69  *
70  * @param[in] g The pixmap virtual display
71  *
72  * @return The pointer to the native gImage
73  *
74  * @note The pointer returned can be passed to @p gdispImageOpenMemory() or to @p gfileOpenMemory().
75  * @note If you are just wanting to copy to a real display it is more efficient to use @p gdispGetPixmapBits() and @p gdispGBlitArea().
76  * @note Like @p gdispGetPixmapBits(), the pointer returned is valid for the life of the pixmap.
77  */
78  void *gdispPixmapGetMemoryImage(GDisplay *g);
79 #endif
80 
81 #endif /* GFX_USE_GDISP && GDISP_NEED_PIXMAP */
82 #endif /* _GDISP_PIXMAP_H */
83 /** @} */
84 
gColor gPixel
The pixel format.
Definition: gdisp.h:226
gI16 gCoord
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
gPixel * gdispPixmapGetBits(GDisplay *g)
Get a pointer to the pixels of the display surface.
void gdispPixmapDelete(GDisplay *g)
Destroy an off-screen pixmap.
GDisplay * gdispPixmapCreate(gCoord width, gCoord height)
Create an off-screen pixmap that can be drawn to just like a normal display.
void * gdispPixmapGetMemoryImage(GDisplay *g)
Get a pointer to a native format gImage.