pyglet Documentation<a class="headerlink" href="#pyglet-documentation" title="Permalink to this heading">

schedule_interval_soft(

func: Callable,

interval: float,

*args: Any,

**kwargs: Any,

) → None

Schedule a function to be called approximately every interval seconds.

This method is similar to schedule_interval(), except that the clock will move the interval out of phase with other scheduled functions in order to distribute CPU load more evenly.

This is useful for functions that need to be called regularly, but not relative to the initial start time. pyglet.media does this for scheduling audio buffer updates, which need to occur regularly – if all audio updates are scheduled at the same time (for example, mixing several tracks of a music score, or playing multiple videos back simultaneously), the resulting load on the CPU is excessive for those intervals but idle outside. Using the soft interval scheduling, the load is more evenly distributed.

Soft interval scheduling can also be used as an easy way to schedule graphics animations out of phase; for example, multiple flags waving in the wind.

Return type:: None

schedule_once(

func: Callable,

delay: float,

*args: Any,

**kwargs: Any,

) → None

Schedule a function to be called once after delay seconds.

The callback function prototype is the same as for schedule().

Return type:: None

static sleep(microseconds: float) → None

Return type:: None

tick(poll: bool = False) → float

Signify that one frame has passed.

This will call any scheduled functions that have elapsed, and returns the number of seconds since the last time this method has been called. The first time this method is called, 0 is returned.

Parameters:: poll (bool) – If True, the function will call any scheduled functions but will not sleep or busy-wait for any reason. Recommended for advanced applications managing their own sleep timers only.
Return type:: float

unschedule(func: Callable) → None

Remove a function from the schedule.

If the function appears in the schedule more than once, all occurrences are removed. If the function was not scheduled, no error is raised.

Return type:: None

update_time() → float

Get the elapsed time since the last call to update_time.

This updates the clock’s internal measure of time and returns the difference (in seconds) since the last time it was called. The first call of this method always returns 0.

Return type:: float

get_default() → Clock

Get the pyglet default Clock.

Return the Clock instance that is used by all module-level clock functions.

Return type:: Clock

get_frequency() → float

See:: get_frequency().
Return type:: float

get_sleep_time(sleep_idle: bool) → float | None

See:: get_sleep_time().
Return type:: float | None

schedule(func: Callable, *args: Any, **kwargs: Any) → None

See:: schedule().
Return type:: None

schedule_interval(

func: Callable,

interval: float,

*args: Any,

**kwargs: Any,

) → None

See:: schedule_interval().
Return type:: None

schedule_interval_for_duration(

func: Callable,

interval: float,

duration: float,

*args,

**kwargs,

) → None

See:: schedule_interval_for_duration().
Return type:: None

schedule_interval_soft(

func: Callable,

interval: float,

*args,

**kwargs,

) → None

See:: schedule_interval_soft().
Return type:: None

schedule_once(func: Callable, delay: float, *args, **kwargs) → None

See:: schedule_once().
Return type:: None

set_default(default: Clock) → None

Set the default clock to use for all module-level functions.

By default, an instance of Clock is used.

Return type:: None

tick(poll: bool = False) → float

See:: tick().
Return type:: float

unschedule(func: Callable) → None

See:: unschedule().
Return type:: None

pyglet.customtypes

Holds type aliases used throughout the codebase.

Buffer: alias of Union[bytes, bytearray, memoryview, Array]

HorizontalAlign: alias of Literal[‘left’, ‘center’, ‘right’]

AnchorX: alias of Literal[‘left’, ‘center’, ‘right’]

AnchorY: alias of Literal[‘top’, ‘bottom’, ‘center’, ‘baseline’]

ContentVAlign: alias of Literal[‘left’, ‘center’, ‘top’]

pyglet.event

Event dispatch framework.

All objects that produce events in pyglet implement EventDispatcher, providing a consistent interface for registering and manipulating event handlers. A commonly used event dispatcher is pyglet.window.Window.

Event types

For each event dispatcher there is a set of events that it dispatches; these correspond with the type of event handlers you can attach. Event types are identified by their name, for example, ‘’on_resize’’. If you are creating a new class which implements EventDispatcher, you must call EventDispatcher.register_event_type for each event type.

Attaching event handlers

An event handler is simply a function or method. You can attach an event handler by setting the appropriate function on the instance:

def on_resize(width, height):
    # ...
dispatcher.on_resize = on_resize

There is also a convenience decorator that reduces typing:

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

You may prefer to subclass and override the event handlers instead:

class MyDispatcher(DispatcherClass):
    def on_resize(self, width, height):
        # ...

Event handler stack

When attaching an event handler to a dispatcher using the above methods, it replaces any existing handler (causing the original handler to no longer be called). Each dispatcher maintains a stack of event handlers, allowing you to insert an event handler “above” the existing one rather than replacing it.

There are two main use cases for “pushing” event handlers:

Temporarily intercepting the events coming from the dispatcher by pushing a custom set of handlers onto the dispatcher, then later “popping” them all off at once.
Creating “chains” of event handlers, where the event propagates from the top-most (most recently added) handler to the bottom, until a handler takes care of it.

Use EventDispatcher.push_handlers to create a new level in the stack and attach handlers to it. You can push several handlers at once:

dispatcher.push_handlers(on_resize, on_key_press)

If your function handlers have different names to the events they handle, use keyword arguments:

dispatcher.push_handlers(on_resize=my_resize, on_key_press=my_key_press)

After an event handler has processed an event, it is passed on to the next-lowest event handler, unless the handler returns EVENT_HANDLED, which prevents further propagation.

To remove all handlers on the top stack level, use EventDispatcher.pop_handlers.

Note that any handlers pushed onto the stack have precedence over the handlers set directly on the instance (for example, using the methods described in the previous section), regardless of when they were set. For example, handler foo is called before handler bar in the following example:

dispatcher.push_handlers(on_resize=foo)
dispatcher.on_resize = bar

Dispatching events

pyglet uses a single-threaded model for all application code. Event handlers are only ever invoked as a result of calling EventDispatcher.dispatch_events`.

It is up to the specific event dispatcher to queue relevant events until they can be dispatched, at which point the handlers are called in the order the events were originally generated.

This implies that your application runs with a main loop that continuously updates the application state and checks for new events:

while True:
    dispatcher.dispatch_events()
    # ... additional per-frame processing

Not all event dispatchers require the call to dispatch_events; check with the particular class documentation.

Note

In order to prevent issues with garbage collection, the EventDispatcher class only holds weak references to pushed event handlers. That means the following example will not work, because the pushed object will fall out of scope and be collected:

dispatcher.push_handlers(MyHandlerClass())

Instead, you must make sure to keep a reference to the object before pushing it. For example:

my_handler_instance = MyHandlerClass()
dispatcher.push_handlers(my_handler_instance)

exception EventException: An exception raised when an event handler could not be attached.

class EventDispatcher

Generic event dispatcher interface.

See the module docstring for usage.

dispatch_event(event_type: str, *args: Any) → bool | None

Dispatch an event to the attached event handlers.

The event is propagated to all registered event handlers in the stack, starting and the top and going down. If any registered event handler returns EVENT_HANDLED, no further handlers down the stack will receive this event.

This method has several possible return values. If any event hander has returned EVENT_HANDLED, then this method will also return EVENT_HANDLED. If not, this method will return EVENT_UNHANDLED. If there were no events registered to receive this event, False is returned.

Return type:: bool | None
Returns:: EVENT_HANDLED if any event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked without any of them returning EVENT_HANDLED; False if no event handlers were registered.

event(*args: Any) → Callable

Function decorator for an event handler.

If the function or method name matches the event name, the decorator can be added without arguments. Likewise, if the name does not match, you can provide the target event name by passing it as an argument.

Name matches:

win = window.Window()

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

Name does not match:

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

Return type:: Callable

pop_handlers() → None

Pop the top level of event handlers off the stack.

Return type:: None

push_handlers(*args: Any, **kwargs: Any) → None

Push a new level onto the handler stack, and add 0 or more handlers.

This method first pushes a new level to the top of the handler stack. It then attaches any handlers that were passed to this new level.

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.

Return type:: None

classmethod register_event_type(name: str) → str

Register an event type with the dispatcher.

Before dispatching events, they must first be registered by name. Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Return type:: str

remove_handler(name: str, handler: Callable) → None

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.

Return type:: None

remove_handlers(*args: Any, **kwargs: Any) → None

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().

Return type:: None

set_handler(name: str, handler: Callable) → None

Attach a single event handler.

Return type:: None

set_handlers(*args: Any, **kwargs: Any) → None

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

See push_handlers() for the accepted argument types.

Return type:: None

event_types: list

pyglet.font

Load fonts.

pyglet will automatically load any system-installed fonts. You can add additional fonts (for example, from your program resources) using add_file() or add_directory(). These fonts are then available in the same way as system-installed fonts:

from pyglet import font
font.add_file('action_man.ttf')
action_man = font.load('Action Man', 16)
# or
from pyglet import resource
resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

See the pyglet.font.base module for documentation on the base classes used by this package.

add_directory(directory: str) → None

Add a directory of fonts to pyglet’s search path.

This function simply calls pyglet.font.add_file() for each file with a .ttf extension in the given directory. Subdirectories are not searched.

Parameters:: directory (str) – Directory that contains font files.
Return type:: None

add_file(font: str | BinaryIO) → None

Add a font to pyglet’s search path.

In order to load a font that is not installed on the system, you must call this method to tell pyglet that it exists. You can supply either a filename or any file-like object.

The font format is platform-dependent, but is typically a TrueType font file containing a single font face. Note that to use a font added with this method, you should pass the face name (not the file name) to :meth:pyglet.font.load() or any other place where you normally specify a font.

Parameters:: font (str | BinaryIO) – Filename or file-like object to load fonts from.
Return type:: None

add_user_font(font: UserDefinedFontBase) → None

Add a custom font created by the user.

A strong reference needs to be applied to the font object, otherwise pyglet may not find the font later.

Parameters:: font (UserDefinedFontBase) – A font class instance defined by user.
Raises:: Exception – If font provided is not derived from UserDefinedFontBase.
Return type:: None

have_font(name: str) → bool

Check if specified font name is available in the system database or user font database.

Return type:: bool

Load a font for rendering.

Parameters:

name (str | Iterable[str] | None) – Font family, for example, “Times New Roman”. If a list of names is provided, the first one matching a known font is used. If no font can be matched to the name(s), a default font is used. The default font will be platform dependent.
size (float | None) – Size of the font, in points. The returned font may be an exact match or the closest available.
bold (bool | str) – If True, a bold variant is returned, if one exists for the given family and size. For some Font renderers, bold is the weight of the font, and a string can be provided specifying the weight. For example, “semibold” or “light”.
italic (bool | str) – If True, an italic variant is returned, if one exists for the given family and size. For some Font renderers, italics may have an “oblique” variation which can be specified as a string.
stretch (bool | str) – If True, a stretch variant is returned, if one exists for the given family and size. Currently only supported by Windows through the DirectWrite font renderer. For example, “condensed” or “expanded”.
dpi (float | None) – float The assumed resolution of the display device, for the purposes of determining the pixel size of the font. Defaults to 96.

Return type:

Font

pyglet.font.user

This module defines the usage and creation of user defined fonts in Pyglet.

Previously, pyglet only supported font renderers that are built into the operating system, such as FreeType, DirectWrite, or Quartz. However, there are situations in which a user may not want or need all the features a font can provide. They just need to put characters in a particular order without the hassle of exporting into a separate file.

The UserDefinedMappingFont is provided for most use cases, which will allow you to make an internal font that can be used where a font_name is required to identify a font.

A user defined font is also identified by its name. The name you choose should be unique to ensure it will not conflict with a system font. For example, do not use Arial, as that will collide with Windows systems.

With UserDefinedMappingFont you can pass a mapping of characters that point to your ImageData.

mappings={'c': my_image_data, 'b': my_image_data, 'a': my_image_data}

For more custom behavior, a dict-like object can be used, such as a class.

class MyCustomMapping:
    def get(self, char: str) -> ImageData | None:
        # return ImageData if a character is found.
        # return None if no character is found

mappings = MyCustomMapping()

Once your font is created, you also must register it within pyglet to use it. This can be done through the: add_user_font() function.

When you register a user defined font, only those parameters will used to identify the font. If you have a font, but want to have a bold enabled version. You must make a new instance of your font, but with the bold parameter set as True. Same applies to the size parameter.

Scaling

By default, user font’s will not be scaled. In most use cases, you have a single font at a specific size that you want to use.

There are cases where a user may want to scale their font to be used at any size. We provide the following function: get_scaled_user_font(). By providing the user defined font instance, and a new size, you will get back a new font instance that is scaled to the new size. This new instance must also be registered the same way as the base font.

When specifying the size parameter, that value is used to determine the ratio of scaling between the new size. So if your base font is a size of 12, creating a scaled version at size 24 will be double the size of the base.

Warning

The PIL library is a required dependency to use the scaling functionality.

New in version 2.0.15.

exception UserDefinedFontException: An exception related to user font creation.

class UserDefinedFontBase

Used as a base for all user defined fonts.

New in version 2.0.15.

glyph_renderer_class: alias of UserDefinedGlyphRenderer

__init__( name: str, default_char: str, size: int, ascent: int | None = None, descent: int | None = None, bold: bool = False, italic: bool = False, stretch: bool = False, dpi: int = 96, locale: str | None = None, ) → None

Initialize a user defined font.

Parameters:

name (str) – Name of the font. Used to identify the font. Must be unique to ensure it does not collide with any system fonts.
default_char (str) – If a character in a string is not found in the font, it will use this as fallback.
size (int) – Font size, usually in pixels.
ascent (int | None) – Maximum ascent above the baseline, in pixels. If None, the image height is used.
descent (int | None) – Maximum descent below the baseline, in pixels. Usually negative.
bold (bool) – If True, this font will be used when bold is enabled for the font name.
italic (bool) – If True, this font will be used when italic is enabled for the font name.
stretch (bool) – If True, this font will be used when stretch is enabled for the font name.
dpi (int) – The assumed resolution of the display device, for the purposes of determining the pixel size of the font. Use a default of 96 for standard sizing.
locale (str | None) – Used to specify the locale of this font.

enable_scaling(base_size: int) → None

Return type:: None

property name: str: Return the Family Name of the font as a string.

class UserDefinedMappingFont

The class allows the creation of user defined fonts from a set of mappings.

New in version 2.0.15.

__init__( name: str, default_char: str, size: int, mappings: DictLikeObject, ascent: int | None = None, descent: int | None = None, bold: bool = False, italic: bool = False, stretch: bool = False, dpi: int = 96, locale: str | None = None, ) → None

Initialize the default parameters of your font.

Parameters:

name (str) – Name of the font. Must be unique to ensure it does not collide with any system fonts.
default_char (str) – If a character in a string is not found in the font, it will use this as fallback.
size (int) – Font size. Should be in pixels. This value will affect scaling if enabled.
mappings (DictLikeObject) – A dict or dict-like object with a get function. The get function must take a string character, and output ImageData if found. It also must return None if no character is found.
ascent (int | None) – Maximum ascent above the baseline, in pixels. If None, the image height is used.
descent (int | None) – Maximum descent below the baseline, in pixels. Usually negative.
bold (bool) – If True, this font will be used when bold is enabled for the font name.
italic (bool) – If True, this font will be used when italic is enabled for the font name.
stretch (bool) – If True, this font will be used when stretch is enabled for the font name.
dpi (int) – The assumed resolution of the display device, for the purposes of determining the pixel size of the font. Use a default of 96 for standard sizing.
locale (str | None) – Used to specify the locale of this font.

enable_scaling(base_size: int) → None

Enables scaling the font size.

Parameters:: base_size (int) – The base size is used to calculate the ratio between new sizes and the original.
Return type:: None

get_glyphs(text: str) → list[pyglet.font.base.Glyph]

Create and return a list of Glyphs for text.

If any characters do not have a known glyph representation in this font, a substitution will be made with the default_char.

Return type:: list[Glyph]

get_scaled_user_font( font_base: UserDefinedMappingFont, size: int, ) → UserDefinedMappingFont

This function will return a new font instance which can scale it’s size based off the original base font.

Note

The scaling functionality requires the PIL library to be installed.

New in version 2.0.15.

Parameters:

font_base (UserDefinedMappingFont) – The base font object to create a new size from.
size (int) – The new font size. This will be scaled based on the ratio between the base size and the new size.

Return type:

UserDefinedMappingFont

pyglet.gl

OpenGL interface.

This package imports all OpenGL and registered OpenGL extension functions. Functions have identical signatures to their C counterparts.

OpenGL is documented in full at the OpenGL Reference Pages.

The OpenGL Programming Guide, also known as “The Red Book”, is a popular reference manual organised by topic. It is available in digital and paper editions.

The following subpackages are imported into this “mega” package already (and so are available by importing pyglet.gl):

pyglet.gl.gl: OpenGL
pyglet.gl.gl.glext_arb: ARB registered OpenGL extension functions

These subpackages are also available, but are not imported into this namespace by default:

pyglet.gl.glext_nv: nVidia OpenGL extension functions
pyglet.gl.agl: AGL (Mac OS X OpenGL context functions)
pyglet.gl.glx: GLX (Linux OpenGL context functions)
pyglet.gl.glxext_arb: ARB registered GLX extension functions
pyglet.gl.glxext_nv: nvidia GLX extension functions
pyglet.gl.wgl: WGL (Windows OpenGL context functions)
pyglet.gl.wglext_arb: ARB registered WGL extension functions
pyglet.gl.wglext_nv: nvidia WGL extension functions

The information modules are provided for convenience, and are documented below.

exception ConfigException

exception ContextException

current_context = None

The active OpenGL context.

You can change the current context by calling Context.set_current; do not modify this global.

Type:: Context

New in version 1.1.

class GLException

__init__(*args, **kwargs)

__new__(**kwargs)

class ObjectSpace

__init__()

class Config

Graphics configuration.

A Config stores the preferences for OpenGL attributes such as the number of auxiliary buffers, size of the colour and depth buffers, double buffering, stencilling, multi- and super-sampling, and so on.

Different platforms support a different set of attributes, so these are set with a string key and a value which is integer or boolean.

Ivariables:

double_bufferbool: Specify the presence of a back-buffer for every color buffer.
stereobool: Specify the presence of separate left and right buffer sets.
buffer_sizeint: Total bits per sample per color buffer.
aux_buffersint: The number of auxiliary color buffers.
sample_buffersint: The number of multisample buffers.
samplesint: The number of samples per pixel, or 0 if there are no multisample buffers.
red_sizeint: Bits per sample per buffer devoted to the red component.
green_sizeint: Bits per sample per buffer devoted to the green component.
blue_sizeint: Bits per sample per buffer devoted to the blue component.
alpha_sizeint: Bits per sample per buffer devoted to the alpha component.
depth_sizeint: Bits per sample in the depth buffer.
stencil_sizeint: Bits per sample in the stencil buffer.
accum_red_sizeint: Bits per pixel devoted to the red component in the accumulation buffer.
accum_green_sizeint: Bits per pixel devoted to the green component in the accumulation buffer.
accum_blue_sizeint: Bits per pixel devoted to the blue component in the accumulation buffer.
accum_alpha_sizeint: Bits per pixel devoted to the alpha component in the accumulation buffer.

__init__(**kwargs)

Create a template config with the given attributes.

Specify attributes as keyword arguments, for example:

template = Config(double_buffer=True)

create_context(share)

Create a GL context that satisifies this configuration.

Deprecated:

Use CanvasConfig.create_context.

Parameters:

shareContext: If not None, a context with which to share objects with.

Return type:

Context

Returns:

The new context.

get_gl_attributes()

Return a list of attributes set on this config.

Return type:: list of tuple (name, value)
Returns:: All attributes, with unset attributes having a value of None.

is_complete()

Determine if this config is complete and able to create a context.

Configs created directly are not complete, they can only serve as templates for retrieving a supported config from the system. For example, pyglet.window.Screen.get_matching_configs returns complete configs.

Deprecated:: Use isinstance(config, CanvasConfig).
Return type:: bool
Returns:: True if the config is complete and can create a context.

match(canvas)

Return a list of matching complete configs for the given canvas.

New in version 1.2.

Parameters:

canvasCanvas: Display to host contexts created from the config.

Return type:

list of DisplayConfig

debug = None

forward_compatible = None

major_version = None

minor_version = None

opengl_api = None

class DisplayConfig

Bases: Config

An OpenGL configuration for a particular display.

Use Config.match to obtain an instance of this class.

New in version 1.2.

Ivariables:

canvasCanvas: The canvas this config is valid on.

__init__(canvas, base_config)

Create a template config with the given attributes.

Specify attributes as keyword arguments, for example:

template = Config(double_buffer=True)

create_context(share)

Create a GL context that satisifies this configuration.

Parameters:

shareContext: If not None, a context with which to share objects with.

Return type:

Context

Returns:

The new context.

is_complete()

Determine if this config is complete and able to create a context.

Configs created directly are not complete, they can only serve as templates for retrieving a supported config from the system. For example, pyglet.window.Screen.get_matching_configs returns complete configs.

Deprecated:: Use isinstance(config, CanvasConfig).
Return type:: bool
Returns:: True if the config is complete and can create a context.

class Context

An OpenGL context for drawing.

Use CanvasConfig.create_context to create a context.

Ivariables:

object_spaceObjectSpace: An object which is shared between all contexts that share GL objects.

__init__(config, context_share=None)

attach(canvas)

create_program(*sources: Tuple[str, str], program_class=None)

Create a ShaderProgram from OpenGL GLSL source.

This is a convenience method that takes one or more tuples of (source_string, shader_type), and returns a ShaderProgram instance.

source_string is OpenGL GLSL source code as a str, and shader_type is the OpenGL shader type, such as “vertex” or “fragment”. See Shader for more information.

Note

This method is cached. Given the same shader sources, the same ShaderProgram instance will be returned. For more control over the ShaderProgram lifecycle, it is recommended to manually create Shaders and link ShaderPrograms.

New in version 2.0.10.

delete_buffer(buffer_id)

Safely delete a Buffer object belonging to this context’s object space.

This method behaves similarly to delete_texture, though for glDeleteBuffers instead of glDeleteTextures.

Parameters:

buffer_idint: The OpenGL name of the buffer to delete.

New in version 1.1.

delete_framebuffer(fbo_id)

Safely delete a Framebuffer Object belonging to this context.

This method behaves similarly to delete_vao, though for glDeleteFramebuffers instead of glDeleteVertexArrays.

Parameters:

fbo_idint: The OpenGL name of the Framebuffer Object to delete.

New in version 2.0.10.

delete_renderbuffer(rbo_id)

Safely delete a Renderbuffer Object belonging to this context’s object space.

This method behaves similarly to delete_texture, though for glDeleteRenderbuffers instead of glDeleteTextures.

Parameters:

rbo_idint: The OpenGL name of the Shader Program to delete.

New in version 2.0.10.

delete_shader(shader_id)

Safely delete a Shader belonging to this context’s object space.

This method behaves similarly to delete_texture, though for glDeleteShader instead of glDeleteTextures.

Parameters:

shader_idint: The OpenGL name of the Shader to delete.

New in version 2.0.10.

delete_shader_program(program_id)

Safely delete a Shader Program belonging to this context’s object space.

This method behaves similarly to delete_texture, though for glDeleteProgram instead of glDeleteTextures.

Parameters:

program_idint: The OpenGL name of the Shader Program to delete.

New in version 2.0.

delete_texture(texture_id)

Safely delete a Texture belonging to this context’s object space.

This method will delete the texture immediately via glDeleteTextures if the current context’s object space is the same as this context’s object space and it is called from the main thread.

Otherwise, the texture will only be marked for deletion, postponing it until any context with the same object space becomes active again.

This makes it safe to call from anywhere, including other threads.

Parameters:

texture_idint: The OpenGL name of the Texture to delete.

delete_vao(vao_id)

Safely delete a Vertex Array Object belonging to this context.

If this context is not the current context or this method is not called from the main thread, its deletion will be postponed until this context is next made active again.

Otherwise, this method will immediately delete the VAO via glDeleteVertexArrays.

Parameters:

vao_idint: The OpenGL name of the Vertex Array to delete.

New in version 2.0.

destroy()

Release the context.

The context will not be useable after being destroyed. Each platform has its own convention for releasing the context and the buffer(s) that depend on it in the correct order; this should never be called by an application.

detach()

get_info()

Get the OpenGL information for this context.

New in version 1.2.

Return type:: GLInfo

set_current()

pyglet.graphics

Submodules

pyglet.graphics.allocation

Memory allocation algorithm for vertex arrays and buffers.

The region allocator is used to allocate vertex indices within a vertex domain’s multiple buffers. (“Buffer” refers to any abstract buffer presented by pyglet.graphics.vertexbuffer.

The allocator will at times request more space from the buffers. The current policy is to double the buffer size when there is not enough room to fulfil an allocation. The buffer is never resized smaller.

The allocator maintains references to free space only; it is the caller’s responsibility to maintain the allocated regions.

exception AllocatorMemoryException

The buffer is not large enough to fulfil an allocation.

Raised by Allocator methods when the operation failed due to lack of buffer space. The buffer should be increased to at least requested_capacity and then the operation retried (guaranteed to pass second time).

__init__(requested_capacity)

class Allocator

Buffer space allocation implementation.

__init__(capacity)

Create an allocator for a buffer of the specified capacity.

Parameters:

capacityint: Maximum size of the buffer.

alloc(size)

Allocate memory in the buffer.

Raises AllocatorMemoryException if the allocation cannot be fulfilled.

Parameters:

sizeint: Size of region to allocate.

Return type:

int

Returns:

Starting index of the allocated region.

dealloc(start, size)

Free a region of the buffer.

Parameters:

startint: Starting index of the region.
sizeint: Size of the region.

get_allocated_regions()

Get a list of (aggregate) allocated regions.

The result of this method is (starts, sizes), where starts is a list of starting indices of the regions and sizes their corresponding lengths.

Return type:: (list, list)

get_fragmentation()

Return fraction of free space that is not expandable.

Return type:: float

get_fragmented_free_size()

Returns the amount of space unused, not including the final free block.

Return type:: int

get_free_size()

Return the amount of space unused.

Return type:: int

get_usage()

Return fraction of capacity currently allocated.

Return type:: float

realloc(start, size, new_size)

Reallocate a region of the buffer.

This is more efficient than separate dealloc and alloc calls, as the region can often be resized in-place.

Raises AllocatorMemoryException if the allocation cannot be fulfilled.

Parameters:

startint: Current starting index of the region.
sizeint: Current size of the region.
new_sizeint: New size of the region.

set_capacity(size)

Resize the maximum buffer size.

The capaity cannot be reduced.

Parameters:

sizeint: New maximum size of the buffer.

capacity

sizes

starts

pyglet.graphics.shader

exception ShaderException

class Attribute

Abstract accessor for an attribute in a mapped buffer.

__init__(name, location, count, gl_type, normalize)

Create the attribute accessor.

Parameters:

namestr: Name of the vertex attribute.
locationint: Location (index) of the vertex attribute.
countint: Number of components in the attribute.
gl_typeint: OpenGL type enumerant; for example, GL_FLOAT
normalize: bool: True if OpenGL should normalize the values

enable(): Enable the attribute.

get_region(buffer, start, count)

Map a buffer region using this attribute as an accessor.

The returned region consists of a contiguous array of component data elements. For example, if this attribute uses 3 floats per vertex, and the count parameter is 4, the number of floats mapped will be 3 * 4 = 12.

Parameters:

bufferAttributeBufferObject: The buffer to map.
startint: Offset of the first vertex to map.
countint: Number of vertices to map

set_pointer(ptr)

Setup this attribute to point to the currently bound buffer at the given offset.

offset should be based on the currently bound buffer’s ptr member.

Parameters:

offsetint: Pointer offset to the currently bound buffer for this attribute.

set_region(buffer, start, count, data)

Set the data over a region of the buffer.

Parameters:

bufferAbstractMappable`: The buffer to modify.
startint: Offset of the first vertex to set.
countint: Number of vertices to set.
dataseq: A sequence of data components.

