raisin::WorldCells

class · #include <rayrai/WorldCells.hpp>

Bounded cell residency planning, independent of rendering and physics. Call plan(), unload released cells, then load the proposed cells on the owning thread. Commit only successful operations. Multiple interests cover viewer cameras, sensor cameras and interacting bodies independently.

Constructors & destructor

WorldCells

WorldCells(
    WorldCellBounds bounds,
    double cellSize,
    size_t residentBudget,
    size_t loadBudget=2)

Divide bounds into square cells.

Parameters

Parameter	Description
bounds	World rectangle; the last row/column of cells is clipped to it.
cellSize	Cell edge length.
residentBudget	Maximum number of resident cells.
loadBudget	Maximum number of cells plan() proposes to load per call.

Exceptions

Exception	Description
std::invalid_argument	on non-finite or empty bounds, a non-positive cell size, a zero budget, or a grid too large for int32 keys.

Public member functions

cellBounds

WorldCellBounds cellBounds(WorldCellKey key) const

Returns World rectangle of key.

Exceptions

Exception	Description
std::out_of_range	outside the grid.

Parameters

Parameter	Description
key	Cell key.

resident

const std::vector<WorldCellKey> &resident() const

Returns Committed resident cells, sorted by WorldCellKey::operator<.

dimensions

glm::ivec2 dimensions() const

Returns Number of cells along x and y.

isResident

bool isResident(WorldCellKey key) const

Parameters

Parameter	Description
key	Cell key.

Returns True if key has been committed as loaded.

commitLoad

void commitLoad(WorldCellKey key)

Record a successful load. No-op if already resident; throws std::length_error when the resident budget is full.

Parameters

Parameter	Description
key	Loaded cell.

commitUnload

void commitUnload(WorldCellKey key)

Record an unload; ignores keys that are not resident.

Parameters

Parameter	Description
key	Unloaded cell.

plan

WorldCellPlan plan(std::span<const WorldInterest> interests) const

Propose loads and unloads for the given interests without changing state.

Cells kept only by a retain radius are released first when requested cells need their capacity.

Parameters

Parameter	Description
interests	Points that want cells resident.

Returns Loads and unloads to perform, then commit.

Exceptions

Exception	Description
std::invalid_argument	for a non-finite interest or retainRadius < loadRadius.
std::length_error	if one interest's load square spans more than one million cells.

Static member functions

distanceSquared static

static double distanceSquared(WorldCellBounds bounds, glm::dvec2 position)

Parameters

Parameter	Description
bounds	Rectangle.
position	Point.

Returns Squared distance from position to bounds (0 inside).