pyglet Documentation

Attention

This documentation is for the pyglet 2.x series, which has incompatible changes from the 1.5 and older releases. If you are looking for documentation for the previous stable release, please see 1.5 maintenance.

pyglet is a cross-platform windowing and multimedia library for Python, intended for developing games and other visually rich applications. It supports windowing, user interface event handling, game controllers and joysticks, OpenGL graphics, loading images and videos, and playing sounds and music. pyglet works on Windows, OS X and Linux.

Some of the features of pyglet are:

• No external dependencies or installation requirements. For most application and game requirements, pyglet needs nothing else besides Python, simplifying distribution and installation.

• Take advantage of multiple windows and multi-monitor desktops. pyglet allows you to use as many windows as you need, and is fully aware of multi-monitor setups for use with fullscreen games and applications.

• Load images, sound, music and video in almost any format. pyglet has built-in support for common audio and image formats, and can optionally use ffmpeg to load almost any other compressed audio or video files.

• pyglet is provided under the BSD open-source license, allowing you to use it for both commercial and other open-source projects with very little restriction.

Please join our Discord server, or join us on the mailing list!

If this is your first time reading about pyglet, we suggest you start at Writing a pyglet application. If you are migrating from an older version of pyglet, please read through Migrating from pyglet 1.5.

Programming Guide

• Installation
  • Running the examples
• Writing a pyglet application
  • Hello, World
  • Image viewer
  • Handling mouse and keyboard events
  • Playing sounds and music
  • Where to next?
• Windowing
  • Creating a window
    • OpenGL Context configuration
    • Fullscreen windows
    • Size and position
  • Appearance
    • Window style
    • Caption
    • Icon
  • Visibility
  • Subclassing Window
  • Windows and OpenGL contexts
    • Double-buffering
    • Vertical retrace synchronisation
• Keyboard input
  • Keyboard events
    • Defined key symbols
    • Modifiers
    • User-defined key symbols
    • Remembering key state
  • Text and motion events
    • Motion events
  • Keyboard exclusivity
• Mouse input
  • Mouse events
  • Changing the mouse cursor
  • Mouse exclusivity
• Controller & Joystick input
  • Using Controllers
    • Rumble
    • ControllerManager
  • Using Joysticks
  • Using the Apple Remote
  • Low-level Devices
• Drawing Shapes
  • Creating a Shape
    • Anchor Points
• Images and Sprites
  • Loading an image
  • Displaying images
    • Sprites
    • Simple image blitting
  • Supported image decoders
  • Supported image formats
  • Working with images
  • The AbstractImage hierarchy
  • Accessing or providing pixel data
    • Performance concerns
  • Image sequences and atlases
    • Image grids
    • 3D textures
    • Texture bins and atlases
  • Animations
  • Buffer images
  • OpenGL imaging
    • Texture dimensions
    • Texture internal format
    • Texture filtering
  • Saving an image
• Playing Sound and Video
  • Audio drivers
    • XAudio2
    • DirectSound
    • OpenAL
    • Pulse
  • Supported media types
    • Windows Media Foundation
    • GStreamer
    • CoreAudio
    • PyOgg
    • FFmpeg
  • FFmpeg installation
  • Loading media
  • Audio Synthesis
  • Simple audio playback
  • Controlling playback
  • Gapless playback
  • Incorporating video
  • Positional audio
  • Ticking the clock
• Displaying text
  • Simple text rendering
  • The document/layout model
    • Documents
    • Layouts
  • Formatted text
    • Character styles
    • Paragraph styles
    • Attributed text
    • HTML
  • Custom elements
  • User-editable text
  • Loading system fonts
  • Font sizes
    • Font resolution
    • Determining font size
  • Loading custom fonts
    • Supported font formats
  • OpenGL font considerations
    • Context affinity
    • Blend state
• Application resources
  • Loading resources
    • Resource locations
  • Specifying the resource path
  • Multiple loaders
  • Saving user preferences and data
• Shaders and Rendering
  • Working with Shaders
    • Creating a Shader Program
    • Uniforms
    • Uniform Buffer Objects (Uniform Blocks)
    • Creating Vertex Lists
  • Batched rendering
    • Setting the OpenGL state
    • Shader state
    • Hierarchical state
    • Drawing order
    • Visibility
  • Batches and groups in other modules
