Class SurfArray
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
surfaceSurfaceThe 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
surfaceis 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
arrayNDArrayA 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
arrayis null.- ValueError
Thrown for any other shape, with pygame's message, which ends in a newline:
must be a valid 2d or 3d arrayfollowed 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
surfaceSurfaceThe surface.
Returns
- NDArray
A new array the caller owns (dispose it).
Exceptions
- ArgumentNullException
Thrown when
surfaceis null.