Header file for SDL 2D rendering functions. More...

Classes
struct	SDL::RendererBase
	A structure representing rendering state. More...

struct	SDL::RendererRef
	Handle to a non owned renderer. More...

struct	SDL::Renderer
	Handle to an owned renderer. More...

struct	SDL::TextureBase
	An efficient driver-specific representation of pixel data. More...

struct	SDL::TextureRef
	Handle to a non owned texture. More...

struct	SDL::Texture
	Handle to an owned texture. More...

class	SDL::TextureLock
	Locks a Texture for access to its pixels. More...

Macros
#define	SDL_SOFTWARE_RENDERER "software"
	The name of the software renderer.

#define	SDL_RENDERER_VSYNC_DISABLED 0
	Disable vsync.

#define	SDL_RENDERER_VSYNC_ADAPTIVE (-1)
	Adaptative vsync.

#define	SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8
	The size, in pixels, of a single RendererBase.RenderDebugText() character.

Typedefs
using	SDL::OptionalTexture = OptionalResource< TextureRef, Texture >
	A texture parameter that might own its value.

using	SDL::Vertex = SDL_Vertex
	Vertex structure.

using	SDL::TextureAccess = SDL_TextureAccess
	The access pattern allowed for a texture.

using	SDL::RendererLogicalPresentation = SDL_RendererLogicalPresentation
	How the logical size is mapped to the output.

Functions
int	SDL::GetNumRenderDrivers ()
	Get the number of 2D rendering drivers available for the current display.

const char *	SDL::GetRenderDriver (int index)
	Use this function to get the name of a built in 2D rendering driver.

std::pair< Window, Renderer >	SDL::CreateWindowAndRenderer (StringParam title, SDL_Point size, WindowFlags window_flags=0)
	Create a window and default renderer.

void *	SDL::GetRenderMetalLayer (RendererBase &renderer)
	Get the CAMetalLayer associated with the given Metal renderer.

void *	SDL::GetRenderMetalCommandEncoder (RendererBase &renderer)
	Get the Metal command encoder for the current frame.

void	SDL::AddVulkanRenderSemaphores (RendererBase &renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore)
	Add a set of synchronization semaphores for the current frame.

Texture	SDL::LoadTextureBMP (RendererBase &renderer, IOStreamBase &src)
	Load a BMP texture from a seekable SDL data stream.

Texture	SDL::LoadTextureBMP (RendererBase &renderer, StringParam file)
	Load a BMP texture from a file.

RendererRef	SDL::WindowBase::GetRenderer () const
	Get the renderer associated with a window.

void	SDL::RendererBase::SetTarget (OptionalTexture texture)
	Set a texture as the current rendering target.

TextureRef	SDL::RendererBase::GetTarget () const
	Get the current render target.

void	SDL::RendererBase::RenderTexture (TextureBase &texture, OptionalRef< const SDL_FRect > srcrect, OptionalRef< const SDL_FRect > dstrect)
	Copy a portion of the texture to the current rendering target at subpixel precision.

void	SDL::RendererBase::RenderTextureRotated (TextureBase &texture, OptionalRef< const SDL_FRect > srcrect, OptionalRef< const SDL_FRect > dstrect, double angle, OptionalRef< const SDL_FPoint > center={}, FlipMode flip=SDL_FLIP_NONE)
	Copy a portion of the source texture to the current rendering target, with rotation and flipping, at subpixel precision.

void	SDL::RendererBase::RenderTextureAffine (TextureBase &texture, OptionalRef< const SDL_FRect > srcrect, OptionalRef< const SDL_FPoint > origin, OptionalRef< const SDL_FPoint > right, OptionalRef< const SDL_FPoint > down)
	Copy a portion of the source texture to the current rendering target, with affine transform, at subpixel precision.

void	SDL::RendererBase::RenderTextureTiled (TextureBase &texture, OptionalRef< const SDL_FRect > srcrect, float scale, OptionalRef< const SDL_FRect > dstrect)
	Tile a portion of the texture to the current rendering target at subpixel precision.

void	SDL::RendererBase::RenderTexture9Grid (TextureBase &texture, OptionalRef< const SDL_FRect > srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, OptionalRef< const SDL_FRect > dstrect)
	Perform a scaled copy using the 9-grid algorithm to the current rendering target at subpixel precision.

