dmVITC(3dm) dmVITC(3dm)
dmVITCDecoderCreate, dmVITCDecoderSetStride, dmVITCDecode,
dmVITCDecoderDestroy - decode vertical interval timecode (VITC)
#include <dmedia/dm_vitc.h>
DMstatus dmVITCDecoderCreate [Toc] [Back]
( int tc_type, DMVITCdecoder *decoder );
DMstatus dmVITCDecoderSetStride [Toc] [Back]
( DMVITCdecoder decoder,
int bytesperpixel,
int offsetintopixel);
DMstatus dmVITCDecoderSetPixelTiming [Toc] [Back]
( DMVITCdecoder decoder,
int pixeltiming);
DMstatus dmVITCDecode [Toc] [Back]
( DMVITCdecoder decoder,
void *videopixels,
int lineWidth,
int numLines,
DMVITCCode *dmVITCcodeword);
void dmVITCDecoderDestroy
( DMVITCdecoder decoder );
These routines provide a mechanism for decoding vertical interval time
code (VITC). VITC is a mechanism for storing and transferring SMPTE time
code in the vertical blanking portion of a video signal. Applications
may use VITC to synchronize audio, video, or other events with external
devices by decoding VITC from a video source connected to a video input
port, or they may parse the VITC code from a previously captured movie
file.
To decode VITC, a video source with embedded VITC must be connected to a
video input port on the workstation. The video input port must be
programmed to capture the vertical interval portion of the signal using
the video library (VL). This can be done by setting the Y dimension of
the VL_OFFSET control on your VL memory node to a negative number and
increasing the VL_SIZE by the same amount.
In order to decode VITC, you first create a VITC decoder using
dmVITCDecoderCreate. The tc_type parameter tells the decoder what format
and rate of timecode to expect. The possible values for tc_type, defined
in <dmedia/dm_timecode.h>, are explained in tc_type(3dm). The
dmVITCDecoderCreate routine only pays attention to the DM_TC_FORMAT and
DM_TC_RATE bits of the passed-in tc_type, since it will be able to
determine the drop-frame/non-drop-frame status from the VITC code itself.
Page 1
dmVITC(3dm) dmVITC(3dm)
The currently supported timecode formats are DM_TC_FORMAT_NTSC and
DM_TC_FORMAT_PAL. The currently supported timecode rate values are
DM_TC_RATE_2997, DM_TC_RATE_30, and DM_TC_RATE_25.
The value returned by dmVITCDecoderCreate must be passed to all of the
other VITC routines. It may be freed by calling dmVITCDecoderDestroy.
The video pixel format is set with dmVITCDecoderSetStride function. The
bytesperpixel parameter is used to tell the VITC decoder the size of the
pixels being decoded and the offsetintopixel parameter tells which byte
within the pixel to examine. For YCbCr formats, this should address the
Y component. For RGB formats, this should address the Green component.
The VITC decoder also needs to know the timing of the video pixels it is
parsing: dmVITCDecoderSetPixelTiming is used to indicate this. This
function expects one of four VL_TIMING constants: VL_TIMING_525_SQ_PIX
for analog NTSC timing (the default), VL_TIMING_625_SQ_PIX for analog PAL
timing, VL_TIMING_525_CCIR601 for 525-line digital timing (see ANSI/SMPTE
125M), and VL_TIMING_625_CCIR601 for 625-line digital timing (see ITU-R
BT. 656). These constants can be found in <dmedia/vl.h>. The analog
timings are also called "square pixel" and the digital timings are also
called "non-square pixel." Most applications will simply want to get the
value of the VL_TIMING control from their source VLNode and pass it right
on to dmVITCDecoderSetPixelTiming.
After calling vlGetActiveRegion to get a pointer to the video pixels (or
otherwise obtaining the VITC samples), the procedure dmVITCDecode should
be called to decode the VITC. The videopixels argument takes a pointer
to the vertical interval data returned by vlGetActiveRegion. The
lineWidth and numLines contain the number of pixels in each line and the
number of lines in the buffer to search. dmVITCDecode then scans the
video pixels looking for a VITC codeword. When one is found, it decodes
it and puts the result in the location given by dmVITCcodeword and
returns.
Currently, dmVITCDecode returns after the first codeword found: it makes
no attempt to compare codewords if VITC is present on more than one line
of the passed-in buffer.
The format of the VITC time code structure is as follows:
typedef struct {
DMtimecode tc;
unsigned int dropFrame :1;
unsigned int colorLock :1;
unsigned int evenField :1;
char userType;
char userData[4];
} DMVITCcode;
The tc, dropFrame and colorLock fields are the same as those defined in
dmLTC(3dm).
Page 2
dmVITC(3dm) dmVITC(3dm)
For DM_TC_FORMAT_NTSC VITC, evenField is 1 if the codeword resides in a
field in which the first pre-equalizing pulse follows the preceding
horizontal sync pulse by a half line. For color NTSC signals, this
corresponds to color field II or IV. A value of 0 indicates color field
I or III. Color field I, II, III, and IV are defined in ANSI/SMPTE 170M.
For DM_TC_FORMAT_PAL VITC, evenField is 1 if the codeword resides in
color field 2, 4, 6, or 8. A value of 0 indicates color field 1, 3, 5,
or 7. These color fields are defined in ITU-R BT. 470.
The userData field contains 32 additional bits used in some applications
to contain secondary time codes or other coded data. In the VITC
codeword, the user bits are divided up into 8 4-bit user groups.
userData[0]&0x01 contains the first (leftmost in the pixel image) bit of
the first 4-bit user group (this is bit 6 of the VITC codeword, using the
bit numbering scheme found in the VITC specifications), userData[0]&0x80
contains the last bit of the second 4-bit user group, userData[1]&0x01
contains the first bit of the third 4-bit user group, and so on.
The userType field is currently undefined.
ANSI/SMPTE 12M (defines VITC encoding for 525/60 video applications), EBU
Tech 3097 and IEC 461: 1986 (BS 6865:1987) (for 625/50 applications),
"Time Code: A User's Guide" by Ratcliff (Oxford: Focal Press),
dmTCFromSeconds(3dm), dmTCToSeconds(3dm), dmTCFromString(3dm),
dmTCFromString(3dm), dmTCFramesPerDay(3dm), dmTCFramesBetween(3dm),
dmLTC(3dm)
PPPPaaaaggggeeee 3333 [ Back ]
|