pyglet.graphics.vertexbuffer

Shared GPU buffer abstractions.

AbstractBuffer models a GPU byte buffer. It intentionally has no knowledge of ctypes element formats or shader attribute data types.

Typed host-side data is provided by BufferDataStore implementations. The default store is CTypeDataStore, but other stores can be created later such as JS for WebGL or even Numpy.

class AbstractBuffer

A backend GPU buffer represented as bytes.

__init__(size: int) → None

abstractmethod bind() → None

Bind this buffer for updates/reads.

Return type:: None

abstractmethod delete() → None

Free backend resources used by this buffer.

Return type:: None

abstractmethod get_bytes() → bytes

Read the entire buffer contents as bytes.

Return type:: bytes

abstractmethod get_bytes_region(offset: int, length: int) → bytes

Read a byte-range from the buffer.

Return type:: bytes

get_data() → bytes

Compatibility helper for callers that expect get_data.

Return type:: bytes

get_data_region(start: int, length: int) → bytes

Compatibility helper for callers that expect get_data_region.

Return type:: bytes

abstractmethod resize(size: int) → None

Resize the buffer.

Return type:: None

abstractmethod set_bytes(data: bytes | bytearray | memoryview) → None

Replace the entire buffer contents from bytes.

Return type:: None

abstractmethod set_bytes_region( offset: int, data: bytes | bytearray | memoryview, ) → None

Write bytes into a sub-range of the buffer.

Return type:: None

set_data( data: Sequence[int] | _Pointer | bytes | bytearray | memoryview, ) → None

Compatibility helper for callers that expect set_data.

Return type:: None

set_data_ptr(offset: int, length: int, ptr: _Pointer) → None

Compatibility helper for callers that pass a ctypes pointer.

Return type:: None

set_data_region( data: Sequence[int] | _Pointer | bytes | bytearray | memoryview, start: int, length: int, ) → None

Compatibility helper for callers that expect set_data_region.

Return type:: None

abstractmethod unbind() → None

Unbind this buffer.

Return type:: None

size: int

class AttributeBufferObject: A backed buffer used for shader attributes.

class BackedBufferObject

A GPU buffer that keeps data on the host.

__init__( size: int, store: BufferDataStore, ) → None

abstractmethod commit() → None

Commits all saved changes to the underlying GPU buffer before drawing.

Allows submitting multiple changes at once, rather than having to call glBufferSubData for every change.

Return type:: None

copy_region(dst: int, src: int, count: int) → None

Return type:: None

get_bytes() → bytes

Read the entire buffer contents as bytes.

Return type:: bytes

get_bytes_region(offset: int, length: int) → bytes

Read a byte-range from the buffer.

Return type:: bytes

get_region(start: int, count: int) → Any

Return type:: Any

invalidate() → None

Mark the entire store as dirty.

Return type:: None

invalidate_region(start: int, count: int) → None

Mark a typed region as dirty.

Return type:: None

resize_store(size: int) → None

Return type:: None

set_bytes(data: bytes | bytearray | memoryview) → None

Replace the entire buffer contents from bytes.

Return type:: None

set_bytes_region( offset: int, data: bytes | bytearray | memoryview, ) → None

Write bytes into a sub-range of the buffer.

Return type:: None

set_data( data: Sequence[float | int] | Array, ) → None

Compatibility helper for callers that expect set_data.

Return type:: None

set_data_ptr( offset: int, length: int, ptr: _Pointer, ) → None

Compatibility helper for callers that pass a ctypes pointer.

Return type:: None

set_data_region( data: Sequence[float | int] | Array, start: int, length: int, ) → None

Compatibility helper for callers that expect set_data_region.

Return type:: None

set_region( start: int, count: int, data: Sequence[float | int], ) → None

Return type:: None

property data: Any

property data_ptr: int | None

element_count: int

property element_size: int

store: BufferDataStore

stride: int

class BufferBindingSlice

BufferBindingSlice(offset: ‘int’, size: ‘int’)

__init__(offset: int, size: int) → None

offset: int

size: int

class BufferDataStore

Host-side data store used by BackedBufferObject.

abstractmethod copy_region(dst: int, src: int, count: int) → None

Copy a typed region inside the store.

Return type:: None

abstractmethod get_bytes(offset: int = 0, length: int | None = None) → bytes

Get raw bytes from the store.

Return type:: bytes

abstractmethod get_region(start: int, count: int) → Any

Return a typed region view.

Return type:: Any

abstractmethod resize(size: int) → None

Resize the store.

Return type:: None

abstractmethod set_bytes(offset: int, data: bytes | bytearray | memoryview) → None

Write raw bytes into the store.

Return type:: None

abstractmethod set_region( start: int, count: int, data: Sequence[float | int], ) → None

Write typed region data.

Return type:: None

abstract property data: Any: Store-specific data object.

abstract property data_ptr: int | None: Optional integer pointer/address to the store memory.

element_count: int

abstract property element_size: int: Size in bytes of one store element.

size: int

stride: int

class BufferRange

BufferRange(offset: ‘int’, size: ‘int’, in_use: ‘bool’ = False, frame_use_count: ‘int’ = 0)

__init__( offset: int, size: int, in_use: bool = False, frame_use_count: int = 0, ) → None

frame_use_count: int = 0

in_use: bool = False

offset: int

size: int

class CTypeDataStore

ctypes-based BufferDataStore.

This is the default host-side data store and keeps data in a ctypes array.

