World drawing: drawing

cinnabar:world-draw/drawing@0.1.0

Owner and connection scoped resources. Every mutation is a callback transaction.

Grants: world_draw for mutations; entity_observe for observation, entity_highlight for attachment, render_through_walls for elevated depth and render_material for custom materials. capabilities reports granted bits.

Types

permissions

Independent authority bits; advertised support does not itself grant another capability.

flags permissions {
    world-draw,
    entity-observe,
    entity-highlight,
    render-through-walls,
    render-material,
    render-post,
}

handle

An opaque token scoped to one owner incarnation; never construct or reuse another owner’s token.

record handle {
    owner: u64,
    generation: u64,
    slot: u64,
}

error-code

A typed refusal; stale and in-use resources need lifecycle handling rather than blind retries.

enum error-code {
    denied,
    invalid,
    budget-exceeded,
    stale-handle,
    unsupported,
    in-use,
}

draw-error

A stable error category and a host diagnostic intended for humans.

record draw-error {
    code: error-code,
    detail: string,
}

Types: error-code.

vertex

Local-space position, linear colour, UV and custom material data for one source vertex.

record vertex {
    position: tuple<f32, f32, f32>,
    color: tuple<f32, f32, f32, f32>,
    uv: tuple<f32, f32>,
    data: tuple<f32, f32, f32, f32>,
}

mesh

Triangle vertices and indices; indices address this mesh’s own vertex list.

record mesh {
    vertices: list<vertex>,
    indices: list<u32>,
}

Types: vertex.

polyline

Ordered local vertices; closed connects the last vertex to the first without repeating it.

record polyline {
    vertices: list<vertex>,
    closed: bool,
}

Types: vertex.

geometry-spec

Chooses indexed triangles or a host-expanded polyline.

variant geometry-spec {
    triangles(mesh),
    line(polyline),
}

Types: mesh, polyline.

world-anchor

A double-precision origin in one dimension for local geometry coordinates.

record world-anchor {
    dimension: s32,
    origin: tuple<f64, f64, f64>,
}

block-anchor

An integer block origin in one dimension.

record block-anchor {
    dimension: s32,
    position: tuple<s32, s32, s32>,
}

entity-anchor

An authorized retained actor reference, optionally following its body rotation.

record entity-anchor {
    entity: handle,
    body-rotation: bool,
}

Types: handle.

anchor

Selects the coordinate frame; entity attachment and elevated depth need separate authority.

variant anchor {
    %world(world-anchor),
    block(block-anchor),
    camera,
    entity(entity-anchor),
}

Types: block-anchor, entity-anchor, world-anchor.

transform

Local translation, quaternion rotation and scale applied to the retained geometry.

record transform {
    translation: tuple<f32, f32, f32>,
    rotation: tuple<f32, f32, f32, f32>,
    scale: tuple<f32, f32, f32>,
}

depth

Depth-tested coverage or elevated coverage requiring through-wall authority.

enum depth {
    test,
    always,
}

blend

Premultiplied alpha composition or additive emission.

enum blend {
    premultiplied,
    additive,
}

width-mode

Interprets line width in world units or physical pixels.

enum width-mode {
    %world,
    pixels,
}

join

The host-expanded shape at a polyline corner.

enum join {
    bevel,
    miter,
    round,
}

cap

The host-expanded shape at each open polyline endpoint.

enum cap {
    butt,
    round,
}

instance

One retained geometry placement; geometry and material handles belong to the same owner.

record instance {
    geometry: handle,
    material: option<handle>,
    params: list<f32>,
    anchor: anchor,
    transform: transform,
    tint: tuple<f32, f32, f32, f32>,
    depth: depth,
    blend: blend,
    width: f32,
    width-mode: width-mode,
    join: join,
    cap: cap,
}

Types: anchor, blend, cap, depth, handle, join, transform, width-mode.

observed-entity

An authorized actor reference paired with its session runtime ID; release the reference when finished.

record observed-entity {
    entity: handle,
    runtime-id: u64,
}

Types: handle.

Functions

create-material

create-material: func(source: string) -> result<handle, draw-error>;

Custom procedural fragments use the render-material grant, without textures or depth output. Successful creation means source validation succeeded; native compilation may still fail.

Types: draw-error, handle.

capabilities

capabilities: func() -> permissions;

Reports this instance’s independently granted drawing permissions, including when drawing is denied.

Types: permissions.

observe-entities

observe-entities: func() -> result<list<observed-entity>, draw-error>;

Returns bounded host-selected actor references; retained references need explicit release.

Types: draw-error, observed-entity.

create-geometry

create-geometry: func(spec: geometry-spec) -> result<handle, draw-error>;

Allocates validated geometry owned by this component; mutations commit only on callback success.

Types: draw-error, geometry-spec, handle.

create

create: func(spec: instance) -> result<handle, draw-error>;

Allocates one retained instance referencing this owner’s geometry and optional material.

Types: draw-error, handle, instance.

update

update: func(id: handle, spec: instance) -> result<_, draw-error>;

Atomically replaces an existing instance’s specification after a successful callback.

Types: draw-error, handle, instance.

replace-frame-group

replace-frame-group: func(name: string, draws: list<instance>) -> result<_, draw-error>;

Replaces the named callback-lifetime group; it expires at the next successful callback.

Types: draw-error, instance.

remove

remove: func(id: handle) -> result<_, draw-error>;

Releases this owner’s resource; referenced geometry or materials return in-use.

Types: draw-error, handle.