mob_utils

Batched views over collections of Mobs.

Algan packs many like Mobs into a single tensor batch – every glyph of a Text, every sphere of a point cloud – so that one Mob, one Scene actor and one render primitive cover all of them.

There are two ways to build such a pack. A class that can construct its geometry for many objects at once offers a from_batches constructor (from_batches(), from_batches()), which never creates the per-object Mobs at all; pack_animatable_rows does the timeline bookkeeping those constructors share. batch_mobs is the generic fallback: it packs Mobs that already exist, so it saves render-time cost but not construction cost.

BatchedMobViewSequence presents the result as an ordinary indexable sequence: text.character_mobs[3] returns a lazily-constructed view onto row 3 of the batch, which behaves like a Mob but owns no storage of its own. A view shares its source’s id, and therefore its timeline rows and its lifespan – so members of a pack cannot spawn or despawn independently, and stagger their entrances through opacity instead (this is what Tex.write() does).

Classes

BatchedMobViewSequence

Sequence of lazy views into a mob's batch dimension.

Functions

batch_mobs(mobs, parent_batch_sizes=None, add_to_scene=True)[source]

Pack existing Mobs into one Mob holding all of their rows.

The generic counterpart to a class’s own from_batches: it works for any Mob class, but the per-object Mobs have to exist first, so it saves render-time cost and Scene-actor count rather than construction cost.

Parameters:

  • mobs – The Mobs to pack, in any nested iterable. They must all belong to one Scene.

  • parent_batch_sizes – How many of mobs belong to each row of the pack’s parent, used when recursing into components and children. Defaults to None, which builds a root pack whose parent_batch_sizes instead carries the member boundaries that indexing slices on.

  • add_to_scene – Whether the pack is registered as a Scene actor. Defaults to True.

Returns:

The packed Mob, or None when mobs is empty.

Return type:

Mob or None

pack_animatable_rows(mob, count, overrides=None)[source]

Widen a Mob’s attribute rows to one per logical object, and declare the batch.

A packed Mob stands for count logical objects held in one tensor batch: every animatable attribute carries one row per object instead of a single shared row, and parent_batch_sizes records the boundaries that __getitem__() slices on. Every construction-time packer needs those same steps, so they live here instead of being copied into each one. Use pack_member_rows() for a component whose members own several rows each, such as a surface’s vertex grid.

The writes go through _setattr_and_rebatch_without_record(), which re-allocates the Mob’s timeline rows and leaves any recorded history behind on the old ones, so this is only valid on a Mob whose history is fresh – which at construction time it always is.

Parameters:

  • mob – The Mob to pack. Modified in place.

  • count – Number of logical objects the batch holds.

  • overrides – Values to write instead of the widened current ones, as {attr_name: tensor}; each must already carry count rows. Defaults to None, which widens every attribute.

Returns:

The packed Mob, so calls can be chained.

Return type:

Mob

pack_member_rows(mob, count, rows_per_member, overrides=None)[source]

Pack a component whose every member owns rows_per_member rows.

The counterpart to pack_animatable_rows() for the level below a pack: a surface’s vertex grid, or a circuit’s texture grid, where one logical object is a block of rows rather than a single row. Attributes already holding one member’s worth of rows are repeated per member; single shared rows are widened across the whole batch.

Parameters:

  • mob – The component Mob to pack. Modified in place.

  • count – Number of logical objects the parent batch holds.

  • rows_per_member – Rows this component owns for each of those objects.

  • overrides – Values to write instead of the widened current ones, as {attr_name: tensor}; each must already carry count * rows_per_member rows. Defaults to None.

Returns:

The packed component, so calls can be chained.

Return type:

Mob