Class Renderer

Namespace: Sdl3Sharp.Video.Rendering

Assembly: Sdl3Sharp.dll

Represents a rendering context (renderer)

public abstract class Renderer : IDisposable

Inheritance: object

Renderer

Implements: IDisposable

Derived: Renderer<TDriver>

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This is used to perform driver-specific 2D rendering operations, most commonly to a Window or an off-screen render target.

You can create new renderers for a Window using the TryCreateRenderer(out Renderer?, params ReadOnlySpan<string>) or TryCreateRenderer(out Renderer?, string?, ColorSpace?, RendererVSync?, Properties?) instance methods on a Window instance.

If you create textures using a Renderer, please remember to dispose them before disposing the renderer. Do not dispose the associated Window before disposing the Renderer either! Using an Renderer after its associated Window has been disposed can cause undefined behavior, including crashes.

For the most part Renderers are not thread-safe, and most of their properties and methods should only be accessed from the main thread!

Renderers are not driver-agnostic! Most of the time instance of this abstract class are of the concrete Renderer<TDriver> type with a specific rendering driver as the type argument. However, the Renderer type exists as an abstraction to use common rendering operations.

To specify a concrete renderer type, use Renderer<TDriver> with a rendering driver that implements the IRenderingDriver interface (e.g. Renderer<OpenGL>).

Properties

ClippingRect

Gets or sets the clipping rectangle for the current target

public Rect<int> ClippingRect { get; set; }

Property Value

Rect<int>: The clipping rectangle for the current target

Remarks

If the value of this property is equal to the target's bounds, clipping is effectively disabled.

Alternatively, you can use the IsClippingEnabled property to check whether clipping is enabled or not, and the ResetClippingRect() method to reset the clipping rectangle.

Each render target, Window or Target (or get_Surface(Renderer<Software>) in the case of a software renderer), has its own clipping rectangle. This property reflects the clipping rectangle of the current target.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

ColorScale

Gets or sets the color scale for render operations

public float ColorScale { get; set; }

Property Value

float: The color scale for render operations

Remarks

The color scale is an additional scale multiplied into the pixel color value while rendering. This can be used to adjust the brightness of colors during HDR rendering, or changing HDR video brightness when playing on an SDR display.

The color scale does not affect the alpha channel, only the color brightness.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

CurrentOutputSize

Gets the current output size for the renderer

public (int Width, int Height) CurrentOutputSize { get; }

Property Value

(int Width, int Height): The current output size for the renderer, in pixels

Remarks

If a rendering target is active, the value of this property will be the size of that target, otherwise it will be equal to the value of the OutputSize property.

Either way, the resulting size will be adjusted by the current logical presentation state, dictated by the LogicalPresentation property.

This property should only be accessed from the main thread.

Exceptions

SdlException: When getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

DefaultTextureScaleMode

Gets or sets the default scale mode for new textures created by the renderer

public ScaleMode DefaultTextureScaleMode { get; set; }

Property Value

ScaleMode: The default scale mode for new textures created by the renderer

Remarks

The value of this property defaults to Linear for newly created renderers.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

DrawBlendMode

Gets or sets the blend mode for drawing operations

public BlendMode DrawBlendMode { get; set; }

Property Value

BlendMode

Remarks

Drawing operations that make use of the blend mode defined by this property include, but are not limited to: TryRenderDebugText(float, float, string), TryRenderDebugText(float, float, string, params ReadOnlySpan<object>), TryRenderFilledRect(in Rect<float>), TryRenderFilledRects(ReadOnlySpan<Rect<float>>), TryRenderLine(float, float, float, float), TryRenderLines(ReadOnlySpan<Point<float>>), TryRenderPoint(float, float), TryRenderPoints(ReadOnlySpan<Point<float>>), TryRenderRect(), TryRenderRect(in Rect<float>), and TryRenderRects(ReadOnlySpan<Rect<float>>).

This property should only be accessed from the main thread.

Exceptions

SdlException

When setting this property, the specified blend is Invalid or not supported by the renderer (check TryGet(out string?) for more information)

OR - When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

DrawColor

Gets or sets the color used for drawing operations

public Color<byte> DrawColor { get; set; }

Property Value

Color<byte>: The color used for drawing operations

Remarks

In addition to that, DrawColor also defines the color used for clearing the current render target when using the TryClear() method.

The DrawBlendMode specifies how the alpha component of this property is used in drawing operations.

The component values of this property are equivalent to the component values of the DrawColorFloat property, multiplied by 255 and rounded towards zero.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

DrawColorFloat

Gets or sets the color used for drawing operations

public Color<float> DrawColorFloat { get; set; }

Property Value

Color<float>: The color used for drawing operations

Remarks

In addition to that, DrawColorFloat also defines the color used for clearing the current render target when using the TryClear() method.

The DrawBlendMode specifies how the alpha component of this property is used in drawing operations.

The component values of this property are equivalent to the component values of the DrawColor property, divided by 255.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

HdrHeadroom

Gets the additional high dynamic range that can be displayed, in terms of the SDR white point

public float HdrHeadroom { get; }

Property Value

float: The additional high dynamic range that can be displayed, in terms of the SDR white point

Remarks

The value of this property will be 1.0 when HDR is not enabled.

The value of this property can change dynamically at runtime when a WindowHdrStateChanged event (WindowEvent) is sent.

IsClippingEnabled

Gets a value indicating whether clipping on the current target is enabled or not

public bool IsClippingEnabled { get; }

Property Value

bool: A value indicating whether clipping on the current target is enabled or not

Remarks

Each render target, Window or Target (or get_Surface(Renderer<Software>) in the case of a software renderer), has its own clipping state. This property reflects the clipping state of the current target.

This property should only be accessed from the main thread.

IsHdrEnabled

Gets a value indicating whether the renderer is presenting to a display with HDR enabled

public bool IsHdrEnabled { get; }

Property Value

bool: A value indicating whether the renderer is presenting to a display with HDR enabled

Remarks

The value of this property can change dynamically at runtime when a WindowHdrStateChanged event (WindowEvent) is sent.

IsViewportSet

Gets a value indicating whether an explicit rectangle was set as the current Viewport for the renderer

public bool IsViewportSet { get; }

Property Value

bool: A value indicating whether an explicit rectangle was set as the current Viewport for the renderer

Remarks

This is useful if you're saving and restoring the Viewport and want to know whether you should restore a specific rectangle or not.

Each render target, Window or Target (or get_Surface(Renderer<Software>) in the case of a software renderer), has its own viewport. This property reflects the viewport of the current target.

This property should only be accessed from the main thread.

LogicalPresentation

Gets or sets the device-independent resolution and presentation mode for rendering

public (int Width, int Height, RendererLogicalPresentation Mode) LogicalPresentation { get; set; }

Property Value

(int Width, int Height, RendererLogicalPresentation Mode): The device-independent resolution and presentation mode for rendering

Remarks

The value of this property specifies the width and height of the logical rendering output. The renderer will act as if the current target is always the specified size, scaling to the actual resolution as necessary.

This can be useful for games and applications that expect a fixed size, but would like to scale the output to whatever is available, regardless of how a user resizes a window, or if the display is high DPI.

Logical presentation is disabled if the mode is set to Disabled, in which case the logical presentation size will be equal to the output size of the current target. It is safe to toggle the logical presentation mode during the rendering of a frame. E.g. you can do most of the rendering to a specified logical resolution, but to make text look sharper, you can temporarily disable logical presentation when rendering text.

It might be useful to draw to a texture that matches the window dimensions with logical presentation enabled, and then draw that texture across the entire window with logical presentation disabled. Be careful not to render both with logical presentation enabled, however, as this could produce double-letterboxing, etc.

Coordinates coming from an event can be converted to rendering coordinates using the Sdl3Sharp.Events.EventExtensions.TryConvertToRenderCoordinates<TEvent, TRenderer>(ref TEvent, TRenderer) method.

