mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-11-03 09:14:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

GPU: Simultaneous compute pass read-write (#10965)

Browse Source
This commit is contained in:
Evan Hemsley
2024-09-27 12:49:37 -07:00
committed by GitHub
parent d39acc6d1e
commit 05d0656bd6
8 changed files with 241 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
include/SDL3/SDL_gpu.h
View File

@@ -464,18 +464,24 @@ typedef enum SDL_GPUTextureFormat
* A texture must have at least one usage flag. Note that some usage flag
* combinations are invalid.
*
* \since This enum is available since SDL 3.0.0
* 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.0.0
*
* \sa SDL_CreateGPUTexture
*/
typedef Uint32 SDL_GPUTextureUsageFlags;
#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */
#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */
#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */
#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */
#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */
#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */
#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */
#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */
/**
* Specifies the type of a texture.
@@ -536,18 +542,21 @@ typedef enum SDL_GPUCubeMapFace
* A buffer must have at least one usage flag. Note that some usage flag
* combinations are invalid.
*
* \since This enum is available since SDL 3.0.0
* Unlike textures, READ | WRITE can be used for simultaneous read-write usage.
* The same data synchronization concerns as textures apply.
*
* \since This datatype is available since SDL 3.0.0
*
* \sa SDL_CreateGPUBuffer
*/
typedef Uint32 SDL_GPUBufferUsageFlags;
#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */
#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */
#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */
#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */
#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */
#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */
#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */
#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */
/**
* Specifies how a transfer buffer is intended to be used by the client.
@@ -811,7 +820,7 @@ typedef enum SDL_GPUBlendFactor
/**
* Specifies which color components are written in a graphics pipeline.
*
* \since This enum is available since SDL 3.0.0
* \since This datatype is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
@@ -1489,8 +1498,8 @@ typedef struct SDL_GPUComputePipelineCreateInfo
Uint32 num_samplers; /**< The number of samplers defined in the shader. */
Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */
Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */
Uint32 num_writeonly_storage_textures; /**< The number of writeonly storage textures defined in the shader. */
Uint32 num_writeonly_storage_buffers; /**< The number of writeonly storage buffers defined in the shader. */
Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */
Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */
Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */
Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */
Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */
@@ -1667,14 +1676,14 @@ typedef struct SDL_GPUTextureSamplerBinding
*
* \sa SDL_BeginGPUComputePass
*/
typedef struct SDL_GPUStorageBufferWriteOnlyBinding
typedef struct SDL_GPUStorageBufferReadWriteBinding
{
SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */
bool cycle; /**< true cycles the buffer if it is already bound. */
bool cycle; /**< true cycles the buffer if it is already bound. */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
} SDL_GPUStorageBufferWriteOnlyBinding;
} SDL_GPUStorageBufferReadWriteBinding;
/**
* A structure specifying parameters related to binding textures in a compute
@@ -1684,16 +1693,16 @@ typedef struct SDL_GPUStorageBufferWriteOnlyBinding
*
* \sa SDL_BeginGPUComputePass
*/
typedef struct SDL_GPUStorageTextureWriteOnlyBinding
typedef struct SDL_GPUStorageTextureReadWriteBinding
{
SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE. */
SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */
Uint32 mip_level; /**< The mip level index to bind. */
Uint32 layer; /**< The layer index to bind. */
bool cycle; /**< true cycles the texture if it is already bound. */
bool cycle; /**< true cycles the texture if it is already bound. */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
} SDL_GPUStorageTextureWriteOnlyBinding;
} SDL_GPUStorageTextureReadWriteBinding;
/* Functions */
@@ -2807,17 +2816,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass(
* Begins a compute pass on a command buffer.
*
* A compute pass is defined by a set of texture subresources and buffers that
* will be written to by compute pipelines. These textures and buffers must
* have been created with the COMPUTE_STORAGE_WRITE bit. All operations
* 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 Textures and buffers bound as write-only MUST NOT be
* read from during the compute pass. Doing so will result in undefined
* behavior. If your compute work requires reading the output from a previous
* 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.
* 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!
*
* \param command_buffer a command buffer.
* \param storage_texture_bindings an array of writeable storage texture
@@ -2836,9 +2850,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass(
*/
extern SDL_DECLSPEC SDL_GPUComputePass *SDLCALL SDL_BeginGPUComputePass(
SDL_GPUCommandBuffer *command_buffer,
const SDL_GPUStorageTextureWriteOnlyBinding *storage_texture_bindings,
const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings,
Uint32 num_storage_texture_bindings,
const SDL_GPUStorageBufferWriteOnlyBinding *storage_buffer_bindings,
const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings,
Uint32 num_storage_buffer_bindings);
/**