class ComputeShaderProgram

OpenGL Compute Shader Program

__init__(source: str): Create an OpenGL ComputeShaderProgram from source.

bind() → None

Return type:: None

delete()

static dispatch( x: int = 1, y: int = 1, z: int = 1, barrier: int = 4294967295, ) → None

Launch one or more compute work groups.

The ComputeShaderProgram should be active (bound) before calling this method. The x, y, and z parameters specify the number of local work groups that will be dispatched in the X, Y and Z dimensions.

Return type:: None

static stop()

static unbind()

use() → None

Return type:: None

property id: int

property uniform_blocks: dict

property uniforms

class Shader

OpenGL shader.

Shader objects are compiled on instantiation. You can reuse a Shader object in multiple ShaderPrograms.

shader_type is one of 'compute', 'fragment', 'geometry', 'tesscontrol', 'tessevaluation', or 'vertex'.

__init__(source_string: str, shader_type: str)

delete()

property id

class ShaderProgram

OpenGL shader program.

__init__(*shaders: Shader)

bind()

delete()

static stop()

static unbind()

use()

vertex_list(count, mode, batch=None, group=None, **data)

Create a VertexList.

Parameters:

countint: The number of vertices in the list.
modeint: OpenGL drawing mode enumeration; for example, one of GL_POINTS, GL_LINES, GL_TRIANGLES, etc. This determines how the list is drawn in the given batch.
batch~pyglet.graphics.Batch: Batch to add the VertexList to, or None if a Batch will not be used. Using a Batch is strongly recommended.
group~pyglet.graphics.Group: Group to add the VertexList to, or None if no group is required.
**datastr or tuple: Attribute formats and initial data for the vertex list.

Return type:

VertexList

vertex_list_indexed(

count,

mode,

indices,

batch=None,

group=None,

**data,

)

Create a IndexedVertexList.

Parameters:

countint: The number of vertices in the list.
modeint: OpenGL drawing mode enumeration; for example, one of GL_POINTS, GL_LINES, GL_TRIANGLES, etc. This determines how the list is drawn in the given batch.
indicessequence of int: Sequence of integers giving indices into the vertex list.
batch~pyglet.graphics.Batch: Batch to add the VertexList to, or None if a Batch will not be used. Using a Batch is strongly recommended.
group~pyglet.graphics.Group: Group to add the VertexList to, or None if no group is required.
**datastr or tuple: Attribute formats and initial data for the vertex list.

Return type:

IndexedVertexList

property attributes: dict

Attribute metadata dictionary

This property returns a dictionary containing metadata of all Attributes that were introspected in this ShaderProgram. Modifying this dictionary has no effect.

property id

property uniform_blocks: dict

A dictionary of introspected UniformBlocks

This property returns a dictionary of UniformBlock instances. They can be accessed by name. For example:

block = my_shader_program.uniform_blocks['WindowBlock']
ubo = block.create_ubo()

property uniforms: dict

Uniform metadata dictionary

This property returns a dictionary containing metadata of all Uniforms that were introspected in this ShaderProgram. Modifying this dictionary has no effect. To set or get a uniform, the uniform name is used as a key on the ShaderProgram instance. For example:

my_shader_program[uniform_name] = 123
value = my_shader_program[uniform_name]

class ShaderSource

GLSL source container for making source parsing simpler.

We support locating out attributes and applying #defines values.

NOTE: We do assume the source is neat enough to be parsed this way and don’t contain several statements in one line.

__init__(source: str, source_type: c_uint): Create a shader source wrapper.

validate() → str

Return the validated shader source.

Return type:: str

class UniformBlock

__init__(program, name, index, size, uniforms)

create_ubo(index=0)

Create a new UniformBufferObject from this uniform block.

Parameters:

indexint: The uniform buffer index the returned UBO will bind itself to. By default, this is 0.

Return type:

UniformBufferObject

index

name

program

size

uniforms

view_cls

class UniformBufferObject

__init__(view_class, buffer_size, index)

bind(index=None)

read(): Read the byte contents of the buffer

buffer

property id

index

view

pyglet.graphics.vertexbuffer

Byte abstractions of OpenGL Buffer Objects.

Use create_buffer to create a Buffer Object.

Buffers can optionally be created “mappable” (incorporating the AbstractMappable mix-in). In this case the buffer provides a get_region method which provides the most efficient path for updating partial data within the buffer.

class AbstractBuffer

Abstract buffer of byte data.

Ivariables:

sizeint: Size of buffer, in bytes
ptrint: Memory offset of the buffer, as used by the glVertexPointer family of functions
usageint: OpenGL buffer usage, for example GL_DYNAMIC_DRAW

bind(target=34962): Bind this buffer to an OpenGL target.

delete(): Delete this buffer, reducing system resource usage.

map()

Map the entire buffer into system memory.

The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.

Parameters:

invalidatebool: If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.

Return type:

POINTER(ctypes.c_ubyte)

Returns:

Pointer to the mapped block in memory

resize(size)

Resize the buffer to a new size.

Parameters:

sizeint: New size of the buffer, in bytes

set_data(data)

Set the entire contents of the buffer.

Parameters:

datasequence of int or ctypes pointer: The byte array to set.

set_data_region(data, start, length)

Set part of the buffer contents.

Parameters:

datasequence of int or ctypes pointer: The byte array of data to set
startint: Offset to start replacing data
lengthint: Length of region to replace

unbind(): Reset the buffer’s OpenGL target.

unmap(): Unmap a previously mapped memory block.

ptr = 0

size = 0

class AttributeBufferObject

A buffer with system-memory backed store.

Updates to the data via set_data and set_data_region will be held in local memory until buffer_data is called. The advantage is that fewer OpenGL calls are needed, which can increasing performance at the expense of system memory.

__init__(size, attribute, usage=35048)

get_region(start, count)

invalidate()

invalidate_region(start, count)

resize(size)

Resize the buffer to a new size.

Parameters:

sizeint: New size of the buffer, in bytes

set_region(start, count, data)

sub_data(): Updates the buffer if any data has been changed or invalidated. Allows submitting multiple changes at once, rather than having to call glBufferSubData for every change.

class BufferObject

Lightweight representation of an OpenGL Buffer Object.

The data in the buffer is not replicated in any system memory (unless it is done so by the video driver). While this can improve memory usage and possibly performance, updates to the buffer are relatively slow. The target of the buffer is GL_ARRAY_BUFFER internally to avoid accidentally overriding other states when altering the buffer contents. The intended target can be set when binding the buffer.

This class does not implement AbstractMappable, and so has no get_region() method. See MappableVertexBufferObject for a Buffer class that does implement get_region().

__init__(size, usage=35048)

bind(target=34962): Bind this buffer to an OpenGL target.

bind_to_index_buffer(): Binds this buffer as an index buffer on the active vertex array.

delete(): Delete this buffer, reducing system resource usage.

invalidate()

map()

Map the entire buffer into system memory.

The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.

Parameters:

invalidatebool: If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.

Return type:

POINTER(ctypes.c_ubyte)

Returns:

Pointer to the mapped block in memory

map_range(start, size, ptr_type)

resize(size)

Resize the buffer to a new size.

Parameters:

sizeint: New size of the buffer, in bytes

set_data(data)

Set the entire contents of the buffer.

Parameters:

datasequence of int or ctypes pointer: The byte array to set.

set_data_region(data, start, length)

Set part of the buffer contents.

Parameters:

datasequence of int or ctypes pointer: The byte array of data to set
startint: Offset to start replacing data
lengthint: Length of region to replace

unbind(): Reset the buffer’s OpenGL target.

unmap(): Unmap a previously mapped memory block.

class PersistentBufferObject

__init__(size, attribute, vao)

bind(target=34962): Bind this buffer to an OpenGL target.

get_region(start, count)

invalidate()

invalidate_region(start, count)

map_range(start, size, ptr_type, flags=2)

resize(size)

Resize the buffer to a new size.

Parameters:

sizeint: New size of the buffer, in bytes

set_region(start, count, data)

sub_data()

unbind(): Reset the buffer’s OpenGL target.

pyglet.graphics.vertexdomain

Manage related vertex attributes within a single vertex domain.

A vertex “domain” consists of a set of attribute descriptions that together describe the layout of one or more vertex buffers which are used together to specify the vertices in a primitive. Additionally, the domain manages the buffers used to store the data and will resize them as necessary to accommodate new vertices.

Domains can optionally be indexed, in which case they also manage a buffer containing vertex indices. This buffer is grown separately and has no size relation to the attribute buffers.

Applications can create vertices (and optionally, indices) within a domain with the VertexDomain.create() method. This returns a VertexList representing the list of vertices created. The vertex attribute data within the group can be modified, and the changes will be made to the underlying buffers automatically.

The entire domain can be efficiently drawn in one step with the VertexDomain.draw() method, assuming all the vertices comprise primitives of the same OpenGL primitive mode.

class IndexedVertexDomain

Management of a set of indexed vertex lists.

Construction of an indexed vertex domain is usually done with the create_domain() function.

__init__(program, attribute_meta, index_gl_type=5125)

create(count, index_count)

Create an IndexedVertexList in this domain.

Parameters:

countint: Number of vertices to create
index_count: Number of indices to create

draw(mode)

Draw all vertices in the domain.

All vertices in the domain are drawn at once. This is the most efficient way to render primitives.

Parameters:

modeint: OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.

draw_subset(mode, vertex_list)

Draw a specific IndexedVertexList in the domain.

The vertex_list parameter specifies a IndexedVertexList to draw. Only primitives in that list will be drawn.

Parameters:

modeint: OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.
vertex_listIndexedVertexList: Vertex list to draw.

get_index_region(start, count)

Get a data from a region of the index buffer.

Parameters:

startint: Start of the region to map.
countint: Number of indices to map.

Return type:

Array of int

safe_index_alloc(count): Allocate indices, resizing the buffers if necessary.

safe_index_realloc(start, count, new_count): Reallocate indices, resizing the buffers if necessary.

set_index_region(start, count, data)

class IndexedVertexList

A list of vertices within an IndexedVertexDomain that are indexed. Use IndexedVertexDomain.create() to construct this list.

__init__(domain, start, count, index_start, index_count)

delete(): Delete this group.

migrate(domain)

Move this group from its current indexed domain and add to the specified one. Attributes on domains must match. (In practice, used to change parent state of some vertices).

Parameters:

domainIndexedVertexDomain: Indexed domain to migrate this vertex list to.

resize(count, index_count)

Resize this group.

Parameters:

countint: New number of vertices in the list.
index_countint: New number of indices in the list.

property indices: Array of index data.

class VertexDomain

Management of a set of vertex lists.

Construction of a vertex domain is usually done with the create_domain() function.

__init__(program, attribute_meta)

create(count, index_count=None)

Create a VertexList in this domain.

Parameters:

countint: Number of vertices to create.
index_count: None: Ignored for non indexed VertexDomains

Return type:

VertexList

draw(mode)

Draw all vertices in the domain.

All vertices in the domain are drawn at once. This is the most efficient way to render primitives.

Parameters:

modeint: OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.

draw_subset(mode, vertex_list)

Draw a specific VertexList in the domain.

The vertex_list parameter specifies a VertexList to draw. Only primitives in that list will be drawn.

Parameters:

modeint: OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.
vertex_listVertexList: Vertex list to draw.

safe_alloc(count): Allocate vertices, resizing the buffers if necessary.

safe_realloc(start, count, new_count): Reallocate vertices, resizing the buffers if necessary.

property is_empty

class VertexList

A list of vertices within a VertexDomain. Use VertexDomain.create() to construct this list.

__init__(domain, start, count)

delete(): Delete this group.

draw(mode)

Draw this vertex list in the given OpenGL mode.

Parameters:

modeint: OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.

migrate(domain)

Move this group from its current domain and add to the specified one. Attributes on domains must match. (In practice, used to change parent state of some vertices).

Parameters:

domainVertexDomain: Domain to migrate this vertex list to.

resize(count, index_count=None)

Resize this group.

Parameters:

countint: New number of vertices in the list.
index_count: None: Ignored for non indexed VertexDomains

set_attribute_data(name, data)

Details

Low-level graphics rendering and abstractions.

This module provides efficient abstractions over OpenGL objects, such as Shaders and Buffers. It also provides classes for highly performant batched rendering and grouping.

See the Shaders and Rendering for details on how to use this graphics API.

class Batch

Manage a collection of drawables for batched rendering.

Many drawable pyglet objects accept an optional Batch argument in their constructors. By giving a Batch to multiple objects, you can tell pyglet that you expect to draw all of these objects at once, so it can optimise its use of OpenGL. Hence, drawing a Batch is often much faster than drawing each contained drawable separately.

The following example creates a batch, adds two sprites to the batch, and then draws the entire batch:

batch = pyglet.graphics.Batch()
car = pyglet.sprite.Sprite(car_image, batch=batch)
boat = pyglet.sprite.Sprite(boat_image, batch=batch)

def on_draw():
    batch.draw()

While any drawables can be added to a Batch, only those with the same draw mode, shader program, and group can be optimised together.

Internally, a Batch manages a set of VertexDomains along with information about how the domains are to be drawn. To implement batching on a custom drawable, get your vertex domains from the given batch instead of setting them up yourself.

__init__(): Create a graphics batch.

draw(): Draw the batch.

draw_subset(vertex_lists)

Draw only some vertex lists in the batch.

The use of this method is highly discouraged, as it is quite inefficient. Usually an application can be redesigned so that batches can always be drawn in their entirety, using draw.

The given vertex lists must belong to this batch; behaviour is undefined if this condition is not met.

Parameters:

vertex_listssequence of VertexList or IndexedVertexList: Vertex lists to draw.

get_domain(indexed, mode, group, program, attributes): Get, or create, the vertex domain corresponding to the given arguments.

invalidate()

Force the batch to update the draw list.

This method can be used to force the batch to re-compute the draw list when the ordering of groups has changed.

New in version 1.2.

migrate(vertex_list, mode, group, batch)

Migrate a vertex list to another batch and/or group.

vertex_list and mode together identify the vertex list to migrate. group and batch are new owners of the vertex list after migration.

The results are undefined if mode is not correct or if vertex_list does not belong to this batch (they are not checked and will not necessarily throw an exception immediately).

batch can remain unchanged if only a group change is desired.

Parameters:

vertex_list~pyglet.graphics.vertexdomain.VertexList: A vertex list currently belonging to this batch.
modeint: The current GL drawing mode of the vertex list.
group~pyglet.graphics.Group: The new group to migrate to.
batch~pyglet.graphics.Batch: The batch to migrate to (or the current batch).

class Group

Group of common OpenGL state.

Group provides extra control over how drawables are handled within a Batch. When a batch draws a drawable, it ensures its group’s state is set; this can include binding textures, shaders, or setting any other parameters. It also sorts the groups before drawing.

In the following example, the background sprite is guaranteed to be drawn before the car and the boat:

batch = pyglet.graphics.Batch()
background = pyglet.graphics.Group(order=0)
foreground = pyglet.graphics.Group(order=1)

background = pyglet.sprite.Sprite(background_image, batch=batch, group=background)
car = pyglet.sprite.Sprite(car_image, batch=batch, group=foreground)
boat = pyglet.sprite.Sprite(boat_image, batch=batch, group=foreground)

def on_draw():
    batch.draw()

Parameters:

orderint: Set the order to render above or below other Groups. Lower orders are drawn first.
parent~pyglet.graphics.Group: Group to contain this Group; its state will be set before this Group’s state.

Variables:

visiblebool: Determines whether this Group is visible in any of the Batches it is assigned to. If False, objects in this Group will not be rendered.
batcheslist: Read Only. A list of which Batches this Group is a part of.

__init__(order=0, parent=None)

set_state()

Apply the OpenGL state change.

The default implementation does nothing.

set_state_recursive()

Set this group and its ancestry.

Call this method if you are using a group in isolation: the parent groups will be called in top-down order, with this class’s set being called last.

unset_state()

Repeal the OpenGL state change.

The default implementation does nothing.

unset_state_recursive()

Unset this group and its ancestry.

The inverse of set_state_recursive.

property batches

property order

property visible

class ShaderGroup

A group that enables and binds a ShaderProgram.

__init__(program, order=0, parent=None)

set_state()

Apply the OpenGL state change.

The default implementation does nothing.

unset_state()

Repeal the OpenGL state change.

The default implementation does nothing.

class TextureGroup

A group that enables and binds a texture.

TextureGroups are equal if their textures’ targets and names are equal.

__init__(texture, order=0, parent=None)

Create a texture group.

Parameters:

texture~pyglet.image.Texture: Texture to bind.
orderint: Change the order to render above or below other Groups.
parent~pyglet.graphics.Group: Parent group.

set_state()

Apply the OpenGL state change.

The default implementation does nothing.

draw(size, mode, **data)

Draw a primitive immediately.

Warning:

This function is deprecated as of 2.0.4, and will be removed in the next release.

Parameters:

sizeint: Number of vertices given
modegl primitive type: OpenGL drawing mode, e.g. GL_TRIANGLES, avoiding quotes.
**datakeyword arguments for passing vertex attribute data.: The keyword should be the vertex attribute name, and the argument should be a tuple of (format, data). For example: position=(‘f’, array)

draw_indexed(size, mode, indices, **data)

Draw a primitive with indexed vertices immediately.

Warning:

This function is deprecated as of 2.0.4, and will be removed in the next release.

Parameters:

sizeint: Number of vertices given
modeint: OpenGL drawing mode, e.g. GL_TRIANGLES
indicessequence of int: Sequence of integers giving indices into the vertex list.
**datakeyword arguments for passing vertex attribute data.: The keyword should be the vertex attribute name, and the argument should be a tuple of (format, data). For example: position=(‘f’, array)

get_default_batch()

get_default_shader()

pyglet.gui

Classes

class WidgetBase

Attributes

x: X coordinate of the widget.

y: Y coordinate of the widget.

width: Width of the widget.

height: Height of the widget.

aabb

Bounding box of the widget.

The “left”, “bottom”, “right”, and “top” coordinates of the widget. This is expressed as (x, y, x + width, y + height).

__init__(x: int, y: int, width: int, height: int) → None

__new__(**kwargs)

class PushButton

Bases: WidgetBase

Instance of a push button.

Triggers the event ‘on_press’ when it is clicked by the mouse. Triggers the event ‘on_release’ when the mouse is released.

__init__( x: int, y: int, pressed: AbstractImage, unpressed: AbstractImage, hover: AbstractImage | None = None, batch: Batch | None = None, group: Group | None = None, ) → None

Create a push button.

Parameters:

x (int) – X coordinate of the push button.
y (int) – Y coordinate of the push button.
pressed (AbstractImage) – Image to display when the button is pressed.
unpressed (AbstractImage) – Image to display when the button isn’t pressed.
hover (AbstractImage | None) – Image to display when the button is being hovered over.
batch (Batch | None) – Optional batch to add the push button to.
group (Group | None) – Optional parent group of the push button.

on_mouse_drag( x: int, y: int, dx: int, dy: int, buttons: int, modifiers: int, ) → None

Return type:: None

on_mouse_motion(x: int, y: int, dx: int, dy: int) → None

Return type:: None

on_mouse_press(x: int, y: int, buttons: int, modifiers: int) → None

Return type:: None

on_mouse_release(x: int, y: int, buttons: int, modifiers: int) → None

Return type:: None

on_press(widget: PushButton) → None

Event: Dispatched when the button is clicked.

Return type:: None

on_release(widget: PushButton) → None

Event: Dispatched when the button is released.

Return type:: None

update_groups(order: float) → None

Return type:: None

property value: Whether the button is pressed or not.

class ToggleButton

Bases: PushButton

Instance of a toggle button.

Triggers the event ‘on_toggle’ when the mouse is pressed or released.

on_mouse_press(x: int, y: int, buttons: int, modifiers: int) → None

Return type:: None

on_mouse_release(x: int, y: int, buttons: int, modifiers: int) → None

Return type:: None

on_toggle(widget: ToggleButton, value: bool) → None

Event: returns True or False to indicate the current state.

Return type:: None

class Slider

Bases: WidgetBase

Instance of a slider made of a base and a knob image.

Triggers the event ‘on_change’ when the knob position is changed. The knob position can be changed by dragging with the mouse, or scrolling the mouse wheel.

__init__( x: int, y: int, base: AbstractImage, knob: AbstractImage, edge: int = 0, batch: Batch | None = None, group: Group | None = None, ) → None

Create a slider.

Parameters:

x (int) – X coordinate of the slider.
y (int) – Y coordinate of the slider.
base (AbstractImage) – Image to display as the background to the slider.
knob (AbstractImage) – Knob that moves to show the position of the slider.
edge (int) – Pixels from the maximum and minimum position of the slider, to the edge of the base image.
batch (Batch | None) – Optional batch to add the slider to.
group (Group | None) – Optional parent group of the slider.

on_change(widget: Slider, value: float) → None

Event: Returns the current value when the slider is changed.

Return type:: None

on_mouse_drag( x: int, y: int, dx: int, dy: int, buttons: int, modifiers: int, ) → None

Return type:: None

on_mouse_press(x: int, y: int, buttons: int, modifiers: int) → None

Return type:: None

on_mouse_release(x: int, y: int, buttons: int, modifiers: int) → None

Return type:: None

on_mouse_scroll(x: int, y: int, scroll_x: int, scroll_y: int) → None

Return type:: None

update_groups(order: float) → None

Return type:: None

property value: float

Query or set the Widget’s value.

This property allows you to set the value of a Widget directly, without any user input. This could be used, for example, to restore Widgets to a previous state, or if some event in your program is meant to naturally change the same value that the Widget controls. Note that events are not dispatched when changing this property directly.

class TextEntry

Bases: WidgetBase

Instance of a text entry widget. Allows the user to enter and submit text.

Triggers the event ‘on_commit’, when the user hits the Enter or Return key. The current text string is passed along with the event.

__init__( text: str, x: int, y: int, width: int, color: tuple[int, int, int, int] = (255, 255, 255, 255), text_color: tuple[int, int, int, int] = (0, 0, 0, 255), caret_color: tuple[int, int, int, int] = (0, 0, 0, 255), batch: Batch | None = None, group: Group | None = None, ) → None

Create a text entry widget.

Parameters:

text (str) – Initial text to display.
x (int) – X coordinate of the text entry widget.
y (int) – Y coordinate of the text entry widget.
width (int) – The width of the text entry widget.
color (tuple[int, int, int, int]) – The color of the outline box in RGBA format.
text_color (tuple[int, int, int, int]) – The color of the text in RGBA format.
caret_color (tuple[int, int, int, int]) – The color of the caret (when it is visible) in RGBA or RGB format.
batch (Batch | None) – Optional batch to add the text entry widget to.
group (Group | None) – Optional parent group of text entry widget.

on_commit(widget: TextEntry, text: str) → None

Event: dispatches the current text when commited via Enter/Return key.

Return type:: None

on_mouse_drag( x: int, y: int, dx: int, dy: int, buttons: int, modifiers: int, ) → None

Return type:: None

on_mouse_motion(x: int, y: int, dx: int, dy: int) → None

Return type:: None

on_mouse_press(x: int, y: int, buttons: int, modifiers: int) → None

Return type:: None

on_text(text: str) → None

Return type:: None

on_text_motion(motion: int) → None

Return type:: None

on_text_motion_select(motion: int) → None

Return type:: None

