SDL_CreateTe...ithProperties(3)

✨ NAME ✨

SDL_CreateTextureWithProperties — bestie, this one makes you a texture for a rendering context, and you get to pick the properties. it's giving bespoke ✨

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_render.h>

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

---

💅 DESCRIPTION 💅

okay so instead of passing a million boring args, you hand this girl a bag of properties and she builds your texture exactly how you like it. here's the supported properties, no cap 🫶

• SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER — an SDL_Colorspace value that says what colorspace the texture lives in. defaults? it's giving variety: 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. slay 🌈
• 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, not optional, she's not playing 😤
• SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER — the height of the texture in pixels. also required fr fr
• SDL_PROP_TEXTURE_CREATE_PALETTE_POINTER — an SDL_Palette to use with palettized texture formats. you can also set this 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. 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. important little caveat, don't skip it 💜

🎮 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_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.
• SDL_PROP_TEXTURE_CREATE_VULKAN_LAYOUT_NUMBER — the VkImageLayout for the VkImage. defaults to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL ✨

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

---

🫶 FUNCTION PARAMETERS 🫶

• renderer — the rendering context. your main character 💫
• props — the properties to use. the whole vibe check, basically 🎀

---

💀 RETURN VALUE 💀

Returns the created texture, or NULL on failure. if it flops, call SDL_GetError() for more information — she will tell you what went wrong, ngl 😭

---

🔒 THREAD SAFETY 🔒

This function should only be called on the main thread. no side-quests, no other threads, periodt ✋

---

⭐ AVAILABILITY ⭐

This function is available since SDL 3.2.0. so if you're on an older version... not me finding out the hard way 🙈

---

👀 SEE ALSO 👀

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

---

and that's the whole page bestie, every single property, every default, every required field, all of it. go make something iconic 💜

this has been your girl from Simple Directmedia Layer, serving SDL 3.4.18 — mwah, ily, bye 🫶✨💅