##### pygame-ce documentation

Pygame-ce Home || Help Contents || Reference Index

Most useful stuff: Color | display | draw | event | font | image | key | locals | mixer | mouse | Rect | Surface | time | music | pygame

Advanced stuff: cursors | joystick | mask | sprite | transform | BufferProxy | freetype | gfxdraw | midi | PixelArray | pixelcopy | sndarray | surfarray | math

Other: camera | controller | examples | scrap | system | tests | touch | typing | version | Window

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

  Experimental pygame module for porting new SDL video systems
  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.Window` Pygame 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

    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.Surface` Pygame 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.Surface` Pygame 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.Rect` pygame 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

    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 point relative to the topleft coordinates 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

    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.Surface` Pygame 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)

      Note: When the rendering target is the main window, and `logical_size` has not been set before, it will contain `(0, 0)` and not the size of the window.

    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.Rect` pygame 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.

    coordinates_to_window()
      Translates renderer coordinates to window coordinates
      coordinates_to_window(point) -> (float, float)
      Parameters:

        point -- The coordinates in render space.

      New in pygame-ce 2.5.6.

    coordinates_from_window()
      Translates window coordinates to renderer coordinates
      coordinates_from_window(point) -> (float, float)
      Parameters:

        point -- The coordinates in window space.

      New in pygame-ce 2.5.6.

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

    draw_rect()
      Draw a rectangle outline
      draw_rect(rect)-> None
      Parameters:

        rect -- The `pygame.Rect` pygame object for storing rectangular coordinates-like rectangle to draw.

    fill_rect()
      Draw a filled rectangle
      fill_rect(rect)-> None
      Parameters:

        rect -- The `pygame.Rect` pygame 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.Surface` Pygame object for representing images. containing it.

      Parameters:

        - surface (Surface) -- A `pygame.Surface` Pygame 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.Surface` Pygame 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