libctru  v2.4.1
gfx.h
Go to the documentation of this file.
1 /**
2  * @file gfx.h
3  * @brief Simple framebuffer API
4  *
5  * This API provides basic functionality needed to bring up framebuffers for both screens,
6  * as well as managing display mode (stereoscopic 3D) and double buffering.
7  * It is mainly an abstraction over the gsp service.
8  *
9  * Please note that the 3DS uses *portrait* screens rotated 90 degrees counterclockwise.
10  * Width/height refer to the physical dimensions of the screen; that is, the top screen
11  * is 240 pixels wide and 400 pixels tall; while the bottom screen is 240x320.
12  */
13 #pragma once
14 
15 #include <3ds/types.h>
16 #include <3ds/services/gspgpu.h>
17 
18 /// Converts red, green, and blue components to packed RGB565.
19 #define RGB565(r,g,b) (((b)&0x1f)|(((g)&0x3f)<<5)|(((r)&0x1f)<<11))
20 
21 /// Converts packed RGB8 to packed RGB565.
22 #define RGB8_to_565(r,g,b) (((b)>>3)&0x1f)|((((g)>>2)&0x3f)<<5)|((((r)>>3)&0x1f)<<11)
23 
24 /// Screen IDs.
25 typedef enum {
26  GFX_TOP = GSP_SCREEN_TOP, ///< Top screen
27  GFX_BOTTOM = GSP_SCREEN_BOTTOM, ///< Bottom screen
28 } gfxScreen_t;
29 
30 /**
31  * @brief Top screen framebuffer side.
32  *
33  * This is only meaningful when stereoscopic 3D is enabled on the top screen.
34  * In any other case, use \ref GFX_LEFT.
35  */
36 typedef enum {
37  GFX_LEFT = 0, ///< Left eye framebuffer
38  GFX_RIGHT = 1, ///< Right eye framebuffer
39 } gfx3dSide_t;
40 
41 ///@name Initialization and deinitialization
42 ///@{
43 
44 /**
45  * @brief Initializes the LCD framebuffers with default parameters
46  * This is equivalent to calling: @code gfxInit(GSP_BGR8_OES,GSP_BGR8_OES,false); @endcode
47  */
48 void gfxInitDefault(void);
49 
50 /**
51  * @brief Initializes the LCD framebuffers.
52  * @param topFormat The format of the top screen framebuffers.
53  * @param bottomFormat The format of the bottom screen framebuffers.
54  * @param vramBuffers Whether to allocate the framebuffers in VRAM.
55  *
56  * This function allocates memory for the framebuffers in the specified memory region.
57  * Initially, stereoscopic 3D is disabled and double buffering is enabled.
58  *
59  * @note This function internally calls \ref gspInit.
60  */
61 void gfxInit(GSPGPU_FramebufferFormat topFormat, GSPGPU_FramebufferFormat bottomFormat, bool vrambuffers);
62 
63 /**
64  * @brief Deinitializes and frees the LCD framebuffers.
65  * @note This function internally calls \ref gspExit.
66  */
67 void gfxExit(void);
68 
69 ///@}
70 
71 ///@name Control
72 ///@{
73 
74 /**
75  * @brief Enables or disables the 3D stereoscopic effect on the top screen.
76  * @param enable Pass true to enable, false to disable.
77  * @note Stereoscopic 3D is disabled by default.
78  */
79 void gfxSet3D(bool enable);
80 
81 /**
82  * @brief Retrieves the status of the 3D stereoscopic effect on the top screen.
83  * @return true if 3D enabled, false otherwise.
84  */
85 bool gfxIs3D(void);
86 
87 /**
88  * @brief Retrieves the status of the 800px (double-height) high resolution display mode of the top screen.
89  * @return true if wide mode enabled, false otherwise.
90  */
91 bool gfxIsWide(void);
92 
93 /**
94  * @brief Enables or disables the 800px (double-height) high resolution display mode of the top screen.
95  * @param enable Pass true to enable, false to disable.
96  * @note Wide mode is disabled by default.
97  * @note Wide and stereoscopic 3D modes are mutually exclusive.
98  * @note In wide mode pixels are not square, since scanlines are half as tall as they normally are.
99  * @warning Wide mode does not work on Old 2DS consoles (however it does work on New 2DS XL consoles).
100  */
101 void gfxSetWide(bool enable);
102 
103 /**
104  * @brief Changes the pixel format of a screen.
105  * @param screen Screen ID (see \ref gfxScreen_t)
106  * @param format Pixel format (see \ref GSPGPU_FramebufferFormat)
107  * @note If the currently allocated framebuffers are too small for the specified format,
108  * they are freed and new ones are reallocated.
109  */
111 
112 /**
113  * @brief Retrieves the current pixel format of a screen.
114  * @param screen Screen ID (see \ref gfxScreen_t)
115  * @return Pixel format (see \ref GSPGPU_FramebufferFormat)
116  */
118 
119 /**
120  * @brief Enables or disables double buffering on a screen.
121  * @param screen Screen ID (see \ref gfxScreen_t)
122  * @param enable Pass true to enable, false to disable.
123  * @note Double buffering is enabled by default.
124  */
125 void gfxSetDoubleBuffering(gfxScreen_t screen, bool enable);
126 
127 ///@}
128 
129 ///@name Rendering and presentation
130 ///@{
131 
132 /**
133  * @brief Retrieves the framebuffer of the specified screen to which graphics should be rendered.
134  * @param screen Screen ID (see \ref gfxScreen_t)
135  * @param side Framebuffer side (see \ref gfx3dSide_t) (pass \ref GFX_LEFT if not using stereoscopic 3D)
136  * @param width Pointer that will hold the width of the framebuffer in pixels.
137  * @param height Pointer that will hold the height of the framebuffer in pixels.
138  * @return A pointer to the current framebuffer of the chosen screen.
139  *
140  * Please remember that the returned pointer will change every frame if double buffering is enabled.
141  */
142 u8* gfxGetFramebuffer(gfxScreen_t screen, gfx3dSide_t side, u16* width, u16* height);
143 
144 /**
145  * @brief Flushes the data cache for the current framebuffers.
146  * @warning This is **only used during software rendering**. Since this function has significant overhead,
147  * it is preferred to call this only once per frame, after all software rendering is completed.
148  */
149 void gfxFlushBuffers(void);
150 
151 /**
152  * @brief Updates the configuration of the specified screen, swapping the buffers if double buffering is enabled.
153  * @param scr Screen ID (see \ref gfxScreen_t)
154  * @param hasStereo For the top screen in 3D mode: true if the framebuffer contains individual images
155  * for both eyes, or false if the left image should be duplicated to the right eye.
156  * @note Previously rendered content will be displayed on the screen after the next VBlank.
157  * @note This function is still useful even if double buffering is disabled, as it must be used to commit configuration changes.
158  * @warning Only call this once per screen per frame, otherwise graphical glitches will occur
159  * since this API does not implement triple buffering.
160  */
161 void gfxScreenSwapBuffers(gfxScreen_t scr, bool hasStereo);
162 
163 /**
164  * @brief Same as \ref gfxScreenSwapBuffers, but with hasStereo set to true.
165  * @param scr Screen ID (see \ref gfxScreen_t)
166  * @param immediate This parameter no longer has any effect and is thus ignored.
167  * @deprecated This function has been superseded by \ref gfxScreenSwapBuffers, please use that instead.
168  */
169 CTR_DEPRECATED void gfxConfigScreen(gfxScreen_t scr, bool immediate);
170 
171 /**
172  * @brief Updates the configuration of both screens.
173  * @note This function is equivalent to: \code gfxScreenSwapBuffers(GFX_TOP,true); gfxScreenSwapBuffers(GFX_BOTTOM,true); \endcode
174  */
175 void gfxSwapBuffers(void);
176 
177 /// Same as \ref gfxSwapBuffers (formerly different).
178 void gfxSwapBuffersGpu(void);
179 
180 ///@}
bool gfxIs3D(void)
Retrieves the status of the 3D stereoscopic effect on the top screen.
void gfxSwapBuffers(void)
Updates the configuration of both screens.
void gfxInit(GSPGPU_FramebufferFormat topFormat, GSPGPU_FramebufferFormat bottomFormat, bool vrambuffers)
Initializes the LCD framebuffers.
void gfxSetWide(bool enable)
Enables or disables the 800px (double-height) high resolution display mode of the top screen.
void gfxInitDefault(void)
Initializes the LCD framebuffers with default parameters This is equivalent to calling:
void gfxSwapBuffersGpu(void)
Same as gfxSwapBuffers (formerly different).
u8 * gfxGetFramebuffer(gfxScreen_t screen, gfx3dSide_t side, u16 *width, u16 *height)
Retrieves the framebuffer of the specified screen to which graphics should be rendered.
GSPGPU_FramebufferFormat gfxGetScreenFormat(gfxScreen_t screen)
Retrieves the current pixel format of a screen.
gfxScreen_t
Screen IDs.
Definition: gfx.h:25
@ GFX_BOTTOM
Bottom screen.
Definition: gfx.h:27
@ GFX_TOP
Top screen.
Definition: gfx.h:26
void gfxSet3D(bool enable)
Enables or disables the 3D stereoscopic effect on the top screen.
void gfxScreenSwapBuffers(gfxScreen_t scr, bool hasStereo)
Updates the configuration of the specified screen, swapping the buffers if double buffering is enable...
void gfxSetDoubleBuffering(gfxScreen_t screen, bool enable)
Enables or disables double buffering on a screen.
void gfxExit(void)
Deinitializes and frees the LCD framebuffers.
CTR_DEPRECATED void gfxConfigScreen(gfxScreen_t scr, bool immediate)
Same as gfxScreenSwapBuffers, but with hasStereo set to true.
void gfxSetScreenFormat(gfxScreen_t screen, GSPGPU_FramebufferFormat format)
Changes the pixel format of a screen.
gfx3dSide_t
Top screen framebuffer side.
Definition: gfx.h:36
@ GFX_LEFT
Left eye framebuffer.
Definition: gfx.h:37
@ GFX_RIGHT
Right eye framebuffer.
Definition: gfx.h:38
bool gfxIsWide(void)
Retrieves the status of the 800px (double-height) high resolution display mode of the top screen.
void gfxFlushBuffers(void)
Flushes the data cache for the current framebuffers.
GSPGPU service.
#define GSP_SCREEN_BOTTOM
ID of the bottom screen.
Definition: gspgpu.h:8
#define GSP_SCREEN_TOP
ID of the top screen.
Definition: gspgpu.h:7
GSPGPU_FramebufferFormat
Framebuffer format.
Definition: gspgpu.h:28
Various system types.
#define CTR_DEPRECATED
Flags a function as deprecated.
Definition: types.h:56
uint8_t u8
would be nice if newlib had this already
Definition: types.h:21
uint16_t u16
16-bit unsigned integer
Definition: types.h:22