gfx.h File Reference

Simple framebuffer API. More...

`#include <3ds/types.h>`
`#include <3ds/services/gspgpu.h>`

Go to the source code of this file.

## Macros

#define | RGB565(r, g, b) (((b)&0x1f)|(((g)&0x3f)<<5)|(((r)&0x1f)<<11))
| Converts red, green, and blue components to packed RGB565.
#define | RGB8_to_565(r, g, b) (((b)>>3)&0x1f)|((((g)>>2)&0x3f)<<5)|((((r)>>3)&0x1f)<<11)
| Converts packed RGB8 to packed RGB565.

## Enumerations

enum | gfxScreen_t { GFX_TOP = GSP_SCREEN_TOP , GFX_BOTTOM = GSP_SCREEN_BOTTOM }
| Screen IDs. More...
enum | gfx3dSide_t { GFX_LEFT = 0 , GFX_RIGHT = 1 }
| Top screen framebuffer side. More...

## Functions

Initialization and deinitialization
void | gfxInitDefault (void)
| Initializes the LCD framebuffers with default parameters This is equivalent to calling: More...
void | gfxInit (GSPGPU_FramebufferFormat topFormat, GSPGPU_FramebufferFormat bottomFormat, bool vrambuffers)
| Initializes the LCD framebuffers. More...
void | gfxExit (void)
| Deinitializes and frees the LCD framebuffers. More...
Control
void | gfxSet3D (bool enable)
| Enables or disables the 3D stereoscopic effect on the top screen. More...
bool | gfxIs3D (void)
| Retrieves the status of the 3D stereoscopic effect on the top screen. More...
bool | gfxIsWide (void)
| Retrieves the status of the 800px (double-height) high resolution display mode of the top screen. More...
void | gfxSetWide (bool enable)
| Enables or disables the 800px (double-height) high resolution display mode of the top screen. More...
void | gfxSetScreenFormat (gfxScreen_t screen, GSPGPU_FramebufferFormat format)
| Changes the pixel format of a screen. More...
GSPGPU_FramebufferFormat | gfxGetScreenFormat (gfxScreen_t screen)
| Retrieves the current pixel format of a screen. More...
void | gfxSetDoubleBuffering (gfxScreen_t screen, bool enable)
| Enables or disables double buffering on a screen. More...
Rendering and presentation
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. More...
void | gfxFlushBuffers (void)
| Flushes the data cache for the current framebuffers. More...
void | gfxScreenSwapBuffers (gfxScreen_t scr, bool hasStereo)
| Updates the configuration of the specified screen, swapping the buffers if double buffering is enabled. More...
CTR_DEPRECATED void | gfxConfigScreen (gfxScreen_t scr, bool immediate)
| Same as gfxScreenSwapBuffers, but with hasStereo set to true. More...
void | gfxSwapBuffers (void)
| Updates the configuration of both screens. More...
void | gfxSwapBuffersGpu (void)
| Same as gfxSwapBuffers (formerly different).

## Detailed Description

Simple framebuffer API.

This API provides basic functionality needed to bring up framebuffers for both screens, as well as managing display mode (stereoscopic 3D) and double buffering. It is mainly an abstraction over the gsp service.

Please note that the 3DS uses portrait screens rotated 90 degrees counterclockwise. Width/height refer to the physical dimensions of the screen; that is, the top screen is 240 pixels wide and 400 pixels tall; while the bottom screen is 240x320.

## Enumeration Type Documentation

## gfx3dSide_t

enum gfx3dSide_t

Top screen framebuffer side.

This is only meaningful when stereoscopic 3D is enabled on the top screen. In any other case, use GFX_LEFT.

Enumerator
GFX_LEFT | Left eye framebuffer.
GFX_RIGHT | Right eye framebuffer.

## gfxScreen_t

enum gfxScreen_t

Screen IDs.

Enumerator
GFX_TOP | Top screen.
GFX_BOTTOM | Bottom screen.

## Function Documentation

## gfxConfigScreen()