void	SDL::RendererBase::RenderGeometry (OptionalTexture texture, std::span< const Vertex > vertices, std::span< const int > indices={})
	Render a list of triangles, optionally using a texture and indices into the vertex array Color and alpha modulation is done per vertex (TextureBase.SetColorMod and TextureBase.SetAlphaMod are ignored).

void	SDL::RendererBase::RenderGeometryRaw (OptionalTexture texture, const float xy, int xy_stride, const FColor color, int color_stride, const float uv, int uv_stride, int num_vertices, const void indices, int num_indices, int size_indices)
	Render a list of triangles, optionally using a texture and indices into the vertex arrays Color and alpha modulation is done per vertex (TextureBase.SetColorMod and TextureBase.SetAlphaMod are ignored).

void	SDL::RendererBase::ResetTarget ()
	Set target texture back to window.

TextureLock	SDL::TextureBase::Lock (OptionalRef< const SDL_Rect > rect={}) &
	Lock a portion of the texture for write-only pixel access.

Variables
constexpr TextureAccess	SDL::TEXTUREACCESS_STATIC
	Changes rarely, not lockable.

constexpr TextureAccess	SDL::TEXTUREACCESS_STREAMING
	Changes frequently, lockable.

constexpr TextureAccess	SDL::TEXTUREACCESS_TARGET
	Texture can be used as a render target.

constexpr RendererLogicalPresentation	SDL::LOGICAL_PRESENTATION_DISABLED
	There is no logical size in effect.

constexpr RendererLogicalPresentation	SDL::LOGICAL_PRESENTATION_STRETCH
	The rendered content is stretched to the output resolution.

constexpr RendererLogicalPresentation	SDL::LOGICAL_PRESENTATION_LETTERBOX
	The rendered content is fit to the largest dimension and the other dimension is letterboxed with black bars.

constexpr RendererLogicalPresentation	SDL::LOGICAL_PRESENTATION_OVERSCAN
	The rendered content is fit to the smallest dimension and the other dimension extends beyond the output bounds.

constexpr RendererLogicalPresentation	SDL::LOGICAL_PRESENTATION_INTEGER_SCALE
	The rendered content is scaled up by integer multiples to fit the output resolution.

Detailed Description

This API supports the following features:

single pixel points
single pixel lines
filled rectangles
texture images
2D polygons

The primitives may be drawn in opaque, blended, or additive modes.

The texture images may be drawn in opaque, blended, or additive modes. They can have an additional color tint or alpha modulation applied to them, and may also be stretched with linear interpolation.

This API is designed to accelerate simple 2D operations. You may want more functionality such as polygons and particle effects and in that case you should use SDL's OpenGL/Direct3D support, the SDL3 GPU API, or one of the many good 3D engines.

These functions must be called from the main thread. See this bug for details: https://github.com/libsdl-org/SDL/issues/986

Macro Definition Documentation

◆ SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE

#define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8

The font is monospaced and square, so this applies to all characters.

Since: This macro is available since SDL 3.2.0.

See also: RendererBase.RenderDebugText

◆ SDL_SOFTWARE_RENDERER

#define SDL_SOFTWARE_RENDERER "software"

Since: This macro is available since SDL 3.2.0.

Typedef Documentation

◆ OptionalTexture

using SDL::OptionalTexture = typedef OptionalResource<TextureRef, Texture>

This is designed to be used on parameter's type and accepts that accepts a std::nullopt, a non-owned TextureRef or an owned Texture

◆ RendererLogicalPresentation

using SDL::RendererLogicalPresentation = typedef SDL_RendererLogicalPresentation

Since: This enum is available since SDL 3.2.0.

◆ TextureAccess

using SDL::TextureAccess = typedef SDL_TextureAccess

Since: This enum is available since SDL 3.2.0.

◆ Vertex

using SDL::Vertex = typedef SDL_Vertex

Since: This struct is available since SDL 3.2.0.

Function Documentation

◆ AddVulkanRenderSemaphores()

void SDL::AddVulkanRenderSemaphores	(	RendererBase &	renderer,
		Uint32	wait_stage_mask,
		Sint64	wait_semaphore,
		Sint64	signal_semaphore
	)

