eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-06-03 10:27:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Sync SDL3 wiki -> header

Browse source
This commit is contained in:
SDL Wiki Bot 2024-09-05 01:25:36 +00:00
parent 1c8c014481
commit 249a74e436
1 changed files with 100 additions and 125 deletions
Download patch file Download diff file Expand all files Collapse all files

225
include/SDL3/SDL_gpu.h
View file

@ -54,7 +54,8 @@ typedef struct SDL_GPUDevice SDL_GPUDevice;
/** /**
* An opaque handle representing a buffer. * An opaque handle representing a buffer.
* *
* Used for vertices, indices, indirect draw commands, and general compute data. * Used for vertices, indices, indirect draw commands, and general compute
* data.
* *
* \since This struct is available since SDL 3.0.0 * \since This struct is available since SDL 3.0.0
* *
@ -166,17 +167,20 @@ typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline;
/** /**
* An opaque handle representing a command buffer. * An opaque handle representing a command buffer.
* *
* Most state is managed via command buffers. * Most state is managed via command buffers. When setting state using a
* When setting state using a command buffer, that state is local to the command buffer. * command buffer, that state is local to the command buffer.
* *
* Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is called. * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is
* Once the command buffer is submitted, it is no longer valid to use it. * called. Once the command buffer is submitted, it is no longer valid to use
* it.
* *
* Command buffers are executed in submission order. If you submit command buffer A and then command buffer B * Command buffers are executed in submission order. If you submit command
* all commands in A will begin executing before any command in B begins executing. * buffer A and then command buffer B all commands in A will begin executing
* before any command in B begins executing.
* *
* In multi-threading scenarios, you should acquire and submit a command buffer on the same thread. * In multi-threading scenarios, you should acquire and submit a command
* As long as you satisfy this requirement, all functionality related to command buffers is thread-safe. * buffer on the same thread. As long as you satisfy this requirement, all
* functionality related to command buffers is thread-safe.
* *
* \since This struct is available since SDL 3.0.0 * \since This struct is available since SDL 3.0.0
* *
@ -189,7 +193,8 @@ typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer;
/** /**
* An opaque handle representing a render pass. * An opaque handle representing a render pass.
* *
* This handle is transient and should not be held or referenced after SDL_EndGPURenderPass is called. * This handle is transient and should not be held or referenced after
* SDL_EndGPURenderPass is called.
* *
* \since This struct is available since SDL 3.0.0 * \since This struct is available since SDL 3.0.0
* *
@ -201,7 +206,8 @@ typedef struct SDL_GPURenderPass SDL_GPURenderPass;
/** /**
* An opaque handle representing a compute pass. * An opaque handle representing a compute pass.
* *
* This handle is transient and should not be held or referenced after SDL_EndGPUComputePass is called. * This handle is transient and should not be held or referenced after
* SDL_EndGPUComputePass is called.
* *
* \since This struct is available since SDL 3.0.0 * \since This struct is available since SDL 3.0.0
* *
@ -213,7 +219,8 @@ typedef struct SDL_GPUComputePass SDL_GPUComputePass;
/** /**
* An opaque handle representing a copy pass. * An opaque handle representing a copy pass.
* *
* This handle is transient and should not be held or referenced after SDL_EndGPUCopyPass is called. * This handle is transient and should not be held or referenced after
* SDL_EndGPUCopyPass is called.
* *
* \since This struct is available since SDL 3.0.0 * \since This struct is available since SDL 3.0.0
* *
@ -251,7 +258,8 @@ typedef enum SDL_GPUPrimitiveType
} SDL_GPUPrimitiveType; } SDL_GPUPrimitiveType;
/** /**
* Specifies how the contents of a texture attached to a render pass are treated at the beginning of the render pass. * Specifies how the contents of a texture attached to a render pass are
* treated at the beginning of the render pass.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -265,7 +273,8 @@ typedef enum SDL_GPULoadOp
} SDL_GPULoadOp; } SDL_GPULoadOp;
/** /**
* Specifies how the contents of a texture attached to a render pass are treated at the end of the render pass. * Specifies how the contents of a texture attached to a render pass are
* treated at the end of the render pass.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -293,73 +302,36 @@ typedef enum SDL_GPUIndexElementSize
/** /**
* Specifies the pixel format of a texture. * Specifies the pixel format of a texture.
* *
* Texture format support varies depending on driver, hardware, and usage flags. * Texture format support varies depending on driver, hardware, and usage
* In general, you should use SDL_GPUTextureSupportsFormat to query if a format * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if
* is supported before using it. However, there are a few guaranteed formats. * a format is supported before using it. However, there are a few guaranteed
* formats.
* *
* For SAMPLER usage, the following formats are universally supported: * For SAMPLER usage, the following formats are universally supported: -
* - R8G8B8A8_UNORM * R8G8B8A8_UNORM - B8G8R8A8_UNORM - R8_UNORM - R8_SNORM - R8G8_UNORM -
* - B8G8R8A8_UNORM * R8G8_SNORM - R8G8B8A8_SNORM - R16_FLOAT - R16G16_FLOAT - R16G16B16A16_FLOAT
* - R8_UNORM * - R32_FLOAT - R32G32_FLOAT - R32G32B32A32_FLOAT - R11G11B10_UFLOAT -
* - R8_SNORM * R8G8B8A8_UNORM_SRGB - B8G8R8A8_UNORM_SRGB - D16_UNORM
* - 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: * For COLOR_TARGET usage, the following formats are universally supported: -
* - R8G8B8A8_UNORM * R8G8B8A8_UNORM - B8G8R8A8_UNORM - R8_UNORM - R16_FLOAT - R16G16_FLOAT -
* - B8G8R8A8_UNORM * R16G16B16A16_FLOAT - R32_FLOAT - R32G32_FLOAT - R32G32B32A32_FLOAT -
* - R8_UNORM * R8_UINT - R8G8_UINT - R8G8B8A8_UINT - R16_UINT - R16G16_UINT -
* - R16_FLOAT * R16G16B16A16_UINT - R8_INT - R8G8_INT - R8G8B8A8_INT - R16_INT - R16G16_INT
* - R16G16_FLOAT * - R16G16B16A16_INT - R8G8B8A8_UNORM_SRGB - B8G8R8A8_UNORM_SRGB
* - 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: * For STORAGE usages, the following formats are universally supported: -
* - R8G8B8A8_UNORM * R8G8B8A8_UNORM - R8G8B8A8_SNORM - R16G16B16A16_FLOAT - R32_FLOAT -
* - R8G8B8A8_SNORM * R32G32_FLOAT - R32G32B32A32_FLOAT - R8G8B8A8_UINT - R16G16B16A16_UINT -
* - R16G16B16A16_FLOAT * R8G8B8A8_INT - R16G16B16A16_INT
* - 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: * For DEPTH_STENCIL_TARGET usage, the following formats are universally
* - D16_UNORM * supported: - D16_UNORM - Either (but not necessarily both!) D24_UNORM or
* - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT * D32_SFLOAT - Either (but not necessarily both!) D24_UNORM_S8_UINT or
* - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_SFLOAT_S8_UINT * D32_SFLOAT_S8_UINT
* *
* Unless D16_UNORM is sufficient for your purposes, always check which * Unless D16_UNORM is sufficient for your purposes, always check which of
* of D24/D32 is supported before creating a depth-stencil texture! * D24/D32 is supported before creating a depth-stencil texture!
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -443,8 +415,8 @@ typedef enum SDL_GPUTextureFormat
/** /**
* Specifies how a texture is intended to be used by the client. * Specifies how a texture is intended to be used by the client.
* *
* A texture must have at least one usage flag. * A texture must have at least one usage flag. Note that some usage flag
* Note that some usage flag combinations are invalid. * combinations are invalid.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -477,8 +449,8 @@ typedef enum SDL_GPUTextureType
/** /**
* Specifies the sample count of a texture. * Specifies the sample count of a texture.
* *
* Used in multisampling. * Used in multisampling. Note that this value only applies when the texture
* Note that this value only applies when the texture is used as a render pass attachment. * is used as a render pass attachment.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -514,8 +486,8 @@ typedef enum SDL_GPUCubeMapFace
/** /**
* Specifies how a buffer is intended to be used by the client. * Specifies how a buffer is intended to be used by the client.
* *
* A buffer must have at least one usage flag. * A buffer must have at least one usage flag. Note that some usage flag
* Note that some usage flag combinations are invalid. * combinations are invalid.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -533,7 +505,8 @@ typedef Uint32 SDL_GPUBufferUsageFlags;
/** /**
* Specifies how a transfer buffer is intended to be used by the client. * Specifies how a transfer buffer is intended to be used by the client.
* *
* Note that mapping and copying FROM an upload transfer buffer or TO a download transfer buffer is undefined behavior. * 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.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -681,7 +654,8 @@ typedef enum SDL_GPUCullMode
} SDL_GPUCullMode; } SDL_GPUCullMode;
/** /**
* Specifies the vertex winding that will cause a triangle to be determined to be front-facing. * Specifies the vertex winding that will cause a triangle to be determined to
* be front-facing.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -713,7 +687,8 @@ typedef enum SDL_GPUCompareOp
} SDL_GPUCompareOp; } SDL_GPUCompareOp;
/** /**
* Specifies what happens to a stored stencil value if stencil tests fail or pass. * Specifies what happens to a stored stencil value if stencil tests fail or
* pass.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -732,10 +707,11 @@ typedef enum SDL_GPUStencilOp
} SDL_GPUStencilOp; } SDL_GPUStencilOp;
/** /**
* Specifies the operator to be used when pixels in a render pass texture attachment are blended with existing pixels in the texture. * Specifies the operator to be used when pixels in a render pass texture
* attachment are blended with existing pixels in the texture.
* *
* The source color is the value written by the fragment shader. * The source color is the value written by the fragment shader. The
* The destination color is the value currently existing in the texture. * destination color is the value currently existing in the texture.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -751,11 +727,11 @@ typedef enum SDL_GPUBlendOp
} SDL_GPUBlendOp; } SDL_GPUBlendOp;
/** /**
* Specifies a blending factor to be used when pixels in a render pass texture attachment * Specifies a blending factor to be used when pixels in a render pass texture
* are blended with existing pixels in the texture. * attachment are blended with existing pixels in the texture.
* *
* The source color is the value written by the fragment shader. * The source color is the value written by the fragment shader. The
* The destination color is the value currently existing in the texture. * destination color is the value currently existing in the texture.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -819,7 +795,8 @@ typedef enum SDL_GPUSamplerMipmapMode
} SDL_GPUSamplerMipmapMode; } SDL_GPUSamplerMipmapMode;
/** /**
* Specifies behavior of texture sampling when the coordinates exceed the 0-1 range. * Specifies behavior of texture sampling when the coordinates exceed the 0-1
* range.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -833,29 +810,27 @@ typedef enum SDL_GPUSamplerAddressMode
} SDL_GPUSamplerAddressMode; } SDL_GPUSamplerAddressMode;
/** /**
* Specifies the timing that will be used to present swapchain textures to the OS. * Specifies the timing that will be used to present swapchain textures to the
* OS.
* *
* Note that this value affects the behavior of SDL_AcquireGPUSwapchainTexture. * Note that this value affects the behavior of
* VSYNC mode will always be supported. * SDL_AcquireGPUSwapchainTexture. VSYNC mode will always be supported.
* IMMEDIATE and MAILBOX modes may not be supported on certain systems. * IMMEDIATE and MAILBOX modes may not be supported on certain systems.
* *
* It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming the window * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming
* if you wish to change the present mode to IMMEDIATE or MAILBOX. * the window if you wish to change the present mode to IMMEDIATE or MAILBOX.
* *
* VSYNC: * VSYNC: Waits for vblank before presenting. No tearing is possible. If there
* Waits for vblank before presenting. No tearing is possible. * is a pending image to present, the new image is enqueued for presentation.
* 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
* Disallows tearing at the cost of visual latency. * mode, AcquireSwapchainTexture will block if too many frames are in flight.
* 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: * occur. When using this mode, AcquireSwapchainTexture will return NULL if
* Immediately presents. * too many frames are in flight. MAILBOX: Waits for vblank before presenting.
* Lowest latency option, but tearing may occur. * No tearing is possible. If there is a pending image to present, the pending
* When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. * image is replaced by the new image. Similar to VSYNC, but with reduced
* MAILBOX: * visual latency. When using this mode, AcquireSwapchainTexture will return
* Waits for vblank before presenting. No tearing is possible. * NULL if too many frames are in flight.
* 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 NULL if too many frames are in flight.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -873,20 +848,19 @@ typedef enum SDL_GPUPresentMode
/** /**
* Specifies the texture format and colorspace of the swapchain textures. * Specifies the texture format and colorspace of the swapchain textures.
* *
* SDR will always be supported. * SDR will always be supported. Other compositions may not be supported on
* Other compositions may not be supported on certain systems. * certain systems.
* *
* It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after claiming the window * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after
* if you wish to change the swapchain composition from SDR. * claiming the window if you wish to change the swapchain composition from
* SDR.
* *
* SDR: * SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB
* B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB encoding. * encoding. SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel
* SDR_LINEAR: * values are in nonlinear sRGB encoding. HDR_EXTENDED_LINEAR:
* B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in nonlinear sRGB encoding. * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear
* HDR_EXTENDED_LINEAR: * encoding. HDR10_ST2048: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values
* R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear encoding. * are in PQ ST2048 encoding.
* HDR10_ST2048:
* A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in PQ ST2048 encoding.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
* *
@ -2746,7 +2720,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUPresentMode(
* *
* The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and
* SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain
* parameters, you must call SDL_SetGPUSwapchainParameters after claiming the window. * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the
* window.
* *
* \param device a GPU context. * \param device a GPU context.
* \param window an SDL_Window. * \param window an SDL_Window.