pyglet.graphics.instance

VertexInstance provides an object handle for one independently managed instance. For array-oriented workloads, InstanceCollection manages the entire contiguous instance range without allocating a Python object for every item. See Instanced Rendering for selection guidance and examples.

class InstanceCollection(
bucket_ref: ReferenceType[InstanceBucket],
capacity: int,
count: int,
) → None

Manage contiguous instance data without per-instance Python objects.

Create collections with vertex_list.create_instance_collection.

Create an instance collection.

Parameters:
  • bucket_ref (ReferenceType[InstanceBucket]) – Weak reference to the instance bucket that owns the collection.

  • capacity (int) – Number of instance slots reserved in the stream.

  • count (int) – Number of active instances submitted by draw calls.

delete() → None

Release the collection’s reserved instance storage.

Return type:

None

get(
name: str,
start: int = 0,
count: int | None = None,
) → Any

Return one attribute over a contiguous active range.

Parameters:
  • name (str) – Instanced attribute name.

  • start (int) – First active instance to read.

  • count (int | None) – Number of instances to read. Defaults to all active instances from start onward.

Return type:

Any

insert(
index: int,
count: int = 1,
**attributes: Any,
) → None

Insert instance slots, shifting following data to the right.

This is convenient for occasional structural edits, but shifting large ranges is more expensive than replacing attributes with set().

Parameters:
  • index (int) – Active instance index at which to insert.

  • count (int) – Number of slots to insert.

  • **attributes (Any) – Initial data for the inserted slots.

Return type:

None

remove(start: int, count: int = 1) → None

Remove active slots while retaining the collection’s capacity.

Following instance data is shifted left to keep the active range contiguous.

Parameters:
  • start (int) – First active instance to remove.

  • count (int) – Number of instances to remove.

Return type:

None

reserve(capacity: int) → None

Reserve storage without changing the active instance count.

Existing data and the current draw count are preserved. Requests no larger than the current capacity do nothing.

Parameters:

capacity (int) – Minimum number of instance slots to reserve.

Return type:

None

set(
start: int = 0,
count: int | None = None,
**attributes: Any,
) → None

Update one or more attributes over a contiguous active range.

Attribute values are flattened sequences sized for count rows. Attributes not supplied are left unchanged.

Parameters:
  • start (int) – First active instance to update.

  • count (int | None) – Number of instances to update. Defaults to all active instances from start onward.

  • **attributes (Any) – Instanced attribute names and flattened data sequences.

Return type:

None

set_count(count: int) → None

Set the number of drawn instances while retaining capacity.

Growing beyond the current capacity automatically reserves enough storage. Newly activated slots are not initialized.

Parameters:

count (int) – New active instance count.

Return type:

None

property capacity: int

Number of reserved instance slots, including inactive slots.

property count: int

Number of active instances submitted by instanced draw calls.

class VertexInstance(
bucket_ref: ReferenceType[InstanceBucket],
slot: int = -1,
) → None

Base class for VertexInstance instances.

set(**attrs: Any) → None

Partial row update (by attribute name).

Return type:

None