(This is the documentation for SDL3, which is under heavy development and the API is changing! SDL2 is the current stable version!)

SDL_BeginGPURenderPass

Begins a render pass on a command buffer.

Header File

Syntax

SDL_GPURenderPass* SDL_BeginGPURenderPass(
    SDL_GPUCommandBuffer *command_buffer,
    const SDL_GPUColorTargetInfo *color_target_infos,
    Uint32 num_color_targets,
    const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info);

Function Parameters

SDL_GPUCommandBuffer *	command_buffer	a command buffer.
const SDL_GPUColorTargetInfo *	color_target_infos	an array of texture subresources with corresponding clear values and load/store ops.
Uint32	num_color_targets	the number of color targets in the color_target_infos array.
const SDL_GPUDepthStencilTargetInfo *	depth_stencil_target_info	a texture subresource with corresponding clear value and load/store ops, may be NULL.

Return Value

(SDL_GPURenderPass *) Returns a render pass handle.

Remarks

A render pass consists of a set of texture subresources (or depth slices in the 3D texture case) which will be rendered to during the render pass, along with corresponding clear values and load/store operations. All operations related to graphics pipelines must take place inside of a render pass. A default viewport and scissor state are automatically set when this is called. You cannot begin another render pass, or begin a compute pass or copy pass until you have ended the render pass.

Version

This function is available since SDL 3.0.0.

D3D12 Warnings

On D3D12 with debug_mode enabled, when clearing a color texture or depth/stencil texture, you may see a CLEARRENDERTARGETVIEW_MISMATCHINGCLEARVALUE or CLEARDEPTHSTENCILVIEW_MISMATCHINGCLEARVALUE warning at runtime like:

D3D12 WARNING: ... The clear values do not match those passed to resource creation. The clear operation is typically slower as a result; but will still clear to the desired value.

You can avoid these warnings by, when creating the texture, setting the relevant properties below, in the props of your SDL_GPUTextureCreateInfo, to the same clear color/depth/stencil value that you use in your render pass.

For the color texture: