NAME

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

SYNOPSIS

       #include <SDL3/SDL_render.h>

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

DESCRIPTION

       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 renderer

       •  SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER:  one of the enumerated values in SDL_TextureAccess, defaults to
       SDL_TEXTUREACCESS_STATIC

       • SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER: the width of the texture in pixels, required

       • SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER: the height of the texture in pixels, required

       • 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. This
       defaults to 100 for HDR10 textures and 1.0 for floating point textures.

       • SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT: for HDR10 and floating point  textures,  this  defines  the
       maximum  dynamic  range used by the content, in terms 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, any  values
       outside the range supported by the display will be scaled into the available HDR headroom, otherwise they
       are clipped.

       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.

       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_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        with        layout
       VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL  associated  with  the  texture, if you want to wrap an existing
       texture.

FUNCTION PARAMETERS

       renderer
              the rendering context.

       props  the properties to use.

RETURN VALUE

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

THREAD SAFETY

       This function should only be called on the main thread.

AVAILABILITY

       This function is available since SDL 3.2.0.

SEE ALSO

       SDL_CreateProperties(3),  SDL_CreateTexture(3),  SDL_CreateTextureFromSurface(3),  SDL_DestroyTexture(3),
       SDL_GetTextureSize(3), SDL_UpdateTexture(3)

Simple Directmedia Layer                           SDL 3.2.20                 SDL_CreateTextureWithProperties(3)