pyglet.graphics

Submodules

• pyglet.graphics.allocation
• pyglet.graphics.vertexattribute
• pyglet.graphics.vertexbuffer
• pyglet.graphics.vertexdomain

Details

Low-level graphics rendering.

This module provides an efficient low-level abstraction over OpenGL. It gives very good performance for rendering OpenGL primitives; far better than the typical immediate-mode usage and, on modern graphics cards, better than using display lists in many cases. The module is used internally by other areas of pyglet.

See the Graphics for details on how to use this graphics API.

Batches and groups

Without even needing to understand the details on how to draw primitives with the graphics API, developers can make use of Batch and Group objects to improve performance of sprite and text rendering.

The Sprite, Label() and TextLayout() classes all accept a batch and group parameter in their constructors. A batch manages a set of objects that will be drawn all at once, and a group describes the manner in which an object is drawn.

The following example creates a batch, adds two sprites to the batch, and then draws the entire batch:

batch = pyglet.graphics.Batch()
car = pyglet.sprite.Sprite(car_image, batch=batch)
boat = pyglet.sprite.Sprite(boat_image, batch=batch)

def on_draw()
    batch.draw()

Drawing a complete batch is much faster than drawing the items in the batch individually, especially when those items belong to a common group.

Groups describe the OpenGL state required for an item. This is for the most part managed by the sprite and text classes, however you can also use groups to ensure items are drawn in a particular order. For example, the following example adds a background sprite which is guaranteed to be drawn before the car and the boat:

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

background = pyglet.sprite.Sprite(background_image,
                                  batch=batch, group=background)
car = pyglet.sprite.Sprite(car_image, batch=batch, group=foreground)
boat = pyglet.sprite.Sprite(boat_image, batch=batch, group=foreground)

def on_draw()
    batch.draw()

It’s preferable to manage sprites and text objects within as few batches as possible. If the drawing of sprites or text objects need to be interleaved with other drawing that does not use the graphics API, multiple batches will be required.

Data item parameters

Many of the functions and methods in this module accept any number of data parameters as their final parameters. In the documentation these are notated as *data in the formal parameter list.

A data parameter describes a vertex attribute format and an optional sequence to initialise that attribute. Examples of common attribute formats are:

"v3f"

Vertex position, specified as three floats.

"c4B"

Vertex color, specified as four unsigned bytes.

"t2f"

Texture coordinate, specified as two floats.

See pyglet.graphics.vertexattribute for the complete syntax of the vertex format string.

When no initial data is to be given, the data item is just the format string. For example, the following creates a 2 element vertex list with position and color attributes:

vertex_list = pyglet.graphics.vertex_list(2, 'v2f', 'c4B')

When initial data is required, wrap the format string and the initial data in a tuple, for example:

vertex_list = pyglet.graphics.vertex_list(2,
                                          ('v2f', (0.0, 1.0, 1.0, 0.0)),
                                          ('c4B', (255, 255, 255, 255) * 2))

Drawing modes

Methods in this module that accept a mode parameter will accept any value in the OpenGL drawing mode enumeration: GL_POINTS, GL_LINE_STRIP, GL_LINE_LOOP, GL_LINES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_TRIANGLES, GL_QUAD_STRIP, GL_QUADS, and GL_POLYGON.

pyglet.graphics.draw(1, GL_POINTS, ('v2i',(10,20)))

However, because of the way the graphics API renders multiple primitives with shared state, GL_POLYGON, GL_LINE_LOOP and GL_TRIANGLE_FAN cannot be used — the results are undefined.

When using GL_LINE_STRIP, GL_TRIANGLE_STRIP or GL_QUAD_STRIP care must be taken to insert degenerate vertices at the beginning and end of each vertex list. For example, given the vertex list:

A, B, C, D

the correct vertex list to provide the vertex list is:

A, A, B, C, D, D

Alternatively, the NV_primitive_restart extension can be used if it is present. This also permits use of GL_POLYGON, GL_LINE_LOOP and GL_TRIANGLE_FAN. Unfortunately the extension is not provided by older video drivers, and requires indexed vertex lists.

New in version 1.1.

class Batch

Manage a collection of vertex lists for batched rendering.

Vertex lists are added to a Batch using the add and add_indexed methods. An optional group can be specified along with the vertex list, which gives the OpenGL state required for its rendering. Vertex lists with shared mode and group are allocated into adjacent areas of memory and sent to the graphics card in a single operation.

Call VertexList.delete to remove a vertex list from the batch.

add(count, mode, group, *data)

Add a vertex list to the batch.

Parameters:

