Table of Contents

Class Surface

Namespace
Gym.Rendering
Assembly
Gym.Rendering.dll

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

width int

Columns; 0 is allowed, as in pygame (nothing can be drawn on it).

height int

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

width int

Columns; 0 is allowed, as in pygame (nothing can be drawn on it).

height int

Rows; 0 is allowed.

hasAlpha bool

Whether 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

bool

Height

The number of rows, surface.get_height().

public int Height { get; }

Property Value

int

Width

The number of columns, surface.get_width().

public int Width { get; }

Property Value

int

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

source Surface

The surface to copy or blend from.

x int

Where the source's left column lands.

y int

Where the source's top row lands.

Exceptions

ArgumentNullException

Thrown when source is 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

color Color

The 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

x int

The column.

y int

The row.

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 * 3 bytes.

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 * 4 bytes.