pyglet.shapes
2D shapes.
This module provides classes for a variety of simplistic 2D shapes,
such as Rectangles, Circles, and Lines. These shapes are made
internally from OpenGL primitives, and provide excellent performance
when drawn as part of a Batch
.
Convenience methods are provided for positioning, changing color, opacity,
and rotation.
The Python in
operator can be used to check whether a point is inside a shape.
(This is approximated with some shapes, such as Star).
If the shapes in this module don’t suit your needs, you have two options:
Your Goals |
Best Approach |
---|---|
Simple shapes like those here |
Subclass |
Complex & optimized shapes |
See Shaders and Rendering to learn about the low-level graphics API. |
A simple example of drawing shapes:
import pyglet
from pyglet import shapes
window = pyglet.window.Window(960, 540)
batch = pyglet.graphics.Batch()
circle = shapes.Circle(700, 150, 100, color=(50, 225, 30), batch=batch)
square = shapes.Rectangle(200, 200, 200, 200, color=(55, 55, 255), batch=batch)
rectangle = shapes.Rectangle(250, 300, 400, 200, color=(255, 22, 20), batch=batch)
rectangle.opacity = 128
rectangle.rotation = 33
line = shapes.Line(100, 100, 100, 200, width=19, batch=batch)
line2 = shapes.Line(150, 150, 444, 111, width=4, color=(200, 20, 20), batch=batch)
star = shapes.Star(800, 400, 60, 40, num_spikes=20, color=(255, 255, 0), batch=batch)
@window.event
def on_draw():
window.clear()
batch.draw()
pyglet.app.run()
Note
Some Shapes, such as Line
and Triangle
,
have multiple coordinates.
These shapes treat their position
as their
primary coordinate. Changing it or its components (the
x
or y
properties)
also moves all secondary coordinates by the same offset from
the previous position
value. This allows
you to move these shapes without distorting them.
New in version 1.5.4.
- class ShapeBase
Base class for all shape objects.
A number of default shapes are provided in this module. Curves are approximated using multiple vertices.
If you need shapes or functionality not provided in this module, you can write your own custom subclass of
ShapeBase
by using the provided shapes as reference.Methods
- draw() None
Debug method to draw a single shape at its current position. :rtype:
None
Warning
Avoid this inefficient method for everyday use!
Regular drawing should add shapes to a
Batch
and call itsdraw()
method.
- delete() None
Force immediate removal of the shape from video memory.
You should usually call this whenever you delete a shape. Unless you are using manual garbage collection, Python might not call the finalizer as soon as the sprite falls out of scope.
Manual garbage collection is a very advanced technique. See Python’s
gc
module documentation to learn more.- Return type:
Attributes
- y
Get/set the Y coordinate of the shape’s
position
.This property has the following pitfalls:
See
position
to learn more.
- position
Get/set the
(x, y)
coordinates of the shape.All shapes default to rotating around their position. However, the way they do so varies.
Shapes with a
radius
property will use this as their center:Others default to using it as their lower left corner.
- rotation
Get/set the shape’s clockwise rotation in degrees.
All shapes rotate around their
anchor_position
. For most shapes, this defaults to both:The shape’s first vertex of the shape
The lower left corner
Shapes with a
radius
property rotate around the point the radius is measured from. This will be either their center or the center of the circle they’re cut from:These shapes rotate around their center:
These shapes rotate around the point of their angles:
- anchor_x
Get/set the X coordinate of the anchor point.
If you need to set both this and
anchor_x
, useanchor_position
instead.
- anchor_y
Get/set the Y coordinate of the anchor point.
If you need to set both this and
anchor_x
, useanchor_position
instead.
- anchor_position
Get/set the anchor’s
(x, y)
offset fromposition
This defines the point a shape rotates around. By default, it is
(0.0, 0.0)
. However:Its behavior may vary between shape classes.
On many shapes, you can set the anchor or its components (
anchor_x
andanchor_y
) to custom values.
Since all anchor updates recalculate a shape’s vertices on the CPU, this property is faster than updating
anchor_x
andanchor_y
separately.
- color
Get/set the shape’s color.
The color may set to:
An RGBA tuple of integers
(red, green, blue, alpha)
An RGB tuple of integers
(red, green, blue)
If an RGB color is set, the current alpha will be preserved. Otherwise, the new alpha value will be used for the shape. Each color component must be in the range 0 (dark) to 255 (saturated).
- opacity
Get/set the blend opacity of the shape.
Tip
To toggle visibility on/off,
visible
may be more efficient!Opacity is implemented as the alpha component of a shape’s
color
. When part of a group with a default blend mode of(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA)
, opacities below255
draw with fractional opacity over the background: Opacity
Effect
255
(Default)Shape is fully opaque
128
Shape looks translucent
0
Invisible
- visible
Get/set whether the shape will be drawn at all.
For absolute showing / hiding, this is
- group
Get/set the shape’s
Group
.You can migrate a shape from one group to another by setting this property. Note that it can be an expensive (slow) operation.
If
batch
isn’tNone
, setting this property will also trigger a batch migration.
- batch
Get/set the
Batch
for this shape.You can migrate a shape from one batch to another by setting this property, but it can be an expensive (slow) operation.
- __init__()
- __new__(**kwargs)
- class Arc
Bases:
ShapeBase
- angle
Get/set the angle of the arc in radians.
- start_angle
Get/set the start angle of the arc in radians.
- thickness
- __init__(
- x: float,
- y: float,
- radius: float,
- segments: int | None = None,
- angle: float = 6.283185307179586,
- start_angle: float = 0.0,
- closed: bool = False,
- thickness: float = 1.0,
- color=(255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create an Arc.
The Arc’s anchor point (x, y) defaults to its center.
- Parameters:
x (
float
) – X coordinate of the circle.y (
float
) – Y coordinate of the circle.radius (
float
) – The desired radius.segments (
int
|None
) – You can optionally specify how many distinct line segments the arc should be made from. If not specified it will be automatically calculated using the formula:max(14, int(radius / 1.25))
.angle (
float
) – The angle of the arc, in radians. Defaults to tau (pi * 2), which is a full circle.start_angle (
float
) – The start angle of the arc, in radians. Defaults to 0.closed (
bool
) – IfTrue
, the ends of the arc will be connected with a line. defaults toFalse
.thickness (
float
) – The desired thickness or width of the line used for the arc.color – The RGB or RGBA color of the arc, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having opacity of 255.
- __new__(**kwargs)
- class BezierCurve
Bases:
ShapeBase
- points
Get/set the control points of the Bézier curve.
- t
Get/set the t in
100*t
percent of the curve to draw.
- thickness
Get/set the line thickness for the Bézier curve.
- __init__(
- *points: tuple[float, float],
- t: float = 1.0,
- segments: int = 100,
- thickness: int = 1.0,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create a Bézier curve.
The curve’s anchor point (x, y) defaults to its first control point.
- Parameters:
points (
tuple
[float
,float
]) – Control points of the curve. Points can be specified as multiple lists or tuples of point pairs. Ex. (0,0), (2,3), (1,9)t (
float
) – Draw 100*t percent of the curve. 0.5 means the curve is half drawn and 1.0 means draw the whole curve.segments (
int
) – You can optionally specify how many line segments the curve should be made from.thickness (
int
) – The desired thickness or width of the line used for the curve.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the curve, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
- __new__(**kwargs)
- class Circle
Bases:
ShapeBase
- radius
Gets/set radius of the circle.
- __init__(
- x: float,
- y: float,
- radius: float,
- segments: int | None = None,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create a circle.
The circle’s anchor point (x, y) defaults to the center of the circle.
- Parameters:
x (
float
) – X coordinate of the circle.y (
float
) – Y coordinate of the circle.radius (
float
) – The desired radius.segments (
int
|None
) – You can optionally specify how many distinct triangles the circle should be made from. If not specified it will be automatically calculated using the formula: max(14, int(radius / 1.25)).color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the circle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
- __new__(**kwargs)
- class Ellipse
Bases:
ShapeBase
- a
Get/set the semi-major axes of the ellipse.
- b
Get/set the semi-minor axes of the ellipse.
- __init__(
- x: float,
- y: float,
- a: float,
- b: float,
- segments: int | None = None,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create an ellipse.
The ellipse’s anchor point
(x, y)
defaults to the center of the ellipse.- Parameters:
x (
float
) – X coordinate of the ellipse.y (
float
) – Y coordinate of the ellipse.a (
float
) – Semi-major axes of the ellipse.b (
float
) – Semi-minor axes of the ellipse.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the ellipse, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
- __new__(**kwargs)
- class Sector
Bases:
ShapeBase
- angle
Get/set the angle of the sector in radians.
- start_angle
Get/set the start angle of the sector in radians.
- radius
Get/set the radius of the sector.
By default, this is in screen pixels. Your drawing / GL settings may alter how this is drawn.
- __init__(
- x: float,
- y: float,
- radius: float,
- segments: int | None = None,
- angle: float = 6.283185307179586,
- start_angle: float = 0.0,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create a Sector of a circle.
By default,
(x, y)
is used as: * The sector’s anchor point * The center of the circle the sector is cut from- Parameters:
x (
float
) – X coordinate of the sector.y (
float
) – Y coordinate of the sector.radius (
float
) – The desired radius.segments (
int
|None
) – You can optionally specify how many distinct triangles the sector should be made from. If not specified it will be automatically calculated using the formula: max(14, int(radius / 1.25)).angle (
float
) – The angle of the sector, in radians. Defaults to tau (pi * 2), which is a full circle.start_angle (
float
) – The start angle of the sector, in radians. Defaults to 0.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the circle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
- __new__(**kwargs)
- class Line
Bases:
ShapeBase
- x2
Get/set the 2nd X coordinate of the line.
- y2
Get/set the 2nd Y coordinate of the line.
- __init__(
- x: float,
- y: float,
- x2: float,
- y2: float,
- width: float = 1.0,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create a line.
The line’s anchor point defaults to the center of the line’s width on the X axis, and the Y axis.
- Parameters:
x (
float
) – The first X coordinate of the line.y (
float
) – The first Y coordinate of the line.x2 (
float
) – The second X coordinate of the line.y2 (
float
) – The second Y coordinate of the line.width (
float
) – The desired width of the line.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the line, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
- __new__(**kwargs)
- class Rectangle
Bases:
ShapeBase
- width
Get/set width of the rectangle.
The new left and right of the rectangle will be set relative to its
anchor_x
value.
- height
Get/set the height of the rectangle.
The bottom and top of the rectangle will be positioned relative to its
anchor_y
value.
- __init__(
- x: float,
- y: float,
- width: float,
- height: float,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create a rectangle or square.
The rectangle’s anchor point defaults to the
(x, y)
coordinates, which are at the bottom left.- Parameters:
x (
float
) – The X coordinate of the rectangle.y (
float
) – The Y coordinate of the rectangle.width (
float
) – The width of the rectangle.height (
float
) – The height of the rectangle.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the circle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.batch (
Batch
|None
) – Optional batch to add the rectangle to.group (
Group
|None
) – Optional parent group of the rectangle.
- __new__(**kwargs)
- class Box
Bases:
ShapeBase
- width
Get/set the width of the box.
Setting the width will position the left and right sides relative to the box’s
anchor_x
value.
- height
Get/set the height of the Box.
Setting the height will set the bottom and top relative to the box’s
anchor_y
value.
- __init__(
- x: float,
- y: float,
- width: float,
- height: float,
- thickness: float = 1.0,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create an unfilled rectangular shape, with optional thickness.
The box’s anchor point defaults to the
(x, y)
coordinates, which are placed at the bottom left. Changing the thickness of the box will extend the walls inward; the outward dimesions will not be affected.- Parameters:
x (
float
) – The X coordinate of the box.y (
float
) – The Y coordinate of the box.width (
float
) – The width of the box.height (
float
) – The height of the box.thickness (
float
) – The thickness of the lines that make up the box.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the box, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
- __new__(**kwargs)
- class BorderedRectangle
Bases:
ShapeBase
- width
Get/set width of the bordered rectangle.
The new left and right of the rectangle will be set relative to its
anchor_x
value.
- height
Get/set the height of the bordered rectangle.
The bottom and top of the rectangle will be positioned relative to its
anchor_y
value.
- border_color
Get/set the bordered rectangle’s border color.
To set the color of the interior fill, see
color
.You can set the border color to either of the following:
An RGBA tuple of integers
(red, green, blue, alpha)
An RGB tuple of integers
(red, green, blue)
Setting the alpha on this property will change the alpha of the entire shape, including both the fill and the border.
Each color component must be in the range 0 (dark) to 255 (saturated).
- __init__(
- x: float,
- y: float,
- width: float,
- height: float,
- border: float = 1.0,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255),
- border_color: tuple[int, int, int, int] | tuple[int, int, int] = (100, 100, 100),
- batch: Batch | None = None,
- group: Group | None = None,
Create a bordered rectangle.
The rectangle’s anchor point defaults to the
(x, y)
coordinates, which are at the bottom left.- Parameters:
x (
float
) – The X coordinate of the rectangle.y (
float
) – The Y coordinate of the rectangle.width (
float
) – The width of the rectangle.height (
float
) – The height of the rectangle.border (
float
) – The thickness of the border.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA fill color of the rectangle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.border_color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) –The RGB or RGBA fill color of the border, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
The alpha values must match if you pass RGBA values to both this argument and border_color. If they do not, a ValueError will be raised informing you of the ambiguity.
batch (
Batch
|None
) – Optional batch to add the rectangle to.group (
Group
|None
) – Optional parent group of the rectangle.
- __new__(**kwargs)
- class Triangle
Bases:
ShapeBase
- x2
Get/set the X coordinate of the triangle’s 2nd vertex.
- y2
Get/set the Y coordinate of the triangle’s 2nd vertex.
- x3
Get/set the X coordinate of the triangle’s 3rd vertex.
- y3
Get/set the Y value of the triangle’s 3rd vertex.
- __init__(
- x: float,
- y: float,
- x2: float,
- y2: float,
- x3: float,
- y3: float,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create a triangle.
The triangle’s anchor point defaults to the first vertex point.
- Parameters:
x (
float
) – The first X coordinate of the triangle.y (
float
) – The first Y coordinate of the triangle.x2 (
float
) – The second X coordinate of the triangle.y2 (
float
) – The second Y coordinate of the triangle.x3 (
float
) – The third X coordinate of the triangle.y3 (
float
) – The third Y coordinate of the triangle.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the triangle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.batch (
Batch
|None
) – Optional batch to add the triangle to.group (
Group
|None
) – Optional parent group of the triangle.
- __new__(**kwargs)
- class Star
Bases:
ShapeBase
- outer_radius
Get/set outer radius of the star.
- inner_radius
Get/set the inner radius of the star.
- num_spikes
Number of spikes of the star.
- __init__(
- x: float,
- y: float,
- outer_radius: float,
- inner_radius: float,
- num_spikes: int,
- rotation: float = 0.0,
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group = None,
Create a star.
The star’s anchor point
(x, y)
defaults to the on-screen center of the star.- Parameters:
x (
float
) – The X coordinate of the star.y (
float
) – The Y coordinate of the star.outer_radius (
float
) – The desired outer radius of the star.inner_radius (
float
) – The desired inner radius of the star.num_spikes (
int
) – The desired number of spikes of the star.rotation (
float
) – The rotation of the star in degrees. A rotation of 0 degrees will result in one spike lining up with the X axis in positive direction.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the star, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.group (
Group
) – Optional parent group of the star.
- __new__(**kwargs)
- class Polygon
Bases:
ShapeBase
- __init__(
- *coordinates: tuple[float, float] | Sequence[float],
- color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create a convex polygon.
The polygon’s anchor point defaults to the first vertex point.
- Parameters:
coordinates (
tuple
[float
,float
] |Sequence
[float
]) – The coordinates for each point in the polygon. Each one must be able to unpack to a pair of float-like X and Y values.color (
tuple
[int
,int
,int
,int
] |tuple
[int
,int
,int
]) – The RGB or RGBA color of the polygon, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.batch (
Batch
|None
) – Optional batch to add the polygon to.group (
Group
|None
) – Optional parent group of the polygon.
- __new__(**kwargs)
- class MultiLine
Bases:
ShapeBase
- thickness
Get/set the line thickness of the multi-line.
- __init__(
- *coordinates: tuple[float, float] | Sequence[float],
- closed: bool = False,
- thickness: float = 1.0,
- color: tuple[int, int, int, int] = (255, 255, 255, 255),
- batch: Batch | None = None,
- group: Group | None = None,
Create multiple connected lines from a series of coordinates.
The shape’s anchor point defaults to the first vertex point.
- Parameters:
coordinates (
tuple
[float
,float
] |Sequence
[float
]) – The coordinates for each point in the shape. Each must unpack like a tuple consisting of an X and Y float-like value.closed (
bool
) – Set this toTrue
to add a line connecting the first and last points. The default isFalse
thickness (
float
) – The desired thickness or width used for the line segments.color (
tuple
[int
,int
,int
,int
]) – The RGB or RGBA color of the shape, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
- __new__(**kwargs)