__init__( size: int, data_type: Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd'], stride: int, element_count: int, data_ptr: int | None = None, ) → None

Create a ctypes-backed typed data store.

Parameters:

size (int) – Total byte size for the store.
data_type (Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd']) – Struct-format data type code (for example "f" or "I") used to determine the underlying ctypes type and element size.
stride (int) – Byte stride for one logical element in this buffer layout.
element_count (int) – Number of scalar values per logical element.
data_ptr (int | None) – Optional pointer to externally owned memory. When provided, this store binds to that memory instead of allocating its own ctypes array.

Note

The _owns_memory flag indicates whether this store allocated its own backing array (True) or is bound to external memory (False). This is used to protect resize: externally backed stores cannot reallocate memory and must be rebound with rebind_external.

copy_region(dst: int, src: int, count: int) → None

Copy a typed region inside the store.

Return type:: None

get_bytes(offset: int = 0, length: int | None = None) → bytes

Get raw bytes from the store.

Return type:: bytes

get_region(start: int, count: int) → Array

Return a typed region view.

Return type:: Array[Any]

rebind_external(size: int, data_ptr: int) → None

Rebind this store to a new externally-owned memory region.

Return type:: None

resize(size: int) → None

Resize the store.

Return type:: None

set_bytes(offset: int, data: bytes | bytearray | memoryview) → None

Write raw bytes into the store.

Return type:: None

set_region( start: int, count: int, data: Sequence[float | int], ) → None

Write typed region data.

Return type:: None

property data: Array: Store-specific data object.

property data_ptr: int: Optional integer pointer/address to the store memory.

data_type: Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd']

property element_size: int: Size in bytes of one store element.

class DrawIndirectBuffer: Backend-agnostic draw indirect buffer.

class IndexedBindingBuffer

Backend-agnostic role for buffers that support indexed binding points.

abstractmethod bind_base(index: int) → None

Bind this buffer object to an indexed binding point.

Return type:: None

abstractmethod bind_range(index: int, offset: int, size: int) → None

Bind a byte range of this buffer object to an indexed binding point.

Return type:: None

class IndexedBufferObject: A backed buffer used for indices.

class MappedBufferObject

A GPU buffer that supports map/unmap and range mapping.

abstractmethod map(bits: int = 0) → Any

Map the entire buffer.

Return type:: Any

abstractmethod map_range( start: int, size: int, ptr_type: type[_Pointer], bits: int = 0, ) → Any

Map a range of the buffer.

Return type:: Any

abstractmethod unmap() → None

Unmap a previously mapped buffer.

Return type:: None

class PersistentBufferObject

A persistently mapped GPU buffer.

Available in OpenGL 4.3+ contexts. Persistently mapped buffers are mapped one time on creation, and can be updated at any time without the need to map or unmap.

class PixelBuffer: Backend-agnostic pixel transfer buffer.

class PixelPackBuffer: Backend-agnostic pixel pack buffer.

class PixelUnpackBuffer: Backend-agnostic pixel unpack buffer.

class RingBuffer

Generic ring allocator.

Range lifetime is tracked by owners such as FrameResourceManager by setting BufferRange.in_use. This allocator only selects writable ranges.

__init__( *, range_size: int, alignment: int = 1, copies_per_resource: int = 3, strict: bool = False, start_offset: int = 0, ) → None

acquire_writable_slice() → tuple[BufferBindingSlice, BufferRange]

Return type:: tuple[BufferBindingSlice, BufferRange]

acquire_writable_slice_from_ranges( ranges: list[BufferRange], next_range_index: int, ) → tuple[BufferBindingSlice, BufferRange, int]

Return type:: tuple[BufferBindingSlice, BufferRange, int]

delete() → None

Return type:: None

reserve_resource_range( copies_per_resource: int | None = None, ) → list[BufferRange]

Return type:: list[BufferRange]

alignment: int

copies_per_resource: int

property planned_size: int

range_size: int

range_stride: int

strict: bool

class ShaderStorageBuffer: Backend-agnostic shader storage buffer.

class TextureBuffer: Backend-agnostic texture buffer.

class TransformFeedbackBuffer

Backend-agnostic transform feedback buffer.

__init__( size: int, *, data_type: Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd'] = 'b', ) → None

Create a transform feedback buffer view.

Parameters:

size (int) – The buffer size in bytes.
data_type (Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd']) – Preferred format used by helper method get_data(), defaults to "b" for bytes.

get_data() → Array

Read transform feedback data as the initialized ctypes array.

Return type:: Array[Any]

class UniformBufferObject

Backend-agnostic Uniform Buffer Object wrapper.

__init__( context: Any, view_class: type[Structure], buffer_size: int, binding: int, *, alignment: int = 1, copies_per_resource: int = 3, strict: bool = False, ) → None

bind_slice( binding: BufferBindingSlice, *, binding_index: int | None = None, ) → None

Return type:: None

delete() → None

Return type:: None

get_data_structure() → Structure

Return type:: Structure

read() → bytes

Return type:: bytes

upload_to_available_binding( resource_data: Structure, ) → BufferBindingSlice

Return type:: BufferBindingSlice

upload_to_available_binding_from_ranges( resource_data: Structure, ranges: list[BufferRange], next_range_index: int, ) → tuple[BufferBindingSlice, BufferRange, int]

Return type:: tuple[BufferBindingSlice, BufferRange, int]

use_range(range_: BufferRange) → None

Return type:: None

binding: int

buffer: AbstractBuffer

property id: int

property size: int

property slice_size: int

property slice_stride: int

view: Structure

view_class: type[Structure]

class UniformBufferRegion

UBO region that uploads through a ring-buffered UniformBufferObject.

The region owns one CPU-side data structure and a set of GPU ranges.

General practice is to update the data structure, mark it dirty, and then commit when you are done updating for that frame.

Warning

Do not make the CPU-side data dirty after binding/committing during the same frame (for example, during the on_draw call), or GPU stalls may occur.

Added in version 3.0.

__init__( ubo: UniformBufferObject, *, copies_per_resource: int | None = None, ) → None

bind(*, binding_index: int | None = None) → None

Upload dirty data if needed, then bind the current GPU range.

Return type:: None

commit() → None

Upload dirty CPU-side data to the next writable GPU range.

Return type:: None

mark_dirty() → None

Mark the CPU-side data for upload on the next bind call.

Return type:: None

data

property dirty: bool: Whether the CPU-side data needs to be uploaded before drawing.

property ubo: UniformBufferObject: The underlying UniformBufferObject.