libctru  v2.4.1
gspgpu.h
Go to the documentation of this file.
1 /**
2  * @file gspgpu.h
3  * @brief GSPGPU service.
4  */
5 #pragma once
6 
7 #define GSP_SCREEN_TOP 0 ///< ID of the top screen.
8 #define GSP_SCREEN_BOTTOM 1 ///< ID of the bottom screen.
9 #define GSP_SCREEN_WIDTH 240 ///< Width of the top/bottom screens.
10 #define GSP_SCREEN_HEIGHT_TOP 400 ///< Height of the top screen.
11 #define GSP_SCREEN_HEIGHT_TOP_2X 800 ///< Height of the top screen (2x).
12 #define GSP_SCREEN_HEIGHT_BOTTOM 320 ///< Height of the bottom screen.
13 
14 /// Framebuffer information.
15 typedef struct
16 {
17  u32 active_framebuf; ///< Active framebuffer. (0 = first, 1 = second)
18  u32 *framebuf0_vaddr; ///< Framebuffer virtual address, for the main screen this is the 3D left framebuffer.
19  u32 *framebuf1_vaddr; ///< For the main screen: 3D right framebuffer address.
20  u32 framebuf_widthbytesize; ///< Value for 0x1EF00X90, controls framebuffer width.
21  u32 format; ///< Framebuffer format, this u16 is written to the low u16 for LCD register 0x1EF00X70.
22  u32 framebuf_dispselect; ///< Value for 0x1EF00X78, controls which framebuffer is displayed.
23  u32 unk; ///< Unknown.
25 
26 /// Framebuffer format.
27 typedef enum
28 {
29  GSP_RGBA8_OES=0, ///< RGBA8. (4 bytes)
30  GSP_BGR8_OES=1, ///< BGR8. (3 bytes)
31  GSP_RGB565_OES=2, ///< RGB565. (2 bytes)
32  GSP_RGB5_A1_OES=3, ///< RGB5A1. (2 bytes)
33  GSP_RGBA4_OES=4 ///< RGBA4. (2 bytes)
35 
36 /// Capture info entry.
37 typedef struct
38 {
39  u32 *framebuf0_vaddr; ///< Left framebuffer.
40  u32 *framebuf1_vaddr; ///< Right framebuffer.
41  u32 format; ///< Framebuffer format.
42  u32 framebuf_widthbytesize; ///< Framebuffer pitch.
44 
45 /// Capture info.
46 typedef struct
47 {
48  GSPGPU_CaptureInfoEntry screencapture[2]; ///< Capture info entries, one for each screen.
50 
51 /// GSPGPU events.
52 typedef enum
53 {
54  GSPGPU_EVENT_PSC0 = 0, ///< Memory fill completed.
55  GSPGPU_EVENT_PSC1, ///< TODO
58  GSPGPU_EVENT_PPF, ///< Display transfer finished.
59  GSPGPU_EVENT_P3D, ///< Command list processing finished.
60  GSPGPU_EVENT_DMA, ///< TODO
61 
62  GSPGPU_EVENT_MAX, ///< Used to know how many events there are.
63 } GSPGPU_Event;
64 
65 /**
66  * @brief Gets the number of bytes per pixel for the specified format.
67  * @param format See \ref GSPGPU_FramebufferFormat.
68  * @return Bytes per pixel.
69  */
70 static inline unsigned gspGetBytesPerPixel(GSPGPU_FramebufferFormat format)
71 {
72  switch (format)
73  {
74  case GSP_RGBA8_OES:
75  return 4;
76  default:
77  case GSP_BGR8_OES:
78  return 3;
79  case GSP_RGB565_OES:
80  case GSP_RGB5_A1_OES:
81  case GSP_RGBA4_OES:
82  return 2;
83  }
84 }
85 
86 /// Initializes GSPGPU.
88 
89 /// Exits GSPGPU.
90 void gspExit(void);
91 
92 /**
93  * @brief Gets a pointer to the current gsp::Gpu session handle.
94  * @return A pointer to the current gsp::Gpu session handle.
95  */
97 
98 /// Returns true if the application currently has GPU rights.
99 bool gspHasGpuRight(void);
100 
101 /**
102  * @brief Presents a buffer to the specified screen.
103  * @param screen Screen ID (see \ref GSP_SCREEN_TOP and \ref GSP_SCREEN_BOTTOM)
104  * @param swap Specifies which set of framebuffer registers to configure and activate (0 or 1)
105  * @param fb_a Pointer to the framebuffer (in stereo mode: left eye)
106  * @param fb_b Pointer to the secondary framebuffer (only used in stereo mode for the right eye, otherwise pass the same as fb_a)
107  * @param stride Stride in bytes between scanlines
108  * @param mode Mode configuration to be written to LCD register
109  * @return true if a buffer had already been presented to the screen but not processed yet by GSP, false otherwise.
110  * @note The most recently presented buffer is processed and configured during the specified screen's next VBlank event.
111  */
112 bool gspPresentBuffer(unsigned screen, unsigned swap, const void* fb_a, const void* fb_b, u32 stride, u32 mode);
113 
114 /**
115  * @brief Returns true if a prior \ref gspPresentBuffer command is still pending to be processed by GSP.
116  * @param screen Screen ID (see \ref GSP_SCREEN_TOP and \ref GSP_SCREEN_BOTTOM)
117  */
118 bool gspIsPresentPending(unsigned screen);
119 
120 /**
121  * @brief Configures a callback to run when a GSPGPU event occurs.
122  * @param id ID of the event.
123  * @param cb Callback to run.
124  * @param data Data to be passed to the callback.
125  * @param oneShot When true, the callback is only executed once. When false, the callback is executed every time the event occurs.
126  */
127 void gspSetEventCallback(GSPGPU_Event id, ThreadFunc cb, void* data, bool oneShot);
128 
129 /**
130  * @brief Waits for a GSPGPU event to occur.
131  * @param id ID of the event.
132  * @param nextEvent Whether to discard the current event and wait for the next event.
133  */
134 void gspWaitForEvent(GSPGPU_Event id, bool nextEvent);
135 
136 /**
137  * @brief Waits for any GSPGPU event to occur.
138  * @return The ID of the event that occurred.
139  *
140  * The function returns immediately if there are unprocessed events at the time of call.
141  */
143 
144 /// Waits for PSC0
145 #define gspWaitForPSC0() gspWaitForEvent(GSPGPU_EVENT_PSC0, false)
146 
147 /// Waits for PSC1
148 #define gspWaitForPSC1() gspWaitForEvent(GSPGPU_EVENT_PSC1, false)
149 
150 /// Waits for VBlank.
151 #define gspWaitForVBlank() gspWaitForVBlank0()
152 
153 /// Waits for VBlank0.
154 #define gspWaitForVBlank0() gspWaitForEvent(GSPGPU_EVENT_VBlank0, true)
155 
156 /// Waits for VBlank1.
157 #define gspWaitForVBlank1() gspWaitForEvent(GSPGPU_EVENT_VBlank1, true)
158 
159 /// Waits for PPF.
160 #define gspWaitForPPF() gspWaitForEvent(GSPGPU_EVENT_PPF, false)
161 
162 /// Waits for P3D.
163 #define gspWaitForP3D() gspWaitForEvent(GSPGPU_EVENT_P3D, false)
164 
165 /// Waits for DMA.
166 #define gspWaitForDMA() gspWaitForEvent(GSPGPU_EVENT_DMA, false)
167 
168 /**
169  * @brief Submits a GX command.
170  * @param gxCommand GX command to execute.
171  */
172 Result gspSubmitGxCommand(const u32 gxCommand[0x8]);
173 
174 /**
175  * @brief Acquires GPU rights.
176  * @param flags Flags to acquire with.
177  */
179 
180 /// Releases GPU rights.
182 
183 /**
184  * @brief Retrieves display capture info.
185  * @param captureinfo Pointer to output capture info to.
186  */
188 
189 /// Saves the VRAM sys area.
191 
192 /// Resets the GPU
194 
195 /// Restores the VRAM sys area.
197 
198 /**
199  * @brief Sets whether to force the LCD to black.
200  * @param flags Whether to force the LCD to black. (0 = no, non-zero = yes)
201  */
203 
204 /**
205  * @brief Updates a screen's framebuffer state.
206  * @param screenid ID of the screen to update.
207  * @param framebufinfo Framebuffer information to update with.
208  */
209 Result GSPGPU_SetBufferSwap(u32 screenid, const GSPGPU_FramebufferInfo* framebufinfo);
210 
211 /**
212  * @brief Flushes memory from the data cache.
213  * @param adr Address to flush.
214  * @param size Size of the memory to flush.
215  */
216 Result GSPGPU_FlushDataCache(const void* adr, u32 size);
217 
218 /**
219  * @brief Invalidates memory in the data cache.
220  * @param adr Address to invalidate.
221  * @param size Size of the memory to invalidate.
222  */
223 Result GSPGPU_InvalidateDataCache(const void* adr, u32 size);
224 
225 /**
226  * @brief Writes to GPU hardware registers.
227  * @param regAddr Register address to write to.
228  * @param data Data to write.
229  * @param size Size of the data to write.
230  */
231 Result GSPGPU_WriteHWRegs(u32 regAddr, const u32* data, u8 size);
232 
233 /**
234  * @brief Writes to GPU hardware registers with a mask.
235  * @param regAddr Register address to write to.
236  * @param data Data to write.
237  * @param datasize Size of the data to write.
238  * @param maskdata Data of the mask.
239  * @param masksize Size of the mask.
240  */
241 Result GSPGPU_WriteHWRegsWithMask(u32 regAddr, const u32* data, u8 datasize, const u32* maskdata, u8 masksize);
242 
243 /**
244  * @brief Reads from GPU hardware registers.
245  * @param regAddr Register address to read from.
246  * @param data Buffer to read data to.
247  * @param size Size of the buffer.
248  */
249 Result GSPGPU_ReadHWRegs(u32 regAddr, u32* data, u8 size);
250 
251 /**
252  * @brief Registers the interrupt relay queue.
253  * @param eventHandle Handle of the GX command event.
254  * @param flags Flags to register with.
255  * @param outMemHandle Pointer to output the shared memory handle to.
256  * @param threadID Pointer to output the GSP thread ID to.
257  */
258 Result GSPGPU_RegisterInterruptRelayQueue(Handle eventHandle, u32 flags, Handle* outMemHandle, u8* threadID);
259 
260 /// Unregisters the interrupt relay queue.
262 
263 /// Triggers a handling of commands written to shared memory.
265 
266 /**
267  * @brief Sets 3D_LEDSTATE to the input state value.
268  * @param disable False = 3D LED enable, true = 3D LED disable.
269  */
bool gspIsPresentPending(unsigned screen)
Returns true if a prior gspPresentBuffer command is still pending to be processed by GSP.
Result gspInit(void)
Initializes GSPGPU.
GSPGPU_Event
GSPGPU events.
Definition: gspgpu.h:53
@ GSPGPU_EVENT_MAX
Used to know how many events there are.
Definition: gspgpu.h:62
@ GSPGPU_EVENT_PPF
Display transfer finished.
Definition: gspgpu.h:58
@ GSPGPU_EVENT_VBlank0
TODO.
Definition: gspgpu.h:56
@ GSPGPU_EVENT_DMA
TODO.
Definition: gspgpu.h:60
@ GSPGPU_EVENT_PSC0
Memory fill completed.
Definition: gspgpu.h:54
@ GSPGPU_EVENT_PSC1
TODO.
Definition: gspgpu.h:55
@ GSPGPU_EVENT_VBlank1
TODO.
Definition: gspgpu.h:57
@ GSPGPU_EVENT_P3D
Command list processing finished.
Definition: gspgpu.h:59
Result GSPGPU_SetLcdForceBlack(u8 flags)
Sets whether to force the LCD to black.
void gspExit(void)
Exits GSPGPU.
Result GSPGPU_FlushDataCache(const void *adr, u32 size)
Flushes memory from the data cache.
Result GSPGPU_AcquireRight(u8 flags)
Acquires GPU rights.
void gspSetEventCallback(GSPGPU_Event id, ThreadFunc cb, void *data, bool oneShot)
Configures a callback to run when a GSPGPU event occurs.
Result gspSubmitGxCommand(const u32 gxCommand[0x8])
Submits a GX command.
Handle * gspGetSessionHandle(void)
Gets a pointer to the current gsp::Gpu session handle.
Result GSPGPU_SetLedForceOff(bool disable)
Sets 3D_LEDSTATE to the input state value.
Result GSPGPU_RegisterInterruptRelayQueue(Handle eventHandle, u32 flags, Handle *outMemHandle, u8 *threadID)
Registers the interrupt relay queue.
Result GSPGPU_SaveVramSysArea(void)
Saves the VRAM sys area.
Result GSPGPU_RestoreVramSysArea(void)
Restores the VRAM sys area.
Result GSPGPU_ImportDisplayCaptureInfo(GSPGPU_CaptureInfo *captureinfo)
Retrieves display capture info.
Result GSPGPU_WriteHWRegs(u32 regAddr, const u32 *data, u8 size)
Writes to GPU hardware registers.
Result GSPGPU_UnregisterInterruptRelayQueue(void)
Unregisters the interrupt relay queue.
GSPGPU_Event gspWaitForAnyEvent(void)
Waits for any GSPGPU event to occur.
static unsigned gspGetBytesPerPixel(GSPGPU_FramebufferFormat format)
Gets the number of bytes per pixel for the specified format.
Definition: gspgpu.h:70
void gspWaitForEvent(GSPGPU_Event id, bool nextEvent)
Waits for a GSPGPU event to occur.
Result GSPGPU_ReleaseRight(void)
Releases GPU rights.
Result GSPGPU_TriggerCmdReqQueue(void)
Triggers a handling of commands written to shared memory.
bool gspHasGpuRight(void)
Returns true if the application currently has GPU rights.
Result GSPGPU_InvalidateDataCache(const void *adr, u32 size)
Invalidates memory in the data cache.
bool gspPresentBuffer(unsigned screen, unsigned swap, const void *fb_a, const void *fb_b, u32 stride, u32 mode)
Presents a buffer to the specified screen.
Result GSPGPU_WriteHWRegsWithMask(u32 regAddr, const u32 *data, u8 datasize, const u32 *maskdata, u8 masksize)
Writes to GPU hardware registers with a mask.
GSPGPU_FramebufferFormat
Framebuffer format.
Definition: gspgpu.h:28
@ GSP_RGB5_A1_OES
RGB5A1. (2 bytes)
Definition: gspgpu.h:32
@ GSP_RGBA4_OES
RGBA4. (2 bytes)
Definition: gspgpu.h:33
@ GSP_BGR8_OES
BGR8. (3 bytes)
Definition: gspgpu.h:30
@ GSP_RGBA8_OES
RGBA8. (4 bytes)
Definition: gspgpu.h:29
@ GSP_RGB565_OES
RGB565. (2 bytes)
Definition: gspgpu.h:31
Result GSPGPU_ResetGpuCore(void)
Resets the GPU.
Result GSPGPU_ReadHWRegs(u32 regAddr, u32 *data, u8 size)
Reads from GPU hardware registers.
Result GSPGPU_SetBufferSwap(u32 screenid, const GSPGPU_FramebufferInfo *framebufinfo)
Updates a screen's framebuffer state.
Capture info entry.
Definition: gspgpu.h:38
u32 format
Framebuffer format.
Definition: gspgpu.h:41
u32 * framebuf1_vaddr
Right framebuffer.
Definition: gspgpu.h:40
u32 * framebuf0_vaddr
Left framebuffer.
Definition: gspgpu.h:39
u32 framebuf_widthbytesize
Framebuffer pitch.
Definition: gspgpu.h:42
Capture info.
Definition: gspgpu.h:47
Framebuffer information.
Definition: gspgpu.h:16
u32 unk
Unknown.
Definition: gspgpu.h:23
u32 framebuf_widthbytesize
Value for 0x1EF00X90, controls framebuffer width.
Definition: gspgpu.h:20
u32 format
Framebuffer format, this u16 is written to the low u16 for LCD register 0x1EF00X70.
Definition: gspgpu.h:21
u32 * framebuf0_vaddr
Framebuffer virtual address, for the main screen this is the 3D left framebuffer.
Definition: gspgpu.h:18
u32 active_framebuf
Active framebuffer. (0 = first, 1 = second)
Definition: gspgpu.h:17
u32 * framebuf1_vaddr
For the main screen: 3D right framebuffer address.
Definition: gspgpu.h:19
u32 framebuf_dispselect
Value for 0x1EF00X78, controls which framebuffer is displayed.
Definition: gspgpu.h:22
void(* ThreadFunc)(void *)
Thread entrypoint function.
Definition: types.h:43
uint8_t u8
would be nice if newlib had this already
Definition: types.h:21
u32 Handle
Resource handle.
Definition: types.h:41
s32 Result
Function result.
Definition: types.h:42
uint32_t u32
32-bit unsigned integer
Definition: types.h:23