pyglet.graphics.vertexbuffer¶

Byte abstractions of Vertex Buffer Objects and vertex arrays.

Use create_buffer() or create_mappable_buffer() to create a Vertex Buffer Object, or a vertex array if VBOs are not supported by the current context.

Buffers can optionally be created “mappable” (incorporating the AbstractMappable mix-in). In this case the buffer provides a get_region() method which provides the most efficient path for updating partial data within the buffer.

class AbstractBuffer¶

Abstract buffer of byte data.

Variables:	size (int) – Size of buffer, in bytes ptr (int) – Memory offset of the buffer, as used by the `glVertexPointer` family of functions target (int) – OpenGL buffer target, for example `GL_ARRAY_BUFFER` usage (int) – OpenGL buffer usage, for example `GL_DYNAMIC_DRAW`

bind()¶: Bind this buffer to its OpenGL target.

delete()¶: Delete this buffer, reducing system resource usage.

map(invalidate=False)¶

Map the entire buffer into system memory.

The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.

Parameters:	invalidate (bool) – If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.
Return type:	`POINTER(ctypes.c_ubyte)`
Returns:	Pointer to the mapped block in memory

resize(size)¶

Resize the buffer to a new size.

Parameters:	size (int) – New size of the buffer, in bytes

set_data(data)¶

Set the entire contents of the buffer.

Parameters:	data (sequence of int or ctypes pointer) – The byte array to set.

set_data_region(data, start, length)¶

Set part of the buffer contents.

Parameters:	data (sequence of int or ctypes pointer) – The byte array of data to set start (int) – Offset to start replacing data length (int) – Length of region to replace

unbind()¶: Reset the buffer’s OpenGL target.

unmap()¶: Unmap a previously mapped memory block.

ptr = 0¶

size = 0¶

class AbstractBufferRegion¶

A mapped region of a buffer.

Buffer regions are obtained using get_region().

Variables:	array (ctypes array) – Array of data, of the type and count requested by `get_region()`.

invalidate()¶

Mark this region as changed.

The buffer may not be updated with the latest contents of the array until this method is called. (However, it may not be updated until the next time the buffer is used, for efficiency).

class AbstractMappable¶

get_region(start, size, ptr_type)¶

Map a region of the buffer into a ctypes array of the desired type. This region does not need to be unmapped, but will become invalid if the buffer is resized.

Note that although a pointer type is required, an array is mapped. For example:

get_region(0, ctypes.sizeof(c_int) * 20, ctypes.POINTER(c_int * 20))

will map bytes 0 to 80 of the buffer to an array of 20 ints.

Changes to the array may not be recognised until the region’s AbstractBufferRegion.invalidate() method is called.

Parameters:	start (int) – Offset into the buffer to map from, in bytes size (int) – Size of the buffer region to map, in bytes ptr_type (ctypes pointer type) – Pointer type describing the array format to create
Return type:	`AbstractBufferRegion`

class IndirectArrayRegion(region, size, component_count, component_stride)¶

A mapped region in which data elements are not necessarily contiguous.

This region class is used to wrap buffer regions in which the data must be accessed with some stride. For example, in an interleaved buffer this region can be used to access a single interleaved component as if the data was contiguous.

invalidate()¶

Mark this region as changed.

The buffer may not be updated with the latest contents of the array until this method is called. (However, it may not be updated until the next time the buffer is used, for efficiency).

class MappableVertexBufferObject(size, target, usage)¶

A VBO with system-memory backed store.

Updates to the data via set_data(), set_data_region() and map() will be held in local memory until bind() is called. The advantage is that fewer OpenGL calls are needed, increasing performance.

There may also be less performance penalty for resizing this buffer.

Updates to data via map() are committed immediately.

bind()¶: Bind this buffer to its OpenGL target.

get_region(start, size, ptr_type)¶

Map a region of the buffer into a ctypes array of the desired type. This region does not need to be unmapped, but will become invalid if the buffer is resized.

Note that although a pointer type is required, an array is mapped. For example:

get_region(0, ctypes.sizeof(c_int) * 20, ctypes.POINTER(c_int * 20))

will map bytes 0 to 80 of the buffer to an array of 20 ints.

Changes to the array may not be recognised until the region’s AbstractBufferRegion.invalidate() method is called.

Parameters:	start (int) – Offset into the buffer to map from, in bytes size (int) – Size of the buffer region to map, in bytes ptr_type (ctypes pointer type) – Pointer type describing the array format to create
Return type:	`AbstractBufferRegion`

map(invalidate=False)¶

Map the entire buffer into system memory.

The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.

Parameters:	invalidate (bool) – If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.
Return type:	`POINTER(ctypes.c_ubyte)`
Returns:	Pointer to the mapped block in memory

resize(size)¶

Resize the buffer to a new size.

Parameters:	size (int) – New size of the buffer, in bytes

set_data(data)¶

Set the entire contents of the buffer.

