pyglet
pyglet is a cross-platform games and multimedia package.
More information is available at http://www.pyglet.org
- class Options
Dataclass for global pyglet options.
- __init__(
- audio: Sequence[str] = ('xaudio2', 'directsound', 'openal', 'pulse', 'silent'),
- debug_font: bool = False,
- debug_gl: bool = True,
- debug_gl_trace: bool = False,
- debug_gl_trace_args: bool = False,
- debug_gl_shaders: bool = False,
- debug_graphics_batch: bool = False,
- debug_lib: bool = False,
- debug_media: bool = False,
- debug_texture: bool = False,
- debug_trace: bool = False,
- debug_trace_args: bool = False,
- debug_trace_depth: int = 1,
- debug_trace_flush: bool = True,
- debug_win32: bool = False,
- debug_input: bool = False,
- debug_x11: bool = False,
- shadow_window: bool = True,
- vsync: bool | None = None,
- xsync: bool = True,
- xlib_fullscreen_override_redirect: bool = False,
- search_local_libs: bool = True,
- win32_gdi_font: bool = False,
- headless: bool = False,
- headless_device: int = 0,
- win32_disable_shaping: bool = False,
- dw_legacy_naming: bool = False,
- win32_disable_xinput: bool = False,
- com_mta: bool = False,
- osx_alt_loop: bool = False,
- dpi_scaling: Literal['real', 'scaled', 'stretch', 'platform'] = 'real',
- shader_bind_management: bool = True,
-
audio:
Sequence
[str
] = ('xaudio2', 'directsound', 'openal', 'pulse', 'silent') A
Sequence
of valid audio modules names. They will be tried from first to last until either a driver loads or no entries remain. See Choosing the audio driver for more information.Valid driver names are:
'xaudio2'
, the Windows Xaudio2 audio module (Windows only)'directsound'
, the Windows DirectSound audio module (Windows only)'pulse'
, the PulseAudio module(Linux only, otherwise nearly ubiquitous. Limited features; use
'openal'
for more.)
'openal'
, the OpenAL audio module (A library may need to be installed on Windows and Linux)'silent'
, no audio
-
com_mta:
bool
= False If
True
, this will enforce COM Multithreaded Apartment Mode for Windows applications. By default, pyglet has opted to go for Single-Threaded Apartment (STA) for compatibility reasons. Many other third party libraries used with Python explicitly set STA. However, Windows recommends MTA with a lot of their API’s such as Windows Media Foundation (WMF).New in version 2.0.5.
-
debug_font:
bool
= False If
True
, will print more verbose information whenFont
’s are loaded.
-
debug_gl:
bool
= True If
True
, all calls to OpenGL functions are checked afterwards for errors usingglGetError
. This will severely impact performance, but provides useful exceptions at the point of failure. By default, this option is enabled if__debug__
is enabled (i.e., if Python was not run with the -O option). It is disabled by default when pyglet is “frozen”, such as within pyinstaller or nuitka.
-
debug_gl_shaders:
bool
= False If
True
, prints shader compilation information such as creation and deletion of shader’s. Also includes information on shader ID’s, attributes, and uniforms.
-
debug_gl_trace:
bool
= False If
True
, will print the names of OpenGL calls being executed. For example,glBlendFunc
-
debug_gl_trace_args:
bool
= False If
True
, in addition to printing the names of OpenGL calls, it will also print the arguments passed into those calls. For example,glBlendFunc(770, 771)
Note
Requires
debug_gl_trace
to be enabled.
-
debug_graphics_batch:
bool
= False If
True
, prints batch information being drawn, includingGroup
’s, VertexDomains, andTexture
information. This can be useful to see how many Group’s are being consolidated.
-
debug_input:
bool
= False If
True
, prints information on input devices such as controllers, tablets, and more.
-
debug_lib:
bool
= False If
True
, prints the path of each dynamic library loaded.
-
debug_media:
bool
= False If
True
, prints more detailed media information for audio codecs and drivers. Will be very verbose.
-
debug_texture:
bool
= False If
True
, prints information onTexture
size (in bytes) when they are allocated and deleted.
-
debug_win32:
bool
= False If
True
, prints error messages related to Windows library calls. Usually get’s information fromKernel32.GetLastError
. This information is output to a file calleddebug_win32.log
.
-
debug_x11:
bool
= False If
True
, prints information related to Linux X11 calls. This can potentially help narrow down driver or operating system issues.
-
dpi_scaling:
Literal
['real'
,'scaled'
,'stretch'
,'platform'
] = 'real' For ‘HiDPI’ displays, Window behavior can differ between operating systems. Defaults to ‘real’.
The current options are an attempt to create consistent behavior across all of the operating systems.
‘real’ (default): Provides a 1:1 pixel for Window frame size and framebuffer. Primarily used for game applications to ensure you are getting the exact pixels for the resolution. If you provide an 800x600 window, you can ensure it will be 800x600 pixels when the user chooses it.
‘scaled’: Window size is scaled based on the DPI ratio. Window size and content (projection) size matches the full framebuffer. Primarily used for any applications that wish to become DPI aware. You must rescale and reposition your content to take advantage of the larger framebuffer. An 800x600 with a 150% DPI scaling would be changed to 1200x900 for both window.get_size and window.get_framebuffer_size().
Keep in mind that pyglet objects may not be scaled proportionately, so this is left up to the developer. The
scale
&dpi
attributes can be queried as a reference when determining object creation.‘stretch’: Window is scaled based on the DPI ratio. However, content size matches original requested size of the window, and is stretched to fit the full framebuffer. This mimics behavior of having no DPI scaling at all. No rescaling and repositioning of content will be necessary, but at the cost of blurry content depending on the extent of the stretch. For example, 800x600 at 150% DPI will be 800x600 for window.get_size() and 1200x900 for window.get_framebuffer_size().
‘platform’: A DPI aware window is created, however window sizing and framebuffer sizing is not interfered with by Pyglet. Final sizes are dictated by the platform the window was created on. It is up to the user to make any platform adjustments themselves such as sizing on a platform, mouse coordinate adjustments, or framebuffer size handling. On Windows and X11, the framebuffer and the requested window size will always match in pixels 1:1. On MacOS, depending on a Hi-DPI display, you may get a different sized framebuffer than the window size. This option does allow window.dpi and window.scale to return their respective values.
-
dw_legacy_naming:
bool
= False If
True
, will enable legacy naming support for the default Windows font renderer (DirectWrite
). Attempt to parse fonts by the passed name, to best match legacy RBIZ naming.- See:
https://learn.microsoft.com/en-us/windows/win32/directwrite/font-selection#rbiz-font-family-model
For example, this allows specifying
"Arial Narrow"
rather than"Arial"
with a"condensed"
stretch or"Arial Black"
instead of"Arial"
with a weight ofblack
. This may enhance naming compatibility cross-platform for select fonts as older font renderers went by this naming scheme.Starts by parsing the string for any known style names, and searches all font collections for a matching RBIZ name. If a perfect match is not found, it will choose a second best match.
Note
Due to the high variation of styles and limited capability of some fonts, there is no guarantee the second closest match will be exactly what the user wants.
Note
The
debug_font
option can provide information on what settings are being selected.New in version 2.0.3.
-
headless:
bool
= False If
True
, visible Windows are not created and a running desktop environment is not required. This option is useful when running pyglet on a headless server, or compute cluster. OpenGL drivers withEGL
support are required for this mode.
-
headless_device:
int
= 0 If using
headless
mode (pyglet.options['headless'] = True
), this option allows you to set which GPU to use. This is only useful on multi-GPU systems.
-
osx_alt_loop:
bool
= False If
True
, this will enable an alternative loop for Mac OSX. This is enforced for all ARM64 architecture Mac’s.Due to various issues with the ctypes interface with Objective C, Python, and Mac ARM64 processors, the standard event loop eventually starts breaking down to where inputs are either missed or delayed. Even on Intel based Mac’s other odd behavior can be seen with the standard event loop such as randomly crashing from events.
New in version 2.0.5.
-
search_local_libs:
bool
= True If
False
, pyglet won’t try to search for libraries in the script directory and itslib
subdirectory. This is useful to load a local library instead of the system installed version.
-
shader_bind_management:
bool
= True - If
True
, this will enable internal management of Uniform Block bindings for
If
False
, bindings will not be managed by Pyglet. The user will be responsible for either setting the binding points through GLSL layouts (4.2 required) or manually throughUniformBlock.set_binding
.New in version 2.0.16.
- If
-
shadow_window:
bool
= True By default, pyglet creates a hidden window with a GL context when pyglet.gl is imported. This allows resources to be loaded before the application window is created, and permits GL objects to be shared between windows even after they’ve been closed. You can disable the creation of the shadow window by setting this option to False.
Some OpenGL driver implementations may not support shared OpenGL contexts and may require disabling the shadow window (and all resources must be loaded after the window using them was created). Recommended for advanced developers only.
New in version 1.1.
-
vsync:
bool
|None
= None If set, the pyglet.window.Window.vsync property is ignored, and this option overrides it (to either force vsync on or off). If unset, or set to None, the pyglet.window.Window.vsync property behaves as documented.
-
win32_disable_shaping:
bool
= False If
True
, will disable the shaping process for the default Windows font renderer to offer a performance speed up. If your font is simple, monospaced, or you require no advanced OpenType features, this option may be useful. You can try enabling this to see if there is any impact on clarity for your font. The advance will be determined by the glyph width.Note
Shaping is the process of determining which character glyphs to use and specific placements of those glyphs when given a full string of characters.
New in version 2.0.
-
win32_disable_xinput:
bool
= False If
True
, this will disable theXInput
controller usage in Windows and fallback toDirectInput
. Can be useful for debugging or special uses cases. A controller can only be controlled by eitherXInput
orDirectInput
, not both.New in version 2.0.
-
win32_gdi_font:
bool
= False If
True
, pyglet will fallback to the legacyGDIPlus
font renderer for Windows. This may provide better font compatibility for older fonts. The legacy renderer does not support shaping, colored fonts, substitutions, or other OpenType features. It may also have issues with certain languages.Due to those lack of features, it can potentially be more performant.
New in version 2.0.
-
xlib_fullscreen_override_redirect:
bool
= False If
True
, pass the xlib.CWOverrideRedirect flag when creating a fullscreen window. This option is generally not necessary anymore and is considered deprecated.
-
xsync:
bool
= True If
True
(the default), pyglet will attempt to synchronise the drawing of double-buffered windows to the border updates of the X11 window manager. This improves the appearance of the window during resize operations. This option only affects double-buffered windows on X11 servers supporting the Xsync extension with a window manager that implements the _NET_WM_SYNC_REQUEST protocol.New in version 1.1.
- options: Options = Options(audio=('xaudio2', 'directsound', 'openal', 'pulse', 'silent'), debug_font=False, debug_gl=True, debug_gl_trace=False, debug_gl_trace_args=False, debug_gl_shaders=False, debug_graphics_batch=False, debug_lib=False, debug_media=False, debug_texture=False, debug_trace=False, debug_trace_args=False, debug_trace_depth=1, debug_trace_flush=True, debug_win32=False, debug_input=False, debug_x11=False, shadow_window=True, vsync=None, xsync=True, xlib_fullscreen_override_redirect=False, search_local_libs=True, win32_gdi_font=False, headless=False, headless_device=0, win32_disable_shaping=False, dw_legacy_naming=False, win32_disable_xinput=False, com_mta=False, osx_alt_loop=False, dpi_scaling='real', shader_bind_management=True)
Instance of
Options
used to set runtime options.
- version = '2.1.2'
The release version