• count (int) – The number of vertices in the list.
• mode (int) – OpenGL drawing mode enumeration; for example, one of GL_POINTS, GL_LINES, GL_TRIANGLES, etc. See the module summary for additional information.
• group (Group) – Group of the vertex list, or None if no group is required.
• data (data items) – Attribute formats and initial data for the vertex list. See the module summary for details.

Return type:

VertexList

add_indexed(count, mode, group, indices, *data)

Add an indexed vertex list to the batch.

Parameters:

• count (int) – The number of vertices in the list.
• mode (int) – OpenGL drawing mode enumeration; for example, one of GL_POINTS, GL_LINES, GL_TRIANGLES, etc. See the module summary for additional information.
• group (Group) – Group of the vertex list, or None if no group is required.
• indices (sequence) – Sequence of integers giving indices into the vertex list.
• data (data items) – Attribute formats and initial data for the vertex list. See the module summary for details.

Return type:

IndexedVertexList

draw()

Draw the batch.

draw_subset(vertex_lists)

Draw only some vertex lists in the batch.

The use of this method is highly discouraged, as it is quite inefficient. Usually an application can be redesigned so that batches can always be drawn in their entirety, using draw.

The given vertex lists must belong to this batch; behaviour is undefined if this condition is not met.

Parameters:vertex_lists (sequence of VertexList or IndexedVertexList) – Vertex lists to draw.

invalidate()

Force the batch to update the draw list.

This method can be used to force the batch to re-compute the draw list when the ordering of groups has changed.

New in version 1.2.

migrate(vertex_list, mode, group, batch)

Migrate a vertex list to another batch and/or group.

vertex_list and mode together identify the vertex list to migrate. group and batch are new owners of the vertex list after migration.

The results are undefined if mode is not correct or if vertex_list does not belong to this batch (they are not checked and will not necessarily throw an exception immediately).

batch can remain unchanged if only a group change is desired.

Parameters:

• vertex_list (VertexList) – A vertex list currently belonging to this batch.
• mode (int) – The current GL drawing mode of the vertex list.
• group (Group) – The new group to migrate to.
• batch (Batch) – The batch to migrate to (or the current batch).

class Group(parent=None)

Group of common OpenGL state.

Before a vertex list is rendered, its group’s OpenGL state is set; as are that state’s ancestors’ states. This can be defined arbitrarily on subclasses; the default state change has no effect, and groups vertex lists only in the order in which they are drawn.

set_state()

Apply the OpenGL state change.

The default implementation does nothing.

set_state_recursive()

Set this group and its ancestry.

Call this method if you are using a group in isolation: the parent groups will be called in top-down order, with this class’s set being called last.

unset_state()

Repeal the OpenGL state change.

The default implementation does nothing.

unset_state_recursive()

Unset this group and its ancestry.

The inverse of set_state_recursive.

batches

visible

class NullGroup(parent=None)

The default group class used when None is given to a batch.

This implementation has no effect.

class OrderedGroup(order, parent=None)

A group with partial order.

Ordered groups with a common parent are rendered in ascending order of their order field. This is a useful way to render multiple layers of a scene within a single batch.

class TextureGroup(texture, parent=None)

A group that enables and binds a texture.

Texture groups are equal if their textures’ targets and names are equal.

set_state()

Apply the OpenGL state change.

The default implementation does nothing.

unset_state()

Repeal the OpenGL state change.

The default implementation does nothing.

draw(size, mode, *data)

Draw a primitive immediately.

Parameters:

• size (int) – Number of vertices given
• mode (gl primitive type) – OpenGL drawing mode, e.g. GL_TRIANGLES, avoiding quotes.
• data (data items) – Attribute formats and data. See the module summary for details.

draw_indexed(size, mode, indices, *data)

Draw a primitive with indexed vertices immediately.

Parameters:

• size (int) – Number of vertices given
• mode (int) – OpenGL drawing mode, e.g. GL_TRIANGLES
• indices (sequence of int) – Sequence of integers giving indices into the vertex list.
• data (data items) – Attribute formats and data. See the module summary for details.

vertex_list(count, *data)

Create a VertexList not associated with a batch, group or mode.

Parameters:

• count (int) – The number of vertices in the list.
• data (data items) – Attribute formats and initial data for the vertex list. See the module summary for details.

Return type:

VertexList

vertex_list_indexed(count, indices, *data)

Create an IndexedVertexList not associated with a batch, group or mode.

Parameters:

• count (int) – The number of vertices in the list.
• indices (sequence) – Sequence of integers giving indices into the vertex list.
• data (data items) – Attribute formats and initial data for the vertex list. See the module summary for details.

Return type:

IndexedVertexList

null_group = <pyglet.graphics.NullGroup object>

The default group.

Type:Group