Graphics
========

At the lowest level, pyglet uses OpenGL to draw in windows.  The OpenGL
interface is exposed via the `pyglet.gl` module (see `The OpenGL interface`).

However, using the OpenGL interface directly for drawing graphics is difficult
and inefficient.  The `pyglet.graphics` module provides a simpler means for
drawing graphics that uses vertex arrays and vertex buffer objects internally
to deliver better performance.

.. contents::
    :local:

Drawing primitives
------------------

The `pyglet.graphics` module draws the OpenGL primitive objects by a mode
denoted by the constants

* ``pyglet.gl.GL_POINTS``
* ``pyglet.gl.GL_LINES``
* ``pyglet.gl.GL_LINE_LOOP``
* ``pyglet.gl.GL_LINE_STRIP``
* ``pyglet.gl.GL_TRIANGLES``
* ``pyglet.gl.GL_TRIANGLE_STRIP``
* ``pyglet.gl.GL_TRIANGLE_FAN``
* ``pyglet.gl.GL_QUADS``
* ``pyglet.gl.GL_QUAD_STRIP``
* ``pyglet.gl.GL_POLYGON``

See the `OpenGL Programming Guide`_ for a description of each of mode.

Each primitive is made up of one or more vertices.  Each vertex is specified
with either 2, 3 or 4 components (for 2D, 3D, or non-homogeneous coordinates).
The data type of each component can be either int or float.

Use `pyglet.graphics.draw` to draw a primitive.  The following example draws
two points at coordinates (10, 15) and (30, 35)::

    pyglet.graphics.draw(2, pyglet.gl.GL_POINTS, 
        ('v2i', (10, 15, 30, 35))
    )

The first and second arguments to the function give the number of vertices to
draw and the primitive mode, respectively.  The third argument is a "data
item", and gives the actual vertex data.

Because vertex data can be supplied in several forms, a "format string" is
required.  In this case, the format string is ``"v2i"``, meaning the vertex
position data has two components (2D) and int type.

The following example has the same effect as the previous one, but uses
floating point data and 3 components per vertex::

    pyglet.graphics.draw(2, pyglet.gl.GL_POINTS, 
        ('v3f', (10.0, 15.0, 0.0, 30.0, 35.0, 0.0))
    )

Vertices can also be drawn out of order and more than once by using the
`pyglet.graphics.draw_indexed` function.  This requires a list of integers
giving the indices into the vertex data.  The following example draws the same
two points as above, but indexes the vertices (sequentially)::

    pyglet.graphics.draw_indexed(2, pyglet.gl.GL_POINTS, 
        [0, 1, 2, 3],
        ('v2i', (10, 15, 30, 35))
    )

This second example is more typical; two adjacent triangles are drawn, and the
shared vertices are reused with indexing::

    pyglet.graphics.draw_indexed(4, pyglet.gl.GL_TRIANGLES,
        [0, 1, 2, 0, 2, 3],
        ('v2i', (100, 100,
                 150, 100,
                 150, 150,
                 100, 150))
    )

Note that the first argument gives the number of vertices in the data, not the
number of indices (which is implicit on the length of the index list given in
the third argument).

Vertex attributes
-----------------

Besides the required vertex position, vertices can have several other numeric
attributes.  Each is specified in the format string with a letter, the number
of components and the data type.  

Each of the attributes is described in the table below with the set of valid
format strings written as a regular expression (for example, ``"v[234][if]"``
means ``"v2f"``, ``"v3i"``, ``"v4f"``, etc. are all valid formats).

Some attributes have a "recommended" format string, which is the most efficient
form for the video driver as it requires less conversion.

    .. list-table::
        :header-rows: 1

        * - Attribute
          - Formats
          - Recommended
        * - Vertex position
          - ``"v[234][sifd]"``
          - ``"v[234]f"``
        * - Color
          - ``"c[34][bBsSiIfd]"``
          - ``"c[34]B"``
        * - Edge flag
          - ``"e1[bB]"``
          -
        * - Fog coordinate
          - ``"f[1234][bBsSiIfd]"``
          -
        * - Normal
          - ``"n3[bsifd]"``
          - ``"n3f"``
        * - Secondary color
          - ``"s[34][bBsSiIfd]"``
          - ``"s[34]B"``
        * - Texture coordinate
          - ``"[0-31]?t[234][sifd]"``
          - ``"[0-31]?t[234]f"``
        * - Generic attribute
          - ``"[0-15]g(n)?[1234][bBsSiIfd]"``
          -

