pyglet 3.0.dev9__tar.gz → 3.0.dev10__tar.gz

pyglet-3.0.dev10/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: pyglet
+Version: 3.0.dev10
+Summary: pyglet is a cross-platform games and multimedia package.
+Author-email: Alex Holkner & contributors <Alex.Holkner@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+License-File: LICENSE
+Project-URL: Documentation, https://pyglet.readthedocs.io
+Project-URL: Home, https://pyglet.org
+Project-URL: Repository, https://github.com/pyglet/pyglet/
+Project-URL: Tracker, https://github.com/pyglet/pyglet/issues
+
+[![pypi](https://badge.fury.io/py/pyglet.svg)](https://pypi.python.org/pypi/pyglet) [![rtd](https://readthedocs.org/projects/pyglet/badge/?version=latest)](https://pyglet.readthedocs.io) [![PyTest](https://github.com/pyglet/pyglet/actions/workflows/unittests.yml/badge.svg)](https://github.com/pyglet/pyglet/actions/workflows/unittests.yml)
+
+![logo_large.png](https://github.com/pyglet/pyglet/blob/54a8c8b7e701b1692c6a10dd80f94ec837c27bd3/examples/opengl/pyglet.png?raw=true)
+
+# pyglet
+
+*pyglet* is a cross-platform windowing and multimedia library for Python, intended for developing games
+and other visually rich applications. It supports Windowing, input event handling, Controllers & Joysticks,
+OpenGL graphics, loading images and videos, and playing sounds and music. *pyglet* works on Windows, OS X and Linux.
+
+> :exclamation: :exclamation: **We are preparing to release a major pyglet update very soon**.
+> Version 3.0 will include an extensive internal rewrite, bringing support for multiple rendering backends
+> and significant performance improvements. This brings back support for some legacy platforms, as well as
+> new support for WebGL. The high level APIs will be largely the same, but some adjustments will be necessary
+> if you are using OpenGL directly in your game or application. See the migration guide to prepare for the
+> new release at https://pyglet.readthedocs.io/en/development/programming_guide/migration.html, and try out
+> the new release by downloading a 3.0.devX release today (pip install --upgrade pyglet --pre). 
+> **If you want to do a pull request for the previous release, please target the appropriate branch**. 
+
+* pyglet [documentation]
+* pyglet on [PyPI]
+* pyglet [discord] server
+* pyglet [mailing list]
+* pyglet [issue tracker]
+* pyglet [website]
+
+pyglet has an active developer and user community.  If you find a bug or a problem with the documentation,
+please [open an issue](https://github.com/pyglet/pyglet/issues).
+Anyone is welcome to join our [discord] server where a lot of the development discussion is going on.
+It's also a great place to ask for help.
+
+Some 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. It's easy to package and distribute
+  your project with [Nuitka](https://nuitka.net) or [PyInstaller](https://pyinstaller.org). 
+* **Take advantage of multiple windows and multi-monitor desktops.** *pyglet* allows you to use multiple
+  platform-native windows, and is fully aware of multi-monitor setups for use with fullscreen games.
+* **Load images, sound, music and video in almost any format.** *pyglet* can optionally use FFmpeg to play back
+  audio formats such as MP3, OGG/Vorbis and WMA, and video formats such as MPEG2, H.264, H.265, WMV and Xvid.
+  Without FFmpeg, *pyglet* contains built-in support for standard formats such as wav, png, bmp, and others.
+* **pyglet is written entirely in pure Python**, and makes use of the *ctypes* module to interface with system
+  libraries. You can modify the codebase or make a contribution without any second language compilation steps or
+  compiler setup. Despite being pure Python, *pyglet* has excellent performance thanks to advanced batching for
+  drawing thousands of objects.
+* **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.
+
+## Requirements
+
+pyglet runs under Python 3.10+. Being written in pure Python, it also works on other Python interpreters such as PyPy. Supported platforms are:
+
+* Windows 7 or later
+* macOS 10.9 or later.
+* Linux, with the following libraries (most recent distributions will have
+  these in a default installation):
+  * OpenGL and GLX
+  * GDK 2.0+ or Pillow (required for loading images other than PNG and BMP)
+  * OpenAL or Pulseaudio (required for playing audio)
+
+**As of pyglet 2.0, OpenGL 3.3+ is required**. 
+
+To play a large variety of compressed audio and video files,
+pyglet can optionally take advantage of [FFmpeg](https://ffmpeg.org/).
+
+## Installation
+
+pyglet is installable from PyPI:
+
+    pip install --upgrade --user pyglet
+
+## Installation from source
+
+If you're reading this `README` from a source distribution, you can install pyglet with:
+
+    pip install --upgrade --user .
+    # or
+    python setup.py install --user
+
+You can also install the latest development version directly from Github:
+
+    pip install --upgrade --user https://github.com/pyglet/pyglet/archive/master.zip
+
+For local development install pyglet in editable mode:
+
+```bash
+# with pip
+pip install -e .
+# with setup.py
+python setup.py develop
+```
+
+There are no compilation steps during the installation; if you prefer,
+you can simply add this directory to your `PYTHONPATH` and use pyglet without
+installing it. You can also copy pyglet directly into your project folder.
+
+## Contributing
+
+**A good way to start contributing to a component of pyglet is by its documentation**. When studying the code you
+are going to work with, also read the associated docs. If you don't understand the code with the help of the docs,
+it is a sign that the docs should be improved. If you wish to make large changes to any part of pyglet, it's always
+a good idea to reach out for feedback first. This can avoid wasted effort in cases where someone is already working
+on something similar, or if your idea can't be accepted for any reason. 
+
+A basic outline of how to a contribution is as follows:
+
+* Fork the [official repository](https://github.com/pyglet/pyglet/fork).
+* In your fork, checkout the branch you wish to contribute to (such as *pyglet-1.5-maintenance*).
+* Apply your changes to your fork.
+* Submit a [pull request](https://github.com/pyglet/pyglet/pulls) describing the changes you have made.
+* Alternatively you can create a patch and submit it to the issue tracker.
+
+When making a pull request, check that you have addressed its respective documentation, both within the code docstrings
+and the programming guide (if applicable). It is very important to all of us that the documentation matches the latest
+code and vice versa.
+
+Consequently, an error in the documentation, either because it is hard to understand or because it doesn't match the
+code, is a bug that deserves to be reported on a ticket.
+
+## Building Docs
+
+[Documentation and Type Hints]: https://pyglet.readthedocs.io/en/latest/internal/doc.html
+
+To get started quickly:
+
+    python -m pip install -e . --group docs
+    python make.py docs
+
+Please check [Documentation and Type Hints][] guide to learn more.
+
+## Testing
+
+pyglet makes use of pytest for its test suite.
+
+```bash
+python -m pip install -e . --group test
+# Only run unittests
+pytest tests/unit
+```
+
+Please check the [testing section in the development guide](https://pyglet.readthedocs.io/en/latest/internal/testing.html)
+for more information about running and writing tests.
+
+## Contact
+
+pyglet is developed by many individual volunteers, and there is no central point of contact. If you have a question
+about developing with pyglet, or you wish to contribute, please join the [discord] server, or [subreddit].
+
+For legal issues, please contact [Alex Holkner](mailto:Alex.Holkner@gmail.com).
+
+[discord]: https://discord.gg/QXyegWe
+[subreddit]: https://www.reddit.com/r/pyglet/
+[documentation]: https://pyglet.readthedocs.io
+[wiki]:  https://github.com/pyglet/pyglet/wiki
+[pypi]:  https://pypi.org/project/pyglet/
+[website]: http://pyglet.org/
+[issue tracker]: https://github.com/pyglet/pyglet/issues
+

pyglet-3.0.dev10/contrib/dist_field/renderfield.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import sys
+
+import pyglet
+from pyglet.enums import BlendFactor
+from pyglet.graphics.state import State
+from pyglet.window import key
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyglet.graphics import ShaderProgram, Group
+    from pyglet.graphics.texture import Texture
+
+
+class DepthFieldUniforms(State):
+    sets_state = True
+
+    def __init__(self, program: ShaderProgram):
+        self.program = program
+
+    def set_state(self, ctx) -> None:
+        self.program['bidirectional'] = enable_bidirectional
+        self.program['antialias'] = enable_antialias
+        self.program['outline'] = enable_outline
+        self.program['outline_width'] = outline_width
+        self.program['glow'] = enable_glow
+        self.program['glow_width'] = glow_width
+
+class DistFieldGroup(pyglet.sprite.SpriteGroup):
+
+    def __init__(self, texture: Texture, blend_src: BlendFactor, blend_dest: BlendFactor, program: ShaderProgram,
+                 parent: Group | None = None) -> None:
+        super().__init__(texture, blend_src, blend_dest, program, parent)
+        self.set_state(DepthFieldUniforms(program))
+
+
+class DistFieldSprite(pyglet.sprite.Sprite):
+    """Override sprite to use DistFieldTextureGroup."""
+    group_class = DistFieldGroup
+
+    def __init__(self, img, x=0, y=0, z=0, blend_src=BlendFactor.SRC_ALPHA, blend_dest=BlendFactor.ONE_MINUS_SRC_ALPHA, batch=None,
+                 group=None, subpixel=False, program=None) -> None:
+        super().__init__(img, x, y, z, blend_src, blend_dest, batch, group, subpixel, program)
+
+
+window = pyglet.window.Window(resizable=True)
+
+
+@window.event
+def on_resize(width, height):
+    scale_width = width / float(image.width)
+    scale_height = height / float(image.height)
+    sprite.scale = min(scale_width, scale_height)
+    sprite.x = width / 2
+    sprite.y = height / 2
+
+
+@window.event
+def on_draw():
+    window.clear()
+    sprite.draw()
+
+
+@window.event
+def on_key_press(symbol, modifiers):
+    global enable_bidirectional
+    global enable_antialias
+    global enable_outline
+    global enable_glow
+    global outline_width
+    global glow_width
+    if symbol == key.B:
+        enable_bidirectional = not enable_bidirectional
+    elif symbol == key.A:
+        enable_antialias = not enable_antialias
+    elif symbol == key.O:
+        enable_outline = not enable_outline
+        enable_glow = False
+    elif symbol == key.G:
+        enable_glow = not enable_glow
+        enable_outline = False
+    elif symbol == key.PERIOD:
+        if enable_glow:
+            glow_width += 0.005
+        else:
+            outline_width += 0.005
+    elif symbol == key.COMMA:
+        if enable_glow:
+            glow_width -= 0.005
+        else:
+            outline_width -= 0.005
+
+    print('-' * 78)
+    print('enable_bidirectional:', enable_bidirectional)
+    print('enable_antialias:', enable_antialias)
+    print('enable_outline:', enable_outline)
+    print('enable_glow:', enable_glow)
+    print('outline_width:', outline_width)
+
+
+vertex_source = """#version 150 core
+    in vec3 translate;
+    in vec4 colors;
+    in vec3 tex_coords;
+    in vec2 scale;
+    in vec3 position;
+    in float rotation;
+
+    out vec4 vertex_colors;
+    out vec3 texture_coords;
+
+    uniform WindowBlock
+    {
+        mat4 projection;
+        mat4 view;
+    } window;
+
+    mat4 m_scale = mat4(1.0);
+    mat4 m_rotation = mat4(1.0);
+    mat4 m_translate = mat4(1.0);
+
+    void main()
+    {
+        m_scale[0][0] = scale.x;
+        m_scale[1][1] = scale.y;
+        m_translate[3][0] = translate.x;
+        m_translate[3][1] = translate.y;
+        m_translate[3][2] = translate.z;
+        m_rotation[0][0] =  cos(-radians(rotation));
+        m_rotation[0][1] =  sin(-radians(rotation));
+        m_rotation[1][0] = -sin(-radians(rotation));
+        m_rotation[1][1] =  cos(-radians(rotation));
+
+        gl_Position = window.projection * window.view * m_translate * m_rotation * m_scale * vec4(position, 1.0);
+
+        vertex_colors = colors;
+        texture_coords = tex_coords;
+    }
+"""
+
+fragment_source = """#version 150 core
+    in vec4 vertex_colors;
+    in vec3 texture_coords;
+    out vec4 final_colors;
+
+    uniform sampler2D sprite_texture;
+
+    uniform bool bidirectional;
+    uniform bool antialias;
+    uniform bool outline;
+    uniform bool glow;
+    uniform float outline_width;
+    uniform float glow_width;
+
+    const vec4 outline_color = vec4(0.0, 0.0, 1.0, 1.0);
+    const vec4 glow_color = vec4(1.0, 0.0, 0.0, 1.0);
+
+    void main()
+    {
+        float alpha_mask;
+        if (bidirectional)
+        {
+            vec4 field = texture2D(sprite_texture, texture_coords.xy);
+            alpha_mask = float(field.r >= 0.5 && field.g >= 0.5);
+        }
+        else
+        {
+            alpha_mask = texture2D(sprite_texture, texture_coords.xy).a;
+        }
+        float alpha_width = fwidth(alpha_mask);
+        float intensity = alpha_mask;
+
+        final_colors = vertex_colors;
+
+        if (glow)
+        {
+            float glow_min = 0.5 - glow_width;
+            intensity = (alpha_mask - glow_min) / (0.5 - glow_min);
+            float glow_intensity = 0.0;
+            if (antialias)
+                glow_intensity = 1.0 - smoothstep(0.5 - alpha_width,
+                                                  0.5 + alpha_width,
+                                                  alpha_mask) * 2.0;
+            else
+                glow_intensity = float(alpha_mask < 0.5);
+
+            final_colors = mix(final_colors, glow_color, glow_intensity);
+        }
+        else if (outline)
+        {
+            float outline_intensity = 0.0;
+            float outline_min = 0.5 - outline_width;
+            float outline_max = 0.5;
+            if (antialias)
+            {
+
+                outline_intensity = 1.0 - smoothstep(outline_max - alpha_width,
+                                                     outline_max + alpha_width,
+                                                     alpha_mask) * 2.0;
+
+                intensity *= smoothstep(outline_min - alpha_width,
+                                        outline_min + alpha_width,
+                                        alpha_mask) * 2.0;
+            }
+            else
+            {
+                outline_intensity =
+                    float(alpha_mask >= outline_min && alpha_mask <= outline_max);
+                intensity = float(alpha_mask >= outline_min);
+            }
+            final_colors = mix(final_colors, outline_color, outline_intensity);
+        }
+        else if (antialias)
+        {
+            intensity *= smoothstep(0.5 - alpha_width,
+                                    0.5 + alpha_width,
+                                    alpha_mask) * 2.0;
+        }
+        else
+        {
+            intensity = float(alpha_mask >= 0.5);
+        }
+
+        final_colors.a = intensity;
+    }
+"""
+
+enable_bidirectional = False
+enable_antialias = False
+enable_outline = False
+enable_glow = False
+outline_width = 0.02
+glow_width = 0.1
+
+dist_shader = pyglet.graphics.ShaderProgram(
+    pyglet.graphics.Shader(vertex_source, "vertex"),
+    pyglet.graphics.Shader(fragment_source, "fragment"),
+)
+
+if len(sys.argv) > 1:
+    filename = sys.argv[1]
+else:
+    filename = 'py.df.png'
+
+controls = """
+Following keys modify the shader operation:
+
+    A   Toggle antialiasing
+    B   Toggle bidirectional (see below)
+    O   Toggle outline
+    G   Toggle glow
+    ,   Decrease outline/glow
+    .   Increase outline/glow
+"""
+print(controls)
+
+image = pyglet.image.load(filename)
+
+sprite = DistFieldSprite(image, anchor=(image.width // 2, image.height // 2), program=dist_shader)
+
+pyglet.app.run()

pyglet-3.0.dev10/doc/internal/generated.rst

@@ -0,0 +1,76 @@
+ctypes Wrapper Generation
+=========================
+
+Pyglet has two ctypes-generation processes. The OpenGL-family
+bindings use Khronos XML registries. The remaining legacy wrappers parse local
+C headers.
+
+Khronos XML registry bindings
+-----------------------------
+
+The XML registry generators live in ``tools/gen_opengl``:
+
+* ``gengl.py`` generates OpenGL core, compatibility, and OpenGL ES bindings
+  from ``gl.xml``.
+* ``gen_egl.py``, ``gen_glx.py``, and ``gen_wgl.py`` generate the EGL, GLX,
+  and WGL bindings from ``egl.xml``, ``glx.xml``, and ``wgl.xml``.
+* There is no agl.xml file available, and is therefore no longer generated.
+  Since AGL is deprecated, it will not require any future updates.
+
+Run the generators from the repository root::
+
+    python tools/gen_opengl/gengl.py --source local
+    python tools/gen_opengl/gen_egl.py
+    python tools/gen_opengl/gen_glx.py
+    python tools/gen_opengl/gen_wgl.py
+
+``gengl.py`` can also retrieve the current ``gl.xml`` with ``--source url``.
+The generated OpenGL modules are ``pyglet.graphics.api.gl.gl``,
+``pyglet.graphics.api.gl.gl_compat``, and ``pyglet.graphics.api.gl.gles``.
+
+Extension bindings
+------------------
+
+Each generator has an ``EXTENSIONS`` list. It contains extensions pyglet uses
+or that are common enough for the normal binding module. The
+registry contains many legacy and vendor specific extensions, so generating all
+of them by default would substantially increase module size, increase time
+spent linking/importing, and may require additional platform specific ctypes
+declarations.
+
+EGL, GLX, and WGL can write selected extensions to a sibling ``*_ext.py``
+module instead::
+
+    python tools/gen_opengl/gen_egl.py --extensions-file
+    python tools/gen_opengl/gen_glx.py --extensions-file
+    python tools/gen_opengl/gen_wgl.py --extensions-file
+
+Use ``--extra-extensions`` with ``--extensions-file`` to generate all unlisted
+registry extensions into that extra module. Add any required type mappings and
+template imports before enabling an extension that uses platform specific
+types.
+
+If an extension is useful to pyglet and broadly supported, add it to the
+relevant ``EXTENSIONS`` list. For experimental, legacy, or application specific
+extensions, prefer separate extension output.
+
+If there is a commonly used extension, or your application relies on a specific
+extension that pyglet does not include by default, we can include it. Feel free
+to open an issue or pull request with the specific extension.
+
+C-header wrapper bindings
+-------------------------
+
+``tools/genwrappers.py`` invokes the ``tools/wraptypes`` preprocessor
+and C parser over headers installed on the local system. Unlike the XML
+generators, it is platform and development header dependent. It is used for
+X11 and a small number of other platform libraries, not EGL, GLX, or WGL.
+
+On Linux, request the wrappers to generate explicitly::
+
+    python tools/genwrappers.py xlib xinerama
+
+This requires the corresponding X11 and Xinerama development headers. The
+current script still contains output paths from the former X11 package layout;
+update those paths before regenerating the relocated
+``pyglet.libs.linux.x11`` modules.

pyglet-3.0.dev10/doc/internal/gl.rst

@@ -0,0 +1,47 @@
+OpenGL Interface Implementation
+--------------------------------
+
+See `OpenGL Interface` for details on the publicly-visible modules.
+
+See `ctypes Wrapper Generation` for details on some of these modules are
+generated.
+
+ctypes linkage
+==============
+
+Most functions link to libGL.so (Linux), opengl32.dll (Windows) or
+OpenGL.framework (OS X).  ``pyglet.graphics.api.gl.lib`` provides some helper types then
+imports linker functions for the appropriate platform: one of
+``pyglet.libs.darwin.lib_agl``, ``pyglet.libs.linux.glx.lib_glx``, ``pyglet.libs.win32.lib_wgl``.
+
+On any platform, the following steps are taken to link each function during
+import:
+
+1. Look in the appropriate library (e.g. libGL.so, opengl32.dll,
+   etc.) using ``cdll`` or ``windll``.
+
+2. If not found, call ``wglGetProcAddress`` or ``glxGetProcAddress`` to try to
+   resolve the function's address dynamically.  On OS X, skip this step.
+
+3. On Windows, this will fail if the context hasn't been created yet.  Create
+   and return a proxy object ``WGLFunctionProxy`` which will try the same
+   resolution again when the object is ``__call__``'d.
+
+   The proxy object caches its result so that subsequent calls have only a
+   single extra function-call overhead.
+
+4. If the function is still not found (either during import or proxy call),
+   the function is replaced with ``MissingFunction`` (defined in
+   ``pyglet.libs``), which raises an exception.  The exception message
+   details the name of the function, and optionally the name of the extension
+   or OpenGL version it requires.
+
+Binding regeneration
+====================
+
+The generated binding sources, registry extension policy, and the separate
+C-header wrapper pipeline are documented in :doc:`generated`.
+
+To access the linking function, import ``pyglet.graphics.api.gl.lib`` and use one of
+``link_AGL``, ``link_GLX``, ``link_WGL`` or ``link_GL``.  This
+is what the generated modules do.

pyglet-3.0.dev10/doc/modules/graphics/index.rst

@@ -0,0 +1,23 @@
+pyglet.graphics
+===============
+
+.. rubric:: Submodules
+
+.. toctree::
+   :maxdepth: 1
+
+   allocation
+   atlas
+   draw
+   framebuffer
+   instance
+   shader
+   texture
+   vertexbuffer
+   vertexdomain
+
+.. rubric:: Details
+
+.. automodule:: pyglet.graphics
+  :members:
+  :undoc-members:

pyglet-3.0.dev10/doc/modules/graphics/instance.rst

@@ -0,0 +1,10 @@
+pyglet.graphics.instance
+========================
+
+``VertexInstance`` provides an object handle for one independently managed
+instance. For array-oriented workloads, ``InstanceCollection`` manages the
+entire contiguous instance range without allocating a Python object for every
+item. See :ref:`guide_instanced-rendering` for selection guidance and examples.
+
+.. automodule:: pyglet.graphics.instance
+  :members: VertexInstance, InstanceCollection