IAMTimecodeGenerator Interface

The IAMTimecodeGenerator interface contains properties and methods that specify how an external SMPTE/MIDI timecode generator should supply data to the filter graph and the formats in which timecode should be supplied. You should implement this interface in combination with the IAMExtDevice and IAMExtTransport interfaces to control an external device, such as a VCR. This interface provides methods that enable applications to specify various SMPTE/MIDI timecode modes or formats that an external device should use in the generation of timecode, and methods that verify that the generator is working properly.

SMPTE timecode is a frame addressing system that identifies video and audio sources, makes automatic track synchronization possible, and provides a container for additional data related to the production. SMPTE timecode's main purpose is to provide a machine-readable address for video and audio. It is displayed in hh:mm:ss:ff format and is thoroughly defined in ANSI/SMPTE 12-1986.

For more information on SMPTE timecode see Control an External Device in DirectShow.

For more information on methods that access an external timecode reader, see the IAMTimecodeReader interface.

Implement this interface on an external device filter when you want to control how an external timecode generator produces SMPTE/MIDI timecode information.

Expose the IMediaSeeking interface on your filter to enable applications to convert timecode to Microsoft® DirectShow® reference time (by using IMediaSeeking::ConvertTimeFormat).

Your external device must be able to read timecode and send it to the computer over its control interface (see hardware requirements). If this is not the case, you must either have a timecode reader card in your computer, or you can write a software decoder that converts VITC embedded in captured video frames or LTC captured as an audio signal into DirectShow timecode samples.

Use this interface when you want to generate SMPTE timecode in an external device.

Hardware Requirements

For hardware requirements, see the IAMExtTransport interface.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IAMTimecodeGenerator methods Description

GetTCGMode Retrieves the SMPTE timecode generator properties.
SetTCGMode Sets the SMPTE timecode generator properties.
put_VITCLine Specifies which line(s) to insert the vertical interval timecode information into.
get_VITCLine Retrieves which line(s) the vertical interval timecode information has been inserted into.
SetTimecode Sets the timecode, userbit value, or both.
GetTimecode Retrieves the most recent timecode and/or userbit value available in the stream.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMTimecodeGenerator methods	Description
GetTCGMode	Retrieves the SMPTE timecode generator properties.
SetTCGMode	Sets the SMPTE timecode generator properties.
put_VITCLine	Specifies which line(s) to insert the vertical interval timecode information into.
get_VITCLine	Retrieves which line(s) the vertical interval timecode information has been inserted into.
SetTimecode	Sets the timecode, userbit value, or both.
GetTimecode	Retrieves the most recent timecode and/or userbit value available in the stream.

IAMTimecodeGenerator::GetTCGMode

IAMTimecodeGenerator Interface

Retrieves the SMPTE timecode generator properties.

Syntax

HRESULT GetTCGMode(
  long Param,
  long *pValue
  );

Parameters

Param
[in] Timecode generator mode. Specify one of the following modes you want to get settings for.

ED_TCG_FRAMERATE Frame rate
ED_TCG_REFERENCE_SOURCE Source of the count value
ED_TCG_SYNC_SOURCE Source of the hardware clock reference
ED_TCG_TIMECODE_TYPE SMPTE timecode format of the generator

pValue
[out] Pointer to the current setting of the mode specified in Param.
If you specify ED_TCG_FRAMERATE in Param, this parameter retrieves one of the following:

ED_FORMAT_SMPTE_24 24 frames per second
ED_FORMAT_SMPTE_25 25 frames per second
ED_FORMAT_SMPTE_30 30 frames per second. Nondrop frame
ED_FORMAT_SMPTE_30DROP 30 frames per second. Drop frame (actually 29.97 fps)

If you specify ED_TCG_REFERENCE_SOURCE in Param, this parameter retrieves one of the following:

ED_TCG_FREE No count reference source
ED_TCG_READER Synchronize to reader value (jamsync)

If you specify ED_TCG_SYNC_SOURCE in Param, this parameter retrieves one of the following:

ED_TCG_FREE Lock to nothing (freerun)
ED_TCG_READER Lock to timecode reader
ED_TCG_VIDEO Lock to incoming video

If you specify ED_TCG_TIMECODE_TYPE in Param, this parameter retrieves one of the following:

ED_TCG_MIDI_FULL MIDI full frame timecode
ED_TCG_MIDI_QF MIDI quarter frame timecode
ED_TCG_SMPTE_LTC Linear timecode
ED_TCG_SMPTE_VITC Vertical interval timecode

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method returns various settings of the timecode generator. For more information on ED_TCG_TIMECODE_TYPE, see IAMTimecodeReader::SetTCRMode.

IAMTimecodeGenerator::GetTimecode

IAMTimecodeGenerator Interface

Retrieves the most recent timecode and/or userbit value available in the stream.

Syntax

HRESULT GetTimecode(
  PTIMECODE_SAMPLE pTimecodeSample
  );

