pyglet 2.0.15__tar.gz → 2.1.dev2__tar.gz

{pyglet-2.0.15 → pyglet-2.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyglet
-Version: 2.0.15
+Version: 2.1.dev2
 Summary: pyglet is a cross-platform games and multimedia package.
 Author-email: Alex Holkner & contributors <Alex.Holkner@gmail.com>
 Requires-Python: >=3.8

{pyglet-2.0.15 → pyglet-2.1.dev2}/contrib/scenemanager.py

@@ -22,16 +22,19 @@ class Scene:
 
     # Controller event handlers:
 
-    def on_dpad_motion(self, controller, dpleft, dpright, dpup, dpdown):
+    def on_dpad_motion(self, controller, vector):
         pass
 
-    def on_button_press(self, controller, button):
+    def on_stick_motion(self, controller, name, vector):
         pass
 
-    def on_button_release(self, controller, button):
+    def on_trigger_motion(self, controller, value):
+        pass
+
+    def on_button_press(self, controller, button):
         pass
 
-    def on_stick_motion(self, controller, stick, xvalue, yvalue):
+    def on_button_release(self, controller, button):
         pass
 
     # Keyboard event handlers:

{pyglet-2.0.15 → pyglet-2.1.dev2}/contrib/toys/follow_mouse.py

@@ -25,9 +25,9 @@ window = pyglet.window.Window(fullscreen='-fs' in sys.argv, config=config)
 
 class Line:
     batch = pyglet.graphics.Batch()
-    lines = batch.add(100, GL_LINES, None, ('position3f', (0.0,) * 300), ('colors4Bn', (255, ) * 400))
-    black = pyglet.shapes.Rectangle(0, 0, window.width, window.height, color=(0, 0, 0), batch=batch)
-    black.opacity = 32
+    program = pyglet.shapes.get_default_shader()
+    lines = program.vertex_list(100, GL_LINES, batch=batch, colors=('Bn', (255, 255, 255, 255) * 100))
+    black = pyglet.shapes.Rectangle(0, 0, window.width, window.height, color=(0, 0, 0, 32), batch=batch)
     unallocated = list(range(100))
     active = []
 
@@ -82,7 +82,7 @@ class Line:
         # update line positions
         for n, line in enumerate(cls.active):
             line.update(dt)
-            cls.lines.position[n*6:n*6+6] = [line.lx, line.ly, 0, line.x, line.y, 0]
+            cls.lines.position[n*4:n*4+4] = [line.lx, line.ly, line.x, line.y]
 
 
 glEnable(GL_BLEND)

{pyglet-2.0.15 → pyglet-2.1.dev2}/doc/index.rst

@@ -2,17 +2,18 @@ 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
+   This documentation is for the pyglet 2.1 series, which has a few small API
+   changes from the 2.0 series. Previous documentation can be found at:
+   `2.0 maintenance <https://pyglet.readthedocs.io/en/pyglet-2.0-maintenance/>`_.
+   Documentation for the 1.5 series, which is the last to support legacy OpenGL,
+   can be found here:
    `1.5 maintenance <https://pyglet.readthedocs.io/en/pyglet-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.
+**pyglet** works on Windows, macOS and Linux.
 
 Some of the features of pyglet are:
 
@@ -74,8 +75,8 @@ If you are migrating from an older version of pyglet, please read through
 
    modules/pyglet
    modules/app
-   modules/canvas
    modules/clock
+   modules/display
    modules/event
    modules/font
    modules/gl
@@ -104,8 +105,8 @@ If you are migrating from an older version of pyglet, please read through
 
    internal/contributing
    internal/virtualenv
-   internal/testing
    internal/doc
+   internal/testing
    internal/dist
    internal/gl
    internal/generated

{pyglet-2.0.15 → pyglet-2.1.dev2}/doc/internal/contributing.rst

@@ -1,16 +1,12 @@
 Contributing
 ============
 
-Roadmap
--------
-
-Planned work for future versions can be found in the
-`roadmap <https://github.com/pyglet/pyglet/wiki/Roadmap>`_.
-
 Communication
 -------------
 
-Pyglet communication occurs mostly in our
+pyglet communication occurs mostly in our
+`discord server <https://discord.gg/QXyegWe>`_,
+and
 `mailing list <http://groups.google.com/group/pyglet-users>`_.
 
 Issue Tracker

pyglet-2.1.dev2/doc/internal/doc.rst

@@ -0,0 +1,182 @@
+============================
+Documentation and Type Hints
+============================
+
+The pyglet documentation is written in `reStructuredText`_ (RST), and built with `Sphinx`_.
+If you are not familiar with reStructuredText, it is similar to MarkDown but offers more
+robust functionality for creating technical documentation. This is the default language
+used in Sphinx. Most of the documentation is written in plain ascii text, so you can still
+modify or add to it without needing to know much RST syntax.
+
+The documentation can be found as part of the pyglet repository, under the ``doc``
+subfolder. The main index is located at ``pyglet/doc/index.rst``, which includes the
+main landing page, and defines three toctrees:
+
+* The programming guide
+* The API docs
+* The development guide
+
+
+programming guide
+-----------------
+The programming guide is made up of many individual `.rst` files, which are located
+in the repository under the ``pyglet/doc/programming_guide/`` folder. All files in this
+folder are also defined in the index.rst, in order to includes them in the build process.
+
+
+API documentation
+-----------------
+The API documentation is generated direclty from the source code docstrings by `autodoc`_,
+a plugin extension that is included with Sphinx. The generation itself is mostly automatic,
+but declaration files are necessary to instruct Sphinx how and which modules and classes
+should be included. Look through the existing files at ``pyglet/doc/modules/`` to get an
+idea of what this looks like.
+
+docstring rules
+^^^^^^^^^^^^^^^
+- Google Format with no typing.
+- Docstrings are meant primarily for user or general information, not implementation details.
+- Hash (``#``) comments should be used for developers or contributors when needing to provide information to other developers.
+- Any methods or functions without a docstring will not appear in the API documentation.
+- Documentation will hide private attributes unless otherwise overridden in the rst.
+- Parameter descriptions are not required if straight forward enough, unless a clarification is needed.
+- If you have to add a parameter description, you must add one for each in that function. (None or All)
+- A return description is optional.
+- All classes and functions should have a header with at least a one line succinct description.
+- For class attributes, use ``Attributes:`` in the header. Type hints may be specified, as currently they are not picked up automatically.
+    - Required: You will also need to add these ``:exclude-members: <attribute>`` in the rst files manually. Otherwise, autodoc will pick it up twice.
+    - Class attributes are generally meant to be used for:
+        a. Changing global behavior to the class in some form. (Example: ``Texture.default_mag_filter``)
+        b. Simplifying subclassing for users. (Example: group_class for Sprite)
+        c. Troubleshooting purposes.
+
+- Parameter descriptions should be indented on a new line for clarity.
+- Parameter descriptions can have one line of space between each for clarity.
+- For class instance attributes, these should be documented with a #: <description> comment.
+- For class instance attributes you wish to hide from the docs. Either:
+    a. Consider making them private (via ``_name``) if it makes sense.
+    b. Mark them with a comment in this format: #: :meta private:
+
+typing rules
+^^^^^^^^^^^^
+- Do not put type information in docstrings, rely on annotations.
+- If you are using class annotations, you must have ``from __future__ import annotations`` at the top of the module.
+- When adding annotations, if a class type is not used in the file, it must be imported only within TYPE_CHECKING
+- No need to go overboard, some rules can be set to ignored if there is not yet an adequate way to do it.
+- Return types always need to be specified even if ``None``.
+
+example
+^^^^^^^
+
+.. code-block:: python
+
+    class Class1():
+        """Short description of the class
+
+        This is a good place for a general high level description
+        of what the class is, and what it is used for. For example:
+        Class1 is used for X and Y, which makes Z possible, etc.
+        """
+
+        #: This is the default thing.
+        some_default_thing = 123
+
+        #: :meta private:
+        dont_show_me = 456
+
+        def __init__(self, name: str, size: float):
+            """Constructor description
+
+            Here is where you can describe how to make an instance of the
+            class. If any of the arguments need further explaination, that
+            detail can be added as necessary. For example:
+            You must provide a name and a size, etc. etc.
+
+            Args:
+                name: The name of this object.
+                size: The size, in centimeters.
+            """
+            self.name = name
+            self.size = size
+
+            self.some_attribute: int = None
+
+        def set_size(self, centimeters: float) -> None:
+            """Simple description + type hints are enough."""
+            self.size = centimeters
+
+        def calculate_scaled_size(self, scale: float) -> float:
+            """Detailed method description
+
+            You can add more details here.
+
+            Args:
+                scale: The argument description.
+
+            Returns:
+                Describe what is being returned, if not already clear.
+            """
+            # This is a developer comment, which is not intended for end users to
+            # see. These can be used to explain to future developers why something
+            # is implemented a certain way, or any other developer focused notes, etc.
+            return self.size * scale
+
+
+    def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+        """Example function with PEP 484 type annotations.
+
+        Args:
+            param1: The first parameter.
+            param2: The second parameter.
+
+        Returns:
+           When necessary, you can describe the return value in
+           more detail. This can be skipped if it's obvious from
+           the return type hint.
+        """
+        ...
+
+
+Developer reference
+-------------------
+Developer focused documentation is located in the ``pyglet/doc/internal/`` folder.
+This contains various pages about tools that are used with developing pyglet, the
+documentation page that you're reading now, information on unit tests, etc. These
+pages are useful for anyone who wants to contribute.
+
+building
+^^^^^^^^
+Building the documentation locally requires a few dependencies. See :doc:`virtualenv`
+for more information on how to install them. Once you have Sphinx and it's dependencies
+installed, you can proceed with the build. The first way to build is by using pyglet's
+included `make.py` utility. This is found in the root of the repository. Execute::
+
+   ./make.py docs --open
+
+
+If the build succeeds, the generated static web pages will be in ``doc/_build/html``.
+
+You can also build the  standalone way to build docs is through
+``setup.py`` or ``make``.
+
+.. code:: bash
+
+    # using setup.py (output dir: _build in project root)
+    python setup.py build_sphinx
+
+    # make (make.bat for windows)
+    cd doc
+    make html
+
+
+details
+^^^^^^^
+
+.. include:: build.rst
+
+
+.. _Sphinx: https://sphinx-doc.org
+
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+
+.. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

{pyglet-2.0.15 → pyglet-2.1.dev2}/doc/modules/gl.rst

@@ -17,7 +17,7 @@ pyglet.gl
   :members:
   :undoc-members:
 
-.. autoclass:: CanvasConfig
+.. autoclass:: DisplayConfig
   :members:
   :undoc-members:
   :show-inheritance:

{pyglet-2.0.15 → pyglet-2.1.dev2}/doc/programming_guide/input.rst

@@ -112,6 +112,14 @@ following analog controls are available:
           - float
           - -1~1
 
+        * - dpadx
+          - float
+          - -1~1
+
+        * - dpady
+          - float
+          - -1~1
+
         * - lefttrigger
           - float
           - 0~1
@@ -149,14 +157,7 @@ The following digital controls are available:
           - pressing in on the left analog stick
         * - rightstick
           - pressing in on the right analog stick
-        * - dpleft
-          -
-        * - dpright
-          -
-        * - dpup
-          -
-        * - dpdown
-          -
+
 
 These values can be read in two ways. First, you can just query them manually
 in your game loop. All control names listed above are properties on the
@@ -191,27 +192,27 @@ event types:
           - :py:class:`~pyglet.input.Controller`, `str`
 
         * - on_stick_motion
-          - controller, stick_name, x_value, y_value
-          - :py:class:`~pyglet.input.Controller`, `str`, `float`, `float`
+          - controller, stick_name, vector
+          - :py:class:`~pyglet.input.Controller`, `str`, :py:class:`~pyglet.math.Vec2`
 
         * - on_dpad_motion
           - controller, left, right, up, down
-          - :py:class:`~pyglet.input.Controller`, `bool`, `bool`, `bool`, `bool`
+          - :py:class:`~pyglet.input.Controller`, :py:class:`~pyglet.math.Vec2`
 
         * - on_trigger_motion
           - controller, trigger_name, value
           - :py:class:`~pyglet.input.Controller`, `str`, `float`
 
 
-Analog events can be handled like this::
+Analog (and Dpad) events can be handled like this::
 
     @controller.event
-    def on_stick_motion(controller, name, x_value, y_value):
+    def on_stick_motion(controller, name, vector):
 
         if name == "leftstick":
-            # Do something with the x/y_values
+            # Do something with the 2D vector
         elif name == "rightstick":
-            # Do something with the x/y_values
+            # Do something with the 2D vector
 
     @controller.event
     def on_trigger_motion(controller, name, value):
@@ -221,6 +222,10 @@ Analog events can be handled like this::
         elif name == "righttrigger":
             # Do something with the value
 
+    @controller.event
+    def on_dpad_motion(controller, vector):
+        # Do something with the 2D vector
+
 Digital events can be handled like this::
 
     @controller.event
@@ -238,18 +243,6 @@ Digital events can be handled like this::
         elif button_name == 'b':
             # do something else
 
-Finally, the directional pad event can be handled like this::
-
-    @controller.event
-    def on_dpad_motion(controller, dpleft, dpright, dpup, dpdown):
-        if dpup:
-            # move up
-        if dpdown:
-            # move down
-        if dpleft:
-            # move left
-        if dpright:
-            # move right
 
 Rumble
 ^^^^^^

pyglet-2.1.dev2/doc/programming_guide/migration.rst

@@ -0,0 +1,134 @@
+.. _migration:
+
+Migrating from pyglet 2.0
+=========================
+pyglet 2.1 contains several small, but breaking changes. Some of these are
+usibility improvements, and some are in the interest of improving the quality
+of the code base. If you are upgrading from pyglet 2.0 and your game or project
+has suddenly stopped working, this is the place for you. The following sections
+should hopefully get you up and running again without too much effort. If you
+are having an issue that is not covered here, please open up an issue ticket on
+`Github <https://github.com/pyglet/pyglet/issues>`_ so that we can add it.
+
+Window "HiDPI" support
+----------------------
+TBD
+
+Labels & Text Layouts
+---------------------
+The positional argument order for text Labels and Layouts was not consistent
+in previous pyglet releases. This has been refactored to make things more
+consistent, with the goal of making it easier to switch between Layouts or
+create custom subclasses. All layouts now start with the same positional
+argument ordering::
+
+    TextLayout(document, x, y, z, width, height, anchor_x, anchor_y, rotation, ...)
+    ScrollableTextLayout(document, x, y, z, width, height, anchor_x, anchor_y, rotation, ...)
+    IncrementalTextLayout(document, x, y, z, width, height, anchor_x, anchor_y, rotation, ...)
+
+The Label classes also follow a similar default argument ordering, with one
+small exception: Label and HTMLLabel take "text" as the first argument instead
+of "document". Other than that, the rest of the positional arguments line up::
+
+    DocumentLabel(document, x, y, z, width, height, anchor_x, anchor_y, rotation, ...)
+    Label(text, x, y, z, width, height, anchor_x, anchor_y, rotation, ...)
+    HTMLLabel(text, x, y, z, width, height, anchor_x, anchor_y, rotation, ...)
+
+The layouts and lables don't share all of the same argument, so the rest of the
+arguments will need to be provided as usual, where they differ. Please see the
+API documents for full details.
+
+Shapes
+------
+For consistency with the rest of the library, it was decided to represent
+all angles in degrees instead of radians. Previously we had a mix of both,
+which lead to some confusion. Using degrees also makes the API consistent
+with Sprites and other rotatable objects.
+
+The arguments for :py:class:`~pyglet.shapes.Line` have changed slightly.
+Instead of "width", we now use "thickness". This matches with other shapes
+that are made up of line segments. For example the :py:class:`~pyglet.shapes.Box`
+shape, which already uses "width" (and height) to mean it's overall size.
+Going forward, any shape that is made up of lines should use `thickness`
+for the width of those lines.
+
+Controllers
+-----------
+The Controller interface has been changed slightly. Analog sticks and dpad
+events now dispatch :py:class:`~pyglet.math.Vec2`, instead of individual float
+or boolean values. This can potentially save a few lines of code, and gives
+easy access to several helper methods found on the Vec classes. For instance,
+where you had to do this in the past::
+
+    @controller.event
+    def on_dpad_motion(controller, dpleft, dpright, dpup, dpdown):
+        if dpleft:
+            # move left
+        if dpright:
+            # move right
+        if dpright and dpdown:
+            # move diagonal, but have to normalize the values by yourself
+
+You now get a Vec2 instead of booleans that can be used directly::
+
+    @controller.event
+    def on_dpad_motion(controller, vector):
+        player_position += vector * PLAYER_SPEED
+        # Easily normalize for diagonal values:
+        player_position += vector.normalize() * PLAYER_SPEED
+
+Vectors can also be useful for analog sticks, because it gives an easy way to
+calculate dead-zones using `abs`. For example::
+
+    @controller.event
+    def on_stick_motion(controller, name, vector):
+        if abs(vector) <= DEADZONE:
+            return
+        elif name == "leftstick":
+            # Do something with the 2D vector
+        elif name == "rightstick":
+            # Do something with the 2D vector
+
+Normalization of vectors can also be useful for some analog sticks. When dealing
+with Controllers that have non-circular gates, the The absolute values of their
+combined x and y axis can sometimes exceed 1.0. Vector normalization can ensure
+that the maximum value stays within range. For example::
+
+            vector = min(vector, vector.normalize())
+
+You can also of course directly access the individual `Vec2.x` & `Vec2.y`
+attributes. See :py:class:`~pyglet.math.Vec2` for more details on vector types.
+
+Gui
+---
+
+All widget events now dispatch the widget instance itself as the first argument.
+This is similar to how Controller/Joystick events are implemented. In cases where
+the same handler function is set to multiple widgets, this gives a way to determine
+which widget has dispatched the event.
+
+The :py:class:`~pyglet.gui.widget.ToggleButton` and :py:class:`~pyglet.gui.widget.PushButton`
+widgets have a small change. Instead of the image arguments being named "pressed"
+and "depressed", they has been renamed to the correct "pressed" and "unpressed".
+
+Math module
+-----------
+In the :py:mod:`~pyglet.math` module, vector types (:py:class:`~pyglet.math.Vec2`,
+:py:class:`~pyglet.math.Vec3`, :py:class:`~pyglet.math.Vec4`) are now
+immutable; all operations will return a new object. In addition, all vector
+objects are now hashable. This has performance benefits, and matches how the Matrix
+types are implemented. For all intents and purposes, the Vec types can be treated
+as tuples.
+
+Canvas module
+-------------
+The `pyglet.canvas` module has been renamed to `pyglet.display`, as the canvas
+concept was never fully fleshed out. The canvas concept appears to have been
+meant to allow arbitrary renderable areas. This can now be easily accomplished
+with Framebuffers. The name `display` is a more accurate representation of what
+the code in the module actually relates to. The usage is the same, minus the
+name change::
+
+    my_display = pyglet.canvas.get_display()     # old pyglet 2.0
+    my_display = pyglet.display.get_display()    # new pyglet 2.1
+

{pyglet-2.0.15 → pyglet-2.1.dev2}/examples/clipboard.py

@@ -3,9 +3,9 @@ import pyglet
 """Simple example demonstrating how to get the text in the clipboard as well as putting text in the clipboard."""
 
 window = pyglet.window.Window()
-
 print("Existing Clipboard Text:", window.get_clipboard_text())
 
+
 @window.event
 def on_key_press(symbol, modifiers):
     print("Clipboard changed to: Hello World!")
@@ -15,4 +15,9 @@ def on_key_press(symbol, modifiers):
     print("Clipboard Text:", window.get_clipboard_text())
 
 
+@window.event
+def on_draw():
+    window.clear()
+
+
 pyglet.app.run()

pyglet-2.1.dev2/examples/dpi_scaled_window.py

@@ -0,0 +1,43 @@
+import pyglet
+pyglet.options["scale_with_dpi"] = True
+pyglet.options["debug_gl"] = False
+
+window = pyglet.window.Window(800, 600, caption="DPI Test", resizable=True)
+
+print(window.dpi, window.scale)
+
+label = pyglet.text.Label('Hello, world',
+                          font_name='Times New Roman',
+                          font_size=36,
+                          x=window.width//2, y=window.height//2,
+                          anchor_x='center', anchor_y='center'
+                          )
+
+dinosaur = pyglet.resource.animation("programming_guide/dinosaur.gif")
+
+sprite = pyglet.sprite.Sprite(dinosaur, x=100, y=100)
+
+@window.event
+def on_draw():
+    window.clear()
+    sprite.draw()
+    label.draw()
+
+@window.event
+def on_mouse_press(x, y, button, modifier):
+    print("Window Size:", window.get_size())
+    print("Scaled Click:", x, y)
+
+@window.event
+def on_resize(width, height):
+    window.on_resize(width, height)
+    print("RESIZED", width, height)
+
+@window.event
+def on_scale(scale, dpi):
+    print("SCALE_X", scale, dpi)
+    print("Window Size:", window.get_size())
+    print("Window Pixel Ratio:", window.get_pixel_ratio())
+    print("Window Frame Buffer Size:", window.get_framebuffer_size())
+
+pyglet.app.run()

{pyglet-2.0.15 → pyglet-2.1.dev2}/examples/gui/widgets.py

@@ -15,8 +15,8 @@ def on_draw():
 # load resources to use for Widgets:
 ####################################
 
-depressed = pyglet.resource.image('button_up.png')
-pressed = pyglet.resource.image('button_down.png')
+unpressed = pyglet.resource.image('button_unpressed.png')
+pressed = pyglet.resource.image('button_pressed.png')
 hover = pyglet.resource.image('button_hover.png')
 bar = pyglet.resource.image('bar.png')
 knob = pyglet.resource.image('knob.png')
@@ -26,23 +26,23 @@ knob = pyglet.resource.image('knob.png')
 # Create some event handler functions:
 ######################################
 
-def slider_handler(value):
+def slider_handler(widget, value):
     slider_label.text = f"Slider Value: {round(value, 1)}"
 
 
-def toggle_button_handler(value):
+def toggle_button_handler(widget, value):
     toggle_label.text = f"Toggle Button: {value}"
 
 
-def push_button_handler():
+def push_button_handler(widget):
     push_label.text = f"Push Button: True"
 
 
-def release_button_handler():
+def release_button_handler(widget):
     push_label.text = f"Push Button: False"
 
 
-def text_entry_handler(text):
+def text_entry_handler(widget, text):
     text_entry_label.text = f"Text: {text}"
 
 
@@ -55,13 +55,13 @@ def text_entry_handler(text):
 frame = pyglet.gui.Frame(window, order=4)
 
 
-togglebutton = pyglet.gui.ToggleButton(100, 400, pressed=pressed, depressed=depressed, hover=hover, batch=batch)
+togglebutton = pyglet.gui.ToggleButton(100, 400, pressed=pressed, unpressed=unpressed, hover=hover, batch=batch)
 togglebutton.set_handler('on_toggle', toggle_button_handler)
 frame.add_widget(togglebutton)
 toggle_label = pyglet.text.Label("Toggle Button: False", x=300, y=400, batch=batch, color=(0, 0, 0, 255))
 
 
-pushbutton = pyglet.gui.PushButton(100, 300, pressed=pressed, depressed=depressed, hover=hover, batch=batch)
+pushbutton = pyglet.gui.PushButton(100, 300, pressed=pressed, unpressed=unpressed, hover=hover, batch=batch)
 pushbutton.set_handler('on_press', push_button_handler)
 pushbutton.set_handler('on_release', release_button_handler)
 frame.add_widget(pushbutton)