Table of contents

Introduction

Batches and groups

Data item parameters

Drawing modes

4.1.

1. classBatch

4.1.1.

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

4.1.2.

draw()

4.1.3.

draw_subset(vertex_lists)

4.1.4.

invalidate()

4.1.5.

migrate(vertex_list, mode, group, batch)

4.2.

2. classGroup(parent=None)

4.2.1.

set_state()

4.2.2.

set_state_recursive()

4.2.3.

unset_state()

4.2.4.

unset_state_recursive()

4.3.

3. classNullGroup(parent=None)

4.4.

4. classOrderedGroup(order, parent=None)

4.5.

5. classTextureGroup(texture, parent=None)

4.5.1.

set_state()

4.5.2.

unset_state()

4.6.

6. draw(size, mode, *data)

4.7.

7. draw_indexed(size, mode, indices, *data)

4.8.

8. vertex_list(count, *data)

4.8.1.

vertex_list_indexed(count, indices, *data)

4.9.

9. null_group= <pyglet.graphics.NullGroup object>

Frequently Asked Questions

5.1.

What is a pyglet?

5.2.

What are batch and group objects?

5.3.

What is the use of classBatch?

Conclusion

Last Updated: Mar 27, 2024

pyglet.graphics

Author Nagendra

Do you think IIT Guwahati certified course can help you in your career?

Yes

Introduction

Pyglet is a simple yet powerful library for creating aesthetically rich GUI programs on Windows, Mac OS, and Linux, such as games and multimedia. This Python-only package includes capabilities such as windowing, user interface event management, joysticks, OpenGL graphics, loading photos and movies, and playing sounds and music. Pyglet is released under the BSD open-source licence, which allows it to be used in both commercial and open-source projects with few restrictions. The article explains the details of pyglet.graphics module, batches and groups, and data item parameters.

Batches and groups

Developers can use Batch and Group objects to boost the performance of sprite and text rendering without having to grasp the nuances of how to draw primitives with the graphics API.
The constructors of the Sprite, Label(), and TextLayout() classes all accept a batch and group parameter. A batch is used to handle a collection of items that will be rendered all at once, while a group is used to specify how an object is drawn.
The example below generates a batch, adds two sprites to it, 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()

You can also try this code with Online Python Compiler

Run Code

Drawing a batch as a whole is substantially faster than drawing individual things, especially when the pieces are all part of the same group.
The OpenGL state necessary for an item is described by groups. The sprite and text classes are primarily responsible for this, although groups can also be used to ensure that things are drawn in a specific order. The following example, for example, adds a background sprite that will always be drawn before the automobile 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()

You can also try this code with Online Python Compiler

Run Code

Sprites and text elements should be managed in as few batches as possible. Multiple batches will be required if sprites or text objects must be interleaved with other rendering that does not use the graphics API.

Data item parameters

As final parameters, several of the procedures and methods in this module accept any number of data parameters. In the formal parameter list, these are denoted as *data in the documentation.
A data argument specifies the format of a vertex attribute and an optional sequence for initialising it. The following are some examples of typical attribute formats:

"v3f" - Three floats specify the vertex position.
" c4B " - Four unsigned bytes specify the vertex colour.
" t2f " - Two floats specify texture coordinates.

The data item is simply the format string when no starting data is provided. The following code, for example, generates a two-element vertex list with position and colour attributes:

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

You can also try this code with Online Python Compiler

Run Code

Wrap the format string and the starting data in a tuple when initial data is required, for example:

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

You can also try this code with Online Python Compiler

Run Code

Drawing modes

Any value as a parameter in the OpenGL drawing mode enumeration will be accepted by methods in the module that accept a mode parameter.GL_POINTS, GL_LINE_LOOP, GL_LINES, GL_TRIANGLE_STRIP, GL_LINE_STRIP, GL_TRIANGLE_FAN, GL_QUAD_STRIP, GL_TRIANGLES, GL_QUADS, and GL_POLYGON.

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

