SDL_CreateGPUTexture(3)

Usage

#include "SDL3/SDL.h"

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

Header file

Defined in SDL3/SDL_gpu.h

Overview

The contents of this texture are undefined until data is written to the texture.

Note that certain combinations of usage flags are invalid. For example, a texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags.

If you request a sample count higher than the hardware supports, the implementation will automatically fall back to the highest available sample count.

There are optional properties that can be provided through

SDL_GPUTextureCreateInfo props . These are the supported properties:

• 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_UINT8 :
(Direct3D 12 only) if the texture usage is

SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET ,
clear the texture to a stencil of this value. Defaults to zero.

• SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING :
a name that can be displayed in debugging tools.

Function parameters

`device`	a GPU Context.
`createinfo`	a struct describing the state of the texture to create.

Return value

( SDL_GPUTexture
*) Returns a texture object on success, or NULL on failure; call SDL_GetError () for more information.

SDL_UploadToGPUTexture(3) Uploads data from a transfer buffer to a texture. SDL_DownloadFromGPUTexture(3) Copies data from a texture to a transfer buffer on the GPU timeline. SDL_BindGPUVertexSamplers(3) Binds texture-sampler pairs for use on the vertex shader. SDL_BindGPUVertexStorageTextures(3) Binds storage textures for use on the vertex shader. SDL_BindGPUFragmentSamplers(3) Binds texture-sampler pairs for use on the fragment shader. SDL_BindGPUFragmentStorageTextures(3) Binds storage textures for use on the fragment shader. SDL_BindGPUComputeStorageTextures(3) Binds storage textures as readonly for use on the compute pipeline. SDL_BlitGPUTexture(3) Blits from a source texture region to a destination texture region. SDL_ReleaseGPUTexture(3) Frees the given texture as soon as it is safe to do so. SDL_GPUTextureSupportsFormat(3) Determines whether a texture format is supported for a given type and usage.

Referred to by

SDL_GPUTexture(3type) An opaque handle representing a texture. SDL_GPUSampleCount(3type) Specifies the sample count of a texture. SDL_GPUTextureType(3type) Specifies the type of a texture. SDL_GPUTextureFormat(3type) Specifies the pixel format of a texture. SDL_GPUTextureRegion(3type) A structure specifying a region of a texture. SDL_SetGPUTextureName(3) Sets an arbitrary string constant to label a texture. SDL_GPUTextureCreateInfo(3type) A structure specifying the parameters of a texture. SDL_GPUTextureUsageFlags(3type) Specifies how a texture is intended to be used by the client.