A structure representing rendering state. More...

Inheritance diagram for SDL::Renderer:

Public Member Functions
constexpr	Renderer ()=default
	Default ctor.

constexpr	Renderer (const RendererRaw resource)
	Constructs from RendererParam. More...

constexpr	Renderer (const Renderer &other)=delete
	Copy constructor.

constexpr	Renderer (Renderer &&other)
	Move constructor.

constexpr	Renderer (const RendererRef &other)=delete

constexpr	Renderer (RendererRef &&other)=delete

	Renderer (WindowParam window)
	Create a 2D rendering context for a window. More...

	Renderer (WindowParam window, StringParam name)
	Create a 2D rendering context for a window. More...

	Renderer (PropertiesParam props)
	Create a 2D rendering context for a window, with the specified properties. More...

	Renderer (SurfaceParam surface)
	Create a 2D software rendering context for a surface. More...

	~Renderer ()
	Destructor.

Renderer &	operator= (Renderer other)
	Assignment operator.

constexpr RendererRaw	get () const
	Retrieves underlying RendererRaw.

constexpr RendererRaw	release ()
	Retrieves underlying RendererRaw and clear this.

constexpr auto	operator<=> (const Renderer &other) const =default
	Comparison.

constexpr bool	operator== (std::nullptr_t _) const
	Comparison.

constexpr	operator bool () const
	Converts to bool.

constexpr	operator RendererParam () const
	Converts to RendererParam.

void	Destroy ()
	Destroy the rendering context for a window and free all associated textures. More...

WindowRef	GetWindow ()
	Get the window associated with a renderer. More...

const char *	GetName () const
	Get the name of a renderer. More...

Point	GetOutputSize () const
	Get the output size in pixels of a rendering context. More...

void	GetOutputSize (int w, int h) const
	Get the output size in pixels of a rendering context. More...

Point	GetCurrentOutputSize () const
	Get the current output size in pixels of a rendering context. More...

void	GetCurrentOutputSize (int w, int h) const
	Get the current output size in pixels of a rendering context. More...

PropertiesRef	GetProperties () const
	Get the properties associated with a renderer. More...

void	ResetTarget ()
	Set target texture back to window. More...

void	SetTarget (TextureParam texture)
	Set a texture as the current rendering target. More...

Texture	GetTarget () const
	Get the current render target. More...

void	SetLogicalPresentation (const PointRaw &size, RendererLogicalPresentation mode)
	Set a device-independent resolution and presentation mode for rendering. More...

void	GetLogicalPresentation (PointRaw size, RendererLogicalPresentation mode)
	Get device independent resolution and presentation mode for rendering. More...

void	GetLogicalPresentation (int w, int h, RendererLogicalPresentation *mode) const
	Get device independent resolution and presentation mode for rendering. More...

FRect	GetLogicalPresentationRect () const
	Get the final presentation rectangle for rendering. More...

FPoint	RenderCoordinatesFromWindow (const FPointRaw &window_coord) const
	Get a point in render coordinates when given a point in window coordinates. More...

FPoint	RenderCoordinatesToWindow (const FPointRaw &coord) const
	Get a point in window coordinates when given a point in render coordinates. More...

void	ConvertEventToRenderCoordinates (Event *event) const
	Convert the coordinates in an event to render coordinates. More...

void	ResetViewport ()
	Reset the drawing area for rendering to the entire target. More...

void	SetViewport (OptionalRef< const RectRaw > rect)
	Set the drawing area for rendering on the current target. More...

Rect	GetViewport () const
	Get the drawing area for the current target. More...

bool	IsViewportSet () const
	Return whether an explicit rectangle was set as the viewport. More...

Rect	GetSafeArea () const
	Get the safe area for rendering within the current viewport. More...

void	ResetClipRect ()
	Reset the clip rectangle for rendering to the entire render target. More...

void	SetClipRect (OptionalRef< const RectRaw > rect)
	Set the clip rectangle for rendering on the specified target. More...

Rect	GetClipRect () const
	Get the clip rectangle for the current target. More...

bool	IsClipEnabled () const
	Get whether clipping is enabled on the given render target. More...

