diff --git a/doc/devel/uml/fig142725.png b/doc/devel/uml/fig142725.png new file mode 100644 index 000000000..e69ceab0e Binary files /dev/null and b/doc/devel/uml/fig142725.png differ diff --git a/src/lib/Makefile.am b/src/lib/Makefile.am index 9837f7da3..a00b4bdc2 100644 --- a/src/lib/Makefile.am +++ b/src/lib/Makefile.am @@ -44,7 +44,6 @@ liblumiera_la_SOURCES = \ $(liblumiera_la_srcdir)/lockerror.c \ $(liblumiera_la_srcdir)/logging.cpp \ $(liblumiera_la_srcdir)/luid.c \ - $(liblumiera_la_srcdir)/lumitime.cpp \ $(liblumiera_la_srcdir)/mpool.c \ $(liblumiera_la_srcdir)/mrucache.c \ $(liblumiera_la_srcdir)/mutex.c \ @@ -61,6 +60,8 @@ liblumiera_la_SOURCES = \ $(liblumiera_la_srcdir)/test/test-helper.cpp \ $(liblumiera_la_srcdir)/test/testoption.cpp \ $(liblumiera_la_srcdir)/time.c \ + $(liblumiera_la_srcdir)/time/lumitime.cpp \ + $(liblumiera_la_srcdir)/time/quantiser.cpp \ $(liblumiera_la_srcdir)/tmpbuf.c \ $(liblumiera_la_srcdir)/util.cpp diff --git a/src/lib/lumitime.hpp b/src/lib/lumitime.hpp index 5fe942218..88c6a1764 100644 --- a/src/lib/lumitime.hpp +++ b/src/lib/lumitime.hpp @@ -36,27 +36,15 @@ namespace lumiera { /** - * C++ convenience wrapper representing a time value, which could denote - * a temporal position (time point) relative to an (implicit) timeline zero - * point, or it could represent a time interval. + * Lumiera's internal time data. + * Time denotes a time point, specified as opaque value on an + * quasi continuous ("sufficiently precise") internal time scale, relative + * to an (implicit) timeline zero point. The actual implementation relies + * on gavl_time_t (long) values. * - * This wrapper is deliberately kept rather limited as not to be completely - * interchangeable with and integral type. The rationale is that time values - * should be kept separate and tagged as time values. The following is supported: - * - conversions from / to gavl_time_t (which is effectively a int64_t) - * - additions and subtractions of time values - * - multiplication with an integral factor - * - comparisons between time values and gavl_time_t values + * @see lib::time::TimeVar for an number-like time value usable for calculations * - * @todo consider the possible extensions - * - parsing and pretty printing - * - quantising of floating point values - * - conversion to boost::rational - * - define a Framerate type - * - * @note this is currently (10/08) an experimental implementation to ease - * the time handling within C++ code. It is advisable not to use it - * on external interfaces (use gavl_time_t there please). + * @todo it is not clear to which degree Time is mutable... */ class Time : boost::additive::max() ); - + Time::Time ( long millis , uint secs , uint mins @@ -47,7 +49,7 @@ namespace lumiera { ) : t_(lumiera_build_time (millis,secs,mins,hours)) { } - + int Time::getMillis() const { @@ -81,7 +83,7 @@ namespace lumiera { // TODO return 0; } - + Time::operator string() const { diff --git a/src/lib/time/quantiser.cpp b/src/lib/time/quantiser.cpp new file mode 100644 index 000000000..48b24979c --- /dev/null +++ b/src/lib/time/quantiser.cpp @@ -0,0 +1,39 @@ +/* + Quantiser - aligning time values to a time grid + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/lumitime.hpp" +#include "lib/time/timevalue.hpp" + +using std::string; + + +namespace lib { +namespace time { + + + /** */ + + + +}} // lib::time + diff --git a/src/lib/time/quantiser.hpp b/src/lib/time/quantiser.hpp new file mode 100644 index 000000000..b511ed53f --- /dev/null +++ b/src/lib/time/quantiser.hpp @@ -0,0 +1,49 @@ +/* + QUANTISER.hpp - aligning time values to a time grid + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + + +#ifndef LIB_TIME_QUANTISER_H +#define LIB_TIME_QUANTISER_H + +//#include +#include + + +namespace lib { +namespace time { + + + /** + * Facility to create grid-aligned time values. + * + * @todo WIP-WIP-WIP + */ + class Quantiser + { + + public: + }; + + + +}} // lib::time +#endif diff --git a/src/lib/time/timecode.hpp b/src/lib/time/timecode.hpp new file mode 100644 index 000000000..2a8ef6750 --- /dev/null +++ b/src/lib/time/timecode.hpp @@ -0,0 +1,49 @@ +/* + TIMECODE.hpp - grid aligned and fixed format time specifications + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + + +#ifndef LIB_TIME_TIMECODE_H +#define LIB_TIME_TIMECODE_H + +//#include +#include + + +namespace lib { +namespace time { + + + /** + * fixed format time specification. + * + * @todo WIP-WIP-WIP + */ + class TCode + { + + public: + }; + + + +}} // lib::time +#endif diff --git a/src/lib/time/timevalue.hpp b/src/lib/time/timevalue.hpp new file mode 100644 index 000000000..6f4eb0427 --- /dev/null +++ b/src/lib/time/timevalue.hpp @@ -0,0 +1,160 @@ +/* + TIMEVALUE.hpp - basic definitions for time values and time intervals + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + + +#ifndef LIB_TIME_TIMEVALUE_H +#define LIB_TIME_TIMEVALUE_H + +#include +#include + +extern "C" { +#include +#include +} + + +namespace lib { +namespace time { + + + /** + * fixed format time specification. + * + * @todo WIP-WIP-WIP + */ + class TimeValue + : boost::totally_ordered > + { + gavl_time_t t_; + + public: + static const Time MAX ; + static const Time MIN ; + + explicit + TimeValue (gavl_time_t val=0) + : t_(val) + { } + + // using standard copy operations + + operator gavl_time_t () const { return t_; } + + // Supporting totally_ordered + friend bool operator< (Time const& t1, Time const& t2) { return t1.t_ < t2.t_; } + friend bool operator< (Time const& t1, gavl_time_t t2) { return t1.t_ < t2 ; } + friend bool operator> (Time const& t1, gavl_time_t t2) { return t1.t_ > t2 ; } + friend bool operator== (Time const& t1, Time const& t2) { return t1.t_ == t2.t_; } + friend bool operator== (Time const& t1, gavl_time_t t2) { return t1.t_ == t2 ; } + }; + + + class TimeVar + : public TimeValue + , boost::additive + { + + public: + TimeVar (TimeValue time) + : TimeValue(time) + { } + + + // Supporting additive + TimeVar& operator+= (TimeVar const& tx) { t_ += tx.t_; return *this; } + TimeVar& operator-= (TimeVar const& tx) { t_ -= tx.t_; return *this; } + + // Supporting multiplication with integral factor + TimeVar& operator*= (int64_t fact) { t_ *= fact; return *this; } + + // baseclass TimeValue is already totally_ordered + }; + + + class Offset; + + /** + * Lumiera's internal time value datatype + */ + class Time + : public TimeValue + { + public: + explicit + Time (TimeValue val=0) + : TimeValue(val) + { } + + Time ( long millis + , uint secs + , uint mins =0 + , uint hours=0 + ); + }; + + + class Offset + : public TimeValue + { + + public: + explicit + Offset (TimeValue distance) + : TimeValue(distance) + { } + }; + + inline Offset + operator- (Time const& end, Time const& start) + { + TimeVar distance(end); + distance -= start; + return Offset(distance); + } + + typedef const Offset TimeDistance; + + + class Duration + : public TimeValue + { + // always positive + }; + + + class TimeSpan + : public Time + { + Duration dur_; + + public: + TimeSpan(Time start, Duration length) + : Time(start) + , dur_(length) + { } + }; + + +}} // lib::time +#endif diff --git a/tests/40components.tests b/tests/40components.tests index ae1d5da0a..078556126 100644 --- a/tests/40components.tests +++ b/tests/40components.tests @@ -627,12 +627,27 @@ return: 0 END -TEST "Time Wrapper" TimeWrapper_test < @@ -47,7 +47,7 @@ namespace test { /******************************************** * @test sanity of the C++ time wrapper. */ - class TimeWrapper_test : public Test + class LumiTime_test : public Test { virtual void run (Arg arg) @@ -166,7 +166,7 @@ namespace test { /** Register this test class... */ - LAUNCHER (TimeWrapper_test, "unit common"); + LAUNCHER (LumiTime_test, "unit common"); diff --git a/tests/lib/time/time-formats-test.cpp b/tests/lib/time/time-formats-test.cpp new file mode 100644 index 000000000..5a60473ae --- /dev/null +++ b/tests/lib/time/time-formats-test.cpp @@ -0,0 +1,90 @@ +/* + TimeFormats(Test) - timecode handling and formatting + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +#include "lib/time/timecode.hpp" +#include "lib/util.hpp" + +//#include +//#include +//#include + +//using boost::lexical_cast; +//using util::isnil; +//using std::rand; +//using std::cout; +//using std::endl; + + +namespace lib { +namespace time{ +namespace test{ + + + /******************************************************** + * @test verify handling of grid aligned timecode values. + * - creating timecode values + * - some conversions + * - formatting + */ + class TimeFormats_test : public Test + { + virtual void + run (Arg arg) + { + long refval= isnil(arg)? 1 : lexical_cast (arg[1]); + + Time ref (refval); + + checkBasics (ref); + checkComparisons (ref); + checkComponentAccess(); + } + + + void + checkBasics (Time const& ref) + { + } + + + void + checkComparisons (Time const& ref) + { + } + + + void + checkComponentAccess() + { + } + + }; + + + /** Register this test class... */ + LAUNCHER (TimeFormats_test, "unit common"); + + + +}}} // namespace lib::time::test diff --git a/tests/lib/time/time-quantisation-test.cpp b/tests/lib/time/time-quantisation-test.cpp new file mode 100644 index 000000000..5e6660e2d --- /dev/null +++ b/tests/lib/time/time-quantisation-test.cpp @@ -0,0 +1,90 @@ +/* + TimeQuantisation(Test) - handling of virtually grid aligned time values + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +#include "lib/time/quantiser.hpp" +#include "lib/util.hpp" + +//#include +//#include +//#include + +//using boost::lexical_cast; +//using util::isnil; +//using std::rand; +//using std::cout; +//using std::endl; + + +namespace lib { +namespace time{ +namespace test{ + + + /******************************************************** + * @test verify handling of time values, time intervals. + * - creating times and time intervals + * - comparisons + * - time arithmetics + */ + class TimeQuantisation_test : public Test + { + virtual void + run (Arg arg) + { + long refval= isnil(arg)? 1 : lexical_cast (arg[1]); + + Time ref (refval); + + checkBasics (ref); + checkComparisons (ref); + checkComponentAccess(); + } + + + void + checkBasics (Time const& ref) + { + } + + + void + checkComparisons (Time const& ref) + { + } + + + void + checkComponentAccess() + { + } + + }; + + + /** Register this test class... */ + LAUNCHER (TimeQuantisation_test, "unit common"); + + + +}}} // namespace lib::time::test diff --git a/tests/lib/time/time-value-test.cpp b/tests/lib/time/time-value-test.cpp new file mode 100644 index 000000000..b40ca5189 --- /dev/null +++ b/tests/lib/time/time-value-test.cpp @@ -0,0 +1,90 @@ +/* + TimeValue(Test) - working with time values and time intervals in C++... + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +#include "lib/time/timevalue.hpp" +#include "lib/util.hpp" + +//#include +//#include +//#include + +//using boost::lexical_cast; +//using util::isnil; +//using std::rand; +//using std::cout; +//using std::endl; + + +namespace lib { +namespace time{ +namespace test{ + + + /******************************************************** + * @test verify handling of time values, time intervals. + * - creating times and time intervals + * - comparisons + * - time arithmetics + */ + class TimeValue_test : public Test + { + virtual void + run (Arg arg) + { + long refval= isnil(arg)? 1 : lexical_cast (arg[1]); + + Time ref (refval); + + checkBasics (ref); + checkComparisons (ref); + checkComponentAccess(); + } + + + void + checkBasics (Time const& ref) + { + } + + + void + checkComparisons (Time const& ref) + { + } + + + void + checkComponentAccess() + { + } + + }; + + + /** Register this test class... */ + LAUNCHER (TimeValue_test, "unit common"); + + + +}}} // namespace lib::time::test diff --git a/uml/lumiera/128517 b/uml/lumiera/128517 index 1adaeed67..eef0810c5 100644 --- a/uml/lumiera/128517 +++ b/uml/lumiera/128517 @@ -1,6 +1,6 @@ format 58 "CommonLib" // CommonLib - revision 20 + revision 22 modified_by 5 "hiv" // class settings //class diagram settings @@ -811,6 +811,380 @@ ${items}}; end end + classview 135685 "Time Handling" + //class diagram settings + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + //collaboration diagram settings + show_full_operations_definition default show_hierarchical_rank default write_horizontally default drawing_language default package_name_in_tab default show_context default draw_all_relations default shadow default show_stereotype_properties default + //object diagram settings + write_horizontally default package_name_in_tab default show_context default auto_label_position default draw_all_relations default shadow default show_stereotype_properties default + //sequence diagram settings + show_full_operations_definition default write_horizontally default class_drawing_mode default drawing_language default draw_all_relations default shadow default show_stereotype_properties default + //state diagram settings + package_name_in_tab default show_context default auto_label_position default write_trans_label_horizontally default show_trans_definition default draw_all_relations default shadow default + show_activities default region_horizontally default drawing_language default show_stereotype_properties default + //class settings + //activity diagram settings + package_name_in_tab default show_context default show_opaque_action_definition default auto_label_position default write_flow_label_horizontally default draw_all_relations default shadow default + show_infonote default drawing_language default show_stereotype_properties default + classdiagram 142725 "Time flavours" + draw_all_relations no hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + size A4 + end + + class 134917 "Time" + visibility public + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + comment "denotes a temporal position (time point) in continuous time. +This implies a time origin (point of reference), which is kept implicit and depends on the context. +" + classrelation 206085 // + relation 195205 ---|> + a public + cpp default "${type}" + classrelation_ref 206085 // + b parent class_ref 168709 // TimeValue + end + end + + class 168581 "TimeSpan" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 206341 // + relation 195461 ---|> + a public + cpp default "${type}" + classrelation_ref 206341 // + b parent class_ref 168837 // Duration + end + + classrelation 206469 // start () + relation 195589 ---> + a role_name "start" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 206469 // start () + b parent class_ref 134917 // Time + end + end + + class 168709 "TimeValue" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + end + + class 168837 "Duration" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 206213 // + relation 195333 ---|> + a public + cpp default "${type}" + classrelation_ref 206213 // + b parent class_ref 168709 // TimeValue + end + end + + class 168965 "QuTime" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 206853 // + relation 195973 ---> + stereotype "refers_to" + a role_name "" multiplicity "1" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 206853 // + b multiplicity "*" parent class_ref 169093 // Quantiser + end + + classrelation 208133 // + relation 197253 ---|> + a public + cpp default "${type}" + classrelation_ref 208133 // + b parent class_ref 134917 // Time + end + + classrelation 208901 // + relation 198021 ---> + stereotype "yield" + a role_name "" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 208901 // + b parent class_ref 170629 // TCode + end + end + + class 169093 "Quantiser" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 206981 // + relation 196101 ---> + stereotype "use" + a role_name "" multiplicity "1" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 206981 // + b parent class_ref 169221 // TimeGrid + end + + classrelation 209029 // + relation 198149 o--> + stereotype "provide" + a role_name "" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 209029 // + b parent class_ref 170757 // Format + end + end + + class 169221 "TimeGrid" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + attribute 134277 "origin" + protected type class_ref 134917 // Time + multiplicity "1" + cpp_decl " ${comment}${static}${mutable}${volatile}${const}${type} ${name}${value}; +" + java_decl "" + php_decl "" + python_decl "" + idl_decl "" + end + + attribute 134405 "scale" + protected type class_ref 168837 // Duration + cpp_decl " ${comment}${static}${mutable}${volatile}${const}${type} ${name}${value}; +" + java_decl "" + php_decl "" + python_decl "" + idl_decl "" + end + end + + class 170373 "TimeVar" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 208261 // + relation 197381 ---|> + a public + cpp default "${type}" + classrelation_ref 208261 // + b parent class_ref 168709 // TimeValue + end + + classrelation 208389 // val () + relation 197509 ---> + a role_name "val" multiplicity "1" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 208389 // val () + b multiplicity "*" parent class_ref 134917 // Time + end + end + + class 170501 "QuTimeSpan" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 208517 // + relation 197637 ---|> + a public + cpp default "${type}" + classrelation_ref 208517 // + b parent class_ref 168581 // TimeSpan + end + end + + class 170629 "TCode" + visibility package + nformals 1 + formal name "F" type "class" explicit_default_value "" + explicit_extends "" + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 208645 // + relation 197765 -_-> + a default + cpp default "#include in source" + classrelation_ref 208645 // + b parent class_ref 170629 // TCode + end + + classrelation 208773 // + relation 197893 -_-> + a default + cpp default "#include in source" + classrelation_ref 208773 // + b parent class_ref 170757 // Format + end + end + + class 170757 "Format" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + end + + class 170885 "FrameNr" + visibility package + nactuals 1 + actual class class_ref 170629 // TCode + rank 0 explicit_value "" + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 209157 // + relation 198277 ---|> + a public + cpp default "${type}" + classrelation_ref 209157 // + b parent class_ref 170629 // TCode + end + end + + class 171013 "CompoundGrid" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 209285 // + relation 198405 ---|> + a public + cpp default "${type}" + classrelation_ref 209285 // + b parent class_ref 169221 // TimeGrid + end + end + end + package_ref 131077 // ConfigQuery package_ref 132485 // Containers @@ -1161,24 +1535,6 @@ ${inlines} end end - class 134917 "Time" - visibility public - cpp_decl "${comment}${template}class ${name}${inherit} - { -${members} }; -${inlines} -" - java_decl "" - php_decl "" - python_2_2 python_decl "" - idl_decl "" - explicit_switch_type "" - - comment "denotes a temporal position (time point), based on timeline start. - -investigate posix.4 realtime timers, wrap these here" - end - class 135301 "Factory" visibility public nformals 1 diff --git a/uml/lumiera/131077 b/uml/lumiera/131077 index a6ef47693..3b38a2e50 100644 --- a/uml/lumiera/131077 +++ b/uml/lumiera/131077 @@ -1,6 +1,6 @@ format 58 "ConfigQuery" // CommonLib::ConfigQuery - revision 18 + revision 19 modified_by 5 "hiv" // class settings //class diagram settings diff --git a/uml/lumiera/132485 b/uml/lumiera/132485 index 099d2b342..d1bbeacbe 100644 --- a/uml/lumiera/132485 +++ b/uml/lumiera/132485 @@ -1,6 +1,6 @@ format 58 "Containers" // CommonLib::Containers - revision 1 + revision 2 modified_by 5 "hiv" // class settings //class diagram settings diff --git a/uml/lumiera/142725.diagram b/uml/lumiera/142725.diagram new file mode 100644 index 000000000..c38a9266c --- /dev/null +++ b/uml/lumiera/142725.diagram @@ -0,0 +1,142 @@ +format 58 + +classcanvas 128005 class_ref 134917 // Time + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 249 118 2000 +end +classcanvas 128133 class_ref 168581 // TimeSpan + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 38 218 2000 +end +classcanvas 128261 class_ref 168709 // TimeValue + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 36 24 2000 +end +classcanvas 128389 class_ref 168837 // Duration + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 42 118 2000 +end +classcanvas 129669 class_ref 168965 // QuTime + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 245 324 2000 +end +classcanvas 130181 class_ref 169093 // Quantiser + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 393 324 2000 +end +classcanvas 130565 class_ref 169221 // TimeGrid + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 508 324 2000 +end +classcanvas 130949 class_ref 170373 // TimeVar + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 114 118 2000 +end +classcanvas 131589 class_ref 170501 // QuTimeSpan + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 103 324 2000 +end +classcanvas 131973 class_ref 170629 // TCode + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 248 413 2000 +end +classcanvas 132101 class_ref 170757 // Format + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 393 397 2000 +end +classcanvas 132997 class_ref 170885 // FrameNr + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 238 496 2000 +end +classcanvas 133253 class_ref 171013 // CompoundGrid + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 480 439 2000 +end +relationcanvas 128517 relation_ref 195205 // + geometry VHV unfixed + from ref 128005 z 1999 to point 269 88 + line 128645 z 1999 to point 66 88 + line 128773 z 1999 to ref 128261 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 128901 relation_ref 195333 // + from ref 128389 z 1999 to ref 128261 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 129285 relation_ref 195461 // + from ref 128133 z 1999 to ref 128389 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 129413 relation_ref 195589 // + from ref 128133 z 1999 to ref 128005 + role_a_pos 111 214 3000 no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 130437 relation_ref 195973 // + from ref 129669 z 1999 stereotype "<>" xyz 309 330 3000 to ref 130181 + no_role_a no_role_b + multiplicity_a_pos 376 349 3000 multiplicity_b_pos 305 349 3000 +end +relationcanvas 130693 relation_ref 196101 // + decenter_end 353 + from ref 130181 z 1999 stereotype "<>" xyz 457 333 3000 to ref 130565 + no_role_a no_role_b + multiplicity_a_pos 491 352 3000 no_multiplicity_b +end +relationcanvas 130821 relation_ref 197253 // + from ref 129669 z 1999 to ref 128005 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 131077 relation_ref 197381 // + geometry VHV + from ref 130949 z 1999 to point 138 88 + line 131205 z 1999 to point 66 88 + line 131333 z 1999 to ref 128261 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 131461 relation_ref 197509 // + from ref 130949 z 1999 to ref 128005 + role_a_pos 175 124 3000 no_role_b + multiplicity_a_pos 230 140 3000 multiplicity_b_pos 176 143 3000 +end +relationcanvas 131717 relation_ref 197637 // + from ref 131589 z 1999 to point 65 290 + line 131845 z 1999 to ref 128133 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 132485 relation_ref 197893 // + from ref 131973 z 1999 to point 290 413 + line 132869 z 1999 to ref 132101 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 132613 relation_ref 198021 // + from ref 129669 z 1999 stereotype "<>" xyz 275 378 3000 to ref 131973 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 132741 relation_ref 198149 // + decenter_end 595 + from ref 130181 z 1999 stereotype "<>" xyz 360 377 3000 to ref 132101 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 133125 relation_ref 198277 // + decenter_begin 581 + from ref 132997 z 1999 to ref 131973 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 133381 relation_ref 198405 // + decenter_begin 658 + from ref 133253 z 1999 to ref 130565 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +end diff --git a/uml/lumiera/5.session b/uml/lumiera/5.session index 5e7b8f6a0..a3d4a7eab 100644 --- a/uml/lumiera/5.session +++ b/uml/lumiera/5.session @@ -4,10 +4,8 @@ diagrams 631 352 100 4 0 0 objectdiagram_ref 138885 // ModelAssetRelations 730 488 100 4 0 0 - classdiagram_ref 128133 // Session structure - 835 697 100 4 300 0 - active activitydiagram_ref 129413 // build flow - 627 621 100 4 0 0 + active classdiagram_ref 142725 // Time flavours + 595 629 100 4 0 0 end show_stereotypes selected @@ -36,15 +34,10 @@ open expansionregion_ref 128133 // establish partitioning usecaseview_ref 128261 // config examples classview_ref 128133 // Engine Workings - class_ref 164485 // Request - class_ref 164613 // Provision - class_ref 166021 // ActiveProvision - class_ref 164741 // Binding - class_ref 166277 // Index - class_ref 145285 // MediaKind - - package_ref 131077 // ConfigQuery - class_ref 152965 // Handle + classdiagram_ref 142725 // Time flavours + class_ref 134917 // Time + class_ref 169221 // TimeGrid + classview_ref 128645 // Service Components classview_ref 128266 // SmartPointers end end diff --git a/uml/lumiera/lumiera.prj b/uml/lumiera/lumiera.prj index ae9d839be..d6e97d779 100644 --- a/uml/lumiera/lumiera.prj +++ b/uml/lumiera/lumiera.prj @@ -1,6 +1,6 @@ format 58 "lumiera" - revision 65 + revision 66 modified_by 5 "hiv" cpp_root_dir "../../src/" diff --git a/wiki/renderengine.html b/wiki/renderengine.html index 5837913f4..28b45fef5 100644 --- a/wiki/renderengine.html +++ b/wiki/renderengine.html @@ -2081,7 +2081,7 @@ Besides routing to a global pipe, wiring plugs can also connect to the source po Finally, this example shows an ''automation'' data set controlling some parameter of an effect contained in one of the global pipes. From the effect's POV, the automation is simply a ParamProvider, i.e a function yielding a scalar value over time. The automation data set may be implemented as a bézier curve, or by a mathematical function (e.g. sine or fractal pseudo random) or by some captured and interpolated data values. Interestingly, in this example the automation data set has been placed relatively to the meta clip (albeit on another track), thus it will follow and adjust when the latter is moved. -
+
This wiki page is the entry point to detail notes covering some technical decisions, details and problems encountered in the course of the implementation of the Lumiera Renderengine, the Builder and the related parts.
 
 * [[Packages, Interfaces and Namespaces|InterfaceNamespaces]]
@@ -2110,6 +2110,10 @@ Finally, this example shows an ''automation'' data set controlling some paramete
 * shaping the GUI/~Proc-Interface, based on MObjectRef and the [[Command frontend|CommandHandling]]
 * defining PlacementScope in order to allow for [[discovering session contents|Query]]
 * working out a [[Wiring concept|Wiring]] and the foundations of OutputManagement
+* shaping the foundations of the [[player subsystem|Player]]
+* detail considerations regarding [[time and time quantisation|TimeQuant]]
+* designing how to [[build|BuildFixture]] the [[Fixture]] (...{{red{WIP}}}...)
+
@@ -3970,6 +3974,33 @@ We need a way of addressing existing [[pipes|Pipe]]. Besides, as the Pipes and T <<tasksum end>>
+
+
With //play process//&nbsp; we denote an ongoing effort to calculate a stream of frames for playback or rendering.
+The play process is an conceptual entity linking together several activities in the [[Backend]] and the RenderEngine. Creating a play process is the central service provided by the [[player subsystem|Player]]: it maintains a registration entry for the process to keep track of associated entities, resources allocated and calls dispatched as a consequence, and it wires and exposes a PlayController to serve as an interface and information hub.
+
+''Note'': the player is in no way engaged in any of the actual calculation and management tasks necessary to make this stream of calculations happen. The play process code contained within the player subsystem is largely comprised of organisational concerns and not especially performance critical.
+* the [[Backend]] is responsible for scheduling and dispatching the calculations
+* the RenderEngine has the ability to cary out individual frame calculations
+* the OutputSlot exposed by the [[output manager|OutputManagement]] is responsible for accepting timed frame delivery
+
+
+
Within Lumiera, &raquo;Player&laquo; denotes the [[Subsystem]] responsible for organising and tracking //ongoing playback and render processes.// &rarr; [[PlayProcess]]
+The player subsystem does not perform or even manage any render operations, nor does it handle the outputs directly.
+Yet it adresses some central concerns:
+
+;uniformity
+:all playback and render processes are on equal footing, handled in a similar way.
+;integration
+:the player cares for the necessary integration with the other subsystems
+:it consults the OutputManagement, retrieves the necessary informations from the [[Session]] and coordinates [[Backend]] calls.
+;time quantisation
+:the player translates continuous time values into discrete frame counts.
+:to perform this [[quantisation|TimeQuant]], the help of the session for building a TimeGrid for each output channel is required.
+
+!{{red{WIP 12/10}}} under construction
+The player subsystem is currently about to be designed and built up; some time ago, __Joel Holdsworth__ and __Ichthyo__ did a design study with a PlayerDummy, which is currently hooked up with the TransportControl in the Lumiera GUI.
+
+
__Joelholdsworth__ and __Ichthyo__ created this player mockup in 1/2009 to find out about the implementation details regarding integration and colaboration between the layers. There is no working render engine yet, thus we use a ~DummyImageGenerator for creating faked yuv frames to display. Within the GUI, there is a ~PlaybackController hooked up with the transport controls on the timeline pane.
 # first everything was contained within ~PlaybackController, which spawns a thread for periodically creating those dummy frames
@@ -6493,6 +6524,128 @@ function addKeyDownHandlers(e)
 Thus no server and no network connection is needed. Simply open the file in your browser and save changes locally. As the [[Proc-Layer wiki|ProcLayer and Engine]] HTML is located in the Lumiera source tree, all changes will be managed and distributed via GIT. While doing so, you sometimes will have to merge conflicing changes manually in the HTML source.
  * see GettingStarted
  * see [[Homepage|http://tiddlywiki.com]], [[Wiki-Markup|http://tiddlywiki.org/wiki/TiddlyWiki_Markup]]
+
+
+
+
The term &raquo;Time&laquo; spans a variety of vastly different entities. Within a NLE we get to deal with various //flavours of time values.//
+;continuous time
+:without any additional assumptions, ''points in time'' can be specified with arbitrary precision.
+:the time values are just numbers; the point of reference and the meaning is implicit.
+:within Lumiera, time is encoded as integral number of //micro ticks,// practically continuous
+;duration
+:a range of time, a ''distance'' on the time axis, measured with the same arbitrary precision as time points.
+:distances and durations can be determined by //subtracting// two time points, consequently they are //signed numbers.//
+:a duration always abstracts from the time //when// this duration or distance happens, the relation to any time scale remains implicit
+;offset
+:offsetting a time or a duration is an operation (not an entity): it means changing the denoted time point or duration.
+:the //target// of an offset operation is a time or duration, while it's //argument// is a distance (synonymous to duration).
+:Time values are //immutable,// like numbers. Only a ''time variable'' can be changed. Durations to the contrary can be mutable or  const.
+;time span
+:contrary to a mere duration, a ''time interval'' or time span is actually //anchored// at a specific point in time.
+:it can be seen as a //special kind of duration,// which explicitly states the information //when// this time span takes place.
+
+;internal time
+:While the basic continuous time values don't imply any provision regarding the time scale and origin to be used, actually, within the implementation of the application, the meaning of time values is uniform and free of contradictions. Thus effectively there is an ''implementation time scale'' -- but its scope of validity is //strictly limited to the implementation level of a single application instance.// It is never exposed and never persisted. It might not be reproducible over multiple instantiations of the application. The implementation reserves the right to recalibrate this internal scale. Later, when Lumiera gains the capability to run within a network of render nodes, these instance connections will include a negotiation about the internal time scale, which remains completely opaque to the outer world. This explains, why {{{lumiera::Time}}} instances lack the ability to show their time value beyond debugging purposes. This is to avoid confusion and to stress their opaque nature.
+;wall clock and system time
+:The core property of any external real world time is that it is //running// -- we have to synchronise to an external time source.
+:This implies the presence of a //running synchronisation process,// with the authority to adjust the time base;
+:contrast this to the internal time, which is static and unconnected -- 
+;quantised time
+:The ''act of quantisation'' transforms a continuous property into a ''discrete'' structure. Prominent examples can be found in the domain of micro physics and with digital information processing. In a broader sense, any measurement or //quantification// also encompasses a quantisation. Regarding time and time measurement, quantisation means alignment to a predefined ''time grid''. Quantisation necessarily is an //irreversible process// -- possible additional informations get discarded.
+:Note that quantisation introduces an ''time origin'' and a ''reference scale''
+;frame count
+:within the context of film and media editing, the specification of a ''frame number'' is an especially important instance of quantisation.
+:all the properties of quantisation apply indeed to this special case: it is a time measurement or specification, where the values are aligned to a grid, and there is a reference time point where the counting starts (origin) and a reference scale (frames per second). Handling of quantised time values in Lumiera is defined such as to ensure the presence of all those bits of information. Without such precautions, operating with bare frame numbers leads itself to all kinds of confusions, mismatches, quantisation errors and unnecessary limitations of functionality.
+;timecode
+:Quantisation also is the foundation of all kinds of formalised time specifications
+:actually even a frame count is some kind of (informal) timecode -- other timecodes employ a standardised format.
+://every// presentation of time values and every persistent storage and exchange of such values is based on time codes.
+:but quantisation and time code aren't identical: a given quantised time value typically can be cast into multiple timecode formats.
+
+!Patterns for handling quantised time
+When it comes to actually handling quantised time values, several patterns are conceivable for dealing with the quantisation operation and representing quantised data. As guideline for judging these patterns, the general properties of time quantisation, as detailed above, should be taken into account. Quantising a time value means both //discarding information,// while at the same time //adding information// pertaining the assumptions of the context.
+
+__casual handling__: this is rather an frequently encountered ''anti pattern''. When reading such code, most striking is the sense of general unawareness of the problem, which is then "discovered" on a per case base, which leads to numerous repetitions of the same basic undertakings, but done with individual treatment of each instance (not so much copy-n-paste). Typical code smells:
+* the rounding, modulo and subtract-base operations pertinent with scale handling are seemingly inserted as bugfix
+* local code path forks to circumvent or compensate for otherwise hard wired calculations based on specific ways to invoke a function
+* playing strikingly clever tricks or employing heuristics to "figure out" the missing scale information from accessible context after the fact
+* advertising support for some of the conceivable cases as special feature, or adding it as plugin or extension module with limited scope
+* linking parts of the necessary additional information to completely unrelated other structures, thus causing code tangling and scattering
+* result or behaviour of calculations depends on the way things are set up in a seemingly contingent way, forcing users to stick to very specific procedures and ordered steps.
+[>img[Time and Time Quantisation in Lumiera|uml/fig142725.png]]
+__static typing__: an analysis of the cases to be expected establishes common patterns and some base cases, which are then represented by distinct types with well established conversions. This can be combined with generic programming for the common parts. Close to the data input, a factory establishes these statically typed values.
+
+__tagged values__: quantised values are explicitly created out of continuous values by a quantiser entity. These quantised data values contain a copy of the original data, adjusted to be exactly aligned with respect to the underlying time grid. In addition, they carry a tag or ID to denote the respective scale, grid or timecode system. This tag can be used later on to assess compatibility or to recast values into another timecode system.
+
+__delayed quantisation__: with this approach, the information loss is delayed as long as possible. Quantised time values are rather treated as promise for quantisation, while the actual time data remains unaltered. Additionally, they carry a tag, or even a direct link to the responsible quantiser instance. Effectively, these are specialised time values, instances of a sub-concept, able to stand-in for general time values, but exposing additional accessors to get a quantised value.
+
+!!!discussion
+For Lumiera, the static typing approach is of limited value -- it excels when values belonging to different scales are actually treated differently. There are such cases, but rather on the data handling level, e.g. sound samples are always handled block wise. But regarding time values, the unifying aspect is more important, which leads to prefering a dynamic (run time typed) approach, while //erasing// the special differences most of the time. Yet the dynamic and open nature of the Lumiera high-level model favours the delayed quantisation pattern; the same values may require different quantisation depending on the larger model context an object is encountered in. This solution might be to general and heavy weight at times though. Thus, for important special cases, the accessors should return tagged values, preferably even with differing static type. Time codes can be integrated this way, but most notably the ''frame numbers'' used for addressing throughout the backend, can be implemented as such specifically typed tagged values; the tag here denotes the quantiser and thus the underlying grid -- it should be implemented as hash-ID for smooth integration with code written in plain C.
+&rarr; more on [[usage situations|TimeUsage]]
+
+
+
+
the following collection of usage situations helps to shape the details of the time values and time quantisation design. &rarr; see also  [[time quantisation|TimeQuant]]
+
+;time position of an object
+:indeed the term "time position" encompasses two quite different questions
+:* a time or timing specification within the object
+:* determining the time point in reference to an existing scale
+;time and length of an object
+:basically the same situation, but length could be treated in two ways for quantisation
+:* having a precise specification and then quantise the start and endpoint
+:* quantise the start position and then establish an (independently quantised length)
+;moving and resizing an object
+:this can in itself be done in two different ways, and each of them can be applied in a quantised flavour
+:which sums up to 8 possible combinations, considering that position and length are 2 degrees of freedom.
+:* a variable can be /changed/ by an offset
+:* a variable can be /defined/ to a new value
+:another (hidden) degree of freedom lies in how to apply an quantised offset to an unquantised value (and reversed)
+:because this operation might be done both in the quantised or non-quantised domain, and also the result might be (un)quantised
+;updating the playback position
+:this can be seen as a practical application of the above; basically we can choose to show the wall clock time or we can advance the playback position in frame increments, thus denoting the frame currently in display. These distinctions may look mood for video, but are relevant for precise audio editing, especially when combined with loop playback (recall that audio is processed block wise, but the individual sample frames and thus the possible loop positions are way finer than the processing block size)
+;displaying time intervals
+:for display, time intervals get //re-quantised// into display array coordinates.
+:While evidently the display coordinates are themselves quantised and we obviously don't want to cancel out the effect of an quantisation of the values or intervals to be displayed (which means, we get two quantisations chained up after each other), there remains the question if the display array coordinates should be aligned to the grid of the //elements to be displayed,// and especially if the allowed zoom factors should be limited. This decision isn't an easy one, as it has an immediate and tangible effect on what can be showed, how reversible and reproducible a view is and (note) on the actual values which can be set and changed through the GUI.
+;time value arithmetic
+:Client code as well as the internal implementation of time handling needs to do arithmetic operations with time values. Time values are additive and totally ordered. Distance, as calculated by subtraction, can be made into a metric. Another and quite different question is to what extent a quantised variant of this arithmetics is required.
+;relative placement
+:because of the divergence between quantised and unquantised values, the question arises, if placement relative to another object refers to the raw position or the already quantised position. Basically all the variations discussed for //time and length of an object// also do apply here.
+
+!notable issues
+''Direct quantisation of length is not possible''. This is due to the non-linear nature of all but the most trivial time grids: Already such a simple addition like a start offset destroys linearity, and this still the more is true within a compound grid where the grid spacing changes at some point. Thus, the length has to be re-established at the target position of an time interval after each change involving quantisation. Regarding the //strategy// to apply when re-establishing the length, it seems more appropriate to treat the object as an entity which is moved, which means to do quantisation in two steps, first the position, then the endpoint (the second option in the description above). But it seems advisable not to hard wire that strategy -- better put it into the quantiser.
+
+We should note, that the problems regarding quantised durations also carry over to //offsets:// it is difficult to ''define the semantics of a quantised offset''. Seemingly the only viable approach is to have a //intended offset,// and then to apply a re-quantisation to the target after applying the (raw) offset.
+
+''When to materialise a quantisation''. Because of the basic intention to retain information, we delay actually applying the quantisation to the stored values as much as possible. But not materialising immediately at quantisation has the downside of possibly accumulating off-grid values without that being evident. Most notably, if we apply the raw offsets produced by GUI interactions, the object's positions and lengthes are bound to accumulate spurious information never intended by the user.
+
+Thus, an especially important instance of that problem is ''how to deal with updates in a quantised environment''. If we handle quantisation stictly as a view employed on output, we run into the problems with accumulating spurious information. On the other hand, allowing for quantised changes inevitably pulls in all the complexity of mixing quantised and non-quantised values. It would be desirable somehow to move these distinctions out of the scope of this design and offload them onto the client (code using these time classes).
+
+Another closely related problem is ''when to allow mutations'', if at all. We can't completely do away with mutations, simply because we don't have a pure functional language at our disposal. The whole concept of //reference semantics// doesn't play so well with immutable objects. The Lumiera high-level (session) model certainly relies on objects intended to be //manipulated.// Thus we need a re-settable length field in {{{MObject}}} and we need a time variable for position calculations. Yet we could make any //derived objects// into immutable descriptor records, which certainly helps with parallelism.
+
+The ''problem with playback position'' is -- that it's an attempt to conceptualise a non-existing entity. There is no such thing like "the" playback position. Yet most applications I'm aware off employ this concept. Likely they got trapped by the metaphor of the tape head, again. We should do away with that. On playback, we should show a //projection of wall-clock time onto the expected playback range// -- not more, not less. It should be acknowledged that there is //no direct link to the ongoing playback processes,// besides the fact that they're assumed to sync to wall-clock time as well. Recall, typically there are multiple playback processes going on in compound, and each might run on a different update rate. If we really want a //visual out-of-sync indicator,// we should treat that as a separate reporting facility and display it apart of the playback cursor.
+
+Note that the ''display window might be treated as just an independent instance of quantisation''. This is similar to the approach taken above for modifying quantised time span values. We should provide a special kind of time grid, the display coordinates. The origin of these is always defined to the left (lower) side of the interval to be displayed, and they are gauged in screen units (pixels or similar, as used by the GUI toolkit set). The rest is handled by the general quantisation mechanisms. The problem of aligning the display should be transformed into a general facility to align grids, and solved for the general case. Doing so solves the remaining problems with quantised value changes and with ''specifying relative placements'' as well: If we choose to represent them as quantised values, we might (or might not) also choose to apply this //grid-alignment function.//
+
+!substantial problems to be solved
+* how to align multiple grids
+* how to integrate modifications of quantised values.
+
+The problem with modification of quantised values highlights an inner contratiction or conflicting goals
+* the whole system should fit in naturally and just feel like using raw time values
+* quantisation should be added //late// -- like a view
+* there should be a guidance towards the intended proper use
+
+!!! possible solutions{{red{WIP 12/10}}}
+* only allow to assign a completely new setting
+* only accept raw time values for redefining a quantised interval
+* only accept an abstract //modification object.//
+
+!!!usage considerations
+Question is: how fine grained and configurable needs this to be?
+* for example, when moving a clip taken from 50fps media, the new position might be quantised to the 50fps grid established by the media, while the target timeline runs with 25fps, allowing for finer adjustments based on the intermediate frames present in the source material.
+* likely we need a "nudge by unit(s)"
+