pygame.sdl2_video — pygame-ce v2.5.1 documentation

pygame.sdl2_video

Warning

This module isn't ready for prime time yet, it's still in development. These docs are primarily meant to help the pygame developers and super-early adopters who are in communication with the developers. This API will change.

pygame._sdl2.video.messagebox	—	Create a native GUI message box
pygame._sdl2.video.RendererDriverInfo	—	pygame object encapsulating Renderer driver information
pygame._sdl2.video.get_drivers	—	Yield info about the rendering drivers available for Renderer objects
pygame._sdl2.video.get_grabbed_window	—	Get the window with input grab enabled
pygame._sdl2.video.Window	—	pygame object that represents a window
pygame._sdl2.video.Texture	—	pygame object that represents a texture
pygame._sdl2.video.Image	—	pygame object that represents a portion of a texture
pygame._sdl2.video.Renderer	—	pygame object wrapping a 2D rendering context for a window

Experimental pygame module for porting new SDL video systems

pygame._sdl2.video.messagebox()¶

Create a native GUI message box

messagebox(title, message, window=None, info=False, warn=False, buttons=('OK',), return_button=0, escape_button=0)

Parameters:

title (str) -- A title string, or None to omit a title.
message (str) -- A message string.
info (bool) -- If True, display an info message.
warn (bool) -- If True, display a warning message.
error (bool) -- If True, display an error message.
buttons (tuple) -- An optional sequence of button name strings to show to the user.
return_button (int) -- Button index to use if the return key is hit (-1 for none).
escape_button (int) -- Button index to use if the escape key is hit (-1 for none).

Returns:

The index of the button that was pushed.

pygame._sdl2.video.RendererDriverInfo¶

pygame object encapsulating Renderer driver information

Attributes:

name
flags
num_texture_formats
max_texture_width
max_texture_height

pygame._sdl2.video.get_drivers()¶: Yield info about the rendering drivers available for Renderer objects

get_drivers() -> Iterator[RendererDriverInfo]

pygame._sdl2.video.get_grabbed_window()¶: Get the window with input grab enabled

get_grabbed_window() -> Window or None

Gets the Window with input grab enabled, if input is grabbed, otherwise None is returned.

pygame._sdl2.video.Window¶: pygame object that represents a window

See pygame.Windowpygame object that represents a window

pygame._sdl2.video.Texture¶

pygame object that represents a texture

Texture(renderer, size, depth=0, static=False, streaming=False, target=False, scale_quality=None) -> Texture

pygame._sdl2.video.Texture.renderer	—	Get the renderer associated with the texture (read-only)
pygame._sdl2.video.Texture.width	—	Get the width of the texture (read-only)
pygame._sdl2.video.Texture.height	—	Get the height of the texture (read-only)
pygame._sdl2.video.Texture.alpha	—	Get or set the additional alpha value multiplied into draw operations
pygame._sdl2.video.Texture.blend_mode	—	Get or set the blend mode for texture drawing operations
pygame._sdl2.video.Texture.color	—	Get or set the additional color value multiplied into texture drawing operations
pygame._sdl2.video.Texture.from_surface	—	Create a texture from an existing surface
pygame._sdl2.video.Texture.get_rect	—	Get the rectangular area of the texture
pygame._sdl2.video.Texture.draw	—	Copy a portion of the texture to the rendering target
pygame._sdl2.video.Texture.draw_triangle	—	Copy a triangle portion of the texture to the rendering target using the given coordinates
pygame._sdl2.video.Texture.draw_quad	—	Copy a quad portion of the texture to the rendering target using the given coordinates
pygame._sdl2.video.Texture.update	—	Update the texture with Surface (slow operation, use sparingly)

Creates an empty texture.

Parameters:

renderer (Renderer) -- The rendering context for the texture.
size (tuple) -- The width and height for the texture.
depth (int) -- The pixel format (0 to use the default).
static (bool) -- Initialize the texture as static (changes rarely, not lockable).
streaming (bool) -- Initialize the texture as streaming (changes frequently, lockable).
target (bool) -- Initialize the texture as target (can be used as a rendering target).
scale_quality (int) -- Set the texture scale quality. Can be 0 (nearest pixel sampling), 1 (linear filtering, supported by OpenGL and Direct3D) and 2 (anisotropic filtering, supported by Direct3D).

