The GPU API offers a cross-platform way for apps to talk to modern graphics hardware. More...
Classes | |
| struct | SDL::GPUDeviceParam |
| Safely wrap GPUDevice for non owning parameters. More... | |
| class | SDL::GPUBuffer |
| An opaque handle representing a buffer. More... | |
| class | SDL::GPUTransferBuffer |
| An opaque handle representing a transfer buffer. More... | |
| class | SDL::GPUTexture |
| An opaque handle representing a texture. More... | |
| class | SDL::GPUSampler |
| An opaque handle representing a sampler. More... | |
| class | SDL::GPUShader |
| An opaque handle representing a compiled shader object. More... | |
| class | SDL::GPUComputePipeline |
| An opaque handle representing a compute pipeline. More... | |
| class | SDL::GPUGraphicsPipeline |
| An opaque handle representing a graphics pipeline. More... | |
| class | SDL::GPURenderPass |
| An opaque handle representing a render pass. More... | |
| class | SDL::GPUComputePass |
| An opaque handle representing a compute pass. More... | |
| class | SDL::GPUCopyPass |
| An opaque handle representing a copy pass. More... | |
| class | SDL::GPUCommandBuffer |
| An opaque handle representing a command buffer. More... | |
| class | SDL::GPUDevice |
| An opaque handle representing the SDL_GPU context. More... | |
| struct | SDL::GPUDeviceRef |
| Semi-safe reference for GPUDevice. More... | |
Typedefs | |
| using | SDL::GPUDeviceRaw = SDL_GPUDevice * |
| Alias to raw representation for GPUDevice. | |
| using | SDL::GPUBufferRaw = SDL_GPUBuffer * |
| Alias to raw representation for GPUBuffer. | |
| using | SDL::GPUTransferBufferRaw = SDL_GPUTransferBuffer * |
| Alias to raw representation for GPUTransferBuffer. | |
| using | SDL::GPUTextureRaw = SDL_GPUTexture * |
| Alias to raw representation for GPUTexture. | |
| using | SDL::GPUSamplerRaw = SDL_GPUSampler * |
| Alias to raw representation for GPUSampler. | |
| using | SDL::GPUShaderRaw = SDL_GPUShader * |
| Alias to raw representation for GPUShader. | |
| using | SDL::GPUComputePipelineRaw = SDL_GPUComputePipeline * |
| Alias to raw representation for GPUComputePipeline. | |
| using | SDL::GPUGraphicsPipelineRaw = SDL_GPUGraphicsPipeline * |
| Alias to raw representation for GPUGraphicsPipeline. | |
| using | SDL::GPUCommandBufferRaw = SDL_GPUCommandBuffer * |
| Alias to raw representation for GPUCommandBuffer. | |
| using | SDL::GPURenderPassRaw = SDL_GPURenderPass * |
| Alias to raw representation for GPURenderPass. | |
| using | SDL::GPUComputePassRaw = SDL_GPUComputePass * |
| Alias to raw representation for GPUComputePass. | |
| using | SDL::GPUCopyPassRaw = SDL_GPUCopyPass * |
| Alias to raw representation for GPUCopyPass. | |
| using | SDL::GPUBufferCreateInfo = SDL_GPUBufferCreateInfo |
| A structure specifying the parameters of a buffer. More... | |
| using | SDL::GPUTransferBufferCreateInfo = SDL_GPUTransferBufferCreateInfo |
| A structure specifying the parameters of a transfer buffer. More... | |
| using | SDL::GPUTextureCreateInfo = SDL_GPUTextureCreateInfo |
| A structure specifying the parameters of a texture. More... | |
| using | SDL::GPUSamplerCreateInfo = SDL_GPUSamplerCreateInfo |
| A structure specifying the parameters of a sampler. More... | |
| using | SDL::GPUShaderCreateInfo = SDL_GPUShaderCreateInfo |
| A structure specifying code and metadata for creating a shader object. More... | |
| using | SDL::GPUComputePipelineCreateInfo = SDL_GPUComputePipelineCreateInfo |
| A structure specifying the parameters of a compute pipeline state. More... | |
| using | SDL::GPUGraphicsPipelineCreateInfo = SDL_GPUGraphicsPipelineCreateInfo |
| A structure specifying the parameters of a graphics pipeline state. More... | |
| using | SDL::GPUViewport = SDL_GPUViewport |
| A structure specifying a viewport. More... | |
| using | SDL::GPUBufferBinding = SDL_GPUBufferBinding |
| A structure specifying parameters in a buffer binding call. More... | |
| using | SDL::GPUIndexElementSize = SDL_GPUIndexElementSize |
| Specifies the size of elements in an index buffer. More... | |
| using | SDL::GPUTextureSamplerBinding = SDL_GPUTextureSamplerBinding |
| A structure specifying parameters in a sampler binding call. More... | |
| using | SDL::GPUBufferRegion = SDL_GPUBufferRegion |
| A structure specifying a region of a buffer. More... | |
| using | SDL::GPUTextureLocation = SDL_GPUTextureLocation |
| A structure specifying a location in a texture. More... | |
| using | SDL::GPUBufferLocation = SDL_GPUBufferLocation |
| A structure specifying a location in a buffer. More... | |
| using | SDL::GPUTextureRegion = SDL_GPUTextureRegion |
| A structure specifying a region of a texture. More... | |
| using | SDL::GPUTextureTransferInfo = SDL_GPUTextureTransferInfo |
| A structure specifying parameters related to transferring data to or from a texture. More... | |
| using | SDL::GPUTransferBufferLocation = SDL_GPUTransferBufferLocation |
| A structure specifying a location in a transfer buffer. More... | |
| using | SDL::GPUColorTargetInfo = SDL_GPUColorTargetInfo |
| A structure specifying the parameters of a color target used by a render pass. More... | |
| using | SDL::GPUDepthStencilTargetInfo = SDL_GPUDepthStencilTargetInfo |
| A structure specifying the parameters of a depth-stencil target used by a render pass. More... | |
| using | SDL::GPUStorageTextureReadWriteBinding = SDL_GPUStorageTextureReadWriteBinding |
| A structure specifying parameters related to binding textures in a compute pass. More... | |
| using | SDL::GPUStorageBufferReadWriteBinding = SDL_GPUStorageBufferReadWriteBinding |
| A structure specifying parameters related to binding buffers in a compute pass. More... | |
| using | SDL::GPUBlitInfo = SDL_GPUBlitInfo |
| A structure containing parameters for a blit command. More... | |
| using | SDL::GPUFence = SDL_GPUFence |
| An opaque handle representing a fence. More... | |
| using | SDL::GPUShaderFormat = Uint32 |
| Specifies the format of shader code. More... | |
| using | SDL::GPUSwapchainComposition = SDL_GPUSwapchainComposition |
| Specifies the texture format and colorspace of the swapchain textures. More... | |
| using | SDL::GPUPresentMode = SDL_GPUPresentMode |
| Specifies the timing that will be used to present swapchain textures to the OS. More... | |
| using | SDL::GPUTextureFormat = SDL_GPUTextureFormat |
| Specifies the pixel format of a texture. More... | |
| using | SDL::GPUTextureType = SDL_GPUTextureType |
| Specifies the type of a texture. More... | |
| using | SDL::GPUTextureUsageFlags = Uint32 |
| Specifies how a texture is intended to be used by the client. More... | |
| using | SDL::GPUSampleCount = SDL_GPUSampleCount |
| Specifies the sample count of a texture. More... | |
| using | SDL::GPUPrimitiveType = SDL_GPUPrimitiveType |
| Specifies the primitive topology of a graphics pipeline. More... | |
| using | SDL::GPULoadOp = SDL_GPULoadOp |
| Specifies how the contents of a texture attached to a render pass are treated at the beginning of the render pass. More... | |
| using | SDL::GPUStoreOp = SDL_GPUStoreOp |
| Specifies how the contents of a texture attached to a render pass are treated at the end of the render pass. More... | |
| using | SDL::GPUCubeMapFace = SDL_GPUCubeMapFace |
| Specifies the face of a cube map. More... | |
| using | SDL::GPUBufferUsageFlags = Uint32 |
| Specifies how a buffer is intended to be used by the client. More... | |
| using | SDL::GPUTransferBufferUsage = SDL_GPUTransferBufferUsage |
| Specifies how a transfer buffer is intended to be used by the client. More... | |
| using | SDL::GPUShaderStage = SDL_GPUShaderStage |
| Specifies which stage a shader program corresponds to. More... | |
| using | SDL::GPUVertexElementFormat = SDL_GPUVertexElementFormat |
| Specifies the format of a vertex attribute. More... | |
| using | SDL::GPUVertexInputRate = SDL_GPUVertexInputRate |
| Specifies the rate at which vertex attributes are pulled from buffers. More... | |
| using | SDL::GPUFillMode = SDL_GPUFillMode |
| Specifies the fill mode of the graphics pipeline. More... | |
| using | SDL::GPUCullMode = SDL_GPUCullMode |
| Specifies the facing direction in which triangle faces will be culled. More... | |
| using | SDL::GPUFrontFace = SDL_GPUFrontFace |
| Specifies the vertex winding that will cause a triangle to be determined to be front-facing. More... | |
| using | SDL::GPUCompareOp = SDL_GPUCompareOp |
| Specifies a comparison operator for depth, stencil and sampler operations. More... | |
| using | SDL::GPUStencilOp = SDL_GPUStencilOp |
| Specifies what happens to a stored stencil value if stencil tests fail or pass. More... | |
| using | SDL::GPUBlendOp = SDL_GPUBlendOp |
| Specifies the operator to be used when pixels in a render target are blended with existing pixels in the texture. More... | |
| using | SDL::GPUBlendFactor = SDL_GPUBlendFactor |
| Specifies a blending factor to be used when pixels in a render target are blended with existing pixels in the texture. More... | |
| using | SDL::GPUColorComponentFlags = Uint8 |
| Specifies which color components are written in a graphics pipeline. More... | |
| using | SDL::GPUFilter = SDL_GPUFilter |
| Specifies a filter operation used by a sampler. More... | |
| using | SDL::GPUSamplerMipmapMode = SDL_GPUSamplerMipmapMode |
| Specifies a mipmap mode used by a sampler. More... | |
| using | SDL::GPUSamplerAddressMode = SDL_GPUSamplerAddressMode |
| Specifies behavior of texture sampling when the coordinates exceed the 0-1 range. More... | |
| using | SDL::GPUBlitRegion = SDL_GPUBlitRegion |
| A structure specifying a region of a texture used in the blit operation. More... | |
| using | SDL::GPUIndirectDrawCommand = SDL_GPUIndirectDrawCommand |
| A structure specifying the parameters of an indirect draw command. More... | |
| using | SDL::GPUIndexedIndirectDrawCommand = SDL_GPUIndexedIndirectDrawCommand |
| A structure specifying the parameters of an indexed indirect draw command. More... | |
| using | SDL::GPUIndirectDispatchCommand = SDL_GPUIndirectDispatchCommand |
| A structure specifying the parameters of an indexed dispatch command. More... | |
| using | SDL::GPUVertexBufferDescription = SDL_GPUVertexBufferDescription |
| A structure specifying the parameters of vertex buffers used in a graphics pipeline. More... | |
| using | SDL::GPUVertexAttribute = SDL_GPUVertexAttribute |
| A structure specifying a vertex attribute. More... | |
| using | SDL::GPUVertexInputState = SDL_GPUVertexInputState |
| A structure specifying the parameters of a graphics pipeline vertex input state. More... | |
| using | SDL::GPUStencilOpState = SDL_GPUStencilOpState |
| A structure specifying the stencil operation state of a graphics pipeline. More... | |
| using | SDL::GPUColorTargetBlendState = SDL_GPUColorTargetBlendState |
| A structure specifying the blend state of a color target. More... | |
| using | SDL::GPURasterizerState = SDL_GPURasterizerState |
| A structure specifying the parameters of the graphics pipeline rasterizer state. More... | |
| using | SDL::GPUMultisampleState = SDL_GPUMultisampleState |
| A structure specifying the parameters of the graphics pipeline multisample state. More... | |
| using | SDL::GPUDepthStencilState = SDL_GPUDepthStencilState |
| A structure specifying the parameters of the graphics pipeline depth stencil state. More... | |
| using | SDL::GPUColorTargetDescription = SDL_GPUColorTargetDescription |
| A structure specifying the parameters of color targets used in a graphics pipeline. More... | |
| using | SDL::GPUGraphicsPipelineTargetInfo = SDL_GPUGraphicsPipelineTargetInfo |
| A structure specifying the descriptions of render targets used in a graphics pipeline. More... | |
| using | SDL::GPUVulkanOptions = SDL_GPUVulkanOptions |
| A structure specifying additional options when using Vulkan. More... | |
Functions | |
| bool | SDL::GPUSupportsShaderFormats (GPUShaderFormat format_flags, StringParam name) |
| Checks for GPU runtime support. More... | |
| bool | SDL::GPUSupportsProperties (PropertiesParam props) |
| Checks for GPU runtime support. More... | |
| GPUDevice | SDL::CreateGPUDevice (GPUShaderFormat format_flags, bool debug_mode, StringParam name) |
| Creates a GPU context. More... | |
| GPUDevice | SDL::CreateGPUDeviceWithProperties (PropertiesParam props) |
| Creates a GPU context. More... | |
| void | SDL::DestroyGPUDevice (GPUDeviceRaw device) |
| Destroys a GPU context previously returned by GPUDevice.GPUDevice. More... | |
| int | SDL::GetNumGPUDrivers () |
| Get the number of GPU drivers compiled into SDL. More... | |
| const char * | SDL::GetGPUDriver (int index) |
| Get the name of a built in GPU driver. More... | |
| const char * | SDL::GetGPUDeviceDriver (GPUDeviceParam device) |
| Returns the name of the backend used to create this GPU context. More... | |
| GPUShaderFormat | SDL::GetGPUShaderFormats (GPUDeviceParam device) |
| Returns the supported shader formats for this GPU context. More... | |
| PropertiesRef | SDL::GetGPUDeviceProperties (GPUDeviceParam device) |
| Get the properties associated with a GPU device. More... | |
| GPUComputePipeline | SDL::CreateGPUComputePipeline (GPUDeviceParam device, const GPUComputePipelineCreateInfo &createinfo) |
| Creates a pipeline object to be used in a compute workflow. More... | |
| GPUGraphicsPipeline | SDL::CreateGPUGraphicsPipeline (GPUDeviceParam device, const GPUGraphicsPipelineCreateInfo &createinfo) |
| Creates a pipeline object to be used in a graphics workflow. More... | |
| GPUSampler | SDL::CreateGPUSampler (GPUDeviceParam device, const GPUSamplerCreateInfo &createinfo) |
| Creates a sampler object to be used when binding textures in a graphics workflow. More... | |
| GPUShader | SDL::CreateGPUShader (GPUDeviceParam device, const GPUShaderCreateInfo &createinfo) |
| Creates a shader to be used when creating a graphics pipeline. More... | |
| GPUTexture | SDL::CreateGPUTexture (GPUDeviceParam device, const GPUTextureCreateInfo &createinfo) |
| Creates a texture object to be used in graphics or compute workflows. More... | |
| GPUBuffer | SDL::CreateGPUBuffer (GPUDeviceParam device, const GPUBufferCreateInfo &createinfo) |
| Creates a buffer object to be used in graphics or compute workflows. More... | |
| GPUTransferBuffer | SDL::CreateGPUTransferBuffer (GPUDeviceParam device, const GPUTransferBufferCreateInfo &createinfo) |
| Creates a transfer buffer to be used when uploading to or downloading from graphics resources. More... | |
| void | SDL::SetGPUBufferName (GPUDeviceParam device, GPUBuffer buffer, StringParam text) |
| Sets an arbitrary string constant to label a buffer. More... | |
| void | SDL::SetGPUTextureName (GPUDeviceParam device, GPUTexture texture, StringParam text) |
| Sets an arbitrary string constant to label a texture. More... | |
| void | SDL::InsertGPUDebugLabel (GPUCommandBuffer command_buffer, StringParam text) |
| Inserts an arbitrary string label into the command buffer callstream. More... | |
| void | SDL::PushGPUDebugGroup (GPUCommandBuffer command_buffer, StringParam name) |
| Begins a debug group with an arbitrary name. More... | |
| void | SDL::PopGPUDebugGroup (GPUCommandBuffer command_buffer) |
| Ends the most-recently pushed debug group. More... | |
| void | SDL::ReleaseGPUTexture (GPUDeviceParam device, GPUTexture texture) |
| Frees the given texture as soon as it is safe to do so. More... | |
| void | SDL::ReleaseGPUSampler (GPUDeviceParam device, GPUSampler sampler) |
| Frees the given sampler as soon as it is safe to do so. More... | |
| void | SDL::ReleaseGPUBuffer (GPUDeviceParam device, GPUBuffer buffer) |
| Frees the given buffer as soon as it is safe to do so. More... | |
| void | SDL::ReleaseGPUTransferBuffer (GPUDeviceParam device, GPUTransferBuffer transfer_buffer) |
| Frees the given transfer buffer as soon as it is safe to do so. More... | |
| void | SDL::ReleaseGPUComputePipeline (GPUDeviceParam device, GPUComputePipeline compute_pipeline) |
| Frees the given compute pipeline as soon as it is safe to do so. More... | |
| void | SDL::ReleaseGPUShader (GPUDeviceParam device, GPUShader shader) |
| Frees the given shader as soon as it is safe to do so. More... | |
| void | SDL::ReleaseGPUGraphicsPipeline (GPUDeviceParam device, GPUGraphicsPipeline graphics_pipeline) |
| Frees the given graphics pipeline as soon as it is safe to do so. More... | |
| GPUCommandBuffer | SDL::AcquireGPUCommandBuffer (GPUDeviceParam device) |
| Acquire a command buffer. More... | |
| void | SDL::PushGPUVertexUniformData (GPUCommandBuffer command_buffer, Uint32 slot_index, SourceBytes data) |
| Pushes data to a vertex uniform slot on the command buffer. More... | |
| void | SDL::PushGPUFragmentUniformData (GPUCommandBuffer command_buffer, Uint32 slot_index, SourceBytes data) |
| Pushes data to a fragment uniform slot on the command buffer. More... | |
| void | SDL::PushGPUComputeUniformData (GPUCommandBuffer command_buffer, Uint32 slot_index, SourceBytes data) |
| Pushes data to a uniform slot on the command buffer. More... | |
| GPURenderPass | SDL::BeginGPURenderPass (GPUCommandBuffer command_buffer, std::span< const GPUColorTargetInfo > color_target_infos, OptionalRef< const GPUDepthStencilTargetInfo > depth_stencil_target_info) |
| Begins a render pass on a command buffer. More... | |
| void | SDL::BindGPUGraphicsPipeline (GPURenderPass render_pass, GPUGraphicsPipeline graphics_pipeline) |
| Binds a graphics pipeline on a render pass to be used in rendering. More... | |
| void | SDL::SetGPUViewport (GPURenderPass render_pass, const GPUViewport &viewport) |
| Sets the current viewport state on a command buffer. More... | |
| void | SDL::SetGPUScissor (GPURenderPass render_pass, const RectRaw &scissor) |
| Sets the current scissor state on a command buffer. More... | |
| void | SDL::SetGPUBlendConstants (GPURenderPass render_pass, FColorRaw blend_constants) |
| Sets the current blend constants on a command buffer. More... | |
| void | SDL::SetGPUStencilReference (GPURenderPass render_pass, Uint8 reference) |
| Sets the current stencil reference value on a command buffer. More... | |
| void | SDL::BindGPUVertexBuffers (GPURenderPass render_pass, Uint32 first_slot, std::span< const GPUBufferBinding > bindings) |
| Binds vertex buffers on a command buffer for use with subsequent draw calls. More... | |
| void | SDL::BindGPUIndexBuffer (GPURenderPass render_pass, const GPUBufferBinding &binding, GPUIndexElementSize index_element_size) |
| Binds an index buffer on a command buffer for use with subsequent draw calls. More... | |
| void | SDL::BindGPUVertexSamplers (GPURenderPass render_pass, Uint32 first_slot, std::span< const GPUTextureSamplerBinding > texture_sampler_bindings) |
| Binds texture-sampler pairs for use on the vertex shader. More... | |
| void | SDL::BindGPUVertexStorageTextures (GPURenderPass render_pass, Uint32 first_slot, SpanRef< const GPUTextureRaw > storage_textures) |
| Binds storage textures for use on the vertex shader. More... | |
| void | SDL::BindGPUVertexStorageBuffers (GPURenderPass render_pass, Uint32 first_slot, SpanRef< const GPUBufferRaw > storage_buffers) |
| Binds storage buffers for use on the vertex shader. More... | |
| void | SDL::BindGPUFragmentSamplers (GPURenderPass render_pass, Uint32 first_slot, std::span< const GPUTextureSamplerBinding > texture_sampler_bindings) |
| Binds texture-sampler pairs for use on the fragment shader. More... | |
| void | SDL::BindGPUFragmentStorageTextures (GPURenderPass render_pass, Uint32 first_slot, SpanRef< const GPUTextureRaw > storage_textures) |
| Binds storage textures for use on the fragment shader. More... | |
| void | SDL::BindGPUFragmentStorageBuffers (GPURenderPass render_pass, Uint32 first_slot, SpanRef< const GPUBufferRaw > storage_buffers) |
| Binds storage buffers for use on the fragment shader. More... | |
| void | SDL::DrawGPUIndexedPrimitives (GPURenderPass render_pass, Uint32 num_indices, Uint32 num_instances, Uint32 first_index, Sint32 vertex_offset, Uint32 first_instance) |
| Draws data using bound graphics state with an index buffer and instancing enabled. More... | |
| void | SDL::DrawGPUPrimitives (GPURenderPass render_pass, Uint32 num_vertices, Uint32 num_instances, Uint32 first_vertex, Uint32 first_instance) |
| Draws data using bound graphics state. More... | |
| void | SDL::DrawGPUPrimitivesIndirect (GPURenderPass render_pass, GPUBuffer buffer, Uint32 offset, Uint32 draw_count) |
| Draws data using bound graphics state and with draw parameters set from a buffer. More... | |
| void | SDL::DrawGPUIndexedPrimitivesIndirect (GPURenderPass render_pass, GPUBuffer buffer, Uint32 offset, Uint32 draw_count) |
| Draws data using bound graphics state with an index buffer enabled and with draw parameters set from a buffer. More... | |
| void | SDL::EndGPURenderPass (GPURenderPass render_pass) |
| Ends the given render pass. More... | |
| GPUComputePass | SDL::BeginGPUComputePass (GPUCommandBuffer command_buffer, std::span< const GPUStorageTextureReadWriteBinding > storage_texture_bindings, std::span< const GPUStorageBufferReadWriteBinding > storage_buffer_bindings) |
| Begins a compute pass on a command buffer. More... | |
| void | SDL::BindGPUComputePipeline (GPUComputePass compute_pass, GPUComputePipeline compute_pipeline) |
| Binds a compute pipeline on a command buffer for use in compute dispatch. More... | |
| void | SDL::BindGPUComputeSamplers (GPUComputePass compute_pass, Uint32 first_slot, std::span< const GPUTextureSamplerBinding > texture_sampler_bindings) |
| Binds texture-sampler pairs for use on the compute shader. More... | |
| void | SDL::BindGPUComputeStorageTextures (GPUComputePass compute_pass, Uint32 first_slot, SpanRef< const GPUTextureRaw > storage_textures) |
| Binds storage textures as readonly for use on the compute pipeline. More... | |
| void | SDL::BindGPUComputeStorageBuffers (GPUComputePass compute_pass, Uint32 first_slot, SpanRef< const GPUBufferRaw > storage_buffers) |
| Binds storage buffers as readonly for use on the compute pipeline. More... | |
| void | SDL::DispatchGPUCompute (GPUComputePass compute_pass, Uint32 groupcount_x, Uint32 groupcount_y, Uint32 groupcount_z) |
| Dispatches compute work. More... | |
| void | SDL::DispatchGPUComputeIndirect (GPUComputePass compute_pass, GPUBuffer buffer, Uint32 offset) |
| Dispatches compute work with parameters set from a buffer. More... | |
| void | SDL::EndGPUComputePass (GPUComputePass compute_pass) |
| Ends the current compute pass. More... | |
| void * | SDL::MapGPUTransferBuffer (GPUDeviceParam device, GPUTransferBuffer transfer_buffer, bool cycle) |
| Maps a transfer buffer into application address space. More... | |
| void | SDL::UnmapGPUTransferBuffer (GPUDeviceParam device, GPUTransferBuffer transfer_buffer) |
| Unmaps a previously mapped transfer buffer. More... | |
| GPUCopyPass | SDL::BeginGPUCopyPass (GPUCommandBuffer command_buffer) |
| Begins a copy pass on a command buffer. More... | |
| void | SDL::UploadToGPUTexture (GPUCopyPass copy_pass, const GPUTextureTransferInfo &source, const GPUTextureRegion &destination, bool cycle) |
| Uploads data from a transfer buffer to a texture. More... | |
| void | SDL::UploadToGPUBuffer (GPUCopyPass copy_pass, const GPUTransferBufferLocation &source, const GPUBufferRegion &destination, bool cycle) |
| Uploads data from a transfer buffer to a buffer. More... | |
| void | SDL::CopyGPUTextureToTexture (GPUCopyPass copy_pass, const GPUTextureLocation &source, const GPUTextureLocation &destination, Uint32 w, Uint32 h, Uint32 d, bool cycle) |
| Performs a texture-to-texture copy. More... | |
| void | SDL::CopyGPUBufferToBuffer (GPUCopyPass copy_pass, const GPUBufferLocation &source, const GPUBufferLocation &destination, Uint32 size, bool cycle) |
| Performs a buffer-to-buffer copy. More... | |
| void | SDL::DownloadFromGPUTexture (GPUCopyPass copy_pass, const GPUTextureRegion &source, const GPUTextureTransferInfo &destination) |
| Copies data from a texture to a transfer buffer on the GPU timeline. More... | |
| void | SDL::DownloadFromGPUBuffer (GPUCopyPass copy_pass, const GPUBufferRegion &source, const GPUTransferBufferLocation &destination) |
| Copies data from a buffer to a transfer buffer on the GPU timeline. More... | |
| void | SDL::EndGPUCopyPass (GPUCopyPass copy_pass) |
| Ends the current copy pass. More... | |
| void | SDL::GenerateMipmapsForGPUTexture (GPUCommandBuffer command_buffer, GPUTexture texture) |
| Generates mipmaps for the given texture. More... | |
| void | SDL::BlitGPUTexture (GPUCommandBuffer command_buffer, const GPUBlitInfo &info) |
| Blits from a source texture region to a destination texture region. More... | |
| bool | SDL::WindowSupportsGPUSwapchainComposition (GPUDeviceParam device, WindowParam window, GPUSwapchainComposition swapchain_composition) |
| Determines whether a swapchain composition is supported by the window. More... | |
| bool | SDL::WindowSupportsGPUPresentMode (GPUDeviceParam device, WindowParam window, GPUPresentMode present_mode) |
| Determines whether a presentation mode is supported by the window. More... | |
| void | SDL::ClaimWindowForGPUDevice (GPUDeviceParam device, WindowParam window) |
| Claims a window, creating a swapchain structure for it. More... | |
| void | SDL::ReleaseWindowFromGPUDevice (GPUDeviceParam device, WindowParam window) |
| Unclaims a window, destroying its swapchain structure. More... | |
| bool | SDL::SetGPUSwapchainParameters (GPUDeviceParam device, WindowParam window, GPUSwapchainComposition swapchain_composition, GPUPresentMode present_mode) |
| Changes the swapchain parameters for the given claimed window. More... | |
| bool | SDL::SetGPUAllowedFramesInFlight (GPUDeviceParam device, Uint32 allowed_frames_in_flight) |
| Configures the maximum allowed number of frames in flight. More... | |
| GPUTextureFormat | SDL::GetGPUSwapchainTextureFormat (GPUDeviceParam device, WindowParam window) |
| Obtains the texture format of the swapchain for the given window. More... | |
| GPUTexture | SDL::AcquireGPUSwapchainTexture (GPUCommandBuffer command_buffer, WindowParam window, Uint32 *swapchain_texture_width=nullptr, Uint32 *swapchain_texture_height=nullptr) |
| Acquire a texture to use in presentation. More... | |
| void | SDL::WaitForGPUSwapchain (GPUDeviceParam device, WindowParam window) |
| Blocks the thread until a swapchain texture is available to be acquired. More... | |
| GPUTexture | SDL::WaitAndAcquireGPUSwapchainTexture (GPUCommandBuffer command_buffer, WindowParam window, Uint32 *swapchain_texture_width=nullptr, Uint32 *swapchain_texture_height=nullptr) |
| Blocks the thread until a swapchain texture is available to be acquired, and then acquires it. More... | |
| void | SDL::SubmitGPUCommandBuffer (GPUCommandBuffer command_buffer) |
| Submits a command buffer so its commands can be processed on the GPU. More... | |
| GPUFence * | SDL::SubmitGPUCommandBufferAndAcquireFence (GPUCommandBuffer command_buffer) |
| Submits a command buffer so its commands can be processed on the GPU, and acquires a fence associated with the command buffer. More... | |
| void | SDL::CancelGPUCommandBuffer (GPUCommandBuffer command_buffer) |
| Cancels a command buffer. More... | |
| void | SDL::WaitForGPUIdle (GPUDeviceParam device) |
| Blocks the thread until the GPU is completely idle. More... | |
| void | SDL::WaitForGPUFences (GPUDeviceParam device, bool wait_all, std::span< GPUFence *const > fences) |
| Blocks the thread until the given fences are signaled. More... | |
| bool | SDL::QueryGPUFence (GPUDeviceParam device, GPUFence *fence) |
| Checks the status of a fence. More... | |
| void | SDL::ReleaseGPUFence (GPUDeviceParam device, GPUFence *fence) |
| Releases a fence obtained from GPUCommandBuffer.SubmitAndAcquireFence. More... | |
| Uint32 | SDL::GPUTextureFormatTexelBlockSize (GPUTextureFormat format) |
| Obtains the texel block size for a texture format. More... | |
| bool | SDL::GPUTextureSupportsFormat (GPUDeviceParam device, GPUTextureFormat format, GPUTextureType type, GPUTextureUsageFlags usage) |
| Determines whether a texture format is supported for a given type and usage. More... | |
| bool | SDL::GPUTextureSupportsSampleCount (GPUDeviceParam device, GPUTextureFormat format, GPUSampleCount sample_count) |
| Determines if a sample count for a texture format is supported. More... | |
| Uint32 | SDL::CalculateGPUTextureFormatSize (GPUTextureFormat format, Uint32 width, Uint32 height, Uint32 depth_or_layer_count) |
| Calculate the size in bytes of a texture format with dimensions. More... | |
| PixelFormat | SDL::GetPixelFormatFromGPUTextureFormat (GPUTextureFormat format) |
| Get the SDL pixel format corresponding to a GPU texture format. More... | |
| GPUTextureFormat | SDL::GetGPUTextureFormatFromPixelFormat (PixelFormat format) |
| Get the GPU texture format corresponding to an SDL pixel format. More... | |
| void | SDL::GDKSuspendGPU (GPUDeviceParam device) |
| Call this to suspend GPU operation on Xbox when you receive the EVENT_DID_ENTER_BACKGROUND event. More... | |
| void | SDL::GDKResumeGPU (GPUDeviceParam device) |
| Call this to resume GPU operation on Xbox when you receive the EVENT_WILL_ENTER_FOREGROUND event. More... | |
| void | SDL::GPUDevice::Destroy () |
| Destroys a GPU context previously returned by GPUDevice.GPUDevice. More... | |
| const char * | SDL::GPUDevice::GetDriver () |
| Returns the name of the backend used to create this GPU context. More... | |
| GPUShaderFormat | SDL::GPUDevice::GetShaderFormats () |
| Returns the supported shader formats for this GPU context. More... | |
| PropertiesRef | SDL::GPUDevice::GetProperties () |
| Get the properties associated with a GPU device. More... | |
| GPUComputePipeline | SDL::GPUDevice::CreateComputePipeline (const GPUComputePipelineCreateInfo &createinfo) |
| Creates a pipeline object to be used in a compute workflow. More... | |
| GPUGraphicsPipeline | SDL::GPUDevice::CreateGraphicsPipeline (const GPUGraphicsPipelineCreateInfo &createinfo) |
| Creates a pipeline object to be used in a graphics workflow. More... | |
| GPUSampler | SDL::GPUDevice::CreateSampler (const GPUSamplerCreateInfo &createinfo) |
| Creates a sampler object to be used when binding textures in a graphics workflow. More... | |
| GPUShader | SDL::GPUDevice::CreateShader (const GPUShaderCreateInfo &createinfo) |
| Creates a shader to be used when creating a graphics pipeline. More... | |
| GPUTexture | SDL::GPUDevice::CreateTexture (const GPUTextureCreateInfo &createinfo) |
| Creates a texture object to be used in graphics or compute workflows. More... | |
| GPUBuffer | SDL::GPUDevice::CreateBuffer (const GPUBufferCreateInfo &createinfo) |
| Creates a buffer object to be used in graphics or compute workflows. More... | |
| GPUTransferBuffer | SDL::GPUDevice::CreateTransferBuffer (const GPUTransferBufferCreateInfo &createinfo) |
| Creates a transfer buffer to be used when uploading to or downloading from graphics resources. More... | |
| void | SDL::GPUDevice::SetBufferName (GPUBuffer buffer, StringParam text) |
| Sets an arbitrary string constant to label a buffer. More... | |
| void | SDL::GPUDevice::SetTextureName (GPUTexture texture, StringParam text) |
| Sets an arbitrary string constant to label a texture. More... | |
| void | SDL::GPUCommandBuffer::InsertDebugLabel (StringParam text) |
| Inserts an arbitrary string label into the command buffer callstream. More... | |
| void | SDL::GPUCommandBuffer::PushDebugGroup (StringParam name) |
| Begins a debug group with an arbitrary name. More... | |
| void | SDL::GPUCommandBuffer::PopDebugGroup () |
| Ends the most-recently pushed debug group. More... | |
| void | SDL::GPUDevice::ReleaseTexture (GPUTexture texture) |
| Frees the given texture as soon as it is safe to do so. More... | |
| void | SDL::GPUDevice::ReleaseSampler (GPUSampler sampler) |
| Frees the given sampler as soon as it is safe to do so. More... | |
| void | SDL::GPUDevice::ReleaseBuffer (GPUBuffer buffer) |
| Frees the given buffer as soon as it is safe to do so. More... | |
| void | SDL::GPUDevice::ReleaseTransferBuffer (GPUTransferBuffer transfer_buffer) |
| Frees the given transfer buffer as soon as it is safe to do so. More... | |
| void | SDL::GPUDevice::ReleaseComputePipeline (GPUComputePipeline compute_pipeline) |
| Frees the given compute pipeline as soon as it is safe to do so. More... | |
| void | SDL::GPUDevice::ReleaseShader (GPUShader shader) |
| Frees the given shader as soon as it is safe to do so. More... | |
| void | SDL::GPUDevice::ReleaseGraphicsPipeline (GPUGraphicsPipeline graphics_pipeline) |
| Frees the given graphics pipeline as soon as it is safe to do so. More... | |
| GPUCommandBuffer | SDL::GPUDevice::AcquireCommandBuffer () |
| Acquire a command buffer. More... | |
| void | SDL::GPUCommandBuffer::PushVertexUniformData (Uint32 slot_index, SourceBytes data) |
| Pushes data to a vertex uniform slot on the command buffer. More... | |
| void | SDL::GPUCommandBuffer::PushFragmentUniformData (Uint32 slot_index, SourceBytes data) |
| Pushes data to a fragment uniform slot on the command buffer. More... | |
| void | SDL::GPUCommandBuffer::PushComputeUniformData (Uint32 slot_index, SourceBytes data) |
| Pushes data to a uniform slot on the command buffer. More... | |
| GPURenderPass | SDL::GPUCommandBuffer::BeginRenderPass (std::span< const GPUColorTargetInfo > color_target_infos, OptionalRef< const GPUDepthStencilTargetInfo > depth_stencil_target_info) |
| Begins a render pass on a command buffer. More... | |
| void | SDL::GPURenderPass::BindPipeline (GPUGraphicsPipeline graphics_pipeline) |
| Binds a graphics pipeline on a render pass to be used in rendering. More... | |
| void | SDL::GPURenderPass::SetViewport (const GPUViewport &viewport) |
| Sets the current viewport state on a command buffer. More... | |
| void | SDL::GPURenderPass::SetScissor (const RectRaw &scissor) |
| Sets the current scissor state on a command buffer. More... | |
| void | SDL::GPURenderPass::SetBlendConstants (FColorRaw blend_constants) |
| Sets the current blend constants on a command buffer. More... | |
| void | SDL::GPURenderPass::SetStencilReference (Uint8 reference) |
| Sets the current stencil reference value on a command buffer. More... | |
| void | SDL::GPURenderPass::BindVertexBuffers (Uint32 first_slot, std::span< const GPUBufferBinding > bindings) |
| Binds vertex buffers on a command buffer for use with subsequent draw calls. More... | |
| void | SDL::GPURenderPass::BindIndexBuffer (const GPUBufferBinding &binding, GPUIndexElementSize index_element_size) |
| Binds an index buffer on a command buffer for use with subsequent draw calls. More... | |
| void | SDL::GPURenderPass::BindVertexSamplers (Uint32 first_slot, std::span< const GPUTextureSamplerBinding > texture_sampler_bindings) |
| Binds texture-sampler pairs for use on the vertex shader. More... | |
| void | SDL::GPURenderPass::BindVertexStorageTextures (Uint32 first_slot, SpanRef< const GPUTextureRaw > storage_textures) |
| Binds storage textures for use on the vertex shader. More... | |
| void | SDL::GPURenderPass::BindVertexStorageBuffers (Uint32 first_slot, SpanRef< const GPUBufferRaw > storage_buffers) |
| Binds storage buffers for use on the vertex shader. More... | |
| void | SDL::GPURenderPass::BindFragmentSamplers (Uint32 first_slot, std::span< const GPUTextureSamplerBinding > texture_sampler_bindings) |
| Binds texture-sampler pairs for use on the fragment shader. More... | |
| void | SDL::GPURenderPass::BindFragmentStorageTextures (Uint32 first_slot, SpanRef< const GPUTextureRaw > storage_textures) |
| Binds storage textures for use on the fragment shader. More... | |
| void | SDL::GPURenderPass::BindFragmentStorageBuffers (Uint32 first_slot, SpanRef< const GPUBufferRaw > storage_buffers) |
| Binds storage buffers for use on the fragment shader. More... | |
| void | SDL::GPURenderPass::DrawIndexedPrimitives (Uint32 num_indices, Uint32 num_instances, Uint32 first_index, Sint32 vertex_offset, Uint32 first_instance) |
| Draws data using bound graphics state with an index buffer and instancing enabled. More... | |
| void | SDL::GPURenderPass::DrawPrimitives (Uint32 num_vertices, Uint32 num_instances, Uint32 first_vertex, Uint32 first_instance) |
| Draws data using bound graphics state. More... | |
| void | SDL::GPURenderPass::DrawPrimitivesIndirect (GPUBuffer buffer, Uint32 offset, Uint32 draw_count) |
| Draws data using bound graphics state and with draw parameters set from a buffer. More... | |
| void | SDL::GPURenderPass::DrawIndexedPrimitivesIndirect (GPUBuffer buffer, Uint32 offset, Uint32 draw_count) |
| Draws data using bound graphics state with an index buffer enabled and with draw parameters set from a buffer. More... | |
| void | SDL::GPURenderPass::End () |
| Ends the given render pass. More... | |
| GPUComputePass | SDL::GPUCommandBuffer::BeginComputePass (std::span< const GPUStorageTextureReadWriteBinding > storage_texture_bindings, std::span< const GPUStorageBufferReadWriteBinding > storage_buffer_bindings) |
| Begins a compute pass on a command buffer. More... | |
| void | SDL::GPUComputePass::BindPipeline (GPUComputePipeline compute_pipeline) |
| Binds a compute pipeline on a command buffer for use in compute dispatch. More... | |
| void | SDL::GPUComputePass::BindSamplers (Uint32 first_slot, std::span< const GPUTextureSamplerBinding > texture_sampler_bindings) |
| Binds texture-sampler pairs for use on the compute shader. More... | |
| void | SDL::GPUComputePass::BindStorageTextures (Uint32 first_slot, SpanRef< const GPUTextureRaw > storage_textures) |
| Binds storage textures as readonly for use on the compute pipeline. More... | |
| void | SDL::GPUComputePass::BindStorageBuffers (Uint32 first_slot, SpanRef< const GPUBufferRaw > storage_buffers) |
| Binds storage buffers as readonly for use on the compute pipeline. More... | |
| void | SDL::GPUComputePass::Dispatch (Uint32 groupcount_x, Uint32 groupcount_y, Uint32 groupcount_z) |
| Dispatches compute work. More... | |
| void | SDL::GPUComputePass::DispatchIndirect (GPUBuffer buffer, Uint32 offset) |
| Dispatches compute work with parameters set from a buffer. More... | |
| void | SDL::GPUComputePass::End () |
| Ends the current compute pass. More... | |
| void * | SDL::GPUDevice::MapTransferBuffer (GPUTransferBuffer transfer_buffer, bool cycle) |
| Maps a transfer buffer into application address space. More... | |
| void | SDL::GPUDevice::UnmapTransferBuffer (GPUTransferBuffer transfer_buffer) |
| Unmaps a previously mapped transfer buffer. More... | |
| GPUCopyPass | SDL::GPUCommandBuffer::BeginCopyPass () |
| Begins a copy pass on a command buffer. More... | |
| void | SDL::GPUCopyPass::UploadToTexture (const GPUTextureTransferInfo &source, const GPUTextureRegion &destination, bool cycle) |
| Uploads data from a transfer buffer to a texture. More... | |
| void | SDL::GPUCopyPass::UploadToBuffer (const GPUTransferBufferLocation &source, const GPUBufferRegion &destination, bool cycle) |
| Uploads data from a transfer buffer to a buffer. More... | |
| void | SDL::GPUCopyPass::CopyTextureToTexture (const GPUTextureLocation &source, const GPUTextureLocation &destination, Uint32 w, Uint32 h, Uint32 d, bool cycle) |
| Performs a texture-to-texture copy. More... | |
| void | SDL::GPUCopyPass::CopyBufferToBuffer (const GPUBufferLocation &source, const GPUBufferLocation &destination, Uint32 size, bool cycle) |
| Performs a buffer-to-buffer copy. More... | |
| void | SDL::GPUCopyPass::DownloadFromTexture (const GPUTextureRegion &source, const GPUTextureTransferInfo &destination) |
| Copies data from a texture to a transfer buffer on the GPU timeline. More... | |
| void | SDL::GPUCopyPass::DownloadFromBuffer (const GPUBufferRegion &source, const GPUTransferBufferLocation &destination) |
| Copies data from a buffer to a transfer buffer on the GPU timeline. More... | |
| void | SDL::GPUCopyPass::End () |
| Ends the current copy pass. More... | |
| void | SDL::GPUCommandBuffer::GenerateMipmapsForTexture (GPUTexture texture) |
| Generates mipmaps for the given texture. More... | |
| void | SDL::GPUCommandBuffer::BlitTexture (const GPUBlitInfo &info) |
| Blits from a source texture region to a destination texture region. More... | |
| bool | SDL::GPUDevice::WindowSupportsSwapchainComposition (WindowParam window, GPUSwapchainComposition swapchain_composition) |
| Determines whether a swapchain composition is supported by the window. More... | |
| bool | SDL::GPUDevice::WindowSupportsPresentMode (WindowParam window, GPUPresentMode present_mode) |
| Determines whether a presentation mode is supported by the window. More... | |
| void | SDL::GPUDevice::ClaimWindow (WindowParam window) |
| Claims a window, creating a swapchain structure for it. More... | |
| void | SDL::GPUDevice::ReleaseWindow (WindowParam window) |
| Unclaims a window, destroying its swapchain structure. More... | |
| bool | SDL::GPUDevice::SetSwapchainParameters (WindowParam window, GPUSwapchainComposition swapchain_composition, GPUPresentMode present_mode) |
| Changes the swapchain parameters for the given claimed window. More... | |
| bool | SDL::GPUDevice::SetAllowedFramesInFlight (Uint32 allowed_frames_in_flight) |
| Configures the maximum allowed number of frames in flight. More... | |
| GPUTextureFormat | SDL::GPUDevice::GetSwapchainTextureFormat (WindowParam window) |
| Obtains the texture format of the swapchain for the given window. More... | |
| GPUTexture | SDL::GPUCommandBuffer::AcquireSwapchainTexture (WindowParam window, Uint32 *swapchain_texture_width=nullptr, Uint32 *swapchain_texture_height=nullptr) |
| Acquire a texture to use in presentation. More... | |
| void | SDL::GPUDevice::WaitForSwapchain (WindowParam window) |
| Blocks the thread until a swapchain texture is available to be acquired. More... | |
| GPUTexture | SDL::GPUCommandBuffer::WaitAndAcquireSwapchainTexture (WindowParam window, Uint32 *swapchain_texture_width=nullptr, Uint32 *swapchain_texture_height=nullptr) |
| Blocks the thread until a swapchain texture is available to be acquired, and then acquires it. More... | |
| void | SDL::GPUCommandBuffer::Submit () |
| Submits a command buffer so its commands can be processed on the GPU. More... | |
| GPUFence * | SDL::GPUCommandBuffer::SubmitAndAcquireFence () |
| Submits a command buffer so its commands can be processed on the GPU, and acquires a fence associated with the command buffer. More... | |
| void | SDL::GPUCommandBuffer::Cancel () |
| Cancels a command buffer. More... | |
| void | SDL::GPUDevice::WaitForIdle () |
| Blocks the thread until the GPU is completely idle. More... | |
| void | SDL::GPUDevice::WaitForFences (bool wait_all, std::span< GPUFence *const > fences) |
| Blocks the thread until the given fences are signaled. More... | |
| bool | SDL::GPUDevice::QueryFence (GPUFence *fence) |
| Checks the status of a fence. More... | |
| void | SDL::GPUDevice::ReleaseFence (GPUFence *fence) |
| Releases a fence obtained from GPUCommandBuffer.SubmitAndAcquireFence. More... | |
| bool | SDL::GPUDevice::TextureSupportsFormat (GPUTextureFormat format, GPUTextureType type, GPUTextureUsageFlags usage) |
| Determines whether a texture format is supported for a given type and usage. More... | |
| bool | SDL::GPUDevice::TextureSupportsSampleCount (GPUTextureFormat format, GPUSampleCount sample_count) |
| Determines if a sample count for a texture format is supported. More... | |
| void | SDL::GPUDevice::GDKSuspendGPU () |
| Call this to suspend GPU operation on Xbox when you receive the EVENT_DID_ENTER_BACKGROUND event. More... | |
| void | SDL::GPUDevice::GDKResumeGPU () |
| Call this to resume GPU operation on Xbox when you receive the EVENT_WILL_ENTER_FOREGROUND event. More... | |
Detailed Description
It offers both 3D graphics and compute support, in the style of Metal, Vulkan, and Direct3D 12.
A basic workflow might be something like this:
The app creates a GPU device with GPUDevice.GPUDevice(), and assigns it to a window with GPUDevice.ClaimWindow()–although strictly speaking you can render offscreen entirely, perhaps for image processing, and not use a window at all.
Next, the app prepares static data (things that are created once and used over and over). For example:
- Shaders (programs that run on the GPU): use GPUShader.GPUShader().
- Vertex buffers (arrays of geometry data) and other rendering data: use GPUBuffer.GPUBuffer() and GPUCopyPass.UploadToBuffer().
- Textures (images): use GPUTexture.GPUTexture() and GPUCopyPass.UploadToTexture().
- Samplers (how textures should be read from): use GPUSampler.GPUSampler().
- Render pipelines (precalculated rendering state): use GPUGraphicsPipeline.GPUGraphicsPipeline()
To render, the app creates one or more command buffers, with GPUDevice.AcquireCommandBuffer(). Command buffers collect rendering instructions that will be submitted to the GPU in batch. Complex scenes can use multiple command buffers, maybe configured across multiple threads in parallel, as long as they are submitted in the correct order, but many apps will just need one command buffer per frame.
Rendering can happen to a texture (what other APIs call a "render target") or it can happen to the swapchain texture (which is just a special texture that represents a window's contents). The app can use GPUCommandBuffer.WaitAndAcquireSwapchainTexture() to render to the window.
Rendering actually happens in a Render Pass, which is encoded into a command buffer. One can encode multiple render passes (or alternate between render and compute passes) in a single command buffer, but many apps might simply need a single render pass in a single command buffer. Render Passes can render to up to four color textures and one depth texture simultaneously. If the set of textures being rendered to needs to change, the Render Pass must be ended and a new one must be begun.
The app calls GPUCommandBuffer.BeginRenderPass(). Then it sets states it needs for each draw:
- GPURenderPass.BindPipeline()
- GPURenderPass.SetViewport()
- GPURenderPass.BindVertexBuffers()
- GPURenderPass.BindVertexSamplers()
- etc
Then, make the actual draw commands with these states:
- GPURenderPass.DrawPrimitives()
- GPURenderPass.DrawPrimitivesIndirect()
- GPURenderPass.DrawIndexedPrimitivesIndirect()
- etc
After all the drawing commands for a pass are complete, the app should call GPURenderPass.End(). Once a render pass ends all render-related state is reset.
The app can begin new Render Passes and make new draws in the same command buffer until the entire scene is rendered.
Once all of the render commands for the scene are complete, the app calls GPUCommandBuffer.Submit() to send it to the GPU for processing.
If the app needs to read back data from texture or buffers, the API has an efficient way of doing this, provided that the app is willing to tolerate some latency. When the app uses GPUCopyPass.DownloadFromTexture() or GPUCopyPass.DownloadFromBuffer(), submitting the command buffer with GPUCommandBuffer.SubmitAndAcquireFence() will return a fence handle that the app can poll or wait on in a thread. Once the fence indicates that the command buffer is done processing, it is safe to read the downloaded data. Make sure to call GPUDevice.ReleaseFence() when done with the fence.
The API also has "compute" support. The app calls GPUCommandBuffer.BeginComputePass() with compute-writeable textures and/or buffers, which can be written to in a compute shader. Then it sets states it needs for the compute dispatches:
- GPUComputePass.BindPipeline()
- GPUComputePass.BindStorageBuffers()
- GPUComputePass.BindStorageTextures()
Then, dispatch compute work:
For advanced users, this opens up powerful GPU-driven workflows.
Graphics and compute pipelines require the use of shaders, which as mentioned above are small programs executed on the GPU. Each backend (Vulkan, Metal, D3D12) requires a different shader format. When the app creates the GPU device, the app lets the device know which shader formats the app can provide. It will then select the appropriate backend depending on the available shader formats and the backends available on the platform. When creating shaders, the app must provide the correct shader format for the selected backend. If you would like to learn more about why the API works this way, there is a detailed blog post explaining this situation.
It is optimal for apps to pre-compile the shader formats they might use, but for ease of use SDL provides a separate project, SDL_shadercross , for performing runtime shader cross-compilation. It also has a CLI interface for offline precompilation as well.
This is an extremely quick overview that leaves out several important details. Already, though, one can see that GPU programming can be quite complex! If you just need simple 2D graphics, the Render API is much easier to use but still hardware-accelerated. That said, even for 2D applications the performance benefits and expressiveness of the GPU API are significant.
The GPU API targets a feature set with a wide range of hardware support and ease of portability. It is designed so that the app won't have to branch itself by querying feature support. If you need cutting-edge features with limited hardware support, this API is probably not for you.
Examples demonstrating proper usage of this API can be found here.
Performance considerations
Here are some basic tips for maximizing your rendering performance.
- Beginning a new render pass is relatively expensive. Use as few render passes as you can.
- Minimize the amount of state changes. For example, binding a pipeline is relatively cheap, but doing it hundreds of times when you don't need to will slow the performance significantly.
- Perform your data uploads as early as possible in the frame.
- Don't churn resources. Creating and releasing resources is expensive. It's better to create what you need up front and cache it.
- Don't use uniform buffers for large amounts of data (more than a matrix or so). Use a storage buffer instead.
- Use cycling correctly. There is a detailed explanation of cycling further below.
- Use culling techniques to minimize pixel writes. The less writing the GPU has to do the better. Culling can be a very advanced topic but even simple culling techniques can boost performance significantly.
In general try to remember the golden rule of performance: doing things is more expensive than not doing things. Don't Touch The Driver!
FAQ
Question: When are you adding more advanced features, like ray tracing or mesh shaders?
Answer: We don't have immediate plans to add more bleeding-edge features, but we certainly might in the future, when these features prove worthwhile, and reasonable to implement across several platforms and underlying APIs. So while these things are not in the "never" category, they are definitely not "near future" items either.
Question: Why is my shader not working?
Answer: A common oversight when using shaders is not properly laying out the shader resources/registers correctly. The GPU API is very strict with how it wants resources to be laid out and it's difficult for the API to automatically validate shaders to see if they have a compatible layout. See the documentation for GPUShader.GPUShader() and GPUComputePipeline.GPUComputePipeline() for information on the expected layout.
Another common issue is not setting the correct number of samplers, textures, and buffers in GPUShaderCreateInfo. If possible use shader reflection to extract the required information from the shader automatically instead of manually filling in the struct's values.
Question: My application isn't performing very well. Is this the GPU API's fault?
Answer: No. Long answer: The GPU API is a relatively thin layer over the underlying graphics API. While it's possible that we have done something inefficiently, it's very unlikely especially if you are relatively inexperienced with GPU rendering. Please see the performance tips above and make sure you are following them. Additionally, tools like RenderDoc can be very helpful for diagnosing incorrect behavior and performance issues.
System Requirements
Vulkan
SDL driver name: "vulkan" (for use in GPUDevice.GPUDevice() and prop::GpuDevice.CREATE_NAME_STRING)
Supported on Windows, Linux, Nintendo Switch, and certain Android devices. Requires Vulkan 1.0 with the following extensions and device features:
VK_KHR_swapchainVK_KHR_maintenance1independentBlendimageCubeArraydepthClampshaderClipDistancedrawIndirectFirstInstancesampleRateShading
You can remove some of these requirements to increase compatibility with Android devices by using these properties when creating the GPU device with GPUDevice.GPUDevice():
- prop::GpuDevice.CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN
- prop::GpuDevice.CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN
- prop::GpuDevice.CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN
- prop::GpuDevice.CREATE_FEATURE_ANISOTROPY_BOOLEAN
D3D12
SDL driver name: "direct3d12"
Supported on Windows 10 or newer, Xbox One (GDK), and Xbox Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level 11_0 and Resource Binding Tier 2 or above.
You can remove the Tier 2 resource binding requirement to support Intel Haswell and Broadwell GPUs by using this property when creating the GPU device with GPUDevice.GPUDevice():
- prop::GpuDevice.CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN
Metal
SDL driver name: "metal"
Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware requirements vary by operating system:
- macOS requires an Apple Silicon or Intel Mac2 family GPU
- iOS/tvOS requires an A9 GPU or newer
- iOS Simulator and tvOS Simulator are unsupported
Coordinate System
The GPU API uses a left-handed coordinate system, following the convention of D3D12 and Metal. Specifically:
- Normalized Device Coordinates: The lower-left corner has an x,y coordinate of
(-1.0, -1.0). The upper-right corner is(1.0, 1.0). Z values range from[0.0, 1.0]where 0 is the near plane. - Viewport Coordinates: The top-left corner has an x,y coordinate of
(0, 0)and extends to the bottom-right corner at(viewportWidth, viewportHeight). +Y is down. - Texture Coordinates: The top-left corner has an x,y coordinate of
(0, 0)and extends to the bottom-right corner at(1.0, 1.0). +Y is down.
If the backend driver differs from this convention (e.g. Vulkan, which has an NDC that assumes +Y is down), SDL will automatically convert the coordinate system behind the scenes, so you don't need to perform any coordinate flipping logic in your shaders.
Uniform Data
Uniforms are for passing data to shaders. The uniform data will be constant across all executions of the shader.
There are 4 available uniform slots per shader stage (where the stages are vertex, fragment, and compute). Uniform data pushed to a slot on a stage keeps its value throughout the command buffer until you call the relevant Push function on that slot again.
For example, you could write your vertex shaders to read a camera matrix from uniform binding slot 0, push the camera matrix at the start of the command buffer, and that data will be used for every subsequent draw call.
It is valid to push uniform data during a render or compute pass.
Uniforms are best for pushing small amounts of data. If you are pushing more than a matrix or two per call you should consider using a storage buffer instead.
A Note On Cycling
When using a command buffer, operations do not occur immediately - they occur some time after the command buffer is submitted.
When a resource is used in a pending or active command buffer, it is considered to be "bound". When a resource is no longer used in any pending or active command buffers, it is considered to be "unbound".
If data resources are bound, it is unspecified when that data will be unbound unless you acquire a fence when submitting the command buffer and wait on it. However, this doesn't mean you need to track resource usage manually.
All of the functions and structs that involve writing to a resource have a "cycle" bool. GPUTransferBuffer, GPUBuffer, and GPUTexture all effectively function as ring buffers on internal resources. When cycle is true, if the resource is bound, the cycle rotates to the next unbound internal resource, or if none are available, a new one is created. This means you don't have to worry about complex state tracking and synchronization as long as cycling is correctly employed.
For example: you can call GPUDevice.MapTransferBuffer(), write texture data, GPUDevice.UnmapTransferBuffer(), and then GPUCopyPass.UploadToTexture(). The next time you write texture data to the transfer buffer, if you set the cycle param to true, you don't have to worry about overwriting any data that is not yet uploaded.
Another example: If you are using a texture in a render pass every frame, this can cause a data dependency between frames. If you set cycle to true in the GPUColorTargetInfo struct, you can prevent this data dependency.
Cycling will never undefine already bound data. When cycling, all data in the resource is considered to be undefined for subsequent commands until that data is written again. You must take care not to read undefined data.
Note that when cycling a texture, the entire texture will be cycled, even if only part of the texture is used in the call, so you must consider the entire texture to contain undefined data after cycling.
You must also take care not to overwrite a section of data that has been referenced in a command without cycling first. It is OK to overwrite unreferenced data in a bound resource without cycling, but overwriting a section of data that has already been referenced will produce unexpected results.
Debugging
At some point of your GPU journey, you will probably encounter issues that are not traceable with regular debugger - for example, your code compiles but you get an empty screen, or your shader fails in runtime.
For debugging such cases, there are tools that allow visually inspecting the whole GPU frame, every drawcall, every bound resource, memory buffers, etc. They are the following, per platform:
- For Windows/Linux, use RenderDoc * For MacOS (Metal), use Xcode built-in debugger (Open XCode, go to Debug > Debug Executable..., select your application, set "GPU Frame Capture" to "Metal" in scheme "Options" window, run your app, and click the small Metal icon on the bottom to capture a frame)
Aside from that, you may want to enable additional debug layers to receive more detailed error messages, based on your GPU backend:
- For D3D12, the debug layer is an optional feature that can be installed via "Windows Settings -> System -> Optional features" and adding the "Graphics
Tools" optional feature. * For Vulkan, you will need to install Vulkan SDK on Windows, and on Linux, you usually have some sort of
vulkan-validation-layerssystem package that should be installed. * For Metal, it should be enough just to run the application from XCode to receive detailed errors or warnings in the output.
Don't hesitate to use tools as RenderDoc when encountering runtime issues or unexpected output on screen, quick GPU frame inspection can usually help you fix the majority of such problems.
Typedef Documentation
◆ GPUBlendFactor
| using SDL::GPUBlendFactor = typedef SDL_GPUBlendFactor |
The source color is the value written by the fragment shader. The destination color is the value currently existing in the texture.
- Since
- This enum is available since SDL 3.2.0.
◆ GPUBlendOp
| using SDL::GPUBlendOp = typedef SDL_GPUBlendOp |
The source color is the value written by the fragment shader. The destination color is the value currently existing in the texture.
- Since
- This enum is available since SDL 3.2.0.
◆ GPUBlitInfo
| using SDL::GPUBlitInfo = typedef SDL_GPUBlitInfo |
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.BlitTexture
◆ GPUBlitRegion
| using SDL::GPUBlitRegion = typedef SDL_GPUBlitRegion |
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.BlitTexture
◆ GPUBufferBinding
| using SDL::GPUBufferBinding = typedef SDL_GPUBufferBinding |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUBufferCreateInfo
| using SDL::GPUBufferCreateInfo = typedef SDL_GPUBufferCreateInfo |
Usage flags can be bitwise OR'd together for combinations of usages. Note that certain combinations are invalid, for example VERTEX and INDEX.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUBufferLocation
| using SDL::GPUBufferLocation = typedef SDL_GPUBufferLocation |
Used when copying data between buffers.
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUCopyPass.CopyBufferToBuffer
◆ GPUBufferRegion
| using SDL::GPUBufferRegion = typedef SDL_GPUBufferRegion |
Used when transferring data to or from buffers.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUBufferUsageFlags
| using SDL::GPUBufferUsageFlags = typedef Uint32 |
A buffer must have at least one usage flag. Note that some usage flag combinations are invalid.
Unlike textures, READ | WRITE can be used for simultaneous read-write usage. The same data synchronization concerns as textures apply.
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.
- Since
- This datatype is available since SDL 3.2.0.
- See also
- GPUBuffer.GPUBuffer
◆ GPUColorComponentFlags
| using SDL::GPUColorComponentFlags = typedef Uint8 |
- Since
- This datatype is available since SDL 3.2.0.
◆ GPUColorTargetBlendState
| using SDL::GPUColorTargetBlendState = typedef SDL_GPUColorTargetBlendState |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUColorTargetDescription
| using SDL::GPUColorTargetDescription = typedef SDL_GPUColorTargetDescription |
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUGraphicsPipelineTargetInfo
◆ GPUColorTargetInfo
| using SDL::GPUColorTargetInfo = typedef SDL_GPUColorTargetInfo |
The load_op field determines what is done with the texture at the beginning of the render pass.
- LOAD: Loads the data currently in the texture. Not recommended for multisample textures as it requires significant memory bandwidth.
- CLEAR: Clears the texture to a single color.
- DONT_CARE: The driver will do whatever it wants with the texture memory. This is a good option if you know that every single pixel will be touched in the render pass.
The store_op field determines what is done with the color results of the render pass.
- STORE: Stores the results of the render pass in the texture. Not recommended for multisample textures as it requires significant memory bandwidth.
- DONT_CARE: The driver will do whatever it wants with the texture memory. This is often a good option for depth/stencil textures.
- RESOLVE: Resolves a multisample texture into resolve_texture, which must have a sample count of 1. Then the driver may discard the multisample texture memory. This is the most performant method of resolving a multisample target.
- RESOLVE_AND_STORE: Resolves a multisample texture into the resolve_texture, which must have a sample count of 1. Then the driver stores the multisample texture's contents. Not recommended as it requires significant memory bandwidth.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUCompareOp
| using SDL::GPUCompareOp = typedef SDL_GPUCompareOp |
- Since
- This enum is available since SDL 3.2.0.
◆ GPUComputePipelineCreateInfo
| using SDL::GPUComputePipelineCreateInfo = typedef SDL_GPUComputePipelineCreateInfo |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUCubeMapFace
| using SDL::GPUCubeMapFace = typedef SDL_GPUCubeMapFace |
Can be passed in as the layer field in texture-related structs.
- Since
- This enum is available since SDL 3.2.0.
◆ GPUCullMode
| using SDL::GPUCullMode = typedef SDL_GPUCullMode |
- Since
- This enum is available since SDL 3.2.0.
◆ GPUDepthStencilState
| using SDL::GPUDepthStencilState = typedef SDL_GPUDepthStencilState |
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUGraphicsPipelineCreateInfo
◆ GPUDepthStencilTargetInfo
| using SDL::GPUDepthStencilTargetInfo = typedef SDL_GPUDepthStencilTargetInfo |
The load_op field determines what is done with the depth contents of the texture at the beginning of the render pass.
- LOAD: Loads the depth values currently in the texture.
- CLEAR: Clears the texture to a single depth.
- DONT_CARE: The driver will do whatever it wants with the memory. This is a good option if you know that every single pixel will be touched in the render pass.
The store_op field determines what is done with the depth results of the render pass.
- STORE: Stores the depth results in the texture.
- DONT_CARE: The driver will do whatever it wants with the depth results. This is often a good option for depth/stencil textures that don't need to be reused again.
The stencil_load_op field determines what is done with the stencil contents of the texture at the beginning of the render pass.
- LOAD: Loads the stencil values currently in the texture.
- CLEAR: Clears the stencil values to a single value.
- DONT_CARE: The driver will do whatever it wants with the memory. This is a good option if you know that every single pixel will be touched in the render pass.
The stencil_store_op field determines what is done with the stencil results of the render pass.
- STORE: Stores the stencil results in the texture.
- DONT_CARE: The driver will do whatever it wants with the stencil results. This is often a good option for depth/stencil textures that don't need to be reused again.
Note that depth/stencil targets do not support multisample resolves.
Due to ABI limitations, depth textures with more than 255 layers are not supported.
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.BeginRenderPass
◆ GPUFence
| using SDL::GPUFence = typedef SDL_GPUFence |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUFillMode
| using SDL::GPUFillMode = typedef SDL_GPUFillMode |
- Since
- This enum is available since SDL 3.2.0.
◆ GPUFilter
| using SDL::GPUFilter = typedef SDL_GPUFilter |
- Since
- This enum is available since SDL 3.2.0.
- See also
- GPUSampler.GPUSampler
◆ GPUFrontFace
| using SDL::GPUFrontFace = typedef SDL_GPUFrontFace |
- Since
- This enum is available since SDL 3.2.0.
◆ GPUGraphicsPipelineCreateInfo
| using SDL::GPUGraphicsPipelineCreateInfo = typedef SDL_GPUGraphicsPipelineCreateInfo |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUGraphicsPipelineTargetInfo
| using SDL::GPUGraphicsPipelineTargetInfo = typedef SDL_GPUGraphicsPipelineTargetInfo |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUIndexedIndirectDrawCommand
| using SDL::GPUIndexedIndirectDrawCommand = typedef SDL_GPUIndexedIndirectDrawCommand |
Note that the first_vertex and first_instance parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID); GPU APIs and shader languages do not define these built-in variables consistently, so if your shader depends on them, the only way to keep behavior consistent and portable is to always pass 0 for the correlating parameter in the draw calls.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUIndexElementSize
| using SDL::GPUIndexElementSize = typedef SDL_GPUIndexElementSize |
- Since
- This enum is available since SDL 3.2.0.
◆ GPUIndirectDispatchCommand
| using SDL::GPUIndirectDispatchCommand = typedef SDL_GPUIndirectDispatchCommand |
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUComputePass.DispatchIndirect
◆ GPUIndirectDrawCommand
| using SDL::GPUIndirectDrawCommand = typedef SDL_GPUIndirectDrawCommand |
Note that the first_vertex and first_instance parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID); GPU APIs and shader languages do not define these built-in variables consistently, so if your shader depends on them, the only way to keep behavior consistent and portable is to always pass 0 for the correlating parameter in the draw calls.
- Since
- This struct is available since SDL 3.2.0.
◆ GPULoadOp
| using SDL::GPULoadOp = typedef SDL_GPULoadOp |
- Since
- This enum is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.BeginRenderPass
◆ GPUMultisampleState
| using SDL::GPUMultisampleState = typedef SDL_GPUMultisampleState |
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUGraphicsPipelineCreateInfo
◆ GPUPresentMode
| using SDL::GPUPresentMode = typedef SDL_GPUPresentMode |
VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be supported on certain systems.
It is recommended to query GPUDevice.WindowSupportsPresentMode after claiming the window if you wish to change the present mode to IMMEDIATE or MAILBOX.
- VSYNC: Waits for vblank before presenting. No tearing is possible. If there is a pending image to present, the new image is enqueued for presentation. Disallows tearing at the cost of visual latency.
- IMMEDIATE: Immediately presents. Lowest latency option, but tearing may occur.
- MAILBOX: Waits for vblank before presenting. No tearing is possible. If there is a pending image to present, the pending image is replaced by the new image. Similar to VSYNC, but with reduced visual latency.
- Since
- This enum is available since SDL 3.2.0.
◆ GPUPrimitiveType
| using SDL::GPUPrimitiveType = typedef SDL_GPUPrimitiveType |
If you are using POINTLIST you must include a point size output in the vertex shader.
- For HLSL compiling to SPIRV you must decorate a float output with [[vk::builtin("PointSize")]].
- For GLSL you must set the gl_PointSize builtin.
- For MSL you must include a float output with the [[point_size]] decorator.
Note that sized point topology is totally unsupported on D3D12. Any size other than 1 will be ignored. In general, you should avoid using point topology for both compatibility and performance reasons. You WILL regret using it.
- Since
- This enum is available since SDL 3.2.0.
◆ GPURasterizerState
| using SDL::GPURasterizerState = typedef SDL_GPURasterizerState |
Note that GPU_FILLMODE_LINE is not supported on many Android devices. For those devices, the fill mode will automatically fall back to FILL.
Also note that the D3D12 driver will enable depth clamping even if enable_depth_clip is true. If you need this clamp+clip behavior, consider enabling depth clip and then manually clamping depth in your fragment shaders on Metal and Vulkan.
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUGraphicsPipelineCreateInfo
◆ GPUSampleCount
| using SDL::GPUSampleCount = typedef SDL_GPUSampleCount |
Used in multisampling. Note that this value only applies when the texture is used as a render target.
- Since
- This enum is available since SDL 3.2.0.
◆ GPUSamplerAddressMode
| using SDL::GPUSamplerAddressMode = typedef SDL_GPUSamplerAddressMode |
- Since
- This enum is available since SDL 3.2.0.
- See also
- GPUSampler.GPUSampler
◆ GPUSamplerCreateInfo
| using SDL::GPUSamplerCreateInfo = typedef SDL_GPUSamplerCreateInfo |
Note that mip_lod_bias is a no-op for the Metal driver. For Metal, LOD bias must be applied via shader instead.
- Since
- This function is available since SDL 3.2.0.
◆ GPUSamplerMipmapMode
| using SDL::GPUSamplerMipmapMode = typedef SDL_GPUSamplerMipmapMode |
- Since
- This enum is available since SDL 3.2.0.
- See also
- GPUSampler.GPUSampler
◆ GPUShaderCreateInfo
| using SDL::GPUShaderCreateInfo = typedef SDL_GPUShaderCreateInfo |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUShaderFormat
| using SDL::GPUShaderFormat = typedef Uint32 |
Each format corresponds to a specific backend that accepts it.
- Since
- This datatype is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ GPUShaderStage
| using SDL::GPUShaderStage = typedef SDL_GPUShaderStage |
- Since
- This enum is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ GPUStencilOp
| using SDL::GPUStencilOp = typedef SDL_GPUStencilOp |
- Since
- This enum is available since SDL 3.2.0.
◆ GPUStencilOpState
| using SDL::GPUStencilOpState = typedef SDL_GPUStencilOpState |
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUDepthStencilState
◆ GPUStorageBufferReadWriteBinding
| using SDL::GPUStorageBufferReadWriteBinding = typedef SDL_GPUStorageBufferReadWriteBinding |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUStorageTextureReadWriteBinding
| using SDL::GPUStorageTextureReadWriteBinding = typedef SDL_GPUStorageTextureReadWriteBinding |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUStoreOp
| using SDL::GPUStoreOp = typedef SDL_GPUStoreOp |
- Since
- This enum is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.BeginRenderPass
◆ GPUSwapchainComposition
| using SDL::GPUSwapchainComposition = typedef SDL_GPUSwapchainComposition |
SDR will always be supported. Other compositions may not be supported on certain systems.
It is recommended to query GPUDevice.WindowSupportsSwapchainComposition after claiming the window if you wish to change the swapchain composition from SDR.
- SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding.
- SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are stored in memory in sRGB encoding but accessed in shaders in "linear sRGB" encoding which is sRGB but with a linear transfer function.
- HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in extended linear sRGB encoding and permits values outside of the [0, 1] range.
- HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in BT.2020 ST2084 (PQ) encoding.
- Since
- This enum is available since SDL 3.2.0.
◆ GPUTextureCreateInfo
| using SDL::GPUTextureCreateInfo = typedef SDL_GPUTextureCreateInfo |
Usage flags can be bitwise OR'd together for combinations of usages. Note that certain usage combinations are invalid, for example SAMPLER and GRAPHICS_STORAGE.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUTextureFormat
| using SDL::GPUTextureFormat = typedef SDL_GPUTextureFormat |
Texture format support varies depending on driver, hardware, and usage flags. In general, you should use GPUDevice.TextureSupportsFormat to query if a format is supported before using it. However, there are a few guaranteed formats.
FIXME: Check universal support for 32-bit component formats FIXME: Check universal support for SIMULTANEOUS_READ_WRITE
For SAMPLER usage, the following formats are universally supported:
- R8G8B8A8_UNORM
- B8G8R8A8_UNORM
- R8_UNORM
- R8_SNORM
- R8G8_UNORM
- R8G8_SNORM
- R8G8B8A8_SNORM
- R16_FLOAT
- R16G16_FLOAT
- R16G16B16A16_FLOAT
- R32_FLOAT
- R32G32_FLOAT
- R32G32B32A32_FLOAT
- R11G11B10_UFLOAT
- R8G8B8A8_UNORM_SRGB
- B8G8R8A8_UNORM_SRGB
- D16_UNORM
For COLOR_TARGET usage, the following formats are universally supported:
- R8G8B8A8_UNORM
- B8G8R8A8_UNORM
- R8_UNORM
- R16_FLOAT
- R16G16_FLOAT
- R16G16B16A16_FLOAT
- R32_FLOAT
- R32G32_FLOAT
- R32G32B32A32_FLOAT
- R8_UINT
- R8G8_UINT
- R8G8B8A8_UINT
- R16_UINT
- R16G16_UINT
- R16G16B16A16_UINT
- R8_INT
- R8G8_INT
- R8G8B8A8_INT
- R16_INT
- R16G16_INT
- R16G16B16A16_INT
- R8G8B8A8_UNORM_SRGB
- B8G8R8A8_UNORM_SRGB
For STORAGE usages, the following formats are universally supported:
- R8G8B8A8_UNORM
- R8G8B8A8_SNORM
- R16G16B16A16_FLOAT
- R32_FLOAT
- R32G32_FLOAT
- R32G32B32A32_FLOAT
- R8G8B8A8_UINT
- R16G16B16A16_UINT
- R8G8B8A8_INT
- R16G16B16A16_INT
For DEPTH_STENCIL_TARGET usage, the following formats are universally supported:
- D16_UNORM
- Either (but not necessarily both!) D24_UNORM or D32_FLOAT
- Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT
Unless D16_UNORM is sufficient for your purposes, always check which of D24/D32 is supported before creating a depth-stencil texture!
- Since
- This enum is available since SDL 3.2.0.
◆ GPUTextureLocation
| using SDL::GPUTextureLocation = typedef SDL_GPUTextureLocation |
Used when copying data from one texture to another.
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUCopyPass.CopyTextureToTexture
◆ GPUTextureRegion
| using SDL::GPUTextureRegion = typedef SDL_GPUTextureRegion |
Used when transferring data to or from a texture.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUTextureSamplerBinding
| using SDL::GPUTextureSamplerBinding = typedef SDL_GPUTextureSamplerBinding |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUTextureTransferInfo
| using SDL::GPUTextureTransferInfo = typedef SDL_GPUTextureTransferInfo |
If either of pixels_per_row or rows_per_layer is zero, then width and height of passed GPUTextureRegion to GPUCopyPass.UploadToTexture or GPUCopyPass.DownloadFromTexture are used as default values respectively and data is considered to be tightly packed.
WARNING: Direct3D 12 requires texture data row pitch to be 256 byte aligned, and offsets to be aligned to 512 bytes. If they are not, SDL will make a temporary copy of the data that is properly aligned, but this adds overhead to the transfer process. Apps can avoid this by aligning their data appropriately, or using a different GPU backend than Direct3D 12.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUTextureType
| using SDL::GPUTextureType = typedef SDL_GPUTextureType |
- Since
- This enum is available since SDL 3.2.0.
- See also
- GPUTexture.GPUTexture
◆ GPUTextureUsageFlags
| using SDL::GPUTextureUsageFlags = typedef Uint32 |
A texture must have at least one usage flag. Note that some usage flag combinations are invalid.
With regards to compute storage usage, READ | WRITE means that you can have shader A that only writes into the texture and shader B that only reads from the texture and bind the same texture to either shader respectively. SIMULTANEOUS means that you can do reads and writes within the same shader or compute pass. It also implies that atomic ops can be used, since those are read-modify-write operations. If you use SIMULTANEOUS, you are responsible for avoiding data races, as there is no data synchronization within a compute pass. Note that SIMULTANEOUS usage is only supported by a limited number of texture formats.
- Since
- This datatype is available since SDL 3.2.0.
- See also
- GPUTexture.GPUTexture
◆ GPUTransferBufferCreateInfo
| using SDL::GPUTransferBufferCreateInfo = typedef SDL_GPUTransferBufferCreateInfo |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUTransferBufferLocation
| using SDL::GPUTransferBufferLocation = typedef SDL_GPUTransferBufferLocation |
Used when transferring buffer data to or from a transfer buffer.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUTransferBufferUsage
| using SDL::GPUTransferBufferUsage = typedef SDL_GPUTransferBufferUsage |
Note that mapping and copying FROM an upload transfer buffer or TO a download transfer buffer is undefined behavior.
- Since
- This enum is available since SDL 3.2.0.
◆ GPUVertexAttribute
| using SDL::GPUVertexAttribute = typedef SDL_GPUVertexAttribute |
All vertex attribute locations provided to an GPUVertexInputState must be unique.
- Since
- This struct is available since SDL 3.2.0.
◆ GPUVertexBufferDescription
| using SDL::GPUVertexBufferDescription = typedef SDL_GPUVertexBufferDescription |
When you call GPURenderPass.BindVertexBuffers, you specify the binding slots of the vertex buffers. For example if you called GPURenderPass.BindVertexBuffers with a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be used by the vertex buffers you pass in.
Vertex attributes are linked to buffers via the buffer_slot field of GPUVertexAttribute. For example, if an attribute has a buffer_slot of 0, then that attribute belongs to the vertex buffer bound at slot 0.
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPUVertexAttribute
- GPUVertexInputRate
◆ GPUVertexElementFormat
| using SDL::GPUVertexElementFormat = typedef SDL_GPUVertexElementFormat |
- Since
- This enum is available since SDL 3.2.0.
◆ GPUVertexInputRate
| using SDL::GPUVertexInputRate = typedef SDL_GPUVertexInputRate |
- Since
- This enum is available since SDL 3.2.0.
◆ GPUVertexInputState
| using SDL::GPUVertexInputState = typedef SDL_GPUVertexInputState |
- Since
- This struct is available since SDL 3.2.0.
◆ GPUViewport
| using SDL::GPUViewport = typedef SDL_GPUViewport |
- Since
- This struct is available since SDL 3.2.0.
- See also
- GPURenderPass.SetViewport
◆ GPUVulkanOptions
| using SDL::GPUVulkanOptions = typedef SDL_GPUVulkanOptions |
When no such structure is provided, SDL will use Vulkan API version 1.0 and a minimal set of features. The requested API version influences how the feature_list is processed by SDL. When requesting API version 1.0, the feature_list is ignored. Only the vulkan_10_physical_device_features and the extension lists are used. When requesting API version 1.1, the feature_list is scanned for feature structures introduced in Vulkan 1.1. When requesting Vulkan 1.2 or higher, the feature_list is additionally scanned for compound feature structs such as VkPhysicalDeviceVulkan11Features. The device and instance extension lists, as well as vulkan_10_physical_device_features, are always processed.
- Since
- This struct is available since SDL 3.4.0.
Function Documentation
◆ AcquireCommandBuffer()
|
inline |
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.
- Returns
- a command buffer, or nullptr on failure; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ AcquireGPUCommandBuffer()
|
inline |
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.
- Parameters
-
device a GPU context.
- Returns
- a command buffer, or nullptr on failure; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ AcquireGPUSwapchainTexture()
|
inline |
When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it.
This function will fill the swapchain texture handle with nullptr if too many frames are in flight. This is not an error. This nullptr pointer should not be passed back into SDL. Instead, it should be considered as an indication to wait until the swapchain is available.
If you use this function, it is possible to create a situation where many command buffers are allocated while the rendering context waits for the GPU to catch up, which will cause memory usage to grow. You should use GPUCommandBuffer.WaitAndAcquireSwapchainTexture() unless you know what you are doing with timing.
The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this function from any thread other than the one that created the window.
- Parameters
-
command_buffer a command buffer. window a window that has been claimed. swapchain_texture_width a pointer filled in with the swapchain texture width, may be nullptr. swapchain_texture_height a pointer filled in with the swapchain texture height, may be nullptr.
- Returns
- a swapchain texture handle.
- Exceptions
-
Error on failure.
- Thread safety:
- This function should only be called from the thread that created the window.
- Since
- This function is available since SDL 3.2.0.
◆ AcquireSwapchainTexture()
|
inline |
When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it.
This function will fill the swapchain texture handle with nullptr if too many frames are in flight. This is not an error. This nullptr pointer should not be passed back into SDL. Instead, it should be considered as an indication to wait until the swapchain is available.
If you use this function, it is possible to create a situation where many command buffers are allocated while the rendering context waits for the GPU to catch up, which will cause memory usage to grow. You should use GPUCommandBuffer.WaitAndAcquireSwapchainTexture() unless you know what you are doing with timing.
The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this function from any thread other than the one that created the window.
- Parameters
-
window a window that has been claimed. swapchain_texture_width a pointer filled in with the swapchain texture width, may be nullptr. swapchain_texture_height a pointer filled in with the swapchain texture height, may be nullptr.
- Returns
- a swapchain texture handle.
- Exceptions
-
Error on failure.
- Thread safety:
- This function should only be called from the thread that created the window.
- Since
- This function is available since SDL 3.2.0.
◆ BeginComputePass()
|
inline |
A compute pass is defined by a set of texture subresources and buffers that may be written to by compute pipelines. These textures and buffers must have been created with the COMPUTE_STORAGE_WRITE bit or the COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the texture in the compute pass. All operations related to compute pipelines must take place inside of a compute pass. You must not begin another compute pass, or a render pass or copy pass before ending the compute pass.
A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT implicitly synchronized. This means you may cause data races by both reading and writing a resource region in a compute pass, or by writing multiple times to a resource region. If your compute work depends on reading the completed output from a previous dispatch, you MUST end the current compute pass and begin a new one before you can safely access the data. Otherwise you will receive unexpected results. Reading and writing a texture in the same compute pass is only supported by specific texture formats. Make sure you check the format support!
- Parameters
-
storage_texture_bindings an array of writeable storage texture binding structs. storage_buffer_bindings an array of writeable storage buffer binding structs.
- Returns
- a compute pass handle.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUComputePass.End
◆ BeginCopyPass()
|
inline |
All operations related to copying to or from buffers or textures take place inside a copy pass. You must not begin another copy pass, or a render pass or compute pass before ending the copy pass.
- Returns
- a copy pass handle.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCopyPass.End
◆ BeginGPUComputePass()
|
inline |
A compute pass is defined by a set of texture subresources and buffers that may be written to by compute pipelines. These textures and buffers must have been created with the COMPUTE_STORAGE_WRITE bit or the COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the texture in the compute pass. All operations related to compute pipelines must take place inside of a compute pass. You must not begin another compute pass, or a render pass or copy pass before ending the compute pass.
A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT implicitly synchronized. This means you may cause data races by both reading and writing a resource region in a compute pass, or by writing multiple times to a resource region. If your compute work depends on reading the completed output from a previous dispatch, you MUST end the current compute pass and begin a new one before you can safely access the data. Otherwise you will receive unexpected results. Reading and writing a texture in the same compute pass is only supported by specific texture formats. Make sure you check the format support!
- Parameters
-
command_buffer a command buffer. storage_texture_bindings an array of writeable storage texture binding structs. storage_buffer_bindings an array of writeable storage buffer binding structs.
- Returns
- a compute pass handle.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUComputePass.End
◆ BeginGPUCopyPass()
|
inline |
All operations related to copying to or from buffers or textures take place inside a copy pass. You must not begin another copy pass, or a render pass or compute pass before ending the copy pass.
- Parameters
-
command_buffer a command buffer.
- Returns
- a copy pass handle.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCopyPass.End
◆ BeginGPURenderPass()
|
inline |
A render pass consists of a set of texture subresources (or depth slices in the 3D texture case) which will be rendered to during the render pass, along with corresponding clear values and load/store operations. All operations related to graphics pipelines must take place inside of a render pass. A default viewport and scissor state are automatically set when this is called. You cannot begin another render pass, or begin a compute pass or copy pass until you have ended the render pass.
Using GPU_LOADOP_LOAD before any contents have been written to the texture subresource will result in undefined behavior. GPU_LOADOP_CLEAR will set the contents of the texture subresource to a single value before any rendering is performed. It's fine to do an empty render pass using GPU_STOREOP_STORE to clear a texture, but in general it's better to think of clearing not as an independent operation but as something that's done as the beginning of a render pass.
- Parameters
-
command_buffer a command buffer. color_target_infos an array of texture subresources with corresponding clear values and load/store ops. depth_stencil_target_info a texture subresource with corresponding clear value and load/store ops, may be nullptr.
- Returns
- a render pass handle.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPURenderPass.End
◆ BeginRenderPass()
|
inline |
A render pass consists of a set of texture subresources (or depth slices in the 3D texture case) which will be rendered to during the render pass, along with corresponding clear values and load/store operations. All operations related to graphics pipelines must take place inside of a render pass. A default viewport and scissor state are automatically set when this is called. You cannot begin another render pass, or begin a compute pass or copy pass until you have ended the render pass.
Using GPU_LOADOP_LOAD before any contents have been written to the texture subresource will result in undefined behavior. GPU_LOADOP_CLEAR will set the contents of the texture subresource to a single value before any rendering is performed. It's fine to do an empty render pass using GPU_STOREOP_STORE to clear a texture, but in general it's better to think of clearing not as an independent operation but as something that's done as the beginning of a render pass.
- Parameters
-
color_target_infos an array of texture subresources with corresponding clear values and load/store ops. depth_stencil_target_info a texture subresource with corresponding clear value and load/store ops, may be nullptr.
- Returns
- a render pass handle.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPURenderPass.End
◆ BindFragmentSamplers()
|
inline |
The textures must have been created with GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
first_slot the fragment sampler slot to begin binding from. texture_sampler_bindings an array of texture-sampler binding structs.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindFragmentStorageBuffers()
|
inline |
These buffers must have been created with GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
first_slot the fragment storage buffer slot to begin binding from. storage_buffers an array of storage buffers.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindFragmentStorageTextures()
|
inline |
These textures must have been created with GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
first_slot the fragment storage texture slot to begin binding from. storage_textures an array of storage textures.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindGPUComputePipeline()
|
inline |
- Parameters
-
compute_pass a compute pass handle. compute_pipeline a compute pipeline to bind.
- Since
- This function is available since SDL 3.2.0.
◆ BindGPUComputeSamplers()
|
inline |
The textures must have been created with GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in GPUComputePipeline.GPUComputePipeline().
- Parameters
-
compute_pass a compute pass handle. first_slot the compute sampler slot to begin binding from. texture_sampler_bindings an array of texture-sampler binding structs.
- Since
- This function is available since SDL 3.2.0.
◆ BindGPUComputeStorageBuffers()
|
inline |
These buffers must have been created with GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUComputePipeline.GPUComputePipeline().
- Parameters
-
compute_pass a compute pass handle. first_slot the compute storage buffer slot to begin binding from. storage_buffers an array of storage buffer binding structs.
- Since
- This function is available since SDL 3.2.0.
◆ BindGPUComputeStorageTextures()
|
inline |
These textures must have been created with GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUComputePipeline.GPUComputePipeline().
- Parameters
-
compute_pass a compute pass handle. first_slot the compute storage texture slot to begin binding from. storage_textures an array of storage textures.
- Since
- This function is available since SDL 3.2.0.
◆ BindGPUFragmentSamplers()
|
inline |
The textures must have been created with GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
render_pass a render pass handle. first_slot the fragment sampler slot to begin binding from. texture_sampler_bindings an array of texture-sampler binding structs.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindGPUFragmentStorageBuffers()
|
inline |
These buffers must have been created with GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
render_pass a render pass handle. first_slot the fragment storage buffer slot to begin binding from. storage_buffers an array of storage buffers.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindGPUFragmentStorageTextures()
|
inline |
These textures must have been created with GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
render_pass a render pass handle. first_slot the fragment storage texture slot to begin binding from. storage_textures an array of storage textures.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindGPUGraphicsPipeline()
|
inline |
A graphics pipeline must be bound before making any draw calls.
- Parameters
-
render_pass a render pass handle. graphics_pipeline the graphics pipeline to bind.
- Since
- This function is available since SDL 3.2.0.
◆ BindGPUIndexBuffer()
|
inline |
- Parameters
-
render_pass a render pass handle. binding a pointer to a struct containing an index buffer and offset. index_element_size whether the index values in the buffer are 16- or 32-bit.
- Since
- This function is available since SDL 3.2.0.
◆ BindGPUVertexBuffers()
|
inline |
- Parameters
-
render_pass a render pass handle. first_slot the vertex buffer slot to begin binding from. bindings an array of GPUBufferBinding structs containing vertex buffers and offset values.
- Since
- This function is available since SDL 3.2.0.
◆ BindGPUVertexSamplers()
|
inline |
The textures must have been created with GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
render_pass a render pass handle. first_slot the vertex sampler slot to begin binding from. texture_sampler_bindings an array of texture-sampler binding structs.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindGPUVertexStorageBuffers()
|
inline |
These buffers must have been created with GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
render_pass a render pass handle. first_slot the vertex storage buffer slot to begin binding from. storage_buffers an array of buffers.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindGPUVertexStorageTextures()
|
inline |
These textures must have been created with GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
render_pass a render pass handle. first_slot the vertex storage texture slot to begin binding from. storage_textures an array of storage textures.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindIndexBuffer()
|
inline |
- Parameters
-
binding a pointer to a struct containing an index buffer and offset. index_element_size whether the index values in the buffer are 16- or 32-bit.
- Since
- This function is available since SDL 3.2.0.
◆ BindPipeline() [1/2]
|
inline |
- Parameters
-
compute_pipeline a compute pipeline to bind.
- Since
- This function is available since SDL 3.2.0.
◆ BindPipeline() [2/2]
|
inline |
A graphics pipeline must be bound before making any draw calls.
- Parameters
-
graphics_pipeline the graphics pipeline to bind.
- Since
- This function is available since SDL 3.2.0.
◆ BindSamplers()
|
inline |
The textures must have been created with GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in GPUComputePipeline.GPUComputePipeline().
- Parameters
-
first_slot the compute sampler slot to begin binding from. texture_sampler_bindings an array of texture-sampler binding structs.
- Since
- This function is available since SDL 3.2.0.
◆ BindStorageBuffers()
|
inline |
These buffers must have been created with GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUComputePipeline.GPUComputePipeline().
- Parameters
-
first_slot the compute storage buffer slot to begin binding from. storage_buffers an array of storage buffer binding structs.
- Since
- This function is available since SDL 3.2.0.
◆ BindStorageTextures()
|
inline |
These textures must have been created with GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUComputePipeline.GPUComputePipeline().
- Parameters
-
first_slot the compute storage texture slot to begin binding from. storage_textures an array of storage textures.
- Since
- This function is available since SDL 3.2.0.
◆ BindVertexBuffers()
|
inline |
- Parameters
-
first_slot the vertex buffer slot to begin binding from. bindings an array of GPUBufferBinding structs containing vertex buffers and offset values.
- Since
- This function is available since SDL 3.2.0.
◆ BindVertexSamplers()
|
inline |
The textures must have been created with GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
first_slot the vertex sampler slot to begin binding from. texture_sampler_bindings an array of texture-sampler binding structs.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindVertexStorageBuffers()
|
inline |
These buffers must have been created with GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
first_slot the vertex storage buffer slot to begin binding from. storage_buffers an array of buffers.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BindVertexStorageTextures()
|
inline |
These textures must have been created with GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in GPUShader.GPUShader().
- Parameters
-
first_slot the vertex storage texture slot to begin binding from. storage_textures an array of storage textures.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUShader.GPUShader
◆ BlitGPUTexture()
|
inline |
This function must not be called inside of any pass.
- Parameters
-
command_buffer a command buffer. info the blit info struct containing the blit parameters.
- Since
- This function is available since SDL 3.2.0.
◆ BlitTexture()
|
inline |
This function must not be called inside of any pass.
- Parameters
-
info the blit info struct containing the blit parameters.
- Since
- This function is available since SDL 3.2.0.
◆ CalculateGPUTextureFormatSize()
|
inline |
- Parameters
-
format a texture format. width width in pixels. height height in pixels. depth_or_layer_count depth for 3D textures or layer count otherwise.
- Returns
- the size of a texture with this format and dimensions.
- Since
- This function is available since SDL 3.2.0.
◆ Cancel()
|
inline |
None of the enqueued commands are executed.
It is an error to call this function after a swapchain texture has been acquired.
This must be called from the thread the command buffer was acquired on.
You must not reference the command buffer after calling this function.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CancelGPUCommandBuffer()
|
inline |
None of the enqueued commands are executed.
It is an error to call this function after a swapchain texture has been acquired.
This must be called from the thread the command buffer was acquired on.
You must not reference the command buffer after calling this function.
- Parameters
-
command_buffer a command buffer.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ ClaimWindow()
|
inline |
This must be called before GPUCommandBuffer.AcquireSwapchainTexture is called using the window. You should only call this function from the thread that created the window.
The swapchain will be created with GPU_SWAPCHAINCOMPOSITION_SDR and GPU_PRESENTMODE_VSYNC. If you want to have different swapchain parameters, you must call GPUDevice.SetSwapchainParameters after claiming the window.
- Parameters
-
window an Window.
- Exceptions
-
Error on failure.
- Thread safety:
- This function should only be called from the thread that created the window.
- Since
- This function is available since SDL 3.2.0.
◆ ClaimWindowForGPUDevice()
|
inline |
This must be called before GPUCommandBuffer.AcquireSwapchainTexture is called using the window. You should only call this function from the thread that created the window.
The swapchain will be created with GPU_SWAPCHAINCOMPOSITION_SDR and GPU_PRESENTMODE_VSYNC. If you want to have different swapchain parameters, you must call GPUDevice.SetSwapchainParameters after claiming the window.
- Parameters
-
device a GPU context. window an Window.
- Exceptions
-
Error on failure.
- Thread safety:
- This function should only be called from the thread that created the window.
- Since
- This function is available since SDL 3.2.0.
◆ CopyBufferToBuffer()
|
inline |
This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.
- Parameters
-
source the buffer and offset to copy from. destination the buffer and offset to copy to. size the length of the buffer to copy. cycle if true, cycles the destination buffer if it is already bound, otherwise overwrites the data.
- Since
- This function is available since SDL 3.2.0.
◆ CopyGPUBufferToBuffer()
|
inline |
This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.
- Parameters
-
copy_pass a copy pass handle. source the buffer and offset to copy from. destination the buffer and offset to copy to. size the length of the buffer to copy. cycle if true, cycles the destination buffer if it is already bound, otherwise overwrites the data.
- Since
- This function is available since SDL 3.2.0.
◆ CopyGPUTextureToTexture()
|
inline |
This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.
This function does not support copying between depth and color textures. For those, copy the texture to a buffer and then to the destination texture.
- Parameters
-
copy_pass a copy pass handle. source a source texture region. destination a destination texture region. w the width of the region to copy. h the height of the region to copy. d the depth of the region to copy. cycle if true, cycles the destination texture if the destination texture is bound, otherwise overwrites the data.
- Since
- This function is available since SDL 3.2.0.
◆ CopyTextureToTexture()
|
inline |
This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.
This function does not support copying between depth and color textures. For those, copy the texture to a buffer and then to the destination texture.
- Parameters
-
source a source texture region. destination a destination texture region. w the width of the region to copy. h the height of the region to copy. d the depth of the region to copy. cycle if true, cycles the destination texture if the destination texture is bound, otherwise overwrites the data.
- Since
- This function is available since SDL 3.2.0.
◆ CreateBuffer()
|
inline |
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:
prop::GPUBuffer.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
createinfo a struct describing the state of the buffer to create.
- Returns
- a buffer object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCopyPass.UploadToBuffer
- GPUCopyPass.DownloadFromBuffer
- GPUCopyPass.CopyBufferToBuffer
- GPURenderPass.BindVertexBuffers
- GPURenderPass.BindIndexBuffer
- GPURenderPass.BindVertexStorageBuffers
- GPURenderPass.BindFragmentStorageBuffers
- GPURenderPass.DrawPrimitivesIndirect
- GPURenderPass.DrawIndexedPrimitivesIndirect
- GPUComputePass.BindStorageBuffers
- GPUComputePass.DispatchIndirect
- GPUDevice.ReleaseBuffer
◆ CreateComputePipeline()
|
inline |
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:
prop::GPUComputePipeline.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
createinfo a struct describing the state of the compute pipeline to create.
- Returns
- a compute pipeline object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateGPUBuffer()
|
inline |
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:
prop::GPUBuffer.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
device a GPU Context. createinfo a struct describing the state of the buffer to create.
- Returns
- a buffer object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCopyPass.UploadToBuffer
- GPUCopyPass.DownloadFromBuffer
- GPUCopyPass.CopyBufferToBuffer
- GPURenderPass.BindVertexBuffers
- GPURenderPass.BindIndexBuffer
- GPURenderPass.BindVertexStorageBuffers
- GPURenderPass.BindFragmentStorageBuffers
- GPURenderPass.DrawPrimitivesIndirect
- GPURenderPass.DrawIndexedPrimitivesIndirect
- GPUComputePass.BindStorageBuffers
- GPUComputePass.DispatchIndirect
- GPUDevice.ReleaseBuffer
◆ CreateGPUComputePipeline()
|
inline |
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:
prop::GPUComputePipeline.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
device a GPU Context. createinfo a struct describing the state of the compute pipeline to create.
- Returns
- a compute pipeline object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateGPUDevice()
|
inline |
The GPU driver name can be one of the following:
- Parameters
-
format_flags a bitflag indicating which shader formats the app is able to provide. debug_mode enable debug mode properties and validations. name the preferred GPU driver, or nullptr to let SDL pick the optimal driver.
- Returns
- a GPU context on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateGPUDeviceWithProperties()
|
inline |
These are the supported properties:
prop::GpuDevice.CREATE_DEBUGMODE_BOOLEAN: enable debug mode properties and validations, defaults to true.prop::GpuDevice.CREATE_PREFERLOWPOWER_BOOLEAN: enable to prefer energy efficiency over maximum GPU performance, defaults to false.prop::GpuDevice.CREATE_VERBOSE_BOOLEAN: enable to automatically log useful debug information on device creation, defaults to true.prop::GpuDevice.CREATE_NAME_STRING: the name of the GPU driver to use, if a specific one is desired.prop::GpuDevice.CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN: Enable Vulkan device feature shaderClipDistance. If disabled, clip distances are not supported in shader code: gl_ClipDistance[] built-ins of GLSL, SV_ClipDistance0/1 semantics of HLSL and [[clip_distance]] attribute of Metal. Disabling optional features allows the application to run on some older Android devices. Defaults to true.prop::GpuDevice.CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN: Enable Vulkan device feature depthClamp. If disabled, there is no depth clamp support and enable_depth_clip in GPURasterizerState must always be set to true. Disabling optional features allows the application to run on some older Android devices. Defaults to true.prop::GpuDevice.CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN: Enable Vulkan device feature drawIndirectFirstInstance. If disabled, the argument first_instance of GPUIndirectDrawCommand must be set to zero. Disabling optional features allows the application to run on some older Android devices. Defaults to true.prop::GpuDevice.CREATE_FEATURE_ANISOTROPY_BOOLEAN: Enable Vulkan device feature samplerAnisotropy. If disabled, enable_anisotropy of GPUSamplerCreateInfo must be set to false. Disabling optional features allows the application to run on some older Android devices. Defaults to true.
These are the current shader format properties:
prop::GpuDevice.CREATE_SHADERS_PRIVATE_BOOLEAN: The app is able to provide shaders for an NDA platform.prop::GpuDevice.CREATE_SHADERS_SPIRV_BOOLEAN: The app is able to provide SPIR-V shaders if applicable.prop::GpuDevice.CREATE_SHADERS_DXBC_BOOLEAN: The app is able to provide DXBC shaders if applicableprop::GpuDevice.CREATE_SHADERS_DXIL_BOOLEAN: The app is able to provide DXIL shaders if applicable.prop::GpuDevice.CREATE_SHADERS_MSL_BOOLEAN: The app is able to provide MSL shaders if applicable.prop::GpuDevice.CREATE_SHADERS_METALLIB_BOOLEAN: The app is able to provide Metal shader libraries if applicable.
With the D3D12 backend:
prop::GpuDevice.CREATE_D3D12_SEMANTIC_NAME_STRING: the prefix to use for all vertex semantics, default is "TEXCOORD".prop::GpuDevice.CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN: By default, Resourcing Binding Tier 2 is required for D3D12 support. However, an application can set this property to true to enable Tier 1 support, if (and only if) the application uses 8 or fewer storage resources across all shader stages. As of writing, this property is useful for targeting Intel Haswell and Broadwell GPUs; other hardware either supports Tier 2 Resource Binding or does not support D3D12 in any capacity. Defaults to false.
With the Vulkan backend:
prop::GpuDevice.CREATE_VULKAN_REQUIRE_HARDWARE_ACCELERATION_BOOLEAN: By default, Vulkan device enumeration includes drivers of all types, including software renderers (for example, the Lavapipe Mesa driver). This can be useful if your application requires SDL_GPU, but if you can provide your own fallback renderer (for example, an OpenGL renderer) this property can be set to true. Defaults to false.prop::GpuDevice.CREATE_VULKAN_OPTIONS_POINTER: a pointer to an GPUVulkanOptions structure to be processed during device creation. This allows configuring a variety of Vulkan-specific options such as increasing the API version and opting into extensions aside from the minimal set SDL requires.
- Parameters
-
props the properties to use.
- Returns
- a GPU context on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateGPUGraphicsPipeline()
|
inline |
There are optional properties that can be provided through props. These are the supported properties:
prop::GPUGraphicsPipeline.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
device a GPU Context. createinfo a struct describing the state of the graphics pipeline to create.
- Returns
- a graphics pipeline object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateGPUSampler()
|
inline |
There are optional properties that can be provided through props. These are the supported properties:
prop::GPUSampler.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
device a GPU Context. createinfo a struct describing the state of the sampler to create.
- Returns
- a sampler object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateGPUShader()
|
inline |
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 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 prop::GpuDevice.CREATE_D3D12_SEMANTIC_NAME_STRING with GPUDevice.GPUDevice().
There are optional properties that can be provided through props. These are the supported properties:
prop::GPUShader.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
device a GPU Context. createinfo a struct describing the state of the shader to create.
- Returns
- a shader object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateGPUTexture()
|
inline |
The contents of this texture are undefined until data is written to the texture, either via GPUCopyPass.UploadToTexture or by performing a render or compute pass with this texture as a target.
Note that certain combinations of usage flags are invalid. For example, a texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ 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 GPUTextureCreateInfo's props. These are the supported properties:
prop::GPUTexture.CREATE_D3D12_CLEAR_R_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this red intensity. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_G_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this green intensity. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_B_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this blue intensity. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_A_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this alpha intensity. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_DEPTH_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear the texture to a depth of this value. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_STENCIL_NUMBER: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear the texture to a stencil of this Uint8 value. Defaults to zero.prop::GPUTexture.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
device a GPU Context. createinfo a struct describing the state of the texture to create.
- Returns
- a texture object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCopyPass.UploadToTexture
- GPUCopyPass.DownloadFromTexture
- GPUCommandBuffer.BeginRenderPass
- GPUCommandBuffer.BeginComputePass
- GPURenderPass.BindVertexSamplers
- GPURenderPass.BindVertexStorageTextures
- GPURenderPass.BindFragmentSamplers
- GPURenderPass.BindFragmentStorageTextures
- GPUComputePass.BindStorageTextures
- GPUCommandBuffer.BlitTexture
- GPUDevice.ReleaseTexture
- GPUDevice.TextureSupportsFormat
◆ CreateGPUTransferBuffer()
|
inline |
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:
prop::GPUTransferBuffer.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
device a GPU Context. createinfo a struct describing the state of the transfer buffer to create.
- Returns
- a transfer buffer on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateGraphicsPipeline()
|
inline |
There are optional properties that can be provided through props. These are the supported properties:
prop::GPUGraphicsPipeline.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
createinfo a struct describing the state of the graphics pipeline to create.
- Returns
- a graphics pipeline object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateSampler()
|
inline |
There are optional properties that can be provided through props. These are the supported properties:
prop::GPUSampler.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
createinfo a struct describing the state of the sampler to create.
- Returns
- a sampler object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateShader()
|
inline |
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 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 prop::GpuDevice.CREATE_D3D12_SEMANTIC_NAME_STRING with GPUDevice.GPUDevice().
There are optional properties that can be provided through props. These are the supported properties:
prop::GPUShader.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
createinfo a struct describing the state of the shader to create.
- Returns
- a shader object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ CreateTexture()
|
inline |
The contents of this texture are undefined until data is written to the texture, either via GPUCopyPass.UploadToTexture or by performing a render or compute pass with this texture as a target.
Note that certain combinations of usage flags are invalid. For example, a texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ 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 GPUTextureCreateInfo's props. These are the supported properties:
prop::GPUTexture.CREATE_D3D12_CLEAR_R_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this red intensity. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_G_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this green intensity. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_B_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this blue intensity. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_A_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this alpha intensity. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_DEPTH_FLOAT: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear the texture to a depth of this value. Defaults to zero.prop::GPUTexture.CREATE_D3D12_CLEAR_STENCIL_NUMBER: (Direct3D 12 only) if the texture usage is GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear the texture to a stencil of this Uint8 value. Defaults to zero.prop::GPUTexture.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
createinfo a struct describing the state of the texture to create.
- Returns
- a texture object on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCopyPass.UploadToTexture
- GPUCopyPass.DownloadFromTexture
- GPUCommandBuffer.BeginRenderPass
- GPUCommandBuffer.BeginComputePass
- GPURenderPass.BindVertexSamplers
- GPURenderPass.BindVertexStorageTextures
- GPURenderPass.BindFragmentSamplers
- GPURenderPass.BindFragmentStorageTextures
- GPUComputePass.BindStorageTextures
- GPUCommandBuffer.BlitTexture
- GPUDevice.ReleaseTexture
- GPUDevice.TextureSupportsFormat
◆ CreateTransferBuffer()
|
inline |
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:
prop::GPUTransferBuffer.CREATE_NAME_STRING: a name that can be displayed in debugging tools.
- Parameters
-
createinfo a struct describing the state of the transfer buffer to create.
- Returns
- a transfer buffer on success.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ Destroy()
|
inline |
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.GPUDevice
◆ DestroyGPUDevice()
|
inline |
- Parameters
-
device a GPU Context to destroy.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.GPUDevice
◆ Dispatch()
|
inline |
You must not call this function before binding a compute pipeline.
A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and the dispatches write to the same resource region as each other, there is no guarantee of which order the writes will occur. If the write order matters, you MUST end the compute pass and begin another one.
- Parameters
-
groupcount_x number of local workgroups to dispatch in the X dimension. groupcount_y number of local workgroups to dispatch in the Y dimension. groupcount_z number of local workgroups to dispatch in the Z dimension.
- Since
- This function is available since SDL 3.2.0.
◆ DispatchGPUCompute()
|
inline |
You must not call this function before binding a compute pipeline.
A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and the dispatches write to the same resource region as each other, there is no guarantee of which order the writes will occur. If the write order matters, you MUST end the compute pass and begin another one.
- Parameters
-
compute_pass a compute pass handle. groupcount_x number of local workgroups to dispatch in the X dimension. groupcount_y number of local workgroups to dispatch in the Y dimension. groupcount_z number of local workgroups to dispatch in the Z dimension.
- Since
- This function is available since SDL 3.2.0.
◆ DispatchGPUComputeIndirect()
|
inline |
The buffer layout should match the layout of GPUIndirectDispatchCommand. You must not call this function before binding a compute pipeline.
A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and the dispatches write to the same resource region as each other, there is no guarantee of which order the writes will occur. If the write order matters, you MUST end the compute pass and begin another one.
- Parameters
-
compute_pass a compute pass handle. buffer a buffer containing dispatch parameters. offset the offset to start reading from the dispatch buffer.
- Since
- This function is available since SDL 3.2.0.
◆ DispatchIndirect()
The buffer layout should match the layout of GPUIndirectDispatchCommand. You must not call this function before binding a compute pipeline.
A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and the dispatches write to the same resource region as each other, there is no guarantee of which order the writes will occur. If the write order matters, you MUST end the compute pass and begin another one.
- Parameters
-
buffer a buffer containing dispatch parameters. offset the offset to start reading from the dispatch buffer.
- Since
- This function is available since SDL 3.2.0.
◆ DownloadFromBuffer()
|
inline |
This data is not guaranteed to be copied until the command buffer fence is signaled.
- Parameters
-
source the source buffer with offset and size. destination the destination transfer buffer with offset.
- Since
- This function is available since SDL 3.2.0.
◆ DownloadFromGPUBuffer()
|
inline |
This data is not guaranteed to be copied until the command buffer fence is signaled.
- Parameters
-
copy_pass a copy pass handle. source the source buffer with offset and size. destination the destination transfer buffer with offset.
- Since
- This function is available since SDL 3.2.0.
◆ DownloadFromGPUTexture()
|
inline |
This data is not guaranteed to be copied until the command buffer fence is signaled.
- Parameters
-
copy_pass a copy pass handle. source the source texture region. destination the destination transfer buffer with image layout information.
- Since
- This function is available since SDL 3.2.0.
◆ DownloadFromTexture()
|
inline |
This data is not guaranteed to be copied until the command buffer fence is signaled.
- Parameters
-
source the source texture region. destination the destination transfer buffer with image layout information.
- Since
- This function is available since SDL 3.2.0.
◆ DrawGPUIndexedPrimitives()
|
inline |
You must not call this function before binding a graphics pipeline.
Note that the first_vertex and first_instance parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID); GPU APIs and shader languages do not define these built-in variables consistently, so if your shader depends on them, the only way to keep behavior consistent and portable is to always pass 0 for the correlating parameter in the draw calls.
- Parameters
-
render_pass a render pass handle. num_indices the number of indices to draw per instance. num_instances the number of instances to draw. first_index the starting index within the index buffer. vertex_offset value added to vertex index before indexing into the vertex buffer. first_instance the ID of the first instance to draw.
- Since
- This function is available since SDL 3.2.0.
◆ DrawGPUIndexedPrimitivesIndirect()
|
inline |
The buffer must consist of tightly-packed draw parameter sets that each match the layout of GPUIndexedIndirectDrawCommand. You must not call this function before binding a graphics pipeline.
- Parameters
-
render_pass a render pass handle. buffer a buffer containing draw parameters. offset the offset to start reading from the draw buffer. draw_count the number of draw parameter sets that should be read from the draw buffer.
- Since
- This function is available since SDL 3.2.0.
◆ DrawGPUPrimitives()
|
inline |
You must not call this function before binding a graphics pipeline.
Note that the first_vertex and first_instance parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID); GPU APIs and shader languages do not define these built-in variables consistently, so if your shader depends on them, the only way to keep behavior consistent and portable is to always pass 0 for the correlating parameter in the draw calls.
- Parameters
-
render_pass a render pass handle. num_vertices the number of vertices to draw. num_instances the number of instances that will be drawn. first_vertex the index of the first vertex to draw. first_instance the ID of the first instance to draw.
- Since
- This function is available since SDL 3.2.0.
◆ DrawGPUPrimitivesIndirect()
|
inline |
The buffer must consist of tightly-packed draw parameter sets that each match the layout of GPUIndirectDrawCommand. You must not call this function before binding a graphics pipeline.
- Parameters
-
render_pass a render pass handle. buffer a buffer containing draw parameters. offset the offset to start reading from the draw buffer. draw_count the number of draw parameter sets that should be read from the draw buffer.
- Since
- This function is available since SDL 3.2.0.
◆ DrawIndexedPrimitives()
|
inline |
You must not call this function before binding a graphics pipeline.
Note that the first_vertex and first_instance parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID); GPU APIs and shader languages do not define these built-in variables consistently, so if your shader depends on them, the only way to keep behavior consistent and portable is to always pass 0 for the correlating parameter in the draw calls.
- Parameters
-
num_indices the number of indices to draw per instance. num_instances the number of instances to draw. first_index the starting index within the index buffer. vertex_offset value added to vertex index before indexing into the vertex buffer. first_instance the ID of the first instance to draw.
- Since
- This function is available since SDL 3.2.0.
◆ DrawIndexedPrimitivesIndirect()
|
inline |
The buffer must consist of tightly-packed draw parameter sets that each match the layout of GPUIndexedIndirectDrawCommand. You must not call this function before binding a graphics pipeline.
- Parameters
-
buffer a buffer containing draw parameters. offset the offset to start reading from the draw buffer. draw_count the number of draw parameter sets that should be read from the draw buffer.
- Since
- This function is available since SDL 3.2.0.
◆ DrawPrimitives()
|
inline |
You must not call this function before binding a graphics pipeline.
Note that the first_vertex and first_instance parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID); GPU APIs and shader languages do not define these built-in variables consistently, so if your shader depends on them, the only way to keep behavior consistent and portable is to always pass 0 for the correlating parameter in the draw calls.
- Parameters
-
num_vertices the number of vertices to draw. num_instances the number of instances that will be drawn. first_vertex the index of the first vertex to draw. first_instance the ID of the first instance to draw.
- Since
- This function is available since SDL 3.2.0.
◆ DrawPrimitivesIndirect()
|
inline |
The buffer must consist of tightly-packed draw parameter sets that each match the layout of GPUIndirectDrawCommand. You must not call this function before binding a graphics pipeline.
- Parameters
-
buffer a buffer containing draw parameters. offset the offset to start reading from the draw buffer. draw_count the number of draw parameter sets that should be read from the draw buffer.
- Since
- This function is available since SDL 3.2.0.
◆ End() [1/3]
|
inline |
All bound graphics state on the render pass command buffer is unset. The render pass handle is now invalid.
- Since
- This function is available since SDL 3.2.0.
◆ End() [2/3]
|
inline |
All bound compute state on the command buffer is unset. The compute pass handle is now invalid.
- Since
- This function is available since SDL 3.2.0.
◆ End() [3/3]
|
inline |
- Since
- This function is available since SDL 3.2.0.
◆ EndGPUComputePass()
|
inline |
All bound compute state on the command buffer is unset. The compute pass handle is now invalid.
- Parameters
-
compute_pass a compute pass handle.
- Since
- This function is available since SDL 3.2.0.
◆ EndGPUCopyPass()
|
inline |
- Parameters
-
copy_pass a copy pass handle.
- Since
- This function is available since SDL 3.2.0.
◆ EndGPURenderPass()
|
inline |
All bound graphics state on the render pass command buffer is unset. The render pass handle is now invalid.
- Parameters
-
render_pass a render pass handle.
- Since
- This function is available since SDL 3.2.0.
◆ GDKResumeGPU() [1/2]
|
inline |
When resuming, this function MUST be called before calling any other SDL_GPU functions.
- Since
- This function is available since SDL 3.2.0.
- See also
- AddEventWatch
◆ GDKResumeGPU() [2/2]
|
inline |
When resuming, this function MUST be called before calling any other SDL_GPU functions.
- Parameters
-
device a GPU context.
- Since
- This function is available since SDL 3.2.0.
- See also
- AddEventWatch
◆ GDKSuspendGPU() [1/2]
|
inline |
Do NOT call any SDL_GPU functions after calling this function! This must also be called before calling GDKSuspendComplete.
- Since
- This function is available since SDL 3.2.0.
- See also
- AddEventWatch
◆ GDKSuspendGPU() [2/2]
|
inline |
Do NOT call any SDL_GPU functions after calling this function! This must also be called before calling GDKSuspendComplete.
- Parameters
-
device a GPU context.
- Since
- This function is available since SDL 3.2.0.
- See also
- AddEventWatch
◆ GenerateMipmapsForGPUTexture()
|
inline |
This function must not be called inside of any pass.
- Parameters
-
command_buffer a command_buffer. texture a texture with more than 1 mip level.
- Since
- This function is available since SDL 3.2.0.
◆ GenerateMipmapsForTexture()
|
inline |
This function must not be called inside of any pass.
- Parameters
-
texture a texture with more than 1 mip level.
- Since
- This function is available since SDL 3.2.0.
◆ GetDriver()
|
inline |
- Returns
- the name of the device's driver, or nullptr on error.
- Since
- This function is available since SDL 3.2.0.
◆ GetGPUDeviceDriver()
|
inline |
- Parameters
-
device a GPU context to query.
- Returns
- the name of the device's driver, or nullptr on error.
- Since
- This function is available since SDL 3.2.0.
◆ GetGPUDeviceProperties()
|
inline |
All properties are optional and may differ between GPU backends and SDL versions.
The following properties are provided by SDL:
prop::GpuDevice.NAME_STRING: Contains the name of the underlying device as reported by the system driver. This string has no standardized format, is highly inconsistent between hardware devices and drivers, and is able to change at any time. Do not attempt to parse this string as it is bound to fail at some point in the future when system drivers are updated, new hardware devices are introduced, or when SDL adds new GPU backends or modifies existing ones.
Strings that have been found in the wild include:
- GTX 970
- GeForce GTX 970
- NVIDIA GeForce GTX 970
- Microsoft Direct3D12 (NVIDIA GeForce GTX 970)
- NVIDIA Graphics Device
- GeForce GPU
- P106-100
- AMD 15D8:C9
- AMD Custom GPU 0405
- AMD Radeon (TM) Graphics
- ASUS Radeon RX 470 Series
- Intel(R) Arc(tm) A380 Graphics (DG2)
- Virtio-GPU Venus (NVIDIA TITAN V)
- SwiftShader Device (LLVM 16.0.0)
- llvmpipe (LLVM 15.0.4, 256 bits)
- Microsoft Basic Render Driver
- unknown device
The above list shows that the same device can have different formats, the vendor name may or may not appear in the string, the included vendor name may not be the vendor of the chipset on the device, some manufacturers include pseudo-legal marks while others don't, some devices may not use a marketing name in the string, the device string may be wrapped by the name of a translation interface, the device may be emulated in software, or the string may contain generic text that does not identify the device at all.
prop::GpuDevice.DRIVER_NAME_STRING: Contains the self-reported name of the underlying system driver.
Strings that have been found in the wild include:
- Intel Corporation
- Intel open-source Mesa driver
- Qualcomm Technologies Inc. Adreno Vulkan Driver
- MoltenVK
- Mali-G715
- venus
prop::GpuDevice.DRIVER_VERSION_STRING: Contains the self-reported version of the underlying system driver. This is a relatively short version string in an unspecified format. If prop::GpuDevice.DRIVER_INFO_STRING is available then that property should be preferred over this one as it may contain additional information that is useful for identifying the exact driver version used.
Strings that have been found in the wild include:
- 53.0.0
- 0.405.2463
- 32.0.15.6614
prop::GpuDevice.DRIVER_INFO_STRING: Contains the detailed version information of the underlying system driver as reported by the driver. This is an arbitrary string with no standardized format and it may contain newlines. This property should be preferred over prop::GpuDevice.DRIVER_VERSION_STRING if it is available as it usually contains the same information but in a format that is easier to read.
Strings that have been found in the wild include:
- 101.6559
- 1.2.11
- Mesa 21.2.2 (LLVM 12.0.1)
- Mesa 22.2.0-devel (git-f226222 2022-04-14 impish-oibaf-ppa)
- v1.r53p0-00eac0.824c4f31403fb1fbf8ee1042422c2129
This string has also been observed to be a multiline string (which has a trailing newline):
- Parameters
-
device a GPU context to query.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL 3.4.0.
◆ GetGPUDriver()
|
inline |
The GPU drivers are presented in the order in which they are normally checked during initialization.
The names of drivers are all simple, low-ASCII identifiers, like "vulkan", "metal" or "direct3d12". These never have Unicode characters, and are not meant to be proper names.
- Parameters
-
index the index of a GPU driver.
- Returns
- the name of the GPU driver with the given index.
- Since
- This function is available since SDL 3.2.0.
- See also
- GetNumGPUDrivers
◆ GetGPUShaderFormats()
|
inline |
- Parameters
-
device a GPU context to query.
- Returns
- a bitflag indicating which shader formats the driver is able to consume.
- Since
- This function is available since SDL 3.2.0.
◆ GetGPUSwapchainTextureFormat()
|
inline |
◆ GetGPUTextureFormatFromPixelFormat()
|
inline |
- Parameters
-
format a pixel format.
- Returns
- the corresponding GPU texture format, or GPU_TEXTUREFORMAT_INVALID if there is no corresponding GPU texture format.
- Since
- This function is available since SDL 3.4.0.
◆ GetNumGPUDrivers()
|
inline |
- Returns
- the number of built in GPU drivers.
- Since
- This function is available since SDL 3.2.0.
- See also
- GetGPUDriver
◆ GetPixelFormatFromGPUTextureFormat()
|
inline |
- Parameters
-
format a texture format.
- Returns
- the corresponding pixel format, or PIXELFORMAT_UNKNOWN if there is no corresponding pixel format.
- Since
- This function is available since SDL 3.4.0.
◆ GetProperties()
|
inline |
All properties are optional and may differ between GPU backends and SDL versions.
The following properties are provided by SDL:
prop::GpuDevice.NAME_STRING: Contains the name of the underlying device as reported by the system driver. This string has no standardized format, is highly inconsistent between hardware devices and drivers, and is able to change at any time. Do not attempt to parse this string as it is bound to fail at some point in the future when system drivers are updated, new hardware devices are introduced, or when SDL adds new GPU backends or modifies existing ones.
Strings that have been found in the wild include:
- GTX 970
- GeForce GTX 970
- NVIDIA GeForce GTX 970
- Microsoft Direct3D12 (NVIDIA GeForce GTX 970)
- NVIDIA Graphics Device
- GeForce GPU
- P106-100
- AMD 15D8:C9
- AMD Custom GPU 0405
- AMD Radeon (TM) Graphics
- ASUS Radeon RX 470 Series
- Intel(R) Arc(tm) A380 Graphics (DG2)
- Virtio-GPU Venus (NVIDIA TITAN V)
- SwiftShader Device (LLVM 16.0.0)
- llvmpipe (LLVM 15.0.4, 256 bits)
- Microsoft Basic Render Driver
- unknown device
The above list shows that the same device can have different formats, the vendor name may or may not appear in the string, the included vendor name may not be the vendor of the chipset on the device, some manufacturers include pseudo-legal marks while others don't, some devices may not use a marketing name in the string, the device string may be wrapped by the name of a translation interface, the device may be emulated in software, or the string may contain generic text that does not identify the device at all.
prop::GpuDevice.DRIVER_NAME_STRING: Contains the self-reported name of the underlying system driver.
Strings that have been found in the wild include:
- Intel Corporation
- Intel open-source Mesa driver
- Qualcomm Technologies Inc. Adreno Vulkan Driver
- MoltenVK
- Mali-G715
- venus
prop::GpuDevice.DRIVER_VERSION_STRING: Contains the self-reported version of the underlying system driver. This is a relatively short version string in an unspecified format. If prop::GpuDevice.DRIVER_INFO_STRING is available then that property should be preferred over this one as it may contain additional information that is useful for identifying the exact driver version used.
Strings that have been found in the wild include:
- 53.0.0
- 0.405.2463
- 32.0.15.6614
prop::GpuDevice.DRIVER_INFO_STRING: Contains the detailed version information of the underlying system driver as reported by the driver. This is an arbitrary string with no standardized format and it may contain newlines. This property should be preferred over prop::GpuDevice.DRIVER_VERSION_STRING if it is available as it usually contains the same information but in a format that is easier to read.
Strings that have been found in the wild include:
- 101.6559
- 1.2.11
- Mesa 21.2.2 (LLVM 12.0.1)
- Mesa 22.2.0-devel (git-f226222 2022-04-14 impish-oibaf-ppa)
- v1.r53p0-00eac0.824c4f31403fb1fbf8ee1042422c2129
This string has also been observed to be a multiline string (which has a trailing newline):
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL 3.4.0.
◆ GetShaderFormats()
|
inline |
- Returns
- a bitflag indicating which shader formats the driver is able to consume.
- Since
- This function is available since SDL 3.2.0.
◆ GetSwapchainTextureFormat()
|
inline |
◆ GPUSupportsProperties()
|
inline |
- Parameters
-
props the properties to use.
- Returns
- true if supported, false otherwise.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.GPUDevice
◆ GPUSupportsShaderFormats()
|
inline |
- Parameters
-
format_flags a bitflag indicating which shader formats the app is able to provide. name the preferred GPU driver, or nullptr to let SDL pick the optimal driver.
- Returns
- true if supported, false otherwise.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.GPUDevice
◆ GPUTextureFormatTexelBlockSize()
|
inline |
- Parameters
-
format the texture format you want to know the texel size of.
- Returns
- the texel block size of the texture format.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCopyPass.UploadToTexture
◆ GPUTextureSupportsFormat()
|
inline |
- Parameters
-
device a GPU context. format the texture format to check. type the type of texture (2D, 3D, Cube). usage a bitmask of all usage scenarios to check.
- Returns
- whether the texture format is supported for this type and usage.
- Since
- This function is available since SDL 3.2.0.
◆ GPUTextureSupportsSampleCount()
|
inline |
- Parameters
-
device a GPU context. format the texture format to check. sample_count the sample count to check.
- Returns
- whether the sample count is supported for this texture format.
- Since
- This function is available since SDL 3.2.0.
◆ InsertDebugLabel()
|
inline |
Useful for debugging.
On Direct3D 12, using GPUCommandBuffer.InsertDebugLabel requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.
- Parameters
-
text a UTF-8 string constant to insert as the label.
- Since
- This function is available since SDL 3.2.0.
◆ InsertGPUDebugLabel()
|
inline |
Useful for debugging.
On Direct3D 12, using GPUCommandBuffer.InsertDebugLabel requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.
- Parameters
-
command_buffer a command buffer. text a UTF-8 string constant to insert as the label.
- Since
- This function is available since SDL 3.2.0.
◆ MapGPUTransferBuffer()
|
inline |
You must unmap the transfer buffer before encoding upload commands. The memory is owned by the graphics driver - do NOT call free() on the returned pointer.
- Parameters
-
device a GPU context. transfer_buffer a transfer buffer. cycle if true, cycles the transfer buffer if it is already bound.
- Returns
- the address of the mapped transfer buffer memory, or nullptr on failure; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ MapTransferBuffer()
|
inline |
You must unmap the transfer buffer before encoding upload commands. The memory is owned by the graphics driver - do NOT call free() on the returned pointer.
- Parameters
-
transfer_buffer a transfer buffer. cycle if true, cycles the transfer buffer if it is already bound.
- Returns
- the address of the mapped transfer buffer memory, or nullptr on failure; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ PopDebugGroup()
|
inline |
On Direct3D 12, using GPUCommandBuffer.PopDebugGroup requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.PushDebugGroup
◆ PopGPUDebugGroup()
|
inline |
On Direct3D 12, using GPUCommandBuffer.PopDebugGroup requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.
- Parameters
-
command_buffer a command buffer.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.PushDebugGroup
◆ PushComputeUniformData()
|
inline |
Subsequent draw calls in this command buffer will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
- Parameters
-
slot_index the uniform slot to push data to. data client data to write.
- Since
- This function is available since SDL 3.2.0.
◆ PushDebugGroup()
|
inline |
Used for denoting groups of calls when viewing the command buffer callstream in a graphics debugging tool.
Each call to GPUCommandBuffer.PushDebugGroup must have a corresponding call to GPUCommandBuffer.PopDebugGroup.
On Direct3D 12, using GPUCommandBuffer.PushDebugGroup requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.
On some backends (e.g. Metal), pushing a debug group during a render/blit/compute pass will create a group that is scoped to the native pass rather than the command buffer. For best results, if you push a debug group during a pass, always pop it in the same pass.
- Parameters
-
name a UTF-8 string constant that names the group.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.PopDebugGroup
◆ PushFragmentUniformData()
|
inline |
Subsequent draw calls in this command buffer will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
- Parameters
-
slot_index the fragment uniform slot to push data to. data client data to write.
- Since
- This function is available since SDL 3.2.0.
◆ PushGPUComputeUniformData()
|
inline |
Subsequent draw calls in this command buffer will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
- Parameters
-
command_buffer a command buffer. slot_index the uniform slot to push data to. data client data to write.
- Since
- This function is available since SDL 3.2.0.
◆ PushGPUDebugGroup()
|
inline |
Used for denoting groups of calls when viewing the command buffer callstream in a graphics debugging tool.
Each call to GPUCommandBuffer.PushDebugGroup must have a corresponding call to GPUCommandBuffer.PopDebugGroup.
On Direct3D 12, using GPUCommandBuffer.PushDebugGroup requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.
On some backends (e.g. Metal), pushing a debug group during a render/blit/compute pass will create a group that is scoped to the native pass rather than the command buffer. For best results, if you push a debug group during a pass, always pop it in the same pass.
- Parameters
-
command_buffer a command buffer. name a UTF-8 string constant that names the group.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUCommandBuffer.PopDebugGroup
◆ PushGPUFragmentUniformData()
|
inline |
Subsequent draw calls in this command buffer will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
- Parameters
-
command_buffer a command buffer. slot_index the fragment uniform slot to push data to. data client data to write.
- Since
- This function is available since SDL 3.2.0.
◆ PushGPUVertexUniformData()
|
inline |
Subsequent draw calls in this command buffer will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
For detailed information about accessing uniform data from a shader, please refer to GPUShader.GPUShader.
- Parameters
-
command_buffer a command buffer. slot_index the vertex uniform slot to push data to. data client data to write.
- Since
- This function is available since SDL 3.2.0.
◆ PushVertexUniformData()
|
inline |
Subsequent draw calls in this command buffer will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
For detailed information about accessing uniform data from a shader, please refer to GPUShader.GPUShader.
- Parameters
-
slot_index the vertex uniform slot to push data to. data client data to write.
- Since
- This function is available since SDL 3.2.0.
◆ QueryFence()
|
inline |
- Parameters
-
fence a fence.
- Returns
- true if the fence is signaled, false if it is not.
- Since
- This function is available since SDL 3.2.0.
◆ QueryGPUFence()
|
inline |
- Parameters
-
device a GPU context. fence a fence.
- Returns
- true if the fence is signaled, false if it is not.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseBuffer()
|
inline |
You must not reference the buffer after calling this function.
- Parameters
-
buffer a buffer to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseComputePipeline()
|
inline |
You must not reference the compute pipeline after calling this function.
- Parameters
-
compute_pipeline a compute pipeline to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseFence()
|
inline |
You must not reference the fence after calling this function.
- Parameters
-
fence a fence.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGPUBuffer()
|
inline |
You must not reference the buffer after calling this function.
- Parameters
-
device a GPU context. buffer a buffer to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGPUComputePipeline()
|
inline |
You must not reference the compute pipeline after calling this function.
- Parameters
-
device a GPU context. compute_pipeline a compute pipeline to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGPUFence()
|
inline |
You must not reference the fence after calling this function.
- Parameters
-
device a GPU context. fence a fence.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGPUGraphicsPipeline()
|
inline |
You must not reference the graphics pipeline after calling this function.
- Parameters
-
device a GPU context. graphics_pipeline a graphics pipeline to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGPUSampler()
|
inline |
You must not reference the sampler after calling this function.
- Parameters
-
device a GPU context. sampler a sampler to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGPUShader()
|
inline |
You must not reference the shader after calling this function.
- Parameters
-
device a GPU context. shader a shader to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGPUTexture()
|
inline |
You must not reference the texture after calling this function.
- Parameters
-
device a GPU context. texture a texture to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGPUTransferBuffer()
|
inline |
You must not reference the transfer buffer after calling this function.
- Parameters
-
device a GPU context. transfer_buffer a transfer buffer to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseGraphicsPipeline()
|
inline |
You must not reference the graphics pipeline after calling this function.
- Parameters
-
graphics_pipeline a graphics pipeline to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseSampler()
|
inline |
You must not reference the sampler after calling this function.
- Parameters
-
sampler a sampler to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseShader()
|
inline |
You must not reference the shader after calling this function.
- Parameters
-
shader a shader to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseTexture()
|
inline |
You must not reference the texture after calling this function.
- Parameters
-
texture a texture to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseTransferBuffer()
|
inline |
You must not reference the transfer buffer after calling this function.
- Parameters
-
transfer_buffer a transfer buffer to be destroyed.
- Since
- This function is available since SDL 3.2.0.
◆ ReleaseWindow()
|
inline |
- Parameters
-
window an Window that has been claimed.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.ClaimWindow
◆ ReleaseWindowFromGPUDevice()
|
inline |
- Parameters
-
device a GPU context. window an Window that has been claimed.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.ClaimWindow
◆ SetAllowedFramesInFlight()
|
inline |
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, GPUCommandBuffer.AcquireSwapchainTexture() will fill the swapchain texture pointer with nullptr, and GPUCommandBuffer.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.
- Parameters
-
allowed_frames_in_flight the maximum number of frames that can be pending on the GPU.
- Returns
- true if successful, false on error; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ SetBlendConstants()
|
inline |
- Parameters
-
blend_constants the blend constant color.
- Since
- This function is available since SDL 3.2.0.
◆ SetBufferName()
|
inline |
You should use prop::GPUBuffer.CREATE_NAME_STRING with GPUBuffer.GPUBuffer instead of this function to avoid thread safety issues.
- Parameters
-
buffer a buffer to attach the name to. text a UTF-8 string constant to mark as the name of the buffer.
- Thread safety:
- This function is not thread safe, you must make sure the buffer is not simultaneously used by any other thread.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUBuffer.GPUBuffer
◆ SetGPUAllowedFramesInFlight()
|
inline |
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, GPUCommandBuffer.AcquireSwapchainTexture() will fill the swapchain texture pointer with nullptr, and GPUCommandBuffer.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.
- Parameters
-
device a GPU context. allowed_frames_in_flight the maximum number of frames that can be pending on the GPU.
- Returns
- true if successful, false on error; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ SetGPUBlendConstants()
|
inline |
- Parameters
-
render_pass a render pass handle. blend_constants the blend constant color.
- Since
- This function is available since SDL 3.2.0.
◆ SetGPUBufferName()
|
inline |
You should use prop::GPUBuffer.CREATE_NAME_STRING with GPUBuffer.GPUBuffer instead of this function to avoid thread safety issues.
- Parameters
-
device a GPU Context. buffer a buffer to attach the name to. text a UTF-8 string constant to mark as the name of the buffer.
- Thread safety:
- This function is not thread safe, you must make sure the buffer is not simultaneously used by any other thread.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUBuffer.GPUBuffer
◆ SetGPUScissor()
|
inline |
- Parameters
-
render_pass a render pass handle. scissor the scissor area to set.
- Since
- This function is available since SDL 3.2.0.
◆ SetGPUStencilReference()
|
inline |
- Parameters
-
render_pass a render pass handle. reference the stencil reference value to set.
- Since
- This function is available since SDL 3.2.0.
◆ SetGPUSwapchainParameters()
|
inline |
This function will fail if the requested present mode or swapchain composition are unsupported by the device. Check if the parameters are supported via GPUDevice.WindowSupportsPresentMode / GPUDevice.WindowSupportsSwapchainComposition prior to calling this function.
GPU_PRESENTMODE_VSYNC with GPU_SWAPCHAINCOMPOSITION_SDR are always supported.
- Parameters
-
device a GPU context. window an Window that has been claimed. swapchain_composition the desired composition of the swapchain. present_mode the desired present mode for the swapchain.
- Returns
- true if successful, false on error; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ SetGPUTextureName()
|
inline |
You should use prop::GPUTexture.CREATE_NAME_STRING with GPUTexture.GPUTexture instead of this function to avoid thread safety issues.
- Parameters
-
device a GPU Context. texture a texture to attach the name to. text a UTF-8 string constant to mark as the name of the texture.
- Thread safety:
- This function is not thread safe, you must make sure the texture is not simultaneously used by any other thread.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUTexture.GPUTexture
◆ SetGPUViewport()
|
inline |
- Parameters
-
render_pass a render pass handle. viewport the viewport to set.
- Since
- This function is available since SDL 3.2.0.
◆ SetScissor()
|
inline |
- Parameters
-
scissor the scissor area to set.
- Since
- This function is available since SDL 3.2.0.
◆ SetStencilReference()
|
inline |
- Parameters
-
reference the stencil reference value to set.
- Since
- This function is available since SDL 3.2.0.
◆ SetSwapchainParameters()
|
inline |
This function will fail if the requested present mode or swapchain composition are unsupported by the device. Check if the parameters are supported via GPUDevice.WindowSupportsPresentMode / GPUDevice.WindowSupportsSwapchainComposition prior to calling this function.
GPU_PRESENTMODE_VSYNC with GPU_SWAPCHAINCOMPOSITION_SDR is always supported.
- Parameters
-
window an Window that has been claimed. swapchain_composition the desired composition of the swapchain. present_mode the desired present mode for the swapchain.
- Returns
- true if successful, false on error; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ SetTextureName()
|
inline |
You should use prop::GPUTexture.CREATE_NAME_STRING with GPUTexture.GPUTexture instead of this function to avoid thread safety issues.
- Parameters
-
texture a texture to attach the name to. text a UTF-8 string constant to mark as the name of the texture.
- Thread safety:
- This function is not thread safe, you must make sure the texture is not simultaneously used by any other thread.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUTexture.GPUTexture
◆ SetViewport()
|
inline |
- Parameters
-
viewport the viewport to set.
- Since
- This function is available since SDL 3.2.0.
◆ Submit()
|
inline |
It is invalid to use the command buffer after this is called.
This must be called from the thread the command buffer was acquired on.
All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ SubmitAndAcquireFence()
|
inline |
You must release this fence when it is no longer needed or it will cause a leak. It is invalid to use the command buffer after this is called.
This must be called from the thread the command buffer was acquired on.
All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.
- Returns
- a fence associated with the command buffer, or nullptr on failure; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ SubmitGPUCommandBuffer()
|
inline |
It is invalid to use the command buffer after this is called.
This must be called from the thread the command buffer was acquired on.
All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.
- Parameters
-
command_buffer a command buffer.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
◆ SubmitGPUCommandBufferAndAcquireFence()
|
inline |
You must release this fence when it is no longer needed or it will cause a leak. It is invalid to use the command buffer after this is called.
This must be called from the thread the command buffer was acquired on.
All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.
- Parameters
-
command_buffer a command buffer.
- Returns
- a fence associated with the command buffer, or nullptr on failure; call GetError() for more information.
- Since
- This function is available since SDL 3.2.0.
◆ TextureSupportsFormat()
|
inline |
- Parameters
-
format the texture format to check. type the type of texture (2D, 3D, Cube). usage a bitmask of all usage scenarios to check.
- Returns
- whether the texture format is supported for this type and usage.
- Since
- This function is available since SDL 3.2.0.
◆ TextureSupportsSampleCount()
|
inline |
- Parameters
-
format the texture format to check. sample_count the sample count to check.
- Returns
- whether the sample count is supported for this texture format.
- Since
- This function is available since SDL 3.2.0.
◆ UnmapGPUTransferBuffer()
|
inline |
- Parameters
-
device a GPU context. transfer_buffer a previously mapped transfer buffer.
- Since
- This function is available since SDL 3.2.0.
◆ UnmapTransferBuffer()
|
inline |
- Parameters
-
transfer_buffer a previously mapped transfer buffer.
- Since
- This function is available since SDL 3.2.0.
◆ UploadToBuffer()
|
inline |
The upload occurs on the GPU timeline. You may assume that the upload has finished in subsequent commands.
- Parameters
-
source the source transfer buffer with offset. destination the destination buffer with offset and size. cycle if true, cycles the buffer if it is already bound, otherwise overwrites the data.
- Since
- This function is available since SDL 3.2.0.
◆ UploadToGPUBuffer()
|
inline |
The upload occurs on the GPU timeline. You may assume that the upload has finished in subsequent commands.
- Parameters
-
copy_pass a copy pass handle. source the source transfer buffer with offset. destination the destination buffer with offset and size. cycle if true, cycles the buffer if it is already bound, otherwise overwrites the data.
- Since
- This function is available since SDL 3.2.0.
◆ UploadToGPUTexture()
|
inline |
The upload occurs on the GPU timeline. You may assume that the upload has finished in subsequent commands.
You must align the data in the transfer buffer to a multiple of the texel size of the texture format.
- Parameters
-
copy_pass a copy pass handle. source the source transfer buffer with image layout information. destination the destination texture region. cycle if true, cycles the texture if the texture is bound, otherwise overwrites the data.
- Since
- This function is available since SDL 3.2.0.
◆ UploadToTexture()
|
inline |
The upload occurs on the GPU timeline. You may assume that the upload has finished in subsequent commands.
You must align the data in the transfer buffer to a multiple of the texel size of the texture format.
- Parameters
-
source the source transfer buffer with image layout information. destination the destination texture region. cycle if true, cycles the texture if the texture is bound, otherwise overwrites the data.
- Since
- This function is available since SDL 3.2.0.
◆ WaitAndAcquireGPUSwapchainTexture()
|
inline |
When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it. It is an error to call GPUCommandBuffer.Cancel() after a swapchain texture is acquired.
This function can fill the swapchain texture handle with nullptr in certain cases, for example if the window is minimized. This is not an error. You should always make sure to check whether the pointer is nullptr before actually using it.
The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this function from any thread other than the one that created the window.
The swapchain texture is write-only and cannot be used as a sampler or for another reading operation.
- Parameters
-
command_buffer a command buffer. window a window that has been claimed. swapchain_texture_width a pointer filled in with the swapchain texture width, may be nullptr. swapchain_texture_height a pointer filled in with the swapchain texture height, may be nullptr.
- Returns
- a swapchain texture handle.
- Exceptions
-
Error on failure.
- Thread safety:
- This function should only be called from the thread that created the window.
- Since
- This function is available since SDL 3.2.0.
◆ WaitAndAcquireSwapchainTexture()
|
inline |
When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it. It is an error to call GPUCommandBuffer.Cancel() after a swapchain texture is acquired.
This function can fill the swapchain texture handle with nullptr in certain cases, for example if the window is minimized. This is not an error. You should always make sure to check whether the pointer is nullptr before actually using it.
The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this function from any thread other than the one that created the window.
The swapchain texture is write-only and cannot be used as a sampler or for another reading operation.
- Parameters
-
window a window that has been claimed. swapchain_texture_width a pointer filled in with the swapchain texture width, may be nullptr. swapchain_texture_height a pointer filled in with the swapchain texture height, may be nullptr.
- Returns
- a swapchain texture handle.
- Exceptions
-
Error on failure.
- Thread safety:
- This function should only be called from the thread that created the window.
- Since
- This function is available since SDL 3.2.0.
◆ WaitForFences()
|
inline |
◆ WaitForGPUFences()
|
inline |
◆ WaitForGPUIdle()
|
inline |
- Parameters
-
device a GPU context.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.WaitForFences
◆ WaitForGPUSwapchain()
|
inline |
◆ WaitForIdle()
|
inline |
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.WaitForFences
◆ WaitForSwapchain()
|
inline |
◆ WindowSupportsGPUPresentMode()
|
inline |
The window must be claimed before calling this function.
- Parameters
-
device a GPU context. window an Window. present_mode the presentation mode to check.
- Returns
- true if supported, false if unsupported.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.ClaimWindow
◆ WindowSupportsGPUSwapchainComposition()
|
inline |
The window must be claimed before calling this function.
- Parameters
-
device a GPU context. window an Window. swapchain_composition the swapchain composition to check.
- Returns
- true if supported, false if unsupported.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.ClaimWindow
◆ WindowSupportsPresentMode()
|
inline |
The window must be claimed before calling this function.
- Parameters
-
window an Window. present_mode the presentation mode to check.
- Returns
- true if supported, false if unsupported.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.ClaimWindow
◆ WindowSupportsSwapchainComposition()
|
inline |
The window must be claimed before calling this function.
- Parameters
-
window an Window. swapchain_composition the swapchain composition to check.
- Returns
- true if supported, false if unsupported.
- Since
- This function is available since SDL 3.2.0.
- See also
- GPUDevice.ClaimWindow
Variable Documentation
◆ GPU_BLENDFACTOR_CONSTANT_COLOR
|
constexpr |
◆ GPU_BLENDFACTOR_DST_ALPHA
|
constexpr |
◆ GPU_BLENDFACTOR_DST_COLOR
|
constexpr |
◆ GPU_BLENDFACTOR_INVALID
|
constexpr |
◆ GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR
|
constexpr |
◆ GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA
|
constexpr |
◆ GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR
|
constexpr |
◆ GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA
|
constexpr |
◆ GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR
|
constexpr |
◆ GPU_BLENDFACTOR_SRC_ALPHA
|
constexpr |
◆ GPU_BLENDFACTOR_SRC_ALPHA_SATURATE
|
constexpr |
◆ GPU_BLENDFACTOR_SRC_COLOR
|
constexpr |
◆ GPU_BLENDOP_INVALID
|
constexpr |
◆ GPU_BLENDOP_MAX
|
constexpr |
◆ GPU_BLENDOP_MIN
|
constexpr |
◆ GPU_BLENDOP_REVERSE_SUBTRACT
|
constexpr |
◆ GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ
|
constexpr |
◆ GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE
|
constexpr |
◆ GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ
|
constexpr |
◆ GPU_BUFFERUSAGE_INDEX
|
constexpr |
◆ GPU_BUFFERUSAGE_INDIRECT
|
constexpr |
◆ GPU_BUFFERUSAGE_VERTEX
|
constexpr |
◆ GPU_COLORCOMPONENT_A
|
constexpr |
◆ GPU_COLORCOMPONENT_B
|
constexpr |
◆ GPU_COLORCOMPONENT_G
|
constexpr |
◆ GPU_COLORCOMPONENT_R
|
constexpr |
◆ GPU_COMPAREOP_ALWAYS
|
constexpr |
◆ GPU_COMPAREOP_EQUAL
|
constexpr |
◆ GPU_COMPAREOP_GREATER
|
constexpr |
◆ GPU_COMPAREOP_GREATER_OR_EQUAL
|
constexpr |
◆ GPU_COMPAREOP_INVALID
|
constexpr |
◆ GPU_COMPAREOP_LESS
|
constexpr |
◆ GPU_COMPAREOP_LESS_OR_EQUAL
|
constexpr |
◆ GPU_COMPAREOP_NEVER
|
constexpr |
◆ GPU_COMPAREOP_NOT_EQUAL
|
constexpr |
◆ GPU_CUBEMAPFACE_NEGATIVEX
|
constexpr |
◆ GPU_CUBEMAPFACE_NEGATIVEY
|
constexpr |
◆ GPU_CUBEMAPFACE_NEGATIVEZ
|
constexpr |
◆ GPU_CUBEMAPFACE_POSITIVEX
|
constexpr |
◆ GPU_CUBEMAPFACE_POSITIVEY
|
constexpr |
◆ GPU_CUBEMAPFACE_POSITIVEZ
|
constexpr |
◆ GPU_CULLMODE_BACK
|
constexpr |
◆ GPU_CULLMODE_FRONT
|
constexpr |
◆ GPU_CULLMODE_NONE
|
constexpr |
◆ GPU_FILLMODE_FILL
|
constexpr |
◆ GPU_FILLMODE_LINE
|
constexpr |
◆ GPU_FILTER_LINEAR
|
constexpr |
◆ GPU_FILTER_NEAREST
|
constexpr |
◆ GPU_FRONTFACE_COUNTER_CLOCKWISE
|
constexpr |
◆ GPU_INDEXELEMENTSIZE_16BIT
|
constexpr |
◆ GPU_INDEXELEMENTSIZE_32BIT
|
constexpr |
◆ GPU_LOADOP_DONT_CARE
|
constexpr |
The contents will be undefined.
◆ GPU_PRESENTMODE_IMMEDIATE
|
constexpr |
◆ GPU_PRESENTMODE_MAILBOX
|
constexpr |
◆ GPU_PRESENTMODE_VSYNC
|
constexpr |
◆ GPU_PRIMITIVETYPE_LINELIST
|
constexpr |
◆ GPU_PRIMITIVETYPE_LINESTRIP
|
constexpr |
◆ GPU_PRIMITIVETYPE_POINTLIST
|
constexpr |
◆ GPU_PRIMITIVETYPE_TRIANGLELIST
|
constexpr |
◆ GPU_PRIMITIVETYPE_TRIANGLESTRIP
|
constexpr |
◆ GPU_SAMPLECOUNT_1
|
constexpr |
◆ GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE
|
constexpr |
◆ GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT
|
constexpr |
◆ GPU_SAMPLERADDRESSMODE_REPEAT
|
constexpr |
◆ GPU_SAMPLERMIPMAPMODE_LINEAR
|
constexpr |
◆ GPU_SAMPLERMIPMAPMODE_NEAREST
|
constexpr |
◆ GPU_SHADERFORMAT_DXBC
|
constexpr |
◆ GPU_SHADERFORMAT_DXIL
|
constexpr |
◆ GPU_SHADERFORMAT_INVALID
|
constexpr |
◆ GPU_SHADERFORMAT_METALLIB
|
constexpr |
◆ GPU_SHADERFORMAT_MSL
|
constexpr |
◆ GPU_SHADERFORMAT_PRIVATE
|
constexpr |
◆ GPU_SHADERFORMAT_SPIRV
|
constexpr |
◆ GPU_SHADERSTAGE_FRAGMENT
|
constexpr |
◆ GPU_SHADERSTAGE_VERTEX
|
constexpr |
◆ GPU_STENCILOP_DECREMENT_AND_CLAMP
|
constexpr |
◆ GPU_STENCILOP_DECREMENT_AND_WRAP
|
constexpr |
◆ GPU_STENCILOP_INCREMENT_AND_CLAMP
|
constexpr |
◆ GPU_STENCILOP_INCREMENT_AND_WRAP
|
constexpr |
◆ GPU_STENCILOP_INVALID
|
constexpr |
◆ GPU_STENCILOP_INVERT
|
constexpr |
◆ GPU_STENCILOP_KEEP
|
constexpr |
◆ GPU_STENCILOP_REPLACE
|
constexpr |
◆ GPU_STENCILOP_ZERO
|
constexpr |
◆ GPU_STOREOP_DONT_CARE
|
constexpr |
The contents will be undefined.
◆ GPU_STOREOP_RESOLVE
|
constexpr |
The contents in the multisample texture may then be discarded and will be undefined.
◆ GPU_STOREOP_RESOLVE_AND_STORE
|
constexpr |
The contents in the multisample texture will be written to memory.
◆ GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084
|
constexpr |
◆ GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR
|
constexpr |
◆ GPU_SWAPCHAINCOMPOSITION_SDR
|
constexpr |
◆ GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR
|
constexpr |
◆ GPU_TEXTUREFORMAT_A8_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x10_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x5_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x6_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x8_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_12x10_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_12x12_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_4x4_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_5x4_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_5x5_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_6x5_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_6x6_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x5_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x6_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x8_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_B4G4R4A4_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_B5G5R5A1_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_B5G6R5_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_B8G8R8A8_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC1_RGBA_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC2_RGBA_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC3_RGBA_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC4_R_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC5_RG_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC7_RGBA_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTUREFORMAT_D16_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_D24_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_D32_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_INVALID
|
constexpr |
◆ GPU_TEXTUREFORMAT_R10G10B10A2_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R11G11B10_UFLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16_SNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16_SNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16B16A16_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16B16A16_SNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16B16A16_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R16G16B16A16_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32G32_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32G32_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32G32_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32G32B32A32_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R32G32B32A32_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8_SNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8_SNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8B8A8_INT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8B8A8_SNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8B8A8_UINT
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8B8A8_UNORM
|
constexpr |
◆ GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB
|
constexpr |
◆ GPU_TEXTURETYPE_2D
|
constexpr |
◆ GPU_TEXTURETYPE_2D_ARRAY
|
constexpr |
◆ GPU_TEXTURETYPE_3D
|
constexpr |
◆ GPU_TEXTURETYPE_CUBE
|
constexpr |
◆ GPU_TEXTURETYPE_CUBE_ARRAY
|
constexpr |
◆ GPU_TEXTUREUSAGE_COLOR_TARGET
|
constexpr |
◆ GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ
|
constexpr |
◆ GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE
|
constexpr |
This is NOT equivalent to READ | WRITE.
◆ GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE
|
constexpr |
◆ GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET
|
constexpr |
◆ GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ
|
constexpr |
◆ GPU_TEXTUREUSAGE_SAMPLER
|
constexpr |
◆ GPU_TRANSFERBUFFERUSAGE_DOWNLOAD
|
constexpr |
◆ GPU_TRANSFERBUFFERUSAGE_UPLOAD
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_BYTE2
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_BYTE2_NORM
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_BYTE4
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_BYTE4_NORM
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_FLOAT
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_FLOAT2
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_FLOAT3
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_FLOAT4
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_HALF2
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_HALF4
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_INT
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_INT2
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_INT3
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_INT4
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_INVALID
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_SHORT2
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_SHORT2_NORM
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_SHORT4
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_SHORT4_NORM
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_UBYTE2
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_UBYTE2_NORM
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_UBYTE4
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_UBYTE4_NORM
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_UINT
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_UINT2
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_UINT3
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_UINT4
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_USHORT2
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_USHORT2_NORM
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_USHORT4
|
constexpr |
◆ GPU_VERTEXELEMENTFORMAT_USHORT4_NORM
|
constexpr |
◆ GPU_VERTEXINPUTRATE_INSTANCE
|
constexpr |
◆ GPU_VERTEXINPUTRATE_VERTEX
|
constexpr |
