pygame2.sdl.video – SDL video display wrapper module.

SDL video display wrapper module.

Module Functions

pygame2.sdl.video.get_drivername() → str

Gets the name of the video driver.

Gets the name of the video driver or None, if the video system has not been initialised or it could not be determined.

pygame2.sdl.video.get_gammaramp() -> (int, int, ...), (int, int, ...), (int, int, ...)

Gets the color gamma lookup tables for the display.

Gets the color gamma lookup table for the display. This will return three tuples for the red, green and blue gamma values. Each tuple contains 256 values.

pygame2.sdl.video.get_info() → dict

Gets information about the video hardware.

Gets information about the video hardware. The returned dictionary contains the following entries.

Entry Meaning
hw_available Is it possible to create hardware surfaces?
wm_available Is a window manager available?
blit_hw Are hardware to hardware blits accelerated?
blit_hw_CC Are hardware to hardware colorkey blits accelerated?
blit_hw_A Are hardware to hardware alpha blits accelerated?
blit_sw Are software to hardware blits accelerated?
blit_sw_CC Are software to hardware colorkey blits accelerated?
blit_sw_A Are software to hardware alpha blits accelerated?
blit_fill Are color fills accelerated?
video_mem Total amount of video memory in Kilobytes
vfmt Pixel format of the video device
pygame2.sdl.video.get_videosurface() → Surface
Gets the current display surface or None, if there is no such Surface.
pygame2.sdl.video.init() → None
Initializes the video subsystem of the SDL library.
pygame2.sdl.video.is_mode_ok(width, height[, bpp, flags]) → bool
pygame2.sdl.video.is_mode_ok(size[, bpp, flags]) → bool

Checks, whether the requested video mode is supported.

Checks, whether the video mode is supported for the passed size, bit depth and flags. If the bit depth (bpp) argument is omitted, the current screen bit depth will be used.

The optional flags argument is the same as for set_mode().

pygame2.sdl.video.list_modes([format, flags]) → [rect, rect, ...]

Returns the supported modes for a specific format and flags.

Returns the supported modes for a specific format and flags. The optional format argument must be a PixelFormat instance with the desired mode information. The optional flags argument is the same as for set_mode().

If both, the format and flags are omitted, all supported screen resolutions for all supported formats and flags are returned.

pygame2.sdl.video.quit() → None

Shuts down the video subsystem of the SDL library.

After calling this function, you should not invoke any class, method or function related to the video subsystem as they are likely to fail or might give unpredictable results.

pygame2.sdl.video.set_gamma(red, green, blue) → None

Sets the gamma values for all three color channels.

Sets the gamma values for all three color channels. In case adjusting the gamma is not supported, an exception will be raised.

pygame2.sdl.video.set_gammaramp(redtable, greentable, bluetable) → None

Sets the color gamma lookup tables for the display.

Sets the color gamma lookup table for the display. The three arguments must be sequences with 256 integer value enties for the gamma ramps.

pygame2.sdl.video.set_mode(width, height[, bpp, flags]) → Surface
pygame2.sdl.video.set_mode(size[, bpp, flags]) → Surface

Creates the main display Surface.

Creates the main display Surface using the specified size, bit depth and flags. If the bit depth (bpp) argument is omitted, the current screen bit depth will be used.

The optional flags argument can be a bitwise OR’d combination of the surface flags from the pygame2.sdl.constants.

pygame2.sdl.video.was_init() → bool
Returns, whether the video subsystem of the SDL library is initialized.

Overlay

class pygame2.sdl.video.Overlay(surface, width, height, format) → Overlay
class pygame2.sdl.video.Overlay(surface, size, format) → Overlay

Creates a new Overlay for a surface.

The Overlay objects provide support for accessing hardware video overlays. Video overlays do not use standard RGB pixel formats, and can use multiple resolutions of data to create a single image.

The Overlay objects represent lower level access to the display hardware. To use the object you should understand the technical details of video overlays.

The Overlay format determines the type of pixel data used. Not all hardware will support all types of overlay formats. Supported format types are listed in the pygame2.sdl.constants module.

The width and height arguments control the size for the overlay image data. The overlay image can be displayed at any size, not just the resolution of the overlay and are always visible, and always show above the regular display contents.

Attributes

