IFullScreenVideo Interface

This interface allows 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.

When to Implement

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

When to Use

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	Returns 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.

HRESULT CountModes(
  long *pModes
  );

Parameters

pModes

[out] Returned mode count.

Return Values

Returns an HRESULT value.

Remarks

The Microsoft DirectShow full-screen renderer supports eight modes (320 x 200 x 8/16 bit, 320 x 240 x 8/16, 640 x 400 x 8/16, and 640 x 480 x 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.

HRESULT GetCaption(
  BSTR *pstrCaption
  );

Parameters

pstrCaption

[out] Retrieved caption.

Return Values

Returns an HRESULT value.

Remarks

The Microsoft 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.

HRESULT GetClipFactor(
  long *pClipFactor
  );

Parameters

pClipFactor

[out] Maximum allowable amount of the image to lose.

Return Values

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.

HRESULT GetCurrentMode(
  long *pMode
  );

Parameters

pMode

[out] Retrieved full-screen video mode.

Return Values

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 Microsoft DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

---

IFullScreenVideo::GetMessageDrain

IFullScreenVideo Interface

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

HRESULT GetMessageDrain(
  HWND *hwnd
  );

Parameters

hwnd

[out] Window handle of the window specified as the message drain.

Return Values

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.

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

Parameters

Mode

[in] Specified mode for which to retrieve information.

pWidth

[out] Width in pixels of the mode's image display.

pHeight

[out] Height in pixels of the mode's image display.

pDepth

[out] Number of color bits per pixel.

Return Values

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 Microsoft DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

---

IFullScreenVideo::GetMonitor

IFullScreenVideo Interface

Retrieves the monitor type in use.

HRESULT GetMonitor(
  long *Monitor
  );

Parameters

Monitor

[out] Monitor currently in use.

Return Values

Returns NOERROR.

Remarks

The Microsoft 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.

HRESULT HideOnDeactivate(
  long Hide
  );

Parameters

Hide

[in] Set to OATRUE to hide the video window icon when deactivated; set to OAFALSE to display the icon.

Return Values

Returns NOERROR if successful and E_INVALIDARG if Hide is invalid.

Remarks

The default setting for the Microsoft 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.

HRESULT IsHideOnDeactivate(void);

Return Values

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.

HRESULT IsModeAvailable(
  long Mode
  );

Parameters

Mode

[in] Full-screen mode to check.

Return Values

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

Remarks

The display modes supported by the Microsoft 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.

HRESULT IsModeEnabled(
  long Mode
  );

Parameters

Mode

[in] Full-screen video mode to check.

Return Values

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 Microsoft DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

See Also

IFullScreenVideo::IsModeAvailable

---

IFullScreenVideo::SetCaption

IFullScreenVideo Interface

Sets the title associated with the full-screen window.

HRESULT SetCaption(
  BSTR strCaption
  );

Parameters

strCaption

[in] String containing the caption.

Return Values

Returns an HRESULT value.

---

IFullScreenVideo::SetClipFactor

IFullScreenVideo Interface

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

HRESULT SetClipFactor(
  long ClipFactor
  );

Parameters

ClipFactor

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

Return Values

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 x 288 pixels) into a 320 x 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 x 288 pixels) to be played in a 320 x 200 display mode, it defaults to 25 percent.

---

IFullScreenVideo::SetDefault

IFullScreenVideo Interface

Sets the default full-screen video renderer settings.

HRESULT SetDefault(void);

Return Values

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.

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.

Value	Meaning
OATRUE	Enable mode.
OAFALSE	Disable mode.

Return Values

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

---

IFullScreenVideo::SetMessageDrain

IFullScreenVideo Interface

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

HRESULT SetMessageDrain(
  HWND hwnd
  );

Parameters

hwnd

[in] Window handle of the message drain window.

Return Values

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.

HRESULT SetMonitor(
  long Monitor
  );

Parameters

Monitor

[in] Monitor currently in use.

Return Values

Returns an HRESULT value.

Remarks

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

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page