Struct VisualWorld 

pub struct VisualWorld { /* private fields */ }

Implementations

impl VisualWorld

pub fn instance(&self, handle: InstanceHandle) -> Option<&VisualInstance>

pub fn skin(&self, id: SkinId) -> Option<&Skin>

Examples found in repository

examples/vtuber-joints-example.rs (line 452)

fn debug_print_selected_joint_influence(
    universe: &engine::Universe,
    mesh_key: &str,
    model_root: engine::ecs::ComponentId,
    selected: &[(usize, engine::ecs::ComponentId)],
) {
    let Some(renderable) = find_renderable_by_mesh_key(&universe.world, model_root, mesh_key)
    else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' renderable not found",
            mesh_key
        );
        return;
    };

    let renderable_handle = universe
        .world
        .get_component_by_id_as::<RenderableComponent>(renderable)
        .and_then(|r| r.get_handle());
    println!(
        "[vtuber-joints-example] influence: mesh_key='{}' renderable={:?} instance_handle={:?}",
        mesh_key, renderable, renderable_handle
    );
    let Some(skin_id) = find_skin_id_for_renderable(&universe.world, renderable) else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' has no skin_id",
            mesh_key
        );
        return;
    };
    let Some(skin) = universe.visuals.skin(skin_id) else {
        println!(
            "[vtuber-joints-example] influence: skin_id={:?} missing in visuals",
            skin_id
        );
        return;
    };
    let Some(cpu_h) = universe.render_assets.imported_mesh(mesh_key) else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' missing in RenderAssets (did meshes register?)",
            mesh_key
        );
        return;
    };
    let Some(cpu) = universe.render_assets.cpu_mesh(cpu_h) else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' cpu mesh handle invalid",
            mesh_key
        );
        return;
    };
    let (Some(joints0), Some(weights0)) = (cpu.joints0.as_ref(), cpu.weights0.as_ref()) else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' has no skin attributes",
            mesh_key
        );
        return;
    };

    let joint_count = skin.joint_count();
    let totals = compute_total_weight_per_joint(joints0, weights0, joint_count);

    println!(
        "[vtuber-joints-example] influence: mesh_key='{}' verts={} joints={}",
        mesh_key,
        cpu.vertices.len(),
        joint_count
    );

    for &(node_index, joint_tx) in selected.iter() {
        // Find the skin joint index that maps to this node.
        let skin_joint_index = skin
            .joint_node_indices
            .iter()
            .position(|&ni| ni == node_index);

        let name = universe
            .world
            .get_component_record(joint_tx)
            .map(|r| r.name.as_str())
            .unwrap_or("<unknown>");

        match skin_joint_index {
            Some(j) => {
                let total = totals.get(j).copied().unwrap_or(0.0);
                println!(
                    "  influence: name='{}' node_index={} skin_joint_index={} total_weight={:.3}",
                    name, node_index, j, total
                );
            }
            None => {
                println!(
                    "  influence: name='{}' node_index={} skin_joint_index=<none>",
                    name, node_index
                );
            }
        }
    }
}

fn compute_total_weight_per_joint(
    joints0: &[[u16; 4]],
    weights0: &[[f32; 4]],
    joint_count: usize,
) -> Vec<f32> {
    let mut totals = vec![0.0f32; joint_count];
    if joint_count == 0 {
        return totals;
    }
    for (jv, wv) in joints0.iter().zip(weights0.iter()) {
        for lane in 0..4 {
            let j = jv[lane] as usize;
            if j >= joint_count {
                continue;
            }
            let w = wv[lane];
            if w > 0.0 {
                totals[j] += w;
            }
        }
    }
    totals
}

fn select_body_prim0_influencers(
    universe: &engine::Universe,
    model_root: engine::ecs::ComponentId,
    mesh_key: &str,
    count: usize,
    node_index_to_transform: &HashMap<usize, engine::ecs::ComponentId>,
) -> Option<Vec<(usize, engine::ecs::ComponentId)>> {
    if count == 0 {
        return Some(Vec::new());
    }

    let renderable = find_renderable_by_mesh_key(&universe.world, model_root, mesh_key)?;
    let skin_id = find_skin_id_for_renderable(&universe.world, renderable)?;
    let skin = universe.visuals.skin(skin_id)?;

    let cpu_h = universe.render_assets.imported_mesh(mesh_key)?;
    let cpu = universe.render_assets.cpu_mesh(cpu_h)?;
    let joints0 = cpu.joints0.as_ref()?;
    let weights0 = cpu.weights0.as_ref()?;

    let joint_count = skin.joint_count();
    if joint_count == 0 {
        return None;
    }

    let mut total_weight_per_joint: Vec<f32> = vec![0.0; joint_count];
    for (jv, wv) in joints0.iter().zip(weights0.iter()) {
        for lane in 0..4 {
            let j = jv[lane] as usize;
            if j >= joint_count {
                continue;
            }
            let w = wv[lane];
            if w > 0.0 {
                total_weight_per_joint[j] += w;
            }
        }
    }

    let mut ranked: Vec<(usize, f32)> =
        total_weight_per_joint.iter().copied().enumerate().collect();
    ranked.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));

    let min_total: f32 = 10.0;

    println!(
        "[vtuber-joints-example] auto joints for mesh_key='{}': verts={} joint_count={} min_total={}",
        mesh_key,
        cpu.vertices.len(),
        joint_count,
        min_total
    );

    let mut out: Vec<(usize, engine::ecs::ComponentId)> = Vec::with_capacity(count);
    let mut seen: HashSet<engine::ecs::ComponentId> = HashSet::new();

    for (joint_index, total) in ranked.into_iter() {
        if out.len() >= count {
            break;
        }
        if total < min_total {
            continue;
        }

        let node_index = *skin.joint_node_indices.get(joint_index)?;
        let Some(&joint_tx) = node_index_to_transform.get(&node_index) else {
            continue;
        };
        if !seen.insert(joint_tx) {
            continue;
        }

        let name = universe
            .world
            .get_component_record(joint_tx)
            .map(|n| n.name.clone())
            .unwrap_or_else(|| "<unknown>".to_string());

        println!(
            "  auto[{:<2}] joint_index={:<3} total_weight={:<10.3} node_index={:<3} name={} tx={:?}",
            out.len(),
            joint_index,
            total,
            node_index,
            name,
            joint_tx
        );

        out.push((node_index, joint_tx));
    }

    if out.is_empty() { None } else { Some(out) }
}

fn find_renderable_by_mesh_key(
    world: &engine::ecs::World,
    root: engine::ecs::ComponentId,
    mesh_key: &str,
) -> Option<engine::ecs::ComponentId> {
    let mut stack = vec![root];
    while let Some(node) = stack.pop() {
        if let Some(m) = world.get_component_by_id_as::<MeshComponent>(node) {
            if m.key == mesh_key {
                return find_parent_renderable(world, node);
            }
        }
        for &ch in world.children_of(node) {
            stack.push(ch);
        }
    }
    None
}

fn find_parent_renderable(
    world: &engine::ecs::World,
    mut cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    while let Some(parent) = world.parent_of(cid) {
        if world
            .get_component_by_id_as::<RenderableComponent>(parent)
            .is_some()
        {
            return Some(parent);
        }
        cid = parent;
    }
    None
}

fn find_skin_id_for_renderable(
    world: &engine::ecs::World,
    renderable: engine::ecs::ComponentId,
) -> Option<engine::graphics::SkinId> {
    let mut stack = vec![renderable];
    while let Some(node) = stack.pop() {
        if let Some(sm) = world.get_component_by_id_as::<SkinnedMeshComponent>(node) {
            if let Some(id) = sm.skin_id {
                return Some(id);
            }
        }
        for &ch in world.children_of(node) {
            stack.push(ch);
        }
    }
    None
}

fn collect_joint_transforms(
    world: &engine::ecs::World,
    skinned_mesh: &engine::ecs::system::SkinnedMeshSystem,
    visuals: &engine::graphics::VisualWorld,
    gltf_component: engine::ecs::ComponentId,
    root: engine::ecs::ComponentId,
) -> Vec<(usize, engine::ecs::ComponentId)> {
    fn find_first_skin_id_in_subtree(
        world: &engine::ecs::World,
        root: engine::ecs::ComponentId,
    ) -> Option<engine::graphics::SkinId> {
        let mut stack = vec![root];
        while let Some(node) = stack.pop() {
            if let Some(sm) = world.get_component_by_id_as::<SkinnedMeshComponent>(node) {
                if let Some(id) = sm.skin_id {
                    return Some(id);
                }
            }
            for &ch in world.children_of(node) {
                stack.push(ch);
            }
        }
        None
    }

    let Some(skin_id) = find_first_skin_id_in_subtree(world, root) else {
        return Vec::new();
    };
    let Some(skin) = visuals.skin(skin_id) else {
        return Vec::new();
    };
    let Some(joints) = skinned_mesh.instance_joints_for_skin(gltf_component, skin_id) else {
        return Vec::new();
    };

    let joint_count = skin.joint_count().min(joints.len());
    let mut out: Vec<(usize, engine::ecs::ComponentId)> = Vec::with_capacity(joint_count);
    for i in 0..joint_count {
        let Some(joint_tx) = joints[i] else {
            continue;
        };
        let node_index = skin.joint_node_indices[i];
        out.push((node_index, joint_tx));
    }

    out
}

pub fn skin_id_for(&self, uri: &str, skin_index: usize) -> Option<SkinId>

pub fn upsert_skin( &mut self, uri: &str, skin_index: usize, joint_node_indices: Vec<usize>, inverse_bind_matrices: Vec<TransformMatrix>, ) -> SkinId

pub fn set_skin_matrices( &mut self, handle: InstanceHandle, bones: &[TransformMatrix], ) -> bool

Assigns the skin matrices for an instance into the shared palette.

This keeps bones_base stable for an instance unless its bone count changes.

pub fn bones_palette(&self) -> &[TransformMatrix]

pub fn take_bones_palette_dirty(&mut self) -> bool

Returns whether the bones palette changed since the last call, and clears the dirty flag.

pub fn update_skin_range( &mut self, handle: InstanceHandle, bones_base: u32, bones_count: u32, ) -> bool

Compatibility helper: updates the skin palette range for an instance.

Prefer set_skin_matrices() for stable allocation.

impl VisualWorld

pub fn new() -> Self

pub fn clear_color(&self) -> [f32; 4]

pub fn set_clear_color(&mut self, rgba: [f32; 4])

pub fn renderer_msaa_mode(&self) -> MsaaMode

pub fn set_renderer_msaa_mode(&mut self, mode: MsaaMode)

pub fn preferred_window_size(&self) -> Option<[u32; 2]>

pub fn set_preferred_window_size(&mut self, size: Option<[u32; 2]>)

pub fn take_preferred_window_size(&mut self) -> Option<[u32; 2]>

pub fn window_frame_dt_sec(&self) -> f32

pub fn window_frame_fps(&self) -> f32

pub fn set_window_frame_dt_sec(&mut self, dt_sec: f32)

pub fn xr_frame_dt_sec(&self) -> Option<f32>

pub fn xr_frame_fps(&self) -> Option<f32>

pub fn set_xr_frame_dt_sec(&mut self, dt_sec: Option<f32>)

pub fn ambient_light(&self) -> [f32; 3]

pub fn set_ambient_light(&mut self, rgb: [f32; 3])

pub fn clear(&mut self)

pub fn active_xr_camera(&self) -> Option<ComponentId>

pub fn set_active_xr_camera(&mut self, component: Option<ComponentId>)

pub fn lights_dirty(&self) -> bool

pub fn take_lights_dirty(&mut self) -> bool

pub fn point_lights(&self) -> &[VisualPointLight]

pub fn upsert_point_light(&mut self, cid: ComponentId, light: VisualPointLight)

pub fn camera_dirty(&self) -> bool

pub fn take_camera_dirty(&mut self) -> bool

pub fn visual_cameras(&self) -> &[VisualCamera]

pub fn visual_camera(&self, target: CameraTarget) -> Option<&VisualCamera>

pub fn camera_view(&self) -> [[f32; 4]; 4]

Window-facing compatibility: returns the first eye’s view matrix for the window target.

pub fn camera_proj(&self) -> [[f32; 4]; 4]

Window-facing compatibility: returns the first eye’s projection matrix for the window target.

pub fn camera_view_for(&self, target: CameraTarget) -> [[f32; 4]; 4]

pub fn camera_view_for_eye( &self, target: CameraTarget, eye: usize, ) -> [[f32; 4]; 4]

pub fn camera_proj_for(&self, target: CameraTarget) -> [[f32; 4]; 4]

pub fn camera_proj_for_eye( &self, target: CameraTarget, eye: usize, ) -> [[f32; 4]; 4]

pub fn viewport(&self) -> [f32; 2]

pub fn set_viewport(&mut self, viewport: [f32; 2])

pub fn camera_2d(&self) -> [[f32; 4]; 3]

pub fn set_camera(&mut self, view: [[f32; 4]; 4], proj: [[f32; 4]; 4])

pub fn set_camera_for_target( &mut self, target: CameraTarget, eyes: Vec<CameraData>, )

Set all eyes for a target.

• For CameraTarget::Window, pass a 1-element eyes vector.
• For CameraTarget::Xr, pass 2 (or more) eyes.

pub fn set_camera_mono_for_target( &mut self, target: CameraTarget, view: [[f32; 4]; 4], proj: [[f32; 4]; 4], )

Convenience: set a single-eye camera for a target.

pub fn set_camera_mono_for_target_with_transform( &mut self, target: CameraTarget, view: [[f32; 4]; 4], proj: [[f32; 4]; 4], transform: Transform, )

pub fn set_xr_camera(&mut self, eyes: Vec<CameraData>)

Convenience: set XR eyes.

pub fn set_camera_2d(&mut self, m: [[f32; 4]; 3])

pub fn register_mirror(&mut self, mirror: VisualMirror)

pub fn clear_mirrors(&mut self)

pub fn mirrors(&self) -> &[VisualMirror]

pub fn mirror_texture_key_for_view( &self, mirror_component: ComponentId, family: MirrorViewerFamily, view_index: usize, ) -> Option<&str>

pub fn mirror_count(&self) -> usize

pub fn instance_data_dirty(&self) -> bool

Returns whether any per-instance data has changed since the last time it was consumed.

pub fn take_instance_data_dirty(&mut self) -> bool

Consume the instance-data dirty flag.

pub fn instances(&self) -> &[VisualInstance]

pub fn instance_count(&self) -> usize

pub fn background_order(&self) -> &[u32]

Indices into instances() in the order they should be drawn (opaque batching).

pub fn background_batches(&self) -> &[DrawBatch]

pub fn background_occluded_lit_order(&self) -> &[u32]

pub fn background_occluded_lit_batches(&self) -> &[DrawBatch]

pub fn background_occluded_lit_emissive_order(&self) -> &[u32]

pub fn background_occluded_lit_emissive_batches(&self) -> &[DrawBatch]

pub fn has_background_occluded_lit_emissive(&self) -> bool

pub fn draw_order(&self) -> &[u32]

Indices into instances() in the order they should be drawn (opaque batching).

pub fn draw_batches(&self) -> &[DrawBatch]

pub fn emissive_draw_order(&self) -> &[u32]

Indices into instances() in the order they should be drawn (emissive opaque batching).

pub fn emissive_draw_batches(&self) -> &[DrawBatch]

pub fn cutout_order(&self) -> &[u32]

Indices into instances() in the order they should be drawn (alpha-to-coverage cutout pass).

pub fn cutout_batches(&self) -> &[DrawBatch]

pub fn cutout_stream(&self) -> (&[RenderOp], &[u32])

DFS-ordered render stream for the alpha-to-coverage cutout phase.

pub fn cutout_stream_excluding( &self, excluded_instance: Option<InstanceHandle>, ) -> (Vec<RenderOp>, Vec<u32>)

pub fn emissive_cutout_order(&self) -> &[u32]

Indices into instances() in the order they should be drawn (emissive cutout batching).

pub fn emissive_cutout_batches(&self) -> &[DrawBatch]

pub fn overlay_order(&self) -> &[u32]

Indices into instances() in the order they should be drawn (overlay pass).

pub fn overlay_batches(&self) -> &[DrawBatch]

pub fn transparent_single_stream(&self) -> (&[RenderOp], &[u32])

DFS-ordered render stream for the single-layer transparent phase.

pub fn transparent_single_stream_excluding( &self, excluded_instance: Option<InstanceHandle>, ) -> (Vec<RenderOp>, Vec<u32>)

pub fn overlay_stream(&self) -> (&[RenderOp], &[u32])

DFS-ordered render stream for the overlay phase.

Returns (ops, instance_indices).

• ops is the sequence of EnterClip, DrawBatch, and ExitClip commands.
• instance_indices[batch.start .. batch.start + batch.count] gives the VisualInstance indices for each DrawBatch op.

pub fn overlay_stream_excluding( &self, excluded_instance: Option<InstanceHandle>, ) -> (Vec<RenderOp>, Vec<u32>)

pub fn opaque_stream(&self) -> (&[RenderOp], &[u32])

DFS-ordered render stream for the opaque phase.

Returns (ops, instance_indices).

pub fn opaque_stream_excluding( &self, excluded_instance: Option<InstanceHandle>, ) -> (Vec<RenderOp>, Vec<u32>)

pub fn stencil_clip_order(&self) -> &[u32]

Indices into instances() where is_stencil_clip=true, sorted by stencil_ref ascending. Used by the renderer to inject stencil write/restore draws around clipped batch groups.

pub fn register_stencil_clip( &mut self, handle: InstanceHandle, stencil_ref: u8, ) -> bool

Mark an instance as a stencil clip source with the given reference value. Triggers draw cache rebuild.

pub fn unregister_stencil_clip(&mut self, handle: InstanceHandle) -> bool

Remove stencil clip status from an instance.

pub fn update_stencil_ref( &mut self, handle: InstanceHandle, stencil_ref: u8, ) -> bool

Update the stencil reference value for a clipped instance (not the clip source itself).

pub fn transparent_single_draw_order(&self) -> &[u32]

Indices into instances() in the order they should be drawn (single-layer transparent pass).

pub fn transparent_single_draw_batches(&self) -> &[DrawBatch]

pub fn transparent_multi_draw_order(&self) -> &[u32]

Indices into instances() in the order they should be drawn (multi-layer transparent pass).

pub fn transparent_multi_draw_batches(&self) -> &[DrawBatch]

pub fn transparent_multi_draw_excluding( &self, excluded_instance: Option<InstanceHandle>, ) -> (Vec<u32>, Vec<DrawBatch>)

pub fn prepare_draw_cache(&mut self) -> bool

Call once per frame before rendering. Cheap if nothing changed.

Returns true if the cached draw order/batches were rebuilt this call.

pub fn prepare_transparent_multi_draw_cache_for_eye( &mut self, target: CameraTarget, eye: usize, )

pub fn prepare_transparent_multi_draw_cache_for_view( &mut self, view: [[f32; 4]; 4], )

Rebuild multi-layer transparent draw order/batches for a specific view matrix.

pub fn register( &mut self, cid: ComponentId, renderable: GpuRenderable, transform: Transform, color: [f32; 4], opacity: f32, multiple_layers: bool, transparent_cutout: bool, background: bool, background_occluded_lit: bool, overlay: bool, emissive: f32, texture: Option<TextureHandle>, quant_steps: f32, ) -> InstanceHandle

pub fn update_quant_steps( &mut self, handle: InstanceHandle, quant_steps: f32, ) -> bool

pub fn remove(&mut self, handle: InstanceHandle) -> bool

pub fn update_transform( &mut self, handle: InstanceHandle, transform: Transform, ) -> bool

pub fn update_model( &mut self, handle: InstanceHandle, model: TransformMatrix, ) -> bool

pub fn update_color(&mut self, handle: InstanceHandle, color: [f32; 4]) -> bool

pub fn update_opacity(&mut self, handle: InstanceHandle, opacity: f32) -> bool

pub fn update_opacity_state( &mut self, handle: InstanceHandle, opacity: f32, multiple_layers: impl Into<Option<bool>>, ) -> bool

pub fn update_transparent_cutout( &mut self, handle: InstanceHandle, enabled: bool, ) -> bool

pub fn update_emissive(&mut self, handle: InstanceHandle, emissive: f32) -> bool

pub fn update_material( &mut self, handle: InstanceHandle, material: MaterialHandle, ) -> bool

pub fn post_processing(&self) -> &PostProcessingConfig

pub fn post_processing_mut(&mut self) -> &mut PostProcessingConfig

pub fn set_post_processing(&mut self, config: PostProcessingConfig)

pub fn runtime_texture_handle(&self, key: &str) -> Option<TextureHandle>

pub fn stencil_clip_debug_requested(&self) -> bool

pub fn set_stencil_clip_debug_requested(&mut self, requested: bool)

pub fn set_runtime_texture_handle( &mut self, key: impl Into<String>, handle: TextureHandle, )

pub fn update_texture( &mut self, handle: InstanceHandle, texture: Option<TextureHandle>, ) -> bool

pub fn update_texture_filtering( &mut self, handle: InstanceHandle, filtering: TextureFiltering, ) -> bool

pub fn update( &mut self, handle: InstanceHandle, renderable: GpuRenderable, transform: Transform, ) -> bool

Trait Implementations

impl Default for VisualWorld

fn default() -> Self

Returns the “default value” for a type.