Struct ViewerSharedState 

pub struct ViewerSharedState { /* private fields */ }

Internal state that is used by MjViewer to store MjData-related state. This is separate from MjViewer to allow use in multi-threaded programs, where the physics part runs in another thread and syncs the state with the viewer running in the main thread.

The state can be obtained through MjViewer::state, which will return a reference to an Arc<Mutex<ViewerSharedState>> instance. For scoped access, you may also use MjViewer::with_state_lock.

Implementations

impl ViewerSharedState

pub fn running(&self) -> bool

Checks whether the viewer is still running or is supposed to run.

pub fn user_scene(&self) -> &MjvScene

Returns an immutable reference to a user scene for drawing custom visual-only geoms. Geoms in the user scene are preserved between calls to ViewerSharedState::sync_data.

pub fn user_scene_mut(&mut self) -> &mut MjvScene

Returns a mutable reference to a user scene for drawing custom visual-only geoms. Geoms in the user scene are preserved between calls to ViewerSharedState::sync_data.

pub fn sync_model(&mut self, model: &mut MjModel)

Performs a bidirectional three-way merge of model’s opt, vis, and stat parameters between the viewer’s passive model and the incoming model.

Detects model changes via signature comparison and reloads internal state if needed.

pub fn sync_model_opt(&mut self, opt: &mut MjOption)

Performs a bidirectional three-way merge of MjModel::opt between the viewer’s passive model and the provided option struct.

Changes made by the viewer UI are written to opt; changes made to opt externally are written back to the viewer’s passive model.

pub fn sync_model_vis(&mut self, vis: &mut MjVisual)

Performs a bidirectional three-way merge of MjModel::vis between the viewer’s passive model and the provided visual struct.

Changes made by the viewer UI are written to vis; changes made to vis externally are written back to the viewer’s passive model.

pub fn sync_model_stat(&mut self, stat: &mut MjStatistic)

Performs a bidirectional three-way merge of MjModel::stat between the viewer’s passive model and the provided statistic struct.

Changes made by the viewer UI are written to stat; changes made to stat externally are written back to the viewer’s passive model.

pub fn last_opt_sync_time(&self) -> Instant

Returns the last time physics options (opt) were synced.

pub fn last_vis_sync_time(&self) -> Instant

Returns the last time visualization options (vis) were synced.

pub fn last_stat_sync_time(&self) -> Instant

Returns the last time statistics (stat) were synced.

pub fn update_texture_from( &mut self, model: &MjModel, texture_id: usize, ) -> Result<(), MjViewerError>

Copies the texture with texture_id from model into the viewer’s internal passive model and schedules a GPU re-upload for the next MjViewer::render call.

The upload is processed on the next call to MjViewer::render, at which point the updated texture will be reflected in the scene.

Errors

• MjViewerError::SignatureMismatch if model’s signature does not match the viewer’s passive model.
• MjViewerError::IndexOutOfBounds if texture_id >= model.ntex().

pub fn update_textures_from( &mut self, model: &MjModel, ) -> Result<(), MjViewerError>

Copies all textures from model into the viewer’s internal passive model and schedules a GPU re-upload for the next MjViewer::render call.

Errors

• MjViewerError::SignatureMismatch if model’s signature does not match the viewer’s passive model.

pub fn update_mesh_from( &mut self, model: &MjModel, mesh_id: usize, ) -> Result<(), MjViewerError>

Copies the mesh with mesh_id from model into the viewer’s internal passive model and schedules a GPU re-upload for the next MjViewer::render call.

All data arrays read by mjr_uploadMesh are copied: vertex positions (mesh_vert), per-vertex normals (mesh_normal), UV texture coordinates (mesh_texcoord), face–vertex indices (mesh_face), face–normal indices (mesh_facenormal), face–texcoord indices (mesh_facetexcoord), and convex hull graph data (mesh_graph). Layout fields (address and count arrays) are not copied because they are fixed by the model signature.

The upload is processed on the next call to MjViewer::render, at which point the updated mesh will be reflected in the scene.

Errors

• MjViewerError::SignatureMismatch if model’s signature does not match the viewer’s passive model.
• MjViewerError::IndexOutOfBounds if mesh_id >= model.nmesh().

pub fn update_meshes_from( &mut self, model: &MjModel, ) -> Result<(), MjViewerError>

Copies all meshes from model into the viewer’s internal passive model and schedules a GPU re-upload for the next MjViewer::render call.

All data arrays read by mjr_uploadMesh are bulk-copied: vertex positions (mesh_vert), per-vertex normals (mesh_normal), UV texture coordinates (mesh_texcoord), face–vertex indices (mesh_face), face–normal indices (mesh_facenormal), face–texcoord indices (mesh_facetexcoord), and convex hull graph data (mesh_graph). Layout fields (address and count arrays) are not copied because they are fixed by the model signature.

Errors

• MjViewerError::SignatureMismatch if model’s signature does not match the viewer’s passive model.

pub fn update_hfield_from( &mut self, model: &MjModel, hfield_id: usize, ) -> Result<(), MjViewerError>

Copies the heightfield with hfield_id from model into the viewer’s internal passive model and schedules a GPU re-upload for the next MjViewer::render call.

The upload is processed on the next call to MjViewer::render, at which point the updated heightfield will be reflected in the scene.

Errors

• MjViewerError::SignatureMismatch if model’s signature does not match the viewer’s passive model.
• MjViewerError::IndexOutOfBounds if hfield_id >= model.nhfield().

pub fn update_hfields_from( &mut self, model: &MjModel, ) -> Result<(), MjViewerError>

Copies all heightfields from model into the viewer’s internal passive model and schedules a GPU re-upload for the next MjViewer::render call.

Errors

• MjViewerError::SignatureMismatch if model’s signature does not match the viewer’s passive model.

pub fn sync_data_full<M: Deref<Target = MjModel>>( &mut self, data: &mut MjData<M>, )

Same as ViewerSharedState::sync_data, except it copies the entire MjData struct (including large Jacobian and other arrays), not just the state needed for visualization.

Panics

Panics if the internal data copy fails due to an inconsistent model state (indicates a bug).

pub fn sync_data<M: Deref<Target = MjModel>>(&mut self, data: &mut MjData<M>)

Syncs the viewer’s internal passive MjData with data. Synchronization happens in three steps:

1. The viewer checks if any changes have been made to the internal MjData since the last call to this method (since the last sync). Changed elements are selectively merged into data (elements the viewer did not touch are preserved).
2. data is copied into the viewer’s internal passive copy (visualization fields only; see warning below).
3. Perturbations are applied to data via MjvPerturb::apply, which unconditionally zeroes xfrc_applied before writing any active perturbation forces. Any external forces previously set on data will be cleared.

Note that users must afterward call MjViewer::render for the scene to be rendered and the UI to be processed.

The user's data is copied into the viewer's internal passive copy via ``mjv_copyData``, which skips large computed arrays not required for visualization. The viewer's passive copy will therefore **not** contain:

• mass matrices (qM, qLD, qLDiagInv, qLU);
• constraint arrays (efc_*, iefc_*, including constraint Jacobians).

In UI callbacks these fields will be absent unless ViewerSharedState::sync_data_full is used or they are recomputed explicitly (e.g. via data.forward()).

Additionally, because the viewer may write integration state (e.g. ctrl) back to the user’s data, any Jacobians or other derived quantities in data may be stale after this call and should be recomputed if needed.

Panics

Panics if the internal data copy or state merge fails due to an inconsistent model state (indicates a bug).

Trait Implementations

impl Debug for ViewerSharedState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.