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. In the future, new capture cards with Windows Driver Model (WDM) drivers will provide Line21 data.
When to Implement
Note: DirectShow will provide this implementation post-beta 2.
Do not implement this interface. DirectShow provides the Line 21 Decoder, 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. |
Retrieves the physical color to use as background for overlays.
HRESULT GetBackgroundColor(
DWORD *pdwPhysColor
);
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.
Magenta is the default background color.
IAMLine21Decoder::SetBackgroundColor
Retrieves the current closed captioning service selected by the user.
HRESULT GetCurrentService(
AM_LINE21_CCSERVICE *lpService
);
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.
IAMLine21Decoder::SetCurrentService
Retrieves the closed-captioned decoder level.
HRESULT GetDecoderLevel(
AM_LINE21_CCLEVEL *lpLevel
);
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.
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.
Retrieves whether the caption text background should be opaque or transparent.
HRESULT GetDrawBackgroundMode(
AM_LINE21_DRAWBGMODE *lpMode
);
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.
By default, the caption background is opaque.
IAMLine21Decoder::SetDrawBackgroundMode
Retrieves information about output video characteristics such as size and bit depth.
HRESULT GetOutputFormat(
LPBITMAPINFOHEADER lpbmih
);
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.
The default video output size is 320 × 240 pixels.
IAMLine21Decoder::SetOutputFormat
Retrieves whether the renderer should redraw the whole output bitmap for each sample.
HRESULT GetRedrawAlways(
LPBOOL lpbOption
);
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.
IAMLine21Decoder::SetRedrawAlways
Retrieves the closed captioning service state (on or off).
HRESULT GetServiceState(
AM_LINE21_CCSTATE *lpState
);
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.
IAMLine21Decoder::SetServiceState
Sets the physical color to use as background for overlays.
HRESULT SetBackgroundColor(
DWORD dwPhysColor
);
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.
Magenta is the default background color.
IAMLine21Decoder::GetBackgroundColor
Sets the current closed captioning service.
HRESULT SetCurrentService(
AM_LINE21_CCSERVICE Service
);
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.
IAMLine21Decoder::GetCurrentService
Sets whether to make the caption text background opaque or transparent.
HRESULT SetDrawBackgroundMode(
AM_LINE21_DRAWBGMODE Mode
);
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.
By default, the caption background is opaque.
IAMLine21Decoder::GetDrawBackgroundMode
Sets information that describes output video characteristics such as size and bit depth.
HRESULT SetOutputFormat(
LPBITMAPINFO lpbmi
);
Returns an HRESULT value that depends on the implementation of the interface.
The default video output size is 320 × 240 pixels.
IAMLine21Decoder::GetOutputFormat
Sets whether the renderer should redraw the whole output bitmap for each sample.
HRESULT SetRedrawAlways(
BOOL bOption
);
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.
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.
IAMLine21Decoder::GetRedrawAlways
Sets the closed captioning service state.
HRESULT SetServiceState(
AM_LINE21_CCSTATE State
);
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.
IAMLine21Decoder::GetServiceState
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.