Each render target, Window or Target (or get_Surface(Renderer<Software>) in the case of a software renderer), has its own logical presentation size and mode. This property reflects the logical presentation size and mode of the current target.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

LogicalPresentationRect

Gets the final presentation rectangle for rendering

public Rect<float> LogicalPresentationRect { get; }

Property Value

Rect<float>: The final presentation rectangle for rendering, in pixels

Remarks

This property should only be accessed from the main thread.

Exceptions

SdlException: When getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

MaximumTextureSize

Gets the maximum texture size supported by the renderer

public int MaximumTextureSize { get; }

Property Value

int: The maximum texture size supported by the renderer, in pixels

Remarks

The value of this property is in regards to both width and height of the texture. E.g. if the value is 4096, then the renderer supports textures up to 4096⨯4096 in size.

Name

Gets the name of the rendering driver used by the renderer

public string? Name { get; }

Property Value

string: The name of the rendering driver used by the renderer, or null if the name is not available

Remarks

The value of this property can be compared to the name of any pre-defined rendering driver implementing the IRenderingDriver interface to determine whether the renderer is using that driver.

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

You can see AvailableDriverNames for a list of the names of all available rendering drivers in the current environment.

OutputColorSpace

Gets the color space used by the renderer for presenting to the output display

public ColorSpace OutputColorSpace { get; }

Property Value

ColorSpace: The color space used by the renderer for presenting to the output display

OutputSize

Gets the output size for the renderer

public (int Width, int Height) OutputSize { get; }

Property Value

(int Width, int Height): The output size for the renderer, in pixels

Remarks

The value of this property is the true output size in pixels, ignoring any render targets or logical presentation settings.

To get the output size of the current target, adjusted by the current logical presentation settings, use the CurrentOutputSize property instead.

This property should only be accessed from the main thread.

Exceptions

SdlException: When getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

Properties

Gets the properties associated with the renderer

public Properties? Properties { get; }

Property Value

Properties: The properties associated with the renderer, or null if the properties could not be retrieved successfully (check TryGet(out string?) for more information)

SafeArea

Gets the safe area for rendering within the current viewport

public Rect<int> SafeArea { get; }

Property Value

Rect<int>: The safe area for rendering within the current viewport, in pixels

Remarks

Some devices have portions of the screen which are partially obscured or not interactive, possibly due to on-screen controls, curved edges, camera notches, TV overscan, etc. This property provides the area of the current viewport which is safe to have interactible content. You should continue rendering into the rest of the render target, but it should not contain visually important or interactible content.

This property should only be accessed from the main thread.

Exceptions

SdlException: When getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

Scale

Gets or sets the drawing scales for rendering on the current target

public (float ScaleX, float ScaleY) Scale { get; set; }

Property Value

(float Integer, float Fractional): The drawing scales for rendering on the current target

Remarks

The drawing coordinates are scaled by the values of this property before they are used by the renderer. This allows for resolution-independent drawing with a single coordinate system.

If this results in scaling or subpixel drawing by the rendering backend, it will be handled using the appropriate quality hints. For best results use integer scaling factors.

Each render target, Window or Target (or get_Surface(Renderer<Software>) in the case of a software renderer), has its own drawing scales. This property reflects the drawing scales of the current target.

This property should only be accessed from the main thread.

Exceptions

SdlException: When getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

SdrWhitePoint

Gets the SDR white point in the SrgbLinear color space

public float SdrWhitePoint { get; }

Property Value

float: The SDR white point in the SrgbLinear color space

Remarks

The value of this property is automatically multiplied into the color scale when HDR is enabled.

The value of this property can change dynamically at runtime when a WindowHdrStateChanged event (WindowEvent) is sent.

SupportedTextureFormats

Gets the texture formats supported by the renderer

public IEnumerable<PixelFormat> SupportedTextureFormats { get; }

Property Value

IEnumerable<PixelFormat>: The texture formats supported by the renderer

Remarks

For performance reasons, the resulting collection is enumerated lazily, so the actual enumeration of the supported texture formats is deferred until you start enumerating over the collection.

Because of that, the fact that you can enumerate the result just a single time, and the fact that the enumeration itself is quite an expensive operation, you should consider caching the result into a persistent collection.

Note that the enumerator returned by this property can throw an InvalidOperationException if the reference to the texture formats is invalid or if it changes during the enumeration.

SupportsNonPowerOfTwoTextureWrapping

Gets a value indicating whether the renderer supports texture address wrapping on non-power-of-two textures

public bool SupportsNonPowerOfTwoTextureWrapping { get; }

Property Value

bool: A value indicating whether the renderer supports texture address wrapping on non-power-of-two textures

Remarks

The value of this property determines whether the renderer supports Wrap on textures that don't have power-of-two dimensions.

Texture address wrapping is always supported for power-of-two texture sizes.

Target

Gets the current render target

public Texture? Target { get; set; }

Property Value

Texture: The current render target, or null if the default render target is active

Remarks

If the value of this property is null, then the default render target is active. The default render target is the Window associated with the renderer, the Surface associated with a software renderer, or the off-screen target associated with a GPU renderer.

You can reset the current render target to the default render target by either setting this property to null, or by using the ResetTarget() method.

Only textures created with this renderer can be used as render targets, and only if they were created with the Target access mode.

This property should only be accessed from the main thread.

Exceptions

ObjectDisposedException

When setting this property, the specified texture was already disposed

SdlException

When setting this property, the specified texture is not a valid render target (e.g. it wasn't created with the Target access mode, or it wasn't created with this renderer) (check TryGet(out string?) for more information)

OR - When setting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

TextureAddressMode

Gets or sets the texture address modes used in TryRenderGeometry(ReadOnlySpan<Vertex>, Texture?) and TryRenderGeometry(ReadOnlySpan<Vertex>, ReadOnlySpan<int>, Texture?)

public (TextureAddressMode UMode, TextureAddressMode VMode) TextureAddressMode { get; set; }

Property Value

(TextureAddressMode UMode, TextureAddressMode VMode): The texture address modes used in TryRenderGeometry(ReadOnlySpan<Vertex>, Texture?) and TryRenderGeometry(ReadOnlySpan<Vertex>, ReadOnlySpan<int>, Texture?).

Remarks

The TextureAddressModes specified by this property determine the horizontal addressing mode (UMode) and vertical addressing mode (VMode) respectively.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

VSync

Gets or sets the vertical synchronization (VSync) mode or interval for the renderer

public RendererVSync VSync { get; set; }

Property Value

RendererVSync: The vertical synchronization (VSync) mode or interval for the renderer

Remarks

You can set the value of this property to Disabled to disable VSync, Adaptive to enable late swap tearing (adaptive VSync) if supported, or use the Interval(int) method to specify a custom VSync interval. You can specify a custom interval of 1 to synchronize to present of the renderer with every vertical refresh, 2 to synchronize it with every second vertical refresh, and so on.

When a renderer is newly created, the value of this property defaults to Disabled.

This property should only be accessed from the main thread.

Exceptions

SdlException

When setting this property, the renderer is a software renderer associated with a Surface instead of a Window, and you tried to enable VSync (check TryGet(out string?) for more information)

OR - When setting this property, the specified VSync mode or interval is not supported by the renderer (check TryGet(out string?) for more information)
OR - When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

Viewport

Gets or sets the drawing area for rendering on the current target

public Rect<int> Viewport { get; set; }

Property Value

Rect<int>: The drawing area for rendering on the current target, in pixels

Remarks

Drawing operations will clip to the area defined by this property (separatly from any clipping defined by the ClippingRect property), and the top-left of the area will become the coordinates origin (0, 0) for future drawing operations.

The area defined by this property must be ≥ 0.

