Struct LinkageView 

pub struct LinkageView<'a, const DOF: usize, const MARKS: usize> { /* private fields */ }

A borrowed linkage used to evaluate, compose, and render a linkage.

It erases fixed step capacity while preserving the linkage-parameter and mark dimensions. Obtain one with LinkageFixed::view or LinkageBuf::view.

Examples

const LINKAGE: LinkageFixed<1, 0, 8> = LinkageFixed::start()
    .define_param("distance", 0.5)
    .forward_param("distance", 1.0, 5.0);

let pose = view.final_pose(&[0.5])?;
assert!(pose.position().is_close_to(&Vec3::from([3.0, 0.0, 0.0]), 1e-5));

The API keeps LinkageFixed<DOF, MARKS, N> as the owned const-generic representation and uses this borrowed wrapper to erase N.

Implementations

impl<'a, const DOF: usize, const MARKS: usize> LinkageView<'a, DOF, MARKS>

pub const DOF: usize = DOF

The number of linkage parameters expected at evaluation time.

pub const MARKS: usize = MARKS

The number of mark slots in this view.

pub const fn dof(&self) -> usize

Return the number of linkage parameters expected at evaluation time.

pub const fn len(&self) -> usize

Return the number of linkage steps, including the implicit start step.

pub const fn is_empty(&self) -> bool

Return whether this linkage has no steps.

pub const fn param(&self, index: usize) -> Param

Return a parameter definition by index.

Panics

Panics if index >= dof().

Examples

const LINKAGE: LinkageFixed<2, 0, 8> = LinkageFixed::start()
    .define_param("yaw", 0.5)
    .define_param("distance", 0.75);

let view = LINKAGE.view();
let param = view.param(0);
assert_eq!(param.name(), "yaw");
assert_eq!(param.default(), 0.5);

pub const fn params(&self) -> &'a [Param; DOF]

Return a reference to the parameter array.

Examples

const LINKAGE: LinkageFixed<2, 0, 8> = LinkageFixed::start()
    .define_param("x", 0.0)
    .define_param("y", 0.5);

let view = LINKAGE.view();
let params = view.params();
assert_eq!(params.len(), 2);

pub const fn param_defaults(&self) -> [f32; DOF]

Return each parameter’s normalized default value.

Examples

const LINKAGE: LinkageFixed<2, 0, 8> = LinkageFixed::start()
    .define_param("x", 0.25)
    .define_param("y", 0.75);

let defaults = LINKAGE.view().param_defaults();
assert_eq!(defaults, [0.25, 0.75]);

pub const fn steps(&self) -> &'a [Step]

Return a reference to the step slice.

pub const fn scan_param_range(&self, index: usize) -> (f32, f32)

Scan the steps for the (low, high) legal range of the parameter at index, as driven by the first step that uses it. Rotation ranges are in radians (convert with f32::to_degrees); translation/disk/sphere ranges are in linkage units.

This is an O(steps) linear scan, not a field read. The range is constant for a given linkage, so resolve it once — ideally in a const — and never per frame:

const HOURS_RANGE: (f32, f32) = LINKAGE.view().scan_param_range(1);

Panics

Panics if no step drives the parameter at index.

pub const fn mark_names(&self) -> &'a [&'static str; MARKS]

Return the active mark-name slots.

pub const fn mark_len(&self) -> usize

Return the number of distinct mark slots used by this linkage.

pub const fn mark_count(&self) -> usize

Return the number of marks currently used by this view.

pub const fn marks(&self) -> usize

Return the view’s mark-slot capacity.

pub const fn to_fixed<const N: usize>(self) -> LinkageFixed<DOF, MARKS, N>

Copy this view into fixed backing storage.

N must be large enough for the active steps.

See the fixed-storage example.

pub fn to_lb_rs(&self) -> String

Serialize this linkage view as .lb.rs source using the linkage![ ... ] format.

The output is intended for editor interchange and generated linkage files. Color values are emitted as Rgb888::new(r, g, b) calls.

See the growable storage and serialization examples.

pub const fn param_index(&self, name: &str, n: usize) -> usize

Return the index of the nth parameter (0-based) with the given name.

Panics

Panics if the name is not found or if n exceeds the occurrence count.

Examples

const LINKAGE: LinkageFixed<3, 0, 8> = LinkageFixed::start()
    .define_param("x", 0.0)
    .define_param("y", 0.5)
    .define_param("x", 0.8);