• Dispatching Events
  • Setting event handlers
  • Stacking event handlers
  • Creating your own event dispatcher
    • Implementing the Observer pattern
• Keeping track of time
  • Calling functions periodically
  • Sprite movement techniques
  • Displaying the frame rate
  • User-defined clocks
• Creating an OpenGL context
  • Displays, screens, configs and contexts
    • Contexts and configs
    • Displays
    • Screens
  • OpenGL configuration options
    • The default configuration
  • Simple context configuration
  • Selecting the best configuration
  • Sharing objects between contexts
• The OpenGL interface
  • Using OpenGL
  • Resizing the window
  • Error checking
  • Using extension functions
  • Using multiple windows
  • AGL, GLX and WGL
• Matrix and Vector Math
  • Creating a Matrix
  • Matrix Multiplication
  • Helper Methods
• The application event loop
  • Customising the event loop
    • Event loop events
    • Overriding the default idle policy
  • Dispatching events manually
• In-depth game example
  • Basic graphics
    • Setting up
    • Getting a window
    • Loading and displaying an image
    • Centering the images
    • Initializing objects
    • Making the labels
    • Drawing the labels
    • Making the player and asteroid sprites
  • Basic motion
    • Drawing with batches
    • Displaying little ship icons
    • Making things move
    • Writing the game update function
    • Calling the update() function
    • Writing the Player class
    • Integrating the player class
  • Giving the player something to do
    • Simplifying player input
    • Adding an engine flame
    • Loading the flame image
    • Creating and drawing the flame
    • Cleaning up after death
    • Checking For collisions
    • Checking all object pairs
    • Implementing the collision functions
  • Collision response
    • Adding objects during play
    • Tweaking the game loop
    • Putting the attribute in PhysicalObject
    • Adding bullets
    • Firing bullets
    • Customizing collision behavior
    • Customizing bullet collisions
    • Making asteroids explode
    • Writing the asteroid class
  • Next steps
• Runtime Options
  • options
  • version
  • Environment settings
• Debugging tools
  • Debugging OpenGL
    • Error checking
    • Tracing
  • Tracing execution
  • Platform-specific debugging
    • Linux
    • Windows
• Migrating from pyglet 1.5
  • General Changes
    • Sprites and Labels
    • Groups
    • Window Projection and Cameras
    • Application Event Loop
  • Graphics module

API Reference

• pyglet
• pyglet.app
  • Applications
    • Events
  • Classes
    • EventLoop
    • PlatformEventLoop
  • Functions
    • run()
    • exit()
  • Attributes
    • event_loop
    • platform_event_loop
    • windows
  • Exceptions
    • AppException
• pyglet.canvas
  • get_display()
  • Display
    • Display.get_default_screen()
    • Display.get_screens()
    • Display.get_windows()
    • Display.name
    • Display.x_screen
  • Screen
    • Screen.get_best_config()
    • Screen.get_closest_mode()
    • Screen.get_matching_configs()
    • Screen.get_mode()
    • Screen.get_modes()
    • Screen.restore_mode()
    • Screen.set_mode()
    • Screen.display
    • Screen.height
    • Screen.width
    • Screen.x
    • Screen.y
  • Canvas
    • Canvas.display
• pyglet.clock
  • Scheduling
  • Using multiple clocks
  • Clock
    • Clock.call_scheduled_functions()
    • Clock.get_frequency()
    • Clock.get_sleep_time()
    • Clock.schedule()
    • Clock.schedule_interval()
    • Clock.schedule_interval_for_duration()
    • Clock.schedule_interval_soft()
    • Clock.schedule_once()
    • Clock.sleep()
    • Clock.tick()
    • Clock.unschedule()
    • Clock.update_time()
  • get_default()
  • get_frequency()
  • get_sleep_time()
  • schedule()
  • schedule_interval()
  • schedule_interval_soft()
  • schedule_once()
  • set_default()
  • tick()
  • unschedule()
