ForestCells

from acron.proctree import ForestCells

class ForestCells

Bases:

Bases: TypedReferenceCount

The CPU side of an instanced forest: trees binned into square cells, each cell culled against the view frustum, each tree given a level of detail by its distance (with hysteresis) and faded into a new level over time, and each changed cell’s instance table rebuilt.

A tree is twelve floats – three RGBA texels of the table the vertex shader reads by gl_InstanceID: (x, y, z, scale), (cos yaw, sin yaw, random, jitter), (tint rgb, season) – plus a group (species: its four LOD distances, metres) and a prototype. `update()` writes each tree into the run of its (lod, group, prototype) in its cell’s table; during a fade a tree sits in two runs, the old level’s and the new one’s, with the jitter float replaced by a fade code the shader turns into a progress (0: steady, s + 1: fading in since time s, -(s + 1): fading out). Time is the frame values’ clock (seconds, wrapping at 3600). A cell that comes into view snaps to its levels (no fade for what was not seen). Level 4 is “not drawn” (beyond the last distance).

Only cells whose table changed are reported (`get_changed()`), so a still camera costs a distance test per visible tree and no upload.

`plant()` and `update()` run without the GIL; every method that reads or changes the trees and cells takes the forest’s lock, so another thread may plant or query meanwhile (it waits for the update to finish).

Inheritance diagram

digraph inheritance0da68673dd { bgcolor=transparent; rankdir=BT; size="8.0, 12.0"; "DTOOL_SUPER_BASE" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style=""]; "ForestCells" [URL="acron.proctree.ForestCells.html#acron.proctree.ForestCells",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedReferenceCount" -> "ForestCells" [arrowsize=0.75,style=""]; "ReferenceCount" [URL="acron.core.ReferenceCount.html#acron.core.ReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "ReferenceCount" [arrowsize=0.75,style=""]; "TypedObject" [URL="acron.core.TypedObject.html#acron.core.TypedObject",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "TypedObject" [arrowsize=0.75,style=""]; "TypedReferenceCount" [URL="acron.core.TypedReferenceCount.html#acron.core.TypedReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedObject" -> "TypedReferenceCount" [arrowsize=0.75,style=""]; "ReferenceCount" -> "TypedReferenceCount" [arrowsize=0.75,style=""]; }

__init__()

add_instances()

Adds n trees: `table` n x 12 floats, `groups` and `protos` n ints. Returns the index of the first.

clear()

static frustum_planes()

The six planes (a, b, c, d; inside >= 0) of a world-to-clip matrix in Acron’s row-vector convention (clip = p * M; GL depth -1..1).

get_cell_max()

get_cell_min()

get_cell_num_instances()

get_cell_num_runs()

get_cell_rows()

get_cell_run()

(lod, group, prototype, first row) of a run.

get_cell_run_count()

get_cell_size()

get_cell_table()

get_cell_x()

get_cell_y()

get_changed()

static get_class_type()

get_cull_pad()

get_fade_time()

get_group_distances()

get_hysteresis()

get_instance_lod()

The level a tree is fading into (or at); 4 not drawn.

get_instance_row()

The twelve floats of tree i (with its LOD jitter, as planted).

get_keep_radius()

get_lod_counts()

get_max_tree_height()

get_metres_per_unit()

get_num_cells()

get_num_changed()

get_num_fading()

get_num_instances()

static hash_positions()

Eight numbers in [0, 1) per position (n x 3 floats, quantised to 1 cm), splitmix64 of the position’s hash and the seed: what plant() draws each tree’s defaults from.

is_cell_visible()

plant()

Plants n trees of a group at `positions` (n x 3). Each optional array may be empty (a default from the position’s hash), one value for all, or one per tree: `heights` (metres; else `scales`, else 0.9-1.1), `yaws` (radians), `tints` (rgb), `protos` (else picked from the group’s `proto_heights`). Returns the first tree’s index.

set_cull_pad()

set_fade_time()

set_group_distances()

The four LOD far edges (metres) of a group (species); trees of a group without distances are never drawn.

set_hysteresis()

set_keep_radius()

set_metres_per_unit()

update()

Culls the cells against `planes` (n x 4 floats, a x + b y + c z + d >= 0 inside, in the forest’s space; empty: nothing culled; cells nearer than the keep radius are kept: they may cast shadows into view), updates the levels and fades of the trees in view, and rebuilds the tables that changed. Returns how many cells changed.

write_cell_texture()

Writes a cell’s instance table into `texture` (RGBA32F, ROW x 3 texels wide, nearest filtered), setting it up when its size changes.