TSdlGpuDevice

The SDL_GPU context.

Definition

Unit: Neslib.Sdl3.Gpu

type TSdlGpuDevice = record ... end;

Properties

Name	Description
Driver	The backend driver used to create this GPU context.
Formats	The supported shader formats for this GPU context.

Constructors

Name	Description
Create(TSdlProperties)	Creates a GPU context.
Create(TSdlGpuShaderFormats, TSdlGpuDriver, Boolean)	Creates a GPU context.
Create(TSdlGpuShaderFormats, Boolean)	Creates a GPU context.

Operators

Name	Description
Equal(TSdlGpuDevice, TSdlGpuDevice)	Used to compare against another TSdlGpuDevice.
Equal(TSdlGpuDevice, Pointer)	Used to compare against nil.
Implicit	Used to set the value to nil.
NotEqual(TSdlGpuDevice, TSdlGpuDevice)	Used to compare against another TSdlGpuDevice.
NotEqual(TSdlGpuDevice, Pointer)	Used to compare against nil.

Methods

Name	Description
AcquireCommandBuffer	Acquire a command buffer.
ClaimWindow	Claims a window, creating a swapchain structure for it.
CreateBuffer	Creates a buffer object to be used in graphics or compute workflows.
CreateComputePipeline	Creates a pipeline object to be used in a compute workflow.
CreateGraphicsPipeline	Creates a pipeline object to be used in a graphics workflow.
CreateSampler	Creates a sampler object to be used when binding textures in a graphics workflow.
CreateShader	Creates a shader to be used when creating a graphics pipeline.
CreateTexture	Creates a texture object to be used in graphics or compute workflows.
CreateTransferBuffer	Creates a transfer buffer to be used when uploading to or downloading from graphics resources.
Free	Destroys the GPU context.
GetSwapchainTextureFormat	Obtains the texture format of the swapchain for the given window.
MapTransferBuffer	Maps a transfer buffer into application address space.
QueryFence	Checks the status of a fence.
ReleaseBuffer	Frees the given buffer as soon as it is safe to do so.
ReleaseComputePipeline	Frees the given compute pipeline as soon as it is safe to do so.
ReleaseFence	Releases a fence obtained from TSdlGpuCommandBuffer.SubmitAndAcquireFence.
ReleaseGraphicsPipeline	Frees the given graphics pipeline as soon as it is safe to do so.
ReleaseSampler	Frees the given sampler as soon as it is safe to do so.
ReleaseShader	Frees the given shader as soon as it is safe to do so.
ReleaseTexture	Frees the given texture as soon as it is safe to do so.
ReleaseTransferBuffer	Frees the given transfer buffer as soon as it is safe to do so.
ReleaseWindow	Unclaims a window, destroying its swapchain structure.
SetAllowedFramesInFlight	Configures the maximum allowed number of frames in flight.
SetBufferName	Sets an arbitrary string constant to label a buffer.
SetSwapchainParameters	Changes the swapchain parameters for the given claimed window.
SetTextureName	Sets an arbitrary string constant to label a texture.
TextureSupportsFormat	Determines whether a texture format is supported for a given type and usage.
TextureSupportsSampleCount	Determines if a sample count for a texture format is supported.
UnmapTransferBuffer	Unmaps a previously mapped transfer buffer.
WaitForFences	Blocks the thread until the given fences are signaled.
WaitForIdle	Blocks the thread until the GPU is completely idle.
WaitForSwapchain	Blocks the thread until a swapchain texture is available to be acquired.
WindowSupportsPresentMode	Determines whether a presentation mode is supported by the window.
WindowSupportsSwapchainComposition	Determines whether a swapchain composition is supported by the window.

Property Descriptions

Driver

The backend driver used to create this GPU context.

property Driver: TSdlGpuDriver read GetDriver

Type: TSdlGpuDriver

Exceptions

ESdlError: Raised on failure.

---

Formats

The supported shader formats for this GPU context.

property Formats: TSdlGpuShaderFormats read GetFormats

