pygame.sdl2_video — pygame-ce v2.3.2 documentation

##### 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 | version

`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.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
    Window(title='pygame window', size=(640, 480), position=None, fullscreen=False, fullscreen_desktop=False, **kwargs) -> Window

    Creates a window.

    Parameters:

      - title (str) -- The title of the window.

      - size ((int, int)) -- The size of the window, in screen coordinates.

      - position ((int, int) or int) -- A tuple specifying the window position, or `WINDOWPOS_CENTERED`, or `WINDOWPOS_UNDEFINED`.

      - fullscreen (bool) -- Create a fullscreen window using the window size as the resolution (videomode change).

      - fullscreen_desktop (bool) -- Create a fullscreen window using the current desktop resolution.

      - opengl (bool) -- Create a window with support for an OpenGL context. You will still need to create an OpenGL context separately.

      - vulkan (bool) -- Create a window with support for a Vulkan instance.

      - hidden (bool) -- Create a hidden window.

      - borderless (bool) -- Create a window without borders.

      - resizable (bool) -- Create a resizable window.

      - minimized (bool) -- Create a mimized window.

      - maximized (bool) -- Create a maximized window.

      - input_grabbed (bool) -- Create a window with a grabbed input focus.

      - input_focus (bool) -- Create a window with input focus.

      - mouse_focus (bool) -- Create a window with mouse focus.

      - foreign (bool) -- Marks a window not created by SDL.

      - allow_highdpi (bool) -- Create a window in high-DPI mode if supported.

      - mouse_capture (bool) -- Create a window that has the mouse captured (unrelated to INPUT_GRABBED).

      - always_on_top (bool) -- Create a window that is always on top (X11 only).

      - skip_taskbar (bool) -- Create a window that should not be added to the taskbar (X11 only).

      - utility (bool) -- Create a window that should be treated as a utility window (X11 only).

      - tooltip (bool) -- Create a window that should be treated as a tooltip (X11 only).

      - popup_menu (bool) -- Create a window that should be treated as a popup menu (X11 only).

    grab
      Get or set the window's input grab state
      grab -> bool

      Gets or sets the window's input grab state. When input is grabbed, the mouse is confined to the window. If the caller enables a grab while another window is currently grabbed, the other window loses its grab in favor of the caller's window.

    relative_mouse
      Get or set the window's relative mouse mode state
      relative_mouse -> bool

      Gets or sets the window's relative mouse mode state. SDL2 docs: "While the mouse is in relative mode, the cursor is hidden, the mouse position is constrained to the window, and SDL will report continuous relative mouse motion even if the mouse is at the edge of the window.

      This function will flush any pending mouse motion."

      Calling `pygame.mouse.set_visible()`hide or show the mouse cursor with argument `True` will exit relative mouse mode.

    title
      Get or set the window title
      title -> str

      Gets or sets the window title. An empty string means that no title is set.

    resizable
      Get or set whether the window is resizable
      resizable -> bool
    borderless
      Get or set whether the window is borderless
      borderless -> bool

      Gets or sets whether the window is borderless.

      Note

      You can't change the border state of a fullscreen window.

    always_on_top
      Get or set whether the window is always on top
      always_on_top -> bool

      Get or set whether the window is always on top.

      Setting the always-on-top mode requires SDL 2.0.16+.

      New in pygame-ce 2.3.1.

    id
      Get the unique window ID (**read-only**)
      id -> int
    size
      Get or set the window size in pixels
      size -> (int, int)
    position
      Get or set the window position in screen coordinates
      position -> (int, int) or WINDOWPOS_CENTERED or WINDOWPOS_UNDEFINED
    opacity
      Get or set the window opacity, between 0.0 (fully transparent) and 1.0 (fully opaque)
      opacity -> float
    display_index
      Get the index of the display that owns the window (**read-only**)
      get_display_index -> int
    classmethod from_display_module()
      Create a Window object using window data from display module
      from_display_module() -> Window

      Create a Window object that uses the same window data from the `pygame.display`pygame module to control the display window and screen module, created upon calling `pygame.display.set_mode()`Initialize a window or screen for display.

    set_windowed()
      Enable windowed mode (exit fullscreen)
      set_windowed() -> None

      See also

      `set_fullscreen()`

    set_fullscreen()
      Enter fullscreen
      set_fullscreen(desktop=False) -> None
      Parameters:

        desktop (bool) -- If `True`, use the current desktop resolution. If `False`, change the fullscreen resolution to the window size.

      See also

      `set_windowed()`.

    destroy()
      Destroy the window
      destroy() -> None

      Destroys the internal window data of this Window object. This method is called automatically when this Window object is garbage collected, so there usually aren't any reasons to call it manually.

      Other methods that try to manipulate that window data will raise an error.

    hide()
      Hide the window
      hide() -> None
    show()
      Show the window
      show() -> None
    focus()
      Set the window to be focused
      focus(input_only=False) -> None

      Raises the window above other windows and sets the input focus.

      Parameters:

        input_only (bool) -- if `True`, the window will be given input focus but may be completely obscured by other windows. Only supported on X11.

    restore()
      Restore the size and position of a minimized or maximized window
      restore() -> None
    maximize()
      Maximize the window
      maximize() -> None
    minimize()
      Minimize the window
      maximize() -> None
    set_icon()
      Set the window icon
      set_icon(surface) -> None

      Sets the window icon.

      Parameters:

        surface (Surface) -- A Surface to use as the icon.

    set_modal_for()
      Set the window as a modal for a parent window
      set_modal_for(parent) -> None
      Parameters:

        parent (Window) -- The parent window.

      Note

      This function is only supported on X11.

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

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

    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 one image onto another.

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