Overlay.format
Gets the format of the Overlay.
Overlay.h
Gets the height of the Overlay.
Overlay.height
Gets the height of the Overlay.
Overlay.hw_overlay
Gets, whether the Overlay is hardware accelerated.
Overlay.locked
Gets, whether the Overlay is currently locked.
Overlay.pitches
Gets the pitches (length in bytes) for all planes of the Overlay.
Overlay.pixels
Gets the pixel buffers for all planes of the Overlay.
Overlay.planes
Get the amount of planes for the Overlay.
Overlay.size
Gets the width and height of the Overlay.
Overlay.w
Gets the width of the Overlay.
Overlay.width
Gets the width of the Overlay.

Methods

Overlay.display([rect]) → None
Displays the current overlay data in the SDL overlay plane.
Overlay.lock() → None
Locks the Overlay for a direct access to its internal pixel data.
Overlay.unlock() → None
Unlocks the Overlay, releasing the direct access to the pixel data.

PixelFormat

class pygame2.sdl.video.PixelFormat → PixelFormat

Creates a new, empty PixelFormat.

The PixelFormat typically describes a Surface‘s pixel buffer representation. It contains information about the bit depth, RGBA masks, the palette and transparency information.

Attributes

PixelFormat.alpha
Gets or sets the overall surface alpha value in the range [0, 255].
PixelFormat.bits_per_pixel
Gets or sets the bits per pixel to use for storing a RGBA value.
PixelFormat.bytes_per_pixel
Gets or sets the bytes per pixel to use for storing a RGBA value.
PixelFormat.colorkey
Gets or sets the RGBA value of transparent pixels.
PixelFormat.losses
Gets or sets the precision loss of each RGBA color component.
PixelFormat.masks
Gets or sets the binary masks used to retrieve individual color values.
PixelFormat.palette
Gets the color palette (if any) used by the PixelFormat. If the PixelFormat does not have any palette, None will be returned.
PixelFormat.readonly
Gets, whether the PixelFormat is read-only (this cannot be changed).
PixelFormat.shifts
Gets the binary left shift of each color component in the pixel value.

Methods

PixelFormat.get_rgba(color) → :class:`pygame2.Color`

Gets the best matching pygame2.Color for the passed color.

Gets a color value, which fits the PixelFormat best. This means that an internal conversion is done (on demand) to match the passed color to the PixelFormat’s supported value ranges. If the PixelFormat does not have alpha transparency support, the color’s alpha value will be set to fully opaque (255).

PixelFormat.map_rgba(r, g, b[, a]) → long
PixelFormat.map_rgba(color) → long

Converts a color to the best value matching the format.

Gets a color value, which fits the PixelFormat best. This means that an internal conversion is done (on demand) to match the passed color to the PixelFormat’s supported value ranges. Instead of returning a color as in get_rgba(), an integer value matching the PixelFormat’s supported value ranges will be returned.

Surface

class pygame2.sdl.video.Surface(width, height[, depth, flags, masks]) → Surface
class pygame2.sdl.video.Surface(size[, depth, flags, masks]) → Surface

Creates a new Surface to represent image data.

Creates a new Surface which represents a rectangular area of pixel information, typically displaying some sort of image data. The Surface is the central element of the pygame2.sdl.video module and used to display image information on an SDL screen window.

Todo

TODO

Attributes

Surface.clip_rect
Gets or sets the current clipping rectangle for operations on the Surface.
Surface.flags
The currently set flags for the Surface.
Surface.format
Gets the (read-only) PixelFormat for this Surface.
Surface.h
Gets the height of the Surface.
Surface.height
Gets the height of the Surface.
Surface.locked
Gets, whether the Surface is currently locked.
Surface.pitch
Get the length of a surface scanline in bytes.
Surface.pixels
Gets the pixel buffer of the Surface.
Surface.size
Gets the size of the Surface.
Surface.w
Gets the width of the Surface.
Surface.width
Gets the width of the Surface.

Methods

Surface.blit(srcsurface[, destrect, srcrect, blendargs]) → Rect

Draws the passed source surface onto this surface.

Draws the passed source surface onto this surface. The destrect and srcrect arguments are used for clipping the destination area (on this surface) and source area (on the source surface). For the destination rectangle, the width and height are ignored, only the position is taken into account. For the source rectangle, all values, position as well as the size are used for clipping.

The optional blendargs for the drawing operation perform certain specialised pixel manipulations. For those, pixels on the same position are evaluated and the result manipulated according to the argument.

For all supported blending operations take a look at the blending constants in the pygame2.sdl.constants module.

Surface.copy() → Surface
Creates an exact copy of the Surface and its image data.
Surface.convert([pixelformat, flags]) → Surface

Converts the Surface to the desired pixel format.

Converts the Surface to the desired pixel format. If no format is given, the active display format is used, which will be the fastest for blit operations to the screen. The flags are the same as for surface creation.

This creates a new, converted surface and leaves the original one untouched.

Surface.fill(color[, dstrect, blendargs]) → None

Fills the Surface with a color.

Fills the Surface with the desired color. The color does not need to match the Surface’s format, it will be converted implicitly to the nearest appropriate color for its format.

The optional destination rectangle limits the color fill to the specified area. The blendargs are the same as for the blit() operation, but compare the color with the specific Surface pixel value.

Surface.flip() → None

Swaps the screen buffers for the Surface.

Swaps screen buffers for the Surface, causing a full update and redraw of its whole area.

Surface.get_alpha() → int

Gets the current overall alpha value of the Surface.

Gets the current overall alpha value of the Surface. In case the surface does not support alpha transparency (SRCALPHA flag not set), None will be returned.

Surface.get_at(x, y) → Color
Surface.get_at(point) → Color
Gets the Surface pixel value at the specified point.
Surface.get_colorkey() → Color

Gets the colorkey for the Surface.

Gets the colorkey for the Surface or None in case it has no colorkey (SRCCOLORKEY flag not set).

Surface.get_palette() -> (Color, Color, ...)

Gets the palette colors used by the Surface.

Gets the palette colors used by the Surface or None, if the Surface does not use any palette.

Surface.lock() → None
Locks the Surface for a direct access to its internal pixel data.
Surface.save(file[, type]) → None

Saves the Surface to a file.

Saves the Surface to a file. The file argument can be either a file name or a file-like object to save the Surface to. The optional type argument is required, if the file type cannot be determined by the suffix.

Currently supported file types (suitable to pass as string for the type argument) are:

  • BMP
  • TGA
  • PNG
  • JPEG (JPG)

If no type information is supplied and the file type cannot be determined either, it will use TGA.

Note

The file object must support binary read and write access. This is especially important for Python 3.x users.

Surface.scroll([dx, dy]) → None

Scrolls the Surface in place.

Move the Surface contents by dx pixels right and dy pixels down. dx and dy may be negative for left and up scrolls respectively. Areas of the surface that are not overwritten retain their original pixel values. Scrolling is contained by the Surface clip area. It is safe to have dx and dy values that exceed the surface size.

Surface.set_alpha(alpha[, flags]) → None

Adjusts the alpha properties of the Surface.

TODO

Surface.set_at(x, y, color) → None
Surface.set_at(point, color) → None
Sets the Surface pixel value at the specified point.
Surface.set_colorkey(color[, flags]) → None

Adjusts the colorkey of the Surface.

Sets the colorkey of the Surface to the passed value. if flags is omitted, SRCCOLORKEY will be used, if flags is set to 0, the colorkey will be reset.

The colorkey denotes a certain pygame2.Color, which will be used for emulating transparency. Each pixel on the Surface matching the set color will be ignored on blit operations.

Surface.set_colors((color1, color2, ...)[, first]) → bool

Sets a portion of the colormap palette for the 8-bit Surface.

Sets a portion of the colormap palette for the 8-bit Surface, starting at the desired first position. If the first position plus length of the passed colormap exceeds the Surface palette size, the palette will be unchanged and False returned.

If any other error occurs, False will be returned and the Surface palette should be inspected for any changes.

Surface.set_palette((color1, color2, ...)[, flags, first]) → bool

Sets a portion of the palette for the given 8-bit surface.

Sets a portion of the color palette for the 8-bit Surface, starting at the desired first position. If the first position plus length of the passed colormap exceeds the Surface palette size, the palette will be unchanged and False returned.

If flags is omitted and a Surface with hardware palette used, both the physical and logical palettes will be modified. Otherwise, flags can be set to LOGPAL or PHYSPAL or a combination to modify either the logical, physical or both palettes.

If any other error occurs, False will be returned and the Surface palette should be inspected for any changes.

Surface.unlock() → None
Unlocks the Surface, releasing the direct access to the pixel data.
Surface.update([rect]) → None
Surface.update([(rect1, rect2, ...)]) → None

Updates the given area on the Surface.

Upates the given area (or areas, if a list of rects is passed) on the Surface, performing partial screen buffer swaps. For smaller portions of the Surface, this is much faster than running flip().