Module render
Available on crate feature
dep_sdl3
only.Expand description
Header file for SDL 2D rendering functions.
This API supports the following features:
- single pixel points
- single pixel lines
- filled rectangles
- texture images
- 2D polygons
The primitives may be drawn in opaque, blended, or additive modes.
The texture images may be drawn in opaque, blended, or additive modes. They can have an additional color tint or alpha modulation applied to them, and may also be stretched with linear interpolation.
This API is designed to accelerate simple 2D operations. You may want more functionality such as polygons and particle effects and in that case you should use SDL’s OpenGL/Direct3D support, the SDL3 GPU API, or one of the many good 3D engines.
These functions must be called from the main thread. See this bug for details: https://github.com/libsdl-org/SDL/issues/986
Structs§
- SDL_
Renderer - A structure representing rendering state
- SDL_
Renderer Logical Presentation - How the logical size is mapped to the output.
- SDL_
Texture - An efficient driver-specific representation of pixel data
- SDL_
Texture Access - The access pattern allowed for a texture.
- SDL_
Vertex - Vertex structure.
Constants§
- SDL_
DEBUG_ TEXT_ FONT_ CHARACTER_ SIZE - The size, in pixels, of a single
SDL_RenderDebugText()
character. - SDL_
LOGICAL_ PRESENTATION_ DISABLED - There is no logical size in effect
- SDL_
LOGICAL_ PRESENTATION_ INTEGER_ SCALE - The rendered content is scaled up by integer multiples to fit the output resolution
- SDL_
LOGICAL_ PRESENTATION_ LETTERBOX - The rendered content is fit to the largest dimension and the other dimension is letterboxed with black bars
- SDL_
LOGICAL_ PRESENTATION_ OVERSCAN - The rendered content is fit to the smallest dimension and the other dimension extends beyond the output bounds
- SDL_
LOGICAL_ PRESENTATION_ STRETCH - The rendered content is stretched to the output resolution
- SDL_
PROP_ RENDERER_ CREATE_ NAME_ STRING - SDL_
PROP_ RENDERER_ CREATE_ OUTPUT_ COLORSPACE_ NUMBER - SDL_
PROP_ RENDERER_ CREATE_ PRESENT_ VSYNC_ NUMBER - SDL_
PROP_ RENDERER_ CREATE_ SURFACE_ POINTER - SDL_
PROP_ RENDERER_ CREATE_ VULKAN_ DEVICE_ POINTER - SDL_
PROP_ RENDERER_ CREATE_ VULKAN_ GRAPHICS_ QUEUE_ FAMILY_ INDEX_ NUMBER - SDL_
PROP_ RENDERER_ CREATE_ VULKAN_ INSTANCE_ POINTER - SDL_
PROP_ RENDERER_ CREATE_ VULKAN_ PHYSICAL_ DEVICE_ POINTER - SDL_
PROP_ RENDERER_ CREATE_ VULKAN_ PRESENT_ QUEUE_ FAMILY_ INDEX_ NUMBER - SDL_
PROP_ RENDERER_ CREATE_ VULKAN_ SURFACE_ NUMBER - SDL_
PROP_ RENDERER_ CREATE_ WINDOW_ POINTER - SDL_
PROP_ RENDERER_ D3D9_ DEVICE_ POINTER - SDL_
PROP_ RENDERER_ D3D11_ DEVICE_ POINTER - SDL_
PROP_ RENDERER_ D3D11_ SWAPCHAIN_ POINTER - SDL_
PROP_ RENDERER_ D3D12_ COMMAND_ QUEUE_ POINTER - SDL_
PROP_ RENDERER_ D3D12_ DEVICE_ POINTER - SDL_
PROP_ RENDERER_ D3D12_ SWAPCHAIN_ POINTER - SDL_
PROP_ RENDERER_ GPU_ DEVICE_ POINTER - SDL_
PROP_ RENDERER_ HDR_ ENABLED_ BOOLEAN - SDL_
PROP_ RENDERER_ HDR_ HEADROOM_ FLOAT - SDL_
PROP_ RENDERER_ MAX_ TEXTURE_ SIZE_ NUMBER - SDL_
PROP_ RENDERER_ NAME_ STRING - SDL_
PROP_ RENDERER_ OUTPUT_ COLORSPACE_ NUMBER - SDL_
PROP_ RENDERER_ SDR_ WHITE_ POINT_ FLOAT - SDL_
PROP_ RENDERER_ SURFACE_ POINTER - SDL_
PROP_ RENDERER_ TEXTURE_ FORMATS_ POINTER - SDL_
PROP_ RENDERER_ VSYNC_ NUMBER - SDL_
PROP_ RENDERER_ VULKAN_ DEVICE_ POINTER - SDL_
PROP_ RENDERER_ VULKAN_ GRAPHICS_ QUEUE_ FAMILY_ INDEX_ NUMBER - SDL_
PROP_ RENDERER_ VULKAN_ INSTANCE_ POINTER - SDL_
PROP_ RENDERER_ VULKAN_ PHYSICAL_ DEVICE_ POINTER - SDL_
PROP_ RENDERER_ VULKAN_ PRESENT_ QUEUE_ FAMILY_ INDEX_ NUMBER - SDL_
PROP_ RENDERER_ VULKAN_ SURFACE_ NUMBER - SDL_
PROP_ RENDERER_ VULKAN_ SWAPCHAIN_ IMAGE_ COUNT_ NUMBER - SDL_
PROP_ RENDERER_ WINDOW_ POINTER - SDL_
PROP_ TEXTURE_ ACCESS_ NUMBER - SDL_
PROP_ TEXTURE_ COLORSPACE_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ ACCESS_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ COLORSPACE_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ D3D11_ TEXTURE_ POINTER - SDL_
PROP_ TEXTURE_ CREATE_ D3D11_ TEXTURE_ U_ POINTER - SDL_
PROP_ TEXTURE_ CREATE_ D3D11_ TEXTURE_ V_ POINTER - SDL_
PROP_ TEXTURE_ CREATE_ D3D12_ TEXTURE_ POINTER - SDL_
PROP_ TEXTURE_ CREATE_ D3D12_ TEXTURE_ U_ POINTER - SDL_
PROP_ TEXTURE_ CREATE_ D3D12_ TEXTURE_ V_ POINTER - SDL_
PROP_ TEXTURE_ CREATE_ FORMAT_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ HDR_ HEADROOM_ FLOAT - SDL_
PROP_ TEXTURE_ CREATE_ HEIGHT_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ METAL_ PIXELBUFFER_ POINTER - SDL_
PROP_ TEXTURE_ CREATE_ OPENGLE S2_ TEXTURE_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ OPENGLE S2_ TEXTURE_ UV_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ OPENGLE S2_ TEXTURE_ U_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ OPENGLE S2_ TEXTURE_ V_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ OPENGL_ TEXTURE_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ OPENGL_ TEXTURE_ UV_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ OPENGL_ TEXTURE_ U_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ OPENGL_ TEXTURE_ V_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ SDR_ WHITE_ POINT_ FLOAT - SDL_
PROP_ TEXTURE_ CREATE_ VULKAN_ TEXTURE_ NUMBER - SDL_
PROP_ TEXTURE_ CREATE_ WIDTH_ NUMBER - SDL_
PROP_ TEXTURE_ D3D11_ TEXTURE_ POINTER - SDL_
PROP_ TEXTURE_ D3D11_ TEXTURE_ U_ POINTER - SDL_
PROP_ TEXTURE_ D3D11_ TEXTURE_ V_ POINTER - SDL_
PROP_ TEXTURE_ D3D12_ TEXTURE_ POINTER - SDL_
PROP_ TEXTURE_ D3D12_ TEXTURE_ U_ POINTER - SDL_
PROP_ TEXTURE_ D3D12_ TEXTURE_ V_ POINTER - SDL_
PROP_ TEXTURE_ FORMAT_ NUMBER - SDL_
PROP_ TEXTURE_ HDR_ HEADROOM_ FLOAT - SDL_
PROP_ TEXTURE_ HEIGHT_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGLE S2_ TEXTURE_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGLE S2_ TEXTURE_ TARGET_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGLE S2_ TEXTURE_ UV_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGLE S2_ TEXTURE_ U_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGLE S2_ TEXTURE_ V_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGL_ TEXTURE_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGL_ TEXTURE_ TARGET_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGL_ TEXTURE_ UV_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGL_ TEXTURE_ U_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGL_ TEXTURE_ V_ NUMBER - SDL_
PROP_ TEXTURE_ OPENGL_ TEX_ H_ FLOAT - SDL_
PROP_ TEXTURE_ OPENGL_ TEX_ W_ FLOAT - SDL_
PROP_ TEXTURE_ SDR_ WHITE_ POINT_ FLOAT - SDL_
PROP_ TEXTURE_ VULKAN_ TEXTURE_ NUMBER - SDL_
PROP_ TEXTURE_ WIDTH_ NUMBER - SDL_
RENDERER_ VSYNC_ ADAPTIVE - SDL_
RENDERER_ VSYNC_ DISABLED - SDL_
SOFTWARE_ RENDERER - The name of the software renderer.
- SDL_
TEXTUREACCESS_ STATIC - Changes rarely, not lockable
- SDL_
TEXTUREACCESS_ STREAMING - Changes frequently, lockable
- SDL_
TEXTUREACCESS_ TARGET - Texture can be used as a render target
Functions§
- SDL_
AddVulkan ⚠Render Semaphores - Add a set of synchronization semaphores for the current frame.
- SDL_
Convert ⚠Event ToRender Coordinates - Convert the coordinates in an event to render coordinates.
- SDL_
Create ⚠Renderer - Create a 2D rendering context for a window.
- SDL_
Create ⚠Renderer With Properties - Create a 2D rendering context for a window, with the specified properties.
- SDL_
Create ⚠Software Renderer - Create a 2D software rendering context for a surface.
- SDL_
Create ⚠Texture - Create a texture for a rendering context.
- SDL_
Create ⚠Texture From Surface - Create a texture from an existing surface.
- SDL_
Create ⚠Texture With Properties - Create a texture for a rendering context with the specified properties.
- SDL_
Create ⚠Window AndRenderer - Create a window and default renderer.
- SDL_
Destroy ⚠Renderer - Destroy the rendering context for a window and free all associated textures.
- SDL_
Destroy ⚠Texture - Destroy the specified texture.
- SDL_
Flush ⚠Renderer - Force the rendering context to flush any pending commands and state.
- SDL_
GetCurrent ⚠Render Output Size - Get the current output size in pixels of a rendering context.
- SDL_
GetNum ⚠Render Drivers - Get the number of 2D rendering drivers available for the current display.
- SDL_
GetRender ⚠Clip Rect - Get the clip rectangle for the current target.
- SDL_
GetRender ⚠Color Scale - Get the color scale used for render operations.
- SDL_
GetRender ⚠Draw Blend Mode - Get the blend mode used for drawing operations.
- SDL_
GetRender ⚠Draw Color - Get the color used for drawing operations (Rect, Line and Clear).
- SDL_
GetRender ⚠Draw Color Float - Get the color used for drawing operations (Rect, Line and Clear).
- SDL_
GetRender ⚠Driver - Use this function to get the name of a built in 2D rendering driver.
- SDL_
GetRender ⚠Logical Presentation - Get device independent resolution and presentation mode for rendering.
- SDL_
GetRender ⚠Logical Presentation Rect - Get the final presentation rectangle for rendering.
- SDL_
GetRender ⚠Metal Command Encoder - Get the Metal command encoder for the current frame.
- SDL_
GetRender ⚠Metal Layer - Get the CAMetalLayer associated with the given Metal renderer.
- SDL_
GetRender ⚠Output Size - Get the output size in pixels of a rendering context.
- SDL_
GetRender ⚠Safe Area - Get the safe area for rendering within the current viewport.
- SDL_
GetRender ⚠Scale - Get the drawing scale for the current target.
- SDL_
GetRender ⚠Target - Get the current render target.
- SDL_
GetRenderV ⚠Sync - Get VSync of the given renderer.
- SDL_
GetRender ⚠Viewport - Get the drawing area for the current target.
- SDL_
GetRender ⚠Window - Get the window associated with a renderer.
- SDL_
GetRenderer ⚠ - Get the renderer associated with a window.
- SDL_
GetRenderer ⚠From Texture - Get the renderer that created an
SDL_Texture
. - SDL_
GetRenderer ⚠Name - Get the name of a renderer.
- SDL_
GetRenderer ⚠Properties - Get the properties associated with a renderer.
- SDL_
GetTexture ⚠Alpha Mod - Get the additional alpha value multiplied into render copy operations.
- SDL_
GetTexture ⚠Alpha ModFloat - Get the additional alpha value multiplied into render copy operations.
- SDL_
GetTexture ⚠Blend Mode - Get the blend mode used for texture copy operations.
- SDL_
GetTexture ⚠Color Mod - Get the additional color value multiplied into render copy operations.
- SDL_
GetTexture ⚠Color ModFloat - Get the additional color value multiplied into render copy operations.
- SDL_
GetTexture ⚠Properties - Get the properties associated with a texture.
- SDL_
GetTexture ⚠Scale Mode - Get the scale mode used for texture scale operations.
- SDL_
GetTexture ⚠Size - Get the size of a texture, as floating point values.
- SDL_
Lock ⚠Texture - Lock a portion of the texture for write-only pixel access.
- SDL_
Lock ⚠Texture ToSurface - Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface.
- SDL_
Render ⚠Clear - Clear the current rendering target with the drawing color.
- SDL_
Render ⚠Clip Enabled - Get whether clipping is enabled on the given renderer.
- SDL_
Render ⚠Coordinates From Window - Get a point in render coordinates when given a point in window coordinates.
- SDL_
Render ⚠Coordinates ToWindow - Get a point in window coordinates when given a point in render coordinates.
- SDL_
Render ⚠Debug Text - Draw debug text to an
SDL_Renderer
. - SDL_
Render ⚠Debug Text Format - Draw debug text to an
SDL_Renderer
. - SDL_
Render ⚠Fill Rect - Fill a rectangle on the current rendering target with the drawing color at subpixel precision.
- SDL_
Render ⚠Fill Rects - Fill some number of rectangles on the current rendering target with the drawing color at subpixel precision.
- SDL_
Render ⚠Geometry - Render a list of triangles, optionally using a texture and indices into the
vertex array Color and alpha modulation is done per vertex
(
SDL_SetTextureColorMod
andSDL_SetTextureAlphaMod
are ignored). - SDL_
Render ⚠Geometry Raw - Render a list of triangles, optionally using a texture and indices into the
vertex arrays Color and alpha modulation is done per vertex
(
SDL_SetTextureColorMod
andSDL_SetTextureAlphaMod
are ignored). - SDL_
Render ⚠Line - Draw a line on the current rendering target at subpixel precision.
- SDL_
Render ⚠Lines - Draw a series of connected lines on the current rendering target at subpixel precision.
- SDL_
Render ⚠Point - Draw a point on the current rendering target at subpixel precision.
- SDL_
Render ⚠Points - Draw multiple points on the current rendering target at subpixel precision.
- SDL_
Render ⚠Present - Update the screen with any rendering performed since the previous call.
- SDL_
Render ⚠Read Pixels - Read pixels from the current rendering target.
- SDL_
Render ⚠Rect - Draw a rectangle on the current rendering target at subpixel precision.
- SDL_
Render ⚠Rects - Draw some number of rectangles on the current rendering target at subpixel precision.
- SDL_
Render ⚠Texture - Copy a portion of the texture to the current rendering target at subpixel precision.
- SDL_
Render ⚠Texture9 Grid - Perform a scaled copy using the 9-grid algorithm to the current rendering target at subpixel precision.
- SDL_
Render ⚠Texture Affine - Copy a portion of the source texture to the current rendering target, with affine transform, at subpixel precision.
- SDL_
Render ⚠Texture Rotated - Copy a portion of the source texture to the current rendering target, with rotation and flipping, at subpixel precision.
- SDL_
Render ⚠Texture Tiled - Tile a portion of the texture to the current rendering target at subpixel precision.
- SDL_
Render ⚠Viewport Set - Return whether an explicit rectangle was set as the viewport.
- SDL_
SetRender ⚠Clip Rect - Set the clip rectangle for rendering on the specified target.
- SDL_
SetRender ⚠Color Scale - Set the color scale used for render operations.
- SDL_
SetRender ⚠Draw Blend Mode - Set the blend mode used for drawing operations (Fill and Line).
- SDL_
SetRender ⚠Draw Color - Set the color used for drawing operations.
- SDL_
SetRender ⚠Draw Color Float - Set the color used for drawing operations (Rect, Line and Clear).
- SDL_
SetRender ⚠Logical Presentation - Set a device independent resolution and presentation mode for rendering.
- SDL_
SetRender ⚠Scale - Set the drawing scale for rendering on the current target.
- SDL_
SetRender ⚠Target - Set a texture as the current rendering target.
- SDL_
SetRenderV ⚠Sync - Toggle VSync of the given renderer.
- SDL_
SetRender ⚠Viewport - Set the drawing area for rendering on the current target.
- SDL_
SetTexture ⚠Alpha Mod - Set an additional alpha value multiplied into render copy operations.
- SDL_
SetTexture ⚠Alpha ModFloat - Set an additional alpha value multiplied into render copy operations.
- SDL_
SetTexture ⚠Blend Mode - Set the blend mode for a texture, used by
SDL_RenderTexture()
. - SDL_
SetTexture ⚠Color Mod - Set an additional color value multiplied into render copy operations.
- SDL_
SetTexture ⚠Color ModFloat - Set an additional color value multiplied into render copy operations.
- SDL_
SetTexture ⚠Scale Mode - Set the scale mode used for texture scale operations.
- SDL_
Unlock ⚠Texture - Unlock a texture, uploading the changes to video memory, if needed.
- SDL_
UpdateNV ⚠Texture - Update a rectangle within a planar NV12 or NV21 texture with new pixels.
- SDL_
Update ⚠Texture - Update the given texture rectangle with new pixel data.
- SDL_
UpdateYUV ⚠Texture - Update a rectangle within a planar YV12 or IYUV texture with new pixel data.