• pyglet.event
  • Event types
  • Attaching event handlers
  • Event handler stack
  • Dispatching events
  • EventException
  • EventDispatcher
    • EventDispatcher.dispatch_event()
    • EventDispatcher.event()
    • EventDispatcher.pop_handlers()
    • EventDispatcher.push_handlers()
    • EventDispatcher.register_event_type()
    • EventDispatcher.remove_handler()
    • EventDispatcher.remove_handlers()
    • EventDispatcher.set_handler()
    • EventDispatcher.set_handlers()
• pyglet.font
  • add_directory()
  • add_file()
  • have_font()
  • load()
• pyglet.gl
  • ConfigException
  • ContextException
  • current_context
  • GLException
  • ObjectSpace
  • Config
    • Config.create_context()
    • Config.get_gl_attributes()
    • Config.is_complete()
    • Config.match()
    • Config.debug
    • Config.forward_compatible
    • Config.major_version
    • Config.minor_version
    • Config.opengl_api
  • CanvasConfig
    • CanvasConfig.compatible()
    • CanvasConfig.create_context()
    • CanvasConfig.is_complete()
  • Context
    • Context.attach()
    • Context.delete_buffer()
    • Context.delete_shader_program()
    • Context.delete_texture()
    • Context.delete_vao()
    • Context.destroy()
    • Context.detach()
    • Context.get_info()
    • Context.set_current()
• pyglet.graphics
  • pyglet.graphics.allocation
    • AllocatorMemoryException
    • Allocator
  • pyglet.graphics.shader
    • ShaderException
    • Attribute
    • ComputeShaderProgram
    • Shader
    • ShaderProgram
    • ShaderSource
    • UniformBlock
    • UniformBufferObject
  • pyglet.graphics.vertexbuffer
    • AbstractBuffer
    • AbstractMappable
    • BufferObject
    • BufferObjectRegion
    • MappableBufferObject
  • pyglet.graphics.vertexdomain
    • IndexedVertexDomain
    • IndexedVertexList
    • VertexDomain
    • VertexList
  • Batch
    • Batch.draw()
    • Batch.draw_subset()
    • Batch.get_domain()
    • Batch.invalidate()
    • Batch.migrate()
  • Group
    • Group.set_state()
    • Group.set_state_recursive()
    • Group.unset_state()
    • Group.unset_state_recursive()
    • Group.batches
    • Group.order
    • Group.visible
  • ShaderGroup
    • ShaderGroup.set_state()
    • ShaderGroup.unset_state()
  • TextureGroup
    • TextureGroup.set_state()
  • draw()
  • draw_indexed()
  • get_default_batch()
  • get_default_group()
  • get_default_shader()
• pyglet.gui
  • Classes
    • WidgetBase
    • PushButton
    • ToggleButton
    • Slider
    • TextEntry
• pyglet.image
  • pyglet.image.atlas
    • AllocatorException
    • Allocator
    • TextureArrayBin
    • TextureAtlas
    • TextureBin
  • pyglet.image.animation
    • Animation
    • AnimationFrame
  • Drawing images
  • Texture access
  • Pixel access
  • Classes
    • Images
    • Image Sequences
    • Patterns
    • Data
    • Other Classes
  • Functions
    • create()
    • get_buffer_manager()
    • load()
    • load_animation()
    • get_max_texture_size()
  • Exceptions
    • ImageException
    • ImageEncodeException
    • ImageDecodeException
• pyglet.info
  • dump()
  • dump_al()
  • dump_ffmpeg()
  • dump_gl()
  • dump_glx()
  • dump_media()
  • dump_platform()
  • dump_pyglet()
  • dump_python()
  • dump_window()
  • dump_wintab()
• pyglet.input
  • Classes
    • ControllerManager
    • Device
    • Control
    • RelativeAxis
    • AbsoluteAxis
    • Button
    • Controller
    • Joystick
    • AppleRemote
    • Tablet
  • Functions
    • get_apple_remote()
    • get_devices()
    • get_controllers()
    • get_joysticks()
    • get_tablets()
  • Exceptions
    • DeviceException
    • DeviceOpenException
    • DeviceExclusiveException
