Ichthyostega
55b39ae592
While these function may seem superficially plausible, I more and more come to the conclusion that offering such function as ''basic building blocks'' is in itself an ill-guided approach to handling of time entities. Time is neither „just a number“ — nor does it „contain“ hours, minutes and seconds. It is possible to ''represent'' it through a **time-code**, which incurs a quantisation step and implies a reference grid. Thus Lumiera ''should not offer'' a »basic time handling library«. Doing so would be just an invitation to bypass proper time handling and avoid the use of more demanding but also more adequate mental concepts. So the next step will be to remove functions not deemed adequate, and better directly inline the respective modulus based computations. Other functions can be integrated into the respective implementation translation units for time quantisation and timecode representation.
485 lines
15 KiB
C++
485 lines
15 KiB
C++
/*
|
||
Timecode - implementation of fixed grid aligned time specifications
|
||
|
||
Copyright (C)
|
||
2010, Hermann Vosseler <Ichthyostega@web.de>
|
||
|
||
**Lumiera** 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. See the file COPYING for further details.
|
||
|
||
* *****************************************************************/
|
||
|
||
|
||
/** @file 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
|
||
*/
|
||
|
||
|
||
#include "lib/time/timecode.hpp"
|
||
#include "lib/time/timevalue.hpp"
|
||
#include "lib/time/timequant.hpp"
|
||
#include "lib/time/formats.hpp"
|
||
#include "lib/time.h"
|
||
#include "lib/util.hpp"
|
||
#include "lib/util-quant.hpp"
|
||
|
||
#include <regex>
|
||
#include <functional>
|
||
#include <boost/lexical_cast.hpp>
|
||
|
||
using util::unConst;
|
||
using util::isSameObject;
|
||
using util::floorwrap;
|
||
using std::string;
|
||
using std::regex;
|
||
using std::smatch;
|
||
using std::regex_search;
|
||
using boost::lexical_cast;
|
||
|
||
namespace lumiera {
|
||
namespace error {
|
||
LUMIERA_ERROR_DEFINE (INVALID_TIMECODE, "timecode format error, illegal value encountered");
|
||
}}
|
||
|
||
namespace lib {
|
||
namespace time {
|
||
namespace error = lumiera::error;
|
||
|
||
namespace format { /* ================= Timecode implementation details ======== */
|
||
|
||
|
||
|
||
/** try to parse a frame number specification
|
||
* @param frameNumber string containing an integral number with trailing '#'
|
||
* @param frameGrid coordinate system (and thus framerate) to use for the conversion
|
||
* @return (opaque internal) lumiera time value of the given frame's start position
|
||
* @throw error::Invalid in case of parsing failure
|
||
* @note the string may contain any additional content, as long as a
|
||
* regular-expression search is able to pick out a suitable value
|
||
*/
|
||
TimeValue
|
||
Frames::parse (string const& frameNumber, QuantR frameGrid)
|
||
{
|
||
static regex frameNr_parser{"(?:^|[^\\d\\.\\-])(\\-?\\d+)#"}; // no leading [.-\d], digit+'#'
|
||
smatch match; // note: ECMA regexp does not support lookbehind
|
||
if (regex_search (frameNumber, match, frameNr_parser))
|
||
return frameGrid.timeOf (lexical_cast<FrameCnt> (match[1]));
|
||
else
|
||
throw error::Invalid ("unable to parse framecount \""+frameNumber+"\""
|
||
, LERR_(INVALID_TIMECODE));
|
||
}
|
||
|
||
|
||
TimeValue
|
||
Smpte::parse (string const&, QuantR)
|
||
{
|
||
UNIMPLEMENTED("parsing SMPTE timecode");
|
||
}
|
||
|
||
|
||
TimeValue
|
||
Hms::parse (string const&, QuantR)
|
||
{
|
||
UNIMPLEMENTED("parse a hours:mins:secs time specification");
|
||
}
|
||
|
||
|
||
/** try to parse a time specification in seconds or fractional seconds.
|
||
* The value is interpreted relative to the origin of a the given time grid
|
||
* This parser recognises full seconds, fractional seconds and both together.
|
||
* In any case, the actual number is required to end with a trailing \c 'sec'
|
||
* @par Example specifications
|
||
\verbatim
|
||
12sec --> 12 * TimeValue::SCALE
|
||
-4sec --> -4 * TimeValue::SCALE
|
||
5/4sec --> 1.25 * TimeValue::SCALE
|
||
-5/25sec --> -0.2 * TimeValue::SCALE
|
||
1+1/2sec --> 1.5 * TimeValue::SCALE
|
||
1-1/25sec --> 0.96 * TimeValue::SCALE
|
||
-12-1/4sec --> -11.75 * TimeValue::SCALE
|
||
\endverbatim
|
||
* @param seconds string containing a time spec in seconds
|
||
* @param grid coordinate system the parsed value is based on
|
||
* @return the corresponding (opaque internal) lumiera time value
|
||
* @throw error::Invalid in case of parsing failure
|
||
* @note the string may contain any additional content, as long as a
|
||
* regular-expression search is able to pick out a suitable value
|
||
*/
|
||
TimeValue
|
||
Seconds::parse (string const& seconds, QuantR grid)
|
||
{
|
||
static regex fracSecs_parser ("(?:^|[^\\./\\d\\-])(\\-?\\d+)(?:([\\-\\+]\\d+)?/(\\d+))?sec");
|
||
//__no leading[./-\d] number [+-] number '/' number 'sec'
|
||
|
||
#define SUB_EXPR(N) lexical_cast<int> (match[N])
|
||
smatch match;
|
||
if (regex_search (seconds, match, fracSecs_parser))
|
||
if (match[2].matched)
|
||
{
|
||
// complete spec with all parts
|
||
FSecs fractionalPart (SUB_EXPR(2), SUB_EXPR(3));
|
||
int fullSeconds (SUB_EXPR(1));
|
||
return grid.timeOf (fullSeconds + fractionalPart);
|
||
}
|
||
else
|
||
if (match[3].matched)
|
||
{
|
||
// only a fractional part was given
|
||
return grid.timeOf (FSecs (SUB_EXPR(1), SUB_EXPR(3)));
|
||
}
|
||
else
|
||
{
|
||
// just simple non-fractional seconds
|
||
return grid.timeOf (FSecs (SUB_EXPR(1)));
|
||
}
|
||
else
|
||
throw error::Invalid ("unable to parse \""+seconds+"\" as (fractional)seconds"
|
||
, LERR_(INVALID_TIMECODE));
|
||
}
|
||
|
||
|
||
|
||
|
||
/** build up a frame count
|
||
* by quantising the given time value
|
||
*/
|
||
void
|
||
Frames::rebuild (FrameNr& frameNr, QuantR quantiser, TimeValue const& rawTime)
|
||
{
|
||
frameNr.setValueRaw (quantiser.gridPoint (rawTime));
|
||
}
|
||
|
||
/** calculate the time point denoted by this frame count */
|
||
TimeValue
|
||
Frames::evaluate (FrameNr const& frameNr, QuantR quantiser)
|
||
{
|
||
return quantiser.timeOf (frameNr);
|
||
}
|
||
|
||
|
||
/** build up a SMPTE timecode
|
||
* by quantising the given time value and then splitting it
|
||
* into hours, minutes, seconds and frame offset.
|
||
*/
|
||
void
|
||
Smpte::rebuild (SmpteTC& tc, QuantR quantiser, TimeValue const& rawTime)
|
||
{
|
||
tc.clear();
|
||
tc.frames = quantiser.gridPoint (rawTime);
|
||
// will automatically wrap over to the seconds, minutes and hour fields
|
||
}
|
||
|
||
/** calculate the time point denoted by this SMPTE timecode,
|
||
* by summing up the timecode's components */
|
||
TimeValue
|
||
Smpte::evaluate (SmpteTC const& tc, QuantR quantiser)
|
||
{
|
||
uint frameRate = tc.getFps();
|
||
int64_t gridPoint(tc.frames);
|
||
gridPoint += int64_t(tc.secs) * frameRate;
|
||
gridPoint += int64_t(tc.mins) * frameRate * 60;
|
||
gridPoint += int64_t(tc.hours) * frameRate * 60 * 60;
|
||
return quantiser.timeOf (tc.sgn * gridPoint);
|
||
}
|
||
|
||
/** yield the Framerate in effect at that point.
|
||
* Especially Timecode in SMPTE format exposes a "frames" field
|
||
* to contain the remainder of frames in addition to the h:m:s value.
|
||
* Obviously this value has to be kept below the number of frames for
|
||
* a full second and wrap around accordingly.
|
||
* @note SMPTE format assumes this framerate to be constant. Actually,
|
||
* in this implementation the value returned here neither needs
|
||
* to be constant (independent of the given rawTime), nor does
|
||
* it need to be the actual framerate used by the quantiser.
|
||
* Especially in case of NTSC drop-frame, the timecode
|
||
* uses 30fps here, while the quantisation uses 29.97
|
||
* @todo this design just doesn't feel quite right...
|
||
*/
|
||
uint
|
||
Smpte::getFramerate (QuantR quantiser_, TimeValue const& rawTime)
|
||
{
|
||
FrameCnt refCnt = quantiser_.gridPoint(rawTime);
|
||
FrameCnt newCnt = quantiser_.gridPoint(Time(0,1) + rawTime);
|
||
FrameCnt effectiveFrames = newCnt - refCnt;
|
||
ENSURE (1000 > effectiveFrames);
|
||
ENSURE (0 < effectiveFrames);
|
||
return uint(effectiveFrames);
|
||
}
|
||
|
||
|
||
/** handle the limits of SMPTE timecode range.
|
||
* This is an extension and configuration point to control how
|
||
* to handle values beyond the official SMPTE timecode range of
|
||
* 0:0:0:0 to 23:59:59:##. When this strategy function is invoked,
|
||
* the frames, seconds, minutes and hours fields have already been processed
|
||
* and stored into the component digxels, under the assumption the overall
|
||
* value stays in range.
|
||
* @note currently the range is extended "naturally" (i.e. mathematically).
|
||
* The representation is flipped around the zero point and the value
|
||
* of the hours is just allowed to increase beyond 23
|
||
* @todo If necessary, this extension point should be converted into a
|
||
* configurable strategy. Possible variations
|
||
* - clip values beyond the boundaries
|
||
* - throw an exception on illegal values
|
||
* - wrap around from 23:59:59:## to 0:0:0:0
|
||
* - just make the hour negative, but continue with the same
|
||
* orientation (0:0:0:0 - 1sec = -1:59:59:0)
|
||
*/
|
||
void
|
||
Smpte::applyRangeLimitStrategy (SmpteTC& tc)
|
||
{
|
||
if (tc.hours < 0)
|
||
tc.invertOrientation();
|
||
}
|
||
}
|
||
|
||
|
||
namespace { // Timecode implementation details
|
||
|
||
typedef util::IDiv<int> Div;
|
||
|
||
void
|
||
wrapFrames (SmpteTC* thisTC, int rawFrames)
|
||
{
|
||
Div scaleRelation = floorwrap<int> (rawFrames, thisTC->getFps());
|
||
thisTC->frames.setValueRaw (scaleRelation.rem);
|
||
thisTC->secs += scaleRelation.quot;
|
||
}
|
||
|
||
void
|
||
wrapSeconds (SmpteTC* thisTC, int rawSecs)
|
||
{
|
||
Div scaleRelation = floorwrap (rawSecs, 60);
|
||
thisTC->secs.setValueRaw (scaleRelation.rem);
|
||
thisTC->mins += scaleRelation.quot;
|
||
}
|
||
|
||
void
|
||
wrapMinutes (SmpteTC* thisTC, int rawMins)
|
||
{
|
||
Div scaleRelation = floorwrap (rawMins, 60);
|
||
thisTC->mins.setValueRaw (scaleRelation.rem);
|
||
thisTC->hours += scaleRelation.quot;
|
||
}
|
||
|
||
void
|
||
wrapHours (SmpteTC* thisTC, int rawHours)
|
||
{
|
||
thisTC->hours.setValueRaw (rawHours);
|
||
format::Smpte::applyRangeLimitStrategy (*thisTC);
|
||
}
|
||
|
||
|
||
using std::bind;
|
||
using std::placeholders::_1;
|
||
|
||
/** bind the individual Digxel mutation functors
|
||
* to normalise raw component values */
|
||
inline void
|
||
setupComponentNormalisation (SmpteTC& thisTC)
|
||
{
|
||
thisTC.hours.installMutator (wrapHours, thisTC);
|
||
thisTC.mins.installMutator (wrapMinutes, thisTC);
|
||
thisTC.secs.installMutator (wrapSeconds, thisTC);
|
||
thisTC.frames.installMutator(wrapFrames, thisTC);
|
||
}
|
||
|
||
}//(End)implementation details
|
||
|
||
|
||
/** */
|
||
FrameNr::FrameNr (QuTime const& quantisedTime)
|
||
: TCode(quantisedTime)
|
||
, CountVal()
|
||
{
|
||
quantisedTime.castInto (*this);
|
||
}
|
||
|
||
|
||
/** */
|
||
SmpteTC::SmpteTC (QuTime const& quantisedTime)
|
||
: TCode(quantisedTime)
|
||
, effectiveFramerate_(Format::getFramerate (*quantiser_, quantisedTime))
|
||
{
|
||
setupComponentNormalisation (*this);
|
||
quantisedTime.castInto (*this);
|
||
}
|
||
|
||
|
||
SmpteTC::SmpteTC (SmpteTC const& o)
|
||
: TCode(o)
|
||
, effectiveFramerate_(o.effectiveFramerate_)
|
||
{
|
||
setupComponentNormalisation (*this);
|
||
sgn = o.sgn;
|
||
hours = o.hours;
|
||
mins = o.mins;
|
||
secs = o.secs;
|
||
frames = o.frames;
|
||
}
|
||
|
||
|
||
SmpteTC&
|
||
SmpteTC::operator= (SmpteTC const& o)
|
||
{
|
||
if (not isSameObject (*this, o))
|
||
{
|
||
TCode::operator= (o);
|
||
effectiveFramerate_ = o.effectiveFramerate_;
|
||
sgn = o.sgn;
|
||
hours = o.hours;
|
||
mins = o.mins;
|
||
secs = o.secs;
|
||
frames = o.frames;
|
||
}
|
||
return *this;
|
||
}
|
||
|
||
|
||
/** */
|
||
HmsTC::HmsTC (QuTime const& quantisedTime)
|
||
: TCode(quantisedTime)
|
||
// : tpoint_(quantisedTime) //////////////////////////////////////////////////////////////////////TICKET #736 implement HMS format
|
||
{ }
|
||
|
||
|
||
/** */
|
||
Secs::Secs (QuTime const& quantisedTime)
|
||
: TCode(quantisedTime)
|
||
// : sec_(TimeVar(quantisedTime) / TimeValue::SCALE) /////////////////////////////////////////////////////TICKET #736 implement Seconds format
|
||
{ }
|
||
|
||
|
||
|
||
void
|
||
SmpteTC::clear()
|
||
{
|
||
frames.setValueRaw(0);
|
||
secs.setValueRaw (0);
|
||
mins.setValueRaw (0);
|
||
hours.setValueRaw (0);
|
||
sgn.setValueRaw (+1);
|
||
}
|
||
|
||
|
||
void
|
||
SmpteTC::rebuild()
|
||
{
|
||
TimeValue point = Format::evaluate (*this, *quantiser_);
|
||
Format::rebuild (*this, *quantiser_, point);
|
||
}
|
||
|
||
|
||
/** flip the orientation of min, sec, and frames.
|
||
* Besides changing the sign, this will flip the
|
||
* meaning of the component fields, which by
|
||
* definition are always oriented towards zero.
|
||
*
|
||
* Normalised value fields are defined positive,
|
||
* with automatic overflow to next higher field.
|
||
* This might cause the hours to become negative.
|
||
* When invoked in this case, the meaning changes
|
||
* from -h + (m+s+f) to -(h+m+s+f)
|
||
*/
|
||
void
|
||
SmpteTC::invertOrientation()
|
||
{
|
||
int fr (getFps());
|
||
int f (fr - frames); // revert orientation
|
||
int s (60 - secs); // of the components
|
||
int m (60 - mins); //
|
||
int h = -hours; // assumed to be negative
|
||
sgn *= -1; // flip sign field
|
||
|
||
if (f < fr) --s; else f -= fr;
|
||
if (s < 60) --m; else s -= 60;
|
||
if (m < 60) --h; else m -= 60;
|
||
|
||
hours.setValueRaw(h);
|
||
mins = m; // invoking setters
|
||
secs = s; // ensures normalisation
|
||
frames = f;
|
||
}
|
||
|
||
|
||
uint
|
||
SmpteTC::getFps() const
|
||
{
|
||
return effectiveFramerate_; //////////////////////////////////TODO better design. Shouldn't Format::getFramerate(QuantR, TimeValue) be moved here?
|
||
}
|
||
|
||
|
||
string
|
||
SmpteTC::show() const
|
||
{
|
||
string tc;
|
||
tc.reserve(15);
|
||
tc += sgn.show();
|
||
tc += hours.show();
|
||
tc += ':';
|
||
tc += mins.show();
|
||
tc += ':';
|
||
tc += secs.show();
|
||
tc += ':';
|
||
tc += frames.show();
|
||
return tc;
|
||
}
|
||
|
||
SmpteTC&
|
||
SmpteTC::operator++ ()
|
||
{
|
||
frames += sgn;
|
||
return *this;
|
||
}
|
||
|
||
SmpteTC&
|
||
SmpteTC::operator-- ()
|
||
{
|
||
frames -= sgn;
|
||
return *this;
|
||
}
|
||
|
||
namespace {
|
||
const auto TIME_SCALE_sec{lib::time::TimeValue::SCALE };
|
||
const auto TIME_SCALE_ms {lib::time::TimeValue::SCALE / 1'000};
|
||
}
|
||
|
||
/** @deprecated 5/25 : no numeric computations in this class! use Digxel instead! */
|
||
int
|
||
HmsTC::getSecs() const
|
||
{ /////////////////////////////////////////////////////////////////////////////////////////////////TICKET #750 we do not want numeric accessors her — rather we want Digxel members
|
||
return (raw_time_64(tpoint_) / TIME_SCALE_sec) % 60;
|
||
}
|
||
|
||
/** @deprecated 5/25 : no numeric computations in this class! use Digxel instead! */
|
||
int
|
||
HmsTC::getMins() const
|
||
{
|
||
return (raw_time_64(tpoint_) / TIME_SCALE_sec / 60) % 60;
|
||
}
|
||
|
||
/** @deprecated 5/25 : no numeric computations in this class! use Digxel instead! */
|
||
int
|
||
HmsTC::getHours() const
|
||
{
|
||
return raw_time_64(tpoint_) / TIME_SCALE_sec / 60 / 60;
|
||
}
|
||
|
||
/** @deprecated 5/25 : no numeric computations in this class! use Digxel instead! */
|
||
double
|
||
HmsTC::getMillis() const
|
||
{
|
||
return (raw_time_64(tpoint_) / TIME_SCALE_ms) % 1000;
|
||
}
|
||
|
||
/** */
|
||
|
||
|
||
|
||
|
||
}} // lib::time
|
||
|