Windows Media Player 11 SDK About SetRects (deprecated)
.gif)
| Previous | Next |
About SetRects (deprecated)
This page documents a feature that may be unavailable in future versions of Windows Media Player and the Windows Media Player SDK.
When a plug-in renders in windowed mode and the rendering region is hosted in the Windows Media Player user interface, the Player must convey to the plug-in a set of values that describe the size and location of the portion of the rendering region that must be updated by the plug-in. The plug-in requests a particular region size when the Player calls the plug-in implementation of IWMPNodeRealEstate::GetDesiredSize by returning a pointer to a SIZE structure representing the desired size for the rendering region. The Player attempts to honor this request to the extent possible, but there is no guarantee that the ultimate region size will equal the requested size, so the plug-in must account for this possibility.
The Player notifies the plug-in about the actual region to be updated by calling the plug-in implementation of IWMPNodeRealEstate::SetRects. Here, the Player provides three pointers to RECT structures: pSrc, pDest, and pClip. For clarity, this section refers to these three RECTs as source rectangle, destination rectangle, and clipping rectangle. Together, these three rectangles are used to resize and to reposition the plug-in window so that it exactly corresponds to the region to be updated. That way, the plug-in can update the rendering region by painting in its window.
The source rectangle represents the portion of the original image to be rendered. The size of this rectangle does not have to equal the dimensions of the original area requested by the plug-in. The origin of the source rectangle can be any set of values specified by the Player. This rectangle is stored in the member variable named m_rctSrc. The following diagram shows the relationship between the video frame and the source rectangle.
.gif)
The destination rectangle is provided with an origin that represents positioning relative to the owner window and a size that represents stretching or shrinking relative to the source rectangle. This means that the destination rectangle is proportional to the source rectangle, but may be smaller, larger, or the same size, depending on conditions in the Player UI. The destination rectangle origin will always consist of a pair of values each greater than or equal to zero. This rectangle is stored in the member variable named m_rctDest.
The clipping rectangle represents the portion of the Windows Media Player video display that should actually be visible to the user. This rectangle is stored in the member variable named m_rctClip.
You can use these three rectangles to determine the size of the plug-in window and where to position it. To accomplish this, the rendering plug-in generated by the wizard creates two additional rectangles (each in a RECT structure) using the information conveyed in the three provided rectangles. The two new rectangles are:
- The window position rectangle. This rectangle represents the location and size of the plug-in window. Its size is given by the intersection of the destination rectangle and the clipping rectangle. This means that the size of the window position rectangle can, and will, change frequently. Its size does not have to equal the size of the entire region being displayed. It is stored in the member variable named m_rctWindowPos.
- The display area rectangle. This rectangle has the same dimensions as the destination rectangle, but its origin is recalculated to be relative to the origin of the plug-in window. Because the window position rectangle is always located within the destination rectangle, the display area rectangle may have an origin comprised of negative values. It is stored in the member variable named m_rctDisplay.
The following diagram illustrates the relationship between the rectangles.
.gif)
The sample plug-in renders by using the StretchBlt function to copy the bitmap to be rendered from the source rectangle to the display rectangle. Because the region to be updated (the plug-in window when rendering in windowed mode) is always contained within the display rectangle, and the display area rectangle may have an origin comprised of negative values, the operating system simply discards the portion of the bitmap that falls outside the rendering region.
You can add tracing code to your implementation of SetRects to print information to the Visual Studio debug window about the supplied and calculated rectangles. That way, you can observe and study this output to learn more about the behavior of the rectangles. It is particularly interesting to resize the Player during playback to see how the rectangles change as the rendering region moves, stretches, and shrinks. You should try this with different settings in the Player for fitting the video to the Player on resize as well.
See Also
| Previous | Next |