Table of Contents

Class SurfArray

Namespace
Gym.Rendering
Assembly
Gym.Rendering.dll

The part of pygame.surfarray Gymnasium's envs use to hand out rgb_array frames: a surface's pixels as a uint8 array in pygame's axis order, or already transposed into the frame an env returns.

public static class SurfArray
Inheritance
SurfArray
Inherited Members

Remarks

Reference: src_py/surfarray.py (pygame-ce 2.5.8).

Methods

Array3d(Surface)

pygame.surfarray.array3d(surface), equivalently np.array(pygame.surfarray.pixels3d(surface)): a (width, height, 3) uint8 copy of the pixels in pygame's [x][y] order.

public static NDArray Array3d(Surface surface)

Parameters

surface Surface

The surface.

Returns

NDArray

A new array the caller owns (dispose it).

Remarks

Gymnasium's envs transpose it to (height, width, 3); ToRgbBytes() and ToRgbArray(Surface) give that frame directly.

Exceptions

ArgumentNullException

Thrown when surface is null.

MakeSurface(NDArray)

pygame.surfarray.make_surface(array): a new surface holding an array's pixels in pygame's [x][y] order, so a (width, height, 3) array gives a width by height surface. play shows each frame through it, after swapping a frame's first two axes.

public static Surface MakeSurface(NDArray array)

Parameters

array NDArray

A uint8 array: (width, height, 3) RGB, or (width, height), whose values pygame reads as indices into its 8-bit palette (not as gray levels; see the remarks). Views (a transposed frame) are read as they are.

Returns

Surface

A new opaque surface the caller owns.

Remarks

pygame makes an 8-bit palettized surface of a 2-D array, with a palette of period 128 measured on pygame-ce 2.5.8: index i is (((i >> 5) & 3) * 85, round(((i >> 2) & 7) * 255 / 7), (i & 3) * 85), so 100 is (255, 36, 0). This surface holds those colours directly; scaling it and blitting it give the same pixels as pygame's palettized one.

Reference: src_c/pixelcopy.c (pygame-ce 2.5.8).

Exceptions

ArgumentNullException

Thrown when array is null.

ValueError

Thrown for any other shape, with pygame's message, which ends in a newline: must be a valid 2d or 3d array followed by \n.

NotSupportedException

Thrown for a dtype other than uint8: pygame converts those by rules no Gymnasium code relies on, which are not modelled.

ToRgbArray(Surface)

The frame Gymnasium's render() returns for render_mode="rgb_array", np.transpose(np.array(pygame.surfarray.pixels3d(surface)), axes=(1, 0, 2)): (height, width, 3) uint8, C-contiguous as NumPy's is.

public static NDArray ToRgbArray(Surface surface)

Parameters

surface Surface

The surface.

Returns

NDArray

A new array the caller owns (dispose it).

Exceptions

ArgumentNullException

Thrown when surface is null.