inline

The Vulkan renderer will wait for wait_semaphore before submitting rendering commands and signal signal_semaphore after rendering commands are complete for this frame.

This should be called each frame that you want semaphore synchronization. The Vulkan renderer may have multiple frames in flight on the GPU, so you should have multiple semaphores that are used for synchronization. Querying prop::Renderer.VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER will give you the maximum number of semaphores you'll need.

Parameters

renderer	the rendering context.
wait_stage_mask	the VkPipelineStageFlags for the wait.
wait_semaphore	a VkSempahore to wait on before rendering the current frame, or 0 if not needed.
signal_semaphore	a VkSempahore that SDL will signal when rendering for the current frame is complete, or 0 if not needed.

Exceptions

Error on failure.

Thread safety:: It is NOT safe to call this function from two threads at once.

Since: This function is available since SDL 3.2.0.

◆ CreateWindowAndRenderer()

std::pair< Window, Renderer > SDL::CreateWindowAndRenderer	(	StringParam	title,
		SDL_Point	size,
		WindowFlags	window_flags = `0`
	)

inline

Parameters

title	the title of the window, in UTF-8 encoding.
size	the width and height of the window.
window_flags	the flags used to create the window (see WindowBase.WindowBase()).

Returns: a pair with Window and Renderer on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RendererBase; WindowBase.WindowBase

◆ GetNumRenderDrivers()

int SDL::GetNumRenderDrivers ( )

inline

A render driver is a set of code that handles rendering and texture management on a particular display. Normally there is only one, but some drivers may have several available with different capabilities.

There may be none if SDL was compiled without render support.

Returns: the number of built in render drivers.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RendererBase; GetRenderDriver

◆ GetRenderDriver()

const char * SDL::GetRenderDriver ( int index )

inline

The list of rendering drivers is given in the order that they are normally initialized by default; the drivers that seem more reasonable to choose first (as far as the SDL developers believe) are earlier in the list.

The names of drivers are all simple, low-ASCII identifiers, like "opengl", "direct3d12" or "metal". These never have Unicode characters, and are not meant to be proper names.

Parameters

index the index of the rendering driver; the value ranges from 0 to GetNumRenderDrivers() - 1.

Returns: the name of the rendering driver at the requested index, or nullptr if an invalid index was specified.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetNumRenderDrivers

◆ GetRenderer()

RendererRef SDL::WindowBase::GetRenderer ( ) const

inline

Returns: the rendering context on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetRenderMetalCommandEncoder()

void * SDL::GetRenderMetalCommandEncoder ( RendererBase & renderer )

inline

This function returns void *, so SDL doesn't have to include Metal's headers, but it can be safely cast to an id<MTLRenderCommandEncoder>.

This will return nullptr if Metal refuses to give SDL a drawable to render to, which might happen if the window is hidden/minimized/offscreen. This doesn't apply to command encoders for render targets, just the window's backbuffer. Check your return values!

Parameters

renderer the renderer to query.

Returns: an id<MTLRenderCommandEncoder> on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetRenderMetalLayer

◆ GetRenderMetalLayer()

void * SDL::GetRenderMetalLayer ( RendererBase & renderer )

inline

This function returns void *, so SDL doesn't have to include Metal's headers, but it can be safely cast to a CAMetalLayer *.

Parameters

renderer the renderer to query.

Returns: a CAMetalLayer * on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetRenderMetalCommandEncoder

◆ GetTarget()

TextureRef SDL::RendererBase::GetTarget ( ) const

inline

The default render target is the window for which the renderer was created, and is reported a nullptr here.

Returns: the current render target or nullptr for the default render target.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.SetTarget

◆ LoadTextureBMP() [1/2]

Texture SDL::LoadTextureBMP	(	RendererBase &	renderer,
		IOStreamBase &	src
	)

inline

Parameters

renderer	the renderer to create texture
src	the data stream for the surface.

Returns: a Texture with loaded content or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ LoadTextureBMP() [2/2]

Texture SDL::LoadTextureBMP	(	RendererBase &	renderer,
		StringParam	file
	)

inline

Parameters

renderer	the renderer to create texture
file	the BMP file to load.

