Index Topic Contents | |||
Previous Topic: IAMFileCutListElement Interface Next Topic: IAMovie Interface |
IAMLine21Decoder Interface
The IAMLine21Decoder interface provides access to closed-captioned information and settings. Closed-captioned information is transmitted in the vertical blanking interval (VBI) of television signals, specifically on line 21 (Line21) of field 1 in the VBI. Video cassette recorders record this information on video tape, and you can use Microsoft® DirectShow filters to capture the Line21 data and save it on disk in a media file format such as audio-video interleaved (AVI). The closed-captioned information appears as a separate stream within the media file.
Closed-captioned text is currently used mainly in digital versatile disc (DVD) movies. DVD movies contain Line21 data as part of the user data section of each Group of Pictures (GOP) in the video stream. Capture cards with Windows Driver Model (WDM) drivers will provide Line21 data.
When to Implement
Do not implement this interface. DirectShow provides the Line 21 Decoder in the DirectX Media 5.1 SDK, which implements it for you.
When to Use
Applications use this interface when they want to provide closed-captioned text, primarily to turn closed-captioned capabilities on and off. Use this interface in your application or in the filter immediately downstream of the Line21 Decoder filter (typically a mixer filter) to change closed-captioned options, such as the output video's size and whether to make the caption background opaque or transparent. Mixer filters can also change the physical color used for the background color key.
Applications can call the GetDrawBackgroundMode and SetDrawBackgroundMode methods so the user can select transparent or opaque captioning.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count.
IAMLine21Decoder methods Description GetDecoderLevel Retrieves the closed-captioned decoder level. GetCurrentService Retrieves the current closed captioning service selected by the user. SetCurrentService Sets the current closed captioning service. GetServiceState Retrieves the closed captioning service state (on or off). SetServiceState Sets the closed captioning service state. GetOutputFormat Retrieves information about output video characteristics such as size and bit depth. SetOutputFormat Sets information that describes output video characteristics such as size and bit depth. GetBackgroundColor Retrieves the physical color to use as background for overlays. SetBackgroundColor Sets the physical color to use as background for overlays. GetRedrawAlways Retrieves whether the renderer should redraw the whole output bitmap for each sample. SetRedrawAlways Sets whether the renderer should redraw the whole output bitmap for each sample. GetDrawBackgroundMode Retrieves whether the caption text background should be opaque or transparent. SetDrawBackgroundMode Sets whether to make the caption text background opaque or transparent. IAMLine21Decoder Interface
IAMLine21Decoder::GetBackgroundColorRetrieves the physical color to use as background for overlays.
HRESULT GetBackgroundColor(
DWORD *pdwPhysColor
);Parameters
- pdwPhysColor
- Pointer to the retrieved DWORD value.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
Remarks
Magenta is the default background color.
See Also
IAMLine21Decoder::SetBackgroundColor
IAMLine21Decoder Interface
IAMLine21Decoder::GetCurrentServiceRetrieves the current closed captioning service selected by the user.
HRESULT GetCurrentService(
AM_LINE21_CCSERVICE *lpService
);Parameters
- lpService
- Pointer to the current service. This value is a member of the AM_LINE21_CCSERVICE enumerated data type. The default service is AM_L21_CCSERVICE_Caption1.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
See Also
IAMLine21Decoder::SetCurrentService
IAMLine21Decoder Interface
IAMLine21Decoder::GetDecoderLevelRetrieves the closed-captioned decoder level.
HRESULT GetDecoderLevel(
AM_LINE21_CCLEVEL *lpLevel
);Parameters
- lpLevel
- Pointer to the retrieved decoder level. AM_L21_CCLEVEL_TC2 (TC2) is the only supported operating channel level and is an enhanced and backward-compatible version of the original TC1 level.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
Remarks
This method is for informational purposes only.
TC1 and TC2 are television set decoder levels that represent whether the television can handle some closed-captioned byte pairs and produce the desired captioning results. The Line21 Decoder is capable of TC2 level decoding, which includes all TC1 decoding. Only the first 100,000 television sets manufactured that included closed-captioned capability were TC1 compliant; the later TV sets are TC2 compliant.
IAMLine21Decoder Interface
IAMLine21Decoder::GetDrawBackgroundModeRetrieves whether the caption text background should be opaque or transparent.
HRESULT GetDrawBackgroundMode(
AM_LINE21_DRAWBGMODE *lpMode
);Parameters
- lpMode
- Retrieved mode. Supported mode values are AM_L21_DRAWBGMODE_Opaque and AM_L21_DRAWBGMODE_Transparent.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
Remarks
By default, the caption background is opaque.
See Also
IAMLine21Decoder::SetDrawBackgroundMode
IAMLine21Decoder Interface
IAMLine21Decoder::GetOutputFormatRetrieves information about output video characteristics such as size and bit depth.
HRESULT GetOutputFormat(
LPBITMAPINFOHEADER lpbmih
);Parameters
- lpbmih
- Pointer to the retrieved BITMAPINFOHEADER structure.
Return Values
Returns an HRESULT value that depends on the implementation of the interface.
If successful, the default implementation returns S_FALSE if downstream filters haven't defined an output format, or S_OK if an output format has been defined.
Remarks
The default video output size is 320 × 240 pixels.
See Also
IAMLine21Decoder::SetOutputFormat
IAMLine21Decoder Interface
IAMLine21Decoder::GetRedrawAlwaysRetrieves whether the renderer should redraw the whole output bitmap for each sample.
HRESULT GetRedrawAlways(
LPBOOL lpbOption
);Parameters
- lpbOption
- Pointer to a value indicating whether the whole bitmap should be redrawn; FALSE by default, indicating don't always redraw. TRUE means always redraw.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
See Also
IAMLine21Decoder::SetRedrawAlways
IAMLine21Decoder Interface
IAMLine21Decoder::GetServiceStateRetrieves the closed captioning service state (on or off).
HRESULT GetServiceState(
AM_LINE21_CCSTATE *lpState
);Parameters
- lpState
- Pointer to the retrieved state. Supported state values are AM_L21_CCSTATE_On and AM_L21_CCSTATE_Off. Closed-captioned text is off by default.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
See Also
IAMLine21Decoder::SetServiceState
IAMLine21Decoder Interface
IAMLine21Decoder::SetBackgroundColorSets the physical color to use as background for overlays.
HRESULT SetBackgroundColor(
DWORD dwPhysColor
);Parameters
- dwPhysColor
- DWORD value that specifies the physical background color.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
Remarks
Magenta is the default background color.
See Also
IAMLine21Decoder::GetBackgroundColor
IAMLine21Decoder Interface
IAMLine21Decoder::SetCurrentServiceSets the current closed captioning service.
HRESULT SetCurrentService(
AM_LINE21_CCSERVICE Service
);Parameters
- Service
- Specified service. This value is a member of the AM_LINE21_CCSERVICE enumerated data type. The default service is AM_L21_CCSERVICE_Caption1.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
See Also
IAMLine21Decoder::GetCurrentService
IAMLine21Decoder Interface
IAMLine21Decoder::SetDrawBackgroundModeSets whether to make the caption text background opaque or transparent.
HRESULT SetDrawBackgroundMode(
AM_LINE21_DRAWBGMODE Mode
);Parameters
- Mode
- Mode to set. Supported mode values are AM_L21_DRAWBGMODE_Opaque and AM_L21_DRAWBGMODE_Transparent.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
Remarks
By default, the caption background is opaque.
See Also
IAMLine21Decoder::GetDrawBackgroundMode
IAMLine21Decoder Interface
IAMLine21Decoder::SetOutputFormatSets information that describes output video characteristics such as size and bit depth.
HRESULT SetOutputFormat(
LPBITMAPINFO lpbmi
);Parameters
- lpbmi
- Pointer to the specified BITMAPINFO structure containing the desired output format.
Return Values
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
The default video output size is 320 × 240 pixels.
See Also
IAMLine21Decoder::GetOutputFormat
IAMLine21Decoder Interface
IAMLine21Decoder::SetRedrawAlwaysSets whether the renderer should redraw the whole output bitmap for each sample.
HRESULT SetRedrawAlways(
BOOL bOption
);Parameters
- bOption
- Value indicating whether the whole bitmap should be redrawn. TRUE indicates redraw always, FALSE means do not redraw always.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
Remarks
Call this method from your filter if it dirties the buffer that it provides to the Line21 Decoder filter. Typically, a mixer filter resides in the filter graph directly downstream from the Line21 Decoder filter. The mixer filter should call this method and set bOption to TRUE to ensure the entire bitmap is redrawn properly.
A downstream mixer (or any filter that needs to do so) should only call this method with bOption set to TRUE if it provides the same buffer to the Line21 decoder as it uses to mix secondary video streams(s).
Redrawing (setting bOption to TRUE) degrades performance and increases CPU load, because it negates any potential optimizations.
See Also
IAMLine21Decoder::GetRedrawAlways
IAMLine21Decoder Interface
IAMLine21Decoder::SetServiceStateSets the closed captioning service state.
HRESULT SetServiceState(
AM_LINE21_CCSTATE State
);Parameters
- State
- Specified state. Supported state values are AM_L21_CCSTATE_On and AM_L21_CCSTATE_Off. Closed-captioned text is off by default.
Return Values
Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.
See Also
IAMLine21Decoder::GetServiceState
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.