pyglet.graphics.vertexdomain

Manage related vertex attributes within a single vertex domain.

A vertex “domain” consists of a set of attribute descriptions that together describe the layout of one or more vertex buffers which are used together to specify the vertices in a primitive. Additionally, the domain manages the buffers used to store the data and will resize them as necessary to accommodate new vertices.

Domains can optionally be indexed, in which case they also manage a buffer containing vertex indices. This buffer is grown separately and has no size relation to the attribute buffers.

Applications can create vertices (and optionally, indices) within a domain with the VertexDomain.create() method. This returns a VertexList representing the list of vertices created. The vertex attribute data within the group can be modified, and the changes will be made to the underlying buffers automatically.

The entire domain can be efficiently drawn in one step with the VertexDomain.draw() method, assuming all the vertices comprise primitives of the same OpenGL primitive mode.

class IndexStream

A container to manage an index buffer for a domain.

__init__(
ctx,
data_type: Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd'],
initial_elems: int,
)

Initialize the stream and create an allocator.

Parameters:

size – Initial allocator and buffer size.

bind_into(vao) → None

Record this stream into the VAO.

The VAO should be bound before this function is called.

Return type:

None

commit() → None

Binds buffers and commits all pending data to the graphics API.

Return type:

None

copy_region(dst: int, src: int, count: int) → None
Return type:

None

get_region(start: int, count: int) → Any
Return type:

Any

set_region(start: int, count: int, data) → None
Return type:

None

class IndexedVertexDomain

Management of a set of indexed vertex lists.

Construction of an indexed vertex domain is usually done with the create_domain() function.

__init__(
context: SurfaceContext,
initial_count: int,
attribute_meta: dict[str, Attribute],
index_type: Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd'] = 'I',
) → None
create(
group: Group,
count: int,
indices: Sequence[int] | None = None,
) → IndexedVertexList

Create an IndexedVertexList in this domain.

Parameters:

  • group (Group) – The Group the resulting vertex list will be drawn with.

  • count (int) – Number of vertices to create

  • indices (Sequence[int] | None) – The indices used for this vertex list.

Return type:

IndexedVertexList

draw(mode: int) → None

Draw all vertices in the domain.

All vertices in the domain are drawn at once. This is the most efficient way to render primitives.

Parameters:

mode (int) – OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.

Return type:

None

draw_subset(
mode: GeometryMode,
vertex_list: IndexedVertexList,
) → None

Draw a specific IndexedVertexList in the domain.

The vertex_list parameter specifies a IndexedVertexList to draw. Only primitives in that list will be drawn.

Parameters:
Return type:

None

get_group_bucket(
group: Group,
) → IndexedVertexGroupBucket

Get a drawable bucket to assign vertex list information to a specific group.

Return type:

IndexedVertexGroupBucket

safe_index_alloc(count: int) → int

Allocate indices, resizing the buffers if necessary.

Return type:

int

safe_index_realloc(start: int, count: int, new_count: int) → int

Reallocate indices, resizing the buffers if necessary.

Return type:

int

index_stream: IndexStream
class IndexedVertexGroupBucket

A grouping of indexed vertex lists belonging to a single group in a domain.

Vertex lists are still owned by the domain, but this allows states to be rendered together if possible.

add_vertex_list(
vl: IndexedVertexList,
) → None
Return type:

None

remove_vertex_list(
vl: IndexedVertexList,
) → None
Return type:

None

is_dirty: bool
class IndexedVertexList

A list of vertices within an IndexedVertexDomain that are indexed.

Use IndexedVertexDomain.create() to construct this list.

__init__(
domain: IndexedVertexDomain,
group: Group,
start: int,
count: int,
index_start: int,
index_count: int,
) → None
delete() → None

Delete this group.

Return type:

None

domain: IndexedVertexDomain
index_count: int
index_start: int
indexed: bool = True
property indices: list[int]

Array of index data.

class InstanceIndexedVertexList

A list of vertices within an IndexedVertexDomain that are indexed.

Use IndexedVertexDomain.create() to construct this list.

__init__(
domain: InstancedIndexedVertexDomain,
group: Group,
start: int,
count: int,
index_start: int,
index_count: int,
index_type: Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd'],
base_vertex: int,
instance_bucket: InstanceBucket,
) → None
create_instance(
**attributes: Any,
) → VertexInstance
Return type:

VertexInstance

dealloc_from_group(vertex_list)

Removes a vertex list from a specific state in this domain.

delete() → None

Delete this group.

Return type:

None

get_instance_by_index(
index: int,
) → VertexInstance | None

Get an instance by its current slot index.

Return type:

VertexInstance | None

get_instance_index(
instance: VertexInstance,
) → int | None

Get the current slot index for an instance.

Return type:

int | None

migrate(
domain: InstancedIndexedVertexDomain,
group: Group,
) → None

Move this group from its current domain and add to the specified one.

Attributes on domains must match. (In practice, used to change parent state of some vertices).

Parameters:
Return type:

None

move_instance_to_index(
instance: VertexInstance,
index: int,
) → None

Move one instance to a target slot index.

Other instances shift as needed to keep slots contiguous. This may be expensive when moving across many slots.

Return type:

None

move_to_back(
instances: Sequence[VertexInstance],
) → None

Move a subset of instances to the back in the given order.

Back means lower indices (drawn earlier). Unspecified instances remain after the moved prefix. This can be expensive for large lists.

Return type:

None

move_to_top(
instances: Sequence[VertexInstance],
) → None

Move a subset of instances to the top in the given order.

Top means higher indices (drawn later). Unspecified instances remain before the moved suffix. This can be expensive for large lists.

Return type:

None

set_attribute_data(name: str, data: Any) → None
Return type:

None

set_instance_order(
order: Sequence[VertexInstance],
) → None

Set the exact full order of all active instances.

This can be expensive for large lists.

Return type:

None

swap_instances(
first: VertexInstance,
second: VertexInstance,
) → None

Swap two instances in-place.

Useful when changing draw order without rebuilding all instance data. This can still be expensive if instance attributes are large.

Return type:

None

domain: InstancedIndexedVertexDomain
index_count: int
index_start: int
indexed: bool = True
instance_bucket: InstanceBucket
property instance_count: int

Number of active instances in this vertex list.

instanced: bool = True
supports_base_vertex: bool = False
class InstanceStream

Handles a stream of buffers to be used with the per-instance attributes.

class InstanceVertexList

A list of vertices within an InstancedVertexDomain that are not indexed.

__init__(
domain: VertexDomain,
group: Group,
start: int,
count: int,
bucket: InstanceBucket,
) → None
create_instance(
**attributes: Any,
) → VertexInstance
Return type:

VertexInstance

get_instance_by_index(
index: int,
) → VertexInstance | None

Get an instance by its current slot index.

Return type:

VertexInstance | None

get_instance_index(
instance: VertexInstance,
) → int | None

Get the current slot index for an instance.

Return type:

int | None

move_instance_to_index(
instance: VertexInstance,
index: int,
) → None

Move one instance to a target slot index.

Other instances shift as needed to keep slots contiguous. This may be expensive when moving across many slots.

Return type:

None

move_to_back(
instances: Sequence[VertexInstance],
) → None

Move a subset of instances to the back in the given order.

Back means lower indices (drawn earlier). Unspecified instances remain after the moved prefix. This can be expensive for large lists.

Return type:

None

move_to_top(
instances: Sequence[VertexInstance],
) → None

Move a subset of instances to the top in the given order.

Top means higher indices (drawn later). Unspecified instances remain before the moved suffix. This can be expensive for large lists.

Return type:

None

set_attribute_data(name: str, data: Any) → None
Return type:

None

set_instance_order(
order: Sequence[VertexInstance],
) → None

Set the exact full order of all active instances.

This can be expensive for large lists.

Return type:

None

swap_instances(
first: VertexInstance,
second: VertexInstance,
) → None

Swap two instances in-place.

Useful when changing draw order without rebuilding all instance data. This can still be expensive if instance attributes are large.

Return type:

None

domain: InstancedVertexDomain
property instance_count: int

Number of active instances in this vertex list.

instanced: bool = True
class InstancedIndexedVertexDomain
__init__(
context: SurfaceContext,
initial_count: int,
attribute_meta: dict[str, Attribute],
index_type: Literal['f', 'i', 'I', 'h', 'H', 'b', 'B', 'q', 'Q', '?', 'd'] = 'I',
) → None
alloc_to_group(vertex_list, group)

Assigns a vertex list to a specific state in this domain.

