The IVideoWindow interface supports the video window properties of a video renderer. It is a dual interface (accessible through Microsoft® Visual Basic® and Visual C++®) that controls a generic video window. Generally, this is a video renderer that draws video into a window on the display. The IVideoWindow interface supports both properties and methods. Properties are more easily accessible from many Automation controllers (such as Microsoft Visual Basic). However, some operations require several properties to be changed simultaneously; for this reason, methods are provided that allow a number of related properties to be changed simultaneously. For example, setting the window's position and size can be done by four individual put_[property name] calls or by the single method SetWindowPosition.
The methods require only that the video renderer be connected. If it is not connected, all the interface functions return VFW_E_NOT_CONNECTED. Properties set on a video renderer persist between successive connections and disconnections. All applications should ensure that they reset the renderer properties before starting a presentation.
Because this interface is Automation-compatible, there are two important aspects to remember about parameters accepted by these methods. First, all Boolean returns are OAFALSE (0) or OATRUE (–1), which is different from the C or C++ definition. Second, all strings are defined as being of type BSTR. All strings sent to the interface should be allocated through the OLE SysAllocString function, and similarly all strings returned from the interface should be freed by using the OLE SysFreeString function.
When to Implement
The video renderer filter supplied with Microsoft DirectShow™ implements this interface. It is also implemented by the filter graph manager (via a plug-in distributor) to pass method calls from the application to the video renderer filter's implementation of the interface.
Implement this interface if you are writing a replacement video renderer filter. You can use the CBaseVideoWindow class, which handles the IDispatch implementation for Automation, to help implement this interface.
When to Use
This interface is used by applications or other filters that must control the video window's properties.
Methods in Vtable Order
| IUnknown methods | Description |
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| IDispatch methods | Description |
| GetTypeInfoCount | Determines whether there is type information available for this dispinterface. |
| GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully. |
| GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs. |
| Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters. |
| IVideoWindow methods | Description |
| put_Caption | Sets the text caption on the playback window. |
| get_Caption | Retrieves the text caption on the playback window. |
| put_WindowStyle | Sets the playback window style. |
| get_WindowStyle | Retrieves the playback window style. |
| put_WindowStyleEx | Sets the style of the control window. |
| get_WindowStyleEx | Retrieves the playback window's extended style bits. |
| put_AutoShow | Specifies if the window will be automatically shown on the first state change. |
| get_AutoShow | Returns if the window will be automatically shown on the first state change. |
| put_WindowState | Sets the current window state (such as visible or minimized). |
| get_WindowState | Retrieves the current window state (such as visible or minimized). |
| put_BackgroundPalette | Informs the renderer to realize its palette in the background. |
| get_BackgroundPalette | Returns whenever the renderer realizes its palette in the background. |
| put_Visible | Sets the visibility of the window. |
| get_Visible | Retrieves the visibility of the window. |
| put_Left | Sets the x-axis coordinate for the video window. |
| get_Left | Retrieves the x-axis coordinate for the video window. |
| put_Width | Sets the width of the video window. |
| get_Width | Retrieves the width of the video window. |
| put_Top | Sets the y-axis coordinates for the video window. |
| get_Top | Retrieves the y-axis coordinates for the video window. |
| put_Height | Sets the height of the video window. |
| get_Height | Retrieves the height of the video window. |
| put_Owner | Sets the owning parent window for the video playback window. |
| get_Owner | Retrieves the owning parent window for the video playback window. |
| put_MessageDrain | Specifies a window to which the video window will post messages. |
| get_MessageDrain | Retrieves the window set to receive messages from the video window. |
| get_BorderColor | Retrieves the border color for the video window. |
| put_BorderColor | Sets the border color for the video window. |
| get_FullScreenMode | Returns the full-screen rendering mode of the video renderer filter supporting this interface. |
| put_FullScreenMode | Sets the full-screen mode for the video renderer filter supporting this interface. |
| SetWindowForeground | Tells the renderer filter to become the foreground window. |
| NotifyOwnerMessage | Forwards messages that have been received by a parent window to a child window owned by a filter. |
| SetWindowPosition | Sets the video window position on the display. |
| GetWindowPosition | Retrieves the video window position. |
| GetMinIdealImageSize | Retrieves the ideal minimum image size for the video image playback (client) area. |
| GetMaxIdealImageSize | Retrieves the ideal maximum image size for the video image playback (client) area. |
| GetRestorePosition | Returns the normal restored window dimensions. |
| HideCursor | Hides the cursor. |
| IsCursorHidden | Determines if the cursor is hidden or showing. |
Retrieves information about whether the window will be automatically shown.
HRESULT get_AutoShow(
long *AutoShow
);
Returns an HRESULT value.
Retrieves information about whether any palette required will be realized in the background.
HRESULT get_BackgroundPalette(
long *pBackgroundPalette
);
Returns an HRESULT value.
Retrieves the border color for the video window.
HRESULT get_BorderColor(
long *pColor
);
Returns an HRESULT value.
Retrieves the textual title string for the video window.
HRESULT get_Caption(
BSTR *strCaption
);
Returns an HRESULT value.
Returns the full-screen rendering capabilities of the renderer filter supporting this interface.
HRESULT get_FullScreenMode(
long *FullScreenMode
);
Returns an HRESULT value.
This method is called by the filter graph manager when asked to render the video to full-screen size. If the renderer does not have inherent support for full-screen playback, it should return E_NOTIMPL. Otherwise, it should return NOERROR. If the renderer does support full-screen playback, this method determines if it is currently switched on or off.
Sets the height of the video window.
HRESULT get_Height(
long *pHeight
);
Returns an HRESULT value.
Retrieves the x-axis coordinate for the video window.
HRESULT get_Left(
long *pLeft
);
Returns an HRESULT value.
Retrieves the window set to receive messages from the video window.
HRESULT get_MessageDrain(
OAHWND *Drain
);
Returns an HRESULT value.
The IVideoWindow::put_MessageDrain description contains a list of the Microsoft Win32® messages passed to the window that is specified as a message drain.
Retrieves the owning parent for the video window.
HRESULT get_Owner(
OAHWND * pOwner
);
Returns an HRESULT value.
Retrieves the y-axis coordinate of the video window.
HRESULT get_Top(
long *pTop
);
Returns an HRESULT value.
Retrieves the visibility of the video window.
HRESULT get_Visible(
long *pVisible
);
Returns an HRESULT value.
Retrieves the width of the video window.
HRESULT get_Width(
long *pWidth
);
Returns an HRESULT value.
Returns the state of the video window.
HRESULT get_WindowState(
long *WindowState
);
Returns an HRESULT value.
This method retrieves a subset of the properties of the window state, specifically SW_MINIMIZE, SW_MAXIMIZE, SW_SHOW, or SW_HIDE. These have the same definitions as the Microsoft Win32 ShowWindow function.
Changes the style parameters for the video window.
HRESULT get_WindowStyle(
long *pWindowStyle
);
Returns an HRESULT value.
For a complete list of window styles, see the CreateWindow function in the Microsoft Win32 Software Development Kit (SDK).
Changes the style parameters for the video window.
HRESULT get_WindowStyleEx(
long * pWindowStyleEx
);
Returns an HRESULT value.
This function uses extended window styles. For a complete list of window styles, see the CreateWindow function in the Microsoft Win32 Software Development Kit (SDK).
Retrieves the ideal maximum image size for the video image playback (client) area.
HRESULT GetMaxIdealImageSize(
long *pWidth,
long *pHeight
);
Returns an HRESULT value.
Retrieves the ideal minimum image size for the video image playback (client) area.
HRESULT GetMinIdealImageSize(
long *pWidth,
long *pHeight
);
Returns an HRESULT value.
Returns the normal restored window dimensions.
HRESULT GetRestorePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);
Returns an HRESULT value.
When the window is maximized or minimized, the window position methods return the actual window size. This method returns the dimensions that the window would be when restored. It is useful for applications that want to save a window state while the window is maximized or minimized.
Retrieves the current window rectangle (not the client rectangle) in device coordinates.
HRESULT GetWindowPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);
Returns an HRESULT value.
This method has the same effect as individually calling the IVideoWindow::get_Left, IVideoWindow::get_Top, IVideoWindow::get_Width, and IVideoWindow::get_Height methods.
Hides the cursor.
HRESULT HideCursor(
long HideCursor
);
Returns an HRESULT value.
This method is typically used when the video renderer is in full-screen mode, where cursor display might be unwanted.
Determines if the cursor is hidden or showing.
HRESULT IsCursorHidden(
long * CursorHidden
);
Returns an HRESULT value.
This method is typically used when the video renderer is in full-screen mode, where cursor display might be unwanted.
Forwards messages that have been received by a parent window to a child window owned by a filter.
HRESULT NotifyOwnerMessage(
long hwnd,
long uMsg,
long wParam,
long lParam
);
Returns an HRESULT value.
This method should be used by windows that make a renderer window a child window. It forwards significant messages to the child window that the child window would not otherwise receive. This includes the following messages.
| WM_ACTIVATEAPP |
| WM_DEVMODECHANGE |
| WM_DISPLAYCHANGE |
| WM_PALETTECHANGED |
| WM_PALETTEISCHANGING |
| WM_QUERYNEWPALETTE |
| WM_SYSCOLORCHANGE |
Determines whether or not the window will be automatically shown.
HRESULT put_AutoShow(
long AutoShow
);
Returns an HRESULT value.
Many simple applications require a displayed window when a filter graph is set to the running state. AutoShow defaults to OATRUE so that when the graph changes state to paused or running, the window is visible (it also is set as the foreground window). It will remain visible on all subsequent state changes to paused or running. If you close the window while the stream is running, the window will not automatically reappear. If you stop and restart the stream, however, the window will automatically reappear.
Determines whether any palette required will be realized in the background.
HRESULT put_BackgroundPalette(
long BackgroundPalette
);
Returns an HRESULT value.
If this is OATRUE (–1), any palette required by the video is realized by the renderer in the background. This means that any colors the palette uses will change to their closest match in the display palette prior to drawing. This ensures that an application will not have its palette disturbed when playing a video. It does, however, impose severe performance penalties on the video and should not be used unless absolutely necessary. The default value for this property is OAFALSE.
Sets the border color for the video window.
HRESULT put_BorderColor(
long Color
);
Returns an HRESULT value.
When a destination rectangle that is set differs from the visible client area of the window, a border is exposed around the edge. This method allows an application to change the border color. It is set to black by default. Any nonsystem color passed in is converted to its closest match according to the current palette before being used (this is not an issue on true color devices). Setting this causes the window border to be repainted in the new color automatically.
Sets the textual title string for the video window.
HRESULT put_Caption(
BSTR strCaption
);
Returns an HRESULT value.
Sets the full-screen mode for the video renderer filter supporting this interface.
HRESULT put_FullScreenMode(
long FullScreenMode
);
Returns E_NOTIMPL if the video renderer doesn't support full-screen mode or NOERROR if it does.
This method allows an application to switch a full-screen renderer into and out of full-screen mode. The renderer's behavior when switched out of full-screen mode is implementation-dependent. The Microsoft full-screen renderer, for example, switches back to a window.
The IVideoWindow plug-in distributor in the filter graph manager implements full-screen renderer switching. It looks to see if any renderer in the graph supports a full-screen mode and, if not, will temporarily replace the renderer with the default DirectShow full-screen renderer. It calls IVideoWindow::GetMaxIdealImageSize to determine if a window can be made a topmost window and resized to the entire display. This is preferred to swapping renderers, because the filter graph might be using DirectDraw® overlays or a hardware decoder filter.
Sets the height of the video window.
HRESULT put_Height(
long Height
);
Returns an HRESULT value.
Calling this method does not affect the y-axis coordinate of the video window.
Sets the x-axis coordinate for the video window.
HRESULT put_Left(
long Left
);
Returns an HRESULT value.
Calling this method does not affect the video window's width.
Specifies a window to which the video window will post messages.
HRESULT put_MessageDrain(
OAHWND Drain
);
Returns an HRESULT value.
The video renderer passes messages to the specified message drain by calling the Microsoft Win32 PostMessage function. These messages allow you to write applications that include user interaction, such as applications that require mouse clicks on specific areas of the video display. An application can have a close relationship with the video window and know at certain time points to look for user interaction. When the renderer passes a message to the drain, it sends the parameters, such as the client-area coordinates, exactly as generated.
DirectShow passes the following messages to the window specified by the Drain parameter, if and when the application generates them.
| WM_KEYDOWN |
| WM_KEYUP |
| WM_LBUTTONDBLCLK |
| WM_LBUTTONDOWN |
| WM_LBUTTONUP |
| WM_MBUTTONDBLCLK |
| WM_MBUTTONDOWN |
| WM_MBUTTONUP |
| WM_MOUSEACTIVATE |
| WM_MOUSEMOVE |
| WM_NCLBUTTONDBLCLK |
| WM_NCLBUTTONDOWN |
| WM_NCLBUTTONUP |
| WM_NCMBUTTONDBLCLK |
| WM_NCMBUTTONDOWN |
| WM_NCMBUTTONUP |
| WM_NCMOUSEMOVE |
| WM_NCRBUTTONDBLCLK |
| WM_NCRBUTTONDOWN |
| WM_NCRBUTTONUP |
| WM_RBUTTONDBLCLK |
| WM_RBUTTONDOWN |
| WM_RBUTTONUP |
Because this member function does not make the message drain window a child window, applications with full-screen capabilities can use it.
Sets an owning parent for the video window.
HRESULT put_Owner(
OAHWND Owner
);
Returns an HRESULT value.
This method offers a way for applications to set the owner of the video window. This is often used when playing videos in compound documents. This method changes the parent of the renderer window and sets the WS_CHILD style for the video window.
To forward video window messages to the parent window, use the IVideoWindow::put_MessageDrain method, supplying the window handle of the parent window. This method does not post messages automatically.
After using this method to set the owner of a video window, you must reset the owner to NULL (by calling put_Owner(NULL)) before releasing the filter graph. Otherwise, messages will continue to be sent to this window and errors will likely occur when the application is terminated.
Sets the y-axis coordinate of the video window.
HRESULT put_Top(
long Top
);
Returns an HRESULT value.
Calling this method does not affect the height of the video window.
Changes the visibility of the video window.
HRESULT put_Visible(
long Visible
);
Returns an HRESULT value.
If the Visible parameter is set to OATRUE (–1), the window is shown. If it is set to OAFALSE (0), the window is hidden.
Sets the video window's width.
HRESULT put_Width(
long Width
);
Returns an HRESULT value.
Calling this method does not affect the video window's x-axis coordinate.
Sets the video window's state.
HRESULT put_WindowState(
long WindowState
);
Returns NOERROR.
This method is a wrapper for the Microsoft Win32 ShowWindow function. IVideoWindow::put_WindowState passes the WindowState parameter on to CBaseWindow::DoShowWindow, which in turn passes it on to ShowWindow. Hence, WindowState can be any value that is valid for ShowWindow.
Changes the style parameters for the video window.
HRESULT put_WindowStyle(
long WindowStyle
);
Returns an HRESULT value.
Use this property to change the overall style of the video window; for example, to remove the border and caption areas of the video window. It is a fairly thin wrapper on top of setting the GWL_STYLE value of the Microsoft Win32 GetWindowLong function and therefore must be treated with care. In particular, ensure that the current styles are first retrieved, and then the necessary bit fields are added or removed. With some exceptions (noted here), the acceptable flags are the same as those allowed by the Win32 CreateWindow function.
Do not use this method to affect the window size. For example, if the window is minimized, do not set the WS_MAXIMIZE style; doing so causes unpredictable results. Instead, use the IVideoWindow::put_WindowState method for maximizing or minimizing the window.
Any of the following styles return E_INVALIDARG.
| WS_DISABLED |
| WS_HSCROLL |
| WS_ICONIC |
| WS_MAXIMIZE |
| WS_MINIMIZE |
| WS_VSCROLL |
Sets the style of the control window.
HRESULT put_WindowStyleEx(
long pWindowStyleEx
);
Returns NOERROR.
This method uses EX window styles. For a complete list of extended window styles, see the CreateWindowEx function in the Microsoft Win32 Software Development Kit (SDK).
Use this property to change the overall style of the video window; for example, to remove the border and caption areas of the video window. It is a fairly thin wrapper on top of setting the GWL_STYLE value of the Microsoft Win32 GetWindowLong function and therefore must be treated with care. In particular, ensure that the current styles are first retrieved, and then the necessary bit fields are added or removed.
Note: Do not use the following window styles as they are not validated.
| WS_DISABLED |
| WS_HSCROLL |
| WS_ICONIC |
| WS_MAXIMIZE |
| WS_MINIMIZE |
| WS_VSCROLL |
With some exceptions (noted here), the acceptable flags are the same as those allowed by the Win32 CreateWindow function.
Moves the video window to the foreground and optionally gives it focus.
HRESULT SetWindowForeground(
long Focus
);
Returns one of the following values.
| Value | Meaning |
| NOERROR | The method succeeded. |
| E_INVALIDARG | Focus doesn't equal –1 or 0. |
| VFW_E_NOT_CONNECTED | The current filter isn't connected to a complete filter graph. |
Sets the position of the video window (not the client rectangle position) in device coordinates.
HRESULT SetWindowPosition(
long Left,
long Top,
long Width,
long Height
);
Returns an HRESULT value.
This method has the same effect as individually calling the IVideoWindow::put_Left, IVideoWindow::put_Top, IVideoWindow::put_Width, and IVideoWindow::put_Height methods.
Specify, in window coordinates, where the video should appear. For example, setting a destination of (100,50,200,400) positions the video playback at an origin of 100 pixels from the left of the client area and 50 pixels from the top, with an overall size of 200 x 400 pixels. If the video is smaller than this (or a source rectangle has been specified that is smaller than the video), it will be stretched appropriately. Similarly, if the video is larger than the destination rectangle, the video is compressed into the visible rectangle. There are fairly severe performance penalties if an application does not keep the source and destination rectangles the same size.
Under typical circumstances, when no destination rectangle has been set, the video fills the entire visible client window area (regardless of how much the user has stretched the window). Also, the destination rectangle properties correctly return the size of the video window client area.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.