Parameters:	data (sequence of int or ctypes pointer) – The byte array to set.

set_data_region(data, start, length)¶

Set part of the buffer contents.

Parameters:	data (sequence of int or ctypes pointer) – The byte array of data to set start (int) – Offset to start replacing data length (int) – Length of region to replace

unmap()¶: Unmap a previously mapped memory block.

class VertexArray(size)¶

A ctypes implementation of a vertex array.

Many of the methods on this class are effectively no-op’s, such as bind(), unbind(), map(), unmap() and delete(); they exist in order to present a consistent interface with VertexBufferObject.

This buffer type is also mappable, and so get_region() can be used.

bind()¶: Bind this buffer to its OpenGL target.

delete()¶: Delete this buffer, reducing system resource usage.

get_region(start, size, ptr_type)¶

Map a region of the buffer into a ctypes array of the desired type. This region does not need to be unmapped, but will become invalid if the buffer is resized.

Note that although a pointer type is required, an array is mapped. For example:

get_region(0, ctypes.sizeof(c_int) * 20, ctypes.POINTER(c_int * 20))

will map bytes 0 to 80 of the buffer to an array of 20 ints.

Changes to the array may not be recognised until the region’s AbstractBufferRegion.invalidate() method is called.

Parameters:	start (int) – Offset into the buffer to map from, in bytes size (int) – Size of the buffer region to map, in bytes ptr_type (ctypes pointer type) – Pointer type describing the array format to create
Return type:	`AbstractBufferRegion`

map(invalidate=False)¶

Map the entire buffer into system memory.

The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.

Parameters:	invalidate (bool) – If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.
Return type:	`POINTER(ctypes.c_ubyte)`
Returns:	Pointer to the mapped block in memory

resize(size)¶

Resize the buffer to a new size.

Parameters:	size (int) – New size of the buffer, in bytes

set_data(data)¶

Set the entire contents of the buffer.

Parameters:	data (sequence of int or ctypes pointer) – The byte array to set.

set_data_region(data, start, length)¶

Set part of the buffer contents.

Parameters:	data (sequence of int or ctypes pointer) – The byte array of data to set start (int) – Offset to start replacing data length (int) – Length of region to replace

unbind()¶: Reset the buffer’s OpenGL target.

unmap()¶: Unmap a previously mapped memory block.

class VertexArrayRegion(array)¶

A mapped region of a vertex array.

The invalidate() method is a no-op but is provided in order to present a consistent interface with VertexBufferObjectRegion().

class VertexBufferObject(size, target, usage)¶

Lightweight representation of an OpenGL VBO.

The data in the buffer is not replicated in any system memory (unless it is done so by the video driver). While this can improve memory usage and possibly performance, updates to the buffer are relatively slow.

This class does not implement AbstractMappable, and so has no get_region() method. See MappableVertexBufferObject for a VBO class that does implement get_region().

bind()¶: Bind this buffer to its OpenGL target.

delete()¶: Delete this buffer, reducing system resource usage.

map(invalidate=False)¶

Map the entire buffer into system memory.

The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.

Parameters:	invalidate (bool) – If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.
Return type:	`POINTER(ctypes.c_ubyte)`
Returns:	Pointer to the mapped block in memory

resize(size)¶

Resize the buffer to a new size.

Parameters:	size (int) – New size of the buffer, in bytes

set_data(data)¶

Set the entire contents of the buffer.

Parameters:	data (sequence of int or ctypes pointer) – The byte array to set.

set_data_region(data, start, length)¶

Set part of the buffer contents.

Parameters:	data (sequence of int or ctypes pointer) – The byte array of data to set start (int) – Offset to start replacing data length (int) – Length of region to replace

unbind()¶: Reset the buffer’s OpenGL target.

unmap()¶: Unmap a previously mapped memory block.

class VertexBufferObjectRegion(buffer, start, end, array)¶

A mapped region of a VBO.

invalidate()¶

Mark this region as changed.

The buffer may not be updated with the latest contents of the array until this method is called. (However, it may not be updated until the next time the buffer is used, for efficiency).

create_buffer(size, target=34962, usage=35048, vbo=True)¶

Create a buffer of vertex data.

Parameters:	size (int) – Size of the buffer, in bytes target (int) – OpenGL target buffer usage (int) – OpenGL usage constant vbo (bool) – True if a VertexBufferObject should be created if the driver supports it; otherwise only a VertexArray is created.
Return type:	AbstractBuffer

create_mappable_buffer(size, target=34962, usage=35048, vbo=True)¶

Create a mappable buffer of vertex data.

Parameters:	size (int) – Size of the buffer, in bytes target (int) – OpenGL target buffer usage (int) – OpenGL usage constant vbo (bool) – True if a `VertexBufferObject` should be created if the driver supports it; otherwise only a `VertexArray` is created.
Return type:	`AbstractBuffer` with `AbstractMappable`