• pyglet.math
  • Mat3
    • Mat3.rotate()
    • Mat3.scale()
    • Mat3.shear()
    • Mat3.translate()
  • Mat4
    • Mat4.column()
    • Mat4.from_rotation()
    • Mat4.from_scale()
    • Mat4.from_translation()
    • Mat4.look_at()
    • Mat4.orthogonal_projection()
    • Mat4.perspective_projection()
    • Mat4.rotate()
    • Mat4.row()
    • Mat4.scale()
    • Mat4.translate()
    • Mat4.transpose()
  • Vec2
    • Vec2.clamp()
    • Vec2.distance()
    • Vec2.dot()
    • Vec2.from_heading()
    • Vec2.from_magnitude()
    • Vec2.from_polar()
    • Vec2.lerp()
    • Vec2.limit()
    • Vec2.normalize()
    • Vec2.reflect()
    • Vec2.rotate()
    • Vec2.heading
    • Vec2.mag
    • Vec2.x
    • Vec2.y
  • Vec3
    • Vec3.clamp()
    • Vec3.cross()
    • Vec3.distance()
    • Vec3.dot()
    • Vec3.from_magnitude()
    • Vec3.lerp()
    • Vec3.limit()
    • Vec3.normalize()
    • Vec3.mag
    • Vec3.x
    • Vec3.y
    • Vec3.z
  • Vec4
    • Vec4.clamp()
    • Vec4.distance()
    • Vec4.dot()
    • Vec4.lerp()
    • Vec4.normalize()
    • Vec4.w
    • Vec4.x
    • Vec4.y
    • Vec4.z
  • clamp()
• pyglet.media
  • pyglet.media.synthesis
    • ADSREnvelope
    • FlatEnvelope
    • LinearDecayEnvelope
    • Sawtooth
    • Silence
    • Sine
    • Square
    • SynthesisSource
    • TremoloEnvelope
    • Triangle
    • WhiteNoise
    • composite_operator()
    • noise_generator()
    • pulse_generator()
    • sawtooth_generator()
    • silence_generator()
    • sine_generator()
    • sine_operator()
    • triangle_generator()
  • Classes
    • Player
    • PlayerGroup
    • AudioFormat
    • VideoFormat
    • AudioData
    • SourceInfo
    • Source
    • StreamingSource
    • StaticSource
    • StaticMemorySource
    • AbstractListener
    • MediaEvent
  • Functions
    • get_audio_driver()
    • load()
    • have_ffmpeg()
  • Exceptions
    • CannotSeekException
    • MediaException
    • MediaFormatException
• pyglet.resource
  • Path format
  • Functions
    • reindex()
    • file()
    • location()
    • add_font()
    • image()
    • animation()
    • texture()
    • media()
    • model()
    • shader()
    • html()
    • attributed()
    • text()
    • get_cached_image_names()
    • get_cached_animation_names()
    • get_texture_bins()
    • get_cached_texture_names()
  • Exceptions
    • ResourceNotFoundException
    • UndetectableShaderType
• pyglet.sprite
  • Drawing multiple sprites
  • Sprite
    • Sprite.delete()
    • Sprite.draw()
    • Sprite.update()
    • Sprite.on_animation_end()
    • Sprite.batch
    • Sprite.color
    • Sprite.group
    • Sprite.height
    • Sprite.image
    • Sprite.opacity
    • Sprite.position
    • Sprite.rotation
    • Sprite.scale
    • Sprite.scale_x
    • Sprite.scale_y
    • Sprite.visible
    • Sprite.width
    • Sprite.x
    • Sprite.y
  • SpriteGroup
    • SpriteGroup.set_state()
    • SpriteGroup.unset_state()
