establish hidden advice link to the session

src/lib/time/quantiser.cpp

@@ -25,6 +25,7 @@
 #include "lib/time/timevalue.hpp"
 #include "lib/time/timequant.hpp"
 #include "lib/time.h"
+#include "lib/advice.hpp"
 
 #include <boost/rational.hpp>
 
@@ -40,7 +41,16 @@ namespace time {
   
   namespace { // implementation helpers...
     
-    ///////////TODO superfluous??
+    PQuant
+    retrieveQuantiser (Symbol gridID)
+    {
+      advice::Request<PQuant> query(gridID);
+      PQuant grid_found = query.getAdvice();
+      if (!grid_found)
+        throw error::Logic ("unable to fetch the quantisation grid -- is it already defined?"
+                           , LUMIERA_ERROR_UNKNOWN_GRID);
+      return grid_found;
+    }
     
   }//(End) implementation helpers
   
@@ -49,13 +59,25 @@ namespace time {
   Grid::~Grid() { } // hint to emit the VTable here...
   
   
-  /** */
+  /** 
+   * build a quantised time value, referring the time grid by-name.
+   * This is the preferred standard way of establishing a quantisation,
+   * but it requires an existing time scale defined in the Lumiera Session,
+   * as TimeGrid (meta asset). Usually, such a time scale gets built based
+   * on the format and parameters of an output bus.
+   */
   QuTime::QuTime (TimeValue raw, Symbol gridID)
-    : Time(raw)          /////////////////////////////////////////////////TODO fetch quantiser
+    : Time(raw)
+    , quantiser_(retrieveQuantiser (gridID))
     { }
   
   
-  /** */
+  /**
+   * build a quantised time value by explicitly specifying a
+   * grid alignment facility and without any hidden reference
+   * to the Lumiera session. This is mainly intended for
+   * debugging and unit testing.
+   */
   QuTime::QuTime (TimeValue raw, PQuant quantisation_to_use)
     : Time(raw)
     , quantiser_(quantisation_to_use)

src/lib/time/quantiser.hpp

@@ -106,13 +106,13 @@ namespace time {
   
   
   /**
-   * Simple stand-alone Quantiser implementation for debugging and test.
-   * This is a self-contained quantiser implementation without any implicit
-   * referral to the Lumiera session. It is mainly intended for simplified unit testing.
-   * @warning real GUI and Proc-Layer code should always prefer to build a real quantiser,
-   * which referres some TimeGrid definition within the session. Basically, the overall
-   * purpose of the time-quantisation framework is to enforce such a link to a specific
-   * time and quantisation scale and to prevent "wild and uncoordinated" rounding attempts.
+   * Simple stand-alone Quantiser implementation based on a constant sized gird.
+   * This is a self-contained quantiser implementation without any implicit referral
+   * to the Lumiera session. As such it is suited for simplified unit testing.
+   * @warning real GUI and Proc-Layer code should always fetch a quantiser from the
+   * Session, referring to a pre defined TimeGrid. Basically, the overall purpose of
+   * the time-quantisation framework is to enforce such a link to a distinct time scale
+   * and quantisation, so to prevent "wild and uncoordinated" rounding attempts.
    */
   class FixedFrameQuantiser
     : public Quantiser

src/lib/time/timequant.hpp

@@ -40,9 +40,19 @@ namespace time {
   
   
   /**
-   * fixed format time specification.
+   * grid aligned time specification, referring to a specific scale.
+   * A quantised time value allows to access the time specification
+   * as numeric value in one of the supported timecode formats, and
+   * relative to the defined time scale. Usually this time scale
+   * exists already in the Lumiera session and is referred simply
+   * by symbolic ID, it will be fetched on demand through the
+   * \link advice.hpp advice system.\endlink
    * 
-   * @todo WIP-WIP-WIP
+   * By creating a QuTime value, the relation to such a predefined
+   * time scale is made explicit. This doesn't change the internal
+   * time value, but the actual creation of a timecode formatted
+   * value (#formatAs) usually implies to quantise or grid align
+   * the time to the frame grid specific to this time scale.  
    */
   class QuTime
     : public Time

tests/lib/time/time-quantisation-test.cpp

@@ -140,13 +140,12 @@ namespace test{
       void
       checkGridLateBinding (TimeValue org)
         {
-          QuTime funny (org, "special_funny_grid");      // refer a not yet existing grid
-          CHECK (org == funny);                          // no problem, unless we request quantisation
-          
-          VERIFY_ERROR (UNKNOWN_GRID, funny.formatAs<format::Frames>() );
+          // refer to a grid not yet defined
+          VERIFY_ERROR (UNKNOWN_GRID, QuTime wired(org, "special_funny_grid"));
           
           TimeGrid::build("special_funny_grid", 1);      // provide the grid's definition (1 frame per second)
           
+          QuTime funny (org, "special_funny_grid");      // now OK, grid is known
           int cnt = funny.formatAs<format::Frames>();
                                                          // and now performing quantisation is OK 
           SmpteTC smpte (funny);                         // also converting into SMPTE (which implies frame quantisation)