CTR_DEPRECATED void gfxConfigScreen | ( | gfxScreen_t | scr,
|  | bool | immediate
| ) |  |

Same as gfxScreenSwapBuffers, but with hasStereo set to true.

Parameters

  scr | Screen ID (see gfxScreen_t)
  immediate | This parameter no longer has any effect and is thus ignored.

Deprecated:
  This function has been superseded by gfxScreenSwapBuffers, please use that instead.

## gfxExit()

void gfxExit | ( | void |  | ) |

Deinitializes and frees the LCD framebuffers.

Note
  This function internally calls gspExit.

Examples
  app_launch/source/main.c, audio/filters/source/main.c, audio/mic/source/main.c, audio/streaming/source/main.c, camera/image/source/main.c, camera/video/source/main.c, get_system_language/source/main.c, graphics/bitmap/24bit-color/source/main.c, graphics/gpu/both_screens/source/main.c, graphics/gpu/fragment_light/source/main.c, graphics/gpu/geoshader/source/main.c, graphics/gpu/gpusprites/source/main.c, graphics/gpu/immediate/source/main.c, graphics/gpu/lenny/source/main.c, graphics/gpu/loop_subdivision/source/main.c, graphics/gpu/mipmap_fog/source/main.c, graphics/gpu/particles/source/main.c, graphics/gpu/proctex/source/main.c, graphics/gpu/simple_tri/source/main.c, graphics/gpu/textured_cube/source/main.c, graphics/gpu/toon_shading/source/main.c, graphics/printing/both-screen-text/source/main.c, graphics/printing/colored-text/source/main.c, graphics/printing/hello-world/source/main.c, graphics/printing/multiple-windows-text/source/main.c, graphics/printing/system-font/source/main.c, input/read-controls/source/main.c, input/software-keyboard/source/main.c, input/touch-screen/source/main.c, libapplet_launch/source/main.c, mvd/source/main.c, network/boss/source/main.c, network/http/source/main.c, network/http_post/source/main.c, network/sockets/source/sockets.c, network/sslc/source/ssl.c, network/uds/source/uds.c, nfc/source/main.c, romfs/source/main.c, sdmc/source/main.c, threads/event/source/main.c, threads/thread-basic/source/main.c, and time/rtc/source/main.c.

## gfxFlushBuffers()

void gfxFlushBuffers | ( | void |  | ) |

Flushes the data cache for the current framebuffers.

Warning
  This is only used during software rendering. Since this function has significant overhead, it is preferred to call this only once per frame, after all software rendering is completed.

Examples
  audio/filters/source/main.c, audio/mic/source/main.c, audio/streaming/source/main.c, camera/image/source/main.c, camera/video/source/main.c, get_system_language/source/main.c, graphics/bitmap/24bit-color/source/main.c, graphics/printing/both-screen-text/source/main.c, graphics/printing/colored-text/source/main.c, graphics/printing/hello-world/source/main.c, graphics/printing/multiple-windows-text/source/main.c, input/read-controls/source/main.c, input/software-keyboard/source/main.c, input/touch-screen/source/main.c, libapplet_launch/source/main.c, mvd/source/main.c, network/boss/source/main.c, network/http/source/main.c, network/http_post/source/main.c, network/sslc/source/ssl.c, network/uds/source/uds.c, threads/event/source/main.c, threads/thread-basic/source/main.c, and time/rtc/source/main.c.

## gfxGetFramebuffer()

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.

Parameters

  screen | Screen ID (see gfxScreen_t)
  side | Framebuffer side (see gfx3dSide_t) (pass GFX_LEFT if not using stereoscopic 3D)
  width | Pointer that will hold the width of the framebuffer in pixels.
  height | Pointer that will hold the height of the framebuffer in pixels.

Returns
  A pointer to the current framebuffer of the chosen screen.

Please remember that the returned pointer will change every frame if double buffering is enabled.

Examples
  camera/image/source/main.c, camera/video/source/main.c, graphics/bitmap/24bit-color/source/main.c, mvd/source/main.c, network/http/source/main.c, and sdmc/source/main.c.

