Data Input and Rendering (deprecated)
This page documents a feature that may be unavailable in future versions of Windows Media Player and the Windows Media Player SDK.
Windows Media Player provides arbitrary data to rendering plug-ins through an input buffer allocated by the Player. Rendering plug-ins can then render data in the Windows Media Player video display region by using resources obtained during a prior negotiation with Windows Media Player. If Windows Media Player cannot provide space in its user interface for rendering, as in the case of an arbitrary data video stream combined with Windows Media-based video, then the plug-in must render in a separate window. Windows Media Player manages this negotiation by calling methods implemented by the plug-in.
To render data, a rendering plug-in requires a rectangle that defines the region on the Windows desktop in which the plug-in can draw, and a handle to a drawing resource. The plug-in must implement IWMPNodeRealEstate::GetDesiredSize to provide the Player with a pointer to a SIZE structure that represents the requested size of the rendering region required by the plug-in. In Windows, drawing rectangles are represented by RECT structures. Windows Media Player provides the plug-in three such structures by calling IWMPNodeRealEstate::SetRects. Together, these RECTs are used to calculate the dimensions and location of the rendering region provided by the Player. It is not guaranteed that requesting a particular size will result in the Player providing a rendering RECT of that size. The actual dimensions and location of the rendering region provided by the Player are determined by a variety of factors, such as whether the user has resized the user interface, whether the rendering is occurring in a skin or a webpage, and how the user has specified settings for sizing behaviors in the Player.
Because Windows Media Player can render in windowed or windowless mode, the plug-in must be able to render data using either a window handle or a device context handle. In either case, the plug-in should create its own window when instantiated. When rendering in windowed mode, this is the window where rendering takes place. When rendering in windowless mode, this window is hidden.
Windows Media Player calls IWMPNodeRealEstate::SetWindowless to notify the plug-in about which drawing state is the current one. When rendering in a window, the Player calls the plug-in implementation of IWMPNodeWindowed::SetOwnerWindow to provide a window handle for rendering. The plug-in sets this handle as the parent for the plug-in window.
Windows Media Player supplies data from the arbitrary data stream to the plug-in by calling IMediaObject::ProcessInput, passing a pointer to an IMediaBuffer object. The plug-in must keep a reference count on the buffer object until finished rendering the data in the buffer. Whenever the plug-in accesses the data in the buffer object, it must do so within a critical section to ensure that the Player does not change the data on a different thread.
After the plug-in has a reference to the data buffer, it causes the drawing region to be invalidated, to prompt a repainting of the region. In windowed mode, the plug-in calls the Windows GDI method InvalidateRect, followed by a call to UpdateWindow, which sends a WM_PAINT message to the rendering window. The plug-in handles the WM_PAINT message in its rendering window and then renders the data. In windowless mode, the plug-in must call IWMPNodeWindowlesshost::InvalidateRect. This causes Windows Media Player to invalidate the rendering region and then call the plug-in implementation of IWMPNodeWindowless::OnDraw. This method receives a device context handle and a pointer to a RECT structure for rendering. The plug-in can then use these to render the data. Since rendering the data requires access to the data buffer, rendering must take place within a critical section.
Rendering plug-ins don't provide an implementation for IMediaObject::ProcessOutput like other DMOs do. Simply returning E_NOTIMPL is sufficient because the Player doesn't require and can't accept any processed data from the plug-in. It is the job of the plug-in to perform all rendering functions.