Milky Way Icon. MultiverseSocial.com Milky Way Icon.

Navigation

Color Coding

Vertex Fragment Compute Tessellation General

Functions are colored by primary shader stage association. Tessellation is hypothetical/future.

SDL3 GPU API

The SDL3 GPU API provides cross-platform access to modern graphics hardware for 3D rendering and compute, abstracting Vulkan, Metal, and D3D12.

Workflow Overview:

  1. Device creation
  2. Resource prep (shaders, buffers, textures)
  3. Command buffer acquisition
  4. Passes (render/compute/copy)
  5. Submission

Examples: SDL_gpu_examples.

Note on Tessellation: As of November 2025, SDL3 GPU does not support tessellation shaders. This section proposes a hypothetical extension for future inclusion, based on common practices in Vulkan/D3D12/Metal. File a feature request on GitHub for official support.

Device Management

Creating and querying the GPU context.

Function Signature Explanation
SDL_GPUSupportsShaderFormats SDL_GPUSupportsShaderFormats(SDL_GPUShaderFormat format_flags, const char *name) Checks shader formats & driver support.
SDL_CreateGPUDevice SDL_CreateGPUDevice(SDL_GPUShaderFormat format_flags, bool debug_mode, const char *name) Creates device with formats, debug, driver (e.g., "vulkan").
SDL_CreateGPUDeviceWithProperties SDL_CreateGPUDeviceWithProperties(SDL_PropertiesID props) Advanced creation via props (e.g., low-power, D3D12 tweaks).
SDL_DestroyGPUDevice SDL_DestroyGPUDevice(SDL_GPUDevice *device) Destroys device & resources.
SDL_GetNumGPUDrivers SDL_GetNumGPUDrivers(void) Lists available drivers.
SDL_GetGPUDriver SDL_GetGPUDriver(int index) Lists available drivers.
SDL_GetGPUDeviceDriver SDL_GetGPUDeviceDriver(SDL_GPUDevice *device) Queries device driver & formats.
SDL_GetGPUShaderFormats SDL_GetGPUShaderFormats(SDL_GPUDevice *device) Queries device driver & formats.
SDL_GetGPUDeviceProperties SDL_GetGPUDeviceProperties(SDL_GPUDevice *device) Gets name, driver version/info.

Resource Creation

Shaders, pipelines, buffers, textures, samplers.

Vertex Fragment Compute Tessellation General

Function Signature Explanation
SDL_CreateGPUComputePipeline SDL_CreateGPUComputePipeline(SDL_GPUDevice *device, const SDL_GPUComputePipelineCreateInfo *createinfo) Compute pipeline; shader code, thread counts, resources (backend layouts).
SDL_CreateGPUGraphicsPipeline SDL_CreateGPUGraphicsPipeline(SDL_GPUDevice *device, const SDL_GPUGraphicsPipelineCreateInfo *createinfo) Graphics pipeline; shaders, vertex input, rasterizer, targets.
SDL_CreateGPUSampler SDL_CreateGPUSampler(SDL_GPUDevice *device, const SDL_GPUSamplerCreateInfo *createinfo) Sampler; filters, address modes, anisotropy, LOD.
SDL_CreateGPUShader SDL_CreateGPUShader(SDL_GPUDevice *device, const SDL_GPUShaderCreateInfo *createinfo) Vertex/fragment/tessellation shader; code, format, resources (e.g., SPIR-V sets). Supports all stages including VERTEX, FRAGMENT, COMPUTE, HULL (proposed), DOMAIN (proposed). For Vulkan backend, shaders can be provided as SPIR-V bytecode; Metal uses MSL, D3D12 uses DXIL. All SPIR-V compatible stages (glslang-validated) are included: core GLSL stages map to SPIR-V OpExecutionMode.
SDL_CreateGPUTexture SDL_CreateGPUTexture(SDL_GPUDevice *device, const SDL_GPUTextureCreateInfo *createinfo) Texture; type/format/usage, dims, mips, samples (D3D12 clears).
SDL_CreateGPUBuffer SDL_CreateGPUBuffer(SDL_GPUDevice *device, const SDL_GPUBufferCreateInfo *createinfo) Buffer; usage (vertex/index/storage), size (std140 for storage).
SDL_CreateGPUTransferBuffer SDL_CreateGPUTransferBuffer(SDL_GPUDevice *device, const SDL_GPUTransferBufferCreateInfo *createinfo) Upload/download buffer; size, direction.

Perf Tips

  • Min passes
  • Min state changes
  • Early uploads
  • Cache resources
  • Cycle correctly
  • Cull draws

Systems

  • Vulkan (Win/Linux/Switch/Android)
  • D3D12 (Win 10+/Xbox)
  • Metal (macOS 10.14+/iOS 13+)

Coords

Left-handed: NDC: (-1,-1) BL Z: [0,1]

Debug

  • Names via props
  • Labels: Insert/Push/Pop
  • Tools: RenderDoc, Xcode

Render Passes

Graphics rendering with targets & draws.

Vertex Fragment Compute Tessellation General

