Sprite Class

Inheritance diagram of Sprite

class Sprite(img, x=0, y=0, blend_src=770, blend_dest=771, batch=None, group=None, usage='dynamic', subpixel=False)

Instance of an on-screen image.

See the module documentation for usage.

Constructor:

__init__(img, x=0, y=0, blend_src=770, blend_dest=771, batch=None, group=None, usage='dynamic', subpixel=False)

Create a sprite.

Parameters:
  • img (AbstractImage or Animation) – Image or animation to display.
  • x (int) – X coordinate of the sprite.
  • y (int) – Y 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.
  • batch (Batch) – Optional batch to add the sprite to.
  • group (Group) – Optional parent group of the sprite.
  • usage (str) – Vertex buffer object usage hint, one of "none", "stream", "dynamic" (default) or "static". Applies only to vertex data.
  • subpixel (bool) – Allow floating-point coordinates for the sprite. By default, coordinates are restricted to integer values.

Methods:

delete() Force immediate removal of the sprite from video memory.
dispatch_event(event_type, *args) Dispatch a single event to the attached handlers.
draw() Draw the sprite at its current position.
event(*args) Function decorator for an event handler.
pop_handlers() Pop the top level of event handlers off the stack.
push_handlers(*args, **kwargs) Push a level onto the top of the handler stack, then attach zero or more event handlers.
register_event_type(name) Register an event type with the dispatcher.
remove_handler(name, handler) Remove a single event handler.
remove_handlers(*args, **kwargs) Remove event handlers from the event stack.
set_handler(name, handler) Attach a single event handler.
set_handlers(*args, **kwargs) Attach one or more event handlers to the top level of the handler stack.
set_position(x, y) Set the X and Y coordinates of the sprite simultaneously.

Events:

on_animation_end() The sprite animation reached the final frame.

Attributes:

batch Graphics batch.
color Blend color.
event_types Type: list
group Parent graphics group.
height Scaled height of the sprite.
image Image or animation to display.
opacity Blend opacity.
position The (x, y) coordinates of the sprite.
rotation Clockwise rotation of the sprite, in degrees.
scale Scaling factor.
visible
width Scaled width of the sprite.
x X coordinate of the sprite.
y Y coordinate of the sprite.

Methods

Sprite.delete()

Force immediate removal of the sprite from video memory.

This is often necessary when using batches, as the Python garbage collector will not necessarily call the finalizer as soon as the sprite is garbage.

Sprite.draw()

Draw the sprite at its current position.

See the module documentation for hints on drawing multiple sprites efficiently.

Sprite.set_position(x, y)

Set the X and Y coordinates of the sprite simultaneously.

Parameters:
  • x (int) – X coordinate of the sprite.
  • y (int) – Y coordinate of the sprite.

Events

Sprite.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

Sprite.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.

Type:Batch
Sprite.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).

Type:(int, int, int)
Sprite.event_types = ['on_animation_end']
Sprite.group

Parent graphics group.

The sprite can change its rendering group, however this can be an expensive operation.

Type:Group
Sprite.height

Scaled height of the sprite.

Read-only. Invariant under rotation.

Type:int
Sprite.image

Image or animation to display.

Type:AbstractImage or Animation
Sprite.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.

Type:int
Sprite.position

The (x, y) coordinates of the sprite.

Type:(int, int)
Sprite.rotation

Clockwise rotation of the sprite, in degrees.

The sprite image will be rotated about its image’s (anchor_x, anchor_y) position.

Type:float
Sprite.scale

Scaling factor.

A scaling factor of 1 (the default) has no effect. A scale of 2 will draw the sprite at twice the native size of its image.

Type:float
Sprite.visible
Sprite.width

Scaled width of the sprite.

Read-only. Invariant under rotation.

Type:int
Sprite.x

X coordinate of the sprite.

Type:int
Sprite.y

Y coordinate of the sprite.

Type:int

Inherited members

Methods

Sprite.dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters:
  • event_type (str) – Name of the event.
  • args (sequence) – Arguments to pass to the event handler.
Return type:

bool or None

Returns:

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earler, the return value is always None.

Sprite.event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
Sprite.pop_handlers()

Pop the top level of event handlers off the stack.

Sprite.push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

classmethod Sprite.register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters:name (str) – Name of the event to register.
Sprite.remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers; and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters:
  • name (str) – Name of the event type to remove.
  • handler (callable) – Event handler to remove.
Sprite.remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers and pop_handlers.

Sprite.set_handler(name, handler)

Attach a single event handler.

Parameters:
  • name (str) – Name of the event type to attach to.
  • handler (callable) – Event handler to attach.
Sprite.set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers for the accepted argument types.

Table Of Contents

Previous topic

SpriteGroup Class

Next topic

SpriteGroup Class