Returns: a Texture with loaded content or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ Lock()

TextureLock SDL::TextureBase::Lock ( OptionalRef< const SDL_Rect > rect = {} ) &

inline

As an optimization, the pixels made available for editing don't necessarily contain the old texture data. This is a write-only operation, and if you need to keep a copy of the texture data you should do that at the application level.

You must use TextureLock.Unlock() to unlock the pixels and apply any changes.

Parameters

rect	an Rect structure representing the area to lock for access; nullptr to lock the entire texture.

Returns: TextureLock on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: TextureLock.Unlock

◆ RenderGeometry()

void SDL::RendererBase::RenderGeometry	(	OptionalTexture	texture,
		std::span< const Vertex >	vertices,
		std::span< const int >	indices = `{}`
	)

inline

Parameters

texture	(optional) The SDL texture to use.
vertices	vertices.
indices	(optional) An array of integer indices into the 'vertices' array, if nullptr all vertices will be rendered in sequential order.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RenderGeometryRaw

◆ RenderGeometryRaw()

void SDL::RendererBase::RenderGeometryRaw	(	OptionalTexture	texture,
		const float *	xy,
		int	xy_stride,
		const FColor *	color,
		int	color_stride,
		const float *	uv,
		int	uv_stride,
		int	num_vertices,
		const void *	indices,
		int	num_indices,
		int	size_indices
	)

inline

Parameters

texture	(optional) The SDL texture to use.
xy	vertex positions.
xy_stride	byte size to move from one element to the next element.
color	vertex colors (as FColor).
color_stride	byte size to move from one element to the next element.
uv	vertex normalized texture coordinates.
uv_stride	byte size to move from one element to the next element.
num_vertices	number of vertices.
indices	(optional) An array of indices into the 'vertices' arrays, if nullptr all vertices will be rendered in sequential order.
num_indices	number of indices.
size_indices	index size: 1 (byte), 2 (short), 4 (int).

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RenderGeometry

◆ RenderTexture()

void SDL::RendererBase::RenderTexture	(	TextureBase &	texture,
		OptionalRef< const SDL_FRect >	srcrect,
		OptionalRef< const SDL_FRect >	dstrect
	)

inline

Parameters

texture	the source texture.
srcrect	a pointer to the source rectangle, or nullptr for the entire texture.
dstrect	a pointer to the destination rectangle, or nullptr for the entire rendering target.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RenderTextureRotated; RendererBase.RenderTextureTiled

◆ RenderTexture9Grid()

void SDL::RendererBase::RenderTexture9Grid	(	TextureBase &	texture,
		OptionalRef< const SDL_FRect >	srcrect,
		float	left_width,
		float	right_width,
		float	top_height,
		float	bottom_height,
		float	scale,
		OptionalRef< const SDL_FRect >	dstrect
	)

inline

The pixels in the texture are split into a 3x3 grid, using the different corner sizes for each corner, and the sides and center making up the remaining pixels. The corners are then scaled using scale and fit into the corners of the destination rectangle. The sides and center are then stretched into place to cover the remaining destination rectangle.

Parameters

texture	the source texture.
srcrect	the Rect structure representing the rectangle to be used for the 9-grid, or nullptr to use the entire texture.
left_width	the width, in pixels, of the left corners in `srcrect`.
right_width	the width, in pixels, of the right corners in `srcrect`.
top_height	the height, in pixels, of the top corners in `srcrect`.
bottom_height	the height, in pixels, of the bottom corners in `srcrect`.
scale	the scale used to transform the corner of `srcrect` into the corner of `dstrect`, or 0.0f for an unscaled copy.
dstrect	a pointer to the destination rectangle, or nullptr for the entire rendering target.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RenderTexture

◆ RenderTextureAffine()

void SDL::RendererBase::RenderTextureAffine	(	TextureBase &	texture,
		OptionalRef< const SDL_FRect >	srcrect,
		OptionalRef< const SDL_FPoint >	origin,
		OptionalRef< const SDL_FPoint >	right,
		OptionalRef< const SDL_FPoint >	down
	)

inline

Parameters

