Create a texture for a rendering context with the specified properties.
Defined in <SDL3/SDL_render.h>
SDL_Texture * SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props);| SDL_Renderer * | renderer | the rendering context. |
| SDL_PropertiesID | props | the properties to use. |
(SDL_Texture *) Returns the created texture or NULL on failure; call SDL_GetError() for more information.
These are the supported properties:
SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER: an SDL_Colorspace value describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures, SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for YUV textures.SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER: one of the enumerated values in SDL_PixelFormat, defaults to the best RGBA format for the rendererSDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER: one of the enumerated values in SDL_TextureAccess, defaults to SDL_TEXTUREACCESS_STATICSDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER: the width of the texture in pixels, requiredSDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER: the height of the texture in pixels, requiredSDL_PROP_TEXTURE_CREATE_PALETTE_POINTER: an SDL_Palette to use with palettized texture formats. This can be set later with SDL_SetTexturePalette()SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT: for HDR10 and floating point textures, this defines the value of 100% diffuse white, with higher values being displayed in the High Dynamic Range headroom. For HDR10 textures this is in nits and defaults to 203. For floating point textures this is a linear value and defaults to 1.0.SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT: for HDR10 and floating point textures, this defines the maximum dynamic range used by the content, as a multiple of the SDR white point. This would be equivalent to maxCLL / SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT for HDR10 content. If this is defined and larger than the output HDR headroom, the content will be tone mapped to fit.With the direct3d11 renderer:
SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER: the ID3D11Texture2D associated with the texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER: the ID3D11Texture2D associated with the U plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER: the ID3D11Texture2D associated with the V plane of a YUV texture, if you want to wrap an existing texture.With the direct3d12 renderer:
SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER: the ID3D12Resource associated with the texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER: the ID3D12Resource associated with the U plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER: the ID3D12Resource associated with the V plane of a YUV texture, if you want to wrap an existing texture.With the metal renderer:
SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER: the CVPixelBufferRef associated with the texture, if you want to create a texture from an existing pixel buffer.SDL_PROP_TEXTURE_CREATE_METAL_TEXTURE_POINTER: the MTLTexture associated with the texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_METAL_TEXTURE_UV_POINTER: the MTLTexture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_METAL_TEXTURE_U_POINTER: the MTLTexture associated with the U plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_METAL_TEXTURE_V_POINTER: the MTLTexture associated with the V plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_METAL_TEXTURE_USAGE_NUMBER: any additional MTLTextureUsage that this texture should have, defaults to 0.With the opengl renderer:
SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER: the GLuint texture associated with the texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER: the GLuint texture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER: the GLuint texture associated with the U plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER: the GLuint texture associated with the V plane of a YUV texture, if you want to wrap an existing texture.With the opengles2 renderer:
SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER: the GLuint texture associated with the texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER: the GLuint texture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER: the GLuint texture associated with the U plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER: the GLuint texture associated with the V plane of a YUV texture, if you want to wrap an existing texture.With the vulkan renderer:
SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER: the VkImage associated with the texture, if you want to wrap an existing texture. For NV12 style textures this can be a single two plane VkImage holding both the Y and UV planes, and for YUV style textures it is the VkImage holding the Y plane.SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_UV_NUMBER: the VkImage associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_U_NUMBER: the VkImage associated with the U plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_V_NUMBER: the VkImage associated with the V plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_VULKAN_LAYOUT_NUMBER: the VkImageLayout for the VkImage, defaults to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.SDL_PROP_TEXTURE_CREATE_VULKAN_USAGE_NUMBER: additional VK_IMAGE_USAGE bits that should be used when creating the texture. VkImage, defaults to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.SDL_PROP_TEXTURE_CREATE_VULKAN_ANDROID_HARDWARE_BUFFER_POINTER: the AHardwareBuffer to sample from, if you want to use an existing Android hardware buffer as the texture. You must use SDL_PIXELFORMAT_EXTERNAL_OES for the texture format. You can't directly update the texture or use it as a render target. If the Android buffer contents change, you must recreate the texture to pick up the changes. The texture holds a reference to the buffer, so you can release your own reference once the texture has been created.With the GPU renderer:
SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_POINTER: the SDL_GPUTexture associated with the texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_NUMBER: the SDL_GPUTexture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_U_NUMBER: the SDL_GPUTexture associated with the U plane of a YUV texture, if you want to wrap an existing texture.SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_V_NUMBER: the SDL_GPUTexture associated with the V plane of a YUV texture, if you want to wrap an existing texture.This function should only be called on the main thread.
This function is available since SDL 3.2.0.