SDL_CreateGPUTexture(3)

💖 SDL_CreateGPUTexture 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual — today's main character is SDL_CreateGPUTexture, and she is literally the girl who makes textures for your graphics and compute workflows. ✨

---

🌸 NAME 🌸

SDL_CreateGPUTexture — Creates a texture object to be used in graphics or compute workflows.

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_gpu.h>

SDL_GPUTexture * SDL_CreateGPUTexture(
    SDL_GPUDevice *device,
    const SDL_GPUTextureCreateInfo *createinfo);

---

✨ DESCRIPTION ✨

so, real talk: the contents of this texture are undefined until you actually write data to it. that's not me being dramatic, that's just the vibe. you write to it either by calling SDL_UploadToGPUTexture, or by running a render or compute pass with this texture as a target. no data written = mystery texture. 🙈

alsooo, heads up: certain combos of usage flags are invalid, and the implementation will not be nice about it. for example, a texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags. like, pick a lane bestie. 💅

and if you ask for a sample count higher than the hardware actually supports? no crash, no drama — the implementation will automatically fall back to the highest available sample count. she's adaptable. 🦋

there are also optional properties you can hand over through SDL_GPUTextureCreateInfo's props. these are the supported ones:

• SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT — (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this red intensity. Defaults to zero.
• SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT — (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this green intensity. Defaults to zero.
• SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT — (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this blue intensity. Defaults to zero.
• SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT — (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this alpha intensity. Defaults to zero.
• SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT — (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear the texture to a depth of this value. Defaults to zero.
• SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER — (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear the texture to a stencil of this Uint8 value. Defaults to zero.
• SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING — a name that can be displayed in debugging tools.

not me listing every single one of those D3D12 clear props 💀 they all default to zero, they're all Direct3D 12 only, and the color ones only kick in for SDL_GPU_TEXTUREUSAGE_COLOR_TARGET while the depth/stencil ones only kick in for SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET. iykyk. 🫶

---

🧚 FUNCTION PARAMETERS 🧚

• device — a GPU Context. (yes queen, the whole context. 👑)
• createinfo — a struct describing the state of the texture to create.

---

⭐ RETURN VALUE ⭐

Returns a texture object on success, or NULL on failure. if you get NULL, go call SDL_GetError() for more information — she will tell you what went wrong, fr fr. 😭

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0.

---

💜 SEE ALSO 💜

• SDL_UploadToGPUTexture(3)
• SDL_DownloadFromGPUTexture(3)
• SDL_BeginGPURenderPass(3)
• SDL_BeginGPUComputePass(3)
• SDL_BindGPUVertexSamplers(3)
• SDL_BindGPUVertexStorageTextures(3)
• SDL_BindGPUFragmentSamplers(3)
• SDL_BindGPUFragmentStorageTextures(3)
• SDL_BindGPUComputeStorageTextures(3)
• SDL_BlitGPUTexture(3)
• SDL_ReleaseGPUTexture(3)
• SDL_GPUTextureSupportsFormat(3)

---

and that's the whole page, bestie!! 🎀 go forth and create textures, you absolute icon. this lil writeup came to you straight from Simple Directmedia Layer, version SDL 3.4.18, and yeah the SDL_CreateGPUTexture(3) header was right there in the corner the whole time. slay, mwah 💖✨🔥