Type: TSdlGpuShaderFormats

---

Constructor Descriptions

Create

Creates a GPU context.

These are the supported properties:

• TSdlProperty.GpuDeviceCreateDebugMode: enable debug mode properties and validations, defaults to True.
• TSdlProperty.GpuDeviceCreatePreferLowPower: enable to prefer energy efficiency over maximum GPU performance, defaults to False.
• TSdlProperty.GpuDeviceCreateName: the name of the GPU driver to use, if a specific one is desired.

These are the current shader format properties:

• TSdlProperty.GpuDeviceCreateShadersPrivate: The app is able to provide shaders for an NDA platform.
• TSdlProperty.GpuDeviceCreateShadersSpirV: The app is able to provide SPIR-V shaders if applicable.
• TSdlProperty.GpuDeviceCreateShadersDxbc: The app is able to provide DXBC shaders if applicable
• TSdlProperty.GpuDeviceCreateShadersDxil: The app is able to provide DXIL shaders if applicable.
• TSdlProperty.GpuDeviceCreateShadersMsl: The app is able to provide MSL shaders if applicable.
• TSdlProperty.GpuDeviceCreateShadersMetalLib: The app is able to provide Metal shader libraries if applicable.

With the D3D12 renderer:

• TSdlProperty.GpuDeviceCreateD3D12SemanticName: the prefix to use for all vertex semantics, default is 'TEXCOORD'.

constructor Create(const AProps: TSdlProperties); overload

Parameters

AProps: TSdlProperties : The properties to use.

Exceptions

ESdlError: Raised on failure.

See Also

• Formats
• Driver
• TSdlGpuDriver.SupportsProperties

---

Create

Creates a GPU context.

constructor Create(const AFormats: TSdlGpuShaderFormats; const ADriver: TSdlGpuDriver; const ADebugMode: Boolean = False{$ENDIF}); overload

Parameters

AFormats: TSdlGpuShaderFormats : Which shader formats the app is able to provide.

ADriver: TSdlGpuDriver : The preferred GPU driver to use.

ADebugMode: Boolean = False{$ENDIF} : (Optional) True to enable debug mode properties and validations. If not given, this will be True in when the app is compiled in DEBUG mode, or False otherwise

Exceptions

ESdlError: Raised on failure.

See Also

• Formats
• Driver
• TSdlGpuDriver.SupportsFormats

---

Create

Creates a GPU context.

constructor Create(const AFormats: TSdlGpuShaderFormats; const ADebugMode: Boolean = False{$ENDIF}); overload

Parameters

AFormats: TSdlGpuShaderFormats : Which shader formats the app is able to provide.

ADebugMode: Boolean = False{$ENDIF} : (Optional) True to enable debug mode properties and validations. If not given, this will be True in when the app is compiled in DEBUG mode, or False otherwise

Exceptions

ESdlError: Raised on failure.

See Also

• Formats
• Driver
• TSdlGpuDriver.SupportsFormats

---

Operator Descriptions

Equal(TSdlGpuDevice, TSdlGpuDevice)

Used to compare against another TSdlGpuDevice.

class operator Equal(const ALeft, ARight: TSdlGpuDevice): Boolean; inline; static

Parameters

ALeft: TSdlGpuDevice

ARight: TSdlGpuDevice

Returns

Boolean

---

Equal(TSdlGpuDevice, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TSdlGpuDevice; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlGpuDevice

ARight: Pointer

Returns

Boolean

---

Implicit(Pointer)

Used to set the value to nil.

class operator Implicit(const AValue: Pointer): TSdlGpuDevice; inline; static

Parameters

AValue: Pointer

Returns

TSdlGpuDevice

---

NotEqual(TSdlGpuDevice, TSdlGpuDevice)

Used to compare against another TSdlGpuDevice.

class operator NotEqual(const ALeft, ARight: TSdlGpuDevice): Boolean; inline; static

Parameters

ALeft: TSdlGpuDevice

ARight: TSdlGpuDevice

Returns

Boolean

---

NotEqual(TSdlGpuDevice, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TSdlGpuDevice; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlGpuDevice

ARight: Pointer

Returns

Boolean

---

Method Descriptions

AcquireCommandBuffer

Acquire a command buffer.

This command buffer is managed by the implementation and should not be freed by the user. The command buffer may only be used on the thread it was acquired on. The command buffer should be submitted on the thread it was acquired on.

It is valid to acquire multiple command buffers on the same thread at once. In fact a common design pattern is to acquire two command buffers per frame where one is dedicated to render and compute passes and the other is dedicated to copy passes and other preparatory work such as generating mipmaps. Interleaving commands between the two command buffers reduces the total amount of passes overall which improves rendering performance.

function AcquireCommandBuffer: TSdlGpuCommandBuffer; inline

Exceptions

ESdlError: Raised on failure.

Returns

TSdlGpuCommandBuffer: A command buffer.

See Also

• TSdlGpuCommandBuffer.Submit
• TSdlGpuCommandBuffer.SubmitAndAcquireFence

---

ClaimWindow(TSdlWindow)

Claims a window, creating a swapchain structure for it.

This must be called before TSdlGpuCommandBuffer.AcquireSwapchainTexture is called using the window. You should only call this method from the thread that created the window.

The swapchain will be created with TSdlGpuSwapchainComposition.Sdr and TSdlGpuPresentMode.VSync. If you want to have different swapchain parameters, you must call SetSwapchainParameters after claiming the window.

procedure ClaimWindow(const AWindow: TSdlWindow); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AWindow: TSdlWindow : A TSdlWindow.

See Also

• TSdlGpuCommandBuffer.WaitAndAcquireSwapchainTexture
• ReleaseWindow
• WindowSupportsPresentMode
• WindowSupportsSwapchainComposition

Remarks

This method should only be called from the thread that created the window.

---

CreateBuffer(TSdlGpuBufferCreateInfo)

Creates a buffer object to be used in graphics or compute workflows.

The contents of this buffer are undefined until data is written to the buffer.

Note that certain combinations of usage flags are invalid. For example, a buffer cannot have both the Vertex and Index flags.

If you use a Storage flag, the data in the buffer must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.

For better understanding of underlying concepts and memory management with SDL GPU API, you may refer this blog post.

There are optional properties that can be provided through Props. These are the supported properties:

• TSdlProperty.GpuBufferCreateName: a name that can be displayed in debugging tools.

function CreateBuffer(const ACreateInfo: TSdlGpuBufferCreateInfo): TSdlGpuBuffer; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ACreateInfo: TSdlGpuBufferCreateInfo : A record describing the state of the buffer to create.

Returns

TSdlGpuBuffer: A buffer object.

See Also

• TSdlGpuCopyPass.UploadToBuffer
• TSdlGpuCopyPass.DownloadFromBuffer
• TSdlGpuCopyPass.CopyBufferToBuffer
• TSdlGpuRenderPass.BindVertexBuffers
• TSdlGpuRenderPass.BindIndexBuffer
• TSdlGpuRenderPass.BindVertexStorageBuffers
• TSdlGpuRenderPass.BindFragmentStorageBuffers
• TSdlGpuRenderPass.DrawPrimitives
• TSdlGpuComputePass.BindStorageBuffers
• TSdlGpuComputePass.Dispatch
• ReleaseBuffer

---

CreateComputePipeline(TSdlGpuComputePipelineCreateInfo)

Creates a pipeline object to be used in a compute workflow.

Shader resource bindings must be authored to follow a particular order depending on the shader format.

For SPIR-V shaders, use the following resource sets:

• 0: Sampled textures, followed by read-only storage textures, followed by read-only storage buffers
• 1: Read-write storage textures, followed by read-write storage buffers
• 2: Uniform buffers

For DXBC and DXIL shaders, use the following register order:

• (t[n], space0): Sampled textures, followed by read-only storage textures, followed by read-only storage buffers
• (u[n], space1): Read-write storage textures, followed by read-write storage buffers
• (b[n], space2): Uniform buffers

For MSL/metallib, use the following order:

• [[buffer]]: Uniform buffers, followed by read-only storage buffers, followed by read-write storage buffers
• [[texture]]: Sampled textures, followed by read-only storage textures, followed by read-write storage textures

There are optional properties that can be provided through Props. These are the supported properties:

• TSdlProperty.GpuComputePipelineCreateName: a name that can be displayed in debugging tools.

function CreateComputePipeline(const ACreateInfo: TSdlGpuComputePipelineCreateInfo): TSdlGpuComputePipeline; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ACreateInfo: TSdlGpuComputePipelineCreateInfo : A record describing the state of the compute pipeline to create.

Returns

TSdlGpuComputePipeline: A compute pipeline object.

See Also

• TSdlGpuComputePass.BindStorageBuffers
• ReleaseComputePipeline

---

CreateGraphicsPipeline(TSdlGpuGraphicsPipelineCreateInfo)

Creates a pipeline object to be used in a graphics workflow.

There are optional properties that can be provided through Props. These are the supported properties:

• TSdlProperty.GpuGraphicsPipelineCreateName: a name that can be displayed in debugging tools.

function CreateGraphicsPipeline(const ACreateInfo: TSdlGpuGraphicsPipelineCreateInfo): TSdlGpuGraphicsPipeline; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ACreateInfo: TSdlGpuGraphicsPipelineCreateInfo : A record describing the state of the graphics pipeline to create.

Returns

TSdlGpuGraphicsPipeline: A graphics pipeline object.

See Also

• TSdlGpuShader
• TSdlGpuRenderPass.BindPipeline
• ReleaseGraphicsPipeline

---

CreateSampler(TSdlGpuSamplerCreateInfo)

Creates a sampler object to be used when binding textures in a graphics workflow.

There are optional properties that can be provided through Props. These are the supported properties:

• TSdlProperty.GpuSamplerCreateName: a name that can be displayed in debugging tools.

function CreateSampler(const ACreateInfo: TSdlGpuSamplerCreateInfo): TSdlGpuSampler; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ACreateInfo: TSdlGpuSamplerCreateInfo : A record describing the state of the sampler to create.

Returns

TSdlGpuSampler: A sampler object.

See Also

• TSdlGpuRenderPass.BindVertexSamplers
• TSdlGpuRenderPass.BindFragmentSamplers
• ReleaseSampler

---

CreateShader(TSdlGpuShaderCreateInfo)

Creates a shader to be used when creating a graphics pipeline.

Shader resource bindings must be authored to follow a particular order depending on the shader format.

For SPIR-V shaders, use the following resource sets:

For vertex shaders:

• 0: Sampled textures, followed by storage textures, followed by storage buffers
• 1: Uniform buffers

For fragment shaders:

• 2: Sampled textures, followed by storage textures, followed by storage buffers
• 3: Uniform buffers

For DXBC and DXIL shaders, use the following register order:

For vertex shaders:

• (t[n], space0): Sampled textures, followed by storage textures, followed by storage buffers
• (s[n], space0): Samplers with indices corresponding to the sampled textures
• (b[n], space1): Uniform buffers

For pixel shaders:

• (t[n], space2): Sampled textures, followed by storage textures, followed by storage buffers
• (s[n], space2): Samplers with indices corresponding to the sampled textures
• (b[n], space3): Uniform buffers

For MSL/metallib, use the following order:

• [[texture]]: Sampled textures, followed by storage textures
• [[sampler]]: Samplers with indices corresponding to the sampled textures
• [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. Rather than manually authoring vertex buffer indices, use the [[stage_in]] attribute which will automatically use the vertex input information from the SDL_GPUGraphicsPipeline.

Shader semantics other than system-value semantics do not matter in D3D12 and for ease of use the SDL implementation assumes that non system-value semantics will all be TEXCOORD. If you are using HLSL as the shader source language, your vertex semantics should start at TEXCOORD0 and increment like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic prefix to something other than TEXCOORD you can use TSdlProperty.GpuDeviceCreateD3D12SemanticName with TSdlGpuDevice.Create.

There are optional properties that can be provided through Props. These are the supported properties:

• TSdlProperty.GpuShaderCreateName: a name that can be displayed in debugging tools.

function CreateShader(const ACreateInfo: TSdlGpuShaderCreateInfo): TSdlGpuShader; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ACreateInfo: TSdlGpuShaderCreateInfo : A record describing the state of the shader to create.

Returns

TSdlGpuShader: A shader object.

See Also

• TSdlGpuGraphicsPipeline
• ReleaseShader

---

CreateTexture(TSdlGpuTextureCreateInfo)

Creates a texture object to be used in graphics or compute workflows.

The contents of this texture are undefined until data is written to the texture.

Note that certain combinations of usage flags are invalid. For example, a texture cannot have both the Sampler and GraphicsStorageRead flags.

If you request a sample count higher than the hardware supports, the implementation will automatically fall back to the highest available sample count.

There are optional properties that can be provided through TSdlGpuTextureCreateInfo's Props. These are the supported properties:

• TSdlProperty.GpuTextureCreateD3D12ClearR: (Direct3D 12 only) if the texture usage is TSdlGpuTextureUsage.ColorTarget, clear the texture to a color with this red intensity. Defaults to zero.
• TSdlProperty.GpuTextureCreateD3D12ClearG: (Direct3D 12 only) if the texture usage is TSdlGpuTextureUsage.ColorTarget, clear the texture to a color with this green intensity. Defaults to zero.
• TSdlProperty.GpuTextureCreateD3D12ClearB: (Direct3D 12 only) if the texture usage is TSdlGpuTextureUsage.ColorTarget, clear the texture to a color with this blue intensity. Defaults to zero.
• TSdlProperty.GpuTextureCreateD3D12ClearA: (Direct3D 12 only) if the texture usage is TSdlGpuTextureUsage.ColorTarget, clear the texture to a color with this alpha intensity. Defaults to zero.
• TSdlProperty.GpuTextureCreateD3D12ClearDepth: (Direct3D 12 only) if the texture usage is TSdlGpuTextureUsage.DepthStencilTarget, clear the texture to a depth of this value. Defaults to zero.
• TSdlProperty.GpuTextureCreateD3D12ClearStencil: (Direct3D 12 only) if the texture usage is TSdlGpuTextureUsage.DepthStencilTarget, clear the texture to a stencil of this value. Defaults to zero.
• TSdlProperty.GpuTextureCreateName: a name that can be displayed in debugging tools.

function CreateTexture(const ACreateInfo: TSdlGpuTextureCreateInfo): TSdlGpuTexture; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ACreateInfo: TSdlGpuTextureCreateInfo : A record describing the state of the texture to create.

Returns

TSdlGpuTexture

See Also

• TSdlGpuCopyPass.UploadToTexture
• TSdlGpuCopyPass.DownloadFromTexture
• TSdlGpuRenderPass.BindVertexSamplers
• TSdlGpuRenderPass.BindVertexStorageTextures
• TSdlGpuRenderPass.BindFragmentSamplers
• TSdlGpuRenderPass.BindFragmentStorageTextures
• TSdlGpuComputePass.BindStorageTextures
• TSdlGpuCommandBuffer.Blit
• ReleaseTexture
• TextureSupportsFormat

---

CreateTransferBuffer(TSdlGpuTransferBufferCreateInfo)

Creates a transfer buffer to be used when uploading to or downloading from graphics resources.

Download buffers can be particularly expensive to create, so it is good practice to reuse them if data will be downloaded regularly.

There are optional properties that can be provided through Props. These are the supported properties:

• TSdlProperty.GpuTransferBufferCreateName: a name that can be displayed in debugging tools.

function CreateTransferBuffer(const ACreateInfo: TSdlGpuTransferBufferCreateInfo): TSdlGpuTransferBuffer; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ACreateInfo: TSdlGpuTransferBufferCreateInfo : A record describing the state of the transfer buffer to create.

Returns

TSdlGpuTransferBuffer: A transfer buffer.

See Also

• TSdlGpuCopyPass.UploadToBuffer
• TSdlGpuCopyPass.DownloadFromBuffer
• TSdlGpuCopyPass.UploadToTexture
• TSdlGpuCopyPass.DownloadFromTexture
• ReleaseTransferBuffer

---

Free

Destroys the GPU context.

procedure Free; inline

---

GetSwapchainTextureFormat(TSdlWindow)

Obtains the texture format of the swapchain for the given window.

Note that this format can change if the swapchain parameters change.

function GetSwapchainTextureFormat(const AWindow: TSdlWindow): TSdlGpuTextureFormat; inline

Parameters

AWindow: TSdlWindow : A TSdlWindow that has been claimed.

Returns

TSdlGpuTextureFormat: The texture format of the swapchain.

---

MapTransferBuffer(TSdlGpuTransferBuffer, Boolean)

Maps a transfer buffer into application address space.

You must unmap the transfer buffer before encoding upload commands. The memory is owned by the graphics driver - do NOT call SdlFree on the returned pointer.

function MapTransferBuffer(const ATransferBuffer: TSdlGpuTransferBuffer; const ACycle: Boolean): Pointer; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ATransferBuffer: TSdlGpuTransferBuffer : A transfer buffer.

ACycle: Boolean : If True, cycles the transfer buffer if it is already bound.

Returns

Pointer: The address of the mapped transfer buffer memory.

---

QueryFence(TSdlGpuFence)

Checks the status of a fence.

function QueryFence(const AFence: TSdlGpuFence): Boolean; inline

Parameters

AFence: TSdlGpuFence : A fence.

Returns

Boolean: True if the fence is signaled, False if it is not.

See Also

• TSdlGpuCommandBuffer.SubmitAndAcquireFence

---

ReleaseBuffer(TSdlGpuBuffer)

Frees the given buffer as soon as it is safe to do so.

You must not reference the buffer after calling this method.

procedure ReleaseBuffer(const ABuffer: TSdlGpuBuffer); inline

Parameters

ABuffer: TSdlGpuBuffer : A buffer to be destroyed.

---

ReleaseComputePipeline(TSdlGpuComputePipeline)

Frees the given compute pipeline as soon as it is safe to do so.

You must not reference the compute pipeline after calling this method.

procedure ReleaseComputePipeline(const AComputePipeline: TSdlGpuComputePipeline); inline

Parameters

AComputePipeline: TSdlGpuComputePipeline : A compute pipeline to be destroyed.

---

ReleaseFence(TSdlGpuFence)

Releases a fence obtained from TSdlGpuCommandBuffer.SubmitAndAcquireFence.

You must not reference the fence after calling this method.

procedure ReleaseFence(const AFence: TSdlGpuFence); inline

Parameters

AFence: TSdlGpuFence : A fence.

See Also

• TSdlGpuCommandBuffer.SubmitAndAcquireFence

---

ReleaseGraphicsPipeline(TSdlGpuGraphicsPipeline)

Frees the given graphics pipeline as soon as it is safe to do so.

You must not reference the graphics pipeline after calling this method.

procedure ReleaseGraphicsPipeline(const AGraphicsPipeline: TSdlGpuGraphicsPipeline); inline

Parameters

AGraphicsPipeline: TSdlGpuGraphicsPipeline : a graphics pipeline to be destroyed.

---

ReleaseSampler(TSdlGpuSampler)

Frees the given sampler as soon as it is safe to do so.

You must not reference the sampler after calling this method.

procedure ReleaseSampler(const ASampler: TSdlGpuSampler); inline

Parameters

ASampler: TSdlGpuSampler : A sampler to be destroyed.

---

ReleaseShader(TSdlGpuShader)

Frees the given shader as soon as it is safe to do so.

You must not reference the shader after calling this method.

procedure ReleaseShader(const AShader: TSdlGpuShader); inline

Parameters

AShader: TSdlGpuShader : A shader to be destroyed.

---

ReleaseTexture(TSdlGpuTexture)

Frees the given texture as soon as it is safe to do so.

You must not reference the texture after calling this method.

procedure ReleaseTexture(const ATexture: TSdlGpuTexture); inline

Parameters

ATexture: TSdlGpuTexture : A texture to be destroyed.

---

ReleaseTransferBuffer(TSdlGpuTransferBuffer)

Frees the given transfer buffer as soon as it is safe to do so.

You must not reference the transfer buffer after calling this methpd.

procedure ReleaseTransferBuffer(const ATransferBuffer: TSdlGpuTransferBuffer); inline

Parameters

ATransferBuffer: TSdlGpuTransferBuffer : a transfer buffer to be destroyed.

---

ReleaseWindow(TSdlWindow)

Unclaims a window, destroying its swapchain structure.

procedure ReleaseWindow(const AWindow: TSdlWindow); inline

Parameters

AWindow: TSdlWindow : A TSdlWindow that has been claimed.

See Also

• ClaimWindow

---

SetAllowedFramesInFlight(Integer)

Configures the maximum allowed number of frames in flight.

The default value when the device is created is 2. This means that after you have submitted 2 frames for presentation, if the GPU has not finished working on the first frame, TSdlGpuCommandBuffer.AcquireSwapchainTexture will fill the swapchain texture pointer with nil, and TSdlGpuCommandBuffer.WaitAndAcquireSwapchainTexture will block.

Higher values increase throughput at the expense of visual latency. Lower values decrease visual latency at the expense of throughput.

Note that calling this function will stall and flush the command queue to prevent synchronization issues.

The minimum value of allowed frames in flight is 1, and the maximum is 3.

procedure SetAllowedFramesInFlight(const AAllowedFramesInFlight: Integer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AAllowedFramesInFlight: Integer : The maximum number of frames that can be pending on the GPU.

---

SetBufferName(TSdlGpuBuffer, String)

Sets an arbitrary string constant to label a buffer.

You should use TSdlProperty.GpuBufferCreateName with CreateBuffer instead of this method to avoid thread safety issues.

procedure SetBufferName(const ABuffer: TSdlGpuBuffer; const AName: String); inline

Parameters

ABuffer: TSdlGpuBuffer : A buffer to attach the name to.

AName: String : A string constant to mark as the name of the buffer.

See Also

• CreateBuffer

Remarks

This method is not thread safe, you must make sure the buffer is not simultaneously used by any other thread.

---

SetSwapchainParameters(TSdlWindow, TSdlGpuSwapchainComposition, TSdlGpuPresentMode)

Changes the swapchain parameters for the given claimed window.

This method will fail if the requested present mode or swapchain composition are unsupported by the device. Check if the parameters are supported via WindowSupportsPresentMode / WindowSupportsSwapchainComposition prior to calling this method.

TSdlGpuPresentMode.VSync and TSdlGpuSwapchainComposition.Sdr are always supported.

procedure SetSwapchainParameters(const AWindow: TSdlWindow; const ASwapchainComposition: TSdlGpuSwapchainComposition; const APresentMode: TSdlGpuPresentMode); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AWindow: TSdlWindow : A TSdlWindow that has been claimed.

ASwapchainComposition: TSdlGpuSwapchainComposition : The desired composition of the swapchain.

APresentMode: TSdlGpuPresentMode : The desired present mode for the swapchain.

See Also

• WindowSupportsPresentMode
• WindowSupportsSwapchainComposition

---

SetTextureName(TSdlGpuTexture, String)

Sets an arbitrary string constant to label a texture.

You should use TSdlProperty.GpuTextureCreateName with CreateTexture instead of this method to avoid thread safety issues.

procedure SetTextureName(const ATexture: TSdlGpuTexture; const AName: String); inline

Parameters

ATexture: TSdlGpuTexture : A texture to attach the name to.

AName: String : A string constant to mark as the name of the texture.

See Also

• CreateTexture

Remarks

This method is not thread safe, you must make sure the texture is not simultaneously used by any other thread.

---

TextureSupportsFormat(TSdlGpuTextureFormat, TSdlGpuTextureKind, TSdlGpuTextureUsageFlags)

Determines whether a texture format is supported for a given type and usage.

function TextureSupportsFormat(const AFormat: TSdlGpuTextureFormat; const AKind: TSdlGpuTextureKind; const AUsages: TSdlGpuTextureUsageFlags): Boolean; inline

Parameters

AFormat: TSdlGpuTextureFormat : The texture format to check.

AKind: TSdlGpuTextureKind : The type of texture (2D, 3D, Cube).

AUsages: TSdlGpuTextureUsageFlags : The usage scenarios to check.

Returns

Boolean: Whether the texture format is supported for this type and usage.

---

TextureSupportsSampleCount(TSdlGpuTextureFormat, TSdlGpuSampleCount)

Determines if a sample count for a texture format is supported.

function TextureSupportsSampleCount(const AFormat: TSdlGpuTextureFormat; const ASampleCount: TSdlGpuSampleCount): Boolean; inline

Parameters

AFormat: TSdlGpuTextureFormat : The texture format to check.

ASampleCount: TSdlGpuSampleCount : The sample count to check.

Returns

Boolean: A hardware-specific version of min(preferred, possible).

---

UnmapTransferBuffer(TSdlGpuTransferBuffer)

Unmaps a previously mapped transfer buffer.

procedure UnmapTransferBuffer(const ATransferBuffer: TSdlGpuTransferBuffer); inline

Parameters

ATransferBuffer: TSdlGpuTransferBuffer : A previously mapped transfer buffer.

---

WaitForFences(Boolean, TArray<TSdlGpuFence>)

Blocks the thread until the given fences are signaled.

procedure WaitForFences(const AWaitAll: Boolean; const AFences: TArray<TSdlGpuFence>); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AWaitAll: Boolean : If False, wait for any fence to be signaled, if True, wait for all fences to be signaled.

AFences: TArray<TSdlGpuFence> : An array of fences to wait on.

See Also

• TSdlGpuCommandBuffer.SubmitAndAcquireFence
• WaitForIdle

---

WaitForIdle

Blocks the thread until the GPU is completely idle.

procedure WaitForIdle; inline

Exceptions

ESdlError: Raised on failure.

See Also

• WaitForFences

---

WaitForSwapchain(TSdlWindow)

Blocks the thread until a swapchain texture is available to be acquired.

procedure WaitForSwapchain(const AWindow: TSdlWindow); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AWindow: TSdlWindow : A window that has been claimed.

See Also

• TSdlGpuCommandBuffer.AcquireSwapchainTexture
• TSdlGpuCommandBuffer.WaitAndAcquireSwapchainTexture
• SetAllowedFramesInFlight

Remarks

This method should only be called from the thread that created the window.

---

WindowSupportsPresentMode(TSdlWindow, TSdlGpuPresentMode)

Determines whether a presentation mode is supported by the window.

The window must be claimed before calling this function.

function WindowSupportsPresentMode(const AWindow: TSdlWindow; const APresentMode: TSdlGpuPresentMode): Boolean; inline

Parameters

AWindow: TSdlWindow : A TSdlWindow.

APresentMode: TSdlGpuPresentMode : The presentation mode to check.

Returns

Boolean: True if supported, False if unsupported.

See Also

• ClaimWindow

---

WindowSupportsSwapchainComposition(TSdlWindow, TSdlGpuSwapchainComposition)

Determines whether a swapchain composition is supported by the window.

The window must be claimed before calling this method.

function WindowSupportsSwapchainComposition(const AWindow: TSdlWindow; const ASwapchainComposition: TSdlGpuSwapchainComposition): Boolean; inline

Parameters

AWindow: TSdlWindow : A TSdlWindow.

ASwapchainComposition: TSdlGpuSwapchainComposition : The swapchain composition to check.

Returns

Boolean: True if supported, False if unsupported.

See Also

• ClaimWindow

---