Parameters

pTimecodeSample
[out] Pointer to a TIMECODE_SAMPLE timecode structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method to obtain the most recent timecode value available in the stream. The application can use this to monitor the timecode and verify the generator is working properly.

See Also

IAMTimecodeGenerator::SetTimecode

IAMTimecodeGenerator::get_VITCLine

IAMTimecodeGenerator Interface

Retrieves which line(s) the vertical interval timecode information has been inserted into.

Syntax

HRESULT get_VITCLine(
  long *pLine );

Parameters

pLine
[out] Pointer to the vertical line(s) containing the timecode information (valid lines are 11-20).

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To get VITC information from multiple lines, make successive calls to this method, once for each line desired, with the hi bit set for each line.

See Also

IAMTimecodeGenerator::put_VITCLine

IAMTimecodeGenerator::put_VITCLine

IAMTimecodeGenerator Interface

Specifies which line to insert the vertical interval timecode information into.

Syntax

HRESULT put_VITCLine(
    long Line );

Parameters

Line
[in] Vertical line to contain the timecode information (valid lines are 11-20; 0 means autoselect).

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To generate VITC on specific multiple lines, make successive calls to this method, once for each line desired.
Set the hi bit to add to this line to any previously set lines.

See Also

IAMTimecodeGenerator::get_VITCLine

IAMTimecodeGenerator::SetTCGMode

IAMTimecodeGenerator Interface

Sets the SMPTE timecode generator properties.

Syntax

HRESULT SetTCGMode(
  long Param,
  long Value
  );

Parameters

Param
[in] Timecode generator mode. Specify one of the following modes.

ED_TCG_FRAMERATE Frame rate
ED_TCG_REFERENCE_SOURCE Source of the count value
ED_TCG_SYNC_SOURCE Source of the hardware clock reference
ED_TCG_TIMECODE_TYPE SMPTE timecode format of the generator

Value

[in] Setting of the mode specified in Param.
If ED_TCG_FRAMERATE is specified in Param, this parameter is set to one of the following:

ED_FORMAT_SMPTE_24 24 frames per second
ED_FORMAT_SMPTE_25 25 frames per second
ED_FORMAT_SMPTE_30 30 frames per second. Nondrop frame
ED_FORMAT_SMPTE_30DROP 30 frames per second. Drop frame (actually 29.97 frames per second)

If ED_TCG_REFERENCE_SOURCE is specified in Param, set one of the following:

ED_TCG_FREE No count reference source
ED_TCG_READER Sync to reader value (jamsync)

If ED_TCG_SYNC_SOURCE is specified in Param, set one of the following:

ED_TCG_FREE Lock to nothing (freerun)
ED_TCG_READER Lock to timecode reader
ED_TCG_VIDEO Lock to incoming video

If ED_TCG_TIMECODE_TYPE is specified in Param, set one of the following:

ED_TCG_MIDI_FULL MIDI Full Frame timecode
ED_TCG_MIDI_QF MIDI quarter frame timecode
ED_TCG_SMPTE_LTC Linear timecode
ED_TCG_SMPTE_VITC Vertical interval timecode

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For more information on ED_TCG_TIMECODE_TYPE, see the IAMTimecodeReader::SetTCRMode method.

See Also

IAMTimecodeGenerator::GetTCGMode

IAMTimecodeGenerator::SetTimecode

IAMTimecodeGenerator Interface

Sets the timecode, userbits value, or both.

Syntax

HRESULT SetTimecode(
  PTIMECODE_SAMPLE pTimecodeSample
  );

Parameters

pTimecodeSample
[in] Pointer to a TIMECODE_SAMPLE timecode structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To set only timecode, set userbit value to NULL, and vice versa. If generator is running, these values will take effect immediately.

See Also

IAMTimecodeGenerator::GetTimecode

ED_TCG_FRAMERATE	Frame rate
ED_TCG_REFERENCE_SOURCE	Source of the count value
ED_TCG_SYNC_SOURCE	Source of the hardware clock reference
ED_TCG_TIMECODE_TYPE	SMPTE timecode format of the generator

ED_FORMAT_SMPTE_24	24 frames per second
ED_FORMAT_SMPTE_25	25 frames per second
ED_FORMAT_SMPTE_30	30 frames per second. Nondrop frame
ED_FORMAT_SMPTE_30DROP	30 frames per second. Drop frame (actually 29.97 fps)

ED_TCG_FREE	No count reference source
ED_TCG_READER	Synchronize to reader value (jamsync)

ED_TCG_FREE	Lock to nothing (freerun)
ED_TCG_READER	Lock to timecode reader
ED_TCG_VIDEO	Lock to incoming video

ED_TCG_MIDI_FULL	MIDI full frame timecode
ED_TCG_MIDI_QF	MIDI quarter frame timecode
ED_TCG_SMPTE_LTC	Linear timecode
ED_TCG_SMPTE_VITC	Vertical interval timecode