dymokomi/luce-kernel
Source of release 0.1.1
0.1.1 / src / lower / host.lucb
# The host's description of its API: what each member of its stub types stands for.
## What an API member stands for.
pub enum Role:
## A field holding a host column (`p.P`): reading it reads the column, writing it
## writes the column back when the run ends.
field
## An accessor `p.f32("mass")`: reads the column named by its literal argument.
getter
## A setter `p.set_f32("mass", value)`: writes the column named by its literal argument.
setter
## The element's number (`p.ptnum`).
element
## A uniform named by the binding (`k.time`, `p.numpt`).
uniform
## A uniform named by the call's literal argument, with its literal default
## (`k.f32("amount", 0.2)`): the node's spare parameters.
parameter
## A host builtin; the receiver is not passed.
builtin
## A method without arguments reading a column the host computes (`f.area()`).
computed
## An accessor reading the uniform named by the prefix and its literal argument
## (`k.detail_f32("height")`); not a spare parameter.
reader
## A method giving an API value (`k.input(1)`): its integer argument names the value
## and is passed first to that value's builtins.
handle
## One member of the API and what it stands for.
pub struct Binding:
## The struct the member belongs to (`Point`), or for a free function its module
## (`luce_geocore.code`).
pub let owner: str
## The field or method.
pub let member: str
pub let role: Role
## The column (`field`), the column name prefix (`getter`, `setter`: the column is the
## prefix and the literal), or the uniform (`uniform`).
pub let column: str
## Values per element in the column: 3 for a three-component `f32[4]`, whose lane 3
## reads 0 and is never written.
pub let components: usize
pub let builtin: Builtin?
## A column the input has: its name, kind and components, for the lowering to check reads
## against (an attribute signature).
pub struct InputColumn:
pub let name: str
pub let kind: Kind
pub let components: usize
## What a missing input column reads as, lane by lane, instead of 0 (`orient`: the
## identity quaternion).
pub struct MissingDefault:
pub let name: str
pub let values: f64[4]
## The host's API description. A zero value is empty; `destroy` gives back its storage.
pub struct Host:
var bindings: collections.List[Binding]
var input_columns: collections.List[InputColumn]
var known_columns: bool
var missing_zero: bool
var missing_defaults: collections.List[MissingDefault]
var libraries: collections.List[str]
var texts: collections.TextPool
## Field `member` of struct `owner` is component-wise column `column`.
pub func field(owner: str, member: str, column: str, components: usize) -> !:
try self.add(owner, member, .field, column, components, none)
## Method `member` of `owner` reads column `prefix` + its literal first argument.
pub func getter(owner: str, member: str, prefix: str, components: usize) -> !:
try self.add(owner, member, .getter, prefix, components, none)
## Method `member` of `owner` writes its second argument into column `prefix` + its
## literal first argument.
pub func setter(owner: str, member: str, prefix: str, components: usize) -> !:
try self.add(owner, member, .setter, prefix, components, none)
## Field `member` of `owner` is the element's number.
pub func element(owner: str, member: str) -> !:
try self.add(owner, member, .element, "", 1, none)
## Field `member` of `owner` is uniform `uniform`.
pub func uniform(owner: str, member: str, uniform: str) -> !:
try self.add(owner, member, .uniform, uniform, 1, none)
## Method `member` of `owner` is a parameter: a uniform named by its literal first
## argument, with its literal second argument (or the parameter's default) as default.
## A vector one has a uniform per lane up to `components` (`name[0]`, ...); lanes past
## them read 0 (a `vec3` returning `f32[4]` has 3).
pub func parameter(owner: str, member: str, components: usize = 32) -> !:
try self.add(owner, member, .parameter, "", components, none)
## Method `member` of struct `owner` (or function `member` of module `owner`) runs
## host builtin `builtin` over its arguments, vectors passed lane by lane.
pub func builtin(owner: str, member: str, builtin: Builtin) -> !:
try self.add(owner, member, .builtin, "", 1, builtin)
## Method `member` of `owner`, called without arguments, reads column `column`.
pub func computed(owner: str, member: str, column: str, components: usize) -> !:
try self.add(owner, member, .computed, column, components, none)
## Method `member` of `owner` reads uniform `prefix` + its literal first argument.
pub func reader(owner: str, member: str, prefix: str) -> !:
try self.add(owner, member, .reader, prefix, 1, none)
## The input has exactly the columns `column` declares (none, until it is called), and
## reading one it lacks gives 0 (VEX's rule) instead of a diagnostic; columns it has
## are still read in their stored kind.
pub func missing_reads_zero():
self.missing_zero = true
self.known_columns = true
## Whether missing columns read as 0.
pub func reads_missing_as_zero() -> bool:
return self.missing_zero
## A missing column `name` reads as `values` (one per component, the rest 0) instead
## of 0: a field whose neutral value is not zero, like a rotation's identity.
pub func missing_reads(name: str, values: f64[4]) -> !:
try self.missing_defaults.append(MissingDefault(name = try self.texts.keep_text(name.bytes), values = values))
## What missing column `name` reads as, when the host gave it a value.
pub func missing_value(name: str) -> f64[4]?:
for found in self.missing_defaults.view():
if found.name == name:
return found.values
return none
## Method `member` of `owner` gives an API value named by its integer argument.
pub func handle(owner: str, member: str) -> !:
try self.add(owner, member, .handle, "", 1, none)
## The input has column `name`. Once any is declared, a snippet may read only declared
## columns, each in its stored kind; writing an undeclared one creates it.
pub func column(name: str, kind: Kind, components: usize) -> !:
let kept = try self.texts.keep_text(name.bytes)
try self.input_columns.append(InputColumn(name = kept, kind = kind, components = components))
self.known_columns = true
## Functions of host stub module `module` (`luce_geocore.gsplat`) are helpers built on
## the API: a call lowers their Base bodies inline, as it does `lib`'s, unless a
## binding names the function.
pub func library(module: str) -> !:
try self.libraries.append(try self.texts.keep_text(module.bytes))
## Whether `module` is one of the host's helper modules.
pub func inlines(module: str) -> bool:
for known in self.libraries.view():
if known == module:
return true
return false
## Give back the storage.
pub func destroy():
self.bindings.destroy()
self.libraries.destroy()
self.input_columns.destroy()
self.missing_defaults.destroy()
self.texts.destroy()
self.known_columns = false
self.missing_zero = false
## The binding of `member` of `owner`.
pub func find(owner: str, member: str) -> Binding?:
for binding in self.bindings.view():
if binding.owner == owner and binding.member == member:
return binding
return none
## The input column `name`, when declared.
pub func input_column(name: str) -> InputColumn?:
for column in self.input_columns.view():
if column.name == name:
return column
return none
## Whether `owner` has any binding (its values are API values a snippet holds).
pub func binds(owner: str) -> bool:
for binding in self.bindings.view():
if binding.owner == owner:
return true
return false
func add(owner: str, member: str, role: Role, column: str, components: usize, builtin: Builtin?) -> !:
if self.find(owner, member) != none:
error(bad_host, "a member bound twice")
if components == 0 or components > 32:
error(bad_host, "a column has 1 to 32 components")
let binding = Binding(owner = try self.texts.keep_text(owner.bytes), member = try self.texts.keep_text(member.bytes), role = role, column = try self.texts.keep_text(column.bytes), components = components, builtin = builtin)
try self.bindings.append(binding)