From 545a07db332cd536c58b306d1c93f0959ce05cf1 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Mon, 7 Nov 2016 16:22:04 +0100 Subject: [PATCH] Doxygen: fill in missing file level headlines for the Library (timecode handling) --- src/lib/time/formats.hpp | 7 ++++++- src/lib/time/grid.hpp | 4 +++- src/lib/time/quantiser.cpp | 2 +- src/lib/time/quantiser.hpp | 13 +++++++++++-- src/lib/time/timecode.cpp | 4 +++- src/lib/time/timecode.hpp | 14 ++++++++++++-- src/lib/time/timequant.hpp | 11 ++++++++++- 7 files changed, 46 insertions(+), 9 deletions(-) diff --git a/src/lib/time/formats.hpp b/src/lib/time/formats.hpp index a3643963e..f1553af75 100644 --- a/src/lib/time/formats.hpp +++ b/src/lib/time/formats.hpp @@ -22,7 +22,12 @@ /** @file formats.hpp - ** TODO formats.hpp + ** Definition of time code formats + ** This header is part of the Lumiera time and timecode handling library + ** and defines the interfaces and types to deal with the common set of + ** time code formats encountered in video editing. The generic handling + ** of _quantised time_ can be parametrised to support and comply to these + ** specific time code formats. */ diff --git a/src/lib/time/grid.hpp b/src/lib/time/grid.hpp index 70a924669..50854ea30 100644 --- a/src/lib/time/grid.hpp +++ b/src/lib/time/grid.hpp @@ -22,7 +22,9 @@ /** @file grid.hpp - ** TODO grid.hpp + ** definition of a time grid abstraction for time and timecode handling. + ** This interface is the foundation to deal with _quantised_ (grid aligned) + ** time values, as is essential for handling of timecode data. */ diff --git a/src/lib/time/quantiser.cpp b/src/lib/time/quantiser.cpp index 6f242ecb5..a2ed4372e 100644 --- a/src/lib/time/quantiser.cpp +++ b/src/lib/time/quantiser.cpp @@ -22,7 +22,7 @@ /** @file quantiser.cpp - ** TODO quantiser.cpp + ** Implementation of support functions to create grid-aligned time and timecode values */ diff --git a/src/lib/time/quantiser.hpp b/src/lib/time/quantiser.hpp index 24cbaeac3..4ed16703d 100644 --- a/src/lib/time/quantiser.hpp +++ b/src/lib/time/quantiser.hpp @@ -22,7 +22,17 @@ /** @file quantiser.hpp - ** TODO quantiser.hpp + ** Library functions to support the formation of grid-aligned time values. + ** This is a crucial part of Lumiera's time and time handling framework; it + ** serves as link between the precise internal time representation and various + ** grid-aligned external standard time representations. The underlying theme is, + ** by forcing all conversions to go through this central set of library functions, + ** the notorious act of frame-aligning / grid-aligning time values, which can not + ** be avoided, will at least be performed in a reproducible and predictable way. + ** Moreover, the time handling library was built in a way such as to encourage + ** use of the internal, abstracted yet precise time entities, so that the + ** inevitable conversion to the imprecise but well-established external + ** entities (frame numbers, SMPTE, drop frame, HMS) happens as late as possible. */ @@ -35,7 +45,6 @@ #include "lib/time/timevalue.hpp" #include "lib/iter-adapter.hpp" -//#include #include #include #include diff --git a/src/lib/time/timecode.cpp b/src/lib/time/timecode.cpp index 5e5e6b0ec..8460516a5 100644 --- a/src/lib/time/timecode.cpp +++ b/src/lib/time/timecode.cpp @@ -22,7 +22,9 @@ /** @file timecode.cpp - ** TODO timecode.cpp + ** Implementation parts of the timecode handling library. + ** @todo a started implementation exists since 2010, + ** yet crucial parts still need to be filled in as of 2016 */ diff --git a/src/lib/time/timecode.hpp b/src/lib/time/timecode.hpp index 203bacd13..bb3a8c5ea 100644 --- a/src/lib/time/timecode.hpp +++ b/src/lib/time/timecode.hpp @@ -22,7 +22,14 @@ /** @file timecode.hpp - ** TODO timecode.hpp + ** Timecode handling library + ** This header defines the foundation interface TCode to represent a grid aligned + ** time specification, given in some well-established time code format. It is complemented + ** by implementations of the most relevant practical time code formats + ** - frame numbers / frame counting + ** - SMPTE (hours, minutes, seconds and frames) -- including drop-frame + ** - HMS (hours, minutes, seconds and fractional seconds) + ** - fractional seconds as rational number */ @@ -50,7 +57,10 @@ namespace time { /** * Interface: fixed format timecode specification. * @see time::format - * @todo WIP-WIP-WIP + * @todo as of 2016 this is basically finished since years, + * but still not in any widespread practical use (not by bad intention, + * simply by lack of opportunities). So this core interface still needs + * some feedback from practice in order to be finalised. */ class TCode { diff --git a/src/lib/time/timequant.hpp b/src/lib/time/timequant.hpp index b029efd04..68ba6b614 100644 --- a/src/lib/time/timequant.hpp +++ b/src/lib/time/timequant.hpp @@ -22,7 +22,16 @@ /** @file timequant.hpp - ** TODO timequant.hpp + ** Support library to represent grid-aligned time specifications + ** This is part of Lumiera's time and time code handling framework. + ** The QuTime entity represents the link between the internal precise + ** time specifications and external representation formatted according + ** to some well established time code format: QuTime both holds a precise + ** internal time::TimeValue entry, plus a reference to the _time grid_ to + ** be used, when it comes to _quantising_ (grid-aligning) those values. + ** And it offers a dedicated API to "materialise" this (still complete and + ** precise) time value into an external representation. + ** */