## gfxGetScreenFormat()

GSPGPU_FramebufferFormat gfxGetScreenFormat | ( | gfxScreen_t | screen | ) |

Retrieves the current pixel format of a screen.

Parameters

  screen | Screen ID (see gfxScreen_t)

Returns
  Pixel format (see GSPGPU_FramebufferFormat)

## gfxInit()

void gfxInit | ( | GSPGPU_FramebufferFormat | topFormat,
|  | GSPGPU_FramebufferFormat | bottomFormat,
|  | bool | vrambuffers
| ) |  |

Initializes the LCD framebuffers.

Parameters

  topFormat | The format of the top screen framebuffers.
  bottomFormat | The format of the bottom screen framebuffers.
  vramBuffers | Whether to allocate the framebuffers in VRAM.

This function allocates memory for the framebuffers in the specified memory region. Initially, stereoscopic 3D is disabled and double buffering is enabled.

Note
  This function internally calls gspInit.

Examples
  mvd/source/main.c.

## gfxInitDefault()

void gfxInitDefault | ( | void |  | ) |

Initializes the LCD framebuffers with default parameters This is equivalent to calling:

gfxInit(GSP_BGR8_OES,GSP_BGR8_OES,false);
gfxInit
void gfxInit(GSPGPU_FramebufferFormat topFormat, GSPGPU_FramebufferFormat bottomFormat, bool vrambuffers)
Initializes the LCD framebuffers.
GSP_BGR8_OES
@ GSP_BGR8_OES
BGR8. (3 bytes)
Definition: gspgpu.h:30

Examples
  app_launch/source/main.c, audio/filters/source/main.c, audio/mic/source/main.c, audio/streaming/source/main.c, camera/image/source/main.c, camera/video/source/main.c, get_system_language/source/main.c, graphics/bitmap/24bit-color/source/main.c, graphics/gpu/both_screens/source/main.c, graphics/gpu/fragment_light/source/main.c, graphics/gpu/geoshader/source/main.c, graphics/gpu/gpusprites/source/main.c, graphics/gpu/immediate/source/main.c, graphics/gpu/lenny/source/main.c, graphics/gpu/loop_subdivision/source/main.c, graphics/gpu/mipmap_fog/source/main.c, graphics/gpu/particles/source/main.c, graphics/gpu/proctex/source/main.c, graphics/gpu/simple_tri/source/main.c, graphics/gpu/textured_cube/source/main.c, graphics/gpu/toon_shading/source/main.c, graphics/printing/both-screen-text/source/main.c, graphics/printing/colored-text/source/main.c, graphics/printing/hello-world/source/main.c, graphics/printing/multiple-windows-text/source/main.c, graphics/printing/system-font/source/main.c, input/read-controls/source/main.c, input/software-keyboard/source/main.c, input/touch-screen/source/main.c, libapplet_launch/source/main.c, network/boss/source/main.c, network/http/source/main.c, network/http_post/source/main.c, network/sockets/source/sockets.c, network/sslc/source/ssl.c, network/uds/source/uds.c, nfc/source/main.c, romfs/source/main.c, sdmc/source/main.c, threads/event/source/main.c, threads/thread-basic/source/main.c, and time/rtc/source/main.c.

## gfxIs3D()

bool gfxIs3D | ( | void |  | ) |

Retrieves the status of the 3D stereoscopic effect on the top screen.

Returns
  true if 3D enabled, false otherwise.

## gfxIsWide()

bool gfxIsWide | ( | void |  | ) |

Retrieves the status of the 800px (double-height) high resolution display mode of the top screen.

Returns
  true if wide mode enabled, false otherwise.

## gfxScreenSwapBuffers()

void gfxScreenSwapBuffers | ( | gfxScreen_t | scr,
|  | bool | hasStereo
| ) |  |

Updates the configuration of the specified screen, swapping the buffers if double buffering is enabled.

