TSdlRenderer
Rendering state
Definition
Unit: Neslib.Sdl3.Video
Properties
| Name | Description |
|---|---|
| ClipRect | The clip rectangle for rendering on the specified target, relative to the viewport (or an empty rectangle if clipping is disabled). |
| ColorScale | Set the color scale used for render operations. |
| CurrentOutputSize | The current output size in pixels of a rendering context. |
| DrawBlendMode | Set the blend mode used for drawing operations (Fill and Line). |
| DrawColor | The (integer) color used for drawing operations (for drawing or filling rectangles, lines, and points, and for Clear). |
| DrawColorFloat | The (floating-point) color used for drawing operations (for drawing or filling rectangles, lines, and points, and for Clear). |
| DriverCount | The number of 2D rendering drivers available for the current display. |
| Drivers | The names of the built in 2D rendering driver (or an empty string if an invalid index is given). |
| IsClipEnabled | Whether clipping is enabled on the given render target. |
| IsViewportSet | Whether an explicit rectangle was set as the viewport. |
| LogicalPresentationRect | Get the final presentation rectangle for rendering. |
| MetalCommandEncoder | Get the Metal command encoder for the current frame. |
| MetalLayer | The CAMetalLayer associated with the given Metal renderer. |
| Name | The name of the renderer. |
| OutputSize | The output size in pixels of a rendering context. |
| Properties | The properties associated with the renderer. |
| SafeArea | The safe area for rendering within the current viewport. |
| Scale | The drawing scale for rendering on the current target. |
| Target | The current rendering target. |
| Viewport | The drawing area for rendering on the current target. |
| VSync | The VSync of the renderer. |
| Window | The window associated with the renderer. |
Constructors
| Name | Description |
|---|---|
| Create(TSdlSurface) | Create a 2D software rendering context for a surface. |
| Create(TSdlProperties) | Create a 2D rendering context for a window, with the specified properties. |
| Create(TSdlWindow, String) | Create a 2D rendering context for a window. |
| Create(String, Integer, Integer, TSdlWindowFlags, TSdlWindow) | Create a default renderer and window. |
Operators
| Name | Description |
|---|---|
| Equal(TSdlRenderer, TSdlRenderer) | Used to compare against another TSdlRenderer. |
| Equal(TSdlRenderer, Pointer) | Used to compare against nil. |
| Implicit | Used to set the value to nil. |
| NotEqual(TSdlRenderer, TSdlRenderer) | Used to compare against another TSdlRenderer. |
| NotEqual(TSdlRenderer, Pointer) | Used to compare against nil. |
Methods
| Name | Description |
|---|---|
| AddVulkanSemaphores | Add a set of synchronization semaphores for the current frame when using Vulkan. |
| Clear | Clear the current rendering target with the drawing color. |
| CreateTexture(TSdlProperties) | Create a texture for this rendering context with the specified properties. |
| CreateTexture(TSdlSurface) | Create a texture for this rendering context from an existing surface. |
| CreateTexture(TSdlPixelFormat, TSdlTextureAccess, Integer, Integer) | Create a texture for this rendering context. |
| DrawDebugText(TSdlPointF, String) | Draw debug text. |
| DrawDebugText(Single, Single, String) | Draw debug text. |
| DrawGeometry(TSdlTexture, TArray<TSdlPointF>, Integer, TArray<TSdlColorF>, Integer, TArray<TSdlPointF>, Integer, Pointer, Integer, TSdlIndexType) | Render a list of triangles, optionally using a texture and indices into the vertex array. Color and alpha modulation is done per vertex (TSdlTexture.ColorMod and TSdlTexture.AlphaMod are ignored). |
| DrawGeometry(TArray<TSdlPointF>, Integer, TArray<TSdlColorF>, Integer, TArray<TSdlPointF>, Integer, Pointer, Integer, TSdlIndexType) | Render a list of triangles, optionally using indices into the vertex array. Color and alpha modulation is done per vertex (TSdlTexture.ColorMod and TSdlTexture.AlphaMod are ignored). |
| DrawGeometry(TSdlTexture, TArray<TSdlVertex>, TArray<Integer>) | Render a list of triangles, optionally using a texture and indices into the vertex array. Color and alpha modulation is done per vertex (TSdlTexture.ColorMod and TSdlTexture.AlphaMod are ignored). |
| DrawGeometry(TArray<TSdlVertex>, TArray<Integer>) | Render a list of triangles, optionally using indices into the vertex array. Color and alpha modulation is done per vertex. |
| DrawLine(TSdlPointF, TSdlPointF) | Draw a line on the current rendering target at subpixel precision. |
| DrawLine(Single, Single, Single, Single) | Draw a line on the current rendering target at subpixel precision. |
| DrawLines(TSdlPointF[]) | Draw a series of connected lines on the current rendering target at subpixel precision. |
| DrawLines(TArray<TSdlPointF>) | Draw a series of connected lines on the current rendering target at subpixel precision. |
| DrawPoint(TSdlPointF) | Draw a point on the current rendering target at subpixel precision. |
| DrawPoint(Single, Single) | Draw a point on the current rendering target at subpixel precision. |
| DrawPoints(TSdlPointF[]) | Draw multiple points on the current rendering target at subpixel precision. |
| DrawPoints(TArray<TSdlPointF>) | Draw multiple points on the current rendering target at subpixel precision. |
| DrawRect | Draw a rectangle on the current rendering target at subpixel precision. |
| DrawRects(TSdlRectF[]) | Draw some number of rectangles on the current rendering target at subpixel precision. |
| DrawRects(TArray<TSdlRectF>) | Draw some number of rectangles on the current rendering target at subpixel precision. |
| DrawTexture(TSdlTexture, TSdlRectF, TSdlRectF) | Copy a portion of the texture to the current rendering target at subpixel precision. |
| DrawTexture(TSdlTexture, TSdlRectF) | Copy the texture to the current rendering target at subpixel precision. |
| DrawTexture(TSdlTexture) | Copy the texture to fill the entire current rendering target. |
| DrawTexture9Grid(TSdlTexture, TSdlRectF, Single, Single, Single, Single, Single, TSdlRectF) | Perform a scaled copy using the 9-grid algorithm to the current rendering target at subpixel precision. |
| DrawTexture9Grid(TSdlTexture, Single, Single, Single, Single, Single, TSdlRectF) | Perform a scaled copy using the 9-grid algorithm to the current rendering target at subpixel precision. |
| DrawTextureAffine(TSdlTexture, TSdlRectF, TSdlPointF, TSdlPointF, TSdlPointF) | Copy a portion of the source texture to the current rendering target, with affine transform, at subpixel precision. |
| DrawTextureAffine(TSdlTexture, TSdlPointF, TSdlPointF, TSdlPointF) | Copy the source texture to the current rendering target, with affine transform, at subpixel precision. |
| DrawTextureRotated(TSdlTexture, TSdlRectF, TSdlRectF, Double, TSdlPointF, TSdlFlipModes) | Copy a portion of the source texture to the current rendering target, with rotation and flipping, at subpixel precision. |
| DrawTextureRotated(TSdlTexture, TSdlRectF, TSdlRectF, Double, TSdlFlipModes) | Copy a portion of the source texture to the current rendering target, with rotation and flipping, at subpixel precision. |
| DrawTextureRotated(TSdlTexture, TSdlRectF, Double, TSdlPointF, TSdlFlipModes) | Copy the source texture to the current rendering target, with rotation and flipping, at subpixel precision. |
| DrawTextureRotated(TSdlTexture, TSdlRectF, Double, TSdlFlipModes) | Copy the source texture to the current rendering target, with rotation and flipping, at subpixel precision. |
| DrawTextureTiled(TSdlTexture, TSdlRectF, Single, TSdlRectF) | Tile a portion of the texture to the current rendering target at subpixel precision. |
| DrawTextureTiled(TSdlTexture, Single, TSdlRectF) | Tile the texture to the current rendering target at subpixel precision. |
| FillRect | Fill a rectangle on the current rendering target with the drawing color at subpixel precision. |
| FillRects(TSdlRectF[]) | Fill some number of rectangles on the current rendering target with the drawing color at subpixel precision. |
| FillRects(TArray<TSdlRectF>) | Fill some number of rectangles on the current rendering target with the drawing color at subpixel precision. |
| Flush | Force the rendering context to flush any pending commands and state. |
| ForWindow | Get the renderer associated with a window. |
| Free | Destroy the rendering context for a window and free all associated textures. |
| GetLogicalPresentation | Get device independent resolution and presentation mode for rendering. |
| Present | Update the screen with any rendering performed since the previous call. |
| ReadPixels(TSdlRect) | Read pixels from the current rendering target. |
| ReadPixels | Read pixels from the entire viewport of the current rendering target. |
| RenderCoordinatesFromWindow | Get a point in render coordinates when given a point in window coordinates. |
| RenderCoordinatesToWindow | Get a point in window coordinates when given a point in render coordinates. |
| ResetViewport | Set the viewport to the entire target. |
| SetDrawColor | Set the (integer) color used for drawing operations. |
| SetDrawColorFloat | Set the (floating-point) color used for drawing operations. |
| SetLogicalPresentation | Set a device-independent resolution and presentation mode for rendering. |
Property Descriptions
ClipRect
The clip rectangle for rendering on the specified target, relative to the viewport (or an empty rectangle if clipping is disabled).
To disable clipping, set IsClipEnabled to False.
Each render target has its own clip rectangle. This property applies to the current render target.
property ClipRect: TSdlRect read GetClipRect write SetClipRect
Type: TSdlRect
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
ColorScale
Set the color scale used for render operations.
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.
property ColorScale: Single read GetColorScale write SetColorScale
Type: Single
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
CurrentOutputSize
The current output size in pixels of a rendering context.
If a rendering target is active, this will return the size of the rendering target in pixels, otherwise return the value of OutputSize.
Rendering target or not, the output will be adjusted by the current logical presentation state, dictated by SetLogicalPresentation.
property CurrentOutputSize: TSdlSize read GetCurrentOutputSize
Type: TSdlSize
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
DrawBlendMode
Set the blend mode used for drawing operations (Fill and Line).
If the blend mode is not supported, the closest supported mode is chosen.
property DrawBlendMode: TSdlBlendMode read GetDrawBlendMode write SetDrawBlendMode
Type: TSdlBlendMode
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
DrawColor
The (integer) color used for drawing operations (for drawing or filling rectangles, lines, and points, and for Clear).
property DrawColor: TSdlColor read GetDrawColor write SetDrawColor
Type: TSdlColor
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
DrawColorFloat
The (floating-point) color used for drawing operations (for drawing or filling rectangles, lines, and points, and for Clear).
property DrawColorFloat: TSdlColorF read GetDrawColorFloat write SetDrawColorFloat
Type: TSdlColorF
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
DriverCount
The number of 2D rendering drivers available for the current display.
A render driver is a set of code that handles rendering and texture management on a particular display. Normally there is only one, but some drivers may have several available with different capabilities.
There may be none if SDL was compiled without render support.
class property DriverCount: Integer read GetDriverCount
Type: Integer
See Also
Remarks
It is safe to use this property from any thread.
Drivers
The names of the built in 2D rendering driver (or an empty string if an invalid index is given).
The list of rendering drivers is given in the order that they are normally initialized by default; the drivers that seem more reasonable to choose first (as far as the SDL developers believe) are earlier in the list.
The names of drivers are all simple, low-ASCII identifiers, like 'opengl', 'direct3d12' or 'metal'. These never have Unicode characters, and are not meant to be proper names.
class property Drivers[const AIndex: Integer]: String read GetDriver
Type: String
See Also
Remarks
It is safe to use this property from any thread.
IsClipEnabled
Whether clipping is enabled on the given render target.
Each render target has its own clip rectangle. This property checks the cliprect for the current render target.
Set this property to False to disable clipping. To enable clipping, set the ClipRect property.
property IsClipEnabled: Boolean read GetIsClipEnabled write SetIsClipEnabled
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
IsViewportSet
Whether an explicit rectangle was set as the viewport.
This is useful if you're saving and restoring the viewport and want to know whether you should restore a specific rectangle or reset the viewport. Note that the viewport is always reset when changing rendering targets.
Each render target has its own viewport. This property checks the viewport for the current render target.
property IsViewportSet: Boolean read GetIsViewportSet
Type: Boolean
See Also
Remarks
This property should only be used on the main thread.
LogicalPresentationRect
Get the final presentation rectangle for rendering.
This property returns the calculated rectangle used for logical presentation, based on the presentation mode and output size. If logical presentation is disabled, it will fill the rectangle with the output size, in pixels.
Each render target has its own logical presentation state. This function gets the rectangle for the current render target.
property LogicalPresentationRect: TSdlRect read GetLogicalPresentationRect
Type: TSdlRect
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
MetalCommandEncoder
Get the Metal command encoder for the current frame.
This property returns a pointer, so SDL doesn't have to link to Metal.
Returns nil if the renderer isn't a Metal renderer, or if Metal refuses to give SDL a drawable to render to, which might happen if the window is hidden/minimized/offscreen. This doesn't apply to command encoders for render targets, just the window's backbuffer. Check your return values!
property MetalCommandEncoder: Pointer read GetMetalCommandEncoder
Type: Pointer
See Also
Remarks
This property should only be used on the main thread.
MetalLayer
The CAMetalLayer associated with the given Metal renderer.
This property returns a pointer, so SDL doesn't have to link to Metal, but it can be safely cast to a CAMetalLayer using TCAMetalLayer.Wrap().
Returns nil if the renderer isn't a Metal renderer.
property MetalLayer: Pointer read GetMetalLayer
Type: Pointer
See Also
Remarks
This property should only be used on the main thread.
Name
The name of the renderer.
property Name: String read GetName
Type: String
Exceptions
ESdlError: Raised on failure.
Remarks
It is safe to use this property from any thread.
OutputSize
The output size in pixels of a rendering context.
This returns the true output size in pixels, ignoring any render targets or logical size and presentation.
For the output size of the current rendering target, with logical size adjustments, use CurrentOutputSize instead.
property OutputSize: TSdlSize read GetOutputSize
Type: TSdlSize
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
Properties
The properties associated with the renderer.
The following read-only properties are provided by SDL:
TSdlProperty.RendererName: the name of the rendering driverTSdlProperty.RendererWindow: the window where rendering is displayed, if anyTSdlProperty.RendererSurface: the surface where rendering is displayed, if this is a software renderer without a windowTSdlProperty.RendererVSync: the current vsync settingTSdlProperty.RendererMaxTextureSize: the maximum texture width and heightTSdlProperty.RendererTextureFormats: a PSdlPixelFormat array of pixel formats, terminated with TSdlPixelFormat.Unknown, representing the available texture formats for this renderer.TSdlProperty.RendererOutputColorspace: a TSdlColorspace value describing the colorspace for output to the display, defaults to TSdlColorspace.Srgb.TSdlProperty.RendererHdrEnabled: True if the output colorspace is TSdlColorspace.SrgbLinear and the renderer is showing on a display with HDR enabled. This property can change dynamically when TSdlEventKind.WindowHdrStateChanged is sent.TSdlProperty.RendererSdrWhitePoint: the value of SDR white in the TSdlColorspace.SrgbLinear colorspace. When HDR is enabled, this value is automatically multiplied into the color scale. This property can change dynamically when TSdlEventKind.HdrStateChanged is sent.TSdlProperty.RendererHdrHeadroom: the additional high dynamic range that can be displayed, in terms of the SDR white point. When HDR is not enabled, this will be 1.0. This property can change dynamically when TSdlEventKind.HdrStateChanged is sent.
With the Direct3D renderer:
TSdlProperty.RendererD3D9Device: the IDirect3DDevice9 associated with the renderer
With the Direct3D11 renderer:
TSdlProperty.RendererD3D11Device: the ID3D11Device associated with the rendererTSdlProperty.RendererD3D11SwapChain: the IDXGISwapChain1 associated with the renderer. This may change when the window is resized.
With the Direct3D12 renderer:
TSdlProperty.RendererD3D12Device: the ID3D12Device associated with the rendererTSdlProperty.RendererD3D12SwapChain: the IDXGISwapChain4 associated with the renderer.TSdlProperty.RendererD3D12CommandQueue: the ID3D12CommandQueue associated with the renderer
With the vulkan renderer:
TSdlProperty.RendererVulkanInstance: the VkInstance associated with the rendererTSdlProperty.RendererVulkanSurface: the VkSurfaceKHR associated with the rendererTSdlProperty.RendererVulkanPhysicalDevice: the VkPhysicalDevice associated with the rendererTSdlProperty.RendererVulkanDevice: the VkDevice associated with the rendererTSdlProperty.RendererVulkanGraphicsQueueFamilyIndex: the queue family index used for renderingTSdlProperty.RendererVulkanPresentQueueFamilyIndex: the queue family index used for presentationTSdlProperty.RendererVulkanSwapChainImageCount: the number of swapchain images, or potential frames in flight, used by the Vulkan renderer
With the GPU renderer:
TSdlProperty.RendererGpuDevice: the TSdlGpuDevice associated with the renderer
property Properties: TSdlProperties read GetProperties
Type: TSdlProperties
Exceptions
ESdlError: Raised on failure.
Remarks
It is safe to use this property from any thread.
SafeArea
The safe area for rendering within the current viewport.
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 function 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.
property SafeArea: TSdlRect read GetSafeArea
Type: TSdlRect
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Scale
The drawing scale for rendering on the current target.
The drawing coordinates are scaled by the X/Y scaling factors before they are used by the renderer. This allows 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 has its own scale. This property applies to the current render target.
property Scale: TSdlPointF read GetScale write SetScale
Type: TSdlPointF
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Target
The current rendering target.
The default render target is the window for which the renderer was created. To stop rendering to a texture and render to the window again, set this property to a nil texture.
Viewport, cliprect, scale, and logical presentation are unique to each render target. Functions and properties for these states apply to the current render target set by this function, and those states persist on each target when the current render target changes.
property Target: TSdlTexture read GetTarget write SetTarget
Type: TSdlTexture
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Viewport
The drawing area for rendering on the current target.
Drawing will clip to this area (separately from any clipping done with ClipRect), and the top left of the area will become coordinate (0, 0) for future drawing commands.
The area's width and height must be >= 0.
Each render target has its own viewport. This property applies to the current render target.
Call ResetViewport to set the viewport to the entire target.
property Viewport: TSdlRect read GetViewport write SetViewport
Type: TSdlRect
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
VSync
The VSync of the renderer.
When a renderer is created, vsync defaults to TSdlRendererVSync.Disabled.
Can be 1 to synchronize present with every vertical refresh, 2 to synchronize present with every second vertical refresh, etc., TSdlRendererVSync.Adaptive for late swap tearing (adaptive vsync), or TSdlRendererVSync.Disabled to disable. Not every value is supported by every driver, so you should check the return value to see whether the requested setting is supported.
property VSync: TSdlRendererVsync read GetVSync write SetVSync
Type: TSdlRendererVsync
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Window
The window associated with the renderer.
property Window: TSdlWindow read GetWindow
Type: TSdlWindow
Exceptions
ESdlError: Raised on failure.
Remarks
It is safe to use this property from any thread.
Constructor Descriptions
Create
Create a 2D software rendering context for a surface.
The other constructors can also create a software renderer, but they are intended to be used with a TSdlWindow as the final destination and not a TSdlSurface.
constructor Create(const ASurface: TSdlSurface); overload
Parameters
ASurface: TSdlSurface
: The srface where rendering is done.
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This constructor should only be called on the main thread.
Create
Create a 2D rendering context for a window, with the specified properties.
These are the supported properties:
TSdlProperty.RendererCreateName: the name of the rendering driver to use, if a specific one is desiredTSdlProperty.RendererCreateWindow: the window where rendering is displayed, required if this isn't a software renderer using a surfaceTSdlProperty.RendererCreateSurface: the surface where rendering is displayed, if you want a software renderer without a windowTSdlProperty.RendererCreateOutputColorspace: a TSdlColorspace value describing the colorspace for output to the display, defaults to TSdlColorspace.Srgb. The Direct3D11, Direct3D12, and Metal renderers support TSdlColorspace.SrgbLinear, which is a linear color space and supports HDR output. If you select TSdlColorspace.SrgbLinear, drawing still uses the sRGB colorspace, but values can go beyond 1.0 and float (linear) format textures can be used for HDR content.TSdlProperty.RendererCreatePresentVSync: non-zero if you want present synchronized with the refresh rate. This property can take any value that is supported by the VSync property for the renderer.
With the vulkan renderer:
TSdlProperty.RendererCreateVulkanInstance: the VkInstance to use with the renderer, optional.TSdlProperty.RendererCreateVulkanSurface: the VkSurfaceKHR to use with the renderer, optional.TSdlProperty.RendererCreateVulkanPhysicalDevice: the VkPhysicalDevice to use with the renderer, optional.TSdlProperty.RendererCreateVulkanDevice: the VkDevice to use with the renderer, optional.TSdlProperty.RendererCreateVulkanGraphicsQueueFamilyIndex: the queue family index used for rendering.TSdlProperty.RendererCreateVulkanPresentQueueFamilyIndex: the queue family index used for presentation.
constructor Create(const AProperties: TSdlProperties); overload
Parameters
AProperties: TSdlProperties
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This constructor should only be called on the main thread.
Create
Create a 2D rendering context for a window.
If you want a specific renderer, you can specify its name here. A list of available renderers can be obtained through the RenderDriverCount and RenderDrivers properties. If you don't need a specific renderer, don't specify a name (or an empty string) and SDL will attempt to choose the best option for you, based on what is available on the user's system.
If AName is a comma-separated list, SDL will try each name, in the order listed, until one succeeds or all of them fail.
By default the rendering size matches the window size in pixels, but you can set LogicalPresentation to change the content size and scaling options.
constructor Create(const AWindow: TSdlWindow; const AName: String = ''); overload
Parameters
AWindow: TSdlWindow
: The window where rendering is displayed.
AName: String = ''
: (Optional) name of the rendering driver to initialize, or an empty string to let SDL choose one.
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This constructor should only be called on the main thread.
Create
Create a default renderer and window.
constructor Create(const ATitle: String; const AWidth, AHeight: Integer; const AWindowFlags: TSdlWindowFlags; out AWindow: TSdlWindow); overload
Parameters
ATitle: String
: The title of the window.
AWidth: Integer
: The width of the window.
AHeight: Integer
: The height of the window.
AWindowFlags: TSdlWindowFlags
: The flags used to create the window (see TSdlWindow.Create).
AWindow: TSdlWindow
: Is set to the newly created window.
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This constructor should only be called on the main thread.
Operator Descriptions
Equal(TSdlRenderer, TSdlRenderer)
Used to compare against another TSdlRenderer.
class operator Equal(const ALeft, ARight: TSdlRenderer): Boolean; inline; static
Parameters
ALeft: TSdlRenderer
ARight: TSdlRenderer
Returns
Boolean
Equal(TSdlRenderer, Pointer)
Used to compare against nil.
class operator Equal(const ALeft: TSdlRenderer; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlRenderer
ARight: Pointer
Returns
Boolean
Implicit(Pointer)
Used to set the value to nil.
class operator Implicit(const AValue: Pointer): TSdlRenderer; inline; static
Parameters
AValue: Pointer
Returns
NotEqual(TSdlRenderer, TSdlRenderer)
Used to compare against another TSdlRenderer.
class operator NotEqual(const ALeft, ARight: TSdlRenderer): Boolean; inline; static
Parameters
ALeft: TSdlRenderer
ARight: TSdlRenderer
Returns
Boolean
NotEqual(TSdlRenderer, Pointer)
Used to compare against nil.
class operator NotEqual(const ALeft: TSdlRenderer; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlRenderer
ARight: Pointer
Returns
Boolean
Method Descriptions
AddVulkanSemaphores(UInt32, Int64, Int64)
Add a set of synchronization semaphores for the current frame when using Vulkan.
The Vulkan renderer will wait for AWaitSemaphore before submitting rendering commands and signal ASignalSemaphore after rendering commands are complete for this frame.
This should be called each frame that you want semaphore synchronization. The Vulkan renderer may have multiple frames in flight on the GPU, so you should have multiple semaphores that are used for synchronization. Querying TSdlProperty.RendererVulkanSwapChainImageCount will give you the maximum number of semaphores you'll need.
procedure AddVulkanSemaphores(const AWaitStageMask: UInt32; const AWaitSemaphore, ASignalSemaphore: Int64); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AWaitStageMask: UInt32
: The VkPipelineStageFlags for the wait.
AWaitSemaphore: Int64
: A VkSempahore to wait on before rendering the current frame, or 0 if not needed.
ASignalSemaphore: Int64
: A VkSempahore that SDL will signal when rendering for the current frame is complete, or 0 if not needed.
Remarks
It is NOT safe to call this method from two threads at once.
Clear
Clear the current rendering target with the drawing color.
This function clears the entire rendering target, ignoring the viewport and the clip rectangle. Note, that clearing will also set/fill all pixels of the rendering target to current renderer draw color, so make sure to invoke SetDrawColor when needed.
procedure Clear; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
CreateTexture(TSdlProperties)
Create a texture for this rendering context with the specified properties.
These are the supported properties:
TSdlProperty.TextureCreateColorspace: a TSdlColorspace value describing the texture colorspace, defaults to TSdlColorspace.SrgbLinear for floating point textures, TSdlColorspace.Hdr10 for 10-bit textures, TSdlColorspace.Srgb for other RGB textures and TSdlColorspace.Jpeg for YUV textures.TSdlProperty.TextureCreateFormat: one of the enumerated values in TSdlPixelFormat, defaults to the best RGBA format for the renderer.TSdlProperty.TextureCreateAccess: one of the enumerated values in TSdlTextureAccess, defaults to TSdlTextureAccess.Static.TSdlProperty.TextureCreateWidth: the width of the texture in pixels, requiredTSdlProperty.TextureCreateHeight: the height of the texture in pixels, requiredTSdlProperty.TextureCreateSdrWhitePoint: for HDR10 and floating point textures, this defines the value of 100% diffuse white, with higher values being displayed in the High Dynamic Range headroom. This defaults to 100 for HDR10 textures and 1.0 for floating point textures.TSdlProperty.TextureCreateHdrHeadroom: for HDR10 and floating point textures, this defines the maximum dynamic range used by the content, in terms of the SDR white point. This would be equivalent to maxCLL / TSdlProperty.TextureCreateSdrWhitePoint for HDR10 content. If this is defined, any values outside the range supported by the display will be scaled into the available HDR headroom, otherwise they are clipped.
With the Direct3D11 renderer:
TSdlProperty.TextureCreateD3D11Texture: the ID3D11Texture2D associated with the texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateD3D11TextureU: the ID3D11Texture2D associated with the U plane of a YUV texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateD3D11TextureV: the ID3D11Texture2D associated with the V plane of a YUV texture, if you want to wrap an existing texture.
With the Direct3D12 renderer:
TSdlProperty.TextureCreateD3D12Texture: the ID3D12Resource associated with the texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateD3D12TextureU: the ID3D12Resource associated with the U plane of a YUV texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateD3D12TextureV: the ID3D12Resource associated with the V plane of a YUV texture, if you want to wrap an existing texture.
With the Metal renderer:
TSdlProperty.TextureCreateMetalPixelBuffer: the CVPixelBufferRef associated with the texture, if you want to create a texture from an existing pixel buffer.
With the OpenGL renderer:
TSdlProperty.TextureCreateOpenGLTexture: the GLuint texture associated with the texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateOpenGLTextureUV: the GLuint texture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateOpenGLTextureU: the GLuint texture associated with the U plane of a YUV texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateOpenGLTextureV: the GLuint texture associated with the V plane of a YUV texture, if you want to wrap an existing texture.
With the OpenGL-ES2 renderer:
TSdlProperty.TextureCreateOpenGles2Texture: the GLuint texture associated with the texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateOpenGles2TextureUV: the GLuint texture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateOpenGles2TextureU: the GLuint texture associated with the U plane of a YUV texture, if you want to wrap an existing texture.TSdlProperty.TextureCreateOpenGles2TextureV: the GLuint texture associated with the V plane of a YUV texture, if you want to wrap an existing texture.
With the Vulkan renderer:
TSdlProperty.TextureCreateVulkanTexture: the VkImage with layout VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL associated with the texture, if you want to wrap an existing texture.
function CreateTexture(const AProps: TSdlProperties): TSdlTexture; overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AProps: TSdlProperties
: The properties to use.
Returns
See Also
Remarks
This constructor should only be called on the main thread.
CreateTexture(TSdlSurface)
Create a texture for this rendering context from an existing surface.
The surface is not modified or freed by this function.
The TSdlTextureAccess hint for the created texture is TSdlHints.TextureAccessStatic.
The pixel format of the created texture may be different from the pixel format of the surface, and can be queried using the TSdlProperty.TextureFormat property.
function CreateTexture(const ASurface: TSdlSurface): TSdlTexture; overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ASurface: TSdlSurface
: The surface containing pixel data used to fill the texture.
Returns
See Also
Remarks
This method should only be called on the main thread.
CreateTexture(TSdlPixelFormat, TSdlTextureAccess, Integer, Integer)
Create a texture for this rendering context.
The contents of a texture when first created are not defined.
function CreateTexture(const AFormat: TSdlPixelFormat; const AAccess: TSdlTextureAccess; const AW, AH: Integer): TSdlTexture; overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AFormat: TSdlPixelFormat
: The pixel format.
AAccess: TSdlTextureAccess
: Texture access.
AW: Integer
: The width of the texture in pixels.
AH: Integer
: The height of the texture in pixels.
Returns
See Also
Remarks
This method should only be called on the main thread.
DrawDebugText(TSdlPointF, String)
Draw debug text.
This function will render a string of text. Note that this is a convenience function for debugging, with severe limitations, and not intended to be used for production apps and games.
Among these limitations:
- It will only renders ASCII characters.
- It has a single, tiny size (8x8 pixels). One can use logical presentation or scaling to adjust it, but it will be blurry.
- It uses a simple, hardcoded bitmap font. It does not allow different font selections and it does not support truetype, for proper scaling.
- It does no word-wrapping and does not treat newline characters as a line break. If the text goes out of the window, it's gone.
For serious text rendering, there are several good options, such as SDL_ttf, stb_truetype, or other external libraries.
On first use, this will create an internal texture for rendering glyphs. This texture will live until the renderer is destroyed.
The text is drawn in the color specified by DrawColor.
procedure DrawDebugText(const APosition: TSdlPointF; const AString: String); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
APosition: TSdlPointF
: The top-left corner of the text will draw. will draw.
AString: String
See Also
Remarks
This method should only be called on the main thread.
DrawDebugText(Single, Single, String)
Draw debug text.
This function will render a string of text. Note that this is a convenience function for debugging, with severe limitations, and not intended to be used for production apps and games.
Among these limitations:
- It will only renders ASCII characters.
- It has a single, tiny size (8x8 pixels). One can use logical presentation or scaling to adjust it, but it will be blurry.
- It uses a simple, hardcoded bitmap font. It does not allow different font selections and it does not support truetype, for proper scaling.
- It does no word-wrapping and does not treat newline characters as a line break. If the text goes out of the window, it's gone.
For serious text rendering, there are several good options, such as SDL_ttf, stb_truetype, or other external libraries.
On first use, this will create an internal texture for rendering glyphs. This texture will live until the renderer is destroyed.
The text is drawn in the color specified by DrawColor.
procedure DrawDebugText(const AX, AY: Single; const AString: String); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AX: Single
: The X coordinate where the top-left corner of the text will draw.
AY: Single
: the Y coordinate where the top-left corner of the text will draw.
AString: String
See Also
Remarks
This method should only be called on the main thread.
DrawGeometry(TSdlTexture, TArray<TSdlPointF>, Integer, TArray<TSdlColorF>, Integer, TArray<TSdlPointF>, Integer, Pointer, Integer, TSdlIndexType)
Render a list of triangles, optionally using a texture and indices into the vertex array. Color and alpha modulation is done per vertex (TSdlTexture.ColorMod and TSdlTexture.AlphaMod are ignored).
procedure DrawGeometry(const ATexture: TSdlTexture; const AXY: TArray<TSdlPointF>; const AXYStride: Integer; const AColor: TArray<TSdlColorF>; const AColorStride: Integer; const AUV: TArray<TSdlPointF>; const AUVStride: Integer; const AIndices: Pointer = nil; const ANumIndices: Integer = 0; const AIndexType: TSdlIndexType = TSdlIndexType.Word); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The texture to use.
AXY: TArray<TSdlPointF>
: Vertex positions.
AXYStride: Integer
: Byte size to move from one element to the next element.
AColor: TArray<TSdlColorF>
: Vertex colors.
AColorStride: Integer
: Byte size to move from one element to the next element.
AUV: TArray<TSdlPointF>
: Vertex normalized texture coordinates.
AUVStride: Integer
: Byte size to move from one element to the next element.
AIndices: Pointer = nil
: (Optional) Pointer to an array of indices into the vertex arrays. If nil (default) all vertices will be rendered in sequential order.
ANumIndices: Integer = 0
: Number of indices.
AIndexType: TSdlIndexType = TSdlIndexType.Word
: (Optional) type of each index in AIndices. Defaults to TSdlIndexType.Word
Remarks
This method should only be called on the main thread.
DrawGeometry(TArray<TSdlPointF>, Integer, TArray<TSdlColorF>, Integer, TArray<TSdlPointF>, Integer, Pointer, Integer, TSdlIndexType)
Render a list of triangles, optionally using indices into the vertex array. Color and alpha modulation is done per vertex (TSdlTexture.ColorMod and TSdlTexture.AlphaMod are ignored).
procedure DrawGeometry(const AXY: TArray<TSdlPointF>; const AXYStride: Integer; const AColor: TArray<TSdlColorF>; const AColorStride: Integer; const AUV: TArray<TSdlPointF>; const AUVStride: Integer; const AIndices: Pointer = nil; const ANumIndices: Integer = 0; const AIndexType: TSdlIndexType = TSdlIndexType.Word); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AXY: TArray<TSdlPointF>
: Vertex positions.
AXYStride: Integer
: Byte size to move from one element to the next element.
AColor: TArray<TSdlColorF>
: Vertex colors.
AColorStride: Integer
: Byte size to move from one element to the next element.
AUV: TArray<TSdlPointF>
: Vertex normalized texture coordinates.
AUVStride: Integer
: Byte size to move from one element to the next element.
AIndices: Pointer = nil
: (Optional) Pointer to an array of indices into the vertex arrays. If nil (default) all vertices will be rendered in sequential order.
ANumIndices: Integer = 0
: Number of indices.
AIndexType: TSdlIndexType = TSdlIndexType.Word
: (Optional) type of each index in AIndices. Defaults to TSdlIndexType.Word
Remarks
This method should only be called on the main thread.
DrawGeometry(TSdlTexture, TArray<TSdlVertex>, TArray<Integer>)
Render a list of triangles, optionally using a texture and indices into the vertex array. Color and alpha modulation is done per vertex (TSdlTexture.ColorMod and TSdlTexture.AlphaMod are ignored).
procedure DrawGeometry(const ATexture: TSdlTexture; const AVertices: TArray<TSdlVertex>; const AIndices: TArray<Integer> = nil); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: Texture to use.
AVertices: TArray<TSdlVertex>
: The vertices.
AIndices: TArray<Integer> = nil
: (Optional) Array of integer indices into the 'AVertices' array. If nil (default) all vertices will be rendered in sequential order.
Remarks
This method should only be called on the main thread.
DrawGeometry(TArray<TSdlVertex>, TArray<Integer>)
Render a list of triangles, optionally using indices into the vertex array. Color and alpha modulation is done per vertex.
procedure DrawGeometry(const AVertices: TArray<TSdlVertex>; const AIndices: TArray<Integer> = nil); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AVertices: TArray<TSdlVertex>
: The vertices.
AIndices: TArray<Integer> = nil
: (Optional) Array of integer indices into the 'AVertices' array. If nil (default) all vertices will be rendered in sequential order.
Remarks
This method should only be called on the main thread.
DrawLine(TSdlPointF, TSdlPointF)
Draw a line on the current rendering target at subpixel precision.
procedure DrawLine(const AP1, AP2: TSdlPointF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AP1: TSdlPointF
: The start point.
AP2: TSdlPointF
: The end point.
See Also
Remarks
This method should only be called on the main thread.
DrawLine(Single, Single, Single, Single)
Draw a line on the current rendering target at subpixel precision.
procedure DrawLine(const AX1, AY1, AX2, AY2: Single); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AX1: Single
: The X coordinate of the start point.
AY1: Single
: The Y coordinate of the start point.
AX2: Single
: The X coordinate of the end point.
AY2: Single
: The Y coordinate of the end point.
See Also
Remarks
This method should only be called on the main thread.
DrawLines(TSdlPointF[])
Draw a series of connected lines on the current rendering target at subpixel precision.
procedure DrawLines(const APoints: array of TSdlPointF); overload
Exceptions
ESdlError: Raised on failure.
Parameters
APoints: array of TSdlPointF
: The points along the lines.
See Also
Remarks
This method should only be called on the main thread.
DrawLines(TArray<TSdlPointF>)
Draw a series of connected lines on the current rendering target at subpixel precision.
procedure DrawLines(const APoints: TArray<TSdlPointF>); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
APoints: TArray<TSdlPointF>
: The points along the lines.
See Also
Remarks
This method should only be called on the main thread.
DrawPoint(TSdlPointF)
Draw a point on the current rendering target at subpixel precision.
procedure DrawPoint(const APoint: TSdlPointF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
APoint: TSdlPointF
See Also
Remarks
This method should only be called on the main thread.
DrawPoint(Single, Single)
Draw a point on the current rendering target at subpixel precision.
procedure DrawPoint(const AX, AY: Single); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AX: Single
: The X coordinate of the point.
AY: Single
: the Y coordinate of the point.
See Also
Remarks
This method should only be called on the main thread.
DrawPoints(TSdlPointF[])
Draw multiple points on the current rendering target at subpixel precision.
procedure DrawPoints(const APoints: array of TSdlPointF); overload
Exceptions
ESdlError: Raised on failure.
Parameters
APoints: array of TSdlPointF
: The points to draw.
See Also
Remarks
This method should only be called on the main thread.
DrawPoints(TArray<TSdlPointF>)
Draw multiple points on the current rendering target at subpixel precision.
procedure DrawPoints(const APoints: TArray<TSdlPointF>); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
APoints: TArray<TSdlPointF>
: The points to draw.
See Also
Remarks
This method should only be called on the main thread.
DrawRect(TSdlRectF)
Draw a rectangle on the current rendering target at subpixel precision.
procedure DrawRect(const ARect: TSdlRectF); inline
Exceptions
ESdlError: Raised on failure.
Parameters
ARect: TSdlRectF
: The destination rectangle.
See Also
Remarks
This method should only be called on the main thread.
DrawRects(TSdlRectF[])
Draw some number of rectangles on the current rendering target at subpixel precision.
procedure DrawRects(const ARects: array of TSdlRectF); overload
Exceptions
ESdlError: Raised on failure.
Parameters
ARects: array of TSdlRectF
: Array of destination rectangles.
See Also
Remarks
This method should only be called on the main thread.
DrawRects(TArray<TSdlRectF>)
Draw some number of rectangles on the current rendering target at subpixel precision.
procedure DrawRects(const ARects: TArray<TSdlRectF>); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ARects: TArray<TSdlRectF>
: Array of destination rectangles.
See Also
Remarks
This method should only be called on the main thread.
DrawTexture(TSdlTexture, TSdlRectF, TSdlRectF)
Copy a portion of the texture to the current rendering target at subpixel precision.
procedure DrawTexture(const ATexture: TSdlTexture; const ASrcRect, ADstRect: TSdlRectF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ASrcRect: TSdlRectF
: The source rectangle.
ADstRect: TSdlRectF
: The destination rectangle.
See Also
Remarks
This method should only be called on the main thread.
DrawTexture(TSdlTexture, TSdlRectF)
Copy the texture to the current rendering target at subpixel precision.
procedure DrawTexture(const ATexture: TSdlTexture; const ADstRect: TSdlRectF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ADstRect: TSdlRectF
: The destination rectangle.
See Also
Remarks
This method should only be called on the main thread.
DrawTexture(TSdlTexture)
Copy the texture to fill the entire current rendering target.
procedure DrawTexture(const ATexture: TSdlTexture); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
See Also
Remarks
This method should only be called on the main thread.
DrawTexture9Grid(TSdlTexture, TSdlRectF, Single, Single, Single, Single, Single, TSdlRectF)
Perform a scaled copy using the 9-grid algorithm to the current rendering target at subpixel precision.
The pixels in the texture are split into a 3x3 grid, using the different corner sizes for each corner, and the sides and center making up the remaining pixels. The corners are then scaled using AScale and fit into the corners of the destination rectangle. The sides and center are then stretched into place to cover the remaining destination rectangle.
procedure DrawTexture9Grid(const ATexture: TSdlTexture; const ASrcRect: TSdlRectF; const ALeftWidth, ARightWidth, ATopHeight, ABottomHeight, AScale: Single; const ADstRect: TSdlRectF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ASrcRect: TSdlRectF
: The rectangle to be used for the 9-grid
ALeftWidth: Single
: The width, in pixels, of the left corners in ASrcRect.
ARightWidth: Single
: The width, in pixels, of the right corners in ASrcRect.
ATopHeight: Single
: The height, in pixels, of the top corners in ASrcRect.
ABottomHeight: Single
: The height, in pixels, of the bottom corners in ASrcRect.
AScale: Single
: The scale used to transform the corner of ASrcRect into the corner of ADstRect, or 0.0 for an unscaled copy.
ADstRect: TSdlRectF
: The destination rectangle.
See Also
Remarks
This method should only be called on the main thread.
DrawTexture9Grid(TSdlTexture, Single, Single, Single, Single, Single, TSdlRectF)
Perform a scaled copy using the 9-grid algorithm to the current rendering target at subpixel precision.
The pixels in the texture are split into a 3x3 grid, using the different corner sizes for each corner, and the sides and center making up the remaining pixels. The corners are then scaled using AScale and fit into the corners of the destination rectangle. The sides and center are then stretched into place to cover the remaining destination rectangle.
procedure DrawTexture9Grid(const ATexture: TSdlTexture; const ALeftWidth, ARightWidth, ATopHeight, ABottomHeight, AScale: Single; const ADstRect: TSdlRectF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ALeftWidth: Single
: The width, in pixels, of the left corners.
ARightWidth: Single
: The width, in pixels, of the right corners.
ATopHeight: Single
: The height, in pixels, of the top corners.
ABottomHeight: Single
: The height, in pixels, of the bottom corners.
AScale: Single
: The scale used to transform the corner of the texture rectangle into the corner of ADstRect, or 0.0 for an unscaled copy.
ADstRect: TSdlRectF
: The destination rectangle.
See Also
Remarks
This method should only be called on the main thread.
DrawTextureAffine(TSdlTexture, TSdlRectF, TSdlPointF, TSdlPointF, TSdlPointF)
Copy a portion of the source texture to the current rendering target, with affine transform, at subpixel precision.
procedure DrawTextureAffine(const ATexture: TSdlTexture; const ASrcRect: TSdlRectF; const AOrigin, ARight, ADown: TSdlPointF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ASrcRect: TSdlRectF
: The source rectangle.
AOrigin: TSdlPointF
: Where the top-left corner of ASrcRect should be mapped to.
ARight: TSdlPointF
: Where the top-right corner of ASrcRect should be mapped to.
ADown: TSdlPointF
: Where the bottom-left corner of srcrect should be mapped to, or NULL for the rendering target's.
See Also
Remarks
This method should only be called on the main thread.
DrawTextureAffine(TSdlTexture, TSdlPointF, TSdlPointF, TSdlPointF)
Copy the source texture to the current rendering target, with affine transform, at subpixel precision.
procedure DrawTextureAffine(const ATexture: TSdlTexture; const AOrigin, ARight, ADown: TSdlPointF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
AOrigin: TSdlPointF
: Where the top-left corner of ASrcRect should be mapped to.
ARight: TSdlPointF
: Where the top-right corner of ASrcRect should be mapped to.
ADown: TSdlPointF
: Where the bottom-left corner of srcrect should be mapped to, or NULL for the rendering target's.
See Also
Remarks
This method should only be called on the main thread.
DrawTextureRotated(TSdlTexture, TSdlRectF, TSdlRectF, Double, TSdlPointF, TSdlFlipModes)
Copy a portion of the source texture to the current rendering target, with rotation and flipping, at subpixel precision.
procedure DrawTextureRotated(const ATexture: TSdlTexture; const ASrcRect, ADstRect: TSdlRectF; const AAngle: Double; const ACenter: TSdlPointF; const AFlip: TSdlFlipModes = []); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ASrcRect: TSdlRectF
: The source rectangle.
ADstRect: TSdlRectF
: The destination rectangle.
AAngle: Double
: An angle in degrees that indicates the rotation that will be applied to ADstRect, rotating it in a clockwise direction.
ACenter: TSdlPointF
: The point around which ADstRect will be rotated.
AFlip: TSdlFlipModes = []
: (Optional) flipping actions that should be performed on the texture. Defaults to [] (none).
See Also
Remarks
This method should only be called on the main thread.
DrawTextureRotated(TSdlTexture, TSdlRectF, TSdlRectF, Double, TSdlFlipModes)
Copy a portion of the source texture to the current rendering target, with rotation and flipping, at subpixel precision.
procedure DrawTextureRotated(const ATexture: TSdlTexture; const ASrcRect, ADstRect: TSdlRectF; const AAngle: Double; const AFlip: TSdlFlipModes = []); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ASrcRect: TSdlRectF
: The source rectangle.
ADstRect: TSdlRectF
: The destination rectangle.
AAngle: Double
: An angle in degrees that indicates the rotation that will be applied around the center of ADstRect, rotating it in a clockwise direction.
AFlip: TSdlFlipModes = []
: (Optional) flipping actions that should be performed on the texture. Defaults to [] (none).
See Also
Remarks
This method should only be called on the main thread.
DrawTextureRotated(TSdlTexture, TSdlRectF, Double, TSdlPointF, TSdlFlipModes)
Copy the source texture to the current rendering target, with rotation and flipping, at subpixel precision.
procedure DrawTextureRotated(const ATexture: TSdlTexture; const ADstRect: TSdlRectF; const AAngle: Double; const ACenter: TSdlPointF; const AFlip: TSdlFlipModes = []); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ADstRect: TSdlRectF
: The destination rectangle.
AAngle: Double
: An angle in degrees that indicates the rotation that will be applied to ADstRect, rotating it in a clockwise direction.
ACenter: TSdlPointF
: The point around which ADstRect will be rotated.
AFlip: TSdlFlipModes = []
: (Optional) flipping actions that should be performed on the texture. Defaults to [] (none).
See Also
Remarks
This method should only be called on the main thread.
DrawTextureRotated(TSdlTexture, TSdlRectF, Double, TSdlFlipModes)
Copy the source texture to the current rendering target, with rotation and flipping, at subpixel precision.
procedure DrawTextureRotated(const ATexture: TSdlTexture; const ADstRect: TSdlRectF; const AAngle: Double; const AFlip: TSdlFlipModes = []); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ADstRect: TSdlRectF
: The destination rectangle.
AAngle: Double
: An angle in degrees that indicates the rotation that will be applied around the center of ADstRect, rotating it in a clockwise direction.
AFlip: TSdlFlipModes = []
: (Optional) flipping actions that should be performed on the texture. Defaults to [] (none).
See Also
Remarks
This method should only be called on the main thread.
DrawTextureTiled(TSdlTexture, TSdlRectF, Single, TSdlRectF)
Tile a portion of the texture to the current rendering target at subpixel precision.
The pixels in ASrcRect will be repeated as many times as needed to completely fill ADstRect.
procedure DrawTextureTiled(const ATexture: TSdlTexture; const ASrcRect: TSdlRectF; const AScale: Single; const ADstRect: TSdlRectF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
ASrcRect: TSdlRectF
: The source rectangle.
AScale: Single
: The scale used to transform srcrect into the destination rectangle, e.g. a 32x32 texture with a scale of 2 would fill 64x64 tiles.
ADstRect: TSdlRectF
: The destination rectangle.
See Also
Remarks
This method should only be called on the main thread.
DrawTextureTiled(TSdlTexture, Single, TSdlRectF)
Tile the texture to the current rendering target at subpixel precision.
The pixels in the texture will be repeated as many times as needed to completely fill ADstRect.
procedure DrawTextureTiled(const ATexture: TSdlTexture; const AScale: Single; const ADstRect: TSdlRectF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATexture: TSdlTexture
: The source texture.
AScale: Single
: The scale used to transform srcrect into the destination rectangle, e.g. a 32x32 texture with a scale of 2 would fill 64x64 tiles.
ADstRect: TSdlRectF
: The destination rectangle.
See Also
Remarks
This method should only be called on the main thread.
FillRect(TSdlRectF)
Fill a rectangle on the current rendering target with the drawing color at subpixel precision.
procedure FillRect(const ARect: TSdlRectF); inline
Exceptions
ESdlError: Raised on failure.
Parameters
ARect: TSdlRectF
: The destination rectangle.
See Also
Remarks
This method should only be called on the main thread.
FillRects(TSdlRectF[])
Fill some number of rectangles on the current rendering target with the drawing color at subpixel precision.
procedure FillRects(const ARects: array of TSdlRectF); overload
Exceptions
ESdlError: Raised on failure.
Parameters
ARects: array of TSdlRectF
: Array of destination rectangles.
See Also
Remarks
This method should only be called on the main thread.
FillRects(TArray<TSdlRectF>)
Fill some number of rectangles on the current rendering target with the drawing color at subpixel precision.
procedure FillRects(const ARects: TArray<TSdlRectF>); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ARects: TArray<TSdlRectF>
: Array of destination rectangles.
See Also
Remarks
This method should only be called on the main thread.
Flush
Force the rendering context to flush any pending commands and state.
You do not need to (and in fact, shouldn't) call this function unless you are planning to call into OpenGL/Direct3D/Metal/whatever directly, in addition to using a TSdlRenderer.
This is 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 function 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 function.
This call 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.
procedure Flush; inline
Exceptions
ESdlError: Raised on failure.
Remarks
This method should only be called on the main thread.
ForWindow(TSdlWindow)
Get the renderer associated with a window.
class function ForWindow(const AWindow: TSdlWindow): TSdlRenderer; inline; static
Exceptions
ESdlError: Raised on failure.
Parameters
AWindow: TSdlWindow
: The window to query.
Returns
TSdlRenderer: The rendering context.
Remarks
It is safe to call this method from any thread.
Free
Destroy the rendering context for a window and free all associated textures.
This should be called before destroying the associated window.
procedure Free; inline
Remarks
This method should only be called on the main thread.
GetLogicalPresentation(Integer, Integer, TSdlRendererLogicalPresentation)
Get device independent resolution and presentation mode for rendering.
This method gets the width and height of the logical rendering output, or the output size in pixels if a logical resolution is not enabled.
Each render target has its own logical presentation state. This method gets the state for the current render target.
procedure GetLogicalPresentation(out AW, AH: Integer; out AMode: TSdlRendererLogicalPresentation); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AW: Integer
: Set to the width.
AH: Integer
: Set to the height.
AMode: TSdlRendererLogicalPresentation
: Set to the presentation.
See Also
Remarks
This method should only be called on the main thread.
Present
Update the screen with any rendering performed since the previous call.
SDL's rendering functions operate on a backbuffer; that is, calling a rendering function such as DrawLine does not directly put a line on the screen, but rather updates the backbuffer. As such, you compose your entire scene and present the composed backbuffer to the screen as a complete picture.
Therefore, when using SDL's rendering API, one does all drawing intended for the frame, and then calls this function once per frame to present the final drawing to the user.
The backbuffer should be considered invalidated after each present; do not assume that previous contents will exist between frames. You are strongly encouraged to call Clear to initialize the backbuffer before starting each new frame's drawing, even if you plan to overwrite every pixel.
Please note, that in case of rendering to a texture - there is no need to call Present after drawing needed objects to a texture, and should not be done; you are only required to change back the rendering target to default via RenderTarget := nil afterwards, as textures by themselves do not have a concept of backbuffers. Calling Present while rendering to a texture will still update the screen with any current drawing that has been done to the window itself.
procedure Present; inline
Exceptions
ESdlError: Raised on failure.
See Also
- Clear
- FillRect
- FillRects
- DrawLine
- DrawLines
- DrawPoint
- DrawPoints
- DrawRect
- DrawRects
- DrawBlendMode
- SetDrawColor
- DrawColor
- DrawColorFloat
Remarks
This methodn should only be called on the main thread.
ReadPixels(TSdlRect)
Read pixels from the current rendering target.
The returned surface contains pixels inside the desired area clipped to the current viewport, and should be freed.
Note that this returns the actual pixels on the screen, so if you are using logical presentation you should use LogicalPresentationRect to get the area containing your content.
function ReadPixels(const ARect: TSdlRect): TSdlSurface; overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ARect: TSdlRect
: The area to read, which will be clipped to the current viewport.
Returns
TSdlSurface: A new SDL surface
Remarks
This method should only be called on the main thread.
ReadPixels
Read pixels from the entire viewport of the current rendering target.
The returned surface contains pixels inside the desired area clipped to the current viewport, and should be freed.
Note that this returns the actual pixels on the screen, so if you are using 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 Present.
function ReadPixels: TSdlSurface; overload; inline
Exceptions
ESdlError: Raised on failure.
Returns
TSdlSurface: A new SDL surface
Remarks
This method should only be called on the main thread.
RenderCoordinatesFromWindow(Single, Single)
Get a point in render coordinates when given a point in window coordinates.
This takes into account several states:
- The window dimensions.
- The logical presentation settings (SetLogicalPresentation)
- The scale (Scale)
- The viewport (Viewport)
function RenderCoordinatesFromWindow(const AWindowX, AWindowY: Single): TSdlPointF; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AWindowX: Single
: The X coordinate in window coordinates.
AWindowY: Single
: The Y coordinate in window coordinates.
Returns
TSdlPointF: The coordinates in render coordinates.
See Also
Remarks
This method should only be called on the main thread.
RenderCoordinatesToWindow(Single, Single)
Get a point in window coordinates when given a point in render coordinates.
This takes into account several states:
- The window dimensions.
- The logical presentation settings (SetLogicalPresentation)
- The scale (Scale)
- The viewport (Viewport)
function RenderCoordinatesToWindow(const AX, AY: Single): TSdlPointF; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AX: Single
: The X coordinate in render coordinates.
AY: Single
: The Y coordinate in render coordinates.
Returns
TSdlPointF: The coordinates in window coordinates.
See Also
Remarks
This method should only be called on the main thread.
ResetViewport
Set the viewport to the entire target.
procedure ResetViewport; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
SetDrawColor(Byte, Byte, Byte, Byte)
Set the (integer) color used for drawing operations.
Set the color for drawing or filling rectangles, lines, and points, and for Clear.
procedure SetDrawColor(const AR, AG, AB: Byte; const AA: Byte = SDL_ALPHA_OPAQUE); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AR: Byte
: The red value used to draw on the rendering target.
AG: Byte
: The green value used to draw on the rendering target.
AB: Byte
: The blue value used to draw on the rendering target.
AA: Byte = SDL_ALPHA_OPAQUE
: (Optional)Aalpha value used to draw on the rendering target; Defaults to SDL_ALPHA_OPAQUE (255). Use DrawBlendMode to specify how the alpha channel is used.
See Also
Remarks
This method should only be called on the main thread.
SetDrawColorFloat(Single, Single, Single, Single)
Set the (floating-point) color used for drawing operations.
Set the color for drawing or filling rectangles, lines, and points, and for Clear.
procedure SetDrawColorFloat(const AR, AG, AB: Single; const AA: Single = SDL_ALPHA_OPAQUE_FLOAT); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AR: Single
: The red value used to draw on the rendering target.
AG: Single
: The green value used to draw on the rendering target.
AB: Single
: The blue value used to draw on the rendering target.
AA: Single = SDL_ALPHA_OPAQUE_FLOAT
: (Optional)Aalpha value used to draw on the rendering target; Defaults to SDL_ALPHA_OPAQUE_FLOAT (1.0). Use DrawBlendMode to specify how the alpha channel is used.
See Also
Remarks
This method should only be called on the main thread.
SetLogicalPresentation(Integer, Integer, TSdlRendererLogicalPresentation)
Set a device-independent resolution and presentation mode for rendering.
This method sets the width and height of the logical rendering output. The renderer will act as if the current render target is always the requested dimensions, scaling to the actual resolution as necessary.
This can be useful for games 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 can be used with both render target textures and the renderer's window; the state is unique to each render target, and this function sets the state for the current render target. 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.
You can disable logical coordinates by setting the mode to TSdlLogicalPresentation.Disabled, and in that case you get the full pixel resolution of the render target; it is safe to toggle logical presentation during the rendering of a frame: perhaps most of the rendering is done to specific dimensions but to make fonts look sharp, the app turns off logical presentation while drawing text, for example.
For the renderer's window, letterboxing is drawn into the framebuffer if logical presentation is enabled during Present; be sure to reenable it before presenting if you were toggling it, otherwise the letterbox areas might have artifacts from previous frames (or artifacts from external overlays, etc). Letterboxing is never drawn into texture render targets; be sure to call Clear before drawing into the texture so the letterboxing areas are cleared, if appropriate.
You can convert coordinates in an event into rendering coordinates using TSdlEvent.ConvertToRenderCoordinates.
procedure SetLogicalPresentation(const AW, AH: Integer; const AMode: TSdlRendererLogicalPresentation); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AW: Integer
: The width of the logical resolution.
AH: Integer
: The height of the logical resolution.
AMode: TSdlRendererLogicalPresentation
: The presentation mode used.
See Also
Remarks
This method should only be called on the main thread.