A state bucket does not allocate any vertices or allocates any GPU resources, it is simply to track the data required for drawing in a specific state.

Parameters:

  • vertex_list – The vertex list to allocate.

  • group – The group affecting the vertices.

Returns:

The new state bucket object.

bind_vao()

Binds the VAO as well as commit any pending buffer changes to the GPU.

create(
group: Group,
count: int,
indices: Sequence[int] | None,
) → InstanceIndexedVertexList

Create an IndexedVertexList in this domain.

Parameters:

  • group (Group) – The Group the resulting vertex list will be drawn with.

  • count (int) – Number of vertices to create

  • indices (Sequence[int] | None) – Indices used for this vertex list.

Return type:

InstanceIndexedVertexList

abstractmethod create_instance_domain(
size: int,
) → InstanceDomain
Return type:

InstanceDomain

class InstancedVertexDomain
__init__(
context: SurfaceContext,
initial_count: int,
attribute_meta: dict[str, Attribute],
) → None
alloc_to_group(vertex_list, group)

Assigns a vertex list to a specific state in this domain.

A state bucket does not allocate any vertices or allocates any GPU resources, it is simply to track the data required for drawing in a specific state.

Parameters:

  • vertex_list – The vertex list to allocate.

  • group – The group affecting the vertices.

Returns:

The new state bucket object.

bind_vao()

Binds the VAO as well as commit any pending buffer changes to the GPU.

create(
group: Group,
count: int,
indices: Sequence[int] | None = None,
) → VertexList

Create a VertexList in this domain.

Parameters:

  • group (Group) – The Group the resulting vertex list will be drawn with.

  • count (int) – Number of vertices to create.

  • indices (Sequence[int] | None) – Ignored for non indexed VertexDomains

Return type:

VertexList

abstractmethod create_instance_domain(
size: int,
) → InstanceDomain
Return type:

InstanceDomain

class Stream

A container that handles a set of buffers to be used with domains.

__init__(size: int) → None

Initialize the stream and create an allocator.

Parameters:

size (int) – Initial allocator and buffer size.

alloc(count: int) → int

Allocate a region of data, resizing the buffers if necessary.

Return type:

int

abstractmethod bind_into(vao) → None

Record this stream into the VAO.

The VAO should be bound before this function is called.

Return type:

None

commit() → None

Binds buffers and commits all pending data to the graphics API.

Return type:

None

dealloc(start: int, count: int) → None
Return type:

None

realloc(start: int, count: int, new_count: int) → int

Reallocate a region of data, resizing the buffers if necessary.

Return type:

int

resize(capacity: int) → None

Resize all buffers to the specified capacity.

Size is passed as capacity * stride.

Return type:

None

abstractmethod set_region(start: int, count: int, data) → None
Return type:

None

class VertexArrayBinding

A wrapper for a Vertex Array Object that binds streams.

VAO’s store which attribute layouts are used, as well as which buffer object each attribute pulls from.

In the case of instanced drawing, each instance needs its own VAO as their per-instance data are separate buffers.

__init__(
ctx: SurfaceContext,
streams: list[VertexStream | InstanceStream | IndexStream],
)
bind()
streams: list[VertexStream | InstanceStream | IndexStream]
class VertexArrayProtocol
__init__(*args, **kwargs)
bind()
unbind()
class VertexDomain

Management of a set of vertex lists.

Construction of a vertex domain is usually done with the create_domain() function.

__init__(
context: SurfaceContext,
initial_count: int,
attribute_meta: dict[str, Attribute],
) → None
alloc_to_group(
vertex_list,
group,
) → VertexGroupBucket

Assigns a vertex list to a specific state in this domain.

A state bucket does not allocate any vertices or allocates any GPU resources, it is simply to track the data required for drawing in a specific state.

Parameters:

  • vertex_list – The vertex list to allocate.

  • group – The group affecting the vertices.

Return type:

VertexGroupBucket

Returns:

The new state bucket object.

bind_vao() → None

Binds the VAO as well as commit any pending buffer changes to the GPU.

Return type:

None

create(
group: Group,
count: int,
indices: Sequence[int] | None = None,
) → VertexList

Create a VertexList in this domain.

Parameters:

  • group (Group) – The Group the resulting vertex list will be drawn with.

  • count (int) – Number of vertices to create.

  • indices (Sequence[int] | None) – Ignored for non indexed VertexDomains