You can use the IsViewportSet property to check whether an explicit rectangle was set as the current viewport for the renderer or not, and the ResetViewport() method to reset the viewport back to the default, which is the entire target area.

Each render target, Window or Target (or get_Surface(Renderer<Software>) in the case of a software renderer), has it own viewport. This property reflects the viewport of the current target.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

Window

Gets the Window associated with the renderer

public Window? Window { get; }

Property Value

Window: The Window associated with the renderer, or null if there is no associated window

Remarks

The value of this property can be null if the renderer is a software renderer with an associated Surface instead or if the renderer is a GPU renderer associated with an off-screen target.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

~Renderer()

protected ~Renderer()

ResetClippingRect()

Disables the clipping rectangle for the current target

public void ResetClippingRect()

Remarks

After a call to this method, the value of the IsClippingEnabled property will be false.

This method should only be called from the main thread.

Exceptions

SdlException: SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

ResetTarget()

Resets the current target to the default render target

public void ResetTarget()

Remarks

After a call to this method, the value of the Target property will be null.

This method should only be called from the main thread.

Exceptions

SdlException: SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

ResetViewport()

Resets the drawing area for rendering on the current target to the entire target area

public void ResetViewport()

Remarks

After a call to this method, the value of the IsViewportSet property will be false.

This method should only be called from the main thread.

Exceptions

SdlException: SDL failed with an error (check TryGet(out string?) for more information). A common reason for this to happen is when the Window associated with this renderer was already disposed, but the renderer itself wasn't disposed yet.

TryClear()

Tries to clear the current target with the drawing color

public bool TryClear()

Returns

bool: true, if the target was cleared successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method clears the entire current rendering target with the current DrawColor (or DrawColorFloat), ignoring any Viewport or ClippingRect settings. The DrawBlendMode does not affect this method.

This method should only be called from the main thread.

TryConvertRenderToWindowCoordinates(float, float, out float, out float)

Tries to get a point in window coordinates for a specified point in render coordinates

public bool TryConvertRenderToWindowCoordinates(float x, float y, out float windowX, out float windowY)

Parameters

x float: The X coordinate in render coordinates to convert to window coordinates
y float: The Y coordinate in render coordinates to convert to window coordinates
windowX float: The X coordinate in window coordinates corresponding to the given render coordinates, if this method returns true
windowY float: The Y coordinate in window coordinates corresponding to the given render coordinates, if this method returns true

Returns

bool: true, if the conversion was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The conversion takes into account several factors:

The Window dimensions
The LogicalPresentation settings
The Scale
The Viewport

This method should only be called from the main thread.

TryConvertWindowToRenderCoordinates(float, float, out float, out float)

Tries to get a point in render coordinates for a specified point in window coordinates

public bool TryConvertWindowToRenderCoordinates(float windowX, float windowY, out float x, out float y)

Parameters

windowX float: The X coordinate in window coordinates to convert to render coordinates
windowY float: The Y coordinate in window coordinates to convert to render coordinates
x float: The X coordinate in render coordinates corresponding to the given window coordinates, if this method returns true
y float: The Y coordinate in render coordinates corresponding to the given window coordinates, if this method returns true

Returns

bool: true, if the conversion was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The conversion takes into account several factors:

The Window dimensions
The LogicalPresentation settings
The Scale
The Viewport

This method should only be called from the main thread.

TryCreateTexture(PixelFormat, TextureAccess, int, int, out Texture?)

Tries to create a new texture for the renderer

public bool TryCreateTexture(PixelFormat format, TextureAccess access, int width, int height, out Texture? texture)

Parameters

format PixelFormat: The pixel format of the texture. Should be one of the supported texture formats returned by the SupportedTextureFormats property.
access TextureAccess: The intended access pattern of the texture. Should be one of the pre-defined TextureAccess values.
width int: The width of the texture in pixels
height int: The height of the texture in pixels
texture Texture: The resulting texture, if this method returns true; otherwise, null

Returns

bool: true, if the texture was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The contents of a newly created texture are undefined.

This method should only be called from the main thread.

TryCreateTexture(out Texture?, ColorSpace?, PixelFormat?, TextureAccess?, int?, int?, Palette?, float?, float?, Properties?)

Tries to create a new texture for the renderer

public bool TryCreateTexture(out Texture? texture, ColorSpace? colorSpace = null, PixelFormat? format = null, TextureAccess? access = null, int? width = null, int? height = null, Palette? palette = null, float? sdrWhitePoint = null, float? hdrHeadroom = null, Properties? properties = null)

Parameters

texture Texture: The resulting texture, if this method returns true; otherwise, null
colorSpace ColorSpace?: The color space of the texture. If not specified, defaults to SrgbLinear for floating point textures, Hdr10 for 10-bit textures, Srgb for other RGB textures, and Jpeg for YUV textures, or whatever the provided properties specify.
format PixelFormat?: The pixel format of the texture. Should be one of the supported texture formats returned by the SupportedTextureFormats property. If not specified, defaults to the best RGBA format available for the renderer, or whatever the provided properties specify.
access TextureAccess?: The intended access pattern of the texture. Should be one of the pre-defined TextureAccess values. If not specified, defaults to Static, or whatever the provided properties specify.
width int?: The width of the texture in pixels. Required if the provided properties don't specify a width.
height int?: The height of the texture in pixels. Required if the provided properties don't specify a height.
palette Palette: The palette to use when creating a texture with a palettized pixel format
sdrWhitePoint float?: The defining value for 100% diffuse white for HDR10 and floating point textures. Defaults to 100 for HDR10 textures and 1.0 for floating point textures, or whatever the provided properties specify.
hdrHeadroom float?: The maximum dynamic range for HDR10 and floating point textures in terms of the sdrWhitePoint
properties Properties: Additional properties to use when creating the texture

Returns

bool: true, if the texture was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The contents of a newly created texture are undefined.

This method should only be called from the main thread.

TryCreateTextureFromSurface(Surface, out Texture?)

Tries to create a texture from an exisiting Surface

public bool TryCreateTextureFromSurface(Surface surface, out Texture? texture)

Parameters

surface Surface: The Surface to copy and create the texture from
texture Texture: The resulting texture, if this method returns true; otherwise, null

Returns

bool: true, if the texture was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The given surface's pixel data is copied into the texture and the surface is not modified in any way. This means that the given surface can be safely disposed of after this method returns, without affecting the resulting texture.

The pixel format of the resulting texture my be different from the pixel format of the given surface. The actual pixel format of the resulting texture can later be checked using the Format property.

The TextureAccess of the resulting texture will be Static.

This method should only be called from the main thread.

TryFlush()

Tries to flush any pending rendering operations on the current target

public bool TryFlush()

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