One of static, streaming, or target can be set to True. If all are False, then static is used.

Texture objects provide a platform-agnostic API for working with GPU textures. They are stored in GPU video memory (VRAM), and are therefore very fast to rotate and resize when drawn onto a Renderer (an object that manages a rendering context inside a Window) on most GPUs.

Since textures are stored in GPU video memory, they aren't as easy to modify as the image data of pygame.Surfacepygame object for representing images objects, which reside in RAM.

Textures can be modified in 2 ways:

By drawing other textures onto them, achieved by marking them as "target" textures and setting them as the rendering target of their Renderer object (if properly configured and supported).

By updating them with a Surface.

Note

A pygame.Surfacepygame object for representing images-to-Texture update is generally considered a slow operation, as it requires image data to be uploaded from RAM to VRAM, which can have a notable overhead cost.

renderer¶: Get the renderer associated with the texture (**read-only**)

renderer -> Renderer

width¶: Get the width of the texture (**read-only**)

width -> int

height¶: Get the height of the texture (**read-only**)

height -> int

alpha¶: Get or set the additional alpha value multiplied into draw operations

alpha -> int

blend_mode¶: Get or set the blend mode for texture drawing operations

blend_mode -> int

Gets or sets the blend mode for the texture's drawing operations. Valid blend modes are any of the BLENDMODE_* constants or a custom one.

color¶: Get or set the additional color value multiplied into texture drawing operations

color -> Color

static from_surface()¶

Create a texture from an existing surface

from_surface(renderer, surface) -> Texture

Parameters:

renderer (Renderer) -- Rendering context for the texture.
surface (Surface) -- The surface to create a texture from.

get_rect()¶: Get the rectangular area of the texture

get_rect(**kwargs) -> Rect

Like pygame.Surface.get_rect()get the rectangular area of the Surface, this method returns a new pygame.Rectpygame object for storing rectangular coordinates covering the entire texture. It will always have a topleft of (0, 0) with a width and height the same size as the texture.

draw()¶

Copy a portion of the texture to the rendering target

draw(srcrect=None, dstrect=None, angle=0, origin=None, flip_x=False, flip_y=False) -> None

Parameters:

srcrect -- The source rectangle on the texture, or None for the entire texture.
dstrect -- The destination rectangle on the rendering target, or None for the entire rendering target. The texture will be stretched to fill dstrect.
angle (float) -- The angle (in degrees) to rotate dstrect around (clockwise).
origin -- The point around which dstrect will be rotated. If None, it will equal the center: (dstrect.w/2, dstrect.h/2).
flip_x (bool) -- Flip the drawn texture portion horizontally (x - axis).
flip_y (bool) -- Flip the drawn texture portion vertically (y - axis).

draw_triangle()¶

Copy a triangle portion of the texture to the rendering target using the given coordinates

draw_triangle(p1_xy, p2_xy, p3_xy, p1_uv=(0.0, 0.0), p2_uv=(1.0, 1.0), p3_uv=(0.0, 1.0), p1_mod=(255, 255, 255, 255), p2_mod=(255, 255, 255, 255), p3_mod=(255, 255, 255, 255)) -> None

Parameters:

p1_xy -- The first vertex coordinate on the rendering target.
p2_xy -- The second vertex coordinate on the rendering target.
p3_xy -- The third vertex coordinate on the rendering target.
p1_uv -- The first UV coordinate of the triangle portion.
p2_uv -- The second UV coordinate of the triangle portion.
p3_uv -- The third UV coordinate of the triangle portion.
p1_mod -- The first vertex color modulation.
p2_mod -- The second vertex color modulation.
p3_mod -- The third vertex color modulation.

draw_quad()¶

Copy a quad portion of the texture to the rendering target using the given coordinates