void	SetScale (const FPointRaw &scale)
	Set the drawing scale for rendering on the current target. More...

FPoint	GetScale () const
	Get the drawing scale for the current target. More...

void	GetScale (float scaleX, float scaleY) const
	Get the drawing scale for the current target. More...

void	SetDrawColor (ColorRaw c)
	Set the color used for drawing operations. More...

void	SetDrawColorFloat (const FColorRaw &c)
	Set the color used for drawing operations (Rect, Line and Clear). More...

Color	GetDrawColor () const
	Get the color used for drawing operations (Rect, Line and Clear). More...

void	GetDrawColor (Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
	Get the color used for drawing operations (Rect, Line and Clear). More...

FColor	GetDrawColorFloat () const
	Get the color used for drawing operations (Rect, Line and Clear). More...

void	GetDrawColorFloat (float r, float g, float b, float a) const
	Get the color used for drawing operations (Rect, Line and Clear). More...

void	SetColorScale (float scale)
	Set the color scale used for render operations. More...

float	GetColorScale () const
	Get the color scale used for render operations. More...

void	SetDrawBlendMode (BlendMode blendMode)
	Set the blend mode used for drawing operations (Fill and Line). More...

BlendMode	GetDrawBlendMode () const
	Get the blend mode used for drawing operations. More...

void	RenderClear ()
	Clear the current rendering target with the drawing color. More...

void	RenderPoint (const FPointRaw &p)
	Draw a point on the current rendering target at subpixel precision. More...

void	RenderPoints (SpanRef< const FPointRaw > points)
	Draw multiple points on the current rendering target at subpixel precision. More...

void	RenderLine (const FPointRaw &p1, const FPointRaw &p2)
	Draw a line on the current rendering target at subpixel precision. More...

void	RenderLines (SpanRef< const FPointRaw > points)
	Draw a series of connected lines on the current rendering target at subpixel precision. More...

void	RenderRect (OptionalRef< const FRectRaw > rect)
	Draw a rectangle on the current rendering target at subpixel precision. More...

void	RenderRects (SpanRef< const FRectRaw > rects)
	Draw some number of rectangles on the current rendering target at subpixel precision. More...

void	RenderFillRect (OptionalRef< const FRectRaw > rect)
	Fill a rectangle on the current rendering target with the drawing color at subpixel precision. More...

void	RenderFillRects (SpanRef< const FRectRaw > rects)
	Fill some number of rectangles on the current rendering target with the drawing color at subpixel precision. More...

void	RenderTexture (TextureParam texture, OptionalRef< const FRectRaw > srcrect, OptionalRef< const FRectRaw > dstrect)
	Copy a portion of the texture to the current rendering target at subpixel precision. More...

void	RenderTextureRotated (TextureParam texture, OptionalRef< const FRectRaw > srcrect, OptionalRef< const FRectRaw > dstrect, double angle, OptionalRef< const FPointRaw > center, FlipMode flip=FlipMode::SDL_FLIP_NONE)
	Copy a portion of the source texture to the current rendering target, with rotation and flipping, at subpixel precision. More...

void	RenderTextureAffine (TextureParam texture, OptionalRef< const FRectRaw > srcrect, OptionalRef< const FPointRaw > origin, OptionalRef< const FPointRaw > right, OptionalRef< const FPointRaw > down)
	Copy a portion of the source texture to the current rendering target, with affine transform, at subpixel precision. More...

void	RenderTextureTiled (TextureParam texture, OptionalRef< const FRectRaw > srcrect, float scale, OptionalRef< const FRectRaw > dstrect)
	Tile a portion of the texture to the current rendering target at subpixel precision. More...

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

void	RenderGeometry (TextureParam 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 (Texture.SetColorMod and Texture.SetAlphaMod are ignored). More...

void	RenderGeometryRaw (TextureParam 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 (Texture.SetColorMod and Texture.SetAlphaMod are ignored). More...

Surface	ReadPixels (OptionalRef< const RectRaw > rect={}) const
	Read pixels from the current rendering target. More...

void	Present ()
	Update the screen with any rendering performed since the previous call. More...

void	Flush ()
	Force the rendering context to flush any pending commands and state. More...

void	SetVSync (int vsync)
	Toggle VSync of the given renderer. More...

int	GetVSync () const
	Get VSync of the given renderer. More...

void	RenderDebugText (const FPointRaw &p, StringParam str)
	Draw debug text to an Renderer. More...

template<class... ARGS>
void	RenderDebugTextFormat (const FPointRaw &p, std::string_view fmt, ARGS... args)
	Draw debug text to an Renderer. More...

Texture	CreateTexture (PixelFormat format, TextureAccess access, const PointRaw &size)
	Create a texture for a rendering context. More...

Texture	CreateTextureFromSurface (SurfaceParam surface)
	Create a texture from an existing surface. More...

Texture	CreateTextureWithProperties (PropertiesParam props)
	Create a texture for a rendering context with the specified properties. More...

void *	GetRenderMetalLayer ()
	Get the CAMetalLayer associated with the given Metal renderer. More...

void *	GetRenderMetalCommandEncoder ()
	Get the Metal command encoder for the current frame. More...

void	AddVulkanRenderSemaphores (Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore)
	Add a set of synchronization semaphores for the current frame. More...

Detailed Description

Since: This struct is available since SDL 3.2.0.

Category:: Resource

Constructor & Destructor Documentation

◆ Renderer() [1/5]

constexpr SDL::Renderer::Renderer ( const RendererRaw resource )

inlineexplicitconstexpr

Parameters

resource a RendererRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

◆ Renderer() [2/5]

SDL::Renderer::Renderer ( WindowParam window )

inline

If you want a specific renderer, you can specify its name here. A list of available renderers can be obtained by calling GetRenderDriver() multiple times, with indices from 0 to GetNumRenderDrivers()-1. If you don't need a specific renderer, specify nullptr and SDL will attempt to choose the best option for you, based on what is available on the user's system.

If name is a comma-separated list, SDL will try each name, in the order listed, until one succeeds or all of them fail.

By default the rendering size matches the window size in pixels, but you can call Renderer.SetLogicalPresentation() to change the content size and scaling options.

Parameters

window the window where rendering is displayed.

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: Renderer.Renderer; Renderer.Renderer; Renderer.Destroy; GetNumRenderDrivers; GetRenderDriver; Renderer.GetName

◆ Renderer() [3/5]

SDL::Renderer::Renderer	(	WindowParam	window,
		StringParam	name
	)

inline

If you want a specific renderer, you can specify its name here. A list of available renderers can be obtained by calling GetRenderDriver() multiple times, with indices from 0 to GetNumRenderDrivers()-1. If you don't need a specific renderer, specify nullptr and SDL will attempt to choose the best option for you, based on what is available on the user's system.

If name is a comma-separated list, SDL will try each name, in the order listed, until one succeeds or all of them fail.

By default the rendering size matches the window size in pixels, but you can call Renderer.SetLogicalPresentation() to change the content size and scaling options.

Parameters

window	the window where rendering is displayed.
name	the name of the rendering driver to initialize, or nullptr to let SDL choose one.

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: Renderer.Renderer; Renderer.Renderer; Renderer.Destroy; GetNumRenderDrivers; GetRenderDriver; Renderer.GetName

◆ Renderer() [4/5]

SDL::Renderer::Renderer ( PropertiesParam props )

inline

These are the supported properties:

prop::Renderer.CREATE_NAME_STRING: the name of the rendering driver to use, if a specific one is desired
prop::Renderer.CREATE_WINDOW_POINTER: the window where rendering is displayed, required if this isn't a software renderer using a surface
prop::Renderer.CREATE_SURFACE_POINTER: the surface where rendering is displayed, if you want a software renderer without a window
prop::Renderer.CREATE_OUTPUT_COLORSPACE_NUMBER: an Colorspace value describing the colorspace for output to the display, defaults to COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers support COLORSPACE_SRGB_LINEAR, which is a linear color space and supports HDR output. If you select COLORSPACE_SRGB_LINEAR, drawing still uses the sRGB colorspace, but values can go beyond 1.0 and float (linear) format textures can be used for HDR content.
prop::Renderer.CREATE_PRESENT_VSYNC_NUMBER: non-zero if you want present synchronized with the refresh rate. This property can take any value that is supported by Renderer.SetVSync() for the renderer.

With the vulkan renderer:

prop::Renderer.CREATE_VULKAN_INSTANCE_POINTER: the VkInstance to use with the renderer, optional.
prop::Renderer.CREATE_VULKAN_SURFACE_NUMBER: the VkSurfaceKHR to use with the renderer, optional.
prop::Renderer.CREATE_VULKAN_PHYSICAL_DEVICE_POINTER: the VkPhysicalDevice to use with the renderer, optional.
prop::Renderer.CREATE_VULKAN_DEVICE_POINTER: the VkDevice to use with the renderer, optional.
prop::Renderer.CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER: the queue family index used for rendering.
prop::Renderer.CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER: the queue family index used for presentation.

Parameters

props the properties to use.

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: Properties.Create; Renderer.Renderer; Renderer.Renderer; Renderer.Destroy; Renderer.GetName

◆ Renderer() [5/5]

SDL::Renderer::Renderer ( SurfaceParam surface )

inline

Two other API which can be used to create Renderer: Renderer.Renderer() and CreateWindowAndRenderer(). These can also create a software renderer, but they are intended to be used with an Window as the final destination and not an Surface.

Parameters

surface the Surface structure representing the surface where rendering is done.

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: Renderer.Destroy

Member Function Documentation

◆ GetCurrentOutputSize()

Point SDL::Renderer::GetCurrentOutputSize ( ) const

inline

If a rendering target is active, this will return the size of the rendering target in pixels, otherwise if a logical size is set, it will return the logical size, otherwise it will return the value of GetOutputSize().

Returns: the size 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: Renderer.GetOutputSize()

◆ GetDrawColor()

Color SDL::Renderer::GetDrawColor ( ) const

inline

Returns: the color channel values used to draw on the 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: GetDrawColor(SDL_FColor*); SetDrawColor()

◆ GetDrawColorFloat()

FColor SDL::Renderer::GetDrawColorFloat ( ) const

inline

Returns: the color 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: GetDrawColor(SDL_FColor*); SetDrawColor()

◆ GetLogicalPresentation()

void SDL::Renderer::GetLogicalPresentation	(	PointRaw *	size,
		RendererLogicalPresentation *	mode
	)

inline

This function gets the width and height of the logical rendering output, or the output size in pixels if a logical resolution is not enabled.

Parameters

size	a Point to be filled with the width and height.
mode	the presentation mode used.

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: Renderer.SetLogicalPresentation

◆ GetOutputSize()

Point SDL::Renderer::GetOutputSize ( ) const

inline

This returns the true output size in pixels, ignoring any render targets or logical size and presentation.

Returns: Point on success.

Exceptions

Error on failure.

◆ GetScale()

FPoint SDL::Renderer::GetScale ( ) const

inline

Each render target has its own scale. This function gets the scale for the current render target.

Returns: the scaling factors 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: Renderer.SetScale

◆ ResetClipRect()

void SDL::Renderer::ResetClipRect ( )

inline

This is equivalent to SetClipRect(std::nullopt)

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: GetClipRect(); SetClipRect(); ClipEnabled()

◆ ResetTarget()

void SDL::Renderer::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()

◆ ResetViewport()

void SDL::Renderer::ResetViewport ( )

inline

This is equivalent to SetViewport(std::nullopt)

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: GetViewport(); SetViewport(); ViewportSet()

The documentation for this class was generated from the following file:

SDL3pp/SDL3pp_render.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Renderer() [1/5]

◆ Renderer() [2/5]

◆ Renderer() [3/5]

◆ Renderer() [4/5]

◆ Renderer() [5/5]

Member Function Documentation

◆ GetCurrentOutputSize()

◆ GetDrawColor()

◆ GetDrawColorFloat()

◆ GetLogicalPresentation()

◆ GetOutputSize()

◆ GetScale()

◆ ResetClipRect()

◆ ResetTarget()

◆ ResetViewport()