update_groups(order: float) → None

Return type:: None

property focus: bool

property height: int: Height of the widget.

property value: str

Query or set the Widget’s value.

This property allows you to set the value of a Widget directly, without any user input. This could be used, for example, to restore Widgets to a previous state, or if some event in your program is meant to naturally change the same value that the Widget controls. Note that events are not dispatched when changing this property directly.

property width: int: Width of the widget.

pyglet.image

Submodules

pyglet.image.atlas

Group multiple small images into larger textures.

This module is used by pyglet.resource to efficiently pack small images into larger textures. TextureAtlas maintains one texture; TextureBin manages a collection of atlases of a given size.

Example usage:

# Load images from disk
car_image = pyglet.image.load('car.png')
boat_image = pyglet.image.load('boat.png')

# Pack these images into one or more textures
bin = TextureBin()
car_texture = bin.add(car_image)
boat_texture = bin.add(boat_image)

The result of TextureBin.add() is a TextureRegion containing the image. Once added, an image cannot be removed from a bin (or an atlas); nor can a list of images be obtained from a given bin or atlas – it is the application’s responsibility to keep track of the regions returned by the add methods.

New in version 1.1.

exception AllocatorException: The allocator does not have sufficient free space for the requested image size.

class Allocator

Rectangular area allocation algorithm.

Initialise with a given width and height, then repeatedly call alloc to retrieve free regions of the area and protect that area from future allocations.

Allocator uses a fairly simple strips-based algorithm. It performs best when rectangles are allocated in decreasing height order.

__init__(width: int, height: int) → None

Create an Allocator of the given size.

Parameters:

widthint: Width of the allocation region.
heightint: Height of the allocation region.

alloc(width: int, height: int) → Tuple[int, int]

Get a free area in the allocator of the given size.

After calling alloc, the requested area will no longer be used. If there is not enough room to fit the given area AllocatorException is raised.

Parameters:

widthint: Width of the area to allocate.
heightint: Height of the area to allocate.

Return type:

int, int

Returns:

The X and Y coordinates of the bottom-left corner of the allocated region.

get_fragmentation() → float

Get the fraction of area that’s unlikely to ever be used, based on current allocation behaviour.

This method is useful for debugging and profiling only.

Return type:: float

get_usage() → float

Get the fraction of area already allocated.

This method is useful for debugging and profiling only.

Return type:: float

height

strips

used_area

width

class TextureArrayBin

Collection of texture arrays.

TextureArrayBin maintains a collection of texture arrays, and creates new ones as necessary as the depth is exceeded.

__init__( texture_width: int = 2048, texture_height: int = 2048, max_depth: int | None = None, ) → None

add( img: AbstractImage, ) → TextureArrayRegion

Add an image into this texture array bin.

This method calls TextureArray.add for the first array that has room for the image.

TextureArraySizeExceeded is raised if the image exceeds the dimensions of texture_width and texture_height.

Parameters:

img~pyglet.image.AbstractImage: The image to add.

Return type:

TextureArrayRegion

Returns:

The region of an array containing the newly added image.

class TextureAtlas

Collection of images within a texture.

__init__(width: int = 2048, height: int = 2048) → None

Create a texture atlas of the given size.

Parameters:

widthint: Width of the underlying texture.
heightint: Height of the underlying texture.

add( img: AbstractImage, border: int = 0, ) → TextureRegion

Add an image to the atlas.

This method will fail if the given image cannot be transferred directly to a texture (for example, if it is another texture). ImageData is the usual image type for this method.

AllocatorException will be raised if there is no room in the atlas for the image.

Parameters:

img~pyglet.image.AbstractImage: The image to add.
borderint: Leaves specified pixels of blank space around each image added to the Atlas.

Return type:

TextureRegion

Returns:

The region of the atlas containing the newly added image.

class TextureBin

Collection of texture atlases.

TextureBin maintains a collection of texture atlases, and creates new ones as necessary to accommodate images added to the bin.

__init__(texture_width: int = 2048, texture_height: int = 2048) → None

Create a texture bin for holding atlases of the given size.

Parameters:

texture_widthint: Width of texture atlases to create.
texture_heightint: Height of texture atlases to create.
borderint: Leaves specified pixels of blank space around each image added to the Atlases.

add( img: AbstractImage, border: int = 0, ) → TextureRegion

Add an image into this texture bin.

This method calls TextureAtlas.add for the first atlas that has room for the image.

AllocatorException is raised if the image exceeds the dimensions of texture_width and texture_height.

Parameters:

img~pyglet.image.AbstractImage: The image to add.
borderint: Leaves specified pixels of blank space around each image added to the Atlas.

Return type:

TextureRegion

Returns:

The region of an atlas containing the newly added image.

pyglet.image.animation

2D Animations

Animations can be used by the Sprite class in place of static images. They are essentially containers for individual image frames, with a duration per frame. They can be infinitely looping, or stop at the last frame. You can load Animations from disk, such as from GIF files:

ani = pyglet.resource.animation('walking.gif')
sprite = pyglet.sprite.Sprite(img=ani)

Alternatively, you can create your own Animations from a sequence of images by using the from_image_sequence() method:

images = [pyglet.resource.image('walk_a.png'),
          pyglet.resource.image('walk_b.png'),
          pyglet.resource.image('walk_c.png')]

ani = pyglet.image.Animation.from_image_sequence(images, duration=0.1, loop=True)

You can also use an pyglet.image.ImageGrid, which is iterable:

sprite_sheet = pyglet.resource.image('my_sprite_sheet.png')
image_grid = pyglet.image.ImageGrid(sprite_sheet, rows=1, columns=5)

ani = pyglet.image.Animation.from_image_sequence(image_grid, duration=0.1)

In the above examples, all of the Animation Frames have the same duration. If you wish to adjust this, you can manually create the Animation from a list of AnimationFrame:

image_a = pyglet.resource.image('walk_a.png')
image_b = pyglet.resource.image('walk_b.png')
image_c = pyglet.resource.image('walk_c.png')

frame_a = pyglet.image.AnimationFrame(image_a, duration=0.1)
frame_b = pyglet.image.AnimationFrame(image_b, duration=0.2)
frame_c = pyglet.image.AnimationFrame(image_c, duration=0.1)

ani = pyglet.image.Animation(frames=[frame_a, frame_b, frame_c])

class Animation

Sequence of images with timing information.

If no frames of the animation have a duration of None, the animation loops continuously; otherwise the animation stops at the first frame with duration of None.

Ivariables:

frameslist of ~pyglet.image.AnimationFrame: The frames that make up the animation.

__init__(frames)

Create an animation directly from a list of frames.

Parameters:

frameslist of ~pyglet.image.AnimationFrame: The frames that make up the animation.

add_to_texture_bin(texture_bin, border=0)

Add the images of the animation to a TextureBin.

The animation frames are modified in-place to refer to the texture bin regions.

Parameters:

texture_bin~pyglet.image.atlas.TextureBin: Texture bin to upload animation frames into.
borderint: Leaves specified pixels of blank space around each image frame when adding to the TextureBin.

classmethod from_image_sequence(sequence, duration, loop=True)

Create an animation from a list of images and a constant framerate.

Parameters:

sequencelist of ~pyglet.image.AbstractImage: Images that make up the animation, in sequence.
durationfloat: Number of seconds to display each image.
loopbool: If True, the animation will loop continuously.

Return type:

Animation

get_duration()

Get the total duration of the animation in seconds.

Return type:: float

get_max_height()

Get the maximum image frame height.

This method is useful for determining texture space requirements: due to the use of anchor_y the actual required playback area may be larger.

Return type:: int

get_max_width()

Get the maximum image frame width.

This method is useful for determining texture space requirements: due to the use of anchor_x the actual required playback area may be larger.

Return type:: int

get_transform(flip_x=False, flip_y=False, rotate=0)

Create a copy of this animation applying a simple transformation.

The transformation is applied around the image’s anchor point of each frame. The texture data is shared between the original animation and the transformed animation.

Parameters:

flip_xbool: If True, the returned animation will be flipped horizontally.
flip_ybool: If True, the returned animation will be flipped vertically.
rotateint: Degrees of clockwise rotation of the returned animation. Only 90-degree increments are supported.

Return type:

Animation

class AnimationFrame

A single frame of an animation.

__init__(image, duration)

Create an animation frame from an image.

Parameters:

image~pyglet.image.AbstractImage: The image of this frame.
durationfloat: Number of seconds to display the frame, or None if it is the last frame in the animation.

duration

image

pyglet.image.buffer

class Framebuffer

OpenGL Framebuffer Object

New in version 2.0.

__init__(target=36160) → Framebuffer

attach_renderbuffer(renderbuffer, target=36160, attachment=36064)

Attach a Renderbuffer to the Framebuffer

Parameters:

renderbufferpyglet.image.Renderbuffer: Specifies the Renderbuffer to attach to the framebuffer attachment point named by attachment.
targetint: Specifies the framebuffer target. target must be GL_DRAW_FRAMEBUFFER, GL_READ_FRAMEBUFFER, or GL_FRAMEBUFFER. GL_FRAMEBUFFER is equivalent to GL_DRAW_FRAMEBUFFER.
attachmentint: Specifies the attachment point of the framebuffer. attachment must be GL_COLOR_ATTACHMENTi, GL_DEPTH_ATTACHMENT, GL_STENCIL_ATTACHMENT or GL_DEPTH_STENCIL_ATTACHMENT.

attach_texture(texture, target=36160, attachment=36064)

Attach a Texture to the Framebuffer

Parameters:

texturepyglet.image.Texture: Specifies the texture object to attach to the framebuffer attachment point named by attachment.
targetint: Specifies the framebuffer target. target must be GL_DRAW_FRAMEBUFFER, GL_READ_FRAMEBUFFER, or GL_FRAMEBUFFER. GL_FRAMEBUFFER is equivalent to GL_DRAW_FRAMEBUFFER.
attachmentint: Specifies the attachment point of the framebuffer. attachment must be GL_COLOR_ATTACHMENTi, GL_DEPTH_ATTACHMENT, GL_STENCIL_ATTACHMENT or GL_DEPTH_STENCIL_ATTACHMENT.

attach_texture_layer( texture, layer, level, target=36160, attachment=36064, )

Attach a Texture layer to the Framebuffer

Parameters:

texturepyglet.image.TextureArray: Specifies the texture object to attach to the framebuffer attachment point named by attachment.
layerint: Specifies the layer of texture to attach.
levelint: Specifies the mipmap level of texture to attach.
targetint: Specifies the framebuffer target. target must be GL_DRAW_FRAMEBUFFER, GL_READ_FRAMEBUFFER, or GL_FRAMEBUFFER. GL_FRAMEBUFFER is equivalent to GL_DRAW_FRAMEBUFFER.
attachmentint: Specifies the attachment point of the framebuffer. attachment must be GL_COLOR_ATTACHMENTi, GL_DEPTH_ATTACHMENT, GL_STENCIL_ATTACHMENT or GL_DEPTH_STENCIL_ATTACHMENT.

bind()

Bind the Framebuffer

This ctivates it as the current drawing target.

clear(): Clear the attachments

delete(): Explicitly delete the Framebuffer.

static get_status() → str

Get the current Framebuffer status, as a string.

If Framebuffer.is_complete is False, this method can be used for more information. It will return a string with the OpenGL reported status.

Return type:: str

unbind()

Unbind the Framebuffer

Unbind should be called to prevent further rendering to the framebuffer, or if you wish to access data from its Texture atachments.

property height: The height of the tallest attachment.

property id: The Framebuffer id

property is_complete: bool: True if the framebuffer is ‘complete’, else False.

property width: The width of the widest attachment.

class Renderbuffer

OpenGL Renderbuffer Object

__init__(width, height, internal_format, samples=1)

bind()

delete()

static unbind()

property height

property id

property width

get_max_color_attachments(): Get the maximum allow Framebuffer Color attachements

Details

Image load, capture and high-level texture functions.

Only basic functionality is described here; for full reference see the accompanying documentation.

To load an image:

from pyglet import image
pic = image.load('picture.png')

The supported image file types include PNG, BMP, GIF, JPG, and many more, somewhat depending on the operating system. To load an image from a file-like object instead of a filename:

pic = image.load('hint.jpg', file=fileobj)

The hint helps the module locate an appropriate decoder to use based on the file extension. It is optional.

Once loaded, images can be used directly by most other modules of pyglet. All images have a width and height you can access:

width, height = pic.width, pic.height

You can extract a region of an image (this keeps the original image intact; the memory is shared efficiently):

subimage = pic.get_region(x, y, width, height)

Remember that y-coordinates are always increasing upwards.

Drawing images

To draw an image at some point on the screen:

pic.blit(x, y, z)

This assumes an appropriate view transform and projection have been applied.

Some images have an intrinsic “anchor point”: this is the point which will be aligned to the x and y coordinates when the image is drawn. By default the anchor point is the lower-left corner of the image. You can use the anchor point to center an image at a given point, for example:

pic.anchor_x = pic.width // 2
pic.anchor_y = pic.height // 2
pic.blit(x, y, z)

Texture access

If you are using OpenGL directly, you can access the image as a texture:

texture = pic.get_texture()

(This is the most efficient way to obtain a texture; some images are immediately loaded as textures, whereas others go through an intermediate form). To use a texture with pyglet.gl:

from pyglet.gl import *
glEnable(texture.target)        # typically target is GL_TEXTURE_2D
glBindTexture(texture.target, texture.id)
# ... draw with the texture

Pixel access

To access raw pixel data of an image:

rawimage = pic.get_image_data()

(If the image has just been loaded this will be a very quick operation; however if the image is a texture a relatively expensive readback operation will occur). The pixels can be accessed as a string:

format = 'RGBA'
pitch = rawimage.width * len(format)
pixels = rawimage.get_data(format, pitch)

“format” strings consist of characters that give the byte order of each color component. For example, if rawimage.format is ‘RGBA’, there are four color components: red, green, blue and alpha, in that order. Other common format strings are ‘RGB’, ‘LA’ (luminance, alpha) and ‘I’ (intensity).

The “pitch” of an image is the number of bytes in a row (this may validly be more than the number required to make up the width of the image, it is common to see this for word alignment). If “pitch” is negative the rows of the image are ordered from top to bottom, otherwise they are ordered from bottom to top.

Retrieving data with the format and pitch given in ImageData.format and ImageData.pitch avoids the need for data conversion (assuming you can make use of the data in this arbitrary format).

Classes

Images

class AbstractImage

Abstract class representing an image.

Parameters:

widthint: Width of image
heightint: Height of image
anchor_xint: X coordinate of anchor, relative to left edge of image data
anchor_yint: Y coordinate of anchor, relative to bottom edge of image data

__init__(width, height)

blit(x, y, z=0)

Draw this image to the active framebuffers.

The image will be drawn with the lower-left corner at (x - anchor_x, y - anchor_y, z).

blit_into(source, x, y, z)

Draw source on this image.

source will be copied into this image such that its anchor point is aligned with the x and y parameters. If this image is a 3D texture, the z coordinate gives the image slice to copy into.

Note that if source is larger than this image (or the positioning would cause the copy to go out of bounds) then you must pass a region of source to this method, typically using get_region().

blit_to_texture(target, level, x, y, z=0)

Draw this image on the currently bound texture at target.

This image is copied into the texture such that this image’s anchor point is aligned with the given x and y coordinates of the destination texture. If the currently bound texture is a 3D texture, the z coordinate gives the image slice to blit into.

get_image_data()

Get an ImageData view of this image.

Changes to the returned instance may or may not be reflected in this image.

Return type:: ImageData

New in version 1.1.

get_mipmapped_texture()

Retrieve a Texture instance with all mipmap levels filled in.

Return type:: Texture

New in version 1.1.

get_region(x, y, width, height)

Retrieve a rectangular region of this image.

Parameters:

xint: Left edge of region.
yint: Bottom edge of region.
widthint: Width of region.
heightint: Height of region.

Return type:

get_texture(rectangle=False)

A Texture view of this image.

Parameters:

rectanglebool: Unused. Kept for compatibility.

New in version 1.1.4..

Return type:

New in version 1.1.

save(filename=None, file=None, encoder=None)

Save this image to a file.

Parameters:

filenamestr: Used to set the image file format, and to open the output file if file is unspecified.
filefile-like object or None: File to write image data to.
encoderImageEncoder or None: If unspecified, all encoders matching the filename extension are tried. If all fail, the exception from the first one attempted is raised.

anchor_x = 0

anchor_y = 0

class BufferImage

Bases: AbstractImage

An abstract framebuffer.

__init__(x, y, width, height)

get_image_data()

Get an ImageData view of this image.

Changes to the returned instance may or may not be reflected in this image.

Return type:: ImageData

New in version 1.1.

get_region(x, y, width, height)

Retrieve a rectangular region of this image.

Parameters:

xint: Left edge of region.
yint: Bottom edge of region.
widthint: Width of region.
heightint: Height of region.

Return type:

format = '': The format string used for image data.

gl_buffer = 1029: The OpenGL read and write target for this buffer.

gl_format = 0: The OpenGL format constant for image data.

owner = None

class BufferImageMask

Bases: BufferImage

A single bit of the stencil buffer.

format = 'R': The format string used for image data.

gl_format = 6401: The OpenGL format constant for image data.

class ColorBufferImage

Bases: BufferImage

A color framebuffer.

This class is used to wrap the primary color buffer (i.e., the back buffer)

blit_to_texture(target, level, x, y, z)

Draw this image on the currently bound texture at target.

This image is copied into the texture such that this image’s anchor point is aligned with the given x and y coordinates of the destination texture. If the currently bound texture is a 3D texture, the z coordinate gives the image slice to blit into.

get_texture(rectangle=False)

A Texture view of this image.

Parameters:

rectanglebool: Unused. Kept for compatibility.

New in version 1.1.4..

Return type:

New in version 1.1.

format = 'RGBA': The format string used for image data.

gl_format = 6408: The OpenGL format constant for image data.

class DepthBufferImage

Bases: BufferImage

The depth buffer.

blit_to_texture(target, level, x, y, z)

Draw this image on the currently bound texture at target.

This image is copied into the texture such that this image’s anchor point is aligned with the given x and y coordinates of the destination texture. If the currently bound texture is a 3D texture, the z coordinate gives the image slice to blit into.

get_texture(rectangle=False)

A Texture view of this image.

Parameters:

rectanglebool: Unused. Kept for compatibility.

New in version 1.1.4..

Return type:

New in version 1.1.

format = 'R': The format string used for image data.

gl_format = 6402: The OpenGL format constant for image data.

class Texture

Bases: AbstractImage

An image loaded into video memory that can be efficiently drawn to the framebuffer.

Typically, you will get an instance of Texture by accessing the texture member of any other AbstractImage.

Parameters:

region_classclass (subclass of TextureRegion): Class to use when constructing regions of this texture.
tex_coordstuple: 12-tuple of float, named (u1, v1, r1, u2, v2, r2, …). u, v, r give the 3D texture coordinates for vertices 1-4. The vertices are specified in the order bottom-left, bottom-right, top-right and top-left.
targetint: The GL texture target (e.g., GL_TEXTURE_2D).
levelint: The mipmap level of this texture.

region_class: alias of TextureRegion

__init__(width, height, target, tex_id)

bind(texture_unit: int = 0): Bind to a specific Texture Unit by number.

bind_image_texture( unit, level=0, layered=False, layer=0, access=35002, fmt=34836, ): Bind as an ImageTexture for use with a ComputeShaderProgram.

Note

OpenGL 4.3, or 4.2 with the GL_ARB_compute_shader extention is required.

blit(x, y, z=0, width=None, height=None)

Draw this image to the active framebuffers.

The image will be drawn with the lower-left corner at (x - anchor_x, y - anchor_y, z).

blit_into(source, x, y, z)

Draw source on this image.

source will be copied into this image such that its anchor point is aligned with the x and y parameters. If this image is a 3D texture, the z coordinate gives the image slice to copy into.

Note that if source is larger than this image (or the positioning would cause the copy to go out of bounds) then you must pass a region of source to this method, typically using get_region().

classmethod create( width, height, target=3553, internalformat=32856, min_filter=None, mag_filter=None, fmt=6408, blank_data=True, )

Create a Texture

Create a Texture with the specified dimentions, target and format. On return, the texture will be bound.

Parameters:

widthint: Width of texture in pixels.
heightint: Height of texture in pixels.
targetint: GL constant giving texture target to use, typically GL_TEXTURE_2D.
internalformatint: GL constant giving internal format of texture; for example, GL_RGBA. The internal format decides how the texture data will be stored internally. If None, the texture will be created but not initialized.
min_filterint: The minifaction filter used for this texture, commonly GL_LINEAR or GL_NEAREST
mag_filterint: The magnification filter used for this texture, commonly GL_LINEAR or GL_NEAREST
fmtint: GL constant giving format of texture; for example, GL_RGBA. The format specifies what format the pixel data we’re expecting to write to the texture and should ideally be the same as for internal format.
blank_databool: Setting to True will initialize the texture data with all zeros. Setting False, will initialize Texture with no data.

Return type:

delete(): Delete this texture and the memory it occupies. After this, it may not be used anymore.

get_image_data(z=0)

Get the image data of this texture.

Changes to the returned instance will not be reflected in this texture.

Parameters:

zint: For 3D textures, the image slice to retrieve.

Return type:

ImageData

get_region(x, y, width, height)

Retrieve a rectangular region of this image.

Parameters:

xint: Left edge of region.
yint: Bottom edge of region.
widthint: Width of region.
heightint: Height of region.

Return type:

get_texture(rectangle=False)

A Texture view of this image.

Parameters:

rectanglebool: Unused. Kept for compatibility.

New in version 1.1.4..

Return type:

New in version 1.1.

get_transform(flip_x=False, flip_y=False, rotate=0)

Create a copy of this image applying a simple transformation.

The transformation is applied to the texture coordinates only; get_image_data() will return the untransformed data. The transformation is applied around the anchor point.

Parameters:

flip_xbool: If True, the returned image will be flipped horizontally.
flip_ybool: If True, the returned image will be flipped vertically.
rotateint: Degrees of clockwise rotation of the returned image. Only 90-degree increments are supported.

Return type:

TextureRegion

colors = (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)

default_mag_filter = 9729

default_min_filter = 9729

images = 1

level = 0

tex_coords = (0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0)

tex_coords_order = (0, 1, 2, 3)

property uv: Tuple containing the left, bottom, right, top 2D texture coordinates.

x = 0

y = 0

z = 0

class TextureRegion

Bases: Texture

A rectangular region of a texture, presented as if it were a separate texture.

__init__(x, y, z, width, height, owner)

blit_into(source, x, y, z)

Draw source on this image.

source will be copied into this image such that its anchor point is aligned with the x and y parameters. If this image is a 3D texture, the z coordinate gives the image slice to copy into.

Note that if source is larger than this image (or the positioning would cause the copy to go out of bounds) then you must pass a region of source to this method, typically using get_region().

delete(): Deleting a TextureRegion has no effect. Operate on the owning texture instead.

get_image_data()

Get the image data of this texture.

Changes to the returned instance will not be reflected in this texture.

Parameters:

zint: For 3D textures, the image slice to retrieve.

Return type:

ImageData

get_region(x, y, width, height)

Retrieve a rectangular region of this image.

Parameters:

xint: Left edge of region.
yint: Bottom edge of region.
widthint: Width of region.
heightint: Height of region.

Return type:

class TileableTexture

Bases: Texture

A texture that can be tiled efficiently.

Use create_for_image classmethod to construct.

blit_tiled(x, y, z, width, height)

Blit this texture tiled over the given area.

The image will be tiled with the bottom-left corner of the destination rectangle aligned with the anchor point of this texture.

classmethod create_for_image(image)

get_region(x, y, width, height)

Retrieve a rectangular region of this image.

Parameters:

xint: Left edge of region.
yint: Bottom edge of region.
widthint: Width of region.
heightint: Height of region.

Return type:

Image Sequences

class AbstractImageSequence

Abstract sequence of images.

The sequence is useful for storing image animations or slices of a volume. For efficient access, use the texture_sequence member. The class also implements the sequence interface (__len__, __getitem__, __setitem__).

get_animation(period, loop=True)

Create an animation over this image sequence for the given constant framerate.

:Parameters

periodfloat: Number of seconds to display each frame.
loopbool: If True, the animation will loop continuously.

Return type:: Animation

New in version 1.1.

get_texture_sequence()

Get a TextureSequence.

Return type:: TextureSequence

New in version 1.1.

class TextureSequence

Bases: AbstractImageSequence

Interface for a sequence of textures.

Typical implementations store multiple TextureRegion s within one Texture so as to minimise state changes.

get_texture_sequence()

Get a TextureSequence.

Return type:: TextureSequence

New in version 1.1.

class UniformTextureSequence

Bases: TextureSequence

Interface for a sequence of textures, each with the same dimensions.

Parameters:

item_widthint: Width of each texture in the sequence.
item_heightint: Height of each texture in the sequence.

property item_height

property item_width

class TextureGrid

Bases: TextureRegion, UniformTextureSequence

A texture containing a regular grid of texture regions.

To construct, create an ImageGrid first:

image_grid = ImageGrid(...)
texture_grid = TextureGrid(image_grid)

The texture grid can be accessed as a single texture, or as a sequence of TextureRegion. When accessing as a sequence, you can specify integer indexes, in which the images are arranged in rows from the bottom-left to the top-right:

# assume the texture_grid is 3x3:
current_texture = texture_grid[3] # get the middle-left image

You can also specify tuples in the sequence methods, which are addressed as row, column:

# equivalent to the previous example:
current_texture = texture_grid[1, 0]

When using tuples in a slice, the returned sequence is over the rectangular region defined by the slice:

