mirror of
https://github.com/libsdl-org/SDL.git
synced 2025-05-23 04:59:10 +00:00
GPU: Revise swapchain acquisition (#11633)
--------- Co-authored-by: Lucas Murray <22484+lmurray@users.noreply.github.com>
This commit is contained in:
Evan Hemsley
GitHub
parent
bbd4eeb287
commit
3ee39f6c3f
9 changed files with 337 additions and 51 deletions
|
|
@ -1068,8 +1068,7 @@ typedef enum SDL_GPUSamplerAddressMode
|
|||
* Specifies the timing that will be used to present swapchain textures to the
|
||||
* OS.
|
||||
*
|
||||
* Note that this value affects the behavior of
|
||||
* SDL_AcquireGPUSwapchainTexture. VSYNC mode will always be supported.
|
||||
* VSYNC mode will always be supported.
|
||||
* IMMEDIATE and MAILBOX modes may not be supported on certain systems.
|
||||
*
|
||||
* It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming
|
||||
|
|
@ -1077,17 +1076,12 @@ typedef enum SDL_GPUSamplerAddressMode
|
|||
*
|
||||
* - 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, AcquireGPUSwapchainTexture will block if too many
|
||||
* frames are in flight.
|
||||
* presentation. Disallows tearing at the cost of visual latency.
|
||||
* - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may
|
||||
* occur. When using this mode, AcquireGPUSwapchainTexture will fill the
|
||||
* swapchain texture pointer with NULL if too many frames are in flight.
|
||||
* 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. When using
|
||||
* this mode, AcquireGPUSwapchainTexture will fill the swapchain texture
|
||||
* pointer with NULL if too many frames are in flight.
|
||||
* new image. Similar to VSYNC, but with reduced visual latency.
|
||||
*
|
||||
* \since This enum is available since SDL 3.1.3
|
||||
*
|
||||
|
|
@ -3442,6 +3436,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode(
|
|||
* \returns true on success, or false on failure; call SDL_GetError() for more
|
||||
* information.
|
||||
*
|
||||
* \threadsafety This function should only be called from the thread that created the window.
|
||||
*
|
||||
* \since This function is available since SDL 3.1.3.
|
||||
*
|
||||
* \sa SDL_AcquireGPUSwapchainTexture
|
||||
|
|
@ -3501,8 +3497,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters(
|
|||
*
|
||||
* 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, SDL_AcquireGPUSwapchainTexture() will block or
|
||||
* return false depending on the present mode.
|
||||
* working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the swapchain texture pointer with NULL,
|
||||
* and SDL_WaitAndAcquireGPUSwapchainTexture() will block.
|
||||
*
|
||||
* Higher values increase throughput at the expense of visual latency. Lower
|
||||
* values decrease visual latency at the expense of throughput.
|
||||
|
|
@ -3514,9 +3510,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters(
|
|||
*
|
||||
* \param device a GPU context.
|
||||
* \param allowed_frames_in_flight the maximum number of frames that can be
|
||||
* pending on the GPU before
|
||||
* AcquireSwapchainTexture blocks or returns
|
||||
* false.
|
||||
* pending on the GPU.
|
||||
* \returns true if successful, false on error; call SDL_GetError() for more
|
||||
* information.
|
||||
*
|
||||
|
|
@ -3547,20 +3541,17 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma
|
|||
* 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. The swapchain texture handle can be filled in
|
||||
* with NULL under certain conditions. This is not necessarily an error. If
|
||||
* this function returns false then there is an error.
|
||||
* buffer used to acquire it.
|
||||
*
|
||||
* This function will fill the swapchain texture handle with NULL if too many frames are in flight.
|
||||
* This is not an error.
|
||||
* The best practice is to call SDL_CancelGPUCommandBuffer if the swapchain texture
|
||||
* handle is NULL to avoid enqueuing needless work on the GPU.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* When using SDL_GPU_PRESENTMODE_VSYNC, this function will block if too many
|
||||
* frames are in flight. Otherwise, this function will fill the swapchain
|
||||
* texture handle with NULL if too many frames are in flight. The best
|
||||
* practice is to call SDL_CancelGPUCommandBuffer if the swapchain texture
|
||||
* handle is NULL to avoid enqueuing needless work on the GPU.
|
||||
*
|
||||
* \param command_buffer a command buffer.
|
||||
* \param window a window that has been claimed.
|
||||
* \param swapchain_texture a pointer filled in with a swapchain texture
|
||||
|
|
@ -3572,14 +3563,17 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma
|
|||
* \returns true on success, false on error; call SDL_GetError() for more
|
||||
* information.
|
||||
*
|
||||
* \threadsafety This function should only be called from the thread that created the window.
|
||||
*
|
||||
* \since This function is available since SDL 3.1.3.
|
||||
*
|
||||
* \sa SDL_GPUPresentMode
|
||||
* \sa SDL_ClaimWindowForGPUDevice
|
||||
* \sa SDL_SubmitGPUCommandBuffer
|
||||
* \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
||||
* \sa SDL_CancelGPUCommandBuffer
|
||||
* \sa SDL_GetWindowSizeInPixels
|
||||
* \sa SDL_WaitForGPUSwapchain
|
||||
* \sa SDL_SetGPUAllowedFramesInFlight
|
||||
*/
|
||||
extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture(
|
||||
SDL_GPUCommandBuffer *command_buffer,
|
||||
|
|
@ -3588,6 +3582,62 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture(
|
|||
Uint32 *swapchain_texture_width,
|
||||
Uint32 *swapchain_texture_height);
|
||||
|
||||
/**
|
||||
* Blocks the thread until a swapchain texture is available to be acquired.
|
||||
*
|
||||
* \param device a GPU context.
|
||||
* \param window a window that has been claimed.
|
||||
* \returns true on success, false on failure; call SDL_GetError() for more
|
||||
* information.
|
||||
*
|
||||
* \threadsafety This function should only be called from the thread that created the window.
|
||||
*
|
||||
* \since This function is available since SDL 3.2.0.
|
||||
*
|
||||
* \sa SDL_AcquireGPUSwapchainTexture
|
||||
* \sa SDL_SetGPUAllowedFramesInFlight
|
||||
*/
|
||||
extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain(
|
||||
SDL_GPUDevice *device,
|
||||
SDL_Window *window);
|
||||
|
||||
/**
|
||||
* Blocks the thread until a swapchain texture is available to be acquired, and then acquires it.
|
||||
*
|
||||
* 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 SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* \param command_buffer a command buffer.
|
||||
* \param window a window that has been claimed.
|
||||
* \param swapchain_texture a pointer filled in with a swapchain texture
|
||||
* handle.
|
||||
* \param swapchain_texture_width a pointer filled in with the swapchain
|
||||
* texture width, may be NULL.
|
||||
* \param swapchain_texture_height a pointer filled in with the swapchain
|
||||
* texture height, may be NULL.
|
||||
* \returns true on success, false on error; call SDL_GetError() for more
|
||||
* information.
|
||||
*
|
||||
* \threadsafety This function should only be called from the thread that created the window.
|
||||
*
|
||||
* \since This function is available since SDL 3.2.0.
|
||||
*
|
||||
* \sa SDL_SubmitGPUCommandBuffer
|
||||
* \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
||||
*/
|
||||
extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture(
|
||||
SDL_GPUCommandBuffer *command_buffer,
|
||||
SDL_Window *window,
|
||||
SDL_GPUTexture **swapchain_texture,
|
||||
Uint32 *swapchain_texture_width,
|
||||
Uint32 *swapchain_texture_height);
|
||||
|
||||
/**
|
||||
* Submits a command buffer so its commands can be processed on the GPU.
|
||||
*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue