IFullScreenVideo Interface

The IFullScreenVideo interface enables an application or plug-in distributor to control a full-screen renderer. The Microsoft® DirectShow® full-screen renderer supports this interface. When connected, a renderer should load the display modes that are available. The number of modes available can be obtained through IFullScreenVideo::CountModes. Information on each individual mode is then available by calling IFullScreenVideo::GetModeInfo and IFullScreenVideo::IsModeAvailable. An application can enable and disable any mode by calling the IFullScreenVideo::SetEnabled method. The current value can be queried by calling IFullScreenVideo::IsModeEnabled. An application can enable or disable any mode by calling the IFullScreenVideo::SetEnabled flag with OATRUE or OAFALSE (not C/C++ TRUE and FALSE values).

The DirectShow full-screen renderer can function only when it is the foreground active window. If the user tries to switch to another application while in full-screen mode, the video will be hidden. The renderer does this by minimizing the window it is actually drawing the video in (although the use of a window is transparent to the user). Maximizing the window restores the video.

The filter graph manager uses the full-screen renderer to help implement the full-screen property that can be set through IVideoWindow::put_FullScreenMode. When used in this manner, the expected behavior is to switch seamlessly between full-screen mode and then back into normal window playback when the user presses ESC or other escape sequences. In this case, the renderer is required to hide its window rather than minimize it when switching away from it. The renderer can be made to hide rather than minimize (the default action) by calling IFullScreenVideo::HideOnDeactivate.

Implement this interface if you are writing an alternate full-screen video renderer. The Microsoft full-screen video renderer implements this interface by default.

Use this interface from any application that must interact with the full-screen video renderer in order to set or determine video modes or other full-screen renderer properties.

Methods in Vtable Order

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

IFullScreenVideo methods Description
CountModes Retrieves the number of modes available on the full-screen renderer.
GetModeInfo Retrieves information about a specified mode.
GetCurrentMode Retrieves the video mode currently in effect.
IsModeAvailable Determines if a specified video mode is available.
IsModeEnabled Determines if a specified video mode is enabled.
SetEnabled Enables and disables video modes.
GetClipFactor Retrieves the current clip loss factor setting.
SetClipFactor Specifies the video mode based on the maximum image area that will be lost.
SetMessageDrain Specifies a window that will receive window messages sent to the renderer.
GetMessageDrain Retrieves the window set to receive window messages sent to the renderer.
SetMonitor Sets the monitor in use (for use with multiple-monitor implementations).
GetMonitor Retrieves the monitor in use.
HideOnDeactivate Hides the window when it is deactivated.
IsHideOnDeactivate Retrieves the state of the HideOnDeactivate property.
SetCaption Sets the caption associated with the full-screen window.
GetCaption Retrieves the caption associated with the full-screen window.
SetDefault Sets the default for all full-screen video renderer properties.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IFullScreenVideo methods	Description
CountModes	Retrieves the number of modes available on the full-screen renderer.
GetModeInfo	Retrieves information about a specified mode.
GetCurrentMode	Retrieves the video mode currently in effect.
IsModeAvailable	Determines if a specified video mode is available.
IsModeEnabled	Determines if a specified video mode is enabled.
SetEnabled	Enables and disables video modes.
GetClipFactor	Retrieves the current clip loss factor setting.
SetClipFactor	Specifies the video mode based on the maximum image area that will be lost.
SetMessageDrain	Specifies a window that will receive window messages sent to the renderer.
GetMessageDrain	Retrieves the window set to receive window messages sent to the renderer.
SetMonitor	Sets the monitor in use (for use with multiple-monitor implementations).
GetMonitor	Retrieves the monitor in use.
HideOnDeactivate	Hides the window when it is deactivated.
IsHideOnDeactivate	Retrieves the state of the HideOnDeactivate property.
SetCaption	Sets the caption associated with the full-screen window.
GetCaption	Retrieves the caption associated with the full-screen window.
SetDefault	Sets the default for all full-screen video renderer properties.

IFullScreenVideo::CountModes

IFullScreenVideo Interface

Retrieves the number of modes available on the full-screen renderer.

Syntax

HRESULT CountModes(
    long *pModes
);

Parameters

pModes
[out] Pointer to the returned mode count.

Return Value

Returns an HRESULT value.

Remarks

The DirectShow full-screen renderer supports eight modes (320 × 200 × 8/16 bit, 320 × 240 × 8/16, 640 × 400 × 8/16, and 640 × 480 × 8/16). The lower-resolution modes are always chosen over the higher modes. An application can enable and disable specific modes to more accurately specify which ones are available for use. A slightly less fine-grained mechanism to affect the selected mode is available through the clip loss factor.

IFullScreenVideo::GetCaption

IFullScreenVideo Interface

Retrieves the caption associated with the full-screen window.

Syntax