The possible data types that can be specified in the format string are
described below.

    .. list-table::
        :header-rows: 1

        * - Format
          - Type
          - Python type
        * - ``"b"``
          - Signed byte
          - int
        * - ``"B"``
          - Unsigned byte
          - int
        * - ``"s"``
          - Signed short
          - int
        * - ``"S"``
          - Unsigned short
          - int
        * - ``"i"``
          - Signed int
          - int
        * - ``"I"``
          - Unsigned int
          - int
        * - ``"f"``
          - Single precision float
          - float
        * - ``"d"``
          - Double precision float
          - float

The following attributes are normalised to the range ``[0, 1]``.  The value is
used as-is if the data type is floating-point.  If the data type is byte,
short or int, the value is divided by the maximum value representable by that
type.  For example, unsigned bytes are divided by 255 to get the normalised
value.

* Color
* Secondary color
* Generic attributes with the ``"n"`` format given.

Texture coordinate attributes may optionally be preceded by a texture unit
number.  If unspecified, texture unit 0 (``GL_TEXTURE0``) is implied.  It is
the application's responsibility to ensure that the OpenGL version is adequate
and that the specified texture unit is within the maximum allowed by the
implementation.

Up to 16 generic attributes can be specified per vertex, and can be used by
shader programs for any purpose (they are ignored in the fixed-function
pipeline).  For the other attributes, consult the OpenGL programming guide for
details on their effects.

When using the `pyglet.graphics.draw` and related functions, attribute data is
specified alongside the vertex position data.  The following example
reproduces the two points from the previous page, except that the first point
is blue and the second green::

    pyglet.graphics.draw(2, pyglet.gl.GL_POINTS, 
        ('v2i', (10, 15, 30, 35)),
        ('c3B', (0, 0, 255, 0, 255, 0))
    )

It is an error to provide more than one set of data for any attribute, or to
mismatch the size of the initial data with the number of vertices specified in
the first argument.

Vertex lists
------------

There is a significant overhead in using `pyglet.graphics.draw` and
`pyglet.graphics.draw_indexed` due to pyglet interpreting and formatting
the vertex data for the video device.  Usually the data drawn in each frame
(of an animation) is identical or very similar to the previous frame, so
this overhead is unnecessarily repeated.

A `VertexList` is a list of vertices and their attributes, stored in
an efficient manner that's suitable for direct upload to the video card.
On newer video cards (supporting OpenGL 1.5 or later) the data is actually
stored in video memory.

Create a `VertexList` for a set of attributes and initial data with
`pyglet.graphics.vertex_list`.  The following example creates a vertex
list with the two coloured points used in the previous page::

    vertex_list = pyglet.graphics.vertex_list(2,
        ('v2i', (10, 15, 30, 35)),
        ('c3B', (0, 0, 255, 0, 255, 0))
    )
    
To draw the vertex list, call its `VertexList.draw` method::

    vertex_list.draw(pyglet.gl.GL_POINTS)

Note that the primitive mode is given to the draw method, not the vertex list
constructor.  Otherwise the `vertex_list` method takes the same arguments
as `pyglet.graphics.draw`, including any number of vertex attributes.

Because vertex lists can reside in video memory, it is necessary to call the
`delete` method to release video resources if the vertex list isn't going to
be used any more (there's no need to do this if you're just exiting the
process).

Updating vertex data
^^^^^^^^^^^^^^^^^^^^

