Class Surface
A drawing surface as Gymnasium's envs create one with pygame.Surface((width, height)): 32 bits per pixel
without per-pixel alpha (SDL's XRGB8888, masks 0xff0000, 0xff00, 0xff, alpha mask 0), black
when created, with pygame's (x, y) addressing and its whole area as the clip rectangle. A surface with
per-pixel alpha (HasAlpha) is what Load(string) gives for a PNG with an alpha channel,
and what transform.scale/smoothscale/flip give for one.
public sealed class Surface
- Inheritance
-
Surface
- Inherited Members
- Extension Methods
Remarks
Pixels are kept as SDL keeps them, one 0x00RRGGBB word each, row by row, so the drawing primitives read and
write exactly the words SDL_gfx does. Without per-pixel alpha there is no alpha channel: an RGBA colour's alpha only
weights a blend with the pixel underneath, it is never stored.
With per-pixel alpha each word is 0xAARRGGBB. pygame stores such a surface in its own channel order
(a loaded PNG is ABGR8888); only the values matter here, since every operation works channel by channel. What is
modelled for them is what Gymnasium's envs do with images: loading, Transform's scaling and flipping,
and blitting onto a surface without alpha. Drawing on them, blitting onto them, and blitting an opaque surface onto
them are refused (NotSupportedException) rather than guessed.
Not thread-safe: draw on a surface from one thread at a time, as with pygame.
Reference: src_c/surface.c (pygame-ce 2.5.8).
Constructors
Surface(int, int)
Creates a black surface, pygame.Surface((width, height)).
public Surface(int width, int height)
Parameters
widthintColumns; 0 is allowed, as in pygame (nothing can be drawn on it).
heightintRows; 0 is allowed.
Exceptions
- ArgumentOutOfRangeException
Thrown for a negative size (pygame raises
pygame.error: Invalid resolution for Surface) or one whose pixel count does not fit an array.
Surface(int, int, bool)
Creates a surface, pygame.Surface((width, height)), or with hasAlpha
pygame.Surface((width, height), pygame.SRCALPHA), which starts fully transparent (every pixel
(0, 0, 0, 0), as SDL zero-fills a new surface).
public Surface(int width, int height, bool hasAlpha)
Parameters
widthintColumns; 0 is allowed, as in pygame (nothing can be drawn on it).
heightintRows; 0 is allowed.
hasAlphaboolWhether each pixel carries its own alpha (
pygame.SRCALPHA).
Exceptions
- ArgumentOutOfRangeException
Thrown for a negative size (pygame raises
pygame.error: Invalid resolution for Surface) or one whose pixel count does not fit an array.
Properties
HasAlpha
Whether each pixel carries its own alpha (surface.get_flags() & pygame.SRCALPHA): blitting the surface
then blends each pixel by its alpha instead of copying it.
public bool HasAlpha { get; }
Property Value
Height
The number of rows, surface.get_height().
public int Height { get; }
Property Value
Width
The number of columns, surface.get_width().
public int Width { get; }
Property Value
Methods
Blit(Surface, int, int)
surface.blit(source, (x, y)) onto this surface (which has no per-pixel alpha), clipped to it. An opaque
source (no colour key, no surface alpha, the only kind this assembly creates) is copied; a source with per-pixel
alpha (a loaded PNG) is blended, each channel as d + (((s - d) * a + s) >> 8) with an arithmetic
shift, which is what pygame-ce 2.5.8 computes for this case (measured on all 2^24 source, alpha and destination
values, every channel): alpha 0 keeps the destination and alpha 255 copies the source.
public void Blit(Surface source, int x, int y)
Parameters
sourceSurfaceThe surface to copy or blend from.
xintWhere the source's left column lands.
yintWhere the source's top row lands.
Exceptions
- ArgumentNullException
Thrown when
sourceis null.- NotSupportedException
Thrown when this surface has per-pixel alpha: pygame blends onto such a destination with other rules (its alpha is composited too), which no Gymnasium env relies on, so they are not modelled.
Fill(Color)
surface.fill(color): every pixel becomes the colour's RGB, and with per-pixel alpha its alpha too. Without
it, alpha is ignored, as SDL_FillRect maps the colour into a format that has no alpha.
public void Fill(Color color)
Parameters
colorColorThe colour.
GetAt(int, int)
surface.get_at((x, y)): the pixel's colour, opaque when the surface has no per-pixel alpha (the format
has no alpha to report), else with the pixel's own alpha.
public Color GetAt(int x, int y)
Parameters
Returns
- Color
The colour.
Exceptions
- IndexOutOfRangeException
Thrown outside the surface, as pygame raises
IndexError: pixel index out of range.
ToRgbBytes()
The pixels as (height, width, 3) RGB bytes, row-major: the byte layout of Gymnasium's rgb_array
frames, np.transpose(np.array(surfarray.pixels3d(surface)), axes=(1, 0, 2)). A per-pixel alpha is left out,
as pixels3d leaves it out.
public byte[] ToRgbBytes()
Returns
- byte[]
A new array of
Height * Width * 3bytes.
ToRgbaBytes()
The pixels as (height, width, 4) RGBA bytes, row-major: what pixels3d and pixels_alpha
together hold for a surface with per-pixel alpha, so an image's every channel can be compared. Without per-pixel
alpha the alpha byte is 255, as get_at reports it.
public byte[] ToRgbaBytes()
Returns
- byte[]
A new array of
Height * Width * 4bytes.