dmVITC(3dm) dmVITC(3dm) NAME dmVITCDecoderCreate, dmVITCDecoderSetStride, dmVITCDecode, dmVITCDecoderDestroy - decode vertical interval timecode (VITC) SYNOPSIS #include <dmedia/dm_vitc.h> DMstatus dmVITCDecoderCreate ( int tc_type, DMVITCdecoder *decoder ); DMstatus dmVITCDecoderSetStride ( DMVITCdecoder decoder, int bytesperpixel, int offsetintopixel); DMstatus dmVITCDecoderSetPixelTiming ( DMVITCdecoder decoder, int pixeltiming); DMstatus dmVITCDecode ( DMVITCdecoder decoder, void *videopixels, int lineWidth, int numLines, DMVITCCode *dmVITCcodeword); void dmVITCDecoderDestroy ( DMVITCdecoder decoder ); DESCRIPTION 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. 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). 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. SEE ALSO 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) Page 3