# returns center, center-right, center-top, top-right images in that
# order:
images = texture_grid[(1,1):]
# equivalent to
images = texture_grid[(1,1):(3,3)]

__init__(grid)

get(row, column)

columns = 1

item_height = 0

item_width = 0

items = ()

rows = 1

class Texture3D

Bases: Texture, UniformTextureSequence

A texture with more than one image slice.

Use create_for_images or create_for_image_grid classmethod to construct.

classmethod create_for_image_grid(grid, internalformat=6408)

classmethod create_for_images(images, internalformat=6408, blank_data=True)

item_height = 0

item_width = 0

items = ()

Patterns

class ImagePattern

Abstract image creation class.

create_image(width, height)

Create an image of the given size.

Parameters:

widthint: Width of image to create
heightint: Height of image to create

Return type:

class CheckerImagePattern

Bases: ImagePattern

Create an image with a tileable checker image.

__init__( color1=(150, 150, 150, 255), color2=(200, 200, 200, 255), )

Initialise with the given colors.

Parameters:

color1(int, int, int, int): 4-tuple of ints in range [0,255] giving RGBA components of color to fill with. This color appears in the top-left and bottom-right corners of the image.
color2(int, int, int, int): 4-tuple of ints in range [0,255] giving RGBA components of color to fill with. This color appears in the top-right and bottom-left corners of the image.

create_image(width, height)

Create an image of the given size.

Parameters:

widthint: Width of image to create
heightint: Height of image to create

Return type:

class SolidColorImagePattern

Bases: ImagePattern

Creates an image filled with a solid color.

__init__(color=(0, 0, 0, 0))

Create a solid image pattern with the given color.

Parameters:

color(int, int, int, int): 4-tuple of ints in range [0,255] giving RGBA components of color to fill with.

create_image(width, height)

Create an image of the given size.

Parameters:

widthint: Width of image to create
heightint: Height of image to create

Return type:

Data

class ImageData

Bases: AbstractImage

An image represented as a string of unsigned bytes.

Parameters:

datastr: Pixel data, encoded according to format and pitch.
formatstr: The format string to use when reading or writing data.
pitchint: Number of bytes per row. Negative values indicate a top-to-bottom arrangement.

__init__(width, height, fmt, data, pitch=None)

Initialise image data.

Parameters:

widthint: Width of image data
heightint: Height of image data
fmtstr: A valid format string, such as ‘RGB’, ‘RGBA’, ‘ARGB’, etc.
datasequence: String or array/list of bytes giving the decoded data.
pitchint or None: If specified, the number of bytes per row. Negative values indicate a top-to-bottom arrangement. Defaults to width * len(format).

blit(x, y, z=0, width=None, height=None)

Draw this image to the active framebuffers.

The image will be drawn with the lower-left corner at (x - anchor_x, y - anchor_y, z).

blit_to_texture(target, level, x, y, z, internalformat=None)

Draw this image to to the currently bound texture at target.

This image’s anchor point will be aligned to the given x and y coordinates. If the currently bound texture is a 3D texture, the z parameter gives the image slice to blit into.

If internalformat is specified, glTexImage is used to initialise the texture; otherwise, glTexSubImage is used to update a region.

create_texture(cls, rectangle=False)

Create a texture containing this image.

Parameters:

clsclass (subclass of Texture): Class to construct.
rectanglebool: Unused. kept for compatibility.

New in version 1.1.

Return type:

cls or cls.region_class

get_data(fmt=None, pitch=None)

Get the byte data of the image.

Parameters:

fmtstr: Format string of the return data.
pitchint: Number of bytes per row. Negative values indicate a top-to-bottom arrangement.

New in version 1.1.

Return type:: sequence of bytes, or str

get_image_data()

Get an ImageData view of this image.

Changes to the returned instance may or may not be reflected in this image.

Return type:: ImageData

New in version 1.1.

get_mipmapped_texture()

Return a Texture with mipmaps.

If set_mipmap_Image has been called with at least one image, the set of images defined will be used. Otherwise, mipmaps will be automatically generated.

Return type:: Texture

New in version 1.1.

get_region(x, y, width, height)

Retrieve a rectangular region of this image data.

Parameters:

xint: Left edge of region.
yint: Bottom edge of region.
widthint: Width of region.
heightint: Height of region.

Return type:

ImageDataRegion

get_texture(rectangle=False)

A Texture view of this image.

Parameters:

rectanglebool: Unused. Kept for compatibility.

New in version 1.1.4..

Return type:

New in version 1.1.

set_data(fmt, pitch, data)

Set the byte data of the image.

Parameters:

fmtstr: Format string of the return data.
pitchint: Number of bytes per row. Negative values indicate a top-to-bottom arrangement.
datastr or sequence of bytes: Image data.

New in version 1.1.

set_mipmap_image(level, image)

Set a mipmap image for a particular level.

The mipmap image will be applied to textures obtained via get_mipmapped_texture.

Parameters:

levelint: Mipmap level to set image at, must be >= 1.
imageAbstractImage: Image to set. Must have correct dimensions for that mipmap level (i.e., width >> level, height >> level)

property format

Format string of the data. Read-write.

Type:: str

class CompressedImageData

Bases: AbstractImage

Image representing some compressed data suitable for direct uploading to driver.

__init__( width, height, gl_format, data, extension=None, decoder=None, )

Construct a CompressedImageData with the given compressed data.

Parameters:

widthint: Width of image
heightint: Height of image
gl_formatint: GL constant giving format of compressed data; for example, GL_COMPRESSED_RGBA_S3TC_DXT5_EXT.
datasequence: String or array/list of bytes giving compressed image data.
extensionstr or None: If specified, gives the name of a GL extension to check for before creating a texture.
decoderfunction(data, width, height) -> AbstractImage: A function to decode the compressed data, to be used if the required extension is not present.

blit_to_texture(target, level, x, y, z)

Draw this image on the currently bound texture at target.

This image is copied into the texture such that this image’s anchor point is aligned with the given x and y coordinates of the destination texture. If the currently bound texture is a 3D texture, the z coordinate gives the image slice to blit into.

get_mipmapped_texture()

Retrieve a Texture instance with all mipmap levels filled in.

Return type:: Texture

New in version 1.1.

get_texture(rectangle=False)

A Texture view of this image.

Parameters:

rectanglebool: Unused. Kept for compatibility.

New in version 1.1.4..

Return type:

New in version 1.1.

set_mipmap_data(level, data)

Set data for a mipmap level.

Supplied data gives a compressed image for the given mipmap level. The image must be of the correct dimensions for the level (i.e., width >> level, height >> level); but this is not checked. If any mipmap levels are specified, they are used; otherwise, mipmaps for mipmapped_texture are generated automatically.

Parameters:

levelint: Level of mipmap image to set.
datasequence: String or array/list of bytes giving compressed image data. Data must be in same format as specified in constructor.

class ImageDataRegion

Bases: ImageData

__init__(x, y, width, height, image_data)

Initialise image data.

Parameters:

widthint: Width of image data
heightint: Height of image data
fmtstr: A valid format string, such as ‘RGB’, ‘RGBA’, ‘ARGB’, etc.
datasequence: String or array/list of bytes giving the decoded data.
pitchint or None: If specified, the number of bytes per row. Negative values indicate a top-to-bottom arrangement. Defaults to width * len(format).

get_data(fmt=None, pitch=None)

Get the byte data of the image.

Parameters:

fmtstr: Format string of the return data.
pitchint: Number of bytes per row. Negative values indicate a top-to-bottom arrangement.

New in version 1.1.

Return type:: sequence of bytes, or str

get_region(x, y, width, height)

Retrieve a rectangular region of this image data.

Parameters:

xint: Left edge of region.
yint: Bottom edge of region.
widthint: Width of region.
heightint: Height of region.

Return type:

ImageDataRegion

set_data(fmt, pitch, data)

Set the byte data of the image.

Parameters:

fmtstr: Format string of the return data.
pitchint: Number of bytes per row. Negative values indicate a top-to-bottom arrangement.
datastr or sequence of bytes: Image data.

New in version 1.1.

Other Classes

class BufferManager

Manages the set of framebuffers for a context.

Use get_buffer_manager() to obtain the instance of this class for the current context.

__init__()

get_buffer_mask()

Get a free bitmask buffer.

A bitmask buffer is a buffer referencing a single bit in the stencil buffer. If no bits are free, ImageException is raised. Bits are released when the bitmask buffer is garbage collected.

Return type:: BufferImageMask

get_color_buffer()

Get the color buffer.

Return type:: ColorBufferImage

get_depth_buffer()

Get the depth buffer.

Return type:: DepthBufferImage

static get_viewport()

Get the current OpenGL viewport dimensions.

Return type:: 4-tuple of float.
Returns:: Left, top, right and bottom dimensions.

class ImageGrid

Bases: AbstractImage, AbstractImageSequence

An imaginary grid placed over an image allowing easy access to regular regions of that image.

The grid can be accessed either as a complete image, or as a sequence of images. The most useful applications are to access the grid as a TextureGrid:

image_grid = ImageGrid(...)
texture_grid = image_grid.get_texture_sequence()

or as a Texture3D:

image_grid = ImageGrid(...)
texture_3d = Texture3D.create_for_image_grid(image_grid)

__init__( image, rows, columns, item_width=None, item_height=None, row_padding=0, column_padding=0, )

Construct a grid for the given image.

You can specify parameters for the grid, for example setting the padding between cells. Grids are always aligned to the bottom-left corner of the image.

Parameters:

imageAbstractImage: Image over which to construct the grid.
rowsint: Number of rows in the grid.
columnsint: Number of columns in the grid.
item_widthint: Width of each column. If unspecified, is calculated such that the entire image width is used.
item_heightint: Height of each row. If unspecified, is calculated such that the entire image height is used.
row_paddingint: Pixels separating adjacent rows. The padding is only inserted between rows, not at the edges of the grid.
column_paddingint: Pixels separating adjacent columns. The padding is only inserted between columns, not at the edges of the grid.

get_image_data()

Get an ImageData view of this image.

Changes to the returned instance may or may not be reflected in this image.

Return type:: ImageData

New in version 1.1.

get_texture(rectangle=False)

A Texture view of this image.

Parameters:

rectanglebool: Unused. Kept for compatibility.

New in version 1.1.4..

Return type:

New in version 1.1.

get_texture_sequence()

Get a TextureSequence.

Return type:: TextureSequence

New in version 1.1.

Functions

create(width, height, pattern=None)

Create an image optionally filled with the given pattern.

Parameters:

widthint: Width of image to create
heightint: Height of image to create
patternImagePattern or None: Pattern to fill image with. If unspecified, the image will initially be transparent.

Return type:

Note

You can make no assumptions about the return type; usually it will be ImageData or CompressedImageData, but patterns are free to return any subclass of AbstractImage.

get_buffer_manager()

Get the buffer manager for the current OpenGL context.

Return type:: BufferManager

load(filename, file=None, decoder=None)

Load an image from a file.

Parameters:

filenamestr: Used to guess the image format, and to load the file if file is unspecified.
filefile-like object or None: Source of image data in any supported format.
decoderImageDecoder or None: If unspecified, all decoders that are registered for the filename extension are tried. If none succeed, the exception from the first decoder is raised.

Return type:

Note

You can make no assumptions about the return type; usually it will be ImageData or CompressedImageData, but decoders are free to return any subclass of AbstractImage.

load_animation(filename, file=None, decoder=None)

Load an animation from a file.

Currently, the only supported format is GIF.

Parameters:

filenamestr: Used to guess the animation format, and to load the file if file is unspecified.
filefile-like object or None: File object containing the animation stream.
decoderImageDecoder or None: If unspecified, all decoders that are registered for the filename extension are tried. If none succeed, the exception from the first decoder is raised.

Return type:

Animation

get_max_texture_size(): Query the maximum texture size available

Exceptions

class ImageException

__init__(*args, **kwargs)

__new__(**kwargs)

class ImageEncodeException

__init__(*args, **kwargs)

__new__(**kwargs)

class ImageDecodeException

__init__(*args, **kwargs)

__new__(**kwargs)

pyglet.info

Get environment information useful for debugging.

Intended usage is to create a file for bug reports, e.g.:

python -m pyglet.info > info.txt

dump(): Dump all information to stdout.

dump_al(): Dump OpenAL info.

dump_ffmpeg(): Dump FFmpeg info.

dump_gl(context=None): Dump GL info.

dump_glx(): Dump GLX info.

dump_media(): Dump pyglet.media info.

dump_platform(): Dump OS specific

dump_pyglet(): Dump pyglet version and options.

dump_python(): Dump Python version and environment to stdout.

dump_window(): Dump display, window, screen and default config info.

dump_wintab(): Dump WinTab info.

pyglet.input

Joystick, Game Controller, Tablet and USB HID device support.

This module provides a unified interface to almost any input device, besides the regular mouse and keyboard support provided by Window. At the lowest level, get_devices() can be used to retrieve a list of all supported devices, including joysticks, tablets, game controllers, wheels, pedals, remote controls, keyboards and mice. The set of returned devices varies greatly depending on the operating system (and, of course, what’s plugged in).

At this level pyglet does not try to interpret what a particular device is, merely what controls it provides. A Control can be either a button, whose value is either True or False, or a relative or absolute-valued axis, whose value is a float. Sometimes the name of a control can be provided (for example, x, representing the horizontal axis of a joystick), but often not. In these cases the device API may still be useful – the user will have to be asked to press each button in turn or move each axis separately to identify them.

Higher-level interfaces are provided for joysticks, game controllers, tablets and the Apple remote control. These devices can usually be identified by pyglet positively, and a base level of functionality for each one provided through a common interface.

To use an input device:

Call get_devices(), get_apple_remote(), get_controllers() or get_joysticks() to retrieve and identify the device.
For low-level devices (retrieved by get_devices()), query the devices list of controls and determine which ones you are interested in. For high-level interfaces the set of controls is provided by the interface.
Optionally attach event handlers to controls on the device. For high-level interfaces, additional events are available.
Call Device.open() to begin receiving events on the device. You can begin querying the control values after this time; they will be updated asynchronously.
Call Device.close() when you are finished with the device (not needed if your application quits at this time).

To use a tablet, follow the procedure above using get_tablets(), but note that no control list is available; instead, calling Tablet.open() returns a TabletCanvas onto which you should set your event handlers.

For game controllers, the ControllerManager is available. This provides a convenient way to handle hot-plugging of controllers.

New in version 1.2.

Classes

class ControllerManager

High level interface for managing game Controllers.

This class provides a convenient way to handle the connection and disconnection of devices. A list of all connected Controllers can be queried at any time with the get_controllers method. For hot-plugging, events are dispatched for on_connect and on_disconnect. To use the ControllerManager, first make an instance:

controller_man = pyglet.input.ControllerManager()

At the start of your game, query for any Controllers that are already connected:

controllers = controller_man.get_controllers()

To handle Controllers that are connected or disconnected after the start of your game, register handlers for the appropriate events:

@controller_man.event
def on_connect(controller):
    # code to handle newly connected
    # (or re-connected) controllers
    controller.open()
    print("Connect:", controller)

@controller_man.event
def on_disconnect(controller):
    # code to handle disconnected Controller
    print("Disconnect:", controller)

New in version 2.0.

Methods

get_controllers() → list[pyglet.input.base.Controller]

Get a list of all connected Controllers

Return type:: list[Controller]

Events

on_connect(controller) → Controller

A Controller has been connected. If this is a previously dissconnected Controller that is being re-connected, the same Controller instance will be returned.

Return type:: Controller

on_disconnect(controller) → Controller

A Controller has been disconnected.

Return type:: Controller

__init__()

__new__(**kwargs)

class Device

Bases: object

Low level input device.

__init__(display: Display, name: str) → None

Create a Device to receive input from.

Parameters:

display (Display) – The Display this device is connected to.
name (str) – The name of the device, as described by the device firmware.

close() → None

Close the device.

Return type:: None

get_controls() → list[pyglet.input.base.Control]

Get a list of controls provided by the device.

Return type:: list[Control]

get_guid() → str

Get the device GUID, in SDL2 format.

Return a str containing a unique device identification string. This is generated from the hardware identifiers, and is in the same format as was popularized by SDL2. GUIDs differ between platforms, but are generally 32 hexidecimal characters.

Return type:: str

open( window: None | Window = None, exclusive: bool = False, ) → None

Open the device to begin receiving input from it.

Parameters:

window (None | Window) – Optional window to associate with the device. The behaviour of this parameter is device and operating system dependant. It can usually be omitted for most devices.
exclusive (bool) – If True the device will be opened exclusively so that no other application can use it.

Raises:

DeviceOpenException – If the device cannot be opened in exclusive mode, usually due to being opened exclusively by another application.

Return type:

property is_open: bool

manufacturer: str | None: The manufacturer name, if available

class Control

Single value input provided by a device.

A control’s value can be queried when the device is open. Event handlers can be attached to the control to be called when the value changes.

The min and max properties are provided as advertised by the device; in some cases the control’s value will be outside this range.

Events

on_change(value) → float

The value changed.

Return type:: float

Attributes

value

Current value of the control.

The range of the value is device-dependent; for absolute controls the range is given by min and max (however the value may exceed this range); for relative controls the range is undefined.

__init__( name: None | str, raw_name: None | str = None, inverted: bool = False, )

Create a Control to receive input.

Parameters:

name (None | str) – The name of the control, or None if unknown.
raw_name (None | str) – Optional unmodified name of the control, as presented by the operating system; or None if unknown.
inverted (bool) – If True, the value reported is actually inverted from what the device reported; usually this is to provide consistency across operating systems.

__new__(**kwargs)

class RelativeAxis

Bases: Control

An axis whose value represents a relative change from the previous value.

This type of axis is used for controls that can scroll or move continuously, such as a scrolling or pointing input. The value is read as a delta change from the previous value.

RX: str = 'rx'

RY: str = 'ry'

RZ: str = 'rz'

WHEEL: str = 'wheel'

X: str = 'x'

Y: str = 'y'

Z: str = 'z'

property value: float

Current value of the control.

The range of the value is device-dependent; for absolute controls the range is given by min and max (however the value may exceed this range); for relative controls the range is undefined.

class AbsoluteAxis

Bases: Control

An axis whose value represents the current measurement from the device.

This type of axis is used for controls that have minimum and maximum positions. The value is a range between the min and max.

__init__( name: str, minimum: float, maximum: float, raw_name: None | str = None, inverted: bool = False, )

Create a Control to receive input.

Parameters:

name (str) – The name of the control, or None if unknown.
raw_name (None | str) – Optional unmodified name of the control, as presented by the operating system; or None if unknown.
inverted (bool) – If True, the value reported is actually inverted from what the device reported; usually this is to provide consistency across operating systems.

HAT: str = 'hat'

HAT_X: str = 'hat_x'

HAT_Y: str = 'hat_y'

RX: str = 'rx'

RY: str = 'ry'

RZ: str = 'rz'

X: str = 'x'

Y: str = 'y'

Z: str = 'z'

class Button

Bases: Control

A control whose value is boolean.

Events

on_press(): The button was pressed.

on_release(): The button was released.

Attributes

value

__init__( name: None | str, raw_name: None | str = None, inverted: bool = False, )

Create a Control to receive input.

Parameters:

name (None | str) – The name of the control, or None if unknown.
raw_name (None | str) – Optional unmodified name of the control, as presented by the operating system; or None if unknown.
inverted (bool) – If True, the value reported is actually inverted from what the device reported; usually this is to provide consistency across operating systems.

__new__(**kwargs)

class Controller

High-level interface for Game Controllers.

Unlike Joysticks, Controllers have a strictly defined set of inputs that matches the layout of popular home video game console Controllers. This includes a variety of face and shoulder buttons, analog sticks and triggers, a directional pad, and optional rumble (force feedback) effects.

To use a Controller, you must first call open. Controllers will then dispatch various events whenever the inputs change. They can also be polled manually at any time to find the current value of any inputs. Analog stick inputs are normalized to the range [-1.0, 1.0], and triggers are normalized to the range [0.0, 1.0]. All other inputs are digital.

Note: A running application event loop is required

The following event types are dispatched:: on_button_press on_button_release on_stick_motion on_dpad_motion on_trigger_motion

Methods

open( window: None | Window = None, exclusive: bool = False, ) → None

Open the controller. See Device.open.

Return type:: None

close() → None

Close the controller. See Device.close.

Return type:: None

Events

on_stick_motion( controller: Controller, stick: str, vector: Vec2, )

The value of a controller analogue stick changed.

Parameters:

controller (Controller) – The controller whose analogue stick changed.
stick (str) – The name of the stick that changed.
vector (Vec2) – A 2D vector representing the stick position. Each individual axis will be normalized from [-1, 1],

on_dpad_motion( controller: Controller, vector: Vec2, )

The direction pad of the controller changed.

Parameters:

controller (Controller) – The controller whose hat control changed.
vector (Vec2) – A 2D vector, representing the dpad position. Each individual axis will be one of [-1, 0, 1].

on_trigger_motion( controller: Controller, trigger: str, value: float, )

The value of a controller analogue stick changed.

Parameters:

controller (Controller) – The controller whose analogue stick changed.
trigger (str) – The name of the trigger that changed.
value (float) – The current value of the trigger, normalized to [0, 1].

on_button_press(controller: Controller, button: str)

A button on the controller was pressed.

Parameters:

controller (Controller) – The controller whose button was pressed.
button (str) – The name of the button that was pressed.

on_button_release(controller: Controller, button: str)

A button on the joystick was released.

Parameters:

controller (Controller) – The controller whose button was released.
button (str) – The name of the button that was released.

type

The type, or family, of the Controller

This property uses a simple heuristic query to attempt to determine which general family the controller falls into. For example, the controller may have Ⓐ,Ⓑ,Ⓧ,Ⓨ, or ✕,○,□,△ labels on the face buttons. Using this information, you can choose to display matching button prompt images in your game. For example:

if controller.type == 'PS':
    a_glyph = 'ps_cross_button.png'
    b_glyph = 'ps_circle_button.png'
    ...
elif controller.type == 'XB':
    a_glyph = 'ms_a_button.png'
    b_glyph = 'ms_b_button.png'
    ...
else:
    ...

Returns:: A string, currently one of “PS”, “XB”, or “GENERIC”.

__init__(device: Device, mapping: dict): Create a Controller instace mapped to a Device.

New in version 2.0.

__new__(**kwargs)

class Joystick

High-level interface for joystick-like devices. This includes a wide range of analog and digital joysticks, gamepads, controllers, and possibly even steering wheels and other input devices. There is unfortunately no easy way to distinguish between most of these different device types.

For a simplified subset of Joysticks, see the Controller interface. This covers a variety of popular game console controllers. Unlike Joysticks, Controllers have strictly defined layouts and inputs.

To use a joystick, first call open, then in your game loop examine the values of x, y, and so on. These values are normalized to the range [-1.0, 1.0].

To receive events when the value of an axis changes, attach an on_joyaxis_motion event handler to the joystick. The Joystick instance, axis name, and current value are passed as parameters to this event.

To handle button events, you should attach on_joybutton_press and on_joy_button_release event handlers to the joystick. Both the Joystick instance and the index of the changed button are passed as parameters to these events.

Alternately, you may attach event handlers to each individual button in button_controls to receive on_press or on_release events.

To use the hat switch, attach an on_joyhat_motion event handler to the joystick. The handler will be called with both the hat_x and hat_y values whenever the value of the hat switch changes.

The device name can be queried to get the name of the joystick.

Methods

open(window: None | Window, exclusive: bool = False) → None

Open the joystick device. See Device.open.

Return type:: None

close() → None

Close the joystick device. See Device.close.

Return type:: None

Events

on_joyaxis_motion( joystick: Joystick, axis: str, value: float, )

The value of a joystick axis changed.

Parameters:

joystick (Joystick) – The joystick device whose axis changed.
axis (str) – The name of the axis that changed.
value (float) – The current value of the axis, normalized to [-1, 1].

on_joyhat_motion( joystick: Joystick, hat_x: float, hat_y: float, )

The value of the joystick hat switch changed.

Parameters:

joystick (Joystick) – The joystick device whose hat control changed.
hat_x (float) – Current hat (POV) horizontal position; one of -1.0 (left), 0.0 (centered) or 1.0 (right).
hat_y (float) – Current hat (POV) vertical position; one of -1.0 (bottom), 0.0 (centered) or 1.0 (top).

on_joybutton_press(joystick: Joystick, button: int)

A button on the joystick was pressed.

Parameters:

joystick (Joystick) – The joystick device whose button was pressed.
button (int) – The index (in button_controls) of the button that was pressed.

on_joybutton_release(joystick: Joystick, button: int)

A button on the joystick was released.

Parameters:

joystick (Joystick) – The joystick device whose button was released.
button (int) – The index (in button_controls) of the button that was released.

__init__(device)

__new__(**kwargs)

class AppleRemote

High-level interface for Apple remote control.

This interface provides access to the 6 button controls on the remote. Pressing and holding certain buttons on the remote is interpreted as a separate control.

Methods

open(window: Window, exclusive: bool = False): Open the device. See Device.open.

close(): Close the device. See Device.close.

Events

on_button_press(button: str)

A button on the remote was pressed.

Only the ‘up’ and ‘down’ buttons will generate an event when the button is first pressed. All other buttons on the remote will wait until the button is released and then send both the press and release events at the same time.

Parameters:: button (str) – The name of the button that was pressed. The valid names are ‘up’, ‘down’, ‘left’, ‘right’, ‘left_hold’, ‘right_hold’, ‘menu’, ‘menu_hold’, ‘select’, and ‘select_hold’

on_button_release(button: str)

A button on the remote was released.

The ‘select_hold’ and ‘menu_hold’ button release events are sent immediately after the corresponding press events regardless of whether the user has released the button.

