Class Draw
The pygame.draw functions Gymnasium's envs call: line (Acrobot, BipedalWalker's lidar), Rect(Surface, Color, long, long, long, long, int)
(FrozenLake), Aalines(Surface, Color, bool, IReadOnlyList<(double X, double Y)>) and Aaline(Surface, Color, double, double, double, double) (MountainCar's hill, LunarLander, BipedalWalker), and
for the box2d envs 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), on surfaces without per-pixel
alpha.
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
surfaceSurfaceThe surface, without per-pixel alpha.
colorColorThe colour; its alpha is dropped, as the surface maps it (coverage alone weights the blend).
x0doubleThe start column; pixel centres are at whole coordinates.
y0doubleThe start row.
x1doubleThe end column.
y1doubleThe 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
surfaceis 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
surfaceSurfaceThe surface, without per-pixel alpha.
colorColorThe colour; its alpha is dropped, as the surface maps it.
closedboolWhether a segment joins the last point back to the first.
pointsIReadOnlyList<(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
surfaceorpointsis 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
surfaceSurfaceThe surface, without per-pixel alpha.
colorColorThe colour; its alpha is ignored.
centerXdoubleThe centre's x (converted as pygame converts it, PyInt(double)).
centerYdoubleThe centre's y, likewise.
radiusdoubleThe radius, likewise; below 1 nothing is drawn.
widthint0 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
surfaceis 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
surfaceSurfaceThe surface, without per-pixel alpha.
colorColorThe colour; its alpha is ignored.
x0doubleThe start column.
y0doubleThe start row.
x1doubleThe end column.
y1doubleThe 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
surfaceis 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
surfaceSurfaceThe surface, without per-pixel alpha.
colorColorThe colour; its alpha is ignored.
x0longThe start column.
y0longThe start row.
x1longThe end column.
y1longThe 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
surfaceis 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
surfaceSurfaceThe surface, without per-pixel alpha.
colorColorThe colour; its alpha is ignored.
closedboolWhether the last point joins the first (ignored for two points, as in pygame).
pointsIReadOnlyList<(double X, double Y)>The points, as floats (converted as pygame converts them, PyInt(double)).
widthint1 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
surfaceorpointsis 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
surfaceSurfaceThe surface, without per-pixel alpha.
colorColorThe colour; its alpha is ignored.
pointsIReadOnlyList<(double X, double Y)>The vertices, as floats (each converted as pygame converts it, PyInt(double)).
widthint0 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
surfaceorpointsis 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
surfaceSurfaceThe surface, without per-pixel alpha.
colorColorThe colour; its alpha is ignored.
xlongThe left column.
ylongThe top row.
widthlongThe width; nothing is drawn unless it is positive.
heightlongThe height; nothing is drawn unless it is positive.
lineWidthint0 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
surfaceis null.- NotSupportedException
Thrown for a surface with per-pixel alpha, or a line width above 1 (not modelled).