2D Accelerated Rendering¶

Render drivers¶

A render driver is a set of code that handles rendering and texture management on a particular display.

class csdl2.SDL_RendererInfo(name=None, flags=0, num_texture_formats=0, texture_formats=0, max_texture_width=0, max_texture_height=0)¶

Information on the capabilities of a render driver or context.

name¶: Name of the renderer.

flags¶: A mask of supported Renderer creation flags.

num_texture_formats¶: The number of available texture formats.

texture_formats¶

The available texture formats as an array of Pixel format constants ints.

Note that the size of the array is always 16. However, only the first num_texture_formats values are valid.

max_texture_width¶: Maximum texture width.

max_texture_height¶: Maximum texture height

csdl2.SDL_GetNumRenderDrivers() → int¶: Get the number of 2D rendering drivers available for the current display.

csdl2.SDL_GetRenderDriverInfo(index) → SDL_RendererInfo¶

Gets information about a specific 2D rendering driver for the current display.

Parameters:	index (int) – The index of the driver to query information about. It must be in the range 0 to `SDL_GetNumRenderDrivers() - 1`.
Returns:	A new `SDL_RendererInfo` filled with information about the render driver.

Renderers¶

class csdl2.SDL_Renderer¶

A 2d rendering context.

This is an opaque handle that cannot be directly constructed. Instead, use SDL_CreateRenderer() or SDL_CreateSoftwareRenderer().

csdl2.SDL_CreateWindowAndRenderer(width, height, window_flags) → tuple¶

Creates a window and a default renderer.

Parameters:	width (int) – The width of the window. height (int) – The height of the window. window_flags (int) – 0, or one or more of the Window flags OR’d together.
Returns:	A 2-tuple `(window, renderer)`, where window is the created `SDL_Window` and renderer is the created `SDL_Renderer`.

csdl2.SDL_CreateRenderer(window: SDL_Window, index: int, flags: int) → SDL_Renderer¶

Creates a SDL_Renderer for window.

Parameters:	window (SDL_Window) – `SDL_Window` to render to. index (int) – The index of the rendering driver to initialize, or -1 to initialize the first driver supporting flags. flags (int) – 0, or one or more Renderer creation flags OR’ed together.
Returns:	A new `SDL_Renderer` that renders to window.

csdl2.SDL_CreateSoftwareRenderer(surface: SDL_Surface) → SDL_Renderer¶

Creates a SDL_Renderer for surface.

Parameters:	surface (SDL_Surface) – `SDL_Surface` to render to.
Returns:	A new `SDL_Renderer` that renders to surface.

csdl2.SDL_GetRenderer(window) → SDL_Renderer¶

Returns the renderer associated with a window.

Parameters:	window (`SDL_Renderer`) – The window to query.
Returns:	The `SDL_Renderer` associated with the window, or None if there is no renderer associated with the window.

csdl2.SDL_GetRendererInfo(renderer) → SDL_RendererInfo¶

Get information about a rendering context.

Parameters:	renderer (`SDL_Renderer`) – The rendering context to query.
Returns:	A new `SDL_RendererInfo` filled with information about the renderer.

csdl2.SDL_GetRendererOutputSize(renderer) → tuple¶

Get the output size of a rendering context.

Parameters:	renderer (`SDL_Renderer`) – The rendering context to query.
Returns:	A 2-tuple `(width, height)` with the output width and height of the rendering context respectively.

csdl2.SDL_DestroyRenderer(renderer: SDL_Renderer) → None¶

Destroys renderer, freeing up its associated textures and resources.

There is no need to manually call this function. SDL_Renderer will automatically call this function as part of its destructor.

Parameters:	renderer (SDL_Renderer) – `SDL_Renderer` to destroy

Renderer creation flags¶

These flags can be passed to SDL_CreateRenderer() to request that the renderer support certain functions.

csdl2.SDL_RENDERER_SOFTWARE¶: The renderer is a software fallback.

csdl2.SDL_RENDERER_ACCELERATED¶: The renderer uses hardware acceleration.

csdl2.SDL_RENDERER_PRESENTVSYNC¶: SDL_RenderPresent() is synchronized with the refresh rate.

csdl2.SDL_RENDERER_TARGETTEXTURE¶: The renderer supports rendering to texture.

Textures¶

class csdl2.SDL_Texture¶

An efficient driver-specific representation of pixel data.

This is an opaque handle that cannot be directly constructed. Instead, use SDL_CreateTexture() or SDL_CreateTextureFromSurface().

csdl2.SDL_CreateTexture(renderer, format, access, w, h) → SDL_Texture¶

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

Parameters:

renderer (SDL_Renderer) – The rendering context.
format (int) – The texture pixel format. One of the Pixel format constants.
access (int) – Specifies whether the texture data can be modified. One of SDL_TEXTUREACCESS_STATIC, SDL_TEXTUREACCESS_STREAMING or SDL_TEXTUREACCESS_TARGET.
w (int) – Width of the texture in pixels.
h (int) – Height of the texture in pixels.

Returns:

A new SDL_Texture for the rendering context.

csdl2.SDL_TEXTUREACCESS_STATIC¶: Texture changes rarely, not lockable.

csdl2.SDL_TEXTUREACCESS_STREAMING¶: Texture changes frequently, lockable.

csdl2.SDL_TEXTUREACCESS_TARGET¶: Texture can be used as a render target.

csdl2.SDL_CreateTextureFromSurface(renderer, surface) → SDL_Texture¶

Creates a texture for a rendering context with the pixel data of an existing surface.

The surface is not modified or freed by this function. The texture will be created with SDL_TEXTUREACCESS_STATIC.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. surface (class:SDL_Surface) – The surface containing pixel data to fill the texture.
Returns:	A new `SDL_Texture` for the rendering context.

csdl2.SDL_QueryTexture(texture) → tuple¶

Query the attributes of a texture. Namely:

The texture’s raw pixel format, one of the Pixel format constants.
The texture’s access. One of SDL_TEXTUREACCESS_STATIC, SDL_TEXTUREACCESS_STREAMING or SDL_TEXTUREACCESS_TARGET.
The texture’s width and height, in pixels.

Parameters:	texture (`SDL_Texture`) – The texture to be queried.
Returns:	A tuple `(int, int, int, int)` with the texture’s raw pixel format, access, width and height respectively.

csdl2.SDL_SetTextureColorMod(texture, r, g, b)¶

Sets an additional color value used in render copy operations.

When the texture is rendered, during the copy operation each source color channel is modulated by the appropriate color value according to the following formula:

srcC = srcC * (color / 255)

Parameters:	texture (`SDL_Texture`) – The texture to update. r (int) – The red color value multiplied into copy operations. g (int) – The green color value multiplied into copy operations. b (int) – The blue color value multiplied into copy operations.

csdl2.SDL_GetTextureColorMod(texture) → tuple¶

Returns the additional color value multiplied into render copy operations.

Parameters:	texture (`SDL_Texture`) – The texture to query.
Returns:	A tuple `(int, int, int)` with the red, green and blue components of the color respectively.

csdl2.SDL_SetTextureAlphaMod(texture, alpha)¶

Sets an additional alpha value multiplied into render copy operations.

When the texture is rendered, during the copy operation the source alpha value would be modulated by this alpha value according to the following formula:

srcA = srcA * (alpha / 255)

Parameters:	texture (`SDL_Texture`) – The texture to update. alpha (int) – The source alpha value multiplied into copy operations. It must be within the range 0-255.

csdl2.SDL_GetTextureAlphaMod(texture) → int¶

Returns the additional alpha value multiplied into render copy operations.

Parameters:	texture (`SDL_Texture`) – The texture to query.
Returns:	The current alpha value. It is within the range 0-255.

csdl2.SDL_SetTextureBlendMode(texture, blendMode: int)¶

Sets the blend mode for a texture.

Parameters:	texture (`SDL_Texture`) – The texture to update. blendMode (int) – The blend mode to use for texture blending. One of the Blend modes.

csdl2.SDL_GetTextureBlendMode(texture) → int¶

Returns the blend mode used for texture copy operations.

Parameters:	texture (`SDL_Texture`) – The texture to query.
Returns:	The texture’s blend mode. One of the Blend modes.

csdl2.SDL_UpdateTexture(texture, rect, pixels, pitch)¶

Updates the given texture rectangle with new pixel data.

Parameters:	texture (`SDL_Texture`) – The texture to update. rect (`SDL_Rect` buffer, or None) – The area to update, or None to update the entire texture. pixels (buffer) – The raw pixel data. pitch (int) – The number of bytes in a row of pixel data, including padding between lines.

Note

This is a fairly slow function, intended for use with static textures that do not change often. If the texture is intended to be updated often, it is preferred to create the texture as streaming and use the locking functions SDL_LockTexture() and SDL_UnlockTexture(). While this function will work with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

csdl2.SDL_LockTexture(texture, rect) → tuple¶

Locks a portion of the texture for write-only pixel access.

Parameters:	texture (`SDL_Texture`) – The texture to lock for access, which was created with `SDL_TEXTUREACCESS_STREAMING`. rect (`SDL_Rect` buffer or None) – The area to lock for access, or None to lock the entire texture.
Returns:	A tuple `(pixels, pitch)`. pixels is a buffer containing the locked pixels, and pitch is the integer length of one row in bytes.

Note

After modifying the pixels, you must use SDL_UnlockTexture() to unlock the pixels and apply any changes.

Note

This is a write-only operation. As an optimization, the pixels made available for editing don’t necessarily contain the old texture data.

csdl2.SDL_UnlockTexture(texture)¶

Unlocks a texture, uploading any changes to video memory.

Parameters:	texture (`SDL_Texture`) – A texture locked by `SDL_LockTexture()`.

Note

The pixels buffer returned by SDL_LockTexture() may contain junk data. For consistent results, ensure that you have overwritten the pixel buffer fully before calling this function.

csdl2.SDL_DestroyTexture(texture)¶

Destroys the specified texture, freeing its resources.

There is no need to explictly call this function. SDL_Texture will automatically call it upon cleanup.

Parameters:	texture (`SDL_Texture`) – Texture to destroy.

Render targets¶

csdl2.SDL_RenderTargetSupported(renderer) → bool¶

Queries whether a renderer supports the use of render targets.

Parameters:	renderer (`SDL_Renderer`) – The rendering context.
Returns:	True if render targets are supported, False if not.

csdl2.SDL_SetRenderTarget(renderer, texture)¶

Sets a texture as the current rendering target.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. texture (`SDL_Texture` or None) – The targeted texture, which must be created with the `SDL_TEXTURTEACCESS_TARGET` flag, or None for the default render target.

csdl2.SDL_GetRenderTarget(renderer) → SDL_Texture¶

Queries the renderer’s current render target.

Parameters:	renderer (`SDL_Renderer`) – The rendering context.
Returns:	The current render target, or None for the default render target.

Device independent resolution¶

csdl2.SDL_RenderSetLogicalSize(renderer, w, h)¶

Sets a device independent resolution for rendering.

Parameters:	renderer (`SDL_Renderer`) – The renderer for which resolution should be set. w (int) – The width of the logical resolution. h (int) – The height of the logical resolution.

csdl2.SDL_RenderGetLogicalSize(renderer) → tuple¶

Queries the device independent resolution for rendering.

If the renderer did not have its logical size set by SDL_RenderSetLogicalSize(), the function returns (0, 0).

Parameters:	renderer (`SDL_Renderer`) – A rendering context.
Returns:	An `(int, int)` tuple with the width and height of the logical resolution respectively.

Viewport¶

csdl2.SDL_RenderSetViewport(renderer, rect)¶

Sets the drawing area for rendering on the current target.

When the window is resized, the current viewport is automatically centered within the new window size.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. rect (`SDL_Rect` or None) – The drawing area, or None to set the viewport to the entire target.

csdl2.SDL_RenderGetViewport(renderer) → SDL_Rect¶

Queries the drawing area for the current target.

Parameters:	renderer (`SDL_Renderer`) – The rendering context.
Returns:	A `SDL_Rect` with the drawing area for the current target.

Clip Rectangle¶

csdl2.SDL_RenderSetClipRect(renderer, rect)¶

Sets the clip rectangle for the current target.

Parameters:	renderer (`SDL_Renderer`) – The renderer for which clip rectangle should be set. rect (`SDL_Rect` or None) – The rectangle to set as the clip rectangle, or None to disable clipping.

csdl2.SDL_RenderGetClipRect(renderer) → SDL_Rect¶

Gets the clip rectangle for the current target.

Parameters:	renderer (`SDL_Renderer`) – The renderer from which clip rectangle should be queried.
Returns:	A `SDL_Rect` with the current clip rectangle, or an empty rectangle if clipping is disabled.

Scaling¶

csdl2.SDL_RenderSetScale(renderer, scaleX, scaleY)¶

Sets the drawing scale for rendering on the current target.

The drawing coordinates are scaled by the x/y scaling factors before they are used by the renderer. This allows resolution independent drawing with a single coordinate system.

Parameters:	renderer (`SDL_Renderer`) – The renderer for which the drawing scale should be set. scaleX (float) – The horizontal scaling factor. scaleY (float) – The vertical scaling factor.

Note

If this results in scaling or subpixel drawing by the rendering backend, it will be hendled using the appropriate quality hints. For best results use integer scaling factors.

csdl2.SDL_RenderGetScale(renderer) → tuple¶

Gets the drawing scale for the current target.

Parameters:	renderer (`SDL_Renderer`) – The renderer from which drawing scale should be queried.
Returns:	A 2-tuple `(scaleX, scaleY)` with the float horizontal and vertical scaling factors respectively.

Drawing¶

csdl2.SDL_SetRenderDrawColor(renderer: SDL_Renderer, r: int, g: int, b: int, a: int) → None¶

Sets the color used for drawing primitives, and for SDL_RenderClear().

Parameters:

renderer (SDL_Renderer) – The rendering context.
r (int) – The red value used to draw on the rendering target, within the range 0-255.
g (int) – The green value used to draw on the rendering target, within the range 0-255.
b (int) – The blue value used to draw on the rendering target, within the range 0-255.
a (int) – The alpha value used to draw on the rendering target, within the range 0-255. Use SDL_SetRenderDrawBlendMode() to specify how the alpha channel is used.

csdl2.SDL_GetRenderDrawColor(renderer: SDL_Renderer) → tuple¶

Returns the color used for drawing operations.

Parameters:	renderer (`SDL_Renderer`) – The rendering context.
Returns:	The (r, g, b, a) components of the drawing color.
Return type:	(int, int, int, int) tuple

csdl2.SDL_SetRenderDrawBlendMode(renderer, blendMode)¶

Sets the blend mode used for drawing operations (Fill and Line).

Parameters:	renderer (`SDL_Renderer`) – The renderer for which blend mode should be set. blendMode (int) – The blend mode to use for blending. One of the Blend modes.

Note

If the blend mode is not supported, the closest supported mode is chosen.

csdl2.SDL_GetRenderDrawBlendMode(renderer) → int¶

Gets the blend mode used for drawing operations.

Parameters:	renderer (`SDL_Renderer`) – The renderer from which blend mode should be queried.
Returns:	The current blend mode. One of the Blend modes.

csdl2.SDL_RenderClear(renderer: SDL_Renderer) → None¶

Clears the current rendering target with the current drawing color.

The entire rendering target will be cleared, ignoring the viewport.

Parameters:	renderer (`SDL_Renderer`) – The rendering context.

csdl2.SDL_RenderDrawPoint(renderer, x, y)¶

Draws a point on the current rendering target.

Parameters:	renderer (`SDL_Renderer`) – The renderer which should draw a point. x (int) – The x coordinate of the point. y (int) – The y coordinate of the point.

csdl2.SDL_RenderDrawPoints(renderer, points, count)¶

Draw multiple points on the current rendering target.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. points (`SDL_Point` array) – The points to draw. count (int) – The number of points to draw.

csdl2.SDL_RenderDrawLine(renderer, x1, y1, x2, y2)¶

Draw a line on the current rendering target.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. x1 (int) – The x coordinate of the start point. y1 (int) – The y coordinate of the start point. x2 (int) – The x coordinate of the end point. y2 (int) – The y coordinate of the end point.

csdl2.SDL_RenderDrawLines(renderer, points, count)¶

Draw a series of connected lines on the current rendering target.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. points (`SDL_Point` array) – The points along the lines. count (int) – The number of points, drawing `count - 1` lines.

csdl2.SDL_RenderDrawRect(renderer, rect)¶

Draw a rectangle on the current rendering target.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. rect (`SDL_Rect` or None) – The rectangle to draw, or None to outline the entire rendering target.

csdl2.SDL_RenderDrawRects(renderer, rects, count)¶

Draw some number of rectangles on the current rendering target.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. rects (`SDL_Rect` array.) – The rectangles to be drawn. count (int) – The number of rectangles.

csdl2.SDL_RenderFillRect(renderer: SDL_Renderer, rect: SDL_Rect) → None¶

Fills a rectangle on the current rendering target with the current drawing color.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. rect (`SDL_Rect` or None) – The `SDL_Rect` representing the rectangle to fill. If None, the entire rendering target will be filled.

csdl2.SDL_RenderFillRects(renderer, rects, count)¶

Fill some number of rectangles on the current rendering target with the current drawing color.

Parameters:	renderer (`SDL_Renderer`) – The rendering context. rects (`SDL_Rect` array) – The rectangles to be filled. count (int) – The number of rectangles.

csdl2.SDL_RenderCopy(renderer, texture, srcrect, dstrect)¶

Copies a portion of the texture to the current rendering target.

The texture is blended with the destination based on its blend mode set with SDL_SetTextureBlendMode().

The texture color is affected based on its color modulation set by SDL_SetTextureColorMod().

The texture alpha is affected based on its alpha modulation set by SDL_SetTextureAlphaMod().

Parameters:	renderer (`SDL_Renderer`) – The rendering context. texture (`SDL_Texture`) – The source texture. srcrect (`SDL_Rect` buffer or None) – The source rectangle, or None for the entire texture. dstrect (`SDL_Rect` buffer or None) – The destination rectangle, or None for the entire rendering target. The texture will be stretched to fill the given rectangle.

csdl2.SDL_RenderCopyEx(renderer, texture, srcrect, dstrect, angle, center, flip)¶

Copies a portion of the texture to the current rendering target, optionally rotating it by an angle around the given center and also flipping it top-bottom and/or left-right.

The texture is blended with the destination based on its blend mode set with SDL_SetTextureBlendMode().

The texture color is affected based on its color modulation set by SDL_SetTextureColorMod().

The texture alpha is affected based on its alpha modulation set by SDL_SetTextureAlphaMod().

Parameters:

renderer (SDL_Renderer) – The rendering context.
texture (SDL_Texture) – The source texture.
srcrect (SDL_Rect or None) – The source rectangle, or None for the entire texture.
dstrect (SDL_Rect or None) – The destination rectangle, or None for the entire rendering target. The texture will be stretched to fill the given rectangle.
angle (float) – An angle in degrees that indicates the rotation that will be applied to dstrect.
center (SDL_Point or None) – The point around which dstrect will be rotated. If None, rotation will be done around (dstrect.w/2, dstrect.h/2).
flip (int) – Indicates which flipping actions should be performed on the texture. One or more of SDL_FLIP_NONE, SDL_FLIP_HORIZONTAL and/or SDL_FLIP_VERTICAL OR’d together.

csdl2.SDL_FLIP_NONE¶: Do not flip.

csdl2.SDL_FLIP_HORIZONTAL¶: Flip horizontally.

csdl2.SDL_FLIP_VERTICAL¶: Flip vertically.

Reading pixels¶

csdl2.SDL_RenderReadPixels(renderer, rect, format, pixels, pitch)¶

Read pixels from the current rendering target.

Parameters:

renderer (SDL_Renderer) – The rendering context.
rect (SDL_Rect or None) – The area to read, or None for the entire render target.
format (int) – The desired format of the pixel data (one of the Pixel format constants), or 0 to use the format of the rendering target.
pixels (buffer) – The buffer to be filled in with the pixel data.
pitch (int) – The pitch of the pixels buffer.

Updating the screen¶

SDL’s rendering functions operate on a backbuffer. Calling a rendering function such as SDL_RenderDrawLine() does not directly draw a line on the screen, but rather updates the backbuffer. As such, after composing your entire scene with the drawing functions, you need to present the composed buffer to the screen as a complete picture. This is done with SDL_RenderPresent().

csdl2.SDL_RenderPresent(renderer: SDL_Renderer) → None¶

Updates the screen with any rendering performed since the previous call.

If the renderer has VSync enabled, this function will block while waiting for the next vertical refresh, hence eliminating screen tearing.

Parameters:	renderer (`SDL_Renderer`) – The rendering context

Note

The backbuffer should be considered invalidated after each call to SDL_RenderPresent(). Do not assume that previous contents will exist between frames. You are strongly encouraged to call SDL_RenderClear() to initialize the backbuffer before drawing each frame.

OpenGL Support¶

csdl2.SDL_GL_BindTexture(texture) → tuple¶

Bind an OpenGL/ES/ES2 texture to the current context for use with when rendering OpenGL primitives directly.

Parameters:	texture (`SDL_Texture`) – The texture to bind to the current OpenGL/ES/ES2 context.
Returns:	A `(float, float)` tuple with the texture width and texture height respectively.

Note

In most cases, the texture height and width will be 1.0. However, on systems that support the GL_ARB_texture_rectangle extension, these values will actually be the pixel width and height used to create the texture, and so this factor needs to be taken into account when providing texture coordinates to OpenGL.

Note

SDL may upload RGB textures as BGR (or vice-versa), and re-order the color channels in the shader phase, so the uploaded texture may have swapped color channels.

csdl2.SDL_GL_UnbindTexture(texture)¶

Unbind an OpenGL/ES/ES2 texture from the current context.

Parameters:	texture (`SDL_Texture`) – The texture to unbind from the current OpenGL/ES/ES2 context.