# Package pyglet.graphics

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 Programming Guide 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, specifed 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; for example, `GL_POINTS`, `GL_LINES`, `GL_TRIANGLES`, etc.

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 degenrate 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`. Unfortunatley the extension is not provided by older video drivers, and requires indexed vertex lists.

Since: pyglet 1.1

## Submodules

| pyglet.graphics.allocation Memory allocation algorithm for vertex arrays and buffers.
| pyglet.graphics.vertexattribute Access byte arrays as arrays of vertex attributes.
| pyglet.graphics.vertexbuffer Byte abstractions of Vertex Buffer Objects and vertex arrays.
| pyglet.graphics.vertexdomain Manage related vertex attributes within a single vertex domain.

## Classes

| Batch Manage a collection of vertex lists for batched rendering.
| Group Group of common OpenGL state.
| NullGroup The default group class used when `None` is given to a batch.
| TextureGroup A group that enables and binds a texture.
| OrderedGroup A group with partial order.

## Functions

| draw(size, mode, *data) Draw a primitive immediately.
| draw_indexed(size, mode, indices, *data) Draw a primitive with indexed vertices immediately.
VertexList | vertex_list(count, *data) Create a VertexList not associated with a batch, group or mode.
IndexedVertexList | vertex_list_indexed(count, indices, *data) Create an IndexedVertexList not associated with a batch, group or mode.

## Variables

Group | null_group = `NullGroup()` The default group.

## Function Details

### draw

draw(size, mode, *data)
Draw a primitive immediately.

Parameters:
  size : int
    Number of vertices given
  mode : int
    OpenGL drawing mode, e.g. `GL_TRIANGLES`
  data : data items
    Attribute formats and data. See the module summary for details.

### draw_indexed

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

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.
Returns: VertexList

### vertex_list_indexed

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.
Returns: IndexedVertexList