Add comments for the debug-renderer

4 files changed, 61 insertions, 2 deletions

diff --git a/src/geometry/mod.rs b/src/geometry/mod.rs
index d64c270..34d3707 100644
--- a/src/geometry/mod.rs
+++ b/src/geometry/mod.rs
@@ -51,6 +51,7 @@ pub type TOI = parry::query::TOI;
 pub use parry::shape::SharedShape;
 
 bitflags::bitflags! {
+    /// Flags providing more information regarding a collision event.
     #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
     pub struct CollisionEventFlags: u32 {
         /// Flag set if at least one of the colliders involved in the
diff --git a/src/pipeline/debug_render_pipeline/debug_render_backend.rs b/src/pipeline/debug_render_pipeline/debug_render_backend.rs
index 27a67e4..4fa86e4 100644
--- a/src/pipeline/debug_render_pipeline/debug_render_backend.rs
+++ b/src/pipeline/debug_render_pipeline/debug_render_backend.rs
@@ -6,16 +6,31 @@ use crate::math::{Isometry, Point, Real, Vector};
 use crate::prelude::{ColliderHandle, MultibodyJointHandle};
 use na::Scale;
 
+/// The object currently being rendered by the debug-renderer.
 #[derive(Copy, Clone)]
 pub enum DebugRenderObject<'a> {
+    /// A rigid-body is being rendered.
     RigidBody(RigidBodyHandle, &'a RigidBody),
+    /// A collider is being rendered.
     Collider(ColliderHandle, &'a Collider),
+    /// An impulse-joint is being rendered.
     ImpulseJoint(ImpulseJointHandle, &'a ImpulseJoint),
+    /// A multibody joint is being rendered.
     MultibodyJoint(MultibodyJointHandle, &'a Multibody, &'a MultibodyLink),
+    /// Another element is being rendered.
     Other,
 }
 
+/// Trait implemented by graphics backends responsible for rendering the physics scene.
+///
+/// The only thing that is required from the graphics backend is to be able to render
+/// a colored line. Note that the color is only a suggestion and is computed from the
+/// `DebugRenderStyle`. The backend is free to apply its own style, for example based on
+/// the `object` being rendered.
 pub trait DebugRenderBackend {
+    /// Draws a colored line.
+    ///
+    /// Note that this method can be called multiple time for the same `object`.
     fn draw_line(
         &mut self,
         object: DebugRenderObject,
@@ -24,6 +39,7 @@ pub trait DebugRenderBackend {
         color: [f32; 4],
     );
 
+    /// Draws a set of line.
     fn draw_polyline(
         &mut self,
         object: DebugRenderObject,
@@ -40,6 +56,7 @@ pub trait DebugRenderBackend {
         }
     }
 
+    /// Draws a chain of line.
     fn draw_line_strip(
         &mut self,
         object: DebugRenderObject,
diff --git a/src/pipeline/debug_render_pipeline/debug_render_pipeline.rs b/src/pipeline/debug_render_pipeline/debug_render_pipeline.rs
index 1c929c2..14da40d 100644
--- a/src/pipeline/debug_render_pipeline/debug_render_pipeline.rs
+++ b/src/pipeline/debug_render_pipeline/debug_render_pipeline.rs
@@ -13,20 +13,31 @@ use std::any::TypeId;
 use std::collections::HashMap;
 
 bitflags::bitflags! {
+    /// Flags indicating what part of the physics engine should be rendered
+    /// by the debug-renderer.
     pub struct DebugRenderMode: u32 {
+        /// If this flag is set, the collider shapes will be rendered.
         const COLLIDER_SHAPES = 1 << 0;
+        /// If this flag is set, the local coordinate axes of rigid-bodies will be rendered.
         const RIGID_BODY_AXES = 1 << 1;
+        /// If this flag is set, the multibody joints will be rendered.
         const MULTIBODY_JOINTS = 1 << 2;
+        /// If this flag is set, the impulse joints will be rendered.
         const IMPULSE_JOINTS = 1 << 3;
     }
 }
 
+/// Pipeline responsible for rendering the state of the physics engine for debugging purpose.
 pub struct DebugRenderPipeline {
     #[cfg(feature = "dim2")]
     instances: HashMap<TypeId, Vec<Point<Real>>>,
     #[cfg(feature = "dim3")]
     instances: HashMap<TypeId, (Vec<Point<Real>>, Vec<[u32; 2]>)>,
+    /// The style used to compute the line colors for each element
+    /// to render.
     pub style: DebugRenderStyle,
+    /// Flags controlling what part of the physics engine need to
+    /// be rendered.
     pub mode: DebugRenderMode,
 }
 
@@ -37,6 +48,7 @@ impl Default for DebugRenderPipeline {
 }
 
 impl DebugRenderPipeline {
+    /// Creates a new debug-render pipeline from a given style and flags.
     pub fn new(style: DebugRenderStyle, mode: DebugRenderMode) -> Self {
         Self {
             instances: outlines::instances(style.subdivisions),
@@ -45,10 +57,13 @@ impl DebugRenderPipeline {
         }
     }
 
+    /// Creates a new debug-render pipeline that renders everything
+    /// it can from the physics state.
     pub fn render_all(style: DebugRenderStyle) -> Self {
         Self::new(style, DebugRenderMode::all())
     }
 
+    /// Render the scene.
     pub fn render(
         &mut self,
         backend: &mut impl DebugRenderBackend,
@@ -57,11 +72,12 @@ impl DebugRenderPipeline {
         impulse_joints: &ImpulseJointSet,
         multibody_joints: &MultibodyJointSet,
     ) {
-        self.render_bodies(backend, bodies);
+        self.render_rigid_bodies(backend, bodies);
         self.render_colliders(backend, bodies, colliders);
         self.render_joints(backend, bodies, impulse_joints, multibody_joints);
     }
 
+    /// Render only the joints from the scene.
     pub fn render_joints(
         &mut self,
         backend: &mut impl DebugRenderBackend,
@@ -137,7 +153,12 @@ impl DebugRenderPipeline {
         }
     }
 
-    pub fn render_bodies(&mut self, backend: &mut impl DebugRenderBackend, bodies: &RigidBodySet) {
+    /// Render only the rigid-bodies from the scene.
+    pub fn render_rigid_bodies(
+        &mut self,
+        backend: &mut impl DebugRenderBackend,
+        bodies: &RigidBodySet,
+    ) {
         for (handle, rb) in bodies.iter() {
             let object = DebugRenderObject::RigidBody(handle, rb);
 
@@ -165,6 +186,7 @@ impl DebugRenderPipeline {
         }
     }
 
+    /// Render only the colliders from the scene.
     pub fn render_colliders(
         &mut self,
         backend: &mut impl DebugRenderBackend,
diff --git a/src/pipeline/debug_render_pipeline/debug_render_style.rs b/src/pipeline/debug_render_pipeline/debug_render_style.rs
index 5401596..0b6fa46 100644
--- a/src/pipeline/debug_render_pipeline/debug_render_style.rs
+++ b/src/pipeline/debug_render_pipeline/debug_render_style.rs
@@ -3,19 +3,38 @@
 /// The default colors are provided in HSLA (Hue Saturation Lightness Alpha) format.
 pub type DebugColor = [f32; 4];
 
+/// Style used for computing colors when rendering the scene.
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct DebugRenderStyle {
+    /// The number of subdivision used to approximate the curved
+    /// parts of a shape with smooth faces.
     pub subdivisions: u32,
+    /// The number of subdivision used to approimate the curved
+    /// borders of round shapes.
     pub border_subdivisions: u32,
+    /// The color of colliders attached to dynamic rigid-bodies.
     pub collider_dynamic_color: DebugColor,
+    /// The color of colliders attached to fixed rigid-bodies.
     pub collider_fixed_color: DebugColor,
+    /// The color of colliders attached to kinematic rigid-bodies.
     pub collider_kinematic_color: DebugColor,
+    /// The color of colliders not attached to any rigid-body.
     pub collider_parentless_color: DebugColor,
+    /// The color of the line between a rigid-body’s center-of-mass and the
+    /// anchors of its attached impulse joints.
     pub impulse_joint_anchor_color: DebugColor,
+    /// The color of the line between the two anchors of an impulse joint.
     pub impulse_joint_separation_color: DebugColor,
+    /// The color of the line between a rigid-body’s center-of-mass and the
+    /// anchors of its attached multibody joints.
     pub multibody_joint_anchor_color: DebugColor,
+    /// The color of the line between the two anchors of a multibody joint.
     pub multibody_joint_separation_color: DebugColor,
+    /// If a rigid-body is sleeping, its attached entities will have their colors
+    /// multiplied by this array. (For a joint, both attached rigid-bodies must be sleeping
+    /// or non-dynamic for this multiplier to be applied).
     pub sleep_color_multiplier: [f32; 4],
+    /// The length of the local coordinate axes rendered for a rigid-body.
     pub rigid_body_axes_length: f32,
 }