Parameters:: button (str) – The name of the button that was released. The valid names are ‘up’, ‘down’, ‘left’, ‘right’, ‘left_hold’, ‘right_hold’, ‘menu’, ‘menu_hold’, ‘select’, and ‘select_hold’

__init__(device)

__new__(**kwargs)

class Tablet

High-level interface to tablet devices.

Unlike other devices, tablets must be opened for a specific window, and cannot be opened exclusively. The open method returns a TabletCanvas object, which supports the events provided by the tablet.

Currently only one tablet device can be used, though it can be opened on multiple windows. If more than one tablet is connected, the behaviour is undefined.

__init__()

__new__(**kwargs)

Functions

get_apple_remote(display: None | Display = None) → AppleRemote | None

Get the Apple remote control device, if it exists.

The Apple remote is the small white 6-button remote control that accompanies most recent Apple desktops and laptops. The remote can only be used with Mac OS X.

Parameters:: display (None | Display) – Currently ignored.
Return type:: AppleRemote | None

get_devices(display: None | Display = None) → list[Device]

Get a list of all attached input devices.

Parameters:: display (None | Display) – The display device to query for input devices. Ignored on Mac OS X and Windows. On Linux, defaults to the default display device.
Return type:: list[Device]

get_controllers(display: None | Display = None) → list[Controller]

Get a list of attached controllers.

Parameters:: display (None | Display) – The display device to query for input devices. Ignored on Mac OS X and Windows. On Linux, defaults to the default display device.
Return type:: list[Controller]

get_joysticks(display: None | Display = None) → list[Joystick]

Get a list of attached joysticks.

Parameters:: display (None | Display) – The display device to query for input devices. Ignored on Mac OS X and Windows. On Linux, defaults to the default display device.
Return type:: list[Joystick]

get_tablets(display: None | Display = None) → list[Tablet]

Get a list of tablets.

This function may return a valid tablet device even if one is not attached (for example, it is not possible on Mac OS X to determine if a tablet device is connected). Despite returning a list of tablets, pyglet does not currently support multiple tablets, and the behaviour is undefined if more than one is attached.

Parameters:: display (None | Display) – The display device to query for input devices. Ignored on Mac OS X and Windows. On Linux, defaults to the default display device.
Return type:: list[Tablet]

Exceptions

class DeviceException

class DeviceOpenException

class DeviceExclusiveException

pyglet.math

Matrix and Vector math.

This module provides Vector and Matrix objects, including Vec2, Vec3, Vec4, Mat3, and Mat4. Most common matrix and vector operations are supported. Helper methods are included for rotating, scaling, and transforming. The Mat4 includes class methods for creating orthographic and perspective projection matrixes.

Matrices behave just like they do in GLSL: they are specified in column-major order and multiply on the left of vectors, which are treated as columns.

All objects are immutable and hashable.

class Mat3

A 3x3 Matrix

Mat3 is an immutable 3x3 Matrix, wich includes most common operators.

A Matrix can be created with a list or tuple of 12 values. If no values are provided, an “identity matrix” will be created (1.0 on the main diagonal). Because Mat3 objects are immutable, all operations return a new Mat3 object.

Note

Matrix multiplication is performed using the “@” operator.

static __new__( cls: type[Mat3T], values: Iterable[float] = (1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0), ) → Mat3T

Return type:: TypeVar (Mat3T, bound = Mat3)

rotate(phi: float) → Mat3

Return type:: Mat3

scale(sx: float, sy: float) → Mat3

Return type:: Mat3

shear(sx: float, sy: float) → Mat3

Return type:: Mat3

translate(tx: float, ty: float) → Mat3

Return type:: Mat3

class Mat4

A 4x4 Matrix

Mat4 is an immutable 4x4 Matrix, which includs most common operators. This includes class methods for creating orthogonal and perspective projection matrixes, which can be used directly by OpenGL.

A Matrix can be created with a list or tuple of 16 values. If no values are provided, an “identity matrix” will be created (1.0 on the main diagonal). Mat4 objects are immutable, so all operations return a new Mat4 object.

Note

Matrix multiplication is performed using the “@” operator.

static __new__( cls: type[Mat4T], values: Iterable[float] = (1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0), ) → Mat4T

Return type:: TypeVar (Mat4T, bound = Mat4)

column(index: int) → tuple

Get a specific column as a tuple.

Return type:: tuple

classmethod from_rotation(angle: float, vector: Vec3) → Mat4

Create a rotation matrix from an angle and Vec3.

Parameters:

angle (float) – The desired angle, in radians.
vector (Vec3) – A Vec3 indicating the direction.

Return type:

Mat4

classmethod from_scale(vector: Vec3) → Mat4T

Create a scale matrix from a Vec3.

Return type:: TypeVar (Mat4T, bound = Mat4)

classmethod from_translation(vector: Vec3) → Mat4T

Create a translation matrix from a Vec3.

Return type:: TypeVar (Mat4T, bound = Mat4)

classmethod look_at( position: Vec3, target: Vec3, up: Vec3, )

Create a viewing matrix that points toward a target.

This method takes three Vec3s, describing the viewer’s position, where they are looking, and the upward axis (typically positive on the Y axis). The resulting Mat4 can be used as the projection matrix.

Parameters:

position (Vec3) – The location of the viewer in the scene.
target (Vec3) – The point that the viewer is looking towards.
up (Vec3) – A vector pointing “up” in the scene, typically Vec3(0.0, 1.0, 0.0).

classmethod orthogonal_projection( left: float, right: float, bottom: float, top: float, z_near: float, z_far: float, ) → Mat4T

Create a Mat4 orthographic projection matrix for use with OpenGL.

Given left, right, bottom, top values, and near/far z planes, create a 4x4 Projection Matrix. This is useful for setting projection.

Return type:: TypeVar (Mat4T, bound = Mat4)

classmethod perspective_projection( aspect: float, z_near: float, z_far: float, fov: float = 60, ) → Mat4T

Create a Mat4 perspective projection matrix for use with OpenGL.

Given a desired aspect ratio, near/far planes, and fov (field of view), create a 4x4 Projection Matrix. This is useful for setting projection.

Return type:: TypeVar (Mat4T, bound = Mat4)

rotate(angle: float, vector: Vec3) → Mat4

Get a rotation Matrix on x, y, or z axis.

Return type:: Mat4

row(index: int) → tuple

Get a specific row as a tuple.

Return type:: tuple

scale(vector: Vec3) → Mat4

Get a scale Matrix on x, y, or z axis.

Return type:: Mat4

translate(vector: Vec3) → Mat4

Get a translation Matrix along x, y, and z axis.

Return type:: Mat4

transpose() → Mat4

Get a transpose of this Matrix.

Return type:: Mat4

class Quaternion

Quaternion

conjugate() → Quaternion

Return type:: Quaternion

dot(other: Quaternion) → float

Return type:: float

classmethod from_mat3() → Quaternion

Return type:: Quaternion

classmethod from_mat4() → Quaternion

Return type:: Quaternion

normalize() → Quaternion

Return type:: Quaternion

to_mat3() → Mat3

Return type:: Mat3

to_mat4() → Mat4

Return type:: Mat4

property mag: float

The magnitude, or length, of the Quaternion.

The distance between the coordinates and the origin. Alias of abs(quaternion_instance).

w: float: Alias for field number 0

x: float: Alias for field number 1

y: float: Alias for field number 2

z: float: Alias for field number 3

class Vec2

A two-dimensional vector represented as an X Y coordinate pair.

Vec2 is an immutable 2D Vector, including most common operators. As an immutable type, all operations return a new object.

Note

The Python len operator returns the number of elements in the vector. For the vector length, use the abs operator.

clamp(min_val: float, max_val: float) → Vec2

Restrict the value of the X and Y components of the vector to be within the given values.

Return type:: Vec2

distance(other: Vec2) → float

Calculate the distance between this vector and another 2D vector.

Return type:: float

dot(other: Vec2) → float

Calculate the dot product of this vector and another 2D vector.

Return type:: float

from_heading(heading: float) → Vec2

Create a new vector of the same magnitude with the given heading.

In effect, the vector rotated to the new heading.

Parameters:: heading (float) – The desired heading, in radians.
Return type:: Vec2

from_magnitude(magnitude: float) → Vec2

Create a new vector of the given magnitude

The new vector will be created by first normalizing, then scaling the vector. The heading remains unchanged.

Return type:: Vec2

static from_polar(mag: float, angle: float) → Vec2

Create a new vector from the given polar coordinates.

Parameters:

mag (float) – The desired magnitude.
angle (float) – The angle, in radians.

Return type:

Vec2

index(*args)

Return first index of value.

Raises ValueError if the value is not present.

lerp(other: Vec2, alpha: float) → Vec2

Create a new Vec2 linearly interpolated between this vector and another Vec2.

Parameters:

other (Vec2) – Another Vec2 instance.
alpha (float) – The amount of interpolation between this vector, and the other vector. This should be a value between 0.0 and 1.0. For example: 0.5 is the midway point between both vectors.

Return type:

Vec2

limit(maximum: float) → Vec2

Limit the magnitude of the vector to passed maximum value.

Return type:: Vec2

normalize() → Vec2

Normalize the vector to have a magnitude of 1. i.e. make it a unit vector.

Return type:: Vec2

reflect(vector: Vec2) → Vec2

Create a new Vec2 reflected (ricochet) from the given normalized vector.

Parameters:: vector (Vec2) – A normalized vector.
Return type:: Vec2

rotate(angle: float) → Vec2

Create a new vector rotated by the angle. The magnitude remains unchanged.

Parameters:: angle (float) – The desired angle, in radians.
Return type:: Vec2

property heading: float: The angle of the vector in radians.

property mag: float

The magnitude, or length of the vector.

The distance between the coordinates and the origin. Alias of abs(vec2_instance).

x: float: Alias for field number 0

y: float: Alias for field number 1

class Vec3

A three-dimensional vector represented as X Y Z coordinates.

Vec3 is an immutable 2D Vector, including most common operators. As an immutable type, all operations return a new object.

Note

The Python len operator returns the number of elements in the vector. For the vector length, use the abs operator.

clamp(min_val: float, max_val: float) → Vec3

Restrict the value of the X, Y and Z components of the vector to be within the given values.

Return type:: Vec3

cross(other: Vec3) → Vec3

Calculate the cross product of this vector and another 3D vector.

Return type:: Vec3

distance(other: Vec3) → float

Get the distance between this vector and another 3D vector.

Return type:: float

dot(other: Vec3) → float

Calculate the dot product of this vector and another 3D vector.

Return type:: float

from_magnitude(magnitude: float) → Vec3

Create a new vector of the given magnitude

The new vector will be created by first normalizing, then scaling the vector. The heading remains unchanged.

Return type:: Vec3

index(*args)

Return first index of value.

Raises ValueError if the value is not present.

lerp(other: Vec3, alpha: float) → Vec3

Create a new Vec3 linearly interpolated between this vector and another Vec3.

Parameters:

other (Vec3) – Another Vec3 instance.
alpha (float) – The amount of interpolation between this vector, and the other vector. This should be a value between 0.0 and 1.0. For example: 0.5 is the midway point between both vectors.

Return type:

Vec3

limit(maximum: float) → Vec3

Limit the magnitude of the vector to passed maximum value.

Return type:: Vec3

normalize() → Vec3

Normalize the vector to have a magnitude of 1. i.e. make it a unit vector.

Return type:: Vec3

property mag: float

The magnitude, or length of the vector.

The distance between the coordinates and the origin. Alias of abs(vector_instance).

x: float: Alias for field number 0

y: float: Alias for field number 1

z: float: Alias for field number 2

class Vec4

A four-dimensional vector represented as X Y Z W coordinates.

Vec4 is an immutable 2D Vector, including most common operators. As an immutable type, all operations return a new object.

Note

The Python len operator returns the number of elements in the vector. For the vector length, use the abs operator.

clamp(min_val: float, max_val: float) → Vec4

Return type:: Vec4

distance(other: Vec4) → float

Return type:: float

dot(other: Vec4) → float

Return type:: float

index(*args)

Return first index of value.

Raises ValueError if the value is not present.

lerp(other: Vec4, alpha: float) → Vec4

Create a new Vec4 linearly interpolated between this vector and another Vec4.

Parameters:

other (Vec4) – Another Vec4 instance.
alpha (float) – The amount of interpolation between this vector, and the other vector. This should be a value between 0.0 and 1.0. For example: 0.5 is the midway point between both vectors.

Return type:

Vec4

normalize() → Vec4

Normalize the vector to have a magnitude of 1. i.e. make it a unit vector.

Return type:: Vec4

w: float: Alias for field number 3

x: float: Alias for field number 0

y: float: Alias for field number 1

z: float: Alias for field number 2

clamp(num: float, minimum: float, maximum: float) → float

Clamp a value between a minimum and maximum limit.

Return type:: float

pyglet.media

Submodules

pyglet.media.synthesis

class ADSREnvelope

A four part Attack, Decay, Suspend, Release envelope.

This is a four part ADSR envelope. The attack, decay, and release parameters should be provided in seconds. For example, a value of 0.1 would be 100ms. The sustain_amplitude parameter affects the sustain volume. This defaults to a value of 0.5, but can be provided on a scale from 0.0 to 1.0.

Parameters:

attackfloat: The attack time, in seconds.
decayfloat: The decay time, in seconds.
releasefloat: The release time, in seconds.
sustain_amplitudefloat: The sustain amplitude (volume), from 0.0 to 1.0.

__init__(attack, decay, release, sustain_amplitude=0.5)

get_generator(sample_rate, duration)

class FlatEnvelope

A flat envelope, providing basic amplitude setting.

Parameters:

amplitudefloat: The amplitude (volume) of the wave, from 0.0 to 1.0. Values outside this range will be clamped.

__init__(amplitude=0.5)

get_generator(sample_rate, duration)

class LinearDecayEnvelope

A linearly decaying envelope.

This envelope linearly decays the amplitude from the peak value to 0, over the length of the waveform.

Parameters:

peakfloat: The Initial peak value of the envelope, from 0.0 to 1.0. Values outside this range will be clamped.

__init__(peak=1.0)

get_generator(sample_rate, duration)

class Sawtooth

__init__(duration, frequency=440, sample_rate=44800, envelope=None): Create a Sawtooth waveform.

class Silence

__init__(duration, frequency=440, sample_rate=44800, envelope=None): Create a Silent waveform.

class Sine

__init__(duration, frequency=440, sample_rate=44800, envelope=None): Create a sinusoid (sine) waveform.

class Square

__init__(duration, frequency=440, sample_rate=44800, envelope=None): Create a Square (pulse) waveform.

class SynthesisSource

Base class for synthesized waveforms.

Parameters:

generatorA non-instantiated generator object: A waveform generator that produces a stream of floats from (-1, 1)
durationfloat: The length, in seconds, of audio that you wish to generate.
sample_rateint: Audio samples per second. (CD quality is 44100).
envelopepyglet.media.synthesis._Envelope: An optional Envelope to apply to the waveform.

__init__(generator, duration, sample_rate=44800, envelope=None)

get_audio_data(num_bytes, compensation_time=0.0): Return num_bytes bytes of audio data.

is_precise() → bool

bool: Whether this source is considered precise.

x bytes on source s are considered aligned if x % s.audio_format.bytes_per_frame == 0, so there’d be no partial audio frame in the returned data.

A source is precise if - for an aligned request of x bytes - it returns::rtype: bool

If x or more bytes are available, x bytes.

If not enough bytes are available anymore, r bytes where r < x and r is aligned.

A source is not precise if it does any of these:

Return less than x bytes for an aligned request of x bytes although data still remains so that an additional request would return additional AudioData / not None.

Return more bytes than requested.

Return an unaligned amount of bytes for an aligned request.

pyglet’s internals are guaranteed to never make unaligned requests, or requests of less than 1024 bytes.

If this method returns False, pyglet will wrap the source in an alignment-forcing buffer creating additional overhead.

If this method is overridden to return True although the source does not comply with the requirements above, audio playback may be negatively impacted at best and memory access violations occurr at worst.

Returns:: bool: Whether the source is precise.

seek(timestamp)

Seek to given timestamp.

Parameters:: timestamp (float) – Time where to seek in the source. The timestamp will be clamped to the duration of the source.

class TremoloEnvelope

A tremolo envelope, for modulation amplitude.

A tremolo envelope that modulates the amplitude of the waveform with a sinusoidal pattern. The depth and rate of modulation can be specified. Depth is calculated as a percentage of the maximum amplitude. For example: a depth of 0.2 and amplitude of 0.5 will fluctuate the amplitude between 0.4 an 0.5.

Parameters:

depthfloat: The amount of fluctuation, from 0.0 to 1.0.
ratefloat: The fluctuation frequency, in seconds.
amplitudefloat: The peak amplitude (volume), from 0.0 to 1.0.

__init__(depth, rate, amplitude=0.5)

get_generator(sample_rate, duration)

class Triangle

__init__(duration, frequency=440, sample_rate=44800, envelope=None): Create a Triangle waveform.

class WhiteNoise

__init__(duration, frequency=440, sample_rate=44800, envelope=None): Create a random white noise waveform.

composite_operator(*operators)

noise_generator(frequency, sample_rate)

pulse_generator(frequency, sample_rate, duty_cycle=50)

sawtooth_generator(frequency, sample_rate)

silence_generator(frequency, sample_rate)

sine_generator(frequency, sample_rate)

sine_operator( sample_rate=44800, frequency=440, index=1, modulator=None, envelope=None, )

A sine wave generator that can be optionally modulated with another generator.

This generator represents a single FM Operator. It can be used by itself as a simple sine wave, or modulated by another waveform generator. Multiple operators can be linked together in this way. For example:

operator1 = sine_operator(samplerate=44800, frequency=1.22)
operator2 = sine_operator(samplerate=44800, frequency=99, modulator=operator1)
operator3 = sine_operator(samplerate=44800, frequency=333, modulator=operator2)
operator4 = sine_operator(samplerate=44800, frequency=545, modulator=operator3)

Parameters:

sample_rateint: Audio samples per second. (CD quality is 44100).
frequencyfloat: The frequency, in Hz, of the waveform you wish to generate.
indexfloat: The modulation index. Defaults to 1
modulatorsine_operator: An optional operator to modulate this one.
envelopepyglet.media.synthesis._Envelope: An optional Envelope to apply to the waveform.

triangle_generator(frequency, sample_rate)

Details

Audio and video playback.

pyglet can play WAV files, and if FFmpeg is installed, many other audio and video formats.

Playback is handled by the Player class, which reads raw data from Source objects and provides methods for pausing, seeking, adjusting the volume, and so on. The Player class implements the best available audio device.

player = Player()

A Source is used to decode arbitrary audio and video files. It is associated with a single player by “queueing” it:

source = load('background_music.mp3')
player.queue(source)

Use the Player to control playback.

If the source contains video, the Source.video_format() attribute will be non-None, and the Player.texture attribute will contain the current video image synchronised to the audio.

Decoding sounds can be processor-intensive and may introduce latency, particularly for short sounds that must be played quickly, such as bullets or explosions. You can force such sounds to be decoded and retained in memory rather than streamed from disk by wrapping the source in a StaticSource:

bullet_sound = StaticSource(load('bullet.wav'))

The other advantage of a StaticSource is that it can be queued on any number of players, and so played many times simultaneously.

Pyglet relies on Python’s garbage collector to release resources when a player has finished playing a source. In this way some operations that could affect the application performance can be delayed.

The player provides a Player.delete() method that can be used to release resources immediately.

Classes

class Player

High-level sound and video player.

Methods

play() → None

Begin playing the current source.

This has no effect if the player is already playing.

Return type:: None

pause() → None

Pause playback of the current source.

This has no effect if the player is already paused.

Return type:: None

queue( source: Source | Iterable[Source], ) → None

Queue the source on this player.

If the player has no source, the player will start to play immediately or pause depending on its playing attribute.

Parameters:: source (Source or Iterable[Source]) – The source to queue.
Return type:: None

seek(timestamp: float) → None

Seek for playback to the indicated timestamp on the current source.

Timestamp is expressed in seconds. If the timestamp is outside the duration of the source, it will be clamped to the end.

Parameters:: timestamp (float) – The time where to seek in the source.
Return type:: None

seek_next_frame() → None

Step forwards one video frame in the current source.

Return type:: None

get_texture() → Texture

Get the texture for the current video frame.

You should call this method every time you display a frame of video, as multiple textures might be used. The return value will be None if there is no video in the current source.

Return type:: Texture
Returns:: pyglet.image.Texture

Deprecated since version 1.4: Use texture instead

next_source() → None

Move immediately to the next source in the current playlist.

If the playlist is empty, discard it and check if another playlist is queued. There may be a gap in playback while the audio buffer is refilled.

Return type:: None

delete() → None

Release the resources acquired by this player.

The internal audio player and the texture will be deleted.

Return type:: None

update_texture(dt: float = None) → None

Manually update the texture from the current source.

This happens automatically, so you shouldn’t need to call this method.

Parameters:: dt (float) – The time elapsed since the last call to update_texture.
Return type:: None

Events

on_eos()

The current source ran out of data.

The default behaviour is to advance to the next source in the playlist if the loop attribute is set to False. If loop attribute is set to True, the current source will start to play again until next_source() is called or loop is set to False.

Event:

on_player_eos()

The player ran out of sources. The playlist is empty.

Event:

on_player_next_source()

The player starts to play the next queued source in the playlist.

This is a useful event for adjusting the window size to the new source VideoFormat for example.

Event:

Attributes

cone_inner_angle

The interior angle of the inner cone.

The angle is given in degrees, and defaults to 360. When the listener is positioned within the volume defined by the inner cone, the sound is played at normal gain (see volume).

cone_outer_angle

The interior angle of the outer cone.

The angle is given in degrees, and defaults to 360. When the listener is positioned within the volume defined by the outer cone, but outside the volume defined by the inner cone, the gain applied is a smooth interpolation between volume and cone_outer_gain.

cone_orientation

The direction of the sound in 3D space.

The direction is specified as a tuple of floats (x, y, z), and has no unit. The default direction is (0, 0, -1). Directional effects are only noticeable if the other cone properties are changed from their default values.

cone_outer_gain

The gain applied outside the cone.

When the listener is positioned outside the volume defined by the outer cone, this gain is applied instead of volume.

min_distance

The distance beyond which the sound volume drops by half, and within which no attenuation is applied.

The minimum distance controls how quickly a sound is attenuated as it moves away from the listener. The gain is clamped at the nominal value within the min distance. By default the value is 1.0.

The unit defaults to meters, but can be modified with the listener properties.

max_distance

The distance at which no further attenuation is applied.

When the distance from the listener to the player is greater than this value, attenuation is calculated as if the distance were value. By default the maximum distance is infinity.

The unit defaults to meters, but can be modified with the listener properties.

pitch

The pitch shift to apply to the sound.

The nominal pitch is 1.0. A pitch of 2.0 will sound one octave higher, and play twice as fast. A pitch of 0.5 will sound one octave lower, and play twice as slow. A pitch of 0.0 is not permitted.

playing

Read-only. Determine if the player state is playing.

The playing property is irrespective of whether or not there is actually a source to play. If playing is True and a source is queued, it will begin to play immediately. If playing is False, it is implied that the player is paused. There is no other possible state.

Type:: bool

position

The position of the sound in 3D space.

The position is given as a tuple of floats (x, y, z). The unit defaults to meters, but can be modified with the listener properties.

source

Read-only. The current Source, or None.

Type:: Source

texture

Get the texture for the current video frame.

You should call this method every time you display a frame of video, as multiple textures might be used. The return value will be None if there is no video in the current source.

Type:: pyglet.image.Texture

time

Read-only. Current playback time of the current source.

The playback time is a float expressed in seconds, with 0.0 being the beginning of the media. The playback time returned represents the player master clock time which is used to synchronize both the audio and the video.

Type:: float

volume

The volume level of sound playback.

The nominal level is 1.0, and 0.0 is silence.

The volume level is affected by the distance from the listener (if positioned).

__init__() → None: Initialize the Player with a MasterClock.

__new__(**kwargs)

loop

Loop the current source indefinitely or until next_source() is called. Defaults to False.

Type:: bool

New in version 1.4.

class PlayerGroup

Group of players that can be played and paused simultaneously.

Create a player group for the given list of players.

All players in the group must currently not belong to any other group.

Parameters:: players (Iterable[Player]) – Iterable of Player s in this group.

play() → None

Begin playing all players in the group simultaneously.

Return type:: None

pause() → None

Pause all players in the group simultaneously.

Return type:: None

__init__(players: Iterable[Player]) → None: Initialize the PlayerGroup with the players.

__new__(**kwargs)

class AudioFormat

Audio details.

An instance of this class is provided by sources with audio tracks. You should not modify the fields, as they are used internally to describe the format of data provided by the source.

Parameters:

channels (int) – The number of channels: 1 for mono or 2 for stereo (pyglet does not yet support surround-sound sources).
sample_size (int) – Bits per sample; only 8 or 16 are supported.
sample_rate (int) – Samples per second (in Hertz).

__init__(channels: int, sample_size: int, sample_rate: int) → None

__new__(**kwargs)

class VideoFormat

Video details.

An instance of this class is provided by sources with a video stream. You should not modify the fields.

Note that the sample aspect has no relation to the aspect ratio of the video image. For example, a video image of 640x480 with sample aspect 2.0 should be displayed at 1280x480. It is the responsibility of the application to perform this scaling.

Parameters:

width (int) – Width of video image, in pixels.
height (int) – Height of video image, in pixels.
sample_aspect (float) – Aspect ratio (width over height) of a single video pixel.
frame_rate (float) –
Frame rate (frames per second) of the video.

New in version 1.2.

__init__(width: int, height: int, sample_aspect: float = 1.0) → None

