Surface Creation and Simple Drawing

class csdl2.SDL_Surface

A structure that contains a collection of pixels used in software blitting.

This structure cannot be initiated directly. Use SDL_CreateRGBSurface(), SDL_CreateRGBSurfaceFrom(), SDL_LoadBMP_RW() or SDL_LoadBMP() to create a new instance.

flags

(readonly) A bitmask of the flags SDL_PREALLOC, SDL_RLEACCEL and/or SDL_DONTFREE for internal use.

format

(readonly) SDL_PixelFormat of the pixels stored in the surface.

w

(readonly) Width of the surface in pixels.

h

(readonly) Height of the surface in pixels.

pitch

(readonly) The length of a row of pixels in bytes.

pixels

(readonly) Buffer providing the actual pixel data.

userdata

An arbitrary object that an application can set for its own use.

locked

(readonly) True if the surface is locked.

clip_rect

(readonly) An SDL_Rect structure used to clip bits to the surface which can be set by SDL_SetClipRect().

refcount

(readonly) SDL’s reference count of the surface. For internal use.

csdl2.SDL_PREALLOC

Surface uses preallocated memory.

csdl2.SDL_RLEACCEL

Surface is RLE encoded.

csdl2.SDL_DONTFREE

Surface is referenced internally.

csdl2.SDL_MUSTLOCK(surface: SDL_Surface) → bool

Returns True if surface needs to be locked before its SDL_Surface.pixels can be accessed.

Parameters:surface (SDL_Surface) – The surface to test
Returns:True if the surface needs to be locked before its pixels can be accessed, False otherwise.
csdl2.SDL_CreateRGBSurface(flags: int, width: int, height: int, depth: int, Rmask: int, Gmask: int, Bmask: int, Amask: int) → SDL_Surface

Creates and returns a new blank SDL_Surface with the specified properties.

Parameters:
  • flags (int) – This argument is unused and should be set to 0.
  • width (int) – The width of the surface in pixels.
  • height (int) – The height of the surface in pixels.
  • depth (int) – The depth of the surface in bits. If depth is 4 or 8 bits, an empty SDL_Palette is allocated for the surface. If depth is greater than 8 bits, the pixel format is set using the Rmask, Gmask, Bmask and Amask arguments.
  • Rmask (int) – Bitmask used to extract the red component from a pixel. If 0, a default mask based on the depth is used.
  • Gmask (int) – Bitmask used to extract the green component from a pixel. If 0, a default mask based on the depth is used.
  • Bmask (int) – Bitmask used to extract the blue component from a pixel. If 0, a default mask based on the depth is used.
  • Amask (int) – Bitmask used to extract the alpha component from a pixel. If 0, the surface has no alpha channel.
Returns:

A new blank SDL_Surface structure.
csdl2.SDL_CreateRGBSurfaceFrom(pixels: buffer, width: int, height: int, depth: int, pitch: int, Rmask: int, Gmask: int, Bmask: int, Amask: int) → SDL_Surface

Creates and returns a SDL_Surface with existing pixel data.

Parameters:
  • pixels (buffer) – Existing pixel data. This can be any object that supports the buffer protocol and exports a C-contiguous buffer of the correct size.
  • width (int) – The width of the surface in pixels.
  • height (int) – The height of the surface in pixels.
  • depth (int) – The depth of the surface in bits. If depth is 4 or 8 bits, an empty SDL_Palette is allocated for the surface. If depth is greater than 8 bits, the pixel format is set using the Rmask, Gmask, Bmask and Amask arguments.
  • Rmask (int) – Bitmask used to extract the red component from a pixel. If 0, a default mask based on the depth is used.
  • Gmask (int) – Bitmask used to extract the green component from a pixel. If 0, a default mask based on the depth is used.
  • Bmask (int) – Bitmask used to extract the blue component from a pixel. If 0, a default mask based on the depth is used.
  • Amask (int) – Bitmask used to extract the alpha component from a pixel. If 0, the surface has no alpha channel.
Returns:

A SDL_Surface with its contents backed by the provided pixels buffer.
csdl2.SDL_LoadBMP_RW(src, freesrc) → SDL_Surface

Load a BMP image from a seekable SDL data stream. (memory or file).

Parameters:
  • src (SDL_RWops) – The data stream for the surface.
  • freesrc (bool) – True to close the stream after being read.
Returns:

SDL_Surface with the image data.
csdl2.SDL_LoadBMP(file) → SDL_Surface

Load a surface from a BMP file on the filesystem.

Parameters:file (str) – The path to the file containing a BMP image.
Returns:SDL_Surface with the image data.
csdl2.SDL_FreeSurface(surface: SDL_Surface)

Frees the surface.

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

Parameters:surface (SDL_Surface) – surface to free