texture	the source texture.
srcrect	a pointer to the source rectangle, or nullptr for the entire texture.
origin	a pointer to a point indicating where the top-left corner of srcrect should be mapped to, or nullptr for the rendering target's origin.
right	a pointer to a point indicating where the top-right corner of srcrect should be mapped to, or nullptr for the rendering target's top-right corner.
down	a pointer to a point indicating where the bottom-left corner of srcrect should be mapped to, or nullptr for the rendering target's bottom-left corner.

Exceptions

Error on failure.

Thread safety:: You may only call this function from the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RenderTexture

◆ RenderTextureRotated()

void SDL::RendererBase::RenderTextureRotated	(	TextureBase &	texture,
		OptionalRef< const SDL_FRect >	srcrect,
		OptionalRef< const SDL_FRect >	dstrect,
		double	angle,
		OptionalRef< const SDL_FPoint >	center = `{}`,
		FlipMode	flip = `SDL_FLIP_NONE`
	)

inline

Parameters

texture	the source texture.
srcrect	a pointer to the source rectangle, or nullptr for the entire texture.
dstrect	a pointer to the destination rectangle, or nullptr for the entire rendering target.
angle	an angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction.
center	a pointer to a point indicating the point around which dstrect will be rotated (if nullptr, rotation will be done around dstrect.w/2, dstrect.h/2).
flip	an FlipMode value stating which flipping actions should be performed on the texture.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RenderTexture

◆ RenderTextureTiled()

void SDL::RendererBase::RenderTextureTiled	(	TextureBase &	texture,
		OptionalRef< const SDL_FRect >	srcrect,
		float	scale,
		OptionalRef< const SDL_FRect >	dstrect
	)

inline

The pixels in srcrect will be repeated as many times as needed to completely fill dstrect.

Parameters

texture	the source texture.
srcrect	a pointer to the source rectangle, or nullptr for the entire texture.
scale	the scale used to transform srcrect into the destination rectangle, e.g. a 32x32 texture with a scale of 2 would fill 64x64 tiles.
dstrect	a pointer to the destination rectangle, or nullptr for the entire rendering target.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.RenderTexture

◆ ResetTarget()

void SDL::RendererBase::ResetTarget ( )

inline

This is equivalent to SetTarget(nullptr)

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: SetTarget(nullptr); GetTarget()

◆ SetTarget()

void SDL::RendererBase::SetTarget ( OptionalTexture texture )

inline

The default render target is the window for which the renderer was created. To stop rendering to a texture and render to the window again, call this function with a nullptr texture.

Viewport, cliprect, scale, and logical presentation are unique to each render target. Get and set functions for these states apply to the current render target set by this function, and those states persist on each target when the current render target changes.

Parameters

texture the targeted texture, which must be created with the TEXTUREACCESS_TARGET flag, or nullptr to render to the window instead of a texture.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: RendererBase.GetTarget

SDL_TEXTUREACCESS_TARGET

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE

◆ SDL_SOFTWARE_RENDERER

Typedef Documentation

◆ OptionalTexture

◆ RendererLogicalPresentation

◆ TextureAccess

◆ Vertex

Function Documentation

◆ AddVulkanRenderSemaphores()

◆ CreateWindowAndRenderer()

◆ GetNumRenderDrivers()

◆ GetRenderDriver()

◆ GetRenderer()

◆ GetRenderMetalCommandEncoder()

◆ GetRenderMetalLayer()

◆ GetTarget()

◆ LoadTextureBMP() [1/2]

◆ LoadTextureBMP() [2/2]

◆ Lock()

◆ RenderGeometry()

◆ RenderGeometryRaw()

◆ RenderTexture()

◆ RenderTexture9Grid()

◆ RenderTextureAffine()

◆ RenderTextureRotated()

◆ RenderTextureTiled()

◆ ResetTarget()

◆ SetTarget()

Variable Documentation

◆ LOGICAL_PRESENTATION_DISABLED

◆ LOGICAL_PRESENTATION_INTEGER_SCALE

◆ LOGICAL_PRESENTATION_LETTERBOX

◆ LOGICAL_PRESENTATION_OVERSCAN

◆ LOGICAL_PRESENTATION_STRETCH

◆ TEXTUREACCESS_STATIC

◆ TEXTUREACCESS_STREAMING

◆ TEXTUREACCESS_TARGET