[update] component & runtime implementations to be Result driven, update package versions.

Author: vmarcella

Cargo.lock

@@ -1,7 +1,7 @@
 [package]
 name = "lambda-rs-platform"
 description = "Platform implementations for lambda-rs"
-version = "2023.1.28"
+version = "2023.1.29"
 edition = "2021"
 resolver = "2"
 license = "MIT"

crates/lambda-rs-platform/Cargo.toml

@@ -1,3 +1,5 @@
+//! Winit wrapper to easily construct cross platform windows
+
 use winit::{
   dpi::{
     LogicalSize,

crates/lambda-rs-platform/src/winit/mod.rs

@@ -1,7 +1,7 @@
 [package]
 name = "lambda-rs"
 description = "A framework for building cross platform graphics & compute applications."
-version = "2023.1.28"
+version = "2023.1.29"
 edition = "2021"
 license = "MIT"
 keywords = ["graphics", "compute"]

crates/lambda-rs/Cargo.toml

@@ -28,7 +28,11 @@ use lambda::{
     ResourceId,
   },
   runtime::start_runtime,
-  runtimes::ApplicationRuntimeBuilder,
+  runtimes::{
+    application::ComponentResult,
+    ApplicationRuntime,
+    ApplicationRuntimeBuilder,
+  },
 };
 use lambda_platform::{
   gfx::{
@@ -129,8 +133,11 @@ pub struct PushConstantsExample {
   height: u32,
 }
 
-impl Component for PushConstantsExample {
-  fn on_attach(&mut self, render_context: &mut lambda::render::RenderContext) {
+impl Component<ComponentResult, String> for PushConstantsExample {
+  fn on_attach(
+    &mut self,
+    render_context: &mut lambda::render::RenderContext,
+  ) -> Result<ComponentResult, String> {
     let render_pass = RenderPassBuilder::new().build(render_context);
     let push_constant_size = std::mem::size_of::<PushConstant>() as u32;
 
@@ -193,13 +200,22 @@ impl Component for PushConstantsExample {
     self.render_pass = Some(render_context.attach_render_pass(render_pass));
     self.render_pipeline = Some(render_context.attach_pipeline(pipeline));
     self.mesh = Some(mesh);
+
+    return Ok(ComponentResult::Success);
   }
 
-  fn on_detach(&mut self, render_context: &mut lambda::render::RenderContext) {
+  fn on_detach(
+    &mut self,
+    render_context: &mut lambda::render::RenderContext,
+  ) -> Result<ComponentResult, String> {
     println!("Detaching component");
+    return Ok(ComponentResult::Success);
   }
 
-  fn on_event(&mut self, event: lambda::events::Events) {
+  fn on_event(
+    &mut self,
+    event: lambda::events::Events,
+  ) -> Result<ComponentResult, String> {
     // Only handle resizes.
     match event {
       lambda::events::Events::Window { event, issued_at } => match event {
@@ -211,13 +227,18 @@ impl Component for PushConstantsExample {
         _ => {}
       },
       _ => {}
-    }
+    };
+    return Ok(ComponentResult::Success);
   }
 
   /// Update the frame number every frame.
-  fn on_update(&mut self, last_frame: &std::time::Duration) {
+  fn on_update(
+    &mut self,
+    last_frame: &std::time::Duration,
+  ) -> Result<ComponentResult, String> {
     self.last_frame = *last_frame;
     self.frame_number += 1;
+    return Ok(ComponentResult::Success);
   }
 
   fn on_render(

crates/lambda-rs/examples/push_constants.rs

@@ -20,7 +20,10 @@ use lambda::{
     RenderContext,
   },
   runtime::start_runtime,
-  runtimes::ApplicationRuntimeBuilder,
+  runtimes::{
+    application::ComponentResult,
+    ApplicationRuntimeBuilder,
+  },
 };
 
 pub struct DemoComponent {
@@ -32,8 +35,11 @@ pub struct DemoComponent {
   height: u32,
 }
 
-impl Component for DemoComponent {
-  fn on_attach(&mut self, render_context: &mut RenderContext) {
+impl Component<ComponentResult, String> for DemoComponent {
+  fn on_attach(
+    &mut self,
+    render_context: &mut RenderContext,
+  ) -> Result<ComponentResult, String> {
     println!("Attached the demo component to the renderer");
     let render_pass =
       render_pass::RenderPassBuilder::new().build(&render_context);
@@ -50,11 +56,20 @@ impl Component for DemoComponent {
     self.render_pipeline_id = Some(render_context.attach_pipeline(pipeline));
 
     println!("Attached the DemoComponent.");
+    return Ok(ComponentResult::Success);
   }
 
-  fn on_detach(self: &mut DemoComponent, render_context: &mut RenderContext) {}
+  fn on_detach(
+    self: &mut DemoComponent,
+    render_context: &mut RenderContext,
+  ) -> Result<ComponentResult, String> {
+    return Ok(ComponentResult::Success);
+  }
 
-  fn on_event(self: &mut DemoComponent, event: Events) {
+  fn on_event(
+    self: &mut DemoComponent,
+    event: Events,
+  ) -> Result<ComponentResult, String> {
     match event {
       Events::Runtime { event, issued_at } => match event {
         lambda::events::RuntimeEvent::Shutdown => {
@@ -101,16 +116,21 @@ impl Component for DemoComponent {
         }
       },
       _ => {}
-    }
+    };
+    return Ok(ComponentResult::Success);
   }
 
-  fn on_update(self: &mut DemoComponent, last_frame: &std::time::Duration) {
+  fn on_update(
+    self: &mut DemoComponent,
+    last_frame: &std::time::Duration,
+  ) -> Result<ComponentResult, String> {
     match last_frame.as_millis() > 20 {
       true => {
         println!("[WARN] Last frame took {}ms", last_frame.as_millis());
       }
       false => {}
-    }
+    };
+    return Ok(ComponentResult::Success);
   }
   fn on_render(
     self: &mut DemoComponent,

crates/lambda-rs/examples/triangle.rs

@@ -23,7 +23,10 @@ use lambda::{
     RenderContext,
   },
   runtime::start_runtime,
-  runtimes::ApplicationRuntimeBuilder,
+  runtimes::{
+    application::ComponentResult,
+    ApplicationRuntimeBuilder,
+  },
 };
 
 pub struct TrianglesComponent {
@@ -37,8 +40,11 @@ pub struct TrianglesComponent {
   position: (f32, f32),
 }
 
-impl Component for TrianglesComponent {
-  fn on_attach(&mut self, render_context: &mut RenderContext) {
+impl Component<ComponentResult, String> for TrianglesComponent {
+  fn on_attach(
+    &mut self,
+    render_context: &mut RenderContext,
+  ) -> Result<ComponentResult, String> {
     let render_pass =
       render_pass::RenderPassBuilder::new().build(&render_context);
 
@@ -56,9 +62,15 @@ impl Component for TrianglesComponent {
     self.render_pipeline = Some(render_context.attach_pipeline(pipeline));
 
     println!("Attached the DemoComponent.");
+    return Ok(ComponentResult::Success);
   }
 
-  fn on_detach(&mut self, _render_context: &mut RenderContext) {}
+  fn on_detach(
+    &mut self,
+    _render_context: &mut RenderContext,
+  ) -> Result<ComponentResult, String> {
+    return Ok(ComponentResult::Success);
+  }
 
   fn on_render(
     &mut self,
@@ -139,7 +151,7 @@ impl Component for TrianglesComponent {
     return commands;
   }
 
-  fn on_event(&mut self, event: Events) {
+  fn on_event(&mut self, event: Events) -> Result<ComponentResult, String> {
     match event {
       Events::Runtime { event, issued_at } => match event {
         lambda::events::RuntimeEvent::Shutdown => {
@@ -180,16 +192,21 @@ impl Component for TrianglesComponent {
         _ => {}
       },
       _ => {}
-    }
+    };
+    return Ok(ComponentResult::Success);
   }
 
-  fn on_update(&mut self, last_frame: &std::time::Duration) {
+  fn on_update(
+    &mut self,
+    last_frame: &std::time::Duration,
+  ) -> Result<ComponentResult, String> {
     match last_frame.as_millis() > 20 {
       true => {
         println!("[WARN] Last frame took {}ms", last_frame.as_millis());
       }
       false => {}
-    }
+    };
+    return Ok(ComponentResult::Success);
   }
 }
 

crates/lambda-rs/examples/triangles.rs

@@ -1,4 +1,7 @@
-use std::time::Duration;
+use std::{
+  fmt::Debug,
+  time::Duration,
+};
 
 use crate::{
   events::Events,
@@ -11,15 +14,29 @@ use crate::{
 /// The Component Interface for allowing Component based data structures
 /// like the ComponentStack to store components with various purposes
 /// and implementations to work together.
-pub trait Component {
-  fn on_attach(&mut self, render_context: &mut RenderContext);
-  fn on_detach(&mut self, render_context: &mut RenderContext);
-  fn on_event(&mut self, event: Events);
+pub trait Component<R, E>
+where
+  R: Sized + Debug,
+  E: Sized + Debug,
+{
+  /// The attach function is called when the component is added to the
+  /// component data storage a runtime is using.
+  fn on_attach(&mut self, render_context: &mut RenderContext) -> Result<R, E>;
+
+  /// The detach function is called when the component is removed from the
+  /// component data storage a runtime is using.
+  fn on_detach(&mut self, render_context: &mut RenderContext) -> Result<R, E>;
+
+  /// The event function is called every time an event is received from
+  /// the windowing system/event loop.
+  fn on_event(&mut self, event: Events) -> Result<R, E>;
 
   /// The update function is called every frame and is used to update
   /// the state of the component.
-  fn on_update(&mut self, last_frame: &Duration);
+  fn on_update(&mut self, last_frame: &Duration) -> Result<R, E>;
 
+  /// Render commands returned from this function will be executed
+  /// by the renderer immediately.
   fn on_render(
     &mut self,
     render_context: &mut RenderContext,

crates/lambda-rs/src/component.rs

@@ -1,3 +1,5 @@
+//! Event definitions for lambda runtimes and applications.
+
 use std::time::Instant;
 
 /// events generated by kernel interactions with the component.
@@ -20,6 +22,7 @@ pub enum WindowEvent {
 pub enum RuntimeEvent {
   Initialized,
   Shutdown,
+  ComponentPanic { message: String },
 }
 
 /// Exports the winit virtual key codes to this namespace for convenience.
@@ -29,14 +32,17 @@ pub use lambda_platform::winit::winit_exports::VirtualKeyCode as VirtualKey;
 /// the windowing system.
 #[derive(Debug, Clone)]
 pub enum Key {
+  /// Emitted when a key is pressed.
   Pressed {
     scan_code: u32,
     virtual_key: Option<VirtualKey>,
   },
+  /// Emitted when a key is released.
   Released {
     scan_code: u32,
     virtual_key: Option<VirtualKey>,
   },
+  /// Emitted when a modifier key is pressed.
   ModifierPressed {
     modifier: u32,
     virtual_key: VirtualKey,
@@ -56,34 +62,34 @@ pub enum Button {
 /// windowing system. The coordinates are in logical pixels.
 #[derive(Debug, Clone)]
 pub enum Mouse {
+  /// Emitted when the mouse cursor is moved within the window.
   Moved {
     x: f64,
     y: f64,
     dx: f64,
     dy: f64,
     device_id: u32,
   },
-  Scrolled {
-    device_id: u32,
-  },
+  /// Emitted when the mouse wheel is scrolled.
+  Scrolled { device_id: u32 },
+  /// Emitted when a mouse button is pressed.
   Pressed {
     x: f64,
     y: f64,
     button: Button,
     device_id: u32,
   },
+  /// Emitted when a mouse button is released.
   Released {
     x: f64,
     y: f64,
     button: Button,
     device_id: u32,
   },
-  LeftWindow {
-    device_id: u32,
-  },
-  EnteredWindow {
-    device_id: u32,
-  },
+  /// Emitted when the mouse cursor leaves the window.
+  LeftWindow { device_id: u32 },
+  /// Emitted when the mouse cursor enters the window.
+  EnteredWindow { device_id: u32 },
 }
 
 /// Generic Event Enum which encapsulates all possible events that will be

crates/lambda-rs/src/events.rs

@@ -9,6 +9,9 @@ use super::{
 
 // -------------------------------- MATRIX -------------------------------------
 
+/// Matrix trait which defines the basic operations that can be performed on a
+/// matrix. Lambda currently implements this trait for f32 arrays of arrays
+/// for any size.
 pub trait Matrix<V: Vector> {
   fn add(&self, other: &Self) -> Self;
   fn subtract(&self, other: &Self) -> Self;