draw_quad(p1_xy, p2_xy, p3_xy, p4_xy, p1_uv=(0.0, 0.0), p2_uv=(1.0, 0.0), p3_uv=(1.0, 1.0), p4_uv=(0.0, 1.0), p1_mod=(255, 255, 255, 255), p2_mod=(255, 255, 255, 255), p3_mod=(255, 255, 255, 255), p4_mod=(255, 255, 255, 255)) -> None

Parameters:

p1_xy -- The first vertex coordinate on the rendering target.
p2_xy -- The second vertex coordinate on the rendering target.
p3_xy -- The third vertex coordinate on the rendering target.
p4_xy -- The fourth vertex coordinate on the rendering target.
p1_uv -- The first UV coordinate of the quad portion.
p2_uv -- The second UV coordinate of the quad portion.
p3_uv -- The third UV coordinate of the quad portion.
p4_uv -- The fourth UV coordinate of the quad portion.
p1_mod -- The first vertex color modulation.
p2_mod -- The second vertex color modulation.
p3_mod -- The third vertex color modulation.
p4_mod -- The fourth vertex color modulation.

update()¶

Update the texture with Surface (slow operation, use sparingly)

update(surface, area=None) -> None

Parameters:

surface (Surface) -- The source surface.
area -- The rectangular area of the texture to update.

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.

While this function will work with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

pygame._sdl2.video.Image¶

pygame object that represents a portion of a texture

Image(texture_or_image, srcrect=None) -> Image

pygame._sdl2.video.Image.angle	—	Get and set the angle the Image draws itself with
pygame._sdl2.video.Image.flip_x	—	Get or set whether the Image is flipped on the x axis
pygame._sdl2.video.Image.flip_y	—	Get or set whether the Image is flipped on the y axis
pygame._sdl2.video.Image.color	—	Get or set the Image color modifier
pygame._sdl2.video.Image.alpha	—	Get or set the Image alpha modifier (0-255)
pygame._sdl2.video.Image.blend_mode	—	Get or set the blend mode for the Image
pygame._sdl2.video.Image.texture	—	Get or set the Texture the Image is based on
pygame._sdl2.video.Image.srcrect	—	Get or set the Rect the Image is based on
pygame._sdl2.video.Image.origin	—	Get or set the Image's origin of rotation
pygame._sdl2.video.Image.get_rect	—	Get the rectangular area of the Image
pygame._sdl2.video.Image.draw	—	Copy a portion of the Image to the rendering target

Creates an Image.

Parameters:

texture_or_image (Texture | Image) -- The Texture or an existing Image object to create the Image from.
srcrect -- The rectangular portion of the Texture or Image object passed to texture_or_image.

An Image object represents a portion of a Texture. Specifically, they can be used to store and manipulate arguments for Texture.draw() in a more user-friendly way.

angle¶: Get and set the angle the Image draws itself with

angle -> float

flip_x¶: Get or set whether the Image is flipped on the x axis

flip_x -> bool

flip_y¶: Get or set whether the Image is flipped on the y axis

flip_y -> bool

color¶: Get or set the Image color modifier

color -> Color

alpha¶: Get or set the Image alpha modifier (0-255)

alpha -> float

blend_mode¶: Get or set the blend mode for the Image

blend_mode -> int

texture¶: Get or set the Texture the Image is based on

texture -> Texture

srcrect¶: Get or set the Rect the Image is based on

srcrect -> Rect

origin¶

Get or set the Image's origin of rotation

origin -> (float, float) or None

Gets or sets the Image's origin of rotation, a 2D coordinate relative to the topleft coordinate of the Image's rectangular area.

An origin of None means no origin was set and the Image will be rotated around its center.

get_rect()¶: Get the rectangular area of the Image

get_rect() -> Rect

Note

The returned Rect object might contain position information relative to the bounds of the Texture or Image object it was created from.

draw()¶

Copy a portion of the Image to the rendering target

draw(srcrect=None, dstrect=None) -> None

Parameters:

srcrect -- Source rectangle specifying a sub-Image, or None for the entire Image.
dstrect -- Destination rectangle or position on the render target, or None for entire target. The Image is stretched to fill dstrect.

pygame._sdl2.video.Renderer¶

pygame object wrapping a 2D rendering context for a window

