Struct MjRenderer 

pub struct MjRenderer { /* private fields */ }

A renderer for rendering 3D scenes. By default, RGB rendering is enabled and depth rendering is disabled.

Implementations

impl MjRenderer

pub fn new<M: Deref<Target = MjModel>>( model: M, width: usize, height: usize, max_user_geom: usize, ) -> Result<Self, RendererError>

Construct a new renderer. The max_user_geom parameter defines how much space will be allocated for additional, user-defined visual-only geoms. It can thus be set to 0 if no additional geoms will be drawn by the user.

Scene allocation

The renderer uses two scenes:

• the internal scene: used by the renderer to draw the model’s state.
• the user scene: used by the user to add additional geoms to the internal scene

The internal scene allocates the amount of space needed to fit every pre-existing model geom + user visual-only geoms + additional visual-only geoms that aren’t from the user (e.g., tendons). By default, the renderer reserves 100 extra geom slots for drawing the additional visual-only geoms. If that is not enough or it is too much, you can construct MjRenderer via its builder (MjRenderer::builder), which allows more configuration.

Parameters width and height must be less or equal to the offscreen buffer size, which can be configured at the top of the model’s XML like so:

<visual>
   <global offwidth="1920" offheight="1080"/>
</visual>

# Returns On success, returns [`Ok`] variant containing the [`MjRenderer`]. # Errors - [`RendererError::ZeroDimension`] if the width or height is zero. - [`RendererError::GlutinError`] if OpenGL initialization fails. - [`RendererError::EventLoopError`] if the event loop fails to initialize (feature `renderer-winit-fallback`). - [`RendererError::GlInitFailed`] if the fallback window initialization fails (feature `renderer-winit-fallback`).

pub fn builder() -> MjRendererBuilder

Create a MjRendererBuilder to configure MjRenderer.

pub fn scene(&self) -> &MjvScene

Return an immutable reference to the internal scene.

pub fn user_scene(&self) -> &MjvScene

Return an immutable reference to a user scene for drawing custom visual-only geoms.

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

Return a mutable reference to a user scene for drawing custom visual-only geoms.

pub fn opts(&self) -> &MjvOption

Return an immutable reference to visualization options.

pub fn opts_mut(&mut self) -> &mut MjvOption

Return a mutable reference to visualization options.

pub fn camera(&self) -> &MjvCamera

Return an immutable reference to the camera.

pub fn camera_mut(&mut self) -> &mut MjvCamera

Return a mutable reference to the camera.

pub fn rgb_enabled(&self) -> bool

Check if RGB rendering is enabled.

pub fn depth_enabled(&self) -> bool

Check if depth rendering is enabled.

pub fn set_font_scale( &mut self, font_scale: MjtFontScale, ) -> Result<(), RendererError>

Sets the font scale.

Errors

Returns RendererError::GlutinError if the OpenGL context cannot be made current.

pub fn set_opts(&mut self, options: MjvOption)

Update the visualization options.

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

Re-uploads the texture with texture_id from model to the GPU immediately.

Errors

• RendererError::SignatureMismatch if model’s signature does not match the renderer’s scene.
• RendererError::ContextError if texture_id >= model.ntex().
• RendererError::GlutinError if the OpenGL context cannot be made current.

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

Re-uploads all textures from model to the GPU immediately.

Errors

• RendererError::SignatureMismatch if model’s signature does not match the renderer’s scene.
• RendererError::GlutinError if the OpenGL context cannot be made current.

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

Re-uploads the mesh with mesh_id from model to the GPU immediately.

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.

Errors

• RendererError::SignatureMismatch if model’s signature does not match the renderer’s scene.
• RendererError::ContextError if mesh_id >= model.nmesh().
• RendererError::GlutinError if the OpenGL context cannot be made current.

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

Re-uploads all meshes from model to the GPU immediately.

All data arrays read by mjr_uploadMesh are bulk-uploaded: 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

• RendererError::SignatureMismatch if model’s signature does not match the renderer’s scene.
• RendererError::GlutinError if the OpenGL context cannot be made current.

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

Re-uploads the heightfield with hfield_id from model to the GPU immediately.

Errors

• RendererError::SignatureMismatch if model’s signature does not match the renderer’s scene.
• RendererError::ContextError if hfield_id >= model.nhfield().
• RendererError::GlutinError if the OpenGL context cannot be made current.

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

Re-uploads all heightfields from model to the GPU immediately.

Errors

• RendererError::SignatureMismatch if model’s signature does not match the renderer’s scene.
• RendererError::GlutinError if the OpenGL context cannot be made current.

pub fn set_camera(&mut self, camera: MjvCamera)

Set the camera used for rendering.

pub fn set_rgb_rendering(&mut self, enable: bool)

Enables/disables RGB rendering.

pub fn set_depth_rendering(&mut self, enable: bool)

Enables/disables depth rendering.

pub fn with_font_scale( self, font_scale: MjtFontScale, ) -> Result<Self, RendererError>

Sets the font scale. To be used on construction.

Errors

Returns RendererError::GlutinError if the OpenGL context cannot be made current.

pub fn with_opts(self, options: MjvOption) -> Self

Update the visualization options and return self. To be used on construction.