__new__(**kwargs)

class AudioData

A single packet of audio data.

This class is used internally by pyglet.

Parameters:

data (bytes, ctypes array, or supporting buffer protocol) – Sample data.
length (int) – Size of sample data, in bytes.
timestamp (float) – Time of the first sample, in seconds.
duration (float) – Total data duration, in seconds.
events (List[pyglet.media.drivers.base.MediaEvent]) – List of events contained within this packet. Events are timestamped relative to this audio packet.

Deprecated since version 2.0.10: timestamp and duration are unused and will be removed eventually.

__init__( data: bytes | Array, length: int, timestamp: float = 0.0, duration: float = 0.0, events: List[MediaEvent] | None = None, ) → None

class SourceInfo

Source metadata information.

Fields are the empty string or zero if the information is not available.

Parameters:

title (str) – Title
author (str) – Author
copyright (str) – Copyright statement
comment (str) – Comment
album (str) – Album name
year (int) – Year
track (int) – Track number
genre (str) – Genre

New in version 1.2.

class Source

An audio and/or video source.

Parameters:

audio_format (AudioFormat) – Format of the audio in this source, or None if the source is silent.
video_format (VideoFormat) – Format of the video in this source, or None if there is no video.
info (SourceInfo) –
Source metadata such as title, artist, etc; or None if the` information is not available.

New in version 1.2.

Class Variables:

is_player_source (bool) – Determine if this source is a player current source.

Check on a Player if this source is the current source.

get_animation() → Animation

Import all video frames into memory.

An empty animation will be returned if the source has no video. Otherwise, the animation will contain all unplayed video frames (the entire source, if it has not been queued on a player). After creating the animation, the source will be at EOS (end of stream).

This method is unsuitable for videos running longer than a few seconds.

New in version 1.1.

Return type:: Animation
Returns:: pyglet.image.Animation

get_audio_data( num_bytes: int, compensation_time=0.0, ) → AudioData | None

Get next packet of audio data.

Parameters:

num_bytes (int) – A size hint for the amount of bytes to return, but the returned amount may be lower or higher.
compensation_time (float) – Time in sec to compensate due to a difference between the master clock and the audio clock.

Deprecated since version 2.0.10: compensation_time: Will always be given as 0.0.

Returns:: Next packet of audio data, or None if there is no (more) data.
Return type:: AudioData

get_next_video_frame() → AbstractImage | None

Get the next video frame.

New in version 1.1.

Returns:: The next video frame image, or None if the video frame could not be decoded or there are no more video frames.
Return type:: pyglet.image.AbstractImage

get_next_video_timestamp() → float | None

Get the timestamp of the next video frame.

New in version 1.1.

Returns:: The next timestamp, or None if there are no more video frames.
Return type:: float

get_queue_source() → Source

Return the Source to be used as the queue source for a player.

Default implementation returns self if this source is precise as specified by is_precise() or if the imprecise_ok argument is given. Otherwise, a new PreciseStreamingSource wrapping this source is returned.

Return type:: Source
Returns:: Source

is_precise() → bool

bool: Whether this source is considered precise.

x bytes on source s are considered aligned if x % s.audio_format.bytes_per_frame == 0, so there’d be no partial audio frame in the returned data.

A source is precise if - for an aligned request of x bytes - it returns::rtype: bool

If x or more bytes are available, x bytes.

If not enough bytes are available anymore, r bytes where r < x and r is aligned.

A source is not precise if it does any of these:

Return less than x bytes for an aligned request of x bytes although data still remains so that an additional request would return additional AudioData / not None.

Return more bytes than requested.

Return an unaligned amount of bytes for an aligned request.

pyglet’s internals are guaranteed to never make unaligned requests, or requests of less than 1024 bytes.

If this method returns False, pyglet will wrap the source in an alignment-forcing buffer creating additional overhead.

If this method is overridden to return True although the source does not comply with the requirements above, audio playback may be negatively impacted at best and memory access violations occurr at worst.

Returns:: bool: Whether the source is precise.

play() → Player

Play the source.

This is a convenience method which creates a Player for this source and plays it immediately.

Return type:: Player
Returns:: Player

save( filename: str, file: BinaryIO | None = None, encoder: MediaEncoder | None = None, ) → None

Save this Source to a file.

Parameters:

filenamestr: Used to set the file format, and to open the output file if file is unspecified.
filefile-like object or None: File to write audio data to.
encoderMediaEncoder or None: If unspecified, all encoders matching the filename extension are tried. If all fail, the exception from the first one attempted is raised.

Return type:

seek(timestamp: float) → None

Seek to given timestamp.

Parameters:: timestamp (float) – Time where to seek in the source. The timestamp will be clamped to the duration of the source.
Return type:: None

property duration: float

The length of the source, in seconds.

Not all source durations can be determined; in this case the value is None.

Read-only.

Type:: float

class StreamingSource

Bases: Source

A source that is decoded as it is being played.

The source can only be played once at a time on any Player.

delete() → None

Release the resources held by this StreamingSource.

Return type:: None

get_queue_source() → StreamingSource

Return the Source to be used as the source for a player.

Default implementation returns self.

Return type:: StreamingSource
Returns:: Source

class StaticSource

Bases: Source

A source that has been completely decoded in memory.

This source can be queued onto multiple players any number of times.

Construct a StaticSource for the data in source.

Parameters:: source (Source) – The source to read and decode audio and video data from.

__init__(source: Source) → None

get_audio_data( num_bytes: float, compensation_time: float = 0.0, ) → AudioData | None

The StaticSource does not provide audio data.

When the StaticSource is queued on a Player, it creates a StaticMemorySource containing its internal audio data and audio format.

Raises:: RuntimeError –
Return type:: AudioData | None

get_queue_source() → StaticMemorySource | None

Return the Source to be used as the queue source for a player.

Default implementation returns self if this source is precise as specified by is_precise() or if the imprecise_ok argument is given. Otherwise, a new PreciseStreamingSource wrapping this source is returned.

Return type:: StaticMemorySource | None
Returns:: Source

class StaticMemorySource

Bases: StaticSource

Helper class for default implementation of StaticSource.

Do not use directly. This class is used internally by pyglet.

Parameters:

data (readable buffer) – The audio data.
audio_format (AudioFormat) – The audio format.

__init__( data, audio_format: AudioFormat, ) → None: Construct a memory source over the given data buffer.

get_audio_data( num_bytes: float, compensation_time: float = 0.0, ) → AudioData | None

Get next packet of audio data.

Parameters:: num_bytes (int) – Maximum number of bytes of data to return.
Returns:: Next packet of audio data, or None if there is no (more) data.
Return type:: AudioData

is_precise() → bool

bool: Whether this source is considered precise.

x bytes on source s are considered aligned if x % s.audio_format.bytes_per_frame == 0, so there’d be no partial audio frame in the returned data.

A source is precise if - for an aligned request of x bytes - it returns::rtype: bool

If x or more bytes are available, x bytes.

If not enough bytes are available anymore, r bytes where r < x and r is aligned.

A source is not precise if it does any of these:

Return less than x bytes for an aligned request of x bytes although data still remains so that an additional request would return additional AudioData / not None.

Return more bytes than requested.

Return an unaligned amount of bytes for an aligned request.

pyglet’s internals are guaranteed to never make unaligned requests, or requests of less than 1024 bytes.

If this method returns False, pyglet will wrap the source in an alignment-forcing buffer creating additional overhead.

If this method is overridden to return True although the source does not comply with the requirements above, audio playback may be negatively impacted at best and memory access violations occurr at worst.

Returns:: bool: Whether the source is precise.

seek(timestamp: float) → None

Seek to given timestamp.

Parameters:: timestamp (float) – Time where to seek in the source.
Return type:: None

class AbstractListener

The listener properties for positional audio.

You can obtain the singleton instance of this class by calling AbstractAudioDriver.get_listener().

property forward_orientation

A vector giving the direction the listener is facing.

The orientation is given as a tuple of floats (x, y, z), and has no unit. The forward orientation should be orthagonal to the up orientation.

Type:: 3-tuple of float

property position

The position of the listener in 3D space.

The position is given as a tuple of floats (x, y, z). The unit defaults to meters, but can be modified with the listener properties.

Type:: 3-tuple of float

property up_orientation

A vector giving the “up” orientation of the listener.

The orientation is given as a tuple of floats (x, y, z), and has no unit. The up orientation should be orthagonal to the forward orientation.

Type:: 3-tuple of float

property volume

The master volume for sound playback.

All sound volumes are multiplied by this master volume before being played. A value of 0 will silence playback (but still consume resources). The nominal volume is 1.0.

Type:: float

class MediaEvent

Representation of a media event.

These events are used internally by some audio driver implementation to communicate events to the Player. One example is the on_eos event.

Parameters:

event (str) – Event description.
timestamp (float) – The time when this event happens.
*args – Any required positional argument to go along with this event.

__init__(event, timestamp=0.0, *args)

Functions

get_audio_driver()

Get the preferred audio driver for the current platform.

See pyglet.options audio, and the Programming guide, section Playing Sound and Video for more information on setting the preferred driver.

Returns:

The concrete implementation of the preferred: audio driver for this platform.

Return type:

AbstractAudioDriver

load(filename, file=None, streaming=True, decoder=None)

Load a Source from a file.

All decoders that are registered for the filename extension are tried. If none succeed, the exception from the first decoder is raised. You can also specifically pass a decoder to use.

Parameters:

filenamestr: Used to guess the media format, and to load the file if file is unspecified.
filefile-like object or None: Source of media data in any supported format.
streamingbool: If False, a StaticSource will be returned; otherwise (default) a StreamingSource is created.
decoderMediaDecoder or None: A specific decoder you wish to use, rather than relying on automatic detection. If specified, no other decoders are tried.

Return type:

StreamingSource or Source

have_ffmpeg()

Check if FFmpeg library is available.

Returns:: True if FFmpeg is found.
Return type:: bool

New in version 1.4.

Exceptions

exception CannotSeekException

exception MediaException

exception MediaFormatException

pyglet.resource

Load application resources from a known path.

Loading resources by specifying relative paths to filenames is often problematic in Python, as the working directory is not necessarily the same directory as the application’s script files.

This module allows applications to specify a search path for resources. Relative paths are taken to be relative to the application’s __main__ module. ZIP files can appear on the path; they will be searched inside. The resource module also behaves as expected when applications are bundled using Freezers such as PyInstaller, Nuitka, py2app, etc..

In addition to providing file references (with the file() function), the resource module also contains convenience functions for loading images, textures, fonts, media and documents.

3rd party modules or packages not bound to a specific application should construct their own Loader instance and override the path to use the resources in the module’s directory.

Path format

The resource path path (see also Loader.__init__() and Loader.path()) is a list of locations to search for resources. Locations are searched in the order given in the path. If a location is not valid (for example, if the directory does not exist), it is skipped.

Locations in the path beginning with an “at” symbol (‘’@’’) specify Python packages. Other locations specify a ZIP archive or directory on the filesystem. Locations that are not absolute are assumed to be relative to the script home. Some examples:

# Search just the `res` directory, assumed to be located alongside the
# main script file.
path = ['res']

# Search the directory containing the module `levels.level1`, followed
# by the `res/images` directory.
path = ['@levels.level1', 'res/images']

Paths are always case-sensitive and forward slashes are always used as path separators, even in cases when the filesystem or platform does not do this. This avoids a common programmer error when porting applications between platforms.

The default path is ['.']. If you modify the path, you must call reindex().

exception ResourceNotFoundException

The named resource was not found on the search path.

__init__(name)

exception UndetectableShaderType

The type of the Shader source could not be identified.

__init__(name)

class FileLocation

Location on the filesystem.

__init__(filepath: str) → None: Create a location given a relative or absolute path.

open(filename: str, mode: str = 'rb') → IO

Open a file at this location.

Parameters:

name – The file name to open. Absolute paths are not supported. Relative paths are not supported by most locations (you should specify only a file name with no path component).
mode (str) – The file mode to open with. Only files opened on the filesystem make use of this parameter; others ignore it.

Return type:

IO

class Loader

Load program resource files from disk.

The loader contains a search path which can include filesystem directories, ZIP archives, URLs, and Python packages.

__init__( pathlist: list[str] | None = None, script_home: str | None = None, ) → None

Create a loader for the given path.

If no path is specified it defaults to ['.']; that is, just the program directory.

See the module documentation for details on the path format.

Parameters:

pathlist (list[str] | None) – List of locations to search for resources.
script_home (str | None) – Base location of relative files. Defaults to the result of get_script_home().

add_font(filename: str) → None

Add a font resource to the application.

Fonts not installed on the system must be added to pyglet before they can be used with font.load. Although the font is added with its filename using this function, fonts are always loaded by specifying their family name. For example:

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

Return type:: None

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, border: int = 1, ) → Animation

Load an animation with optional transformation.

Animations loaded from the same source but with different transformations will use the same textures.

Parameters:

name (str) – Filename of the animation source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (int) – The returned image will be rotated clockwise by the given number of degrees (must be a multiple of 90).
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Animation

attributed(name: str) → AbstractDocument

Load an attributed text document.

See pyglet.text.formats.attributed for details on this format.

Return type:: AbstractDocument

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

Load a file-like object.

Parameters:

name (str) – Filename of the resource to load.
mode (str) – Combination of r, w, a, b and t characters with the meaning as for the builtin open function.

Return type:

get_cached_animation_names() → list[str]

Get a list of animation filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_image_names() → list[str]

Get a list of image filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_texture_names() → list[str]

Get a list of texture filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_texture_bins() → list[pyglet.image.atlas.TextureBin]

Get a list of texture bins in use.

This is useful for debugging and profiling only.

Return type:: list[TextureBin]

html(name: str) → AbstractDocument

Load an HTML document.

Return type:: AbstractDocument

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

Load an image with optional transformation.

This is similar to texture, except the resulting image will be packed into a TextureBin (TextureAtlas) if it is an appropriate size for packing. This is more efficient than loading images into separate textures.

Parameters:

name (str) – The filename of the image source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (int) – The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
atlas (bool) – If True, the image will be loaded into an atlas managed by pyglet. If atlas loading is not appropriate for specific texturing reasons (e.g. border control is required) then set to False.
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Texture | TextureRegion

Note

When using flip_x/y or rotate, the actual image data is not modified. Instead, the texture coordinates are manipulated to produce the desired result.

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

Get the location of a resource.

This method is useful for opening files referenced from a resource. For example, an HTML file loaded as a resource might reference some images. These images should be located relative to the HTML file, not looked up individually in the loader’s path.

Return type:: FileLocation | URLLocation | ZIPLocation

media(name: str, streaming: bool = True) → Source

Load a sound or video resource.

The meaning of streaming is as for load(). Compressed sources cannot be streamed (that is, video and compressed audio cannot be streamed from a ZIP archive).

Parameters:

name (str) – Filename of the media source to load.
streaming (bool) – True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.

Return type:

Source

model( name: str, batch: Batch | None = None, ) → Model

Load a 3D model.

Parameters:

name (str) – Filename of the 3D model to load.
batch (Batch | None) – An optional Batch instance to add this model to.

Return type:

Model

reindex()

Refresh the file index.

You must call this method if resource.path is changed, or the filesystem layout changes.

shader( name: str, shader_type: str | None = None, ) → Shader

Load a Shader object.

Parameters:

name (str) – Filename of the Shader source to load.
shader_type (str | None) – A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension, such as .vert, .frag, etc..

Return type:

Shader

text(name: str) → AbstractDocument

Load a plain text document.

Return type:: AbstractDocument

texture(name: str) → Texture

Load an image as a single OpenGL texture.

Return type:: Texture

class Location

Abstract resource location.

Given a location, a file can be loaded from that location with the open() method. This provides a convenient way to specify a path to load files from, even when that path does not reside on the filesystem.

open( name: str, mode: str = 'rb', ) → BytesIO | StringIO | IO

Open a file at this location.

Parameters:

name (str) – The file name to open. Absolute paths are not supported. Relative paths are not supported by most locations (you should specify only a file name with no path component).
mode (str) – The file mode to open with. Only files opened on the filesystem make use of this parameter; others ignore it.

Return type:

class URLLocation

Location on the network.

This class uses the urllib module to open files on the network, given a base URL.

__init__(base_url: str) → None: Create a location given a base URL.

open(filename: str, mode: str = '') → IO

Open a remote file.

Parameters:

filename (str) – The name of the remote resource to open.
mode (str) – Unused, as the mode is determined by the remote server.

Return type:

IO

class ZIPLocation

Location within a ZIP file.

__init__(zipfileobj: ZipFile, directory: str | None)

Create a location given an open ZIP file and a path within that file.

Parameters:

zipfileobj (ZipFile) – An open ZIP file from the zipfile module.
directory (str | None) – A path within that ZIP file. Can be empty to specify files at the top level of the ZIP file.

open(filename: str, mode='rb') → BytesIO | StringIO

Open a file from inside the ZipFile.

Parameters:

filename (str) – The filename to open.
mode – Valid modes are ‘r’ and ‘rb’.

Return type:

BytesIO | StringIO

add_font(filename: str) → None

Add a font resource to the application.

Fonts not installed on the system must be added to pyglet before they can be used with font.load. Although the font is added with its filename using this function, fonts are always loaded by specifying their family name. For example:

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

Return type:: None

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, border: int = 1, ) → Animation

Load an animation with optional transformation.

Animations loaded from the same source but with different transformations will use the same textures.

Parameters:

name (str) – Filename of the animation source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (int) – The returned image will be rotated clockwise by the given number of degrees (must be a multiple of 90).
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Animation

attributed(name: str) → AbstractDocument

Load an attributed text document.

See pyglet.text.formats.attributed for details on this format.

Return type:: AbstractDocument

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

Load a file-like object.

Parameters:

name (str) – Filename of the resource to load.
mode (str) – Combination of r, w, a, b and t characters with the meaning as for the builtin open function.

Return type:

get_cached_animation_names() → list[str]

Get a list of animation filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_image_names() → list[str]

Get a list of image filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_texture_names() → list[str]

Get a list of texture filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_data_path(name: str) → str

Get a directory to save user data.

For a Posix or Linux based system many distributions have a separate directory to store user data for a specific application and this function returns the path to that location.

On Linux, a directory name in the user’s data directory is returned (usually under ~/.local/share).

On Windows (including under Cygwin) the name directory in the user’s Application Settings directory is returned.

On Mac OS X the name directory under ~/Library/Application Support is returned. :rtype: str

Note

This function does not perform any directory creation. Users should use os.path.exists and os.makedirs to construct the directory if desired.

get_script_home() → str

Get the directory containing the program entry module.

For ordinary Python scripts, this is the directory containing the __main__ module. For applications that have been bundled with PyInstaller, Nuitka, etc., this may be the bundle path or a temporary directory.

If none of the above cases apply and the file for __main__ cannot be determined the working directory is returned.

When the script is being run by a Python profiler, this function may return the directory where the profiler is running instead of the directory of the real script. To work around this behaviour the full path to the real script can be specified in pyglet.resource.path.

Return type:: str

get_settings_path(name: str) → str

Get a directory path to save user preferences.

Different platforms have different conventions for where to save user preferences and settings. This function implements those conventions as described below, and returns a fully formed path.

On Linux, a directory name in the user’s configuration directory is returned (usually under ~/.config).

On Windows (including under Cygwin) the name directory in the user’s Application Settings directory is returned.

On Mac OS X the name directory under ~/Library/Application Support is returned. :rtype: str

Note

This function does not perform any directory creation. Users should use os.path.exists and os.makedirs to construct the directory if desired.

get_texture_bins() → list[pyglet.image.atlas.TextureBin]

Get a list of texture bins in use.

This is useful for debugging and profiling only.

Return type:: list[TextureBin]

html(name: str) → AbstractDocument

Load an HTML document.

Return type:: AbstractDocument

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

Load an image with optional transformation.

This is similar to texture, except the resulting image will be packed into a TextureBin (TextureAtlas) if it is an appropriate size for packing. This is more efficient than loading images into separate textures.

Parameters:

name (str) – The filename of the image source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (int) – The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
atlas (bool) – If True, the image will be loaded into an atlas managed by pyglet. If atlas loading is not appropriate for specific texturing reasons (e.g. border control is required) then set to False.
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Texture | TextureRegion

Note

When using flip_x/y or rotate, the actual image data is not modified. Instead, the texture coordinates are manipulated to produce the desired result.

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

Get the location of a resource.

This method is useful for opening files referenced from a resource. For example, an HTML file loaded as a resource might reference some images. These images should be located relative to the HTML file, not looked up individually in the loader’s path.

Return type:: FileLocation | URLLocation | ZIPLocation

media(name: str, streaming: bool = True) → Source

Load a sound or video resource.

The meaning of streaming is as for load(). Compressed sources cannot be streamed (that is, video and compressed audio cannot be streamed from a ZIP archive).

Parameters:

name (str) – Filename of the media source to load.
streaming (bool) – True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.

Return type:

Source

model(name: str, batch: Batch | None = None) → Model

Load a 3D model.

Parameters:

name (str) – Filename of the 3D model to load.
batch (Batch | None) – An optional Batch instance to add this model to.

Return type:

Model

reindex()

Refresh the file index.

You must call this method if resource.path is changed, or the filesystem layout changes.

shader(name: str, shader_type: str | None = None) → Shader

Load a Shader object.

Parameters:

name (str) – Filename of the Shader source to load.
shader_type (str | None) – A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension, such as .vert, .frag, etc..

Return type:

Shader

text(name: str) → AbstractDocument

Load a plain text document.

Return type:: AbstractDocument

texture(name: str) → Texture

Load an image as a single OpenGL texture.

Return type:: Texture

path = ['.']

Default resource search path.

Locations in the search path are searched in order and are always case-sensitive. After changing the path you must call reindex.

See the module documentation for details on the path format.

Type:: list of str

Functions

reindex()

Refresh the file index.

You must call this method if resource.path is changed, or the filesystem layout changes.

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

Load a file-like object.

Parameters:

name (str) – Filename of the resource to load.
mode (str) – Combination of r, w, a, b and t characters with the meaning as for the builtin open function.

Return type:

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

Get the location of a resource.

This method is useful for opening files referenced from a resource. For example, an HTML file loaded as a resource might reference some images. These images should be located relative to the HTML file, not looked up individually in the loader’s path.

Return type:: FileLocation | URLLocation | ZIPLocation

add_font(filename: str) → None

Add a font resource to the application.

Fonts not installed on the system must be added to pyglet before they can be used with font.load. Although the font is added with its filename using this function, fonts are always loaded by specifying their family name. For example:

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

Return type:: None

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

Load an image with optional transformation.

This is similar to texture, except the resulting image will be packed into a TextureBin (TextureAtlas) if it is an appropriate size for packing. This is more efficient than loading images into separate textures.

Parameters:

name (str) – The filename of the image source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (int) – The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
atlas (bool) – If True, the image will be loaded into an atlas managed by pyglet. If atlas loading is not appropriate for specific texturing reasons (e.g. border control is required) then set to False.
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Texture | TextureRegion

Note

When using flip_x/y or rotate, the actual image data is not modified. Instead, the texture coordinates are manipulated to produce the desired result.

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, border: int = 1, ) → Animation

Load an animation with optional transformation.

Animations loaded from the same source but with different transformations will use the same textures.

Parameters:

name (str) – Filename of the animation source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (int) – The returned image will be rotated clockwise by the given number of degrees (must be a multiple of 90).
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Animation

texture(name: str) → Texture

Load an image as a single OpenGL texture.

Return type:: Texture

media(name: str, streaming: bool = True) → Source

Load a sound or video resource.

The meaning of streaming is as for load(). Compressed sources cannot be streamed (that is, video and compressed audio cannot be streamed from a ZIP archive).

Parameters:

name (str) – Filename of the media source to load.
streaming (bool) – True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.

Return type:

Source

model(name: str, batch: Batch | None = None) → Model

Load a 3D model.

Parameters:

name (str) – Filename of the 3D model to load.
batch (Batch | None) – An optional Batch instance to add this model to.

Return type:

Model

shader(name: str, shader_type: str | None = None) → Shader

Load a Shader object.

Parameters:

name (str) – Filename of the Shader source to load.
shader_type (str | None) – A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension, such as .vert, .frag, etc..

Return type:

Shader

html(name: str) → AbstractDocument

Load an HTML document.

Return type:: AbstractDocument

attributed(name: str) → AbstractDocument

Load an attributed text document.

See pyglet.text.formats.attributed for details on this format.

Return type:: AbstractDocument

text(name: str) → AbstractDocument

Load a plain text document.

Return type:: AbstractDocument

get_cached_image_names() → list[str]

Get a list of image filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_animation_names() → list[str]

Get a list of animation filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_texture_bins() → list[pyglet.image.atlas.TextureBin]

Get a list of texture bins in use.

This is useful for debugging and profiling only.

Return type:: list[TextureBin]

get_cached_texture_names() → list[str]

Get a list of texture filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

Exceptions

class ResourceNotFoundException

The named resource was not found on the search path.

__init__(name)

class UndetectableShaderType

The type of the Shader source could not be identified.

__init__(name)

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:: None

draw() → None

Draw the sprite at its current position.

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

Return type:: 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.

Parameters:

x (float | None) – X coordinate of the sprite.
y (float | None) – Y coordinate of the sprite.
z (float | None) – Z coordinate of the sprite.
rotation (float | None) – Clockwise rotation of the sprite, in degrees.
scale (float | None) – Scaling factor.
scale_x (float | None) – Horizontal scaling factor.
scale_y (float | None) – Vertical scaling factor.

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 either an RGBA tuple of integers ‘(red, green, blue, opacity)’ or an RGB tuple of integers (red, blue, green).

If there are fewer than three components, a :py:func`ValueError` will be raised. Each color component must be an int in the range 0 (dark) to 255 (saturated). If any component is not an int, a TypeError will be raised.

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.
batch (Batch | None) – Optional batch to add the sprite to.
group (Group | None) – Optional parent group of the sprite.
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 Sprite is 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.
parent (Group | None) – Optional parent group.

set_state() → None

Apply the OpenGL state change.

The default implementation does nothing.

Return type:: None

unset_state() → None

Repeal the OpenGL state change.

The default implementation does nothing.

Return type:: None

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 `ShapeBase`
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, thickness=19, batch=batch)
line2 = shapes.Line(150, 150, 444, 111, thickness=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 its draw() 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:: None

Attributes

x

Get/set the X coordinate of the shape’s position.

To update both x and y, use position instead.
Shapes may vary slightly in how they use position

See position to learn more.

y

Get/set the Y coordinate of the shape’s position.

This property has the following pitfalls:

To update both x and y, use position instead.
Shapes may vary slightly in how they use position

See position to learn more.

position

Get/set the (x, y) coordinates of the shape.

Tip

This is more efficient than setting x and y separately!

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:

Circle
Ellipse
Arc
Sector
Star

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:

Circle
Ellipse
Star

These shapes rotate around the point of their angles:

Arc
Sector

anchor_x

Get/set the X coordinate of the anchor point.

If you need to set both this and anchor_x, use anchor_position instead.

anchor_y

Get/set the Y coordinate of the anchor point.

If you need to set both this and anchor_x, use anchor_position instead.

anchor_position

Get/set the anchor’s (x, y) offset from position

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 and anchor_y) to custom values.

Since all anchor updates recalculate a shape’s vertices on the CPU, this property is faster than updating anchor_x and anchor_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 below 255 draw with fractional opacity over the background:

Example Values & Effects
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’t None, setting this property will also trigger a batch migration.

batch

Get/set the Batch for this shape.

Warning

Setting this to None currently breaks things!

Known issues include group breaking.

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: The angle of the arc, in degrees.

start_angle: The start angle of the arc, in degrees.

thickness

__init__( x: float, y: float, radius: float, segments: int | None = None, angle: float = 360.0, 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 degrees. Defaults to 360.0, which is a full circle.
start_angle (float) – The start angle of the arc, in radians. Defaults to 0.
closed (bool) – If True, the ends of the arc will be connected with a line. defaults to False.
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.
batch (Batch | None) – Optional batch to add the circle to.
group (Group | None) – Optional parent group of the circle.

__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.
batch (Batch | None) – Optional batch to add the curve to.
group (Group | None) – Optional parent group of the curve.

__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.
batch (Batch | None) – Optional batch to add the circle to.
group (Group | None) – Optional parent group of the circle.

__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.
batch (Batch | None) – Optional batch to add the circle to.
group (Group | None) – Optional parent group of the circle.

__new__(**kwargs)

class Sector

Bases: ShapeBase

angle: The angle of the sector, in degrees.

start_angle: The start angle of the sector, in degrees.

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 = 360.0, 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 degrees. Defaults to 360, which is a full circle.
start_angle (float) – The start angle of the sector, in degrees. 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.
batch (Batch | None) – Optional batch to add the sector to.
group (Group | None) – Optional parent group of the sector.

__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, 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 a line.

The line’s anchor point defaults to the center of the line’s thickness 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.
thickness (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.
batch (Batch | None) – Optional batch to add the line to.
group (Group | None) – Optional parent group of the line.

__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.
batch (Batch | None) – Optional batch to add the box to.
group (Group | None) – Optional parent group of the box.

__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, ) → 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.
batch (Batch | None) – Optional batch to add the star to.
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 to True to add a line connecting the first and last points. The default is False
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.
batch (Batch | None) – Optional batch to add the shape to.
group (Group | None) – Optional parent group of the shape.

__new__(**kwargs)

pyglet.text

Submodules

pyglet.text.caret

Provides keyboard and mouse editing procedures for text layout.

Example usage:

from pyglet import window
from pyglet.text import layout, caret

my_window = window.Window(...)
my_layout = layout.IncrementalTextLayout(...)
my_caret = caret.Caret(my_layout)
my_window.push_handlers(my_caret)

class Caret

Visible text insertion marker for pyglet.text.layout.IncrementalTextLayout.

The caret is drawn as a single vertical bar at the document position on a text layout object. If mark is not None, it gives the unmoving end of the current text selection. The visible text selection on the layout is updated along with mark and position.

By default, the layout’s graphics batch is used, so the caret does not need to be drawn explicitly. Even if a different graphics batch is supplied, the caret will be correctly positioned and clipped within the layout.

Updates to the document (and so the layout) are automatically propagated to the caret.

The caret object can be pushed onto a window event handler stack with Window.push_handlers. The caret will respond correctly to keyboard, text, mouse and activation events, including double- and triple-clicks. If the text layout is being used alongside other graphical widgets, a GUI toolkit will be needed to delegate keyboard and mouse events to the appropriate widget. Pyglet does not provide such a toolkit at this stage.

__init__( layout: IncrementalTextLayout, batch: Batch = None, color: tuple[int, int, int, int] = (0, 0, 0, 255), ) → None

Create a caret for a layout.

By default the layout’s batch is used, so the caret does not need to be drawn explicitly.

Parameters:

layout~pyglet.text.layout.IncrementalTextLayout: Layout to control.
batch~pyglet.graphics.Batch: Graphics batch to add vertices to.
color(int, int, int, int): An RGBA or RGB tuple with components in the range [0, 255]. RGB colors will be treated as having an opacity of 255.

delete() → None

Remove the caret from its batch.

Also disconnects the caret from further layout events.

Return type:: None

get_style(attribute: str) → Any

Get the document’s named style at the caret’s current position.

If there is a text selection and the style varies over the selection, pyglet.text.document.STYLE_INDETERMINATE is returned.

Parameters:: attribute (str) – Name of style attribute to retrieve. See document for a list of recognised attribute names.
Return type:: Any

move_to_point(x: int, y: int) → None

Move the caret close to the given window coordinate.

The mark will be reset to None.

Return type:: None

on_activate() → bool

Handler for the pyglet.window.Window.on_activate event.

The caret is hidden when the window is not active.

Return type:: bool

on_deactivate() → bool

Handler for the pyglet.window.Window.on_deactivate event.

The caret is hidden when the window is not active.

Return type:: bool

on_layout_update() → None

Handler for the IncrementalTextLayout.on_layout_update event.

Return type:: None

on_mouse_drag( x: int, y: int, dx: int, dy: int, buttons: int, modifiers: int, ) → bool

Handler for the pyglet.window.Window.on_mouse_drag event.

Mouse handlers do not check the bounds of the coordinates: GUI toolkits should filter events that do not intersect the layout before invoking this handler.

Return type:: bool

on_mouse_press(x: int, y: int, button: int, modifiers: int) → bool

Handler for the pyglet.window.Window.on_mouse_press event.

Mouse handlers do not check the bounds of the coordinates: GUI toolkits should filter events that do not intersect the layout before invoking this handler.

This handler keeps track of the number of mouse presses within a short span of time and uses this to reconstruct double- and triple-click events for selecting words and paragraphs. This technique is not suitable when a GUI toolkit is in use, as the active widget must also be tracked. Do not use this mouse handler if a GUI toolkit is being used.

Return type:: bool

on_mouse_scroll(x: float, y: float, scroll_x: float, scroll_y: float) → bool

Handler for the pyglet.window.Window.on_mouse_scroll event.

Mouse handlers do not check the bounds of the coordinates: GUI toolkits should filter events that do not intersect the layout before invoking this handler.

The layout viewport is scrolled by SCROLL_INCREMENT pixels per “click”.

Return type:: bool

on_text(text: str) → bool

Handler for the pyglet.window.Window.on_text event.

Caret keyboard handlers assume the layout always has keyboard focus. GUI toolkits should filter keyboard and text events by widget focus before invoking this handler.

Return type:: bool

on_text_motion(motion: int, select: bool = False) → bool

Handler for the pyglet.window.Window.on_text_motion event.

Caret keyboard handlers assume the layout always has keyboard focus. GUI toolkits should filter keyboard and text events by widget focus before invoking this handler.

Return type:: bool

on_text_motion_select(motion: int) → bool

Handler for the pyglet.window.Window.on_text_motion_select event.

Caret keyboard handlers assume the layout always has keyboard focus. GUI toolkits should filter keyboard and text events by widget focus before invoking this handler.

Return type:: bool

on_translation_update() → None

Return type:: None

select_all() → None

Select all text in the document.

Return type:: None

select_paragraph(x: int, y: int) → None

Select the paragraph at the given window coordinate.

Return type:: None

select_to_point(x: int, y: int) → None

Move the caret close to the given window coordinate while maintaining the mark.

Return type:: None

select_word(x: int, y: int) → None

Select the word at the given window coordinate.

Return type:: None

set_style(attributes: dict[str, Any]) → None

Set the document style at the caret’s current position.

If there is a text selection the style is modified immediately. Otherwise, the next text that is entered before the position is modified will take on the given style.

Parameters:: attributes (dict[str, Any]) – Dict mapping attribute names to style values. See document for a list of recognised attribute names.
Return type:: None

PERIOD: float = 0.5: Blink period, in seconds.

SCROLL_INCREMENT: int = 16: Pixels to scroll viewport per mouse scroll wheel movement. Defaults to 12pt at 96dpi.

property color: tuple[int, int, int, int]

An RGBA tuple of the current caret color.

When blinking off, the alpha channel will be set to 0. The default caret color when visible is (0, 0, 0, 255) (opaque black).

You may set the color to an RGBA or RGB color tuple.

Warning

This setter can fail for a short time after layout / window init!

Use __init__’s color keyword argument instead if you run into this problem.

Each color channel must be between 0 and 255, inclusive. If the color set to an RGB color, the previous alpha channel value will be used.

property layout: IncrementalTextLayout

property line: int

Index of line containing the caret’s position.

When set, position is modified to place the caret on requested line while maintaining the closest possible X offset.

property mark: int

Position of immovable end of text selection within document.

An interactive text selection is determined by its immovable end (the caret’s position when a mouse drag begins) and the caret’s position, which moves interactively by mouse and keyboard input.

This property is None when there is no selection.

property position: int: Position of caret within document.

property visible: bool

Caret visibility.

The caret may be hidden despite this property due to the periodic blinking or by on_deactivate if the event handler is attached to a window.

pyglet.text.document

Formatted and unformatted document interfaces used by text layout.

Abstract representation

Styled text in pyglet is represented by one of the AbstractDocument classes, which manage the state representation of text and style independently of how it is loaded or rendered.

A document consists of the document text (a Unicode string) and a set of named style ranges. For example, consider the following (artificial) example:

0    5   10   15   20
The cat sat on the mat.
+++++++        +++++++    "bold"
            ++++++      "italic"

If this example were to be rendered, “The cat” and “the mat” would be in bold, and “on the” in italics. Note that the second “the” is both bold and italic.

The document styles recorded for this example would be "bold" over ranges (0-7, 15-22) and "italic" over range (12-18). Overlapping styles are permitted; unlike HTML and other structured markup, the ranges need not be nested.

The document has no knowledge of the semantics of "bold" or "italic", it stores only the style names. The pyglet layout classes give meaning to these style names in the way they are rendered; but you are also free to invent your own style names (which will be ignored by the layout classes). This can be useful to tag areas of interest in a document, or maintain references back to the source material.

As well as text, the document can contain arbitrary elements represented by InlineElement. An inline element behaves like a single character in the document, but can be rendered by the application.

Paragraph breaks

Paragraph breaks are marked with a “newline” character (U+0010). The Unicode paragraph break (U+2029) can also be used.

Line breaks (U+2028) can be used to force a line break within a paragraph.

See Unicode recommendation UTR #13 for more information: https://www.unicode.org/standard/reports/tr13/tr13-5.html.

Document classes

Any class implementing AbstractDocument provides an interface to a document model as described above. In theory a structured document such as HTML or XML could export this model, though the classes provided by pyglet implement only unstructured documents.

The UnformattedDocument class assumes any styles set are set over the entire document. So, regardless of the range specified when setting a "bold" style attribute, for example, the entire document will receive that style.

The FormattedDocument class implements the document model directly, using the RunList class to represent style runs efficiently.

Style attributes

The following character style attribute names are recognised by pyglet:

font_name: Font family name, as given to pyglet.font.load().
font_size: Font size, in points.
bold: Boolean.
italic: Boolean.
underline: 4-tuple of ints in range (0, 255) giving RGBA underline color, or None (default) for no underline.
kerning: Additional space to insert between glyphs, in points. Defaults to 0.
baseline: Offset of glyph baseline from line baseline, in points. Positive values give a superscript, negative values give a subscript. Defaults to 0.
color: 4-tuple of ints in range (0, 255) giving RGBA text color
background_color: 4-tuple of ints in range (0, 255) giving RGBA text background color; or None for no background fill.

The following paragraph style attribute names are recognised by pyglet. Note that paragraph styles are handled no differently from character styles by the document: it is the application’s responsibility to set the style over an entire paragraph, otherwise results are undefined.

align: left (default), center or right.
indent: Additional horizontal space to insert before the first
leading: Additional space to insert between consecutive lines within a paragraph, in points. Defaults to 0.
line_spacing: Distance between consecutive baselines in a paragraph, in points. Defaults to None, which automatically calculates the tightest line spacing for each line based on the font ascent and descent.
margin_left: Left paragraph margin, in pixels.
margin_right: Right paragraph margin, in pixels.
margin_top: Margin above paragraph, in pixels.
margin_bottom: Margin below paragraph, in pixels. Adjacent margins do not collapse.
tab_stops: List of horizontal tab stops, in pixels, measured from the left edge of the text layout. Defaults to the empty list. When the tab stops are exhausted, they implicitly continue at 50 pixel intervals.
wrap: Boolean. If True (the default), text wraps within the width of the layout.

Other attributes can be used to store additional style information within the document; it will be ignored by the built-in text classes.

All style attributes (including those not present in a document) default to None (including the so-called “boolean” styles listed above). The meaning of a None style is style- and application-dependent.

class AbstractDocument

Abstract document interface used by all pyglet.text classes.

This class can be overridden to interface pyglet with a third-party document format. It may be easier to implement the document format in terms of one of the supplied concrete classes FormattedDocument or UnformattedDocument.

__init__(text: str = '') → None

Initialize a document with text.

Parameters:: text (str) – Initial text string.

delete_text(start: int, end: int) → None

Delete text from the document.

Dispatches an on_delete_text() event.

Parameters:

start (int) – Starting character position to delete from.
end (int) – Ending character position to delete to (exclusive).

Return type:

get_element(position: int) → InlineElement

Get the element at a specified position.

Parameters:: position (int) – Position in the document of the element.
Return type:: InlineElement

abstract get_font( position: int, dpi: float | None = None, ) → Font

Get the font instance used at the given position.

See:

get_font_runs

Parameters:

position (int) – Character position of document to query.
dpi (float | None) – Optional resolution to construct fonts at. :see: load().

Return type:

Font

abstract get_font_runs( dpi: float | None = None, ) → AbstractRunIterator

Get a style iterator over the pyglet.font.Font instances used in the document.

The font instances are created on-demand by inspection of the font_name, font_size, bold and italic style attributes.

Parameters:: dpi (float | None) – Optional resolution to construct fonts at. :see: load().
Return type:: AbstractRunIterator

get_paragraph_end(pos: int) → int

Get the end position of a paragraph from the character position.

Return type:: int

get_paragraph_start(pos: int) → int

Get the starting position of a paragraph from the character position.

Return type:: int

abstract get_style(attribute: str, position: int = 0) → Any

Get an attribute style at the given position.

Parameters:

attribute (str) – Name of style attribute to query.
position (int) – Character position of document to query.

Return type:

Any

Returns:

The style set for the attribute at the given position.

get_style_range(attribute: str, start: int, end: int) → Any

Get an attribute style over the given range.

If the style varies over the range, STYLE_INDETERMINATE is returned.

Parameters:

attribute (str) – Name of style attribute to query.
start (int) – Starting character position.
end (int) – Ending character position (exclusive).

Return type:

Any

Returns:

The style set for the attribute over the given range, or STYLE_INDETERMINATE if more than one value is set.

abstract get_style_runs( attribute: str, ) → AbstractRunIterator

Get a style iterator over the given style attribute.

Parameters:: attribute (str) – Name of style attribute to query.
Return type:: AbstractRunIterator

insert_element( position: int, element: InlineElement, attributes: dict[str, Any] | None = None, ) → None

Insert a element into the document.

See the InlineElement class documentation for details of usage.

Parameters:

position (int) – Character insertion point within document.
element (InlineElement) – Element to insert.
attributes (dict[str, Any] | None) – dict Optional dictionary giving named style attributes of the inserted text.

Return type:

insert_text( start: int, text: str, attributes: dict[str, Any] | None = None, ) → None

Insert text into the document.

Dispatches an on_insert_text() event.

Parameters:

start (int) – Character insertion point within document.
text (str) – Text to insert.
attributes (dict[str, Any] | None) – Optional dictionary giving named style attributes of the inserted text.

Return type:

on_delete_text(start: int, end: int) → None

Text was deleted from the document.

Parameters:

start (int) – Starting character position of deleted text.
end (int) – Ending character position of deleted text (exclusive).

Event:

Return type:

on_insert_text(start: int, text: str) → None

Text was inserted into the document.

Parameters:

start (int) – Character insertion point within document.
text (str) – The text that was inserted.

Event:

Return type:

on_style_text( start: int, end: int, attributes: dict[str, Any] | None, ) → None

Text character style was modified.

Parameters:

start (int) – Starting character position of modified text.
end (int) – Ending character position of modified text (exclusive).
attributes (dict[str, Any] | None) – Dictionary giving updated named style attributes of the text.

Event:

Return type:

set_paragraph_style( start: int, end: int, attributes: dict[str, Any], ) → None

Set the style for a range of paragraphs.

This is a convenience method for set_style that aligns the character range to the enclosing paragraph(s).

Dispatches an on_style_text() event.

Parameters:

start (int) – Starting character position.
end (int) – Ending character position (exclusive).
attributes (dict[str, Any]) – Dictionary giving named style attributes of the paragraphs.

Return type:

set_style( start: int, end: int, attributes: dict[str, Any], ) → None

Set text style of a range between start and end of the document.

Dispatches an on_style_text() event.

Parameters:

start (int) – Starting character position.
end (int) – Ending character position (exclusive).
attributes (dict[str, Any]) – Dictionary giving named style attributes of the text.

Return type:

event_types: list = ['on_insert_text', 'on_delete_text', 'on_style_text']

property text: str

Document text.

For efficient incremental updates, use the insert_text() and delete_text() methods instead of replacing this property.

class FormattedDocument

Simple implementation of a document that maintains text formatting.

Changes to text style are applied according to the description in AbstractDocument. All styles default to None.

__init__(text: str = '') → None

Initialize a document with text.

Parameters:: text (str) – Initial text string.

get_element_runs() → _ElementIterator

Return type:: _ElementIterator

get_font( position: int, dpi: float | None = None, ) → Font

Get the font instance used at the given position.

See:

get_font_runs

Parameters:

position (int) – Character position of document to query.
dpi (float | None) – Optional resolution to construct fonts at. :see: load().

Return type:

Font

get_font_runs( dpi: float | None = None, ) → _FontStyleRunsRangeIterator

Get a style iterator over the pyglet.font.Font instances used in the document.

The font instances are created on-demand by inspection of the font_name, font_size, bold and italic style attributes.

Parameters:: dpi (float | None) – Optional resolution to construct fonts at. :see: load().
Return type:: _FontStyleRunsRangeIterator

get_style(attribute: str, position: int = 0) → Any | None

Get an attribute style at the given position.

Parameters:

attribute (str) – Name of style attribute to query.
position (int) – Character position of document to query.

Return type:

Any | None

Returns:

The style set for the attribute at the given position.

get_style_runs( attribute: str, ) → RunIterator | _NoStyleRangeIterator

Get a style iterator over the given style attribute.

Parameters:: attribute (str) – Name of style attribute to query.
Return type:: RunIterator | _NoStyleRangeIterator

class InlineElement

Arbitrary inline element positioned within a formatted document.

Elements behave like a single glyph in the document. They are measured by their horizontal advance, ascent above the baseline, and descent below the baseline.

The pyglet layout classes reserve space in the layout for elements and call the element’s methods to ensure they are rendered at the appropriate position.

If the size of an element (any of the advance, ascent, or descent variables) is modified it is the application’s responsibility to trigger a reflow of the appropriate area in the affected layouts. This can be done by forcing a style change over the element’s position.

__init__(ascent: int, descent: int, advance: int) → None

Initialize the element.

Parameters:

ascent (int) – Ascent of the element above the baseline, in pixels.
descent (int) – Descent of the element below the baseline, in pixels. Typically negative.
advance (int) – Width of the element, in pixels.

abstract place( layout: TextLayout, x: float, y: float, z: float, line_x: float, line_y: float, rotation: float, visible: bool, anchor_x: float, anchor_y: float, ) → None

Return type:: None

abstract remove(layout: TextLayout) → None

Return type:: None

abstract update_anchor(anchor_x: float, anchor_y: float) → None

Return type:: None

abstract update_color(color: list[int]) → None

Return type:: None

abstract update_rotation(rotation: float) → None

Return type:: None

abstract update_translation(x: float, y: float, z: float) → None

Return type:: None

abstract update_view_translation(translate_x: float, translate_y: float) → None

Return type:: None

abstract update_visibility(visible: bool) → None

Return type:: None

advance: int

ascent: int

descent: int

property position: int | None

Character position within the document.

Determined by the layout it is in. Will return None if it has not been placed.

class UnformattedDocument

A document having uniform style over all text.

Changes to the style of text within the document affects the entire document. For convenience, the position parameters of the style methods may therefore be omitted.

__init__(text: str = '') → None: Create unformatted document with a string.

get_element_runs() → ConstRunIterator

Return type:: ConstRunIterator

get_font( position: int | None = None, dpi: float | None = None, ) → Font

Get the font instance used at the given position.

See:

get_font_runs

Parameters:

position (int | None) – Character position of document to query.
dpi (float | None) – Optional resolution to construct fonts at. :see: load().

Return type:

Font

get_font_runs( dpi: float | None = None, ) → ConstRunIterator

Get a style iterator over the pyglet.font.Font instances used in the document.

The font instances are created on-demand by inspection of the font_name, font_size, bold and italic style attributes.

Parameters:: dpi (float | None) – Optional resolution to construct fonts at. :see: load().
Return type:: ConstRunIterator

get_style( attribute: str, position: int | None = None, ) → Any

Get an attribute style at the given position.

Parameters:

attribute (str) – Name of style attribute to query.
position (int | None) – Character position of document to query.

Return type:

Any

Returns:

The style set for the attribute at the given position.

get_style_runs( attribute: str, ) → ConstRunIterator

Get a style iterator over the given style attribute.

Parameters:: attribute (str) – Name of style attribute to query.
Return type:: ConstRunIterator

set_paragraph_style( start: int, end: int, attributes: dict[str, Any], ) → None

Set the style for a range of paragraphs.

This is a convenience method for set_style that aligns the character range to the enclosing paragraph(s).

Dispatches an on_style_text() event.

Parameters:

start (int) – Starting character position.
end (int) – Ending character position (exclusive).
attributes (dict[str, Any]) – Dictionary giving named style attributes of the paragraphs.

Return type:

set_style( start: int, end: int, attributes: dict[str, Any], ) → None

Set text style of a range between start and end of the document.

Dispatches an on_style_text() event.

Parameters:

start (int) – Starting character position.
end (int) – Ending character position (exclusive).
attributes (dict[str, Any]) – Dictionary giving named style attributes of the text.

Return type:

ScrollableTextLayout

STYLE_INDETERMINATE = 'indeterminate': The style attribute takes on multiple values in the document.

pyglet.text.layout

Render simple text and formatted documents efficiently.

Three layout classes are provided:

TextLayout

The entire document is laid out before it is rendered. The layout will be grouped with other layouts in the same batch (allowing for efficient rendering of multiple layouts).

Any change to the layout or document, and even querying some properties, will cause the entire document to be laid out again.

Based on TextLayout().

A separate group is used for layout which crops the contents of the layout to the layout rectangle. Additionally, the contents of the layout can be “scrolled” within that rectangle with the view_x and view_y properties.

IncrementalTextLayout

Based on ScrollableTextLayout.

When the layout or document are modified, only the affected regions are laid out again. This permits efficient interactive editing and styling of text.

Only the visible portion of the layout is actually rendered; as the viewport is scrolled additional sections are rendered and discarded as required. This permits efficient viewing and editing of large documents.

Additionally, this class provides methods for locating the position of a caret in the document, and for displaying interactive text selections.

All three layout classes can be used with either UnformattedDocument or FormattedDocument, and can be either single-line or multiline. The combinations of these options effectively provides 12 different text display possibilities.

Style attributes

The following character style attribute names are recognised by the layout classes. Data types and units are as specified.

Where an attribute is marked “as a distance” the value is assumed to be in pixels if given as an int or float, otherwise a string of the form "0u" is required, where 0 is the distance and u is the unit; one of "px" (pixels), "pt" (points), "pc" (picas), "cm" (centimeters), "mm" (millimeters) or "in" (inches). For example, "14pt" is the distance covering 14 points, which at the default DPI of 96 is 18 pixels.

font_name: Font family name, as given to pyglet.font.load().
font_size: Font size, in points.
bold: Boolean.
italic: Boolean.
underline: 4-tuple of ints in range (0, 255) giving RGBA underline color, or None (default) for no underline.
kerning: Additional space to insert between glyphs, as a distance. Defaults to 0.
baseline: Offset of glyph baseline from line baseline, as a distance. Positive values give a superscript, negative values give a subscript. Defaults to 0.
color: 4-tuple of ints in range (0, 255) giving RGBA text color
background_color: 4-tuple of ints in range (0, 255) giving RGBA text background color; or None for no background fill.

The following paragraph style attribute names are recognised. Note that paragraph styles are handled no differently from character styles by the document: it is the application’s responsibility to set the style over an entire paragraph, otherwise results are undefined.

align: left (default), center or right.
indent: Additional horizontal space to insert before the first glyph of the first line of a paragraph, as a distance.
leading: Additional space to insert between consecutive lines within a paragraph, as a distance. Defaults to 0.
line_spacing: Distance between consecutive baselines in a paragraph, as a distance. Defaults to None, which automatically calculates the tightest line spacing for each line based on the font ascent and descent.
margin_left: Left paragraph margin, as a distance.
margin_right: Right paragraph margin, as a distance.
margin_top: Margin above paragraph, as a distance.
margin_bottom: Margin below paragraph, as a distance. Adjacent margins do not collapse.
tab_stops: List of horizontal tab stops, as distances, measured from the left edge of the text layout. Defaults to the empty list. When the tab stops are exhausted, they implicitly continue at 50 pixel intervals.
wrap: char, word, True (default) or False. The boundaries at which to wrap text to prevent it overflowing a line. With char, the line wraps anywhere in the text; with word or True, the line wraps at appropriate boundaries between words; with False the line does not wrap, and may overflow the layout width.

Other attributes can be used to store additional style information within the document; they will be ignored by the built-in text classes.

class IncrementalTextDecorationGroup

scissor_area: ClassVar[tuple[int, int, int, int]] = (0, 0, 0, 0)

class IncrementalTextLayout

Displayed text suitable for interactive editing and/or scrolling large documents.

Unlike TextLayout() and ScrollableTextLayout, this class generates vertex lists only for lines of text that are visible. As the document is scrolled, vertex lists are deleted and created as appropriate to keep video memory usage to a minimum and improve rendering speed.

Changes to the document are quickly reflected in this layout, as only the affected line(s) are reflowed. Use begin_update() and end_update() to further reduce the amount of processing required.

The layout can also display a text selection (text with a different background color). The Caret class implements a visible text cursor and provides event handlers for scrolling, selecting and editing text in an incremental text layout.

Class Variables:

group_class (ClassVar[type[IncrementalTextLayoutGroup]]) – Default group used to set the state for all glyphs.
decoration_class (ClassVar[type[IncrementalTextDecorationGroup]]) – Default group used to set the state for all decorations including background colors and underlines.

__init__( document: AbstractDocument, x: float = 0, y: float = 0, z: float = 0, width: int = None, height: int = None, anchor_x: Literal['left', 'center', 'right'] = 'left', anchor_y: Literal['top', 'bottom', 'center', 'baseline'] = 'bottom', rotation: float = 0, multiline: bool = False, dpi: float | None = None, batch: Batch | None = None, group: Group | None = None, program: ShaderProgram | None = None, wrap_lines: bool = True, ) → None

Create a text layout.

Parameters:

document (AbstractDocument) – Document to display.
x (float) – X coordinate of the label.
y (float) – Y coordinate of the label.
z (float) – Z coordinate of the label.
width (int) – Width of the layout in pixels, or None
height (int) – Height of the layout in pixels, or None
anchor_x (Literal['left', 'center', 'right']) – Anchor point of the X coordinate.
anchor_y (Literal['top', 'bottom', 'center', 'baseline']) – Anchor point of the Y coordinate.
rotation (float) – The amount to rotate the label in degrees. A positive amount will be a clockwise rotation, negative values will result in counter-clockwise rotation.
multiline (bool) – If False, newline and paragraph characters are ignored, and text is not word-wrapped. If True, text is wrapped only if the wrap_lines is True.
dpi (float | None) – Font resolution; defaults to 96.
batch (Batch | None) – Optional graphics batch to add this layout to.
group (Group | None) – Optional Group to parent all internal Groups that this text layout uses. Note that layouts with the same Groups will be rendered simultaneously in a Batch.
program (ShaderProgram | None) – Optional graphics shader to use. Will affect all glyphs in the layout.
wrap_lines (bool) – If True and multiline is True, the text is word-wrapped using the specified width.
init_document – If True the document will be initialized. If subclassing then you may want to avoid duplicate initializations by changing to False.

delete() → None

Deletes all vertices and boxes associated with the layout.

Return type:: None

ensure_line_visible(line_idx: int) → None

Adjust view_y so that the line with the given index is visible.

Return type:: None

ensure_x_visible(x: float) → None

Adjust view_x so that the given X coordinate is visible.

The X coordinate is given relative to the current view_x.

Return type:: None

get_line_count() → int

Get the number of lines in the text layout.

Return type:: int

get_line_from_point(x: float, y: float) → int

Get the closest line index to a point.

Return type:: int

get_line_from_position(position: int) → int

Get the line index of a character position in the document.

Return type:: int

get_point_from_line(line_idx: int) → tuple[float, float]

Get the X, Y coordinates of a line index.

Return type:: tuple[float, float]

get_point_from_position( position: int, line_idx: int | None = None, ) → tuple[float, float]

Get the X, Y coordinates of a character position in the document.

The position that ends a line has an ambiguous point: it can be either the end of the line, or the beginning of the next line. You may optionally specify a line index to disambiguate the case.

The resulting Y coordinate gives the baseline of the line.

Return type:: tuple[float, float]

get_position_from_line(line_idx: int) → int

Get the first document character position of a given line index.

Return type:: int

get_position_from_point(x: float, y: float) → int

Get the closest document position to a point.

Return type:: int

get_position_on_line(line_idx: int, x: float) → int

Get the closest document position for a given line index and X coordinate.

Return type:: int

on_delete_text(start: int, end: int) → None

Event handler for AbstractDocument.on_delete_text.

The event handler is bound by the text layout; there is no need for applications to interact with this method.

Return type:: None

on_insert_text(start: int, text: str) → None

Event handler for AbstractDocument.on_insert_text.

The event handler is bound by the text layout; there is no need for applications to interact with this method.

Return type:: None

on_layout_update() → None

Some or all of the layout text was reflowed.

Text reflow is caused by document edits or changes to the layout’s size. Changes to the layout’s position or active selection, and certain document edits such as text color, do not cause a reflow.

Handle this event to update the position of a graphical element that depends on the laid out position of a glyph or line.

Event:
Return type:: None

on_style_text( start: int, end: int, attributes: dict[str, Any], ) → None

Event handler for AbstractDocument.on_style_text.

The event handler is bound by the text layout; there is no need for applications to interact with this method.

Return type:: None

set_selection(start: int, end: int) → None

Set the text selection range.

If start equals end no selection will be visible.

Parameters:

start (int) – Starting character position of selection.
end (int) – End of selection, exclusive.

Return type:

property anchor_x: Literal['left', 'center', 'right']

Horizontal anchor alignment.

This property determines the meaning of the x coordinate.

The following values are supported:

"left" (default): The X coordinate gives the position of the left edge of the layout.
"center": The X coordinate gives the position of the center of the layout.
"right": The X coordinate gives the position of the right edge of the layout.

For the purposes of calculating the position resulting from this alignment, the width of the layout is taken to be width if multiline is True and wrap_lines is True, otherwise content_width.

property anchor_y: Literal['top', 'bottom', 'center', 'baseline']

Vertical anchor alignment.

This property determines the meaning of the y coordinate.

The following values are supported:

"top": The Y coordinate gives the position of the top edge of the layout.
"center": The Y coordinate gives the position of the center of the layout.
"baseline": The Y coordinate gives the position of the baseline of the first line of text in the layout.
"bottom" (default): The Y coordinate gives the position of the bottom edge of the layout.

For the purposes of calculating the position resulting from this alignment, the height of the layout is taken to be the smallest of height and content_height.

pyglet.window

Submodules

pyglet.window.key

Key constants and utilities for pyglet.window.

Usage:

from pyglet.window import Window
from pyglet.window import key

window = Window()

@window.event
def on_key_press(symbol, modifiers):
    # Symbolic names:
    if symbol == key.RETURN:

    # Alphabet keys:
    elif symbol == key.Z:

    # Number keys:
    elif symbol == key._1:

    # Number keypad keys:
    elif symbol == key.NUM_1:

    # Modifiers:
    if modifiers & key.MOD_CTRL:

class KeyStateHandler

Simple handler that tracks the state of keys on the keyboard. If a key is pressed then this handler holds a True value for it. If the window loses focus, all keys will be reset to False to avoid a “sticky” key state.

For example:

>>> win = window.Window
>>> keyboard = key.KeyStateHandler()
>>> win.push_handlers(keyboard)

# Hold down the "up" arrow...

>>> keyboard[key.UP]
True
>>> keyboard[key.DOWN]
False

__init__()

modifiers_string(modifiers)

Return a string describing a set of modifiers.

Example:

>>> modifiers_string(MOD_SHIFT | MOD_CTRL)
'MOD_SHIFT|MOD_CTRL'

Parameters:

modifiersint: Bitwise combination of modifier constants.

Return type:

motion_string(motion)

Return a string describing a text motion.

Example:

>>> motion_string(MOTION_NEXT_WORD)
'MOTION_NEXT_WORD'

Parameters:

motionint: Text motion constant.

Return type:

symbol_string(symbol)

Return a string describing a key symbol.

Example:

>>> symbol_string(BACKSPACE)
'BACKSPACE'

Parameters:

symbolint: Symbolic key constant.

Return type:

user_key(scancode)

Return a key symbol for a key not supported by pyglet.

This can be used to map virtual keys or scancodes from unsupported keyboard layouts into a machine-specific symbol. The symbol will be meaningless on any other machine, or under a different keyboard layout.

Applications should use user-keys only when user explicitly binds them (for example, mapping keys to actions in a game options screen).

Key Constants

Modifier mask constants

MOD_SHIFT

MOD_CTRL

MOD_ALT

MOD_CAPSLOCK

MOD_NUMLOCK

MOD_WINDOWS

MOD_COMMAND

MOD_OPTION

MOD_SCROLLLOCK

MOD_FUNCTION

MOD_ACCEL (MOD_CTRL on Windows & Linux, MOD_CMD on OS X)

ASCII commands

BACKSPACE

TAB

LINEFEED

CLEAR

RETURN

ENTER

PAUSE

SCROLLLOCK

SYSREQ

ESCAPE

SPACE

Cursor control and motion

HOME

LEFT

UP

RIGHT

DOWN

PAGEUP

PAGEDOWN

END

BEGIN

Misc functions

DELETE

SELECT

PRINT

EXECUTE

INSERT

UNDO

REDO

MENU

FIND

CANCEL

HELP

BREAK

MODESWITCH

SCRIPTSWITCH

FUNCTION

Text motion constants

These are allowed to clash with key constants because they abstract common text motions from their platform-specific keyboard shortcuts. See Motion events for more information.

MOTION_UP

MOTION_RIGHT

MOTION_DOWN

MOTION_LEFT

MOTION_COPY

MOTION_PASTE

MOTION_NEXT_WORD

MOTION_PREVIOUS_WORD

MOTION_BEGINNING_OF_LINE

MOTION_END_OF_LINE

MOTION_NEXT_PAGE

MOTION_PREVIOUS_PAGE

MOTION_BEGINNING_OF_FILE

MOTION_END_OF_FILE

MOTION_BACKSPACE

MOTION_DELETE

Number pad

NUMLOCK

NUM_SPACE

NUM_TAB

NUM_ENTER

NUM_F1

NUM_F2

NUM_F3

NUM_F4

NUM_HOME

NUM_LEFT

NUM_UP

NUM_RIGHT

NUM_DOWN

NUM_PRIOR

NUM_PAGE_UP

NUM_NEXT

NUM_PAGE_DOWN

NUM_END

NUM_BEGIN

NUM_INSERT

NUM_DELETE

NUM_EQUAL

NUM_MULTIPLY

NUM_ADD

NUM_SEPARATOR

NUM_SUBTRACT

NUM_DECIMAL

NUM_DIVIDE

NUM_0

NUM_1

NUM_2

NUM_3

NUM_4

NUM_5

NUM_6

NUM_7

NUM_8

NUM_9

Function keys

F1

F2

F3

F4

F5

F6

F7

F8

F9

F10

F11

F12

F13

F14

F15

F16

F17

F18

F19

F20

Modifiers

LSHIFT

RSHIFT

LCTRL

RCTRL

CAPSLOCK

LMETA

RMETA

LALT

RALT

LWINDOWS

RWINDOWS

LCOMMAND

RCOMMAND

LOPTION

ROPTION

Latin-1

SPACE

EXCLAMATION

DOUBLEQUOTE

HASH

POUND

DOLLAR

PERCENT

AMPERSAND

APOSTROPHE

PARENLEFT

PARENRIGHT

ASTERISK

PLUS

COMMA

MINUS

PERIOD

SLASH

_0

_1

_2

_3

_4

_5

_6

_7

_8

_9

COLON

SEMICOLON

LESS

EQUAL

GREATER

QUESTION

AT

BRACKETLEFT

BACKSLASH

BRACKETRIGHT

ASCIICIRCUM

UNDERSCORE

GRAVE

QUOTELEFT

A

B

C

D

E

F

G

H

I

J

K

L

M

N

O

P

Q

R

S

T

U

V

W

X

Y

Z

BRACELEFT

BAR

BRACERIGHT

ASCIITILDE

pyglet.window.mouse

Mouse constants and utilities for pyglet.window.

class MouseStateHandler

Simple handler that tracks the state of buttons from the mouse. If a button is pressed then this handler holds a True value for it. If the window loses focus, all buttons will be reset to False in order to avoid a “sticky” button state.

For example:

>>> win = window.Window()
>>> mousebuttons = mouse.MouseStateHandler()
>>> win.push_handlers(mousebuttons)

# Hold down the "left" button...

>>> mousebuttons[mouse.LEFT]
True
>>> mousebuttons[mouse.RIGHT]
False

__init__()

buttons_string(buttons)

Return a string describing a set of active mouse buttons.

Example:

>>> buttons_string(LEFT | RIGHT)
'LEFT|RIGHT'

Parameters:

buttonsint: Bitwise combination of mouse button constants.

Return type:

LEFT

Constant for the left mouse button.

MIDDLE

Constant for the middle mouse button.

MOUSE4

Constant for the mouse4 button.

MOUSE5

Constant for the mouse5 button.

RIGHT

Constant for the right mouse button.

Details

Windowing and user-interface events.

This module allows applications to create and display windows with an OpenGL context. Windows can be created with a variety of border styles or set fullscreen.

You can register event handlers for keyboard, mouse and window events. For games and kiosks you can also restrict the input to your windows, for example disabling users from switching away from the application with certain key combinations or capturing and hiding the mouse.

Getting started

Call the Window constructor to create a new window:

from pyglet.window import Window
win = Window(width=960, height=540)

Attach your own event handlers:

@win.event
def on_key_press(symbol, modifiers):
    # ... handle this event ...

Place drawing code for the window within the Window.on_draw event handler:

@win.event
def on_draw():
    # ... drawing code ...

Call pyglet.app.run to enter the main event loop (by default, this returns when all open windows are closed):

from pyglet import app
app.run()

Creating a game window

Use set_exclusive_mouse() to hide the mouse cursor and receive relative mouse movement events. Specify fullscreen=True as a keyword argument to the Window constructor to render to the entire screen rather than opening a window:

win = Window(fullscreen=True)
win.set_exclusive_mouse()

Working with multiple screens

By default, fullscreen windows are opened on the primary display (typically set by the user in their operating system settings). You can retrieve a list of attached screens and select one manually if you prefer. This is useful for opening a fullscreen window on each screen:

display = pyglet.display.get_display()
screens = display.get_screens()
windows = []
for screen in screens:
    windows.append(window.Window(fullscreen=True, screen=screen))

Specifying a screen has no effect if the window is not fullscreen.

Specifying the OpenGL context properties

Each window has its own context which is created when the window is created. You can specify the properties of the context before it is created by creating a “template” configuration:

from pyglet import gl
# Create template config
config = gl.Config()
config.stencil_size = 8
config.aux_buffers = 4
# Create a window using this config
win = window.Window(config=config)

To determine if a given configuration is supported, query the screen (see above, “Working with multiple screens”):

configs = screen.get_matching_configs(config)
if not configs:
    # ... config is not supported
else:
    win = window.Window(config=configs[0])

Classes

class Window

Platform-independent application window.

A window is a “heavyweight” object occupying operating system resources. The “client” or “content” area of a window is filled entirely with an OpenGL viewport. Applications have no access to operating system widgets or controls; all rendering must be done via OpenGL.

Windows may appear as floating regions or can be set to fill an entire screen (fullscreen). When floating, windows may appear borderless or decorated with a platform-specific frame (including, for example, the title bar, minimize and close buttons, resize handles, and so on).

While it is possible to set the location of a window, it is recommended that applications allow the platform to place it according to local conventions. This will ensure it is not obscured by other windows, and appears on an appropriate screen for the user.

To render into a window, you must first call its switch_to() method to make it the active OpenGL context. If you use only one window in your application, you can skip this step as it will always be the active context.

Methods

activate()

Attempt to restore keyboard focus to the window.

Depending on the window manager or operating system, this may not be successful. For example, on Windows XP an application is not allowed to “steal” focus from another application. Instead, the window’s taskbar icon will flash, indicating it requires attention.

static clear()

Clear the window.

This is a convenience method for clearing the color and depth buffer. The window must be the active context (see switch_to()).

close()

Close the window.

After closing the window, the GL context will be invalid. The window instance cannot be reused once closed. To re-use windows, see set_visible() instead.

The pyglet.app.EventLoop.on_window_close() event is dispatched by the pyglet.app.event_loop when this method is called.

dispatch_event(*args)

Dispatch an event to the attached event handlers.

The event is propagated to all registered event handlers in the stack, starting and the top and going down. If any registered event handler returns EVENT_HANDLED, no further handlers down the stack will receive this event.

This method has several possible return values. If any event hander has returned EVENT_HANDLED, then this method will also return EVENT_HANDLED. If not, this method will return EVENT_UNHANDLED. If there were no events registered to receive this event, False is returned.

Returns:: EVENT_HANDLED if any event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked without any of them returning EVENT_HANDLED; False if no event handlers were registered.

dispatch_events()

Poll the operating system event queue for new events and call attached event handlers.

This method is provided for legacy applications targeting pyglet 1.0, and advanced applications that must integrate their event loop into another framework.

Typical applications should use pyglet.app.run().

draw_mouse_cursor()

Draw the custom mouse cursor.

If the current mouse cursor has drawable set, this method is called before the buffers are flipped to render it.

There is little need to override this method; instead, subclass MouseCursor and provide your own draw() method.

flip()

Swap the OpenGL front and back buffers.

Call this method on a double-buffered window to update the visible display with the back buffer. Windows are double-buffered by default unless you turn this feature off.

The contents of the back buffer are undefined after this operation.

The default event_loop automatically calls this method after the window’s on_draw() event.

get_framebuffer_size()

Return the size in actual pixels of the Window framebuffer.

When using HiDPI screens, the size of the Window’s framebuffer can be higher than that of the Window size requested. If you are performing operations that require knowing the actual number of pixels in the window, this method should be used instead of Window.get_size(). For example, setting the Window projection or setting the glViewport size.

Return type:: (int, int)
Returns:: The width and height of the Window’s framebuffer, in pixels.

get_location()

Return the current position of the window.

Return type:: (int, int)
Returns:: The distances of the left and top edges from their respective edges on the virtual desktop, in pixels.

get_pixel_ratio()

Return the framebuffer/window size ratio.

Some platforms and/or window systems support subpixel scaling, making the framebuffer size larger than the window size. Retina screens on OS X and Gnome on Linux are some examples.

On a Retina systems the returned ratio would usually be 2.0 as a window of size 500 x 500 would have a framebuffer of 1000 x 1000. Fractional values between 1.0 and 2.0, as well as values above 2.0 may also be encountered.

Return type:: float
Returns:: The framebuffer/window size ratio

get_size() → Tuple[int, int]

Return the current size of the window.

This does not include the windows’ border or title bar.

Return type:: (int, int)
Returns:: The width and height of the window, in pixels.

get_system_mouse_cursor(name)

Obtain a system mouse cursor.

Use set_mouse_cursor to make the cursor returned by this method active. The names accepted by this method are the CURSOR_* constants defined on this class.

Parameters:

namestr: Name describing the mouse cursor to return. For example, CURSOR_WAIT, CURSOR_HELP, etc.

Return type:

MouseCursor

Returns:

A mouse cursor which can be used with set_mouse_cursor.

maximize()

Maximize the window.

The behaviour of this method is somewhat dependent on the user’s display setup. On a multi-monitor system, the window may maximize to either a single screen or the entire virtual desktop.

minimize(): Minimize the window.

set_caption(caption)

Set the window’s caption.

The caption appears in the titlebar of the window, if it has one, and in the taskbar on Windows and many X11 window managers.

Parameters:

captionstr or unicode: The caption to set.

set_exclusive_keyboard(exclusive=True)

Prevent the user from switching away from this window using keyboard accelerators.

When enabled, this feature disables certain operating-system specific key combinations such as Alt+Tab (Command+Tab on OS X). This can be useful in certain kiosk applications, it should be avoided in general applications or games.

Parameters:

exclusivebool: If True, exclusive keyboard is enabled, otherwise it is disabled.

set_exclusive_mouse(exclusive=True)

Hide the mouse cursor and direct all mouse events to this window.

When enabled, this feature prevents the mouse leaving the window. It is useful for certain styles of games that require complete control of the mouse. The position of the mouse as reported in subsequent events is meaningless when exclusive mouse is enabled; you should only use the relative motion parameters dx and dy.

Parameters:

exclusivebool: If True, exclusive mouse is enabled, otherwise it is disabled.

set_fullscreen( fullscreen=True, screen=None, mode=None, width=None, height=None, )

Toggle to or from fullscreen.

After toggling fullscreen, the GL context should have retained its state and objects, however the buffers will need to be cleared and redrawn.

If width and height are specified and fullscreen is True, the screen may be switched to a different resolution that most closely matches the given size. If the resolution doesn’t match exactly, a higher resolution is selected and the window will be centered within a black border covering the rest of the screen.

Parameters:

fullscreenbool: True if the window should be made fullscreen, False if it should be windowed.
screenScreen: If not None and fullscreen is True, the window is moved to the given screen. The screen must belong to the same display as the window.
modeScreenMode: The screen will be switched to the given mode. The mode must have been obtained by enumerating Screen.get_modes. If None, an appropriate mode will be selected from the given width and height.
widthint: Optional width of the window. If unspecified, defaults to the previous window size when windowed, or the screen size if fullscreen.

New in version 1.2.
heightint: Optional height of the window. If unspecified, defaults to the previous window size when windowed, or the screen size if fullscreen.

New in version 1.2.

set_icon(*images)

Set the window icon.

If multiple images are provided, one with an appropriate size will be selected (if the correct size is not provided, the image will be scaled).

Useful sizes to provide are 16x16, 32x32, 64x64 (Mac only) and 128x128 (Mac only).

Parameters:

imagessequence of pyglet.image.AbstractImage: List of images to use for the window icon.

set_location(x, y)

Set the position of the window.

Parameters:

xint: Distance of the left edge of the window from the left edge of the virtual desktop, in pixels.
yint: Distance of the top edge of the window from the top edge of the virtual desktop, in pixels.

set_maximum_size(width: int, height: int) → None

Set the maximum size of the window.

Once set, the user will not be able to resize the window larger than the given dimensions. There is no way to remove the maximum size constraint on a window (but you could set it to a large value).

The behaviour is undefined if the maximum size is set smaller than the current size of the window.

The window size does not include the border or title bar.

Parameters:

widthint: Maximum width of the window, in pixels.
heightint: Maximum height of the window, in pixels.

Return type:

set_minimum_size(width: int, height: int) → None

Set the minimum size of the window.

Once set, the user will not be able to resize the window smaller than the given dimensions. There is no way to remove the minimum size constraint on a window (but you could set it to 0,0).

The behaviour is undefined if the minimum size is set larger than the current size of the window.

The window size does not include the border or title bar.

Parameters:

widthint: Minimum width of the window, in pixels.
heightint: Minimum height of the window, in pixels.

Return type:

set_mouse_cursor(cursor=None)

Change the appearance of the mouse cursor.

The appearance of the mouse cursor is only changed while it is within this window.

Parameters:

cursorMouseCursor: The cursor to set, or None to restore the default cursor.

set_mouse_platform_visible(platform_visible=None)

Set the platform-drawn mouse cursor visibility. This is called automatically after changing the mouse cursor or exclusive mode.

Applications should not normally need to call this method, see set_mouse_visible instead.

Parameters:

platform_visiblebool or None: If None, sets platform visibility to the required visibility for the current exclusive mode and cursor type. Otherwise, a bool value will override and force a visibility.

set_mouse_visible(visible=True)

Show or hide the mouse cursor.

The mouse cursor will only be hidden while it is positioned within this window. Mouse events will still be processed as usual.

Parameters:

visiblebool: If True, the mouse cursor will be visible, otherwise it will be hidden.

set_size(width: int, height: int) → None

Resize the window.

The behaviour is undefined if the window is not resizable, or if it is currently fullscreen.

The window size does not include the border or title bar.

Parameters:

widthint: New width of the window, in pixels.
heightint: New height of the window, in pixels.

Return type:

set_visible(visible: bool = True) → None

Show or hide the window.

Parameters:

visiblebool: If True, the window will be shown; otherwise it will be hidden.

Return type: