libctru  v1.6.0
gfx.h
Go to the documentation of this file.
1 /**
2  * @file gfx.h
3  * @brief LCD Screens manipulation
4  *
5  * This header provides functions to configure and manipulate the two screens, including double buffering and 3D activation.
6  * It is mainly an abstraction over the gsp service.
7  */
8 #pragma once
9 
10 #include <3ds/types.h>
11 #include <3ds/services/gspgpu.h>
12 
13 /// Converts red, green, and blue components to packed RGB565.
14 #define RGB565(r,g,b) (((b)&0x1f)|(((g)&0x3f)<<5)|(((r)&0x1f)<<11))
15 
16 /// Converts packed RGB8 to packed RGB565.
17 #define RGB8_to_565(r,g,b) (((b)>>3)&0x1f)|((((g)>>2)&0x3f)<<5)|((((r)>>3)&0x1f)<<11)
18 
19 /// Available screens.
20 typedef enum
21 {
22  GFX_TOP = 0, ///< Top screen
23  GFX_BOTTOM = 1 ///< Bottom screen
25 
26 /**
27  * @brief Side of top screen framebuffer.
28  *
29  * This is to be used only when the 3D is enabled.
30  * Use only GFX_LEFT if this concerns the bottom screen or if 3D is disabled.
31  */
32 typedef enum
33 {
34  GFX_LEFT = 0, ///< Left eye framebuffer
35  GFX_RIGHT = 1,///< Right eye framebuffer
37 
38 
39 ///@name System related
40 ///@{
41 
42 /**
43  * @brief Initializes the LCD framebuffers with default parameters
44  *
45  * By default ctrulib will configure the LCD framebuffers with the @ref GSP_BGR8_OES format in linear memory.
46  * This is the same as calling : @code gfxInit(GSP_BGR8_OES,GSP_BGR8_OES,false); @endcode
47  *
48  * @note You should always call @ref gfxExit once done to free the memory and services
49  */
50 void gfxInitDefault(void);
51 
52 /**
53  * @brief Initializes the LCD framebuffers.
54  * @param topFormat The format of the top screen framebuffers.
55  * @param bottomFormat The format of the bottom screen framebuffers.
56  * @param vramBuffers Whether to allocate the framebuffers in VRAM.
57  *
58  * This function will allocate the memory for the framebuffers and open a gsp service session.
59  * It will also bind the newly allocated framebuffers to the LCD screen and setup the VBlank event.
60  *
61  * The 3D stereoscopic display is will be disabled.
62  *
63  * @note Even if the double buffering is disabled, it will allocate two buffer per screen.
64  * @note You should always call @ref gfxExit once done to free the memory and services
65  */
66 void gfxInit(GSPGPU_FramebufferFormats topFormat, GSPGPU_FramebufferFormats bottomFormat, bool vrambuffers);
67 
68 /**
69  * @brief Closes the gsp service and frees the framebuffers.
70  *
71  * Just call it when you're done.
72  */
73 void gfxExit(void);
74 ///@}
75 
76 ///@name Control
77 ///@{
78 /**
79  * @brief Enables the 3D stereoscopic effect.
80  * @param enable Enables the 3D effect if true, disables it if false.
81  */
82 void gfxSet3D(bool enable);
83 
84 /**
85  * @brief Retrieves the status of the 3D stereoscopic effect.
86  * @return true if 3D enabled, false otherwise.
87  */
88 bool gfxIs3D(void);
89 
90 /**
91  * @brief Changes the color format of a screen
92  * @param screen The screen of which format should be changed
93  * @param format One of the gsp pixel formats.
94  */
96 
97 /**
98  * @brief Gets a screen pixel format.
99  * @param screen Screen to get the pixel format of.
100  * @return the pixel format of the chosen screen set by ctrulib.
101  */
103 
104 /**
105  * @brief Sets whether to use ctrulib's double buffering
106  * @param screen Screen to toggle double buffering for.
107  * @param doubleBuffering Whether to use double buffering.
108  *
109  * ctrulib is by default using a double buffering scheme.
110  * If you do not want to swap one of the screen framebuffers when @ref gfxSwapBuffers or @ref gfxSwapBuffers is called,
111  * then you have to disable double buffering.
112  *
113  * It is however recommended to call @ref gfxSwapBuffers even if double buffering is disabled
114  * for both screens if you want to keep the gsp configuration up to date.
115  */
116 void gfxSetDoubleBuffering(gfxScreen_t screen, bool doubleBuffering);
117 
118 /**
119  * @brief Flushes the current framebuffers
120  *
121  * Use this if the data within your framebuffers changes a lot and that you want to make sure everything was updated correctly.
122  * This shouldn't be needed and has a significant overhead.
123  */
124 void gfxFlushBuffers(void);
125 
126 /**
127  * @brief Updates the configuration of the specified screen (swapping the buffers if double-buffering is enabled).
128  * @param scr Screen to configure.
129  * @param immediate Whether to apply the updated configuration immediately or let GSPGPU apply it after the next GX transfer completes.
130  */
131 void gfxConfigScreen(gfxScreen_t scr, bool immediate);
132 
133 /**
134  * @brief Swaps the buffers and sets the gsp state
135  *
136  * This is to be called to update the gsp state and swap the framebuffers.
137  * LCD rendering should start as soon as the gsp state is set.
138  * When using the GPU, call @ref gfxSwapBuffers instead.
139  */
140 void gfxSwapBuffers(void);
141 
142 /**
143  * @brief Swaps the framebuffers
144  *
145  * This is the version to be used with the GPU since the GPU will use the gsp shared memory,
146  * so the gsp state mustn't be set directly by the user.
147  */
148 void gfxSwapBuffersGpu(void);
149 
150 ///@}
151 
152 
153 ///@name Helper
154 ///@{
155 /**
156  * @brief Retrieves a framebuffer information.
157  * @param screen Screen to retrieve framebuffer information for.
158  * @param side Side of the screen to retrieve framebuffer information for.
159  * @param width Pointer that will hold the width of the framebuffer in pixels.
160  * @param height Pointer that will hold the height of the framebuffer in pixels.
161  * @return A pointer to the current framebuffer of the choosen screen.
162  *
163  * Please remember that the returned pointer will change after each call to gfxSwapBuffers if double buffering is enabled.
164  */
165 u8* gfxGetFramebuffer(gfxScreen_t screen, gfx3dSide_t side, u16* width, u16* height);
166 ///@}
167 
168 //global variables
169 extern u8* gfxTopLeftFramebuffers[2];
170 extern u8* gfxTopRightFramebuffers[2];
171 extern u8* gfxBottomFramebuffers[2];
Various system types.
void gfxConfigScreen(gfxScreen_t scr, bool immediate)
Updates the configuration of the specified screen (swapping the buffers if double-buffering is enable...
uint16_t u16
16-bit unsigned integer
Definition: types.h:22
GSPGPU service.
Bottom screen.
Definition: gfx.h:23
GSPGPU_FramebufferFormats
Framebuffer format.
Definition: gspgpu.h:22
void gfxSwapBuffers(void)
Swaps the buffers and sets the gsp state.
bool gfxIs3D(void)
Retrieves the status of the 3D stereoscopic effect.
void gfxSetDoubleBuffering(gfxScreen_t screen, bool doubleBuffering)
Sets whether to use ctrulib's double buffering.
uint8_t u8
would be nice if newlib had this already
Definition: types.h:21
void gfxInitDefault(void)
Initializes the LCD framebuffers with default parameters.
void gfxSwapBuffersGpu(void)
Swaps the framebuffers.
GSPGPU_FramebufferFormats gfxGetScreenFormat(gfxScreen_t screen)
Gets a screen pixel format.
Left eye framebuffer.
Definition: gfx.h:34
void gfxSetScreenFormat(gfxScreen_t screen, GSPGPU_FramebufferFormats format)
Changes the color format of a screen.
Right eye framebuffer.
Definition: gfx.h:35
void gfxInit(GSPGPU_FramebufferFormats topFormat, GSPGPU_FramebufferFormats bottomFormat, bool vrambuffers)
Initializes the LCD framebuffers.
void gfxExit(void)
Closes the gsp service and frees the framebuffers.
Top screen.
Definition: gfx.h:22
gfx3dSide_t
Side of top screen framebuffer.
Definition: gfx.h:32
gfxScreen_t
Available screens.
Definition: gfx.h:20
void gfxSet3D(bool enable)
Enables the 3D stereoscopic effect.
u8 * gfxGetFramebuffer(gfxScreen_t screen, gfx3dSide_t side, u16 *width, u16 *height)
Retrieves a framebuffer information.
void gfxFlushBuffers(void)
Flushes the current framebuffers.