HRESULT GetCaption(
    BSTR *pstrCaption
);

Parameters

pstrCaption
[out] Pointer to the retrieved caption.

Return Value

Returns an HRESULT value.

Remarks

The DirectShow full-screen renderer will show itself as an icon when it is deactivated (you can deactivate it by pressing ALT+TAB to switch away from it). The text caption for the icon can be set through this method. If the renderer is supposed to hide itself when deactivated, this method will succeed, although it will have no use because the window will never be shown as an icon.

IFullScreenVideo::GetClipFactor

IFullScreenVideo Interface

Retrieves the current clip loss factor setting.

Syntax

HRESULT GetClipFactor(
    long *pClipFactor
);

Parameters

pClipFactor
[out] Pointer to the maximum allowable amount of the image to lose.

Return Value

Returns an HRESULT value.

Remarks

For a description of the clip loss factor setting, see IFullScreenVideo::SetClipFactor.

IFullScreenVideo::GetCurrentMode

IFullScreenVideo Interface

Retrieves the video mode currently in effect.

Syntax

HRESULT GetCurrentMode(
    long *pMode
);

Parameters

pMode
[out] Pointer to the retrieved full-screen video mode.

Return Value

Returns an HRESULT value.

Remarks

When the full-screen video renderer is connected, it chooses a display mode to use for video playback. The selected mode can be retrieved through this method. The details for that mode can then be retrieved by using IFullScreenVideo::GetModeInfo.
For a list of available modes for the DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

IFullScreenVideo::GetMessageDrain

IFullScreenVideo Interface

Retrieves the window set to receive window messages sent to the renderer.

Syntax

HRESULT GetMessageDrain(
    HWND *hwnd
);

Parameters

hwnd
[out] Pointer to the window handle of the window specified as the message drain.

Return Value

Returns an HRESULT value.

Remarks

The full-screen video renderer posts all mouse and keyboard messages it receives to the window designated as a message drain, with the message parameters untranslated. The exact list of messages passed is the same as for IVideoWindow::put_MessageDrain. An application can use this to implement hot-key support for full-screen video. For example, it might watch for the CTRL+P key combination as a cue to pause the video.

IFullScreenVideo::GetModeInfo

IFullScreenVideo Interface

Retrieves information about a specified mode.

Syntax

HRESULT GetModeInfo(
    long Mode,
    long *pWidth,
    long *pHeight,
    long *pDepth
);

Parameters

Mode
[in] Specified mode for which to retrieve information.
pWidth
[out] Pointer to the width, in pixels, of the mode's image display.
pHeight
[out] Pointer to the height, in pixels, of the mode's image display.
pDepth
[out] Pointer to the number of color bits per pixel.

Return Value

Returns an HRESULT value.

Remarks

This method returns the height, width, and color depth for a given mode that the renderer has available. The number of display modes available can be retrieved through IFullScreenVideo::CountModes.
For a list of modes available to the DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

IFullScreenVideo::GetMonitor

IFullScreenVideo Interface

Retrieves the monitor type in use.

Syntax

HRESULT GetMonitor(
    long *Monitor
);

Parameters

Monitor
[out] Pointer to the monitor currently in use.

Return Value

Returns NOERROR.

Remarks

The DirectShow full-screen renderer always returns zero (the primary monitor).

IFullScreenVideo::HideOnDeactivate

IFullScreenVideo Interface

Hides the window icon when the full-screen window is deactivated.

Syntax

HRESULT HideOnDeactivate(
    long Hide
);

Parameters

Hide
[in] Value specifying whether to hide the video window icon when the full-screen window is deactivated. Set to OATRUE to hide the icon; set to OAFALSE to display the icon.

Return Value

Returns NOERROR if successful and E_INVALIDARG if Hide is invalid.

Remarks

The default setting for the DirectShow full-screen renderer is OATRUE.
The full-screen renderer can function only when it is the foreground active window. If the user tries to switch to another application while in full-screen mode, the video will be hidden. The renderer does this by minimizing the window it is actually drawing the video in (although the use of a window is transparent to the user). Maximizing the window restores the video. If this property is set, the window will be hidden rather than minimized.

IFullScreenVideo::IsHideOnDeactivate

IFullScreenVideo Interface

Retrieves the state of the IFullScreenVideo::HideOnDeactivate property.

Syntax

HRESULT IsHideOnDeactivate(void);

Return Value

Returns S_OK if HideOnDeactivate is set to OATRUE or S_FALSE if it is set to OAFALSE.

IFullScreenVideo::IsModeAvailable

IFullScreenVideo Interface

Determines if a specified video mode is available.

Syntax

HRESULT IsModeAvailable(
    long Mode
);

Parameters

Mode
[in] Full-screen mode to check.

Return Value

Returns S_OK if the video mode is available or S_FALSE if it isn't.

