pyglet.sprite
Display positioned, scaled and rotated images.
A sprite is an instance of an image displayed on-screen. Multiple sprites can display the same image at different positions on the screen. Sprites can also be scaled larger or smaller, rotated at any angle and drawn at a fractional opacity.
The following complete example loads a "ball.png" image and creates a
sprite for that image. The sprite is then drawn in the window’s
draw event handler:
import pyglet
ball_image = pyglet.image.load('ball.png')
ball = pyglet.sprite.Sprite(ball_image, x=50, y=50)
window = pyglet.window.Window()
@window.event
def on_draw():
ball.draw()
pyglet.app.run()
The sprite can be moved by modifying the x and
y properties. Other
properties determine the sprite’s rotation,
scale and
opacity.
By default, sprite coordinates are restricted to integer values to avoid
sub-pixel artifacts. If you require to use floats, for example for smoother
animations, you can set the subpixel parameter to True when creating
the sprite (:since: pyglet 1.2).
The sprite’s positioning, rotation and scaling all honor the original
image’s anchor (anchor_x,
anchor_y).
Drawing multiple sprites
Sprites can be “batched” together and drawn at once more quickly than if each
of their draw methods were called individually. The following example
creates one hundred ball sprites and adds each of them to a Batch. The
entire batch of sprites is then drawn in one call:
batch = pyglet.graphics.Batch()
ball_sprites = []
for i in range(100):
x, y = i * 10, 50
ball_sprites.append(pyglet.sprite.Sprite(ball_image, x, y, batch=batch))
@window.event
def on_draw():
batch.draw()
Sprites can be freely modified in any way even after being added to a batch,
however a sprite can belong to at most one batch. See the documentation for
pyglet.graphics for more details on batched rendering, and grouping of
sprites within batches.
New in version 1.1.
- class Sprite
Presend and manipulate an on-screen image.
See the module documentation for usage.
Methods
- delete() None
Force immediate removal of the sprite from video memory.
It is recommended to call this whenever you delete a sprite, as the Python garbage collector will not necessarily call the finalizer as soon as the sprite falls out of scope.
- Return type:
- draw() None
Draw the sprite at its current position.
See the module documentation for hints on drawing multiple sprites efficiently.
- Return type:
- update(
- x: float | None = None,
- y: float | None = None,
- z: float | None = None,
- rotation: float | None = None,
- scale: float | None = None,
- scale_x: float | None = None,
- scale_y: float | None = None,
Simultaneously change the position, rotation or scale.
This method is provided for convenience. There is not much performance benefit to updating multiple Sprite attributes at once.
Events
- on_animation_end()
The sprite animation reached the final frame.
The event is triggered only if the sprite has an animation, not an image. For looping animations, the event is triggered each time the animation loops.
Attributes
- batch
Graphics batch.
The sprite can be migrated from one batch to another, or removed from its batch (for individual drawing). Note that this can be an expensive operation.
- color
Blend color.
This property sets the color of the sprite’s vertices. This allows the sprite to be drawn with a color tint.
The color is specified as an RGB tuple of integers ‘(red, green, blue)’. Each color component must be in the range 0 (dark) to 255 (saturated).
- group
Parent graphics group.
The Sprite can change its rendering group, however this can be a relatively expensive operation.
- height
Scaled height of the sprite.
Invariant under rotation.
- image
The Sprite’s Image or Animation to display.
- opacity
Blend opacity.
This property sets the alpha component of the colour of the sprite’s vertices. With the default blend mode (see the constructor), this allows the sprite to be drawn with fractional opacity, blending with the background.
An opacity of 255 (the default) has no effect. An opacity of 128 will make the sprite appear translucent.
- position
The (x, y, z) coordinates of the sprite, as a tuple.
- rotation
Clockwise rotation of the sprite, in degrees.
The sprite image will be rotated about its image’s (anchor_x, anchor_y) position.
- scale
Base Scaling factor.
A scaling factor of 1.0 (the default) has no effect. A scale of 2.0 will draw the sprite at twice the native size of its image.
- scale_x
Horizontal scaling factor.
A scaling factor of 1.0 (the default) has no effect. A scale of 2.0 will draw the sprite at twice the native width of its image.
- scale_y
Vertical scaling factor.
A scaling factor of 1.0 (the default) has no effect. A scale of 2.0 will draw the sprite at twice the native height of its image.
- visible
True if the sprite will be drawn.
- width
Scaled width of the sprite.
Invariant under rotation.
- x
X coordinate of the sprite.
- y
Y coordinate of the sprite.
- __init__(
- img: AbstractImage | Animation,
- x: float = 0,
- y: float = 0,
- z: float = 0,
- blend_src: int = 770,
- blend_dest: int = 771,
- batch: Batch | None = None,
- group: Group | None = None,
- subpixel: bool = False,
Create a Sprite instance.
- Parameters:
img (
AbstractImage|Animation) – Image or Animation to display.x (
float) – X coordinate of the sprite.y (
float) – Y coordinate of the sprite.z (
float) – Z coordinate of the sprite.blend_src (
int) – OpenGL blend source mode. The default is suitable for compositing sprites drawn from back-to-front.blend_dest (
int) – OpenGL blend destination mode. The default is suitable for compositing sprites drawn from back-to-front.subpixel (
bool) – Allow floating-point coordinates for the sprite. By default, coordinates are restricted to integer values.
- __new__(**kwargs)
- class SpriteGroup
Shared Sprite rendering Group.
The Group defines custom
__eq__ane__hash__methods, and so will be automatically coalesced with other Sprite Groups sharing the same parent Group, Texture and blend parameters.- __init__(
- texture: Texture,
- blend_src: int,
- blend_dest: int,
- program: ShaderProgram,
- parent: Group | None = None,
Create a sprite group.
The group is created internally when a
Spriteis created; applications usually do not need to explicitly create it.- Parameters:
texture (
Texture) – The (top-level) texture containing the sprite image.blend_src (
int) – OpenGL blend source mode; for example,GL_SRC_ALPHA.blend_dest (
int) – OpenGL blend destination mode; for example,GL_ONE_MINUS_SRC_ALPHA.program (
ShaderProgram) – A custom ShaderProgram.