WIP some comments and considerations

src/lib/time/formats.hpp

@@ -84,7 +84,7 @@ namespace time {
         static void       rebuild (SmpteTC&, QuantR, TimeValue const&);
         static TimeValue evaluate (SmpteTC const&, QuantR);
         static uint  getFramerate (QuantR, TimeValue const&);
-        static void rangeLimitStrategy (SmpteTC&);
+        static void applyRangeLimitStrategy (SmpteTC&);
       };
     
     

src/lib/time/timecode.cpp

@@ -131,7 +131,7 @@ namespace time {
      *         orientation (0:0:0:0 - 1sec = -1:59:59:0)
      */
     void
-    Smpte::rangeLimitStrategy (SmpteTC& tc)
+    Smpte::applyRangeLimitStrategy (SmpteTC& tc)
     {
       if (tc.hours < 0)
         tc.invertOrientation();
@@ -171,7 +171,7 @@ namespace time {
     wrapHours   (SmpteTC* thisTC, int rawHours)
     {
       thisTC->hours.setValueRaw (rawHours);
-      format::Smpte::rangeLimitStrategy (*thisTC);
+      format::Smpte::applyRangeLimitStrategy (*thisTC);
     }
     
     

src/lib/time/timecode.hpp

@@ -101,7 +101,29 @@ namespace time {
   
   
   /**
+   * Classical Timecode value reminiscent to SMPTE format.
+   * After quantisation, the resulting (materialised) time value is
+   * decimated into a hours, a minutes, a seconds part and the remainder
+   * is cast into a frame number relative to the seconds. Consequently,
+   * a SmpteTC representation is always linked implicitly to a specific framerate.
    * 
+   * \par range extensions
+   * Historically, SMPTE timecode format was focused mainly on how to encode a
+   * unique timestamp in a way allowing to 'piggyback' these timestamps into an
+   * existing (analogue) media data format. As a side effect, quite tight limits
+   * had to be imposed on the possible component values in such a fixed-length format.
+   * This whole concern is completely beyond the scope of a typical computer based video
+   * implementation; thus we can consider ways to extend the value range to be represented
+   * in this SMPTE-like timecode format:
+   * - we can allow time values below the zero point
+   * - we can allow time values beyond 24 hours.
+   * Several different schemes how to do this extensions could be devised (and in addition,
+   * we could also wrap around the hours field, jumping from 23:59:59:## to 0:0:0:0).
+   * Currently, we implement an extension, where the timecode representation is symmetrical
+   * to the zero point and the hours field is just extended beyond 23 hours. To give an
+   * example: \c 0:0:0:0 minus 1 frame yields \c -0:0:0:1
+   * 
+   * @todo the range extension scheme could be a configurable strategy
    */
   class SmpteTC
     : public TCode
@@ -141,7 +163,7 @@ namespace time {
   
   
   /**
-   * 
+   * @warning missing implementation
    */
   class HmsTC
     : public TCode
@@ -166,7 +188,7 @@ namespace time {
   
   
   /**
-   * 
+   * @warning partially missing implementation
    */
   class Secs
     : public TCode

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

@@ -74,6 +74,9 @@ namespace test{
       checkTimecodeUsageCycle ()
         {
           UNIMPLEMENTED ("full usage cycle for a timecode value");
+          
+          /////////TODO: parse-funktion, wie?
+          /////////TODO: vieleicht doch irgendwo eine Funktion zum Materialisieren?
         }
       
       

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

@@ -216,7 +216,7 @@ namespace test{
           
           // Here accidentally both the change and t.quant use the same grid.
           // For a more contrived example, we try to use a different grid...
-          TimeGrid::build("special_funny_grid", 1);      // (1 frame per second, no offset)
+          TimeGrid::build("special_funny_grid", 1, Time(0,-10)); // (1 frame per second, zero point at -10s)
           QuTime funny (original, "special_funny_grid");
           funny.accept (Mutation::materialise (change));
           CHECK (funny == t.quant);                      // leading to the same raw value this far