Class RenderResult
What render() returns, Gymnasium's RenderFrame | list[RenderFrame] | None as a closed union: nothing
(None, human mode and envs without a render mode), one RGB frame (RenderResult.Rgb,
rgb_array), one depth frame (RenderResult.Depth, depth_array), an RGB-D pair (RenderResult.RgbDepth,
rgbd_tuple), text (RenderResult.Ansi, ansi), or the frames collected since the last call
(RenderResult.Frames, the *_list modes). Switch on the case: if (env.Render() is RenderResult.Rgb rgb).
public abstract class RenderResult : IEquatable<RenderResult>, IDisposable
- Inheritance
-
RenderResult
- Implements
- Derived
- Inherited Members
- Extension Methods
Remarks
A frame array is handed over to the caller, who owns it: envs return a fresh array per call (Gymnasium's
np.transpose(np.array(...)) copies), so disposing it never affects the env.
Equality is structural: the same case with equal contents, arrays compared by shape, dtype and elements (never
with NDArray's broadcasting ==). Python has no such union, the distinction between an RGB and
a depth frame (both ndarray) is the render mode's; it is kept here so consumers need not look it up.
A single frame converts explicitly (DR-77, DR-84): (NDArray)env.Render() is the RenderResult.Rgb or
RenderResult.Depth frame itself, still owned by the result, and (Image)env.Render() a new ImageSharp image
of an RenderResult.Rgb frame that the caller disposes. Every other case refuses with
InvalidCastException, since it holds no single frame.
Properties
IsNone
Whether this is None, what render() returns in human mode or without a render mode.
public bool IsNone { get; }
Property Value
None
The single RenderResult.NoneResult value: Python's None from render().
public static RenderResult None { get; }
Property Value
Methods
Dispose()
Releases the frame arrays this result carries (D19): using var frame = env.Render();. A frame is the
caller's from render() on, so disposing it never affects the env; None and
RenderResult.Ansi hold no arrays, and disposing them does nothing.
public virtual void Dispose()
Equals(RenderResult?)
Structural equality (see the class remarks).
public abstract bool Equals(RenderResult? other)
Parameters
otherRenderResultThe other result; may be null.
Returns
Equals(object?)
Structural equality with any object (see the class remarks).
public override bool Equals(object? obj)
Parameters
objobjectThe other object.
Returns
- bool
true when it is an equal RenderResult.
GetHashCode()
A hash consistent with Equals(RenderResult?): the case and the shapes, never the pixels.
public override abstract int GetHashCode()
Returns
- int
The hash.
Operators
explicit operator NDArray(RenderResult)
The single frame of an RenderResult.Rgb or RenderResult.Depth result: NDArray frame = (NDArray)env.Render();
in rgb_array or depth_array mode.
public static explicit operator NDArray(RenderResult result)
Parameters
resultRenderResultThe result.
Returns
- NDArray
The result's own frame, not a copy: disposing the result disposes it, so keep the result alive (or undisposed) while the frame is used, and dispose one of the two, not both.
Exceptions
- ArgumentNullException
Thrown when
resultis null.- InvalidCastException
Thrown for a result without a single frame: None (
humanmode, or no render mode), RenderResult.Ansi text, an RenderResult.RgbDepth pair (read RgbFrame or DepthFrame), or the RenderResult.Frames of a*_listmode.
explicit operator Image(RenderResult)
An ImageSharp image of an RenderResult.Rgb frame: using Image image = (Image)env.Render(); in
rgb_array mode, an Image<Rgb24> of the frame's size (a frame of another dtype is cast to uint8).
public static explicit operator Image(RenderResult result)
Parameters
resultRenderResultThe result.
Returns
- Image
A new image the caller owns and disposes; the result keeps its frame.
Exceptions
- ArgumentNullException
Thrown when
resultis null.- InvalidCastException
Thrown for any case but RenderResult.Rgb: a depth frame has no colors to show, and None, RenderResult.Ansi, RenderResult.RgbDepth and RenderResult.Frames hold no single RGB frame.
- ArgumentException
Thrown when the RenderResult.Rgb frame is not
(H, W),(H, W, 3)or(H, W, 4).