# SDL_CreateTextureWithProperties

Create a texture for a rendering context with the specified properties.

## Header File

Defined in [<SDL3/SDL_render.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_render.h)

## Syntax

```c
SDL_Texture * SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props);
```

## Function Parameters

|                                      |              |                        |
| ------------------------------------ | ------------ | ---------------------- |
| [SDL_Renderer](SDL_Renderer) *       | **renderer** | the rendering context. |
| [SDL_PropertiesID](SDL_PropertiesID) | **props**    | the properties to use. |

## Return Value

([SDL_Texture](SDL_Texture) *) Returns the created texture or NULL on
failure; call [SDL_GetError](SDL_GetError)() for more information.

## Remarks

These are the supported properties:

- [`SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`](SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER):
  an [SDL_Colorspace](SDL_Colorspace) value describing the texture
  colorspace, defaults to
  [SDL_COLORSPACE_SRGB_LINEAR](SDL_COLORSPACE_SRGB_LINEAR) for floating
  point textures, [SDL_COLORSPACE_HDR10](SDL_COLORSPACE_HDR10) for 10-bit
  textures, [SDL_COLORSPACE_SRGB](SDL_COLORSPACE_SRGB) for other RGB
  textures and [SDL_COLORSPACE_JPEG](SDL_COLORSPACE_JPEG) for YUV textures.
- [`SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER`](SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER):
  one of the enumerated values in [SDL_PixelFormat](SDL_PixelFormat),
  defaults to the best RGBA format for the renderer
- [`SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER`](SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER):
  one of the enumerated values in [SDL_TextureAccess](SDL_TextureAccess),
  defaults to [SDL_TEXTUREACCESS_STATIC](SDL_TEXTUREACCESS_STATIC)
- [`SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER`](SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER):
  the width of the texture in pixels, required
- [`SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER`](SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER):
  the height of the texture in pixels, required
- [`SDL_PROP_TEXTURE_CREATE_PALETTE_POINTER`](SDL_PROP_TEXTURE_CREATE_PALETTE_POINTER):
  an [SDL_Palette](SDL_Palette) to use with palettized texture formats.
  This can be set later with
  [SDL_SetTexturePalette](SDL_SetTexturePalette)()
- [`SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT`](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`](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](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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`](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](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`](SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_POINTER):
  the [SDL_GPUTexture](SDL_GPUTexture) associated with the texture, if you
  want to wrap an existing texture.
- [`SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_NUMBER`](SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_NUMBER):
  the [SDL_GPUTexture](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`](SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_U_NUMBER):
  the [SDL_GPUTexture](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`](SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_V_NUMBER):
  the [SDL_GPUTexture](SDL_GPUTexture) associated with the V plane of a YUV
  texture, if you want to wrap an existing texture.

## Thread Safety

This function should only be called on the main thread.

## Version

This function is available since SDL 3.2.0.

## See Also

- [SDL_CreateProperties](SDL_CreateProperties)
- [SDL_CreateTexture](SDL_CreateTexture)
- [SDL_CreateTextureFromSurface](SDL_CreateTextureFromSurface)
- [SDL_DestroyTexture](SDL_DestroyTexture)
- [SDL_GetTextureSize](SDL_GetTextureSize)
- [SDL_UpdateTexture](SDL_UpdateTexture)

----
[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryRender](CategoryRender)