You can also try this code with Online Python Compiler

Run Code

GL_LINE_LOOP, GL_POLYGON, and GL_TRIANGLE_FAN, on the other hand, cannot be utilised because of the way the graphics API produces multiple primitives with shared state – the results are undefined.

When using GL_TRIANGLE_STRIP, GL_LINE_STRIP, or GL_QUAD_STRIP, it's important to avoid putting degenerate vertices at the start and end of each vertex list. Given the vertex list, for example:

A, B, C, D

You can also try this code with Online Python Compiler

Run Code

The following is the correct vertex list to provide:

A, A, B, C, D, D

You can also try this code with Online Python Compiler

Run Code

If the NV_primitive_restart extension is provided, it can be used instead. GL_LINE_LOOP, GL_POLYGON, and GL_TRIANGLE_FAN can now be used. Unfortunately, older video drivers do not support the extension, which requires indexed vertex lists.

1. classBatch

For batch rendering, manage a collection of vertex lists. The add and add indexed methods are used to add vertex lists to a Batch. Along with the vertex list, an optional group can be given, which specifies the OpenGL state necessary for rendering. In a single operation, shared mode and group vertex lists are allocated into adjacent memory locations and delivered to the graphics hardware.
In order to remove a vertex list from a batch, use VertexList.delete.

add(count, mode, group, *data)
It is used to add a vertex list to the batch.

Parameters:

count (int) – The number of vertices present in the list.
mode (int) – It is the OpenGL drawing mode enumeration; for example, one of GL_LINES, GL_POINTS, GL_TRIANGLES, etc.
group (Group) – It represents the group of the vertex list, or None if there is no group required.
data (data items) – It contains the attribute formats and initial data for the vertex list.

Return type:

It returns the VertexList.

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

It is used to add an indexed vertex list.

Parameters:

count (int) – The number of vertices present in the list.
mode (int) – It is the OpenGL drawing mode enumeration; for example, one of GL_LINES, GL_POINTS, GL_TRIANGLES, etc.
group (Group) – It represents the group of the vertex list, or None if there is no group required.
data (data items) – It contains the attribute formats and initial data for the vertex list.

Return type:

IndexedVertexList

draw()

It is used to draw the batch.

draw_subset(vertex_lists)

It's used to draw only some of the batch's vertex lists.

This method is extremely inefficient. Hence it is strongly discouraged. Typically, an application can be redesigned so that batches can be drawn in their entirety using draw at any time.

The specified vertex lists must be part of this batch; otherwise, the behavior is undefined.

Parameters:

vertex_lists (IndexedVertexList) – Vertex lists to draw.

invalidate()

The batch is forced to update the draw list. When the order of groups in the batch has changed, this method can be used to compel the batch to re-compute the draw list.

migrate(vertex_list, mode, group, batch)

Transfer a vertex list to a new batch or group. The vertex list to migrate is identified by the combination of vertex list and mode. After migration, group and batch are the new owners of the vertex list. If the mode is incorrect or the vertex_list does not belong to this batch, the results are undefined (they are not checked and will not necessarily throw an exception immediately). If only a group modification is required, the batch can be left intact.

Parameters:

vertex_list (VertexList) – It contains a vertex list which is currently belonging to this batch.
mode (int) – It depicts the current GL drawing mode of the vertex list.
group (Group) – This represents the new group to migrate.
batch (Batch) – It consists of the batch to migrate to (or the current batch).

2. classGroup(parent=None)

A collection of common OpenGL states. The OpenGL state of a vertex list's group, as well as the states of its ancestors, is set before it is rendered. The default state modification has no effect and just organises vertex lists in the order in which they are drawn.

set_state()

It is used to change the state of OpenGL. The default implementation is completely useless.

set_state_recursive()

It is used to set the ancestry of this group. If you're utilising a group in isolation, call this method: the parent groups will be called in order, with this class's set coming last.

unset_state()

