Using the OpenGL interface directly, however, can be difficult to do
pyglet.graphics module provides a simpler means
for drawing graphics that uses vertex arrays and vertex buffer objects
internally to deliver better performance.
pyglet.graphics module draws the OpenGL primitive objects by
a mode denoted by the constants
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.
pyglet.graphics.draw() to directly 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.
However, because of the way the graphics API renders multiple primitives with
be used — the results are undefined.
NV_primitive_restart extension can be used if it is
present. This also permits use of
GL_TRIANGLE_FAN. Unfortunately the extension is not provided by older
video drivers, and requires indexed vertex lists.
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], ('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).
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
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,
"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.
Attribute Formats Recommended Vertex position
The possible data types that can be specified in the format string are described below.
Format Type Python type
Signed byte int
Unsigned byte int
Signed short int
Unsigned short int
Signed int int
Unsigned int int
Single precision float float
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
- Secondary color
- Generic attributes with the
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
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.
There is a significant overhead in using
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.
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.
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
Note that the primitive mode is given to the draw method, not the vertex list
constructor. Otherwise the
takes the same arguments as
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
The attribute names are given in the following table.
Vertex attribute Object attribute Vertex position
Generic attribute Inaccessible
In the following example, the vertex positions of the vertex list are updated
by replacing the
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')
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:
Data is never or rarely modified after initialisation
Data is occasionally modified (default)
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
static attribute can still be modified), and may only have
performance benefits on some hardware.
Indexed vertex lists¶
IndexedVertexList performs the same
VertexList, but for indexed
pyglet.graphics.vertex_list_indexed() to construct an
indexed vertex list, and update the
indices sequence to
change the indices.
|||Only texture coordinates for texture unit 0 are accessible through this attribute.|
For optimal OpenGL performance, you should render as many vertex lists as
possible in a single
draw call. Internally, pyglet uses
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
draw() on each individual
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.
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
add_indexed() methods instead of
pyglet.graphics.vertex_list_indexed() functions. Unlike the module
functions, these methods accept a
mode parameter (the primitive mode)
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:
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(). If you
don’t need to modify or delete vertex lists after adding them to the batch,
you can simply ignore the return value of the
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:
afterwards to avoid interfering with later drawing commands.
Group these state changes can be
encapsulated and associated with the vertex lists they affect.
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)) )
Batch ensures that the appropriate
unset_state methods are called before and after
the vertex lists that use them.
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
unset_state calls for vertex lists in a batch
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
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
__cmp__ method. This allows groups to be ordered.
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
which then renders it as efficiently as possible.
Batches and groups in other modules¶
TextLayout classes all accept
group parameters in their constructors. This allows you to add any of
these higher-level pyglet drawables into arbitrary places in your rendering
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()
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
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
group parameters in a similar way.