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_RendererLogicalPresentation
How the logical size is mapped to the output.
SDL_Texture
An efficient driver-specific representation of pixel data
SDL_TextureAccess
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_OPENGLES2_TEXTURE_NUMBER
SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER
SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER
SDL_PROP_TEXTURE_CREATE_OPENGLES2_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_OPENGLES2_TEXTURE_NUMBER
SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER
SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER
SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER
SDL_PROP_TEXTURE_OPENGLES2_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_AddVulkanRenderSemaphores
Add a set of synchronization semaphores for the current frame.
SDL_ConvertEventToRenderCoordinates
Convert the coordinates in an event to render coordinates.
SDL_CreateRenderer
Create a 2D rendering context for a window.
SDL_CreateRendererWithProperties
Create a 2D rendering context for a window, with the specified properties.
SDL_CreateSoftwareRenderer
Create a 2D software rendering context for a surface.
SDL_CreateTexture
Create a texture for a rendering context.
SDL_CreateTextureFromSurface
Create a texture from an existing surface.
SDL_CreateTextureWithProperties
Create a texture for a rendering context with the specified properties.
SDL_CreateWindowAndRenderer
Create a window and default renderer.
SDL_DestroyRenderer
Destroy the rendering context for a window and free all associated textures.
SDL_DestroyTexture
Destroy the specified texture.
SDL_FlushRenderer
Force the rendering context to flush any pending commands and state.
SDL_GetCurrentRenderOutputSize
Get the current output size in pixels of a rendering context.
SDL_GetNumRenderDrivers
Get the number of 2D rendering drivers available for the current display.
SDL_GetRenderClipRect
Get the clip rectangle for the current target.
SDL_GetRenderColorScale
Get the color scale used for render operations.
SDL_GetRenderDrawBlendMode
Get the blend mode used for drawing operations.
SDL_GetRenderDrawColor
Get the color used for drawing operations (Rect, Line and Clear).
SDL_GetRenderDrawColorFloat
Get the color used for drawing operations (Rect, Line and Clear).
SDL_GetRenderDriver
Use this function to get the name of a built in 2D rendering driver.
SDL_GetRenderLogicalPresentation
Get device independent resolution and presentation mode for rendering.
SDL_GetRenderLogicalPresentationRect
Get the final presentation rectangle for rendering.
SDL_GetRenderMetalCommandEncoder
Get the Metal command encoder for the current frame.
SDL_GetRenderMetalLayer
Get the CAMetalLayer associated with the given Metal renderer.
SDL_GetRenderOutputSize
Get the output size in pixels of a rendering context.
SDL_GetRenderSafeArea
Get the safe area for rendering within the current viewport.
SDL_GetRenderScale
Get the drawing scale for the current target.
SDL_GetRenderTarget
Get the current render target.
SDL_GetRenderVSync
Get VSync of the given renderer.
SDL_GetRenderViewport
Get the drawing area for the current target.
SDL_GetRenderWindow
Get the window associated with a renderer.
SDL_GetRenderer
Get the renderer associated with a window.
SDL_GetRendererFromTexture
Get the renderer that created an SDL_Texture.
SDL_GetRendererName
Get the name of a renderer.
SDL_GetRendererProperties
Get the properties associated with a renderer.
SDL_GetTextureAlphaMod
Get the additional alpha value multiplied into render copy operations.
SDL_GetTextureAlphaModFloat
Get the additional alpha value multiplied into render copy operations.
SDL_GetTextureBlendMode
Get the blend mode used for texture copy operations.
SDL_GetTextureColorMod
Get the additional color value multiplied into render copy operations.
SDL_GetTextureColorModFloat
Get the additional color value multiplied into render copy operations.
SDL_GetTextureProperties
Get the properties associated with a texture.
SDL_GetTextureScaleMode
Get the scale mode used for texture scale operations.
SDL_GetTextureSize
Get the size of a texture, as floating point values.
SDL_LockTexture
Lock a portion of the texture for write-only pixel access.
SDL_LockTextureToSurface
Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface.
SDL_RenderClear
Clear the current rendering target with the drawing color.
SDL_RenderClipEnabled
Get whether clipping is enabled on the given renderer.
SDL_RenderCoordinatesFromWindow
Get a point in render coordinates when given a point in window coordinates.
SDL_RenderCoordinatesToWindow
Get a point in window coordinates when given a point in render coordinates.
SDL_RenderDebugText
Draw debug text to an SDL_Renderer.
SDL_RenderDebugTextFormat
Draw debug text to an SDL_Renderer.
SDL_RenderFillRect
Fill a rectangle on the current rendering target with the drawing color at subpixel precision.
SDL_RenderFillRects
Fill some number of rectangles on the current rendering target with the drawing color at subpixel precision.
SDL_RenderGeometry
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 and SDL_SetTextureAlphaMod are ignored).
SDL_RenderGeometryRaw
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 and SDL_SetTextureAlphaMod are ignored).
SDL_RenderLine
Draw a line on the current rendering target at subpixel precision.
SDL_RenderLines
Draw a series of connected lines on the current rendering target at subpixel precision.
SDL_RenderPoint
Draw a point on the current rendering target at subpixel precision.
SDL_RenderPoints
Draw multiple points on the current rendering target at subpixel precision.
SDL_RenderPresent
Update the screen with any rendering performed since the previous call.
SDL_RenderReadPixels
Read pixels from the current rendering target.
SDL_RenderRect
Draw a rectangle on the current rendering target at subpixel precision.
SDL_RenderRects
Draw some number of rectangles on the current rendering target at subpixel precision.
SDL_RenderTexture
Copy a portion of the texture to the current rendering target at subpixel precision.
SDL_RenderTexture9Grid
Perform a scaled copy using the 9-grid algorithm to the current rendering target at subpixel precision.
SDL_RenderTextureAffine
Copy a portion of the source texture to the current rendering target, with affine transform, at subpixel precision.
SDL_RenderTextureRotated
Copy a portion of the source texture to the current rendering target, with rotation and flipping, at subpixel precision.
SDL_RenderTextureTiled
Tile a portion of the texture to the current rendering target at subpixel precision.
SDL_RenderViewportSet
Return whether an explicit rectangle was set as the viewport.
SDL_SetRenderClipRect
Set the clip rectangle for rendering on the specified target.
SDL_SetRenderColorScale
Set the color scale used for render operations.
SDL_SetRenderDrawBlendMode
Set the blend mode used for drawing operations (Fill and Line).
SDL_SetRenderDrawColor
Set the color used for drawing operations.
SDL_SetRenderDrawColorFloat
Set the color used for drawing operations (Rect, Line and Clear).
SDL_SetRenderLogicalPresentation
Set a device independent resolution and presentation mode for rendering.
SDL_SetRenderScale
Set the drawing scale for rendering on the current target.
SDL_SetRenderTarget
Set a texture as the current rendering target.
SDL_SetRenderVSync
Toggle VSync of the given renderer.
SDL_SetRenderViewport
Set the drawing area for rendering on the current target.
SDL_SetTextureAlphaMod
Set an additional alpha value multiplied into render copy operations.
SDL_SetTextureAlphaModFloat
Set an additional alpha value multiplied into render copy operations.
SDL_SetTextureBlendMode
Set the blend mode for a texture, used by SDL_RenderTexture().
SDL_SetTextureColorMod
Set an additional color value multiplied into render copy operations.
SDL_SetTextureColorModFloat
Set an additional color value multiplied into render copy operations.
SDL_SetTextureScaleMode
Set the scale mode used for texture scale operations.
SDL_UnlockTexture
Unlock a texture, uploading the changes to video memory, if needed.
SDL_UpdateNVTexture
Update a rectangle within a planar NV12 or NV21 texture with new pixels.
SDL_UpdateTexture
Update the given texture rectangle with new pixel data.
SDL_UpdateYUVTexture
Update a rectangle within a planar YV12 or IYUV texture with new pixel data.