World drawing: masks

cinnabar:world-draw/masks@0.1.0

Retained union silhouettes. Tokens are private to one component and session.

Grants: entity_highlight; actor lookup also requires entity_observe and render_through_walls, elevated coverage requires render_through_walls, and effects require render_post.

Imported type handle: handle.

Imported type draw-error: draw-error.

Types

depth-policy

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

enum depth-policy {
    test,
    always,
}

rgba

Display-space colour components, including alpha coverage.

record rgba {
    r: f32,
    g: f32,
    b: f32,
    a: f32,
}

style

Display-space colours and physical-pixel radii; zero alpha disables a layer.

record style {
    outline: rgba,
    outline-radius: f32,
    glow: rgba,
    glow-radius: f32,
}

Types: rgba.

effect-spec

A named, ordered post effect retaining references to this owner’s masks.

record effect-spec {
    name: string,
    order: s32,
    source: string,
    masks: list<handle>,
}

Types: handle.

Functions

entity

entity: func(runtime-id: u64) -> result<handle, draw-error>;

Resolves an already authorized actor. Unfiltered lookup requires observation authority.

Types: draw-error, handle.

create

create: func(depth: depth-policy) -> result<handle, draw-error>;

Creates an empty retained mask; its depth policy is fixed at creation.

Types: depth-policy, draw-error, handle.

select

select: func(mask: handle, entities: list<handle>) -> result<_, draw-error>;

Atomically replaces membership; an empty selection clears coverage.

Types: draw-error, handle.

remove

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

Releases an owned mask once no retained effect references it.

Types: draw-error, handle.

set-style

set-style: func(mask: handle, appearance: option<style>) -> result<_, draw-error>;

Replaces the host-composed outline and glow; none removes the style without releasing the mask.

Types: draw-error, handle, style.

register-effect

register-effect: func(spec: effect-spec) -> result<_, draw-error>;

Arbitrary sampling also requires the separately negotiated render-post capability.

Types: draw-error, effect-spec.