SDL::RendererRef Struct Reference

Handle to a non owned renderer. More...

Inheritance diagram for SDL::RendererRef:

Public Member Functions
constexpr	RendererRef (const RendererRef &other)
	Copy constructor.
constexpr	RendererRef (RendererRef &&other)
	Move constructor.
constexpr	~RendererRef ()=default
	Default constructor.
RendererRef &	operator= (RendererRef other)
	Assignment operator.
void	reset (SDL_Renderer *newResource={})
	Destroy the rendering context for a window and free all associated textures.
	RendererBase (WindowRef window)
	Create a 2D rendering context for a window.
	RendererBase (WindowBase &window, StringParam name)
	Create a 2D rendering context for a window.
	RendererBase (PropertiesBase &props)
	Create a 2D rendering context for a window, with the specified properties.
	RendererBase (SurfaceBase &surface)
	Create a 2D software rendering context for a surface.
Public Member Functions inherited from SDL::RendererBase
	RendererBase (WindowRef window)
	Create a 2D rendering context for a window.
	RendererBase (WindowBase &window, StringParam name)
	Create a 2D rendering context for a window.
	RendererBase (PropertiesBase &props)
	Create a 2D rendering context for a window, with the specified properties.
	RendererBase (SurfaceBase &surface)
	Create a 2D software rendering context for a surface.
WindowRef	GetWindow ()
	Get the window associated with a renderer.
const char *	GetName () const
	Get the name of a renderer.
Point	GetOutputSize () const
	Get the output size in pixels of a rendering context.
void	GetOutputSize (int *w, int *h) const
	Get the output size in pixels of a rendering context.
Point	GetCurrentOutputSize () const
	Get the current output size in pixels of a rendering context.
void	GetCurrentOutputSize (int *w, int *h) const
	Get the current output size in pixels of a rendering context.
PropertiesRef	GetProperties () const
	Get the properties associated with a renderer.
void	ResetTarget ()
	Set target texture back to window.
void	SetTarget (OptionalTexture texture)
	Set a texture as the current rendering target.
TextureRef	GetTarget () const
	Get the current render target.
void	SetLogicalPresentation (SDL_Point size, RendererLogicalPresentation mode)
	Set a device-independent resolution and presentation mode for rendering.
void	GetLogicalPresentation (SDL_Point *size, RendererLogicalPresentation *mode)
	Get device independent resolution and presentation mode for rendering.
void	GetLogicalPresentation (int *w, int *h, RendererLogicalPresentation *mode) const
	Get device independent resolution and presentation mode for rendering.
FRect	GetLogicalPresentationRect () const
	Get the final presentation rectangle for rendering.
FPoint	RenderCoordinatesFromWindow (const SDL_FPoint &window_coord) const
	Get a point in render coordinates when given a point in window coordinates.
FPoint	RenderCoordinatesToWindow (const SDL_FPoint &coord) const
	Get a point in window coordinates when given a point in render coordinates.
void	ConvertEventToRenderCoordinates (Event *event) const
	Convert the coordinates in an event to render coordinates.
void	ResetViewport ()
	Reset the drawing area for rendering to the entire target.
void	SetViewport (OptionalRef< const SDL_Rect > rect)
	Set the drawing area for rendering on the current target.
Rect	GetViewport () const
	Get the drawing area for the current target.
bool	IsViewportSet () const
	Return whether an explicit rectangle was set as the viewport.
Rect	GetSafeArea () const
	Get the safe area for rendering within the current viewport.
void	ResetClipRect ()
	Reset the clip rectangle for rendering to the entire render target.
void	SetClipRect (OptionalRef< const SDL_Rect > rect)
	Set the clip rectangle for rendering on the specified target.
Rect	GetClipRect () const
	Get the clip rectangle for the current target.
bool	IsClipEnabled () const
	Get whether clipping is enabled on the given render target.
void	SetScale (SDL_FPoint scale)
	Set the drawing scale for rendering on the current target.
FPoint	GetScale () const
	Get the drawing scale for the current target.
void	GetScale (float *scaleX, float *scaleY) const
	Get the drawing scale for the current target.
void	SetDrawColor (SDL_Color c)
	Set the color used for drawing operations.
void	SetDrawColor (SDL_FColor c)
	Set the color used for drawing operations (Rect, Line and Clear).
FColor	GetDrawColor () const
	Get the color used for drawing operations (Rect, Line and Clear).
void	GetDrawColor (SDL_Color *c) const
	Get the color used for drawing operations (Rect, Line and Clear).
void	GetDrawColor (SDL_FColor *c) const
	Get the color used for drawing operations (Rect, Line and Clear).
void	GetDrawColor (Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a) const
	Get the color used for drawing operations (Rect, Line and Clear).
void	GetDrawColor (float *r, float *g, float *b, float *a) const
	Get the color used for drawing operations (Rect, Line and Clear).
void	SetColorScale (float scale)
	Set the color scale used for render operations.
float	GetColorScale () const
	Get the color scale used for render operations.
void	SetDrawBlendMode (BlendMode blendMode)
	Set the blend mode used for drawing operations (Fill and Line).
BlendMode	GetDrawBlendMode () const
	Get the blend mode used for drawing operations.
void	RenderClear ()
	Clear the current rendering target with the drawing color.
void	RenderPoint (SDL_FPoint p)
	Draw a point on the current rendering target at subpixel precision.
void	RenderPoints (SpanRef< const SDL_FPoint > points)
	Draw multiple points on the current rendering target at subpixel precision.
void	RenderLine (SDL_FPoint p1, SDL_FPoint p2)
	Draw a line on the current rendering target at subpixel precision.
void	RenderLines (SpanRef< const SDL_FPoint > points)
	Draw a series of connected lines on the current rendering target at subpixel precision.
void	RenderRect (OptionalRef< const SDL_FRect > rect)
	Draw a rectangle on the current rendering target at subpixel precision.
void	RenderRects (SpanRef< const SDL_FRect > rects)
	Draw some number of rectangles on the current rendering target at subpixel precision.
void	RenderFillRect (OptionalRef< const SDL_FRect > rect)
	Fill a rectangle on the current rendering target with the drawing color at subpixel precision.
void	RenderFillRects (SpanRef< const SDL_FRect > rects)
	Fill some number of rectangles on the current rendering target with the drawing color at subpixel precision.
void	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	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	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	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	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	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	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).
Surface	ReadPixels (OptionalRef< const SDL_Rect > rect={}) const
	Read pixels from the current rendering target.
void	Present ()
	Update the screen with any rendering performed since the previous call.
void	Flush ()
	Force the rendering context to flush any pending commands and state.
void	SetVSync (int vsync)
	Toggle VSync of the given renderer.
int	GetVSync () const
	Get VSync of the given renderer.
void	RenderDebugText (FPoint p, StringParam str)
	Draw debug text to an RendererBase.
template<class... ARGS>
void	RenderDebugTextFormat (FPoint p, std::string_view fmt, ARGS... args)
	Draw debug text to an SDL_Renderer.
constexpr	Resource (T resource={})
	Constructs the underlying resource.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
	Resource (const Resource &other)=delete
	Resource (Resource &&other)=delete
Public Member Functions inherited from SDL::Resource< SDL_Renderer * >
constexpr	Resource (SDL_Renderer * resource={})
	Constructs the underlying resource.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
	Resource (const Resource &other)=delete
	Resource (Resource &&other)=delete
Resource &	operator= (const Resource &other)=delete
Resource &	operator= (Resource &&other)=delete
constexpr	operator bool () const
	True if contains a valid resource.
constexpr bool	operator== (const Resource &other) const=default
	Comparison.
constexpr bool	operator== (std::nullopt_t) const
	Comparison.
constexpr bool	operator== (std::nullptr_t) const
	Comparison.
constexpr SDL_Renderer *	get () const
	Return contained resource;.
constexpr SDL_Renderer *	release (SDL_Renderer * newResource={})
	Return contained resource and empties or replace value.
constexpr const SDL_Renderer *	operator-> () const
	Access to fields.
constexpr SDL_Renderer *	operator-> ()
	Access to fields.

Detailed Description

Category:

Resource

See also

RendererBase

Renderer

Member Function Documentation

RendererBase() [1/4]

SDL::RendererBase::RendererBase ( PropertiesBase &  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 RendererBase.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.

It renderer creation fails for any reason this object is falsy; call GetError() for more information.

Parameters

props

the properties to use.

Postcondition

a valid rendering context.

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.Properties

RendererBase.GetName

RendererBase() [2/4]

SDL::RendererBase::RendererBase ( SurfaceBase &  surface )

inline

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

Parameters

surface

the Surface structure representing the surface where rendering is done.

Postcondition

a valid rendering context.

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.

RendererBase() [3/4]

SDL::RendererBase::RendererBase ( WindowBase &  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 RendererBase.SetLogicalPresentation() to change the content size and scaling options.

It renderer creation fails for any reason this object is falsy; call GetError() for more information.

Parameters

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

Postcondition

a valid rendering context.

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

GetNumRenderDrivers

GetRenderDriver

RendererBase.GetName

RendererBase() [4/4]

SDL::RendererBase::RendererBase ( WindowRef  window )

inline

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

It renderer creation fails for any reason this object is falsy; call GetError() for more information.

Parameters

window

the window where rendering is displayed.

Thread safety:

This function should only be called on the main thread.

reset()

void SDL::RendererRef::reset ( SDL_Renderer *  newResource = {} )

inline

This should be called before destroying the associated window.

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

---

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

• SDL3pp/SDL3pp_render.h