It is used to remove the OpenGL state modification. The default implementation is completely useless.

unset_state_recursive()

It is used to remove this group's ancestors. It is the inverse of set_state_recursive.

batches

visible

3. classNullGroup(parent=None)

When a batch is supplied None, this is the default group class.

This implementation has no impact.

4. classOrderedGroup(order, parent=None)

It is a partially ordered group. Ordered groups with a shared parent are rendered in the order field's ascending order. This is a handy method for rendering several levels of a scene in a single batch.

5. classTextureGroup(texture, parent=None)

A texture enabling and binding group. Texture groups are equal if the targets and names of their textures are the same.

set_state()

It is used to change the state of OpenGL. The default implementation is completely useless.

unset_state()

It is used to remove the OpenGL state modification. The default implementation is completely useless.

**6. draw(size, mode, *data)**

It is used to draw a primitive immediately.

Parameters:

size (int) – It represents the number of vertices given
mode (gl primitive type) – It is the OpenGL drawing mode, for example, GL_TRIANGLES.
data (data items) – It consists of the attribute formats and data.

**7. draw_indexed(size, mode, indices, *data)**

Immediately draw a primitive with indexed vertices.

Parameters:

size (int) – It represents the number of vertices given
mode (gl primitive type) – It is the OpenGL drawing mode, for example, GL_TRIANGLES.
indices (sequence of int) – It is the sequence of the integers giving indices into the vertex list.
data (data items) – It consists of the attribute formats and data.

**8. vertex_list(count, *data)**

It is used to make a VertexList that isn't linked to a batch, group, or mode.

Parameters:

count (int) – It consists of the number of vertices in the list.
data (data items) – It consists of the attribute formats and data.

Return type:

VertexList

**vertex_list_indexed(count, indices, *data)**

It is used to make an IndexedVertexList that isn't tied to a batch, group, or mode.

Parameters:

count (int) – It consists of the number of vertices in the list.
indices (sequence of int) – It is the sequence of the integers giving indices into the vertex list.
data (data items) – It consists of the attribute formats and data.

Return type:

IndexedVertexList

9. null_group= <pyglet.graphics.NullGroup object>

It is the default group.

Type: Group

Frequently Asked Questions

What is a pyglet?

Pyglet is a Python library that provides an object-oriented application programming interface for the development of games and other multimedia applications.

What are batch and group objects?

Batch and Group objects are used to boost the performance of sprite and text rendering without having to grasp the nuances of how to draw primitives with the graphics API.

What is the use of classBatch?

It is used for batch rendering and managing a collection of vertex lists.

Conclusion

In this article, we have extensively discussed pyglet.graphics. The article explains the details of pyglet.graphics, and details of its different class objects.
We hope that this blog has helped you enhance your knowledge regarding pyglet.graphics and if you would like to learn more, check out our articles on pyglet. You can refer to our guided paths on the Coding Ninjas Studio platform to learn more about DSA, DBMS, Competitive Programming, Python, Java, JavaScript, etc. To practice and improve yourself in the interview, you can also check out Top 100 SQL problems, Interview experience, Coding interview questions, and the Ultimate guide path for interviews.

Do upvote our blog to help other ninjas grow.

Happy Coding!!

Live masterclass

Become a YouTube Analyst: Use Python to analyze viewers data

by Coding Ninjas

04 Feb, 2025

02:30 PM

84+ registered

Get hired as an Amazon SDE : Resume building tips

by Coding Ninjas

03 Feb, 2025

02:30 PM

379+ registered

Expert tips: Ace Leadership roles in Fortune 500 companies

by Coding Ninjas

03 Feb, 2025

12:30 PM

71+ registered

Become a YouTube Analyst: Use Python to analyze viewers data

by Coding Ninjas

04 Feb, 2025

02:30 PM

84+ registered

Get hired as an Amazon SDE : Resume building tips

by Coding Ninjas

03 Feb, 2025

02:30 PM

379+ registered

View more events