diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h index 674ead366..dcf393b18 100644 --- a/include/SDL3/SDL_gpu.h +++ b/include/SDL3/SDL_gpu.h @@ -307,28 +307,71 @@ typedef enum SDL_GPUIndexElementSize * a format is supported before using it. However, there are a few guaranteed * formats. * - * 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 SAMPLER usage, the following formats are universally supported: * - * 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 + * - 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 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 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_SFLOAT - Either (but not necessarily both!) D24_UNORM_S8_UINT or - * D32_SFLOAT_S8_UINT + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_SFLOAT_S8_UINT * * Unless D16_UNORM is sufficient for your purposes, always check which of * D24/D32 is supported before creating a depth-stencil texture! @@ -664,7 +707,7 @@ typedef enum SDL_GPUCullMode typedef enum SDL_GPUFrontFace { SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ - SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise winding vertex winding will be considered front-facing. */ + SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */ } SDL_GPUFrontFace; /** @@ -820,13 +863,14 @@ typedef enum SDL_GPUSamplerAddressMode * It is recommended to query SDL_WindowSupportsGPUPresentMode 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 + * - 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. When using this present * mode, AcquireSwapchainTexture will block if too many frames are in flight. - * IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may * occur. When using this mode, AcquireSwapchainTexture will return NULL if - * too many frames are in flight. MAILBOX: Waits for vblank before presenting. + * too many frames are in flight. + * - 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. When using this mode, AcquireSwapchainTexture will return @@ -855,11 +899,14 @@ typedef enum SDL_GPUPresentMode * claiming the window if you wish to change the swapchain composition from * SDR. * - * SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB - * encoding. SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel - * values are in nonlinear sRGB encoding. HDR_EXTENDED_LINEAR: + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB + * encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel + * values are in nonlinear sRGB encoding. + * - HDR_EXTENDED_LINEAR: * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear - * encoding. HDR10_ST2048: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values + * encoding. + * - HDR10_ST2048: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values * are in PQ ST2048 encoding. * * \since This enum is available since SDL 3.0.0 @@ -1462,25 +1509,30 @@ extern SDL_DECLSPEC SDL_GPUDriver SDLCALL SDL_GetGPUDriver(SDL_GPUDevice *device /** * Creates a pipeline object to be used in a compute workflow. * - * Shader resource bindings must be authored to follow a particular order. For - * SPIR-V shaders, use the following resource sets: 0: Read-only storage - * textures, followed by read-only storage buffers 1: Write-only storage - * textures, followed by write-only storage buffers 2: Uniform buffers + * Shader resource bindings must be authored to follow a particular order depending on the shader format. * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Read-only storage textures, followed by read-only storage - * buffers For u registers: Write-only storage textures, followed by - * write-only storage buffers For b registers: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXIL shaders, use the following register order: (t[n], space0): - * Read-only storage textures, followed by read-only storage buffers (u[n], - * space1): Write-only storage textures, followed by write-only storage - * buffers (b[n], space2): Uniform buffers + * - 0: Read-only storage textures, followed by read-only storage buffers + * - 1: Write-only storage textures, followed by write-only storage buffers + * - 2: Uniform buffers * - * For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers, - * followed by write-only storage buffers, followed by write-only storage - * buffers For [[texture]]: Read-only storage textures, followed by write-only - * storage textures + * For DXBC Shader Model 5_0 shaders, use the following register order: + * + * - t registers: Read-only storage textures, followed by read-only storage buffers + * - u registers: Write-only storage textures, followed by write-only storage buffers + * - b registers: Uniform buffers + * + * For DXIL shaders, use the following register order: + * + * - (t[n], space0): Read-only storage textures, followed by read-only storage buffers + * - (u[n], space1): Write-only storage textures, followed by write-only storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by write-only storage buffers, followed by write-only storage buffers + * - [[texture]]: Read-only storage textures, followed by write-only storage textures * * \param device a GPU Context. * \param computePipelineCreateInfo a struct describing the state of the @@ -1536,31 +1588,49 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( /** * Creates a shader to be used when creating a graphics pipeline. * - * Shader resource bindings must be authored to follow a particular order - * depending on the shader format. + * 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 SPIR-V shaders, use the following resource sets: * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Sampled textures, followed by storage textures, followed by - * storage buffers For s registers: Samplers with indices corresponding to the - * sampled textures For b registers: Uniform buffers + * For vertex shaders: * - * For 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 + * - 0: Sampled textures, followed by storage textures, followed by storage buffers + * - 1: Uniform buffers * - * For MSL/metallib, use the following order: For [[texture]]: Sampled - * textures, followed by storage textures For [[sampler]]: Samplers with - * indices corresponding to the sampled textures For [[buffer]]: Uniform - * buffers, followed by storage buffers. Vertex buffer 0 is bound at + * For fragment shaders: + * + * - 2: Sampled textures, followed by storage textures, followed by storage buffers + * - 3: Uniform buffers + * + * For DXBC Shader Model 5_0 shaders, use the following register order: + * + * - t registers: Sampled textures, followed by storage textures, followed by storage buffers + * - s registers: Samplers with indices corresponding to the sampled textures + * - b registers: Uniform buffers + * + * For 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(30)]], vertex buffer 1 at [[buffer(29)]], 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