From 65b7c50c265825266061619660769ac6eea2542d Mon Sep 17 00:00:00 2001
From: mitchmindtree <mitchell.nordine@gmail.com>
Date: Wed, 24 Apr 2019 17:23:47 +1000
Subject: [PATCH] Allow for processing raw points of frame stream

This allows specifying a function that can be called for processing the
raw points of the frame stream that are output from the optimisation and
interpolation pass. See the docs for the new method for possible
use-cases and further details.
---
 src/lib.rs              | 11 ++++++++++-
 src/stream/frame/mod.rs | 39 ++++++++++++++++++++++++++++++++++++---
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 05a5b9f75..de11fdede 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -89,7 +89,16 @@ impl Lasy {
         let builder = Default::default();
         let frame_hz = None;
         let interpolation_conf = Default::default();
-        stream::frame::Builder { api_inner, builder, model, render, frame_hz, interpolation_conf }
+        let process_raw = stream::frame::default_process_raw_fn;
+        stream::frame::Builder {
+            api_inner,
+            builder,
+            model,
+            render,
+            process_raw,
+            frame_hz,
+            interpolation_conf,
+        }
     }
 
     /// Begin building a new laser raw stream.
diff --git a/src/stream/frame/mod.rs b/src/stream/frame/mod.rs
index 8959bb627..49d0cbf62 100644
--- a/src/stream/frame/mod.rs
+++ b/src/stream/frame/mod.rs
@@ -47,13 +47,17 @@ struct Requester {
     raw_points: Vec<RawPoint>,
 }
 
+// The type of the default function used for the `process_raw` function if none is specified.
+type DefaultProcessRawFn<M> = fn(&mut M, &mut Buffer);
+
 /// A type allowing to build a raw laser stream.
-pub struct Builder<M, F> {
+pub struct Builder<M, F, R = DefaultProcessRawFn<M>> {
     /// The laser API inner state, used to find a DAC during `build` if one isn't specified.
     pub(crate) api_inner: Arc<crate::Inner>,
     pub builder: stream::Builder,
     pub model: M,
     pub render: F,
+    pub process_raw: R,
     pub frame_hz: Option<u32>,
     pub interpolation_conf: opt::InterpolationConfigBuilder,
 }
@@ -114,7 +118,7 @@ impl<M> Stream<M> {
     }
 }
 
-impl<M, F> Builder<M, F> {
+impl<M, F, R> Builder<M, F, R> {
     /// The DAC with which the stream should be established.
     pub fn detected_dac(mut self, dac: crate::DetectedDac) -> Self {
         self.builder.dac = Some(dac);
@@ -177,6 +181,21 @@ impl<M, F> Builder<M, F> {
         self
     }
 
+    /// Specify a function that allows for processing the raw points before submission to the DAC.
+    ///
+    /// This mgiht be useful for:
+    ///
+    /// - applying post-processing effects onto the optimised, interpolated points.
+    /// - monitoring the raw points resulting from the optimisation and interpolation processes.
+    /// - tuning brightness of colours based on safety zones.
+    ///
+    /// The given function will get called right before submission of the optimised, interpolated
+    /// buffer.
+    pub fn process_raw<R2>(self, process_raw: R2) -> Builder<M, F, R2> {
+        let Builder { api_inner, builder, model, render, frame_hz, interpolation_conf, .. } = self;
+        Builder { api_inner, builder, model, render, process_raw, frame_hz, interpolation_conf }
+    }
+
     /// Build the stream with the specified parameters.
     ///
     /// **Note:** If no `dac` was specified, this will method will block until a DAC is detected.
@@ -185,8 +204,17 @@ impl<M, F> Builder<M, F> {
     where
         M: 'static + Send,
         F: 'static + RenderFn<M> + Send,
+        R: 'static + raw::RenderFn<M> + Send,
     {
-        let Builder { api_inner, builder, model, render, frame_hz, interpolation_conf } = self;
+        let Builder {
+            api_inner,
+            builder,
+            model,
+            render,
+            process_raw,
+            frame_hz,
+            interpolation_conf,
+        } = self;
 
         // Retrieve the interpolation configuration.
         let interpolation_conf = interpolation_conf.build();
@@ -217,6 +245,7 @@ impl<M, F> Builder<M, F> {
 
             let mut guard = requester.lock().expect("failed to lock frame requester");
             guard.fill_buffer(model, &render, buffer, &state);
+            process_raw(model, buffer);
         };
 
         // Create the raw builder and build the raw stream.
@@ -456,3 +485,7 @@ impl<M> Deref for Stream<M> {
         &self.raw
     }
 }
+
+// The default function used for the `process_raw` function if none is specified.
+pub(crate) fn default_process_raw_fn<M>(_model: &mut M, _buffer: &mut Buffer) {
+}