SLVoxelGrid.sleela
lib/spatial/SLVoxelGrid.sleela · 208 line(s) · sleela
<< lib/spatial/SLVoxelGrid.sleela
SLeeLa Standard Library Definition.
Definition: A dense 3D grid of int cells stored in a single flat, contiguous
native array indexed by i = x + y*width + z*width*height (row-major, x fastest).
This is the "integrated" alternative to a nested int array of arrays of
arrays: one allocation, cache-linear scans, and no per-axis pointer chasing.
Cells carry a caller-chosen empty sentinel (default 0) so a scan can skip
unset space. Suited to dense volumes where most cells are addressed. >>
#sleela 2.5
material;
< Unified SLeeLa standard-library front-end object. >
< Family: spatial. Native VM/OS work crosses an explicit bridge. >
class SLVoxelGrid {
<< ---- Descriptive metadata (version 1.11 nested-friendly accessors) ----
Eleven catalogued attributes with getter/setter pairs, so a GUI, loader,
or catalog can read and (where appropriate) override this record.
Values are faithful to the subject real origin where publicly known. >>
String metaVersion = "1.0.0";
int metaId = 1601;
String metaAuthor = "Max Rupplin vs. Dr. Mrs. Elisabeth Harkins";
String metaDate = "2026-11-04";
String metaCopyright = "SLeeLa project";
String metaTrademark = "none";
String metaCorporation = "none";
< metaOrigin: National | <nation> | International | Galactic >
String metaOrigin = "International";
String metaBirthDate = "2026-11-04";
< metaScienceRating: maturity/robustness on a 1..10 scale >
int metaScienceRating = 8;
< metaNationalSchedule: a real, citable instrument or "none" >
String metaNationalSchedule = "none";
String getMetaVersion() { return metaVersion; }
void setMetaVersion(String v) { metaVersion = v; }
int getMetaId() { return metaId; }
void setMetaId(int v) { metaId = v; }
String getAuthor() { return metaAuthor; }
void setAuthor(String v) { metaAuthor = v; }
String getDate() { return metaDate; }
void setDate(String v) { metaDate = v; }
String getCopyright() { return metaCopyright; }
void setCopyright(String v) { metaCopyright = v; }
String getTrademark() { return metaTrademark; }
void setTrademark(String v) { metaTrademark = v; }
String getCorporation() { return metaCorporation; }
void setCorporation(String v) { metaCorporation = v; }
String getOrigin() { return metaOrigin; }
void setOrigin(String v) { metaOrigin = v; }
String getBirthDate() { return metaBirthDate; }
void setBirthDate(String v) { metaBirthDate = v; }
int getScienceRating() { return metaScienceRating; }
void setScienceRating(int v) { metaScienceRating = v; }
String getNationalSchedule() { return metaNationalSchedule; }
void setNationalSchedule(String v) { metaNationalSchedule = v; }
<< Dimensions and backing storage. cells is a single flat int array of
width*height*depth entries; every entry starts at the empty sentinel. >>
int width = 0;
int height = 0;
int depth = 0;
int empty = 0;
int[] cells = new int[0];
<< Allocate a width*height*depth grid, every cell set to emptyValue. Any
negative dimension is clamped to 0, which yields an empty grid. Call once
after new SLVoxelGrid(), or again to resize (contents are not preserved). >>
void allocate(int w, int h, int d, int emptyValue) {
int ww = w;
int hh = h;
int dd = d;
if (ww < 0) { ww = 0; }
if (hh < 0) { hh = 0; }
if (dd < 0) { dd = 0; }
width = ww;
height = hh;
depth = dd;
empty = emptyValue;
int total = ww * hh * dd;
cells = new int[total];
int i = 0;
while (i < total) {
arraySet(cells, i, emptyValue);
i = i + 1;
}
}
int getWidth() { return width; }
int getHeight() { return height; }
int getDepth() { return depth; }
int getEmptyValue() { return empty; }
< Total number of cells (width*height*depth). >
int size() { return width * height * depth; }
< True when a coordinate is inside the grid. >
boolean inBounds(int x, int y, int z) {
if (x < 0 || y < 0 || z < 0) { return false; }
return x < width && y < height && z < depth;
}
<< Flat row-major index of (x,y,z): x + y*width + z*width*height, with x the
fastest-varying axis for cache-linear iteration. Returns -1 out of bounds. >>
int indexOf(int x, int y, int z) {
if (!inBounds(x, y, z)) { return -1; }
return x + y * width + z * width * height;
}
<< Cell value at (x,y,z); returns the empty sentinel for an out-of-range
coordinate rather than trapping. >>
int get(int x, int y, int z) {
int i = indexOf(x, y, z);
if (i < 0) { return empty; }
return arrayGet(cells, i);
}
< Write a cell; returns false when the coordinate is out of range. >
boolean set(int x, int y, int z, int value) {
int i = indexOf(x, y, z);
if (i < 0) { return false; }
arraySet(cells, i, value);
return true;
}
< Read by flat index directly (0..size()-1); empty sentinel when out of range. >
int getFlat(int index) {
if (index < 0 || index >= width * height * depth) { return empty; }
return arrayGet(cells, index);
}
< Write by flat index directly; returns false when out of range. >
boolean setFlat(int index, int value) {
if (index < 0 || index >= width * height * depth) { return false; }
arraySet(cells, index, value);
return true;
}
< True when the cell at (x,y,z) holds the empty sentinel. >
boolean isEmpty(int x, int y, int z) {
return get(x, y, z) == empty;
}
< Set every cell back to the empty sentinel. >
void clear() {
int total = width * height * depth;
int i = 0;
while (i < total) {
arraySet(cells, i, empty);
i = i + 1;
}
}
< Set every cell to value. >
void fill(int value) {
int total = width * height * depth;
int i = 0;
while (i < total) {
arraySet(cells, i, value);
i = i + 1;
}
}
<< Count cells not equal to the empty sentinel. A full linear walk over the
contiguous backing array: the cache-friendly scan this layout exists for. >>
int occupancy() {
int total = width * height * depth;
int count = 0;
int i = 0;
while (i < total) {
if (arrayGet(cells, i) != empty) { count = count + 1; }
i = i + 1;
}
return count;
}
<< Flat index of the first non-empty cell at or after startFlat, or -1 when
none remain. Decode a returned index with xOf/yOf/zOf. Lets a caller walk
only the occupied cells of a dense volume without nested loops. >>
int nextOccupied(int startFlat) {
int total = width * height * depth;
int i = startFlat;
if (i < 0) { i = 0; }
while (i < total) {
if (arrayGet(cells, i) != empty) { return i; }
i = i + 1;
}
return -1;
}
< X coordinate of a flat index. >
int xOf(int index) {
if (width <= 0) { return -1; }
return index % width;
}
< Y coordinate of a flat index. >
int yOf(int index) {
if (width <= 0 || height <= 0) { return -1; }
return (index / width) % height;
}
< Z coordinate of a flat index. >
int zOf(int index) {
int plane = width * height;
if (plane <= 0) { return -1; }
return index / plane;
}
}