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. |
Retrieves the number of modes available on the full-screen renderer.
HRESULT CountModes(
long *pModes
);
Returns an HRESULT value.
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.
Retrieves the caption associated with the full-screen window.
HRESULT GetCaption(
BSTR *pstrCaption
);
Returns an HRESULT value.
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.
Retrieves the current clip loss factor setting.
HRESULT GetClipFactor(
long *pClipFactor
);
Returns an HRESULT value.
For a description of the clip loss factor setting, see IFullScreenVideo::SetClipFactor.
Retrieves the video mode currently in effect.
HRESULT GetCurrentMode(
long *pMode
);
Returns an HRESULT value.
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.
Retrieves the window set to receive window messages sent to the renderer.
HRESULT GetMessageDrain(
HWND *hwnd
);
Returns an HRESULT value.
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.
Retrieves information about a specified mode.
HRESULT GetModeInfo(
long Mode,
long *pWidth,
long *pHeight,
long *pDepth
);
Returns an HRESULT value.
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.
Retrieves the monitor type in use.
HRESULT GetMonitor(
long *Monitor
);
Returns NOERROR.
The Microsoft DirectShow full-screen renderer always returns zero (the primary monitor).
Hides the window icon when the full-screen window is deactivated.
HRESULT HideOnDeactivate(
long Hide
);
Returns NOERROR if successful and E_INVALIDARG if Hide is invalid.
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.
Retrieves the state of the IFullScreenVideo::HideOnDeactivate property.
HRESULT IsHideOnDeactivate(void);
Returns S_OK if HideOnDeactivate is set to OATRUE or S_FALSE if it is set to OAFALSE.
Determines if a specified video mode is available.
HRESULT IsModeAvailable(
long Mode
);
Returns S_OK if the video mode is available or S_FALSE if it isn't.
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.
Determines if a specified mode is enabled.
HRESULT IsModeEnabled(
long Mode
);
Returns S_OK if the video mode is enabled or S_FALSE if it isn't.
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.
IFullScreenVideo::IsModeAvailable
Sets the title associated with the full-screen window.
HRESULT SetCaption(
BSTR strCaption
);
Returns an HRESULT value.
Specifies the video mode based on the maximum data that will be lost.
HRESULT SetClipFactor(
long ClipFactor
);
Returns an HRESULT value.
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.
Sets the default full-screen video renderer settings.
HRESULT SetDefault(void);
Returns an HRESULT value.
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.
Enables and disables video modes.
HRESULT SetEnabled(
long Mode,
long bEnabled
);
Value | Meaning |
OATRUE | Enable mode. |
OAFALSE | Disable mode. |
Returns an HRESULT value.
Microsoft DirectShow available 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 | 8 |
1 | 320 | 200 | 16 |
2 | 320 | 240 | 8 |
3 | 320 | 240 | 16 |
4 | 640 | 400 | 8 |
5 | 640 | 400 | 16 |
6 | 640 | 480 | 8 |
7 | 640 | 480 | 16 |
Specifies a window that will receive window messages sent to the renderer.
HRESULT SetMessageDrain(
HWND hwnd
);
Returns an HRESULT value.
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.
Sets the monitor type in use.
HRESULT SetMonitor(
long Monitor
);
Returns an HRESULT value.
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.