version 2.8
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.org/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 TRUE 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 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31  /**
32  * @brief Create an off-screen pixmap that can be drawn to just like a normal display
33  *
34  * @param[in] width The width of the pixmap to be created
35  * @param[in] height The height of the pixmap to be created
36  *
37  * @return The created GDisplay representing the pixmap or 0 if the pixmap couldn't be created.
38  *
39  * @note Once created, an off-screen pixmap can be drawn on using the standard gdispGxxxx calls.
40  * @note It must be destroyed using @p gdispDeleteOffscreenPixmap
41  * @note Because the RAM for the display area is allocated, on small micros only very small pixmaps should be considered.
42  * For example a 100x100 at 16 bits per pixel would be 20K of RAM (plus some overheads).
43  */
44  GDisplay *gdispPixmapCreate(coord_t width, coord_t height);
45 
46  /**
47  * @brief Destroy an off-screen pixmap
48  *
49  * @param[in] g The pixmap virtual display to delete
50  *
51  * @note If a normal display is passed to this routine, it will be ignored.
52  */
53  void gdispPixmapDelete(GDisplay *g);
54 
55  /**
56  * @brief Get a pointer to the pixels of the display surface.
57  * @return The pointer to the pixmap display surface or NULL if this display is not a pixmap.
58  *
59  * @param[in] g The pixmap virtual display
60  *
61  * @note The pointer returned can be used for calls to @p gdispGBlitArea() or can be read or written to directly
62  * by the application code. For any one particular pixmap the pointer will not change over the life of the pixmap
63  * (although different pixmaps will have different pixel pointers). Once a pixmap is deleted, the pixel pointer
64  * should not be used by the application.
65  */
66  pixel_t *gdispPixmapGetBits(GDisplay *g);
67 
68  #if GDISP_NEED_PIXMAP_IMAGE || defined(__DOXYGEN__)
69  /**
70  * @brief Get a pointer to a native format gdispImage.
71  * @return A pointer to a NATIVE format gdispImage in memory or NULL if this display is not a pixmap.
72  * @pre GDISP_NEED_PIXAMP_IMAGE must be TRUE in your gfxconf.h
73  *
74  * @param[in] g The pixmap virtual display
75  *
76  * @return The pointer to the native gdispImage
77  *
78  * @note The pointer returned can be passed to @p gdispImageOpenMemory() or to @p gfileOpenMemory().
79  * @note If you are just wanting to copy to a real display it is more efficient to use @p gdispGetPixmapBits() and @p gdispGBlitArea().
80  * @note Like @p gdispGetPixmapBits(), the pointer returned is valid for the life of the pixmap.
81  */
82  void *gdispPixmapGetMemoryImage(GDisplay *g);
83  #endif
84 
85 #ifdef __cplusplus
86 }
87 #endif
88 
89 #endif /* GFX_USE_GDISP && GDISP_NEED_PIXMAP */
90 #endif /* _GDISP_PIXMAP_H */
91 /** @} */
92 
GDisplay * gdispPixmapCreate(coord_t width, coord_t height)
Create an off-screen pixmap that can be drawn to just like a normal display.
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
void gdispPixmapDelete(GDisplay *g)
Destroy an off-screen pixmap.
void * gdispPixmapGetMemoryImage(GDisplay *g)
Get a pointer to a native format gdispImage.
pixel_t * gdispPixmapGetBits(GDisplay *g)
Get a pointer to the pixels of the display surface.
color_t pixel_t
The pixel format.
Definition: gdisp.h:226