Remarks

The display modes supported by the DirectShow full-screen renderer are different than the actual modes available on any given display card. The application should call this method only when the renderer is connected, because until then the renderer might not have allocated the resources it needs to make this information available. Even if a mode is available, it will not necessarily be used for video playback; the mode must also be compatible with the filters in the filter graph.

IFullScreenVideo::IsModeEnabled

IFullScreenVideo Interface

Determines if a specified mode is enabled.

Syntax

HRESULT IsModeEnabled(
    long Mode
);

Parameters

Mode
[in] Full-screen video mode to check.

Return Value

Returns S_OK if the video mode is enabled or S_FALSE if it isn't.

Remarks

You can use this method to enable and disable specific display modes supported by the renderer. Even if a mode is enabled, it will not necessarily be used for video playback; the mode must also be compatible with the filters in the filter graph.
For a list of available modes for the DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

IFullScreenVideo::SetCaption

IFullScreenVideo Interface

Sets the title associated with the full-screen window.

Syntax

HRESULT SetCaption(
    BSTR strCaption
);

Parameters

strCaption
[in] String containing the caption.

Return Value

Returns an HRESULT value.

IFullScreenVideo::SetClipFactor

IFullScreenVideo Interface

Specifies the video mode based on the maximum data that will be lost.

Syntax

HRESULT SetClipFactor(
    long ClipFactor
);

Parameters

ClipFactor
[in] Maximum allowable amount of the image to lose.

Return Value

Returns an HRESULT value.

Remarks

Clip loss factor is a means of enabling full-screen modes that is more generic and easier for applications to use. This method defines the amount of video that can be lost when deciding which display mode to use. For example, assuming the decoder cannot compress the video, playing an MPEG file (say 352 × 288 pixels) into a 320 × 200 display will lose about 25 percent of the image. The clip loss factor specifies the upper range permissible. To allow typical QCIF-sized MPEG video (352 × 288 pixels) to be played in a 320 × 200 display mode, it defaults to 25 percent.

IFullScreenVideo::SetDefault

IFullScreenVideo Interface

Sets the default full-screen video renderer settings.

Syntax

HRESULT SetDefault(void);

Return Value

Returns an HRESULT value.

Remarks

The properties set through this interface apply only to the current renderer instance. They can, however, be made the global default by calling this interface method.

IFullScreenVideo::SetEnabled

IFullScreenVideo Interface

Enables and disables video modes.

Syntax

HRESULT SetEnabled(
    long Mode,
    long bEnabled
);

Parameters

Mode
[in] Mode to be enabled or disabled (see the following table).
bEnabled
[out] Can be set to one of the following values.

OATRUE Enable mode.
OAFALSE Disable mode.

Return Value

Returns an HRESULT value.

Remarks

Available DirectShow modes are defined as follows. The ordering of these modes is subject to change, so use IFullScreenVideo::CountModes and IFullScreenVideo::GetModeInfo interface methods to enumerate modes.

Mode Width Height RGB depth (in bits)

0 320 200 16

1 320 200 8

2 320 240 16

3 320 240 8

4 640 400 16

5 640 400 8

6 640 480 16

7 640 480 8

8 800 600 16

9 800 600 8

10 1024 768 16

11 1024 768 8

12 1152 864 16

13 1152 864 8

14 1280 1024 16

15 1280 1024 8

Mode	Width	Height	RGB depth (in bits)
0	320	200	16
1	320	200	8
2	320	240	16
3	320	240	8
4	640	400	16
5	640	400	8
6	640	480	16
7	640	480	8
8	800	600	16
9	800	600	8
10	1024	768	16
11	1024	768	8
12	1152	864	16
13	1152	864	8
14	1280	1024	16
15	1280	1024	8

IFullScreenVideo::SetMessageDrain

IFullScreenVideo Interface

Specifies a window that will receive window messages sent to the renderer.

Syntax

HRESULT SetMessageDrain(
    HWND hwnd
);

Parameters

hwnd
[in] Window handle of the message drain window.

Return Value

Returns an HRESULT value.

Remarks

The full-screen video renderer posts all mouse and keyboard messages it receives to the window designated as a message drain, with the message parameters untranslated. The exact list of messages passed is the same as for IVideoWindow::put_MessageDrain. An application can use this to implement hot-key support for full-screen video. For example, it might watch for the CTRL+P key combination as a cue to pause the video.

IFullScreenVideo::SetMonitor

IFullScreenVideo Interface

Sets the monitor type in use.

Syntax

HRESULT SetMonitor(
    long Monitor
);

Parameters

Monitor
[in] Monitor currently in use.

Return Value

Returns an HRESULT value.

Remarks

Setting this method to anything but the primary display (0) will return an error. In future versions of DirectShow, the renderer might allow applications to select the monitor on which to play back the full-screen video.