dmTCToString(3dm) dmTCToString(3dm)
dmTCToString, dmTCFromString, DMtimecode, tc_type - digital media
timecode mathematics
#include <dmedia/dm_timecode.h>
DMstatus dmTCToString [Toc] [Back]
( char * outstring,
const DMtimecode *tc )
DMstatus dmTCFromString [Toc] [Back]
( DMtimecode * result,
const char * instring,
int tc_type )
DMtimecode A structure containing a representation of SMPTE time code
on which certain mathematical and utility functions can be
performed. Can be used with: dmTCAddTC(3dm),
dmTCAddFrames(3dm), dmTCToString(3dm), dmTCFromSeconds(3dm),
dmTCToSeconds(3dm), dmTCFromString(3dm),
dmTCFramesPerDay(3dm), and dmTCFramesBetween(3dm). Can also
be used with the dmLTC(3dm) and dmVITC(3dm) routines.
outstring The string created by converting tc.
tc The timecode operand to convert to a string.
result The result of converting instring to a DMtimecode.
instring The string to convert into a DMtimecode.
tc_type
The timecode type which dmTCFromString should assume the
string is in. See TC_TYPE below.
These utility functions will convert between strings and DMtimecode's.
To convert from a string to a DMtimecode, the string format must a
colon-separated string (in the form "h:m:s:f"); if fields are missing
(i.e., "01:01:04") the string will be interpreted by assuming that the
Page 1
dmTCToString(3dm) dmTCToString(3dm)
missing fields are on the left, and are "0". Thus, for example, the
string "2:14" will be interpreted as "0:0:2:14."
When converting from a DMtimecode to a string, the string returned will
be fully justified and contain all fields. (i.e., it will return a
fully-justified "00:00:02:14").
The dmTC routines, as well as other timecode-related routines such as
dmVITC and dmLTC, depend on a proper setting of the tc_type field. Often
this tc_type field appears as a member of a DMtimecode passed to or from
one of these routines.
The tc_type field tells these routines whether the maximum frame value is
25 or 30, whether 30 frame code is drop frame or not, and if so what kind
of drop frame.
The tc_type field, defined in <dmedia/dm_timecode.h>, consists of an
or'ed together bitmask of fields indicating format (DM_TC_FORMAT_...),
timecode rate (DM_TC_RATE_...), and dropframe status (DM_TC_*DROP*), but
most users will find it much easier just to use one of the preconstructed,
fully-qualified tokens:
DM_TC_30_ND - non-drop-frame NTSC or M/PAL timecode
DM_TC_2997_4FIELD_DROP - drop-frame NTSC timecode
DM_TC_2997_8FIELD_DROP - drop-frame M/PAL timecode
DM_TC_25_ND - PAL timecode (not M/PAL)
DM_TC_24_ND - 24 frame per second film timecode
DM_TC_60_ND - non-drop-frame 60 frame per second HDTV
timecode (experiemental)
DM_TC_5594_8FIELD_DROP - drop-frame 59.94 frame per second
HDTV timecode (experiemental)
The most common tokens for US use are DM_TC_24_ND, DM_TC_2997_4FIELD_DROP
and DM_TC_30_ND. In Europe, DM_TC_24_ND and DM_TC_25_ND will be the most
commonly used tokens. "NTSC" and "PAL" above really refer to any 525/60
signal and 625/50 signal, respectively.
Note on rates: the DM_TC_RATE field within tc_type does not refer to the
video signal's rate. It simply refers to whether "30 frame" timecode is
drop frame or not. Non-drop frame code has exactly 30 frames per second,
drop-frame code has exactly 29.97 frames per second over the full day.
The actual video signal rate is neither requested nor required by dmTC
and other timecode routines. For color NTSC and M/PAL signals, it
happens to be 30000/1001 frames per second, which equals neither 30 nor
29.97.
Because of this, any dmTC routines (such as dmTCToSeconds) which go
between a timecode value and real time will assume a timecode rate as
given by DM_TC_RATE, not as given by the actual video signal's frame
rate. This means that over the long term, drop frame timecode will drift
Page 2
dmTCToString(3dm) dmTCToString(3dm)
away from real time at the rate of about 2 frames per day.
If a DMtimecode operand (tc) contains an illegal timecode value (e.g., a
negative entry, invalid frame number, etc.), dmTCToString will return
DM_FAILURE, and the contents of outstring will be undefined.
If dmTCFromString is unable to interpret an input string instring, it
will return DM_FAILURE, and the contents of result will be undefined.
dmTCAddTC(3dm), dmTCAddFrames(3dm), dmTCFromSeconds(3dm),
dmTCToSeconds(3dm), dmTCFramesPerDay(3dm), dmTCFramesBetween(3dm),
dmLTC(3dm), dmVITC(3dm)
PPPPaaaaggggeeee 3333 [ Back ]
|
