Microsoft DirectX 8.0

IAMLine21Decoder Interface

The IAMLine21Decoder interface is implemented by the Line 21 Decoder filter. This interface provides access to closed-captioned information and settings and is primarily used by applications to turn closed-captioning on and off.

Closed-captioned information is transmitted on line 21 of field 1 in the vertical blanking interval (VBI) of television signals. Video cassette recorders record this information on video tape, and you can use the Line21 Decoder and other Microsoft® DirectShow® filters to capture the line 21 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 in live television programming as well as in DVD movies. DVD movies contain line 21 data as part of the user data section of each Group of Pictures (GOP) in the video stream. Television receiver cards with Windows Driver Model (WDM) drivers provide line 21 data.

Applications can call the GetDrawBackgroundMode and SetDrawBackgroundMode methods so the user can select transparent or opaque captioning.

Requirements

Requires Il21dec.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IAMLine21Decoder methodsDescription
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 Not implemented on the DirectShow Line21 Decoder Filter. 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::GetBackgroundColor

IAMLine21Decoder Interface

Retrieves the physical color to use as background for overlays.

Syntax

HRESULT GetBackgroundColor(
    DWORD *pdwPhysColor
);

Parameters

pdwPhysColor
Pointer to the retrieved value indicating the background color. The color value is a DWORD consisting of an RGB triple combined using a bitwise OR. The number of bits in each color component depends on the current bit depth.

Return Value

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::GetCurrentService

IAMLine21Decoder Interface

Retrieves the current closed captioning service selected by the user.

Syntax

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 Value

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::GetDecoderLevel

IAMLine21Decoder Interface

Retrieves the closed-captioned decoder level.

Syntax

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 Value

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 Line 21 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::GetDrawBackgroundMode

IAMLine21Decoder Interface

Retrieves whether the caption text background should be opaque or transparent.

Syntax

HRESULT GetDrawBackgroundMode(
    AM_LINE21_DRAWBGMODE *lpMode
);

Parameters

lpMode
Pointer to the retrieved mode, either AM_L21_DRAWBGMODE_Opaque or AM_L21_DRAWBGMODE_Transparent.

Return Value

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::GetOutputFormat

IAMLine21Decoder Interface

Retrieves information about output video characteristics such as size and bit depth.

Syntax

HRESULT GetOutputFormat(
    LPBITMAPINFOHEADER lpbmih
);

Parameters

lpbmih
Pointer to the retrieved BITMAPINFOHEADER structure.

Return Value

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.

IAMLine21Decoder::GetRedrawAlways

IAMLine21Decoder Interface

Retrieves whether the renderer should redraw the whole output bitmap for each sample.

Syntax

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 Value

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::GetServiceState

IAMLine21Decoder Interface

Retrieves the closed captioning service state (on or off).

Syntax

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 Value

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::SetBackgroundColor

IAMLine21Decoder Interface

Sets the physical color to use as background for overlays.

Syntax

HRESULT SetBackgroundColor(
    DWORD dwPhysColor
);

Parameters

dwPhysColor
DWORD value that specifies the physical background color. The color is specified as an RGB triple combined using a bitwise OR. The number of bits in each color component depends on the current bit depth.

Return Value

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::SetCurrentService

IAMLine21Decoder Interface

Sets the current closed captioning service.

Syntax

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 Value

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::SetDrawBackgroundMode

IAMLine21Decoder Interface

Sets whether to make the caption text background opaque or transparent.

Syntax

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 Value

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::SetOutputFormat

IAMLine21Decoder Interface This method is not implemented on the DirectShow® Line21 Decoder Filter. Sets information that describes output video characteristics such as size and bit depth.

Syntax

HRESULT SetOutputFormat(
    LPBITMAPINFO lpbmi
);

Parameters

lpbmi
Pointer to the specified BITMAPINFO structure containing the desired output format.

Return Value

Returns E_NOTIMPL on the DirectShow Line21 Decoder Filter's implementation of the interface.

Remarks

The default video output size is 320 × 240 pixels.

See Also

IAMLine21Decoder::GetOutputFormat

IAMLine21Decoder::SetRedrawAlways

IAMLine21Decoder Interface

Sets whether the renderer should redraw the whole output bitmap for each sample.

Syntax

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 Value

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 Line 21 Decoder filter. Typically, a mixer filter resides in the filter graph directly downstream from the Line 21 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 Line 21 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::SetServiceState

IAMLine21Decoder Interface

Sets the closed captioning service state.

Syntax

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 Value

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