• pyglet.shapes
  • Arc
    • Arc.group_class
    • Arc.delete()
    • Arc.draw()
    • Arc.anchor_position
    • Arc.anchor_x
    • Arc.anchor_y
    • Arc.angle
    • Arc.batch
    • Arc.color
    • Arc.group
    • Arc.opacity
    • Arc.position
    • Arc.rotation
    • Arc.start_angle
    • Arc.visible
    • Arc.x
    • Arc.y
  • BezierCurve
    • BezierCurve.group_class
    • BezierCurve.delete()
    • BezierCurve.draw()
    • BezierCurve.anchor_position
    • BezierCurve.anchor_x
    • BezierCurve.anchor_y
    • BezierCurve.batch
    • BezierCurve.color
    • BezierCurve.group
    • BezierCurve.opacity
    • BezierCurve.points
    • BezierCurve.position
    • BezierCurve.t
    • BezierCurve.visible
    • BezierCurve.x
    • BezierCurve.y
  • BorderedRectangle
    • BorderedRectangle.group_class
    • BorderedRectangle.delete()
    • BorderedRectangle.draw()
    • BorderedRectangle.anchor_position
    • BorderedRectangle.anchor_x
    • BorderedRectangle.anchor_y
    • BorderedRectangle.batch
    • BorderedRectangle.border_color
    • BorderedRectangle.color
    • BorderedRectangle.group
    • BorderedRectangle.height
    • BorderedRectangle.opacity
    • BorderedRectangle.position
    • BorderedRectangle.rotation
    • BorderedRectangle.visible
    • BorderedRectangle.width
    • BorderedRectangle.x
    • BorderedRectangle.y
  • Circle
    • Circle.group_class
    • Circle.delete()
    • Circle.draw()
    • Circle.anchor_position
    • Circle.anchor_x
    • Circle.anchor_y
    • Circle.batch
    • Circle.color
    • Circle.group
    • Circle.opacity
    • Circle.position
    • Circle.radius
    • Circle.visible
    • Circle.x
    • Circle.y
  • Ellipse
    • Ellipse.group_class
    • Ellipse.delete()
    • Ellipse.draw()
    • Ellipse.a
    • Ellipse.anchor_position
    • Ellipse.anchor_x
    • Ellipse.anchor_y
    • Ellipse.b
    • Ellipse.batch
    • Ellipse.color
    • Ellipse.group
    • Ellipse.opacity
    • Ellipse.position
    • Ellipse.rotation
    • Ellipse.visible
    • Ellipse.x
    • Ellipse.y
  • Line
    • Line.group_class
    • Line.delete()
    • Line.draw()
    • Line.anchor_position
    • Line.anchor_x
    • Line.anchor_y
    • Line.batch
    • Line.color
    • Line.group
    • Line.opacity
    • Line.position
    • Line.visible
    • Line.x
    • Line.x2
    • Line.y
    • Line.y2
  • Polygon
    • Polygon.group_class
    • Polygon.delete()
    • Polygon.draw()
    • Polygon.anchor_position
    • Polygon.anchor_x
    • Polygon.anchor_y
    • Polygon.batch
    • Polygon.color
    • Polygon.group
    • Polygon.opacity
    • Polygon.position
    • Polygon.rotation
    • Polygon.visible
    • Polygon.x
    • Polygon.y
  • Rectangle
    • Rectangle.group_class
    • Rectangle.delete()
    • Rectangle.draw()
    • Rectangle.anchor_position
    • Rectangle.anchor_x
    • Rectangle.anchor_y
    • Rectangle.batch
    • Rectangle.color
    • Rectangle.group
    • Rectangle.height
    • Rectangle.opacity
    • Rectangle.position
    • Rectangle.rotation
    • Rectangle.visible
    • Rectangle.width
    • Rectangle.x
    • Rectangle.y
  • Sector
    • Sector.group_class
    • Sector.delete()
    • Sector.draw()
    • Sector.anchor_position
    • Sector.anchor_x
    • Sector.anchor_y
    • Sector.angle
    • Sector.batch
    • Sector.color
    • Sector.group
    • Sector.opacity
    • Sector.position
    • Sector.radius
    • Sector.rotation
    • Sector.start_angle
    • Sector.visible
    • Sector.x
    • Sector.y
  • Star
    • Star.group_class
    • Star.delete()
    • Star.draw()
    • Star.anchor_position
    • Star.anchor_x
    • Star.anchor_y
    • Star.batch
    • Star.color
    • Star.group
    • Star.inner_radius
    • Star.num_spikes
    • Star.opacity
    • Star.outer_radius
    • Star.position
    • Star.rotation
    • Star.visible
    • Star.x
    • Star.y
  • Triangle
    • Triangle.group_class
    • Triangle.delete()
    • Triangle.draw()
    • Triangle.anchor_position
    • Triangle.anchor_x
    • Triangle.anchor_y
    • Triangle.batch
    • Triangle.color
    • Triangle.group
    • Triangle.opacity
    • Triangle.position
    • Triangle.visible
    • Triangle.x
    • Triangle.x2
    • Triangle.x3
    • Triangle.y
    • Triangle.y2
    • Triangle.y3