Parameters

  scr | Screen ID (see gfxScreen_t)
  hasStereo | For the top screen in 3D mode: true if the framebuffer contains individual images for both eyes, or false if the left image should be duplicated to the right eye.

Note
  Previously rendered content will be displayed on the screen after the next VBlank.
  This function is still useful even if double buffering is disabled, as it must be used to commit configuration changes.

Warning
  Only call this once per screen per frame, otherwise graphical glitches will occur since this API does not implement triple buffering.

## gfxSet3D()

void gfxSet3D | ( | bool | enable | ) |

Enables or disables the 3D stereoscopic effect on the top screen.

Parameters

  enable | Pass true to enable, false to disable.

Note
  Stereoscopic 3D is disabled by default.

Examples
  camera/image/source/main.c, camera/video/source/main.c, graphics/gpu/fragment_light/source/main.c, graphics/gpu/lenny/source/main.c, graphics/gpu/particles/source/main.c, and graphics/gpu/toon_shading/source/main.c.

## gfxSetDoubleBuffering()

void gfxSetDoubleBuffering | ( | gfxScreen_t | screen,
|  | bool | enable
| ) |  |

Enables or disables double buffering on a screen.

Parameters

  screen | Screen ID (see gfxScreen_t)
  enable | Pass true to enable, false to disable.

Note
  Double buffering is enabled by default.

Examples
  camera/image/source/main.c, camera/video/source/main.c, and graphics/bitmap/24bit-color/source/main.c.

## gfxSetScreenFormat()

void gfxSetScreenFormat | ( | gfxScreen_t | screen,
|  | GSPGPU_FramebufferFormat | format
| ) |  |

Changes the pixel format of a screen.

Parameters

  screen | Screen ID (see gfxScreen_t)
  format | Pixel format (see GSPGPU_FramebufferFormat)

Note
  If the currently allocated framebuffers are too small for the specified format, they are freed and new ones are reallocated.

## gfxSetWide()

void gfxSetWide | ( | bool | enable | ) |

Enables or disables the 800px (double-height) high resolution display mode of the top screen.

Parameters

  enable | Pass true to enable, false to disable.

Note
  Wide mode is disabled by default.
  Wide and stereoscopic 3D modes are mutually exclusive.
  In wide mode pixels are not square, since scanlines are half as tall as they normally are.

Warning
  Wide mode does not work on Old 2DS consoles (however it does work on New 2DS XL consoles).

## gfxSwapBuffers()

void gfxSwapBuffers | ( | void |  | ) |

Updates the configuration of both screens.

Note
  This function is equivalent to:
  gfxScreenSwapBuffers(GFX_TOP,true); gfxScreenSwapBuffers(GFX_BOTTOM,true);
  GFX_BOTTOM
  @ GFX_BOTTOM
  Bottom screen.
  Definition: gfx.h:27
  GFX_TOP
  @ GFX_TOP
  Top screen.
  Definition: gfx.h:26
  gfxScreenSwapBuffers
  void gfxScreenSwapBuffers(gfxScreen_t scr, bool hasStereo)
  Updates the configuration of the specified screen, swapping the buffers if double buffering is enable...

Examples
  app_launch/source/main.c, audio/filters/source/main.c, audio/mic/source/main.c, audio/streaming/source/main.c, camera/image/source/main.c, camera/video/source/main.c, get_system_language/source/main.c, graphics/bitmap/24bit-color/source/main.c, graphics/printing/both-screen-text/source/main.c, graphics/printing/colored-text/source/main.c, graphics/printing/hello-world/source/main.c, graphics/printing/multiple-windows-text/source/main.c, input/read-controls/source/main.c, input/software-keyboard/source/main.c, input/touch-screen/source/main.c, libapplet_launch/source/main.c, network/boss/source/main.c, network/http/source/main.c, network/http_post/source/main.c, network/sslc/source/ssl.c, network/uds/source/uds.c, threads/event/source/main.c, threads/thread-basic/source/main.c, and time/rtc/source/main.c.