Table of Contents

Class Draw

Namespace
Gym.Rendering
Assembly
Gym.Rendering.dll
public static class Draw
Inheritance
Draw
Inherited Members

Remarks

line, Rect(Surface, Color, long, long, long, long, int), Polygon(Surface, Color, IReadOnlyList<(double X, double Y)>, int), Circle(Surface, Color, double, double, double, int) and Lines(Surface, Color, bool, IReadOnlyList<(double X, double Y)>, int) are Gym.NET's own implementations of pygame's behaviour (decision D4: derived from live pygame-ce 2.5.8's output, none of its source read), pixel-exact on thousands of random shapes each, clipping included. Float coordinates convert as pygame's C code converts them (PyInt(double)).

Aaline(Surface, Color, double, double, double, double) and Aalines(Surface, Color, bool, IReadOnlyList<(double X, double Y)>) are the exception (decision DR-37): D4's black-box model of them did not converge where segments join, so they are translated from pygame-ce 2.5.8's src_c/draw.c, statement for statement in float32, and MountainCar's frames match pygame's pixel for pixel. That translation lives in its own file, Draw.Aaline.cs, which carries its source's notice (THIRD-PARTY-NOTICES.md); the package is Apache-2.0, as every Gym.NET package is (DR-49).

The colour is written as the surface maps it: its alpha is dropped on a surface without per-pixel alpha (no blending, as pygame's draw functions on such a surface), except where anti-aliasing weights a pixel.

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

Methods

Aaline(Surface, Color, double, double, double, double)

pygame.draw.aaline(surface, color, start_pos, end_pos): an anti-aliased line between float endpoints, each pixel blended with the colour by the line's coverage of it, pixel for pixel as pygame-ce 2.5.8 draws it.

public static void Aaline(Surface surface, Color color, double x0, double y0, double x1, double y1)

Parameters

surface Surface

The surface, without per-pixel alpha.

color Color

The colour; its alpha is dropped, as the surface maps it (coverage alone weights the blend).

x0 double

The start column; pixel centres are at whole coordinates.

y0 double

The start row.

x1 double

The end column.

y1 double

The end row.

Remarks

Translated from pygame-ce 2.5.8's draw_aaline (DR-37; its notice is in this file's header): the coordinates are float32, as pygame converts them, and every step is a float32 operation in pygame's order, which C# reproduces bit for bit (x64 single precision, no fused multiply-adds). Width 1 only, which is all Gymnasium draws. Reference: src_c/draw.c.

Exceptions

ArgumentNullException

Thrown when surface is null.

NotSupportedException

Thrown for a surface with per-pixel alpha (not modelled).

ValueError

Thrown for a coordinate that is NaN or infinite, which pygame's C code would cast to an integer with undefined results.

Aalines(Surface, Color, bool, IReadOnlyList<(double X, double Y)>)

pygame.draw.aalines(surface, color, closed, points): anti-aliased segments through the points, closed back to the first when closed, pixel for pixel as pygame-ce 2.5.8 draws them, its joint rules and quirks included.

public static void Aalines(Surface surface, Color color, bool closed, IReadOnlyList<(double X, double Y)> points)

Parameters

surface Surface

The surface, without per-pixel alpha.

color Color

The colour; its alpha is dropped, as the surface maps it.

closed bool

Whether a segment joins the last point back to the first.

points IReadOnlyList<(double X, double Y)>

At least 2 points, as (x, y) floats.

Remarks

Translated from pygame-ce 2.5.8's aalines (DR-37). A segment leaves out its endpoint columns where its end point is not a whole pixel, unless the segment before and this one differ in steepness, which draws an extra pixel there; an open polyline keeps its two outer endpoints. pygame's quirks are kept as they are: the first segment's steepness test compares the third point with the first point's y (pts[1], not pts[3]) and uses > where the others use !=; the last segment's first endpoint follows its end point's wholeness; and with two points the one segment is drawn twice (as the first and as the last segment).

Footgun, with two points only: pygame keeps the x's and then the y's in one buffer, and its first test reads xlist[2] and ylist[2] whatever the length, so with two points it compares the first point's y with the float just past its buffer, memory it does not own. For a steep segment whose end point is not a whole pixel, that float decides whether the end column is blended once more, so pygame's own drawing of such a polyline changes from run to run. Gym.NET lays its buffer out the same way with one float more, 0: the null link pymalloc writes into the free block after one it carves, which is what a fresh interpreter usually finds there (6 short fresh runs out of 6 drew as Gym.NET does; a longer one differed at its 12th polyline, and a long-running interpreter differed on up to 4 of 11 such polylines per run). The parity suite accepts either of pygame's two outcomes for them and holds every other polyline to its pixels.

Reference: src_c/draw.c.

Exceptions

ArgumentNullException

Thrown when surface or points is null.

ValueError

Thrown for fewer than 2 points, with pygame's message, or a NaN or infinite coordinate.

NotSupportedException

Thrown for a surface with per-pixel alpha (not modelled).

Circle(Surface, Color, double, double, double, int)

pygame.draw.circle(surface, color, center, radius), filled (width 0): the pixels of a circle of the truncated radius centred on the corner (cx - 0.5, cy - 0.5) of the truncated centre's pixel, clipped.

public static void Circle(Surface surface, Color color, double centerX, double centerY, double radius, int width = 0)

Parameters

surface Surface

The surface, without per-pixel alpha.

color Color

The colour; its alpha is ignored.

centerX double

The centre's x (converted as pygame converts it, PyInt(double)).

centerY double

The centre's y, likewise.

radius double

The radius, likewise; below 1 nothing is drawn.

width int

0 fills; a negative width draws nothing; a ring (positive width) is not modelled.

Remarks

Gym.NET's own implementation of pygame-ce 2.5.8's observable behaviour (D4), exact on every radius from 0 to 300 and on 3,000 random circles across and beyond the surface's edges. The disc is a midpoint walk over one octant (x from 0 and y from the radius, a decision term starting at 1 - r); each step's (x, y) fills four spans, rows cy + y - 1 and cy - y over columns cx - x .. cx + x - 1, and rows cy + x - 1 and cy - x over columns cx - y .. cx + y - 1, so a radius-r disc is 2r pixels across. Fractions of the centre and radius are dropped (2.9 draws a radius-2 disc), and a NaN or huge value becomes int.MinValue, which draws nothing visible, as in pygame.

Exceptions

ArgumentNullException

Thrown when surface is null.

NotSupportedException

Thrown for a surface with per-pixel alpha, or a positive width (no Gymnasium env draws a ring).

Line(Surface, Color, double, double, double, double)

pygame.draw.line(surface, color, start_pos, end_pos) with float endpoints (as Acrobot and the box2d envs pass them): each coordinate converted as pygame's C code converts it (PyInt(double): truncated toward zero), then drawn as Line(Surface, Color, long, long, long, long) draws it.

public static void Line(Surface surface, Color color, double x0, double y0, double x1, double y1)

Parameters

surface Surface

The surface, without per-pixel alpha.

color Color

The colour; its alpha is ignored.

x0 double

The start column.

y0 double

The start row.

x1 double

The end column.

y1 double

The end row.

Remarks

A NaN, infinite or out-of-range coordinate becomes int.MinValue, as in pygame, which then draws the visible part of a line to a point two billion pixels away (measured: line((nan, 3), (10, 10)) lights row 10 from column 0 to 10). Only the surface's steps are walked, so such a line costs no more than any other.

Exceptions

ArgumentNullException

Thrown when surface is null.

NotSupportedException

Thrown for a surface with per-pixel alpha (not modelled).

Line(Surface, Color, long, long, long, long)

pygame.draw.line(surface, color, start_pos, end_pos) with integer endpoints and width 1: every pixel of the line from (x0, y0) to (x1, y1), both ends included, clipped to the surface.

public static void Line(Surface surface, Color color, long x0, long y0, long x1, long y1)

Parameters

surface Surface

The surface, without per-pixel alpha.

color Color

The colour; its alpha is ignored.

x0 long

The start column.

y0 long

The start row.

x1 long

The end column.

y1 long

The end row.

Remarks

The line steps along its longer axis from the start; an error term starting at half the longer extent steps the other axis when it drops below zero. Ties therefore fall toward the start, so a line and its reverse can differ by a pixel, as pygame's do ((0, 0)-(4, 2) lights (1, 0), (4, 2)-(0, 0) lights (1, 1)). Off-surface pixels are dropped without moving the others (exact on 5,000 random lines, endpoints to ±5,000).

Exceptions

ArgumentNullException

Thrown when surface is null.

NotSupportedException

Thrown for a surface with per-pixel alpha (not modelled).

Lines(Surface, Color, bool, IReadOnlyList<(double X, double Y)>, int)

pygame.draw.lines(surface, color, closed, points, width) at width 1 or 2: draw.line between each pair of consecutive points, and from the last point back to the first when closed and there are more than two points; at width 2 each segment also gets a copy one pixel over (CarRacing's skid marks).

public static void Lines(Surface surface, Color color, bool closed, IReadOnlyList<(double X, double Y)> points, int width = 1)

Parameters

surface Surface

The surface, without per-pixel alpha.

color Color

The colour; its alpha is ignored.

closed bool

Whether the last point joins the first (ignored for two points, as in pygame).

points IReadOnlyList<(double X, double Y)>

The points, as floats (converted as pygame converts them, PyInt(double)).

width int

1 or 2 draws; below 1 draws nothing; above 2 is not modelled yet.

Remarks

Gym.NET's own implementation of pygame-ce 2.5.8's observable behaviour (D4): pygame's polyline at width 1 is the union of its segments' draw.lines (exact on 600 random open polylines and 600 closed polygon outlines), and a closed polyline of two points draws its one segment only (a line and its reverse can differ by a pixel, so drawing the return segment would show). Each segment is the line Line(Surface, Color, long, long, long, long) draws, stepped only across the surface, so a far-off endpoint (a NaN becomes int.MinValue) costs nothing. At width 2 a segment is its width-1 line plus the same line moved one pixel right when it is steep (|dx| <= |dy| of the truncated ends) or one pixel down otherwise: exact on 3,000 random segments, 600 open polylines of float points, 600 closed ones, 600 closed two-point ones and 600 width-2 polygon outlines.

Exceptions

ArgumentNullException

Thrown when surface or points is null.

NotSupportedException

Thrown for a surface with per-pixel alpha, or a width above 2.

ValueError

Thrown for fewer than 2 points, with pygame's message, whatever the width.

Polygon(Surface, Color, IReadOnlyList<(double X, double Y)>, int)

pygame.draw.polygon(surface, color, points, width): filled when width is 0, otherwise the closed outline Lines(Surface, Color, bool, IReadOnlyList<(double X, double Y)>, int) draws (nothing for a negative width), clipped to the surface.

public static void Polygon(Surface surface, Color color, IReadOnlyList<(double X, double Y)> points, int width = 0)

Parameters

surface Surface

The surface, without per-pixel alpha.

color Color

The colour; its alpha is ignored.

points IReadOnlyList<(double X, double Y)>

The vertices, as floats (each converted as pygame converts it, PyInt(double)).

width int

0 fills; a positive width outlines (1 and 2 are modelled, see Lines(Surface, Color, bool, IReadOnlyList<(double X, double Y)>, int)); a negative width draws nothing.

Remarks

Gym.NET's own implementation of pygame-ce 2.5.8's observable behaviour (decision D4: derived from live pygame's output, none of its source read), exact on 7,500 random polygons of 4 to 8 vertices and 20,000 random triangles, clipped, flat, self-intersecting and far off the surface included, and on 3,000 more with coordinates to ±3e6.

Every vertex is first truncated toward zero, so a polygon's fractions only matter through that. Polygons of 4 or more vertices fill by scanline: on each row between the lowest and highest vertex rows, each non-horizontal edge whose rows include it (its lower end excluded, except on the last row) crosses at its upper end's x plus (row - upper y) * dx / dy, the product in wrapping 32-bit integers and the division in float32. The crossings are rounded alternately down and up in the order the edges are met (edge i - 1 → i for i from 0), so which side rounds which way depends on the starting vertex, then sorted and filled pairwise; horizontal edges strictly between the top and bottom rows are drawn on their own, and a polygon one row high is the span between its outermost vertices.

Three-point polygons take another path: the vertices sorted by row (stable), each row from the top vertex's to the bottom vertex's filled between the long edge and the short edge above or below the middle vertex, each end at its edge's start plus the truncated float32 product of the row offset and the edge's float32 slope (dx / (dy + 1e-17) in double first, so a flat edge's slope stays finite). Float32 slopes put some ends one pixel short of the exact intersection (a slope of 60/58 times 58 lands below 60). A flat triangle whose first two sorted points coincide spans to its third.

Footgun, as in pygame: the rounding makes adjacent polygons that share an edge overlap or leave a gap on some rows, and the same polygon listed from another vertex can fill differently by a pixel.

Exceptions

ArgumentNullException

Thrown when surface or points is null.

NotSupportedException

Thrown for a surface with per-pixel alpha, or an outline wider than 1 (not modelled).

ValueError

Thrown, with pygame's messages, for fewer than 3 points when filling (points argument must contain more than 2 points), or fewer than 2 when outlining or not drawing (Lines(Surface, Color, bool, IReadOnlyList<(double X, double Y)>, int)'s check runs first there).

Rect(Surface, Color, long, long, long, long, int)

pygame.draw.rect(surface, color, (x, y, width, height), line_width): filled when lineWidth is 0, a one-pixel outline when it is 1, nothing when it is negative.

public static void Rect(Surface surface, Color color, long x, long y, long width, long height, int lineWidth = 0)

Parameters

surface Surface

The surface, without per-pixel alpha.

color Color

The colour; its alpha is ignored.

x long

The left column.

y long

The top row.

width long

The width; nothing is drawn unless it is positive.

height long

The height; nothing is drawn unless it is positive.

lineWidth int

0 fills, 1 outlines, a negative value draws nothing.

Remarks

An outline clipped by the surface edge keeps its edges where they are (an edge off the surface is simply not drawn), except that a rectangle whose visible part is at most 2 pixels wide or tall is filled, visible part only: pygame's outline of such a sliver covers it completely. Measured exact on 8,000 random rectangles.

Exceptions

ArgumentNullException

Thrown when surface is null.

NotSupportedException

Thrown for a surface with per-pixel alpha, or a line width above 1 (not modelled).