You do not need to (and in fact, shouldn't) call this method unless you are planning to call into OpenGL/Direct3D/Metal/whatever directly, in addition to using a Renderer.

This method exists for a very-specific case: if you are using SDL's render API, and you plan to make OpenGL/D3D/whatever calls in addition to SDL render API calls. If this applies, you should call this method between calls to SDL's render API and the low-level API you're using in cooperation.

In all other cases, you can ignore this method!

A call to this method makes SDL flush any pending rendering work it was queueing up to do later in a single batch, and marks any internal cached state as invalid, so it'll prepare all its state again later, from scratch.

This means you do not need to save state in your rendering code to protect the SDL renderer. However, there lots of arbitrary pieces of Direct3D and OpenGL state that can confuse things; you should use your best judgment and be prepared to make changes if specific state needs to be protected.

This method should only be called from the main thread.

TryReadPixels(in Rect<int>, out Surface?)

Tries to read the pixels of an area of the current target into a new Surface

public bool TryReadPixels(in Rect<int> rect, out Surface? pixels)

Parameters

rect Rect<int>: The area of the current target to read the pixels from
pixels Surface: The resulting Surface containing the read pixels, if this method returns true; otherwise, null

Returns

bool: true, if the pixels were successfully read into a new Surface; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting Surface contains a copy of the pixels in the area specified by the given rect clipped to the current Viewport.

Note that this method copies the actual pixels on the screen. So if you are using any form of logical presentation, you should use LogicalPresentationRect to get the area containing your content.

WARNING: This is a very slow operation, and should not be used frequently. If you're using this on the main rendering target, it should be called after rendering and before TryRenderPresent().

Please remember to dispose of the resulting Surface when you're done using it.

This method should only be called from the main thread.

TryReadPixels(out Surface?)

Tries to read the pixels of the entirety of the current target into a new Surface

public bool TryReadPixels(out Surface? pixels)

Parameters

pixels Surface: The resulting Surface containing the read pixels, if this method returns true; otherwise, null

Returns

bool: true, if the pixels were successfully read into a new Surface; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting Surface contains a copy of the pixels of the entire texture clipped to the current Viewport.

Note that this method copies the actual pixels on the screen. So if you are using any form of logical presentation, you should use LogicalPresentationRect to get the area containing your content.

WARNING: This is a very slow operation, and should not be used frequently. If you're using this on the main rendering target, it should be called after rendering and before TryRenderPresent().

Please remember to dispose of the resulting Surface when you're done using it.

This method should only be called from the main thread.

TryRenderDebugText(float, float, string)

Tries to draw debug text to the current target

public bool TryRenderDebugText(float x, float y, string text)

Parameters

x float: The top-left X coordinate where the text should be drawn
y float: The top-left Y coordinate where the text should be drawn
text string: The text to be drawn

Returns

bool: true, if the text was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method will render text to a Renderer. Note that this is a convenience method for debugging, with severe limitations, and not intended to be used for production applications and games.

Among these limitations are:

It accepts Unicode strings, but will only render ASCII characters
It has a single, tiny size (8x8 pixels). You can use LogicalPresentation or Scale to adjust for that.
It uses a simple, hardcoded bitmap font. It does not allow different font selections and it does not support truetype, for proper scaling.
It doesn't do word-wrapping and doesn't treat newline characters as a line break. If the text goes out of the target, it's gone.

For more serious text rendering, there are several good options, such as SDL_ttf.

On first use, this will create an internal texture for rendering glyphs. This texture will live until the renderer is disposed.

The text is drawn in the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determine how the text is blended with the existing content of the target.

This method should only be called from the main thread.

TryRenderDebugText(float, float, string, params ReadOnlySpan<object>)

Tries to draw a debug format string to the current target

public bool TryRenderDebugText(float x, float y, string format, params ReadOnlySpan<object> args)

Parameters

x float: The top-left X coordinate where the text should be drawn
y float: The top-left Y coordinate where the text should be drawn
format string: The C-style printf format string
args ReadOnlySpan<object>: The arguments corresponding to the format specifiers in format

Returns

bool: true, if the text was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method will render text to a Renderer. Note that this is a convenience method for debugging, with severe limitations, and not intended to be used for production applications and games.

Among these limitations are:

It accepts Unicode strings, but will only render ASCII characters
It has a single, tiny size (8x8 pixels). You can use LogicalPresentation or Scale to adjust for that.
It uses a simple, hardcoded bitmap font. It does not allow different font selections and it does not support truetype, for proper scaling.
It doesn't do word-wrapping and doesn't treat newline characters as a line break. If the text goes out of the target, it's gone.

For more serious text rendering, there are several good options, such as SDL_ttf.

On first use, this will create an internal texture for rendering glyphs. This texture will live until the renderer is disposed.

The text is drawn in the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determine how the text is blended with the existing content of the target.

The format parameter is interpreted as a C-style printf format string, and the args parameter supplies the values for its format specifiers. Supported argument types include all integral types up to 64-bit (including bool and char), floating point types (float and double), pointer types (nint and nuint), and string.

For a detailed explanation of C-style printf format strings and their specifiers, see https://en.wikipedia.org/wiki/Printf#Format_specifier.

Consider using TryRenderDebugText(float, float, string) instead when possible, as it may be more efficient. In many cases, you can use C# string interpolation to construct the message before logging.

This method should only be called from the main thread.

TryRenderFilledRect()

Tries to draw a filled rectangle to the entirety of the current target

public bool TryRenderFilledRect()

Returns

bool: true, if the filled rectangle was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangle is filled with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the rectangle is blended with the existing content of the target.

Drawing the rectangle works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderFilledRect(in Rect<float>)

Tries to draw a filled rectangle to an area of the current target

public bool TryRenderFilledRect(in Rect<float> rect)

Parameters

rect Rect<float>: The area of the current target to draw the filled rectangle in

Returns

bool: true, if the filled rectangle was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangle is filled with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the rectangle is blended with the existing content of the target.

Drawing the rectangle works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderFilledRects(ReadOnlySpan<Rect<float>>)

Tries to draw multiple filled rectangles to areas of the current target

public bool TryRenderFilledRects(ReadOnlySpan<Rect<float>> rects)

Parameters

rects ReadOnlySpan<Rect<float>>: The list of areas of the current target to draw the filled rectangles in

Returns

bool: true, if the filled rectangles were drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangles are filled with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the rectangles are blended with the existing content of the target.

Drawing the rectangles works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderGeometry(ReadOnlySpan<Vertex>, Texture?)

Tries to draw a list of triangles specified by a list of vertices to the current target, optionally using a texture

public bool TryRenderGeometry(ReadOnlySpan<Vertex> vertices, Texture? texture = null)

Parameters

vertices ReadOnlySpan<Vertex>: The list of vertices to specify the triangles to draw
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometry(ReadOnlySpan<Vertex>, ReadOnlySpan<int>, Texture?)

Tries to draw a list of triangles specified by a list of indices into a list of vertices to the current target, optionally using a texture

public bool TryRenderGeometry(ReadOnlySpan<Vertex> vertices, ReadOnlySpan<int> indices, Texture? texture = null)

Parameters

vertices ReadOnlySpan<Vertex>: The vertices to use
indices ReadOnlySpan<int>: The list of indices into the vertex list to specify the triangles to draw
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the given vertices list.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(ReadOnlyNativeMemory<float>, int, ReadOnlyNativeMemory<Color<float>>, int, ReadOnlyNativeMemory<float>, int, Texture?)

Tries to draw a list of triangles specified by separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(ReadOnlyNativeMemory<float> xy, int xyStride, ReadOnlyNativeMemory<Color<float>> colors, int colorStride, ReadOnlyNativeMemory<float> uv, int uvStride, Texture? texture = null)

Parameters

xy ReadOnlyNativeMemory<float>: The list of vertex positions, first the X coordinate and then the Y coordinate for each vertex
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors ReadOnlyNativeMemory<Color<float>>: The list of vertex colors
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv ReadOnlyNativeMemory<float>: The list of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The number of vertices specified by the various vertex attribute lists is determined by their byte lengths and strides, always selecting the smallest resulting vertex count among them.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(ReadOnlyNativeMemory<float>, int, ReadOnlyNativeMemory<Color<float>>, int, ReadOnlyNativeMemory<float>, int, ReadOnlySpan<short>, Texture?)

Tries to draw a list of triangles specified by a list of short indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(ReadOnlyNativeMemory<float> xy, int xyStride, ReadOnlyNativeMemory<Color<float>> colors, int colorStride, ReadOnlyNativeMemory<float> uv, int uvStride, ReadOnlySpan<short> indices, Texture? texture = null)

Parameters

xy ReadOnlyNativeMemory<float>: The list of vertex positions, first the X coordinate and then the Y coordinate for each vertex
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors ReadOnlyNativeMemory<Color<float>>: The list of vertex colors
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv ReadOnlyNativeMemory<float>: The list of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
indices ReadOnlySpan<short>: The list of short indices into the various vertex attribute lists to specify the triangles to draw
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The number of vertices specified by the various vertex attribute lists is determined by their byte lengths and strides, always selecting the smallest resulting vertex count among them.

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the calculated vertex count from the given vertex attribute lists.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(ReadOnlyNativeMemory<float>, int, ReadOnlyNativeMemory<Color<float>>, int, ReadOnlyNativeMemory<float>, int, ReadOnlySpan<int>, Texture?)

Tries to draw a list of triangles specified by a list of int indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(ReadOnlyNativeMemory<float> xy, int xyStride, ReadOnlyNativeMemory<Color<float>> colors, int colorStride, ReadOnlyNativeMemory<float> uv, int uvStride, ReadOnlySpan<int> indices, Texture? texture = null)

Parameters

xy ReadOnlyNativeMemory<float>: The list of vertex positions, first the X coordinate and then the Y coordinate for each vertex
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors ReadOnlyNativeMemory<Color<float>>: The list of vertex colors
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv ReadOnlyNativeMemory<float>: The list of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
indices ReadOnlySpan<int>: The list of int indices into the various vertex attribute lists to specify the triangles to draw
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The number of vertices specified by the various vertex attribute lists is determined by their byte lengths and strides, always selecting the smallest resulting vertex count among them.

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the calculated vertex count from the given vertex attribute lists.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(ReadOnlyNativeMemory<float>, int, ReadOnlyNativeMemory<Color<float>>, int, ReadOnlyNativeMemory<float>, int, ReadOnlySpan<sbyte>, Texture?)

Tries to draw a list of triangles specified by a list of sbyte indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(ReadOnlyNativeMemory<float> xy, int xyStride, ReadOnlyNativeMemory<Color<float>> colors, int colorStride, ReadOnlyNativeMemory<float> uv, int uvStride, ReadOnlySpan<sbyte> indices, Texture? texture = null)

Parameters

xy ReadOnlyNativeMemory<float>: The list of vertex positions, first the X coordinate and then the Y coordinate for each vertex
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors ReadOnlyNativeMemory<Color<float>>: The list of vertex colors
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv ReadOnlyNativeMemory<float>: The list of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
indices ReadOnlySpan<sbyte>: The list of sbyte indices into the various vertex attribute lists to specify the triangles to draw
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The number of vertices specified by the various vertex attribute lists is determined by their byte lengths and strides, always selecting the smallest resulting vertex count among them.

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the calculated vertex count from the given vertex attribute lists.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(ReadOnlySpan<float>, int, ReadOnlySpan<Color<float>>, int, ReadOnlySpan<float>, int, Texture?)

Tries to draw a list of triangles specified by separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(ReadOnlySpan<float> xy, int xyStride, ReadOnlySpan<Color<float>> colors, int colorStride, ReadOnlySpan<float> uv, int uvStride, Texture? texture = null)

Parameters

xy ReadOnlySpan<float>: The list of vertex positions, first the X coordinate and then the Y coordinate for each vertex
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors ReadOnlySpan<Color<float>>: The list of vertex colors
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv ReadOnlySpan<float>: The list of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The number of vertices specified by the various vertex attribute lists is determined by their byte lengths and strides, always selecting the smallest resulting vertex count among them.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(ReadOnlySpan<float>, int, ReadOnlySpan<Color<float>>, int, ReadOnlySpan<float>, int, ReadOnlySpan<short>, Texture?)

Tries to draw a list of triangles specified by a list of short indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(ReadOnlySpan<float> xy, int xyStride, ReadOnlySpan<Color<float>> colors, int colorStride, ReadOnlySpan<float> uv, int uvStride, ReadOnlySpan<short> indices, Texture? texture = null)

Parameters

xy ReadOnlySpan<float>: The list of vertex positions, first the X coordinate and then the Y coordinate for each vertex
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors ReadOnlySpan<Color<float>>: The list of vertex colors
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv ReadOnlySpan<float>: The list of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
indices ReadOnlySpan<short>: The list of short indices into the various vertex attribute lists to specify the triangles to draw
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The number of vertices specified by the various vertex attribute lists is determined by their byte lengths and strides, always selecting the smallest resulting vertex count among them.

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the calculated vertex count from the given vertex attribute lists.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(ReadOnlySpan<float>, int, ReadOnlySpan<Color<float>>, int, ReadOnlySpan<float>, int, ReadOnlySpan<int>, Texture?)

Tries to draw a list of triangles specified by a list of int indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(ReadOnlySpan<float> xy, int xyStride, ReadOnlySpan<Color<float>> colors, int colorStride, ReadOnlySpan<float> uv, int uvStride, ReadOnlySpan<int> indices, Texture? texture = null)

Parameters

xy ReadOnlySpan<float>: The list of vertex positions, first the X coordinate and then the Y coordinate for each vertex
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors ReadOnlySpan<Color<float>>: The list of vertex colors
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv ReadOnlySpan<float>: The list of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
indices ReadOnlySpan<int>: The list of int indices into the various vertex attribute lists to specify the triangles to draw
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The number of vertices specified by the various vertex attribute lists is determined by their byte lengths and strides, always selecting the smallest resulting vertex count among them.

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the calculated vertex count from the given vertex attribute lists.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(ReadOnlySpan<float>, int, ReadOnlySpan<Color<float>>, int, ReadOnlySpan<float>, int, ReadOnlySpan<sbyte>, Texture?)

Tries to draw a list of triangles specified by a list of sbyte indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(ReadOnlySpan<float> xy, int xyStride, ReadOnlySpan<Color<float>> colors, int colorStride, ReadOnlySpan<float> uv, int uvStride, ReadOnlySpan<sbyte> indices, Texture? texture = null)

Parameters

xy ReadOnlySpan<float>: The list of vertex positions, first the X coordinate and then the Y coordinate for each vertex
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors ReadOnlySpan<Color<float>>: The list of vertex colors
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv ReadOnlySpan<float>: The list of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
indices ReadOnlySpan<sbyte>: The list of sbyte indices into the various vertex attribute lists to specify the triangles to draw
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The number of vertices specified by the various vertex attribute lists is determined by their byte lengths and strides, always selecting the smallest resulting vertex count among them.

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the calculated vertex count from the given vertex attribute lists.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(float, int, Color<float>, int, float*, int, int, Texture?)

Tries to draw a list of triangles specified by separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(float* xy, int xyStride, Color<float>* colors, int colorStride, float* uv, int uvStride, int verticesCount, Texture? texture = null)

Parameters

xy float*: A pointer to a contiguous array of vertex positions, first the X coordinate and then the Y coordinate for each vertex. Must be dereferenceable for at least verticesCount * xyStride bytes.
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors Color<float>*: A pointer to a contiguous array of vertex colors. Must be dereferenceable for at least verticesCount * colorStride bytes.
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv float*: A pointer to a contiguous array of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex. Must be dereferenceable for at least verticesCount * uvStride bytes.
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
verticesCount int: The number of vertices
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(float, int, Color<float>, int, float, int, int, short, int, Texture?)

Tries to draw a list of triangles specified by a list of short indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(float* xy, int xyStride, Color<float>* colors, int colorStride, float* uv, int uvStride, int verticesCount, short* indices, int indicesCount, Texture? texture = null)

Parameters

xy float*: A pointer to a contiguous array of vertex positions, first the X coordinate and then the Y coordinate for each vertex. Must be dereferenceable for at least verticesCount * xyStride bytes.
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors Color<float>*: A pointer to a contiguous array of vertex colors. Must be dereferenceable for at least verticesCount * colorStride bytes.
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv float*: A pointer to a contiguous array of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex. Must be dereferenceable for at least verticesCount * uvStride bytes.
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
verticesCount int: The number of vertices
indices short*: A pointer to a contiguous array of short indices into the various vertex attribute lists to specify the triangles to draw. Must be dereferenceable for at least indicesCount * sizeof(short) bytes.
indicesCount int: The number of short indices
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the given verticesCount.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(float, int, Color<float>, int, float, int, int, int, int, Texture?)

Tries to draw a list of triangles specified by a list of int indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(float* xy, int xyStride, Color<float>* colors, int colorStride, float* uv, int uvStride, int verticesCount, int* indices, int indicesCount, Texture? texture = null)

Parameters

xy float*: A pointer to a contiguous array of vertex positions, first the X coordinate and then the Y coordinate for each vertex. Must be dereferenceable for at least verticesCount * xyStride bytes.
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors Color<float>*: A pointer to a contiguous array of vertex colors. Must be dereferenceable for at least verticesCount * colorStride bytes.
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv float*: A pointer to a contiguous array of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex. Must be dereferenceable for at least verticesCount * uvStride bytes.
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
verticesCount int: The number of vertices
indices int*: A pointer to a contiguous array of int indices into the various vertex attribute lists to specify the triangles to draw. Must be dereferenceable for at least indicesCount * sizeof(int) bytes.
indicesCount int: The number of int indices
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the given verticesCount.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderGeometryRaw(float, int, Color<float>, int, float, int, int, sbyte, int, Texture?)

Tries to draw a list of triangles specified by a list of sbyte indices into separate lists of vertex attributes to the current target, optionally using a texture

public bool TryRenderGeometryRaw(float* xy, int xyStride, Color<float>* colors, int colorStride, float* uv, int uvStride, int verticesCount, sbyte* indices, int indicesCount, Texture? texture = null)

Parameters

xy float*: A pointer to a contiguous array of vertex positions, first the X coordinate and then the Y coordinate for each vertex. Must be dereferenceable for at least verticesCount * xyStride bytes.
xyStride int: The length, in bytes, to move from one element in the xy list to the next. Usually that's 2 * sizeof(float).
colors Color<float>*: A pointer to a contiguous array of vertex colors. Must be dereferenceable for at least verticesCount * colorStride bytes.
colorStride int: The length, in bytes, to move from one element in the colors list to the next. Usually that's sizeof(Color<float>).
uv float*: A pointer to a contiguous array of normalized texture coordinates per vertex, first the horizontal coordinate (U) and then the vertical coordinate (V) for each vertex. Must be dereferenceable for at least verticesCount * uvStride bytes.
uvStride int: The length, in bytes, to move from one element in the uv list to the next. Usually that's 2 * sizeof(float).
verticesCount int: The number of vertices
indices sbyte*: A pointer to a contiguous array of sbyte indices into the various vertex attribute lists to specify the triangles to draw. Must be dereferenceable for at least indicesCount * sizeof(sbyte) bytes.
indicesCount int: The number of sbyte indices
texture Texture: An optional texture to use when drawing the triangles

Returns

bool: true if the geometry was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

There are no surface-level checks for the validity of the given indices, so you must make sure they are all within the bounds of the given verticesCount.

Only textures created with this renderer can be rendered with this method.

Color and alpha modulation is done per vertex, so ColorMod (or ColorModFloat) and AlphaMod (or AlphaModFloat) are ignored.

This method should only be called from the main thread.

TryRenderLine(float, float, float, float)

Tries to draw a line to the current target

public bool TryRenderLine(float x1, float y1, float x2, float y2)

Parameters

x1 float: The X coordinate of the start point of the line
y1 float: The Y coordinate of the start point of the line
x2 float: The X coordinate of the end point of the line
y2 float: The Y coordinate of the end point of the line

Returns

bool: true, if the line was drawn successfully; otherwise, false (check TryGet(out string?) for more information)s

Remarks

The line is drawn with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the line is blended with the existing content of the target.

Drawing the line works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderLines(ReadOnlySpan<Point<float>>)

Tries to draw a series of connected lines to the current target

public bool TryRenderLines(ReadOnlySpan<Point<float>> points)

Parameters

points ReadOnlySpan<Point<float>>: The list of positions specifying the vertices of the connected lines

Returns

bool: true if the lines were drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The lines are drawn with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the lines are blended with the existing content of the target.

Drawing the lines works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderPoint(float, float)

Tries to draw a point to the current target

public bool TryRenderPoint(float x, float y)

Parameters

x float: The X coordinate of the point to draw
y float: The Y coordinate of the point to draw

Returns

bool: true if the point was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The point is drawn with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the point is blended with the existing content of the target.

Drawing the point works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderPoints(ReadOnlySpan<Point<float>>)

Tries to draw multiple points to the current target

public bool TryRenderPoints(ReadOnlySpan<Point<float>> points)

Parameters

points ReadOnlySpan<Point<float>>: The list of positions where the points should be drawn

Returns

bool: true if the points were drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The points are drawn with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the points are blended with the existing content of the target.

Drawing the points works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderPresent()

Tries to update the screen with any rendering performed since the previous call

public bool TryRenderPresent()

Returns

bool: true if the screen was updated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

SDL's rendering API operates on a backbuffer. E.g., performing a rendering operation such as TryRenderLine(float, float, float, float) does not directly draw a line on the screen, but rather updates the backbuffer. That means that you should compose the entire scene in the backbuffer and then present the composed backbuffer to the screen as a complete picture.

When using SDL's rendering API, once per frame, do all drawing intended for the frame, and then call this method once to present the final drawing to the user.

The backbuffer should be considered invalidated after each call to this method; do not assume that previous contents will exist between frames. It is strongly recommended to initialize the backbuffer before starting each new frame's drawing by calling TryClear(). Even if you plan to overwrite every pixel.

Please note, that in case of rendering to a texture target (Target is non-null), there is no need to call TryRenderPresent() and in fact, it shouldn't be called. You are only required to change back the rendering target to default via ResetTarget() or setting Target to null afterwards, as textures by themselves do not have a concept of backbuffers. Calling TryRenderPresent() while rendering to a texture will fail.

This method should only be called from the main thread.

TryRenderRect()

Tries to draw a rectangle to the entirety of the current target

public bool TryRenderRect()

Returns

bool: true, if the rectangle was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangle is drawn with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the rectangle is blended with the existing content of the target.

Drawing the rectangle works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderRect(in Rect<float>)

Tries to draw a rectangle to an area of the current target

public bool TryRenderRect(in Rect<float> rect)

Parameters

rect Rect<float>: The area of the current target to draw the rectangle in

Returns

bool: true, if the rectangle was drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangle is drawn with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the rectangle is blended with the existing content of the target.

Drawing the rectangle works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderRects(ReadOnlySpan<Rect<float>>)

Tries to draw multiple rectangles to areas of the current target

public bool TryRenderRects(ReadOnlySpan<Rect<float>> rects)

Parameters

rects ReadOnlySpan<Rect<float>>: The list of areas of the current target to draw the rectangles in

Returns

bool: true, if the rectangles were drawn successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangles are drawn with the color specified by DrawColor (or DrawColorFloat) and DrawBlendMode determines how the rectangles are blended with the existing content of the target.

Drawing the rectangles works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture(in Rect<float>, Texture)

Tries to copy the entirety of a texture to an area of the current target

public bool TryRenderTexture(in Rect<float> destinationRect, Texture texture)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to
texture Texture: The texture to copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture(in Rect<float>, Texture, in Rect<float>)

Tries to copy a portion of a texture to an area of the current target

public bool TryRenderTexture(in Rect<float> destinationRect, Texture texture, in Rect<float> sourceRect)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to
texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture(Texture)

Tries to copy the entirety of a texture to entirety of the current target

public bool TryRenderTexture(Texture texture)

Parameters

texture Texture: The texture to copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture(Texture, in Rect<float>)

Tries to copy a portion of a texture to entirety of the current target

public bool TryRenderTexture(Texture texture, in Rect<float> sourceRect)

Parameters

texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture9Grid(in Rect<float>, Texture, in Rect<float>, float, float, float, float, float)

Tries to scalingly copy a portion of a texture to an area of the current target using the 9-grid algorithm

public bool TryRenderTexture9Grid(in Rect<float> destinationRect, Texture texture, in Rect<float> sourceRect, float leftWidth, float rightWidth, float topHeight, float bottomHeight, float scale)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to, in a 9-grid manner
texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy, in a 9-grid manner
leftWidth float: The width, in pixels, of the left corners in sourceRect
rightWidth float: The width, in pixels, of the right corners in sourceRect
topHeight float: The height, in pixels, of the top corners in sourceRect
bottomHeight float: The height, in pixels, of the bottom corners in sourceRect
scale float: The scale to use to transform the corners of sourceRect into the corners of destinationRect, or 0 for an unscaled copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the texture are split into a 3⨯3 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 destinationRect. The sides and center are then stretched into place to cover the remaining portion of the destinationRect.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture9Grid(in Rect<float>, Texture, float, float, float, float, float)

Tries to scalingly copy the entirety of a texture to an area of the current target using the 9-grid algorithm

public bool TryRenderTexture9Grid(in Rect<float> destinationRect, Texture texture, float leftWidth, float rightWidth, float topHeight, float bottomHeight, float scale)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to, in a 9-grid manner
texture Texture: The texture to copy
leftWidth float: The width, in pixels, of the left corners of the texture
rightWidth float: The width, in pixels, of the right corners of the texture
topHeight float: The height, in pixels, of the top corners of the texture
bottomHeight float: The height, in pixels, of the bottom corners of the texture
scale float: The scale to use to transform the corners of the texture into the corners of destinationRect, or 0 for an unscaled copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture9Grid(Texture, in Rect<float>, float, float, float, float, float)

Tries to scalingly copy a portion of a texture to the entirety of the current target using the 9-grid algorithm

public bool TryRenderTexture9Grid(Texture texture, in Rect<float> sourceRect, float leftWidth, float rightWidth, float topHeight, float bottomHeight, float scale)

Parameters

texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy, in a 9-grid manner
leftWidth float: The width, in pixels, of the left corners in sourceRect
rightWidth float: The width, in pixels, of the right corners in sourceRect
topHeight float: The height, in pixels, of the top corners in sourceRect
bottomHeight float: The height, in pixels, of the bottom corners in sourceRect
scale float: The scale to use to transform the corners of sourceRect into the corners of the current target, or 0 for an unscaled copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the texture are split into a 3⨯3 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 current target. The sides and center are then stretched into place to cover the remaining portion of the current target.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture9Grid(Texture, float, float, float, float, float)

Tries to scalingly copy a portion of a texture to the entirety of the current target using the 9-grid algorithm

public bool TryRenderTexture9Grid(Texture texture, float leftWidth, float rightWidth, float topHeight, float bottomHeight, float scale)

Parameters

texture Texture: The texture to copy
leftWidth float: The width, in pixels, of the left corners of the texture
rightWidth float: The width, in pixels, of the right corners of the texture
topHeight float: The height, in pixels, of the top corners of the texture
bottomHeight float: The height, in pixels, of the bottom corners of the texture
scale float: The scale to use to transform the corners of the texture into the corners of the current target, or 0 for an unscaled copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the texture are split into a 3⨯3 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 current target. The sides and center are then stretched into place to cover the remaining portion of the current target.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture9GridTiled(in Rect<float>, Texture, in Rect<float>, float, float, float, float, float, float)

Tries to scalingly copy a portion of a texture to an area of the current target using the 9-grid algorithm with tiling for the borders and the center

public bool TryRenderTexture9GridTiled(in Rect<float> destinationRect, Texture texture, in Rect<float> sourceRect, float leftWidth, float rightWidth, float topHeight, float bottomHeight, float scale, float tileScale)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to, in a 9-grid manner
texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy, in a 9-grid manner
leftWidth float: The width, in pixels, of the left corners in sourceRect
rightWidth float: The width, in pixels, of the right corners in sourceRect
topHeight float: The height, in pixels, of the top corners in sourceRect
bottomHeight float: The height, in pixels, of the bottom corners in sourceRect
scale float: The scale to use to transform the corners of sourceRect into the corners of destinationRect, or 0 for an unscaled copy
tileScale float: The scale to use to transform the borders and the center of sourceRect into the border and the center of destinationRect, or 1 for an unscaled copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the texture are split into a 3⨯3 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 destinationRect. The sides and center are then tiled into place to cover the remaining portion of the destinationRect.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture9GridTiled(in Rect<float>, Texture, float, float, float, float, float, float)

Tries to scalingly copy the entirety of a texture to an area of the current target using the 9-grid algorithm with tiling for the borders and the center

public bool TryRenderTexture9GridTiled(in Rect<float> destinationRect, Texture texture, float leftWidth, float rightWidth, float topHeight, float bottomHeight, float scale, float tileScale)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to, in a 9-grid manner
texture Texture: The texture to copy
leftWidth float: The width, in pixels, of the left corners of the texture
rightWidth float: The width, in pixels, of the right corners of the texture
topHeight float: The height, in pixels, of the top corners of the texture
bottomHeight float: The height, in pixels, of the bottom corners of the texture
scale float: The scale to use to transform the corners of the texture into the corners of destinationRect, or 0 for an unscaled copy
tileScale float: The scale to use to transform the borders and the center of the texture into the border and the center of destinationRect, or 1 for an unscaled copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the texture are split into a 3⨯3 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 destinationRect. The sides and center are then tiled into place to cover the remaining portion of the destinationRect.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture9GridTiled(Texture, in Rect<float>, float, float, float, float, float, float)

Tries to scalingly copy a portion of a texture to the entirety of the current target using the 9-grid algorithm with tiling for the borders and the center

public bool TryRenderTexture9GridTiled(Texture texture, in Rect<float> sourceRect, float leftWidth, float rightWidth, float topHeight, float bottomHeight, float scale, float tileScale)

Parameters

texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy, in a 9-grid manner
leftWidth float: The width, in pixels, of the left corners in sourceRect
rightWidth float: The width, in pixels, of the right corners in sourceRect
topHeight float: The height, in pixels, of the top corners in sourceRect
bottomHeight float: The height, in pixels, of the bottom corners in sourceRect
scale float: The scale to use to transform the corners of sourceRect into the corners of the current target, or 0 for an unscaled copy
tileScale float: The scale to use to transform the borders and the center of sourceRect into the border and the center of the current target, or 1 for an unscaled copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the texture are split into a 3⨯3 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 current target. The sides and center are then tiled into place to cover the remaining portion of the current target.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTexture9GridTiled(Texture, float, float, float, float, float, float)

Tries to scalingly copy the entirety of a texture to the entirety of the current target using the 9-grid algorithm with tiling for the borders and the center

public bool TryRenderTexture9GridTiled(Texture texture, float leftWidth, float rightWidth, float topHeight, float bottomHeight, float scale, float tileScale)

Parameters

texture Texture: The texture to copy
leftWidth float: The width, in pixels, of the left corners of the texture
rightWidth float: The width, in pixels, of the right corners of the texture
topHeight float: The height, in pixels, of the top corners of the texture
bottomHeight float: The height, in pixels, of the bottom corners of the texture
scale float: The scale to use to transform the corners of the texture into the corners of the current target, or 0 for an unscaled copy
tileScale float: The scale to use to transform the borders and the center of the texture into the border and the center of the current target, or 1 for an unscaled copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the texture are split into a 3⨯3 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 current target. The sides and center are then tiled into place to cover the remaining portion of the current target.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureAffine(in Point<float>?, in Point<float>?, in Point<float>?, Texture)

Tries to copy the entirety of a texture to the current target with a specified affine transformation

public bool TryRenderTextureAffine(in Point<float>? destinationOrigin, in Point<float>? destinationRight, in Point<float>? destinationDown, Texture texture)

Parameters

destinationOrigin Point<float>?: A point specifying where the top-left corner of the texture should be mapped to on the current target, or null to use the current target's origin
destinationRight Point<float>?: A point specifying where the top-right corner of the texture should be mapped to on the current target, or null to use the current target's top-right corner
destinationDown Point<float>?: A point specifying where the bottom-left corner of the texture should be mapped to on the current target, or null to use the current target's bottom-left corner
texture Texture: The texture to copy

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureAffine(in Point<float>?, in Point<float>?, in Point<float>?, Texture, in Rect<float>)

Tries to copy a portion of a texture to the current target with a specified affine transformation

public bool TryRenderTextureAffine(in Point<float>? destinationOrigin, in Point<float>? destinationRight, in Point<float>? destinationDown, Texture texture, in Rect<float> sourceRect)

Parameters

destinationOrigin Point<float>?: A point specifying where the top-left corner of sourceRect should be mapped to on the current target, or null to use the current target's origin
destinationRight Point<float>?: A point specifying where the top-right corner of sourceRect should be mapped to on the current target, or null to use the current target's top-right corner
destinationDown Point<float>?: A point specifying where the bottom-left corner of sourceRect should be mapped to on the current target, or null to use the current target's bottom-left corner
texture Texture: The texture to copy
sourceRect Rect<float>

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureRotated(in Rect<float>, Texture, in Rect<float>, double, in Point<float>?, FlipMode)

Tries to copy a portion of a texture to an area of the current target with a specified rotation and flipping

public bool TryRenderTextureRotated(in Rect<float> destinationRect, Texture texture, in Rect<float> sourceRect, double angle, in Point<float>? centerPoint, FlipMode flip)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to
texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy
angle double: The angle, in degrees, to rotate the texture clockwise around the center point
centerPoint Point<float>?: An optional point specifying the center of rotation, or null to rotate around the center of destinationRect
flip FlipMode: An optional flipping direction to flip the texture in addition to rotating it

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

You can also use this method to just render a flipped texture by specifying the angle as 0 and leaving the centerPoint as unspecified.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureRotated(in Rect<float>, Texture, double, in Point<float>?, FlipMode)

Tries to copy the entirety of a texture to an area of the current target with a specified rotation and flipping

public bool TryRenderTextureRotated(in Rect<float> destinationRect, Texture texture, double angle, in Point<float>? centerPoint, FlipMode flip)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to
texture Texture: The texture to copy
angle double: The angle, in degrees, to rotate the texture clockwise around the center point
centerPoint Point<float>?: An optional point specifying the center of rotation, or null to rotate around the center of destinationRect
flip FlipMode: An optional flipping direction to flip the texture in addition to rotating it

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

You can also use this method to just render a flipped texture by specifying the angle as 0 and leaving the centerPoint as unspecified.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureRotated(Texture, in Rect<float>, double, in Point<float>?, FlipMode)

Tries to copy a portion of a texture to the entirety of the current target with a specified rotation and flipping

public bool TryRenderTextureRotated(Texture texture, in Rect<float> sourceRect, double angle, in Point<float>? centerPoint, FlipMode flip)

Parameters

texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy
angle double: The angle, in degrees, to rotate the texture clockwise around the center point
centerPoint Point<float>?: An optional point specifying the center of rotation, or null to rotate around the center of the current target
flip FlipMode: An optional flipping direction to flip the texture in addition to rotating it

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

You can also use this method to just render a flipped texture by specifying the angle as 0 and leaving the centerPoint as unspecified.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureRotated(Texture, double, in Point<float>?, FlipMode)

Tries to copy the entirety of a texture to the entirety of the current target with a specified rotation and flipping

public bool TryRenderTextureRotated(Texture texture, double angle, in Point<float>? centerPoint, FlipMode flip)

Parameters

texture Texture: The texture to copy
angle double: The angle, in degrees, to rotate the texture clockwise around the center point
centerPoint Point<float>?: An optional point specifying the center of rotation, or null to rotate around the center of the current target
flip FlipMode: An optional flipping direction to flip the texture in addition to rotating it

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

You can also use this method to just render a flipped texture by specifying the angle as 0 and leaving the centerPoint as unspecified.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureTiled(in Rect<float>, Texture, in Rect<float>, float)

Tries to tilingly copy a portion of a texture to an area of the current target with a specified scale

public bool TryRenderTextureTiled(in Rect<float> destinationRect, Texture texture, in Rect<float> sourceRect, float scale)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to
texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy
scale float: The scale used to transform the sourceRect into the destinationRect

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The scale is applied to the region of the texture specified by sourceRect, e.g. 32⨯32 region with a scale of 2 would become a 64⨯64 region. That scaled region is then used and repeated as many times as needed to completely fill the region specified by destinationRect on the current target.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureTiled(in Rect<float>, Texture, float)

Tries to tilingly copy the entirety of a texture to an area of the current target with a specified scale

public bool TryRenderTextureTiled(in Rect<float> destinationRect, Texture texture, float scale)

Parameters

destinationRect Rect<float>: The area of the current target to copy the texture to
texture Texture: The texture to copy
scale float: The scale used to transform the texture into the destinationRect

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The scale is applied to the entire texture, e.g. 32⨯32 texture with a scale of 2 would become a 64⨯64 region. That scaled region is then used and repeated as many times as needed to completely fill the region specified by destinationRect on the current target.

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureTiled(Texture, in Rect<float>, float)

Tries to tilingly copy a portion of a texture to the entirety of the current target with a specified scale

public bool TryRenderTextureTiled(Texture texture, in Rect<float> sourceRect, float scale)

Parameters

texture Texture: The texture to copy
sourceRect Rect<float>: The area of the texture to copy
scale float: The scale used to transform the sourceRect into the current target

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

TryRenderTextureTiled(Texture, float)

Tries to tilingly copy the entirety of a texture to the entirety of the current target with a specified scale

public bool TryRenderTextureTiled(Texture texture, float scale)

Parameters

texture Texture: The texture to copy
scale float: The scale used to transform the texture into the current target

Returns

bool: true, if the texture was rendered successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Only textures created with this renderer can be rendered with this method.

Rendering the texture works with sub-pixel precision.

This method should only be called from the main thread.

Table of Contents

Class Renderer

Remarks

Properties

ClippingRect

Property Value

Remarks

Exceptions

ColorScale

Property Value

Remarks

Exceptions

CurrentOutputSize

Property Value

Remarks

Exceptions

DefaultTextureScaleMode

Property Value

Remarks

Exceptions

DrawBlendMode

Property Value

Remarks

Exceptions

DrawColor

Property Value

Remarks

Exceptions

DrawColorFloat

Property Value

Remarks

Exceptions

HdrHeadroom

Property Value

Remarks

IsClippingEnabled

Property Value

Remarks

IsHdrEnabled

Property Value

Remarks

IsViewportSet

Property Value

Remarks

LogicalPresentation

Property Value

Remarks

Exceptions

LogicalPresentationRect

Property Value

Remarks

Exceptions

MaximumTextureSize

Property Value

Remarks

Name

Property Value

Remarks

OutputColorSpace

Property Value

OutputSize

Property Value

Remarks

Exceptions

Properties

Property Value

SafeArea

Property Value

Remarks

Exceptions

Scale

Property Value

Remarks

Exceptions

SdrWhitePoint

Property Value

Remarks

SupportedTextureFormats

Property Value

Remarks