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); 

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); 

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.