[update] documentation across lambda-rs.

Author: vmarcella

crates/lambda-rs/src/events.rs

@@ -15,7 +15,7 @@ pub enum WindowEvent {
   Resize { width: u32, height: u32 },
 }
 
-/// Kernel events are generated by the kernel itself
+/// Runtime events are generated by the Runtimes themselves.
 #[derive(Debug, Clone)]
 pub enum RuntimeEvent {
   Initialized,
@@ -25,6 +25,8 @@ pub enum RuntimeEvent {
 /// Exports the winit virtual key codes to this namespace for convenience.
 pub use lambda_platform::winit::winit_exports::VirtualKeyCode as VirtualKey;
 
+/// Keyboard events are generated in response to keyboard events coming from
+/// the windowing system.
 #[derive(Debug, Clone)]
 pub enum Key {
   Pressed {
@@ -41,6 +43,7 @@ pub enum Key {
   },
 }
 
+/// Mouse buttons.
 #[derive(Debug, Clone)]
 pub enum Button {
   Left,
@@ -49,6 +52,8 @@ pub enum Button {
   Other(u16),
 }
 
+/// Mouse events are generated in response to mouse events coming from the
+/// windowing system. The coordinates are in logical pixels.
 #[derive(Debug, Clone)]
 pub enum Mouse {
   Moved {

crates/lambda-rs/src/lib.rs

@@ -1,3 +1,5 @@
+//! Lambda is a simple, fast, and safe compute engine written in Rust.
+
 pub mod component;
 pub mod components;
 pub mod events;

crates/lambda-rs/src/render/buffer.rs

@@ -1,3 +1,5 @@
+//! Buffers for allocating memory on the GPU.
+
 mod internal {
   // Placed these in an internal module to avoid a name collision with the
   // high level Buffer & BufferBuilder types in the parent module.
@@ -22,6 +24,7 @@ use super::{
   RenderContext,
 };
 
+/// Buffer for storing vertex data on the GPU.
 #[derive(Debug)]
 pub struct Buffer {
   buffer: Rc<internal::Buffer<super::internal::RenderBackend>>,

crates/lambda-rs/src/render/command.rs

@@ -1,3 +1,5 @@
+//! Render command definitions for lambda runtimes.
+
 use std::ops::Range;
 
 use lambda_platform::gfx::viewport::ViewPort as PlatformViewPort;
@@ -20,36 +22,35 @@ pub enum RenderCommand {
     start_at: u32,
     viewports: Vec<super::viewport::Viewport>,
   },
-  SetPipeline {
-    pipeline: super::ResourceId,
-  },
+  /// Sets the pipeline to use for the render context.
+  SetPipeline { pipeline: super::ResourceId },
   /// Begins the render pass.
   BeginRenderPass {
     render_pass: super::ResourceId,
     viewport: super::viewport::Viewport,
   },
   /// Ends the render pass.
   EndRenderPass,
+
+  /// Sets the push constants for the render pipeline.
   PushConstants {
     pipeline: super::ResourceId,
     stage: super::pipeline::PipelineStage,
     offset: u32,
     bytes: Vec<u32>,
   },
+  /// Binds a vertex buffer to the render pipeline.
   BindVertexBuffer {
     pipeline: super::ResourceId,
     buffer: u32,
   },
   /// Draws a graphical primitive.
-  Draw {
-    vertices: Range<u32>,
-  },
+  Draw { vertices: Range<u32> },
 }
 
 impl RenderCommand {
   /// Converts the RenderCommand into a platform compatible render command.
-  // TODO(vmarcella): implement this using Into<PlatformRenderCommand>
-  pub fn into_platform_command(
+  pub(super) fn into_platform_command(
     &self,
     render_context: &mut RenderContext,
   ) -> PlatformRenderCommand {

crates/lambda-rs/src/render/mesh.rs

@@ -1,3 +1,5 @@
+//! Mesh Implementation
+
 use lambda_platform::obj::load_textured_obj_from_file;
 
 use super::{
@@ -7,7 +9,6 @@ use super::{
     VertexElement,
   },
   ColorFormat,
-  RenderContext,
 };
 
 // ---------------------------------- Mesh ------------------------------------
@@ -20,10 +21,12 @@ pub struct Mesh {
 }
 
 impl Mesh {
+  /// Gets the vertices of the mesh.
   pub fn vertices(&self) -> &[Vertex] {
     &self.vertices
   }
 
+  /// Gets the attributes of the mesh.
   pub fn attributes(&self) -> &[VertexAttribute] {
     &self.attributes
   }
@@ -40,6 +43,7 @@ pub struct MeshBuilder {
 }
 
 impl MeshBuilder {
+  /// Creates a new mesh builder.
   pub fn new() -> Self {
     return Self {
       capacity: 0,
@@ -48,16 +52,29 @@ impl MeshBuilder {
     };
   }
 
+  /// Allocates memory for the given number of vertices and fills
+  /// the mesh with empty vertices.
   pub fn with_capacity(&mut self, size: usize) -> &mut Self {
     self.capacity = size;
+    self.vertices.resize(
+      size,
+      Vertex {
+        position: [0.0, 0.0, 0.0],
+        normal: [0.0, 0.0, 0.0],
+        color: [0.0, 0.0, 0.0],
+      },
+    );
     return self;
   }
 
+  /// Adds a vertex to the mesh.
   pub fn with_vertex(&mut self, vertex: Vertex) -> &mut Self {
     self.vertices.push(vertex);
     return self;
   }
 
+  /// Specify the attributes of the mesh. This is used to map the vertex data to
+  /// the input of the vertex shader.
   pub fn with_attributes(
     &mut self,
     attributes: Vec<VertexAttribute>,

crates/lambda-rs/src/render/mod.rs

@@ -38,21 +38,23 @@ use self::{
   render_pass::RenderPass,
 };
 
+/// A RenderContext is a localized rendering context that can be used to render
+/// to a window. It is localized to a single window at the moment.
 pub struct RenderContextBuilder {
   name: String,
   render_timeout: u64,
 }
 
 impl RenderContextBuilder {
-  /// Create a new localized RenderContext
+  /// Create a new localized RenderContext with the given name.
   pub fn new(name: &str) -> Self {
     return Self {
       name: name.to_string(),
       render_timeout: 1_000_000_000,
     };
   }
 
-  /// The time rendering has to complete before timing out.
+  /// The time rendering has to complete before a timeout occurs.
   pub fn with_render_timeout(mut self, render_timeout: u64) -> Self {
     self.render_timeout = render_timeout;
     return self;
@@ -69,7 +71,7 @@ impl RenderContextBuilder {
 
     let mut instance = internal::InstanceBuilder::new()
       .build::<internal::RenderBackend>(name.as_str());
-    let mut surface = Rc::new(
+    let surface = Rc::new(
       internal::SurfaceBuilder::new().build(&instance, window.window_handle()),
     );
 
@@ -90,10 +92,6 @@ impl RenderContextBuilder {
     let render_semaphore =
       internal::RenderSemaphoreBuilder::new().build(&mut gpu);
 
-    // Create the image extent and initial frame buffer attachment description
-    // for rendering.
-    let (width, height) = window.dimensions();
-
     return RenderContext {
       name,
       instance,
@@ -305,10 +303,14 @@ impl RenderContext {
     }
   }
 
+  /// Get the render pass with the resource ID that was provided upon
+  /// attachment.
   pub fn get_render_pass(&self, id: ResourceId) -> &RenderPass {
     return &self.render_passes[id];
   }
 
+  /// Get the render pipeline with the resource ID that was provided upon
+  /// attachment.
   pub fn get_render_pipeline(&mut self, id: ResourceId) -> &RenderPipeline {
     return &self.render_pipelines[id];
   }

crates/lambda-rs/src/render/pipeline.rs

@@ -1,15 +1,10 @@
-use std::{
-  borrow::Borrow,
-  ops::Deref,
-  rc::Rc,
-};
+//! Render pipeline builders and definitions for lambda runtimes and
+//! applications.
+use std::rc::Rc;
 
-use lambda_platform::gfx::{
-  buffer::Buffer as InternalBuffer,
-  shader::{
-    ShaderModuleBuilder,
-    ShaderModuleType,
-  },
+use lambda_platform::gfx::shader::{
+  ShaderModuleBuilder,
+  ShaderModuleType,
 };
 
 use super::{
@@ -69,6 +64,7 @@ pub struct RenderPipelineBuilder {
 }
 
 impl RenderPipelineBuilder {
+  /// Creates a new render pipeline builder.
   pub fn new() -> Self {
     return Self {
       push_constants: Vec::new(),
@@ -88,6 +84,8 @@ impl RenderPipelineBuilder {
     return self;
   }
 
+  /// Adds a push constant to the render pipeline at the given stage
+  /// with the given size in bytes.
   pub fn with_push_constant(
     mut self,
     stage: PipelineStage,

crates/lambda-rs/src/render/render_pass.rs

@@ -1,3 +1,4 @@
+//! Render pass builders and definitions for lambda runtimes and applications.
 use std::rc::Rc;
 
 use lambda_platform::gfx::render_pass;
@@ -38,6 +39,7 @@ impl RenderPass {
 pub struct RenderPassBuilder {}
 
 impl RenderPassBuilder {
+  /// Creates a new render pass builder.
   pub fn new() -> Self {
     return Self {};
   }

crates/lambda-rs/src/render/shader.rs

@@ -1,3 +1,5 @@
+//! A module for compiling shaders into SPIR-V binary.
+
 // Expose some lower level shader
 pub use lambda_platform::shaderc::{
   ShaderCompiler,
@@ -6,18 +8,6 @@ pub use lambda_platform::shaderc::{
   VirtualShader,
 };
 
-#[macro_export]
-macro_rules! vertex_shader {
-  ($source:ident) => {
-    VirtualShader::Source {
-      source: String::from($stringify!($source)),
-      kind: ShaderKind::Vertex,
-      name: String::from("vertex-shader"),
-      entry_point: String::from("main"),
-    }
-  };
-}
-
 pub struct ShaderBuilder {
   compiler: ShaderCompiler,
 }
@@ -41,12 +31,16 @@ impl ShaderBuilder {
   }
 }
 
+/// A shader that has been compiled into SPIR-V binary. Contains the binary
+/// representation of the shader as well as the virtual shader that was used
+/// to compile it.
 pub struct Shader {
   binary: Vec<u32>,
   virtual_shader: VirtualShader,
 }
 
 impl Shader {
+  /// Returns a copy of the SPIR-V binary representation of the shader.
   pub fn as_binary(&self) -> Vec<u32> {
     return self.binary.clone();
   }

crates/lambda-rs/src/render/vertex.rs

@@ -1,8 +1,11 @@
+//! Vertex data structures.
+
 pub use lambda_platform::gfx::assembler::{
   VertexAttribute,
   VertexElement,
 };
 
+/// Vertex data structure with position, normal, and color.
 #[repr(C)]
 #[derive(Clone, Copy, Debug)]
 pub struct Vertex {
@@ -20,6 +23,7 @@ pub struct VertexBuilder {
 }
 
 impl VertexBuilder {
+  /// Creates a new vertex builder.
   pub fn new() -> Self {
     return Self {
       position: [0.0, 0.0, 0.0],
@@ -40,11 +44,13 @@ impl VertexBuilder {
     return self;
   }
 
+  /// Set the color of the vertex.
   pub fn with_color(&mut self, color: [f32; 3]) -> &mut Self {
     self.color = color;
     return self;
   }
 
+  /// Build the vertex.
   pub fn build(&self) -> Vertex {
     return Vertex {
       position: self.position,