sdlCreateTextureWithProperties function render

Pointer<SdlTexture> sdlCreateTextureWithProperties(
  1. Pointer<SdlRenderer> renderer,
  2. int props
)

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

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_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.

\param renderer the rendering context. \param props the properties to use. \returns the created texture or NULL on failure; call SDL_GetError() for more information.

\threadsafety This function should only be called on the main thread.

\since This function is available since SDL 3.2.0.

\sa SDL_CreateProperties \sa SDL_CreateTexture \sa SDL_CreateTextureFromSurface \sa SDL_DestroyTexture \sa SDL_GetTextureSize \sa SDL_UpdateTexture

extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props)

See also:

Implementation

Pointer<SdlTexture> sdlCreateTextureWithProperties(
  Pointer<SdlRenderer> renderer,
  int props,
) {
  final sdlCreateTextureWithPropertiesLookupFunction = _libSdl
      .lookupFunction<
        Pointer<SdlTexture> Function(
          Pointer<SdlRenderer> renderer,
          Uint32 props,
        ),
        Pointer<SdlTexture> Function(Pointer<SdlRenderer> renderer, int props)
      >('SDL_CreateTextureWithProperties');
  return sdlCreateTextureWithPropertiesLookupFunction(renderer, props);
}