Function Signature Explanation
SDL_BeginGPURenderPass SDL_BeginGPURenderPass(SDL_GPUCommandBuffer *command_buffer, const SDL_GPUColorTargetInfo *color_target_infos, Uint32 num_color_targets, const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info) Start; color/depth targets, load/store/clear ops.
SDL_BindGPUGraphicsPipeline SDL_BindGPUGraphicsPipeline(SDL_GPURenderPass *render_pass, SDL_GPUGraphicsPipeline *graphics_pipeline) Bind pipeline.
SDL_SetGPUViewport SDL_SetGPUViewport(SDL_GPURenderPass *render_pass, const SDL_GPUViewport *viewport) Set viewport, clip, blends, stencil.
SDL_SetGPUScissor SDL_SetGPUScissor(SDL_GPURenderPass *render_pass, const SDL_Rect *scissor) Set viewport, clip, blends, stencil.
SDL_SetGPUBlendConstants SDL_SetGPUBlendConstants(SDL_GPURenderPass *render_pass, SDL_FColor blend_constants) Set viewport, clip, blends, stencil.
SDL_SetGPUStencilReference SDL_SetGPUStencilReference(SDL_GPURenderPass *render_pass, Uint8 reference) Set viewport, clip, blends, stencil.
SDL_BindGPUVertexBuffers SDL_BindGPUVertexBuffers(SDL_GPURenderPass *render_pass, Uint32 first_slot, const SDL_GPUBufferBinding *bindings, Uint32 num_bindings) Bind verts/index (16/32-bit).
SDL_BindGPUIndexBuffer SDL_BindGPUIndexBuffer(SDL_GPURenderPass *render_pass, const SDL_GPUBufferBinding *binding, SDL_GPUIndexElementSize index_element_size) Bind verts/index (16/32-bit).
SDL_BindGPUVertexSamplers SDL_BindGPUVertexSamplers(SDL_GPURenderPass *render_pass, Uint32 first_slot, const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, Uint32 num_bindings) Bind samplers/storage per stage.
SDL_BindGPUFragmentSamplers SDL_BindGPUFragmentSamplers(SDL_GPURenderPass *render_pass, Uint32 first_slot, const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, Uint32 num_bindings) Bind samplers/storage per stage.
SDL_BindGPUVertexStorageTextures SDL_BindGPUVertexStorageTextures(SDL_GPURenderPass *render_pass, Uint32 first_slot, SDL_GPUTexture *const *storage_textures, Uint32 num_bindings) Bind samplers/storage per stage.
SDL_BindGPUFragmentStorageTextures SDL_BindGPUFragmentStorageTextures(SDL_GPURenderPass *render_pass, Uint32 first_slot, SDL_GPUTexture *const *storage_textures, Uint32 num_bindings) Bind samplers/storage per stage.
SDL_BindGPUVertexStorageBuffers SDL_BindGPUVertexStorageBuffers(SDL_GPURenderPass *render_pass, Uint32 first_slot, SDL_GPUBuffer *const *storage_buffers, Uint32 num_bindings) Bind samplers/storage per stage.
SDL_BindGPUFragmentStorageBuffers SDL_BindGPUFragmentStorageBuffers(SDL_GPURenderPass *render_pass, Uint32 first_slot, SDL_GPUBuffer *const *storage_buffers, Uint32 num_bindings) Bind samplers/storage per stage.
SDL_DrawGPUPrimitives SDL_DrawGPUPrimitives(SDL_GPURenderPass *render_pass, Uint32 num_vertices, Uint32 num_instances, Uint32 first_vertex, Uint32 first_instance) Direct draws w/ instancing.
SDL_DrawGPUIndexedPrimitives SDL_DrawGPUIndexedPrimitives(SDL_GPURenderPass *render_pass, Uint32 num_indices, Uint32 num_instances, Uint32 first_index, Sint32 vertex_offset, Uint32 first_instance) Direct draws w/ instancing.
SDL_DrawGPUPrimitivesIndirect SDL_DrawGPUPrimitivesIndirect(SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, Uint32 offset, Uint32 draw_count) Indirect from buffer.
SDL_DrawGPUIndexedPrimitivesIndirect SDL_DrawGPUIndexedPrimitivesIndirect(SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, Uint32 offset, Uint32 draw_count) Indirect from buffer.
SDL_EndGPURenderPass SDL_EndGPURenderPass(SDL_GPURenderPass *render_pass) End; reset state.

Tessellation Shaders (Proposed)

Hypothetical extension for dynamic geometry subdivision.
 Would require new stages:
 HULL (control),
DOMAIN (evaluation). Not currently supported.

Vertex Fragment Compute Tessellation General