let view = LINKAGE.view();
assert_eq!(view.param_index("x", 0), 0);  // first "x"
assert_eq!(view.param_index("x", 1), 2);  // second "x"

pub fn final_pose(&self, params: &[f32; DOF]) -> Result<Pose, Error>

Return the final pose after evaluating all steps.

This evaluates the linkage immediately. When rendering or looking up marked poses in the same pass, use the DrawItem3dIter returned by Self::draw_items_3d and inspect it after exhaustion instead.

Examples

const LINKAGE: LinkageFixed<2, 0, 8> = LinkageFixed::start()
    .define_param("yaw", 0.5)
    .define_param("distance", 0.5)
    .yaw_param("yaw", -90.0, 90.0)
    .forward_param("distance", 1.0, 5.0);

let pose = view.final_pose(&[0.5, 0.6])?;
assert!(pose.position().is_close_to(&Vec3::from([3.4, 0.0, 0.0]), 1e-5));

pub fn poses<'b>( &'b self, params: &'b [f32; DOF], ) -> Result<impl Iterator<Item = Pose> + 'b, Error>

Iterate over all intermediate poses produced by evaluating this linkage.

Examples

const LINKAGE: LinkageFixed<1, 0, 8> = LinkageFixed::start()
    .define_param("distance", 0.5)
    .forward_param("distance", 1.0, 5.0);

let mut poses = view.poses(&[0.5])?;
let start = poses.next().expect("linkage always has start pose");
assert!(start.position().is_close_to(&Vec3::from([0.0, 0.0, 0.0]), 1e-5));
let end = poses.next().expect("forward step exists");
assert!(end.position().is_close_to(&Vec3::from([3.0, 0.0, 0.0]), 1e-5));

pub fn styled_poses<'b>( &'b self, params: &'b [f32; DOF], ) -> Result<impl Iterator<Item = StyledPose> + 'b, Error>

Iterate over all styled poses with their pen state.

Examples

const LINKAGE: LinkageFixed<0, 0, 8> = LinkageFixed::start()
    .forward(1.0)
    .forward(2.0);

let mut styled = view.styled_poses(&[])?;
let start = styled.next().expect("has start");
assert!(start.pose().position().is_close_to(&Vec3::from([0.0, 0.0, 0.0]), 1e-5));
assert_eq!(start.pen(), PenState::Down);
styled.next().expect("has first forward");
let end = styled.next().expect("has second forward");
assert!(end.pose().position()[0] > 2.9);

pub fn draw_items_3d<'b>( &'b self, params: &'b [f32; DOF], ) -> Result<DrawItem3dIter<'b, DOF, MARKS>, Error>

Iterate over all draw items produced by this linkage.

Examples

const LINKAGE: LinkageFixed<0, 0, 8> = LinkageFixed::start()
    .forward(1.0)
    .forward(2.0);

let has_stroke = view.draw_items_3d(&[])?
    .any(|item| matches!(item, Item3d::Stroke(_)));
assert!(has_stroke);

pub const fn draw_item_3d_count(&self) -> usize

The number of Item3ds this linkage yields, evaluated at compile time.

Which steps emit a draw item depends only on the linkage’s steps and pen state (which moves draw, which shapes are emitted), never on the runtime parameter values, so the count is a const and can size a buffer.

Examples

const LINKAGE: LinkageFixed<0, 0, 8> = LinkageFixed::start()
    .forward(1.0)
    .forward(2.0);

const COUNT: usize = LINKAGE.view().draw_item_3d_count();
assert_eq!(COUNT, 2);

Trait Implementations

impl<'a, const DOF: usize, const MARKS: usize> Clone for LinkageView<'a, DOF, MARKS>

fn clone(&self) -> LinkageView<'a, DOF, MARKS>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, const DOF: usize, const MARKS: usize> Copy for LinkageView<'a, DOF, MARKS>

impl<'a, const DOF: usize, const MARKS: usize> From<&'a LinkageBuf<DOF, MARKS>> for LinkageView<'a, DOF, MARKS>

Available on crate feature alloc only.

fn from(linkage: &'a LinkageBuf<DOF, MARKS>) -> Self

Converts to this type from the input type.

impl<'a, const DOF: usize, const MARKS: usize, const N: usize> From<&'a LinkageFixed<DOF, MARKS, N>> for LinkageView<'a, DOF, MARKS>

fn from(linkage: &'a LinkageFixed<DOF, MARKS, N>) -> Self

Converts to this type from the input type.