Stream Time

The following document describes both a data structure for representing time, and functions for manipulating and translating those data structures. The data structures are defined in ${CHEOPS_BASE}/local/include/sys/streams_time.h and the library functions are in ${CHEOPS_BASE}/local/include/streams_time.h (which pulls in the data structures.)

Functions:

SMPTEToStreamTime
StreamTimeToSMPTE
StreamTimeAdd
StreamTimeSubtract
StreamTimeDiff
StreamTimeMultiply
StreamTimeMultiplyInt
FreqToStreamTime
FFreqToStreamTime

Time in the world of streams is defined in two different manners. Time may be defined absolutely, in seconds, with an accuracy of 1/19,800 of a second. Each frame of a video stream has an absolute time associated with it. Time may also be defined relatively, in terms of frames. Examples of relative time are TIME_NEXT_FRAME and TIME_REL_FRAME( -10 ). Absolute time is analogous to the set of real numbers, as relative time is to integer numbers. Applications may use either time definition or both, as convenient.

#define TIME_FRAC_DENOM         19800   /*  2x2x2x3x3x5x5x11  */

typedef union {
  struct {
    unsigned long  fraction:15,
                   seconds:17;
  }                              abs;   /*  Absolute Stream time */
  unsigned long                  rel;   /*  Relative Stream time */
  struct {
    unsigned long  f:8,                 /*  frames  */
                   s:8,                 /*  seconds */
                   m:8,                 /*  minutes */
                   h:8;                 /*  hours   */
  }                              smpte; /*  SMPTE time - use carefully */
  struct {
    unsigned long  offset:10,           /*  signed offset from ptr  */
                   class:2,             /*  which ptr ? (cur, head, tail or special case) */
                   key:3,               /*  all ones iff relative   */
                   reserved:17;         /*  ignored in relative case */
  }                              lrel;  /*  Long Relative Stream struct */
} stream_time;

Both time definitions use the same 32 bit structure to represent time. The stream_time structure uses 15 bits to represent the fractional component, and 16 bits plus a sign bit to represent the number of seconds. Invalid fractional components are used to signal relative time. Any SMPTE timecode has a unique stream_time equivalent.

In absolute mode, negative time is represented by the top bit of the seconds field being set. A negative stream time uses a twos-complement representation for the seconds field, but the fractional field is always an unsigned positive offset from the specified second.

All time storage and calculations internal to the Rman library use the stream_time structure. It is expected that most user I/O will be done using the SMPTE format (hh:mm:ss:ff), not the stream_time format (ssss.ffff).

To facilitate programming of applications using relative time, flags are provided for selecting a frame relative to the frame currently being accessed. These are summarized here :

TIME_NEXT_FRAME: Selects the next frame temporally after the current one.
TIME_PREV_FRAME: Selects the previous frame temporally after the current one.
TIME_CUR_FRAME: Selects the current frame - no change.
TIME_STREAM_HEAD: Selects the frame with the newest (highest) time.
TIME_STREAM_TAIL: Selects the frame with the oldest (lowest) time.
TIME_REL_CUR( offset ): Selects the frame with the indicated offset from the current one (limited to [-512,511]). Note that TIME_NEXT_FRAME and TIME_CUR_FRAME are implemented using TIME_REL_CUR( 1 ) and TIME_REL_CUR( 0 ) respectively.
TIME_REL_TAIL( offset ): Selects the frame with the indicated offset from the tail of the stream buffer (offset limited to [0,511]). Note that TIME_STREAM_TAIL is implemented as TIME_REL_TAIL( 0 ).
TIME_REL_HEAD( offset ): Selects the frame with the indicated offset from the head of the stream buffer (offset limited to [-512,0]). Note that TIME_STREAM_HEAD is implemented as TIME_REL_HEAD( 0 ).
TIME_IMMEDIATE: Use the current stream_time of the input source.
TIME_INVALID: Indicates that an error condition occured.
IS_TIME_RELATIVE( st ): This macro returns non-zero if st is relative.
TIME_INFINITE: NOT a relative time. It is a flag indicating that a continuous stream of data is desired.

When indexing to a frame using an absolute time, the frame temporally closest to the time requested is selected. The absolute timecode of the frame selected is returned, for use by more discerning applications. This feature allows an application to easily process data at a fixed data rate, relatively independent of the input frame rate.