The data in a vertex list can be modified.  Each vertex attribute (including
the vertex position) appears as an attribute on the `VertexList` object.  The
attribute names are given in the following table.

    .. list-table::
        :header-rows: 1

        * - Vertex attribute
          - Object attribute
        * - Vertex position
          - ``vertices``
        * - Color
          - ``colors``
        * - Edge flag
          - ``edge_flags``
        * - Fog coordinate
          - ``fog_coords``
        * - Normal
          - ``normals``
        * - Secondary color
          - ``secondary_colors``
        * - Texture coordinate
          - ``tex_coords`` [#multitex]_
        * - Generic attribute
          - *Inaccessible*

In the following example, the vertex positions of the vertex list are updated
by replacing the ``vertices`` attribute::

    vertex_list.vertices = [20, 25, 40, 45]

The attributes can also be selectively updated in-place::

    vertex_list.vertices[:2] = [30, 35]

Similarly, the color attribute of the vertex can be updated::

    vertex_list.colors[:3] = [255, 0, 0]

For large vertex lists, updating only the modified vertices can have a
perfomance benefit, especially on newer graphics cards.

Attempting to set the attribute list to a different size will cause an error
(not necessarily immediately, either).  To resize the vertex list, call
`VertexList.resize` with the new vertex count.  Be sure to fill in any
newly uninitialised data after resizing the vertex list.

Since vertex lists are mutable, you may not necessarily want to initialise
them with any particular data.  You can specify just the format string in
place of the ``(format, data)`` tuple in the data arguments `vertex_list`
function.  The following example creates a vertex list of 1024 vertices with
positional, color, texture coordinate and normal attributes::
    
    vertex_list = pyglet.graphics.vertex_list(1024, 'v3f', 'c4B', 't2f', 'n3f')

Data usage
^^^^^^^^^^

By default, pyglet assumes vertex data will be updated less often than it is
drawn, but more often than just during initialisation.  You can override
this assumption for each attribute by affixing a usage specification
onto the end of the format string, detailed in the following table:

    .. list-table::
        :header-rows: 1

        * - Usage
          - Description
        * - ``"/static"``
          - Data is never or rarely modified after initialisation
        * - ``"/dynamic"``
          - Data is occasionally modified (default)
        * - ``"/stream"``
          - Data is updated every frame

In the following example a vertex list is created in which the positional data
is expected to change every frame, but the color data is expected to remain
relatively constant::

    vertex_list = pyglet.graphics.vertex_list(1024, 'v3f/stream', 'c4B/static')

The usage specification affects how pyglet lays out vertex data in memory,
whether or not it's stored on the video card, and is used as a hint to OpenGL.
Specifying a usage does not affect what operations are possible with a vertex
list (a ``static`` attribute can still be modified), and may only have
performance benefits on some hardware.

Indexed vertex lists
^^^^^^^^^^^^^^^^^^^^

`IndexedVertexList` performs the same role as `VertexList`, but for indexed
vertices.  Use `pyglet.graphics.vertex_list_indexed` to construct an indexed
vertex list, and update the `IndexedVertexList.indices` sequence to change the
indices.

.. [#multitex] Only texture coordinates for texture unit 0 are accessible
    through this attribute.

Batched rendering
-----------------

For optimal OpenGL performance, you should render as many vertex lists as
possible in a single ``draw`` call.  Internally, pyglet uses `VertexDomain`
and `IndexedVertexDomain` to keep vertex lists that share the same attribute
formats in adjacent areas of memory.  The entire domain of vertex lists can
then be drawn at once, without calling `VertexList.draw` on each individual
list.

It is quite difficult and tedious to write an application that manages vertex
domains itself, though.  In addition to maintaining a vertex domain for each
set of attribute formats, domains must also be separated by primitive mode and
required OpenGL state.

The `Batch` class implements this functionality, grouping related vertex lists
together and sorting by OpenGL state automatically.  A batch is created with
no arguments::

    batch = pyglet.graphics.Batch()

Vertex lists can now be created with the `Batch.add` and `Batch.add_indexed`
methods instead of `pyglet.graphics.vertex_list` and
`pyglet.graphics.vertex_list_indexed` functions.  Unlike the module functions,
these methods accept a ``mode`` parameter (the primitive mode) and a ``group``
parameter (described below).

The two coloured points from previous pages can be added to a batch as a
single vertex list with::

    vertex_list = batch.add(2, pyglet.gl.GL_POINTS, None,
        ('v2i', (10, 15, 30, 35)),
        ('c3B', (0, 0, 255, 0, 255, 0))
    )

The resulting `vertex_list` can be modified as described in the previous
section.  However, instead of calling `VertexList.draw` to draw it, call
`Batch.draw` to draw all vertex lists contained in the batch at once::

    batch.draw()

For batches containing many vertex lists this gives a significant performance
improvement over drawing individual vertex lists.

To remove a vertex list from a batch, call `VertexList.delete`.

Setting the OpenGL state
^^^^^^^^^^^^^^^^^^^^^^^^

In order to achieve many effects in OpenGL one or more global state parameters
must be set.  For example, to enable and bind a texture requires::

    from pyglet.gl import *
    glEnable(texture.target)
    glBindTexture(texture.target, texture.id)

before drawing vertex lists, and then::

    glDisable(texture.target)

afterwards to avoid interfering with later drawing commands.

With a `Group` these state changes can be encapsulated and associated with the
vertex lists they affect.  Subclass `Group` and override the `Group.set_state`
and `Group.unset_state` methods to perform the required state changes::

    class CustomGroup(pyglet.graphics.Group):
        def set_state(self):
            glEnable(texture.target)
            glBindTexture(texture.target, texture.id)

        def unset_state(self):
            glDisable(texture.target)

An instance of this group can now be attached to vertex lists in the batch::

    custom_group = CustomGroup()
    vertex_list = batch.add(2, pyglet.gl.GL_POINTS, custom_group,
        ('v2i', (10, 15, 30, 35)),
        ('c3B', (0, 0, 255, 0, 255, 0))
    )

The `Batch` ensures that the appropriate ``set_state`` and ``unset_state``
methods are called before and after the vertex lists that use them.

Hierarchical state
^^^^^^^^^^^^^^^^^^

Groups have a `parent` attribute that allows them to be implicitly organised
in a tree structure.  If groups **B** and **C** have parent **A**, then the
order of ``set_state`` and ``unset_state`` calls for vertex lists in a batch
will be::

    A.set_state()
    # Draw A vertices
    B.set_state()
    # Draw B vertices
    B.unset_state()
    C.set_state()
    # Draw C vertices
    C.unset_state()
    A.unset_state()

This is useful to group state changes into as few calls as possible.  For
example, if you have a number of vertex lists that all need texturing enabled,
but have different bound textures, you could enable and disable texturing in
the parent group and bind each texture in the child groups.  The following
example demonstrates this::

    class TextureEnableGroup(pyglet.graphics.Group):
        def set_state(self):
            glEnable(GL_TEXTURE_2D)

        def unset_state(self):
            glDisable(GL_TEXTURE_2D)

    texture_enable_group = TextureEnableGroup()

    class TextureBindGroup(pyglet.graphics.Group):
        def __init__(self, texture):
            super(TextureBindGroup, self).__init__(parent=texture_enable_group)
            assert texture.target = GL_TEXTURE_2D
            self.texture = texture

        def set_state(self):
            glBindTexture(GL_TEXTURE_2D, self.texture.id)

        # No unset_state method required.

        def __eq__(self, other):
            return (self.__class__ is other.__class__ and 
                    self.texture.id == other.texture.id and
                    self.texture.target == other.texture.target and
                    self.parent == other.parent)

        def __hash__(self):
            return hash((self.texture.id, self.texture.target))

    batch.add(4, GL_QUADS, TextureBindGroup(texture1), 'v2f', 't2f')
    batch.add(4, GL_QUADS, TextureBindGroup(texture2), 'v2f', 't2f')
    batch.add(4, GL_QUADS, TextureBindGroup(texture1), 'v2f', 't2f')

Note the use of an ``__eq__`` method on the group to allow `Batch` to merge
the two ``TextureBindGroup`` identical instances.

Sorting vertex lists
^^^^^^^^^^^^^^^^^^^^

`VertexDomain` does not attempt to keep vertex lists in any particular order.
So, any vertex lists sharing the same primitive mode, attribute formats and
group will be drawn in an arbitrary order.  However, `Batch` will sort `Group`
objects sharing the same parent by their ``__cmp__`` method.  This allows
groups to be ordered.

The `OrderedGroup` class is a convenience group that does not set any OpenGL
state, but is parameterised by an integer giving its draw order.  In the
following example a number of vertex lists are grouped into a "background"
group that is drawn before the vertex lists in the "foreground" group::

    background = pyglet.graphics.OrderedGroup(0)
    foreground = pyglet.graphics.OrderedGroup(1)

    batch.add(4, GL_QUADS, foreground, 'v2f')
    batch.add(4, GL_QUADS, background, 'v2f')
    batch.add(4, GL_QUADS, foreground, 'v2f')
    batch.add(4, GL_QUADS, background, 'v2f', 'c4B')
    
By combining hierarchical groups with ordered groups it is possible to
describe an entire scene within a single `Batch`, which then renders it as
efficiently as possible.

Batches and groups in other modules
-----------------------------------

The `Sprite`, `Label` and `TextLayout` classes all accept ``batch`` and
``group`` parameters in their constructors.  This allows you to add any of
these higher-level pyglet drawables into arbitrary places in your rendering
code.

For example, multiple sprites can be grouped into a single batch and then
drawn at once, instead of calling `Sprite.draw` on each one individually::

    batch = pyglet.graphics.Batch()
    sprites = [pyglet.sprite.Sprite(image, batch=batch) for i in range(100)]

    batch.draw()

The ``group`` parameter can be used to set the drawing order (and hence which
objects overlap others) within a single batch, as described  on the previous
page.

In general you should batch all drawing objects into as few batches as
possible, and use groups to manage the draw order and other OpenGL state
changes for optimal performance.   If you are creating your own drawable
classes, consider adding ``batch`` and ``group`` parameters in a similar way.