Return type:

VertexList

dealloc_from_group(vertex_list)

Removes a vertex list from a specific state in this domain.

abstractmethod draw(mode: int) → None

Draw all vertices in the domain.

All vertices in the domain are drawn at once. This is the most efficient way to render primitives.

Parameters:

mode (int) – OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.

Return type:

None

abstractmethod draw_subset(
mode: GeometryMode,
vertex_list: VertexList,
) → None

Draw a specific VertexList in the domain.

The vertex_list parameter specifies a VertexList to draw. Only primitives in that list will be drawn.

Parameters:

  • mode (GeometryMode) – OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.

  • vertex_list (VertexList) – Vertex list to draw.

Return type:

None

get_drawable_bucket(
group: Group,
) → VertexGroupBucket | None

Get a bucket that exists and has vertices to draw (not empty).

Return type:

VertexGroupBucket | None

has_bucket(group: Group) → bool
Return type:

bool

safe_alloc(count: int) → int

Allocate vertices, resizing the buffers if necessary.

Return type:

int

safe_realloc(start: int, count: int, new_count: int) → int

Reallocate vertices, resizing the buffers if necessary.

Return type:

int

attrib_name_buffers: dict[str, VertexStream | InstanceStream]
attribute_meta: dict[str, Attribute]
property attribute_names
buffer_attributes: list[tuple[AttributeBufferObject, Attribute]]
property is_empty: bool

If the domain has no vertices.

per_instance: list[Attribute]
per_vertex: list[Attribute]
vertex_stream: VertexStream
class VertexGroupBucket

A grouping of vertex lists belonging to a single group in a domain.

Vertex lists are still owned by the domain, but this allows states to be rendered together if possible.

__init__() → None

Initialize an empty range collector.

add_vertex_list(
vl: VertexList,
) → None
Return type:

None

remove_vertex_list(
vl: VertexList,
) → None
Return type:

None

is_dirty: bool
class VertexList

A list of vertices within a VertexDomain.

Use VertexDomain.create() to construct this list.

__init__(
domain: VertexDomain,
group: Group,
start: int,
count: int,
) → None
delete() → None

Delete this group.

Return type:

None

draw(mode: GeometryMode) → None

Draw this vertex list in the given OpenGL mode.

Parameters:

mode (GeometryMode) – OpenGL drawing mode, e.g. GL_POINTS, GL_LINES, etc.

Return type:

None

migrate(
domain: VertexDomain,
group: Group,
) → None

Move this group from its current domain and add to the specified one.

Attributes on domains must match. (In practice, used to change parent state of some vertices).

Parameters:

  • domain (VertexDomain) – Domain to migrate this vertex list to.

  • group (Group) – The group this vertex list belongs to.

Return type:

None

resize(count: int, index_count: int | None = None) → None

Resize this group.

Parameters:

  • count (int) – New number of vertices in the list.

  • index_count (int | None) – Ignored for non indexed VertexDomains

Return type:

None

set_attribute_data(name: str, data: Any) → None
Return type:

None

update_group(group: Group) → None
Return type:

None

count: int
domain: VertexDomain
indexed: bool = False
initial_attribs: dict
instanced: bool = False
start: int
class VertexStream

A stream of buffers to be used with per-vertex attributes.

__init__(
ctx: SurfaceContext,
initial_size: int,
attrs: Sequence[Attribute],
*,
divisor: int = 0,
)

Initialize the stream and create an allocator.

Parameters:

size – Initial allocator and buffer size.

copy_data(
dst_slot: int,
dst_stream: VertexStream | InstanceStream,
src_slot: int,
count: int = 1,
attrs: Iterable[str] | None = None,
*,
strict: bool = False,
) → None
Return type:

None

get_attribute_region(name: str, start: int, count: int)
get_buffer(size, attribute)
get_graphics_attribute(
attribute: Attribute,
view: AttributeView,
) → GraphicsAttribute
Return type:

GraphicsAttribute

invalidate_attribute_region(name: str, start: int, count: int)
set_attribute_region(
name: str,
start: int,
count: int,
data: Any,
)
set_region(start: int, count: int, data_by_attr: dict[str, Any])
attrib_name_buffers: dict[str, AttributeBufferObject]
attribute_meta: Sequence[Attribute]