Proposed Function Signature Explanation
SDL_GPU_SHADERSTAGE_HULL enum addition: SDL_GPU_SHADERSTAGE_HULL Hull shader stage for patch control. SPIR-V: Supports OpExecutionMode TessellationControlShader.
SDL_GPU_SHADERSTAGE_DOMAIN enum addition: SDL_GPU_SHADERSTAGE_DOMAIN Domain shader stage for evaluation. SPIR-V: Supports OpExecutionMode TessellationEvaluationShader.
SDL_CreateGPUShader (extended) Supports HULL/DOMAIN stages. Create tessellation shaders with patch types. Includes SPIR-V validation for tessellation extensions (SPV_KHR_tessellation).
SDL_CreateGPUGraphicsPipeline (extended) Add hull_shader, domain_shader to createinfo. Pipeline with tessellation enabled; specify primitive topology as patches. SPIR-V pipelines link all stages including hull/domain.
SDL_SetGPUPatchControlPoints SDL_SetGPUPatchControlPoints(SDL_GPURenderPass *render_pass, Uint32 num_control_points) Set patch vertices (e.g., 3 for triangles).

Backend mapping:
Vulkan (VK_PRIMITIVE_TOPOLOGY_PATCH_LIST),
D3D12 (D3D12_PRIMITIVE_TOPOLOGY_PATCHLIST),
Metal (MTLPrimitiveTopologyClassUnspecified with patches).

Compute Passes

Shader dispatches (no sync; end for barriers).

Vertex Fragment Compute Tessellation General

Function Signature Explanation
SDL_BeginGPUComputePass SDL_BeginGPUComputePass(SDL_GPUCommandBuffer *command_buffer, const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings, Uint32 num_storage_texture_bindings, const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings, Uint32 num_storage_buffer_bindings) Start; writable storage textures/buffers.
SDL_BindGPUComputePipeline SDL_BindGPUComputePipeline(SDL_GPUComputePass *compute_pass, SDL_GPUComputePipeline *compute_pipeline) Bind pipeline.
SDL_BindGPUComputeSamplers SDL_BindGPUComputeSamplers(SDL_GPUComputePass *compute_pass, Uint32 first_slot, const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, Uint32 num_bindings) Bind resources.
SDL_BindGPUComputeStorageTextures SDL_BindGPUComputeStorageTextures(SDL_GPUComputePass *compute_pass, Uint32 first_slot, SDL_GPUTexture *const *storage_textures, Uint32 num_bindings) Bind resources.
SDL_BindGPUComputeStorageBuffers SDL_BindGPUComputeStorageBuffers(SDL_GPUComputePass *compute_pass, Uint32 first_slot, SDL_GPUBuffer *const *storage_buffers, Uint32 num_bindings) Bind resources.
SDL_DispatchGPUCompute SDL_DispatchGPUCompute(SDL_GPUComputePass *compute_pass, Uint32 groupcount_x, Uint32 groupcount_y, Uint32 groupcount_z) Dispatch groups (order undefined for overlaps).
SDL_DispatchGPUComputeIndirect SDL_DispatchGPUComputeIndirect(SDL_GPUComputePass *compute_pass, SDL_GPUBuffer *buffer, Uint32 offset) Dispatch groups (order undefined for overlaps).
SDL_EndGPUComputePass SDL_EndGPUComputePass(SDL_GPUComputePass *compute_pass) End; reset.

FAQ

Shader fail? Layouts strict; use reflection.

Low perf? Follow tips; RenderDoc.

Advanced? No RT/mesh yet; tessellation proposed.

Uniforms

  • Push to slots (std140)
  • Small data only
  • Per-stage (V/F/C/T)

Transfers

  • Map/Unmap transfer buf
  • Cycle for reuse

Copy Passes & Utils

Data transfers & misc.

Function Signature Explanation
SDL_BeginGPUCopyPass SDL_BeginGPUCopyPass(SDL_GPUCommandBuffer *command_buffer) Start/end copies.
SDL_EndGPUCopyPass SDL_EndGPUCopyPass(SDL_GPUCopyPass *copy_pass) Start/end copies.
SDL_UploadToGPUTexture SDL_UploadToGPUTexture(SDL_GPUCopyPass *copy_pass, const SDL_GPUTextureTransferInfo *source, const SDL_GPUTextureRegion *destination, bool cycle) From transfer buf (align texels).
SDL_UploadToGPUBuffer SDL_UploadToGPUBuffer(SDL_GPUCopyPass *copy_pass, const SDL_GPUTransferBufferLocation *source, const SDL_GPUBufferRegion *destination, bool cycle) From transfer buf (align texels).
SDL_DownloadFromGPUTexture SDL_DownloadFromGPUTexture(SDL_GPUCopyPass *copy_pass, const SDL_GPUTextureRegion *source, const SDL_GPUTextureTransferInfo *destination) To transfer buf (fence sync).
SDL_DownloadFromGPUBuffer SDL_DownloadFromGPUBuffer(SDL_GPUCopyPass *copy_pass, const SDL_GPUBufferRegion *source, const SDL_GPUTransferBufferLocation *destination) To transfer buf (fence sync).
SDL_CopyGPUTextureToTexture SDL_CopyGPUTextureToTexture(SDL_GPUCopyPass *copy_pass, const SDL_GPUTextureLocation *source, const SDL_GPUTextureLocation *destination, Uint32 w, Uint32 h, Uint32 d, bool cycle) GPU-GPU copies.