• pyglet.text
  • pyglet.text.caret
    • Caret
  • pyglet.text.document
    • Abstract representation
    • Paragraph breaks
    • Document classes
    • Style attributes
    • AbstractDocument
    • FormattedDocument
    • InlineElement
    • UnformattedDocument
    • STYLE_INDETERMINATE
  • pyglet.text.layout
    • Style attributes
    • IncrementalTextDecorationGroup
    • IncrementalTextLayout
    • IncrementalTextLayoutGroup
    • ScrollableTextDecorationGroup
    • ScrollableTextLayout
    • ScrollableTextLayoutGroup
    • TextDecorationGroup
    • TextLayout
    • TextLayoutGroup
    • get_default_decoration_shader()
    • get_default_image_layout_shader()
    • get_default_layout_shader()
  • DocumentDecodeException
  • DocumentDecoder
    • DocumentDecoder.decode()
  • DocumentLabel
    • DocumentLabel.get_style()
    • DocumentLabel.set_style()
    • DocumentLabel.bold
    • DocumentLabel.color
    • DocumentLabel.font_name
    • DocumentLabel.font_size
    • DocumentLabel.italic
    • DocumentLabel.opacity
    • DocumentLabel.text
  • HTMLLabel
    • HTMLLabel.text
  • Label
  • decode_attributed()
  • decode_html()
  • decode_text()
  • get_decoder()
  • load()
• pyglet.window
  • pyglet.window.key
    • KeyStateHandler
    • modifiers_string()
    • motion_string()
    • symbol_string()
    • user_key()
    • Key Constants
  • pyglet.window.mouse
    • MouseStateHandler
    • buttons_string()
    • LEFT
    • MIDDLE
    • MOUSE4
    • MOUSE5
    • RIGHT
  • Getting started
  • Creating a game window
  • Working with multiple screens
  • Specifying the OpenGL context properties
  • Classes
    • Window
    • FPSDisplay
    • MouseCursor
    • DefaultMouseCursor
    • ImageMouseCursor
  • Exceptions
    • MouseCursorException
    • NoSuchConfigException
    • NoSuchDisplayException
    • WindowException

External Resources

• Related Documentation
• Projects using pyglet
  • cocos2d
  • Arcade

Development Guide

• Contributing
  • Roadmap
  • Communication
  • Issue Tracker
  • Getting the latest development version
  • Contributing to the source
  • Contributing to the documentation
  • Contact
• Development environment
  • Linux or Mac OSX
    • Setting up
    • Finishing
  • Windows
    • Setting up
    • Finishing
• Testing pyglet
  • Test Suites
    • Unit tests
    • Integration tests
    • Interactive tests
  • Running tests
  • Writing tests
    • Annotations
• Documentation
  • Writing documentation
    • Literature
  • Source code
  • Building
  • HTML Theme
• Making a pyglet release
  • Major version increase
• OpenGL Interface Implementation
  • ctypes linkage
  • Missing extensions
• ctypes Wrapper Generation
  • Generating GL wrappers (new version)
  • Generating GL wrappers (old version)
  • Generated GL wrappers
  • Generating Xlib wrappers
• wraptypes
  • Parser Modifications
  • Preprocessor
  • CParser
  • CtypesParser
• Media manual
  • Domain knowledge
  • Current code architecture
    • Source
    • FFmpegStreamingSource
    • Player
    • AudioPlayer
    • AudioDriver
    • Normal operation of the Player
  • Helpful tools
  • Convert video to mkv
• Media logging manual
  • Workflows
    • User submitting debug info
    • Changing code in pyglet ffmpeg subsystem
    • Changing the debug code for pyglet ffmpeg
  • Session
  • Active session
  • Commands Summary
    • Primary commands
    • Helper commands
  • Data directory layout
  • Code Layout and conventions
    • Scripts (commands)
    • Modules
    • Scripts that also acts as modules
  • Commands detailed
    • bokeh_timeline.py
    • compare.py
    • configure.py
    • mp.py
    • playmany.py
    • report.py
    • retry_crashed.py
    • run_test_suite.py
    • summarize.py
    • timeline.py
  • Samples
  • pycharm notes