Renderer(window, index=-1, accelerated=-1, vsync=False, target_texture=False) -> Renderer

pygame._sdl2.video.Renderer.draw_blend_mode	—	Get or set the blend mode used for primitive drawing operations
pygame._sdl2.video.Renderer.draw_color	—	Get or set the color used for primitive drawing operations
pygame._sdl2.video.Renderer.logical_size	—	Get or set the logical Renderer size (a device independent resolution for rendering)
pygame._sdl2.video.Renderer.scale	—	Get the drawing scale for the current rendering target
pygame._sdl2.video.Renderer.target	—	Get or set the current rendering target
pygame._sdl2.video.Renderer.from_window	—	Create a Renderer from an existing window
pygame._sdl2.video.Renderer.clear	—	Clear the current rendering target with the drawing color
pygame._sdl2.video.Renderer.present	—	Update the screen with any rendering performed since the previous call
pygame._sdl2.video.Renderer.get_viewport	—	Get the drawing area on the rendering target
pygame._sdl2.video.Renderer.set_viewport	—	Set the drawing area on the rendering target
pygame._sdl2.video.Renderer.blit	—	Draw textures using a Surface-like API
pygame._sdl2.video.Renderer.draw_line	—	Draw a line
pygame._sdl2.video.Renderer.draw_point	—	Draw a point
pygame._sdl2.video.Renderer.draw_rect	—	Draw a rectangle outline
pygame._sdl2.video.Renderer.fill_rect	—	Draw a filled rectangle
pygame._sdl2.video.Renderer.draw_triangle	—	Draw a triangle outline
pygame._sdl2.video.Renderer.fill_triangle	—	Draw a filled triangle
pygame._sdl2.video.Renderer.draw_quad	—	Draw a quad outline
pygame._sdl2.video.Renderer.fill_quad	—	Draw a filled quad
pygame._sdl2.video.Renderer.to_surface	—	Read pixels from current rendering target and create a Surface (slow operation, use sparingly)
pygame._sdl2.video.Renderer.compose_custom_blend_mode	—	Compose a custom blend mode

Creates a 2D rendering context for a window.

Parameters:

window (Window) -- The window onto which the rendering context should be placed.
index (int) -- The index of rendering driver to initialize, or -1 to init the first supporting the requested options.
accelerated (int) -- If 1, the renderer uses hardware acceleration. if 0, the renderer is a software fallback. -1 gives precedence to renderers using hardware acceleration.
vsync (bool) -- If True Renderer.present() is synchronized with the refresh rate.
target_texture (bool) -- Whether the renderer should support setting Texture objects as target textures, to enable drawing onto them.

Renderer objects provide a cross-platform API for rendering 2D graphics onto a Window, by using either Metal (macOS), OpenGL (macOS, Windows, Linux) or Direct3D (Windows) rendering drivers, depending on what is set or is available on a system during their creation.

They can be used to draw both Texture objects and simple points, lines and rectangles (which are colored based on Renderer.draw_color).

If configured correctly and supported by an underlying rendering driver, Renderer objects can have a Texture object temporarily set as a target texture (the Texture object must have been created with target texture usage support), which allows those textures to be drawn onto.

To present drawn content onto the window, Renderer.present() should be called. Renderer.clear() should be called to clear any drawn content with the set Renderer draw color.

When things are drawn onto Renderer objects, an internal batching system is used by default to batch those "draw calls" together, to have all of them be processed in one go when Renderer.present() is called. This is unlike pygame.Surfacepygame object for representing images objects, on which modifications via blitting occur immediately, but lends well to the behavior of GPUs, as draw calls can be expensive on lower-end models.

draw_blend_mode¶: Get or set the blend mode used for primitive drawing operations

draw_blend_mode -> int

draw_color¶: Get or set the color used for primitive drawing operations

draw_color -> Color

logical_size¶: Get or set the logical Renderer size (a device independent resolution for rendering)

logical_size -> (int width, int height)

scale¶: Get the drawing scale for the current rendering target

scale -> (float, float)

target¶: Get or set the current rendering target

target -> Texture or None

Gets or sets the current rendering target. A value of None means that no custom rendering target was set and the Renderer's window will be used as the target.

classmethod from_window()¶: Create a Renderer from an existing window

from_window(window) -> Renderer

clear()¶: Clear the current rendering target with the drawing color

clear() -> None

present()¶: Update the screen with any rendering performed since the previous call

present() -> None

Presents the composed backbuffer to the screen. Updates the screen with any rendering performed since the previous call.

get_viewport()¶: Get the drawing area on the rendering target

get_viewport() -> Rect

set_viewport()¶

Set the drawing area on the rendering target

set_viewport(area) -> None

Parameters:: area -- A pygame.Rectpygame object for storing rectangular coordinates or tuple representing the drawing area on the target, or None to use the entire area of the current rendering target.

blit()¶

Draw textures using a Surface-like API

blit(source, dest, area=None, special_flags=0)-> Rect

For compatibility purposes. Draws Texture objects onto the Renderer using a method signature similar to pygame.Surface.blit()draw another surface onto this one.

Parameters:

source -- A Texture or Image to draw.
dest -- The drawing destination on the rendering target.
area -- The portion of the source texture or image to draw from.
special_flags -- have no effect at this moment.

Note

Textures created by different Renderers cannot shared with each other!

draw_line()¶

Draw a line

draw_line(p1, p2) -> None

Parameters:

p1 -- The line start point.
p2 -- The line end point.

draw_point()¶

Draw a point

draw_point(point) -> None

Parameters:: point -- The point's coordinate.

draw_rect()¶

Draw a rectangle outline

draw_rect(rect)-> None

Parameters:: rect -- The pygame.Rectpygame object for storing rectangular coordinates-like rectangle to draw.

fill_rect()¶

Draw a filled rectangle

fill_rect(rect)-> None

Parameters:: rect -- The pygame.Rectpygame object for storing rectangular coordinates-like rectangle to draw.

draw_triangle()¶

Draw a triangle outline

draw_triangle(p1, p2, p3) -> None

Parameters:

p1 -- The first triangle point.
p2 -- The second triangle point.
p2 -- The third triangle point.

fill_triangle()¶

Draw a filled triangle

fill_triangle(p1, p2, p3) -> None

Parameters:

p1 -- The first triangle point.
p2 -- The second triangle point.
p2 -- The third triangle point.

draw_quad()¶

Draw a quad outline

draw_quad(p1, p2, p3, p4) -> None

Parameters:

p1 -- The first quad point.
p2 -- The second quad point.
p2 -- The third quad point.
p2 -- The fourth quad point.

fill_quad()¶

Draw a filled quad

fill_quad(p1, p2, p3, p4) -> None

Parameters:

p1 -- The first quad point.
p2 -- The second quad point.
p2 -- The third quad point.
p2 -- The fourth quad point.

to_surface()¶

Read pixels from current rendering target and create a Surface (slow operation, use sparingly)

to_surface(surface=None, area=None)-> Surface

Read pixel data from the current rendering target and return a pygame.Surfacepygame object for representing images containing it.

Parameters:

surface (Surface) -- A pygame.Surfacepygame object for representing images object to read the pixel data into. It must be large enough to fit the area, otherwise ValueError is raised. If set to None, a new surface will be created.
area -- The area of the screen to read pixels from. The area is clipped to fit inside the viewport. If None, the entire viewport is used.

Note

This is a very slow operation, due to the overhead of the VRAM to RAM data transfer and the cost of creating a potentially large pygame.Surfacepygame object for representing images. It should not be used frequently.

compose_custom_blend_mode()¶

Compose a custom blend mode

compose_custom_blend_mode(color_mode, alpha_mode) -> int

Compose a custom blend mode. See https://wiki.libsdl.org/SDL2/SDL_ComposeCustomBlendMode for more information.

Parameters:

color_mode -- A tuple (srcColorFactor, dstColorFactor, colorOperation)
alpha_mode -- A tuple (srcAlphaFactor, dstAlphaFactor, alphaOperation)

Returns:

A blend mode to be used with Renderer.set_draw_blend_mode() and Texture.set_blend_mode().

Edit on GitHub

pygame-ce documentation