pub fn with_camera(self, camera: MjvCamera) -> Self

Set the camera used for rendering. To be used on construction.

pub fn with_rgb_rendering(self, enable: bool) -> Self

Enables/disables RGB rendering. To be used on construction.

pub fn with_depth_rendering(self, enable: bool) -> Self

Enables/disables depth rendering. To be used on construction.

pub fn set_png_compression(&mut self, compression: Compression)

Set the PNG compression level used by MjRenderer::save_rgb and MjRenderer::save_depth.

pub fn with_png_compression(self, compression: Compression) -> Self

Set the PNG compression level. To be used on construction.

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

Update the scene with new data from data. When data was created from a different model than the renderer, the internal scene is automatically recreated for the new model.

Errors

• RendererError::GlutinError if the OpenGL context could not be made current (only when the MjModel in data differs from the model that created the internal MjvScene).

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

👎Deprecated since 3.0.0:

replaced with sync_data + render

Update the scene with new data and render it.

Panics

Panics if syncing the data or performing the render step fails (e.g. the OpenGL context cannot be made current). Use MjRenderer::sync_data + MjRenderer::render instead.

pub fn rgb_flat(&self) -> Option<&[u8]>

Return a flattened RGB image of the scene.

pub fn rgb<const WIDTH: usize, const HEIGHT: usize>( &self, ) -> &[[[u8; 3]; WIDTH]; HEIGHT]

Return an RGB image of the scene. This method accepts two generic parameters <WIDTH, HEIGHT> that define the shape of the output slice.

Panics

• If the image size doesn’t match the required dimensions.
• If RGB rendering is disabled.

Use MjRenderer::try_rgb for a fallible alternative.

pub fn try_rgb<const WIDTH: usize, const HEIGHT: usize>( &self, ) -> Result<&[[[u8; 3]; WIDTH]; HEIGHT], RendererError>

Fallible version of MjRenderer::rgb.

Returns

On success, returns Ok variant containing the rendered RGB image.

Errors

• RendererError::DimensionMismatch if the image size doesn’t match the required dimensions.
• RendererError::RgbDisabled if RGB rendering is disabled.

pub fn depth_flat(&self) -> Option<&[f32]>

Return a flattened depth image of the scene.

pub fn depth<const WIDTH: usize, const HEIGHT: usize>( &self, ) -> &[[f32; WIDTH]; HEIGHT]

Return a depth image of the scene. This method accepts two generic parameters <WIDTH, HEIGHT> that define the shape of the output slice.

Panics

• If the image size doesn’t match the required dimensions.
• If depth rendering is disabled.

Use MjRenderer::try_depth for a fallible alternative.

pub fn try_depth<const WIDTH: usize, const HEIGHT: usize>( &self, ) -> Result<&[[f32; WIDTH]; HEIGHT], RendererError>

Fallible version of MjRenderer::depth.

Returns

On success, returns Ok variant containing the rendered depth image.

Errors

• RendererError::DimensionMismatch if the image size doesn’t match the required dimensions.
• RendererError::DepthDisabled if depth rendering is disabled.

pub fn save_rgb<T: AsRef<Path>>(&self, path: T) -> Result<(), RendererError>

Save an RGB image of the scene to a path.

Returns

Ok(()) on success.

Errors

• RendererError::RgbDisabled when RGB rendering is disabled.
• RendererError::IoError if a file I/O operation fails.

pub fn save_depth<T: AsRef<Path>>( &self, path: T, normalize: bool, ) -> Result<(f32, f32), RendererError>

Save a depth image of the scene to a path. The image is 16-bit PNG, which can be converted into depth (distance) data by dividing the grayscale values by 65535.0 and applying inverse normalization: depth = min + (grayscale / 65535.0) * (max - min).

If normalize is true, then the data is normalized with per-frame min-max normalization. When normalize is false, the depth values are mapped using the model’s camera near/far clip planes as the range, providing a fixed (frame-independent) mapping.

Use of MjRenderer::save_depth_raw is recommended if performance is critical, as it skips PNG encoding and also saves the true depth values directly.

Returns

An Ok((min, max)) is returned, where min and max represent the normalization parameters.

Errors

• RendererError::DepthDisabled when depth rendering is disabled.
• RendererError::IoError if a file I/O operation fails.

pub fn save_depth_raw<T: AsRef<Path>>( &self, path: T, ) -> Result<(), RendererError>

Save the raw depth data to the path. The data is encoded as a sequence of bytes, where groups of four represent a single f32 value in native byte order.

Returns

Ok(()) on success.

Errors

• RendererError::DepthDisabled when depth rendering is disabled.
• RendererError::IoError if a file I/O operation fails.

pub fn render(&mut self) -> Result<(), RendererError>

Draws the scene to internal arrays. Use MjRenderer::rgb or MjRenderer::depth to obtain the rendered image.

Errors

• RendererError::GlutinError if the OpenGL context could not be made current.
• RendererError::SceneError if the user-scene sync overflows the geom buffer.
• RendererError::ContextError if reading pixels from the framebuffer fails.

Trait Implementations

impl Debug for MjRenderer

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

Formats the value using the given formatter.

impl Drop for MjRenderer

Ensures the OpenGL context is current before GPU resources are freed.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.