DirectDraw Exclusive Mode Video Playback Capability ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ General Information: ==================== Now video can be played back from AVI, MPEG files as well as DVD titles even in DirectDraw exclusive fullscreen mode. This is expected to be very helpful to games and interactive content development. The DirectX Media 6.0 SDK includes various components that together offers this capability. An updated Overlay Mixer filter in DirectShow is now capable of using a DirectDraw object and primary surface provided by an application rather than insisting on using its own. A new COM interface, IDDrawExclModeVideo, has been added on the Overlay Mixer filter which allows applications to specify DirectDraw parameters and playback position, size etc. An app can do QueryInterface() on the Overlay Mixer filter to get the interface. This interface is fully documented in the SDK help documentation. Also another new COM interface, IDDrawExclModeVideoCallback, has been defined in the SDK. An application should implement an object that supports this interface to have a notification set up with the OverlayMixer about any changes to the overlay size, position, color key etc. This callback mechanism allows any color key flashes and/or strips to be avoided. We have also updated the DVD graph builder object and some methods of the IDvdGraphBuilder interface which allows applications to use the updated DVD graph builder object to pass the DirectDraw-related information to the Overlay Mixer for use in DVD playback filter graph building operation. Using a couple of other methods available on the IDDrawExclModeVideo interface, applications can get the color key information for super-imposing graphics on top of video playing in the background. All these changes have been fully documented in the SDK help. A sample application, DDrawXcl, has also been added to the SDK samples. This application consists of * a DirectDraw object (DDrawObj.h, .cpp) that wraps all DirectDraw functionality using IDirectDraw* COM interfaces as well IDDrawExclModeVideo interface. * a video playback object (VidPlay.h, .cpp) that implements the details of building a filter graph to playback AVI/MPEG files as well as DVD titles. * an overlay notification sink object that receives the overlay change related callbacks from OverlayMixer and takes appropriate actions. * a Windows app that uses the above objects to: - go into fullscreen exclusive mode, switch to 800x600x8 (just picked one particular mode), create a primary surface with one back buffer. - build a filter graph to playback the selected type of video using the DirectDraw object and surface provided by the application, starts playing it and sets a timer to fire every 0.1 second. - on the timer event, the application draws color key of the required dimension on the back buffer, draws a ball that can be moved using keystrokes, draws an updated number (of flips done) and flips the surfaces. - the callback notification object informs the DDraw object when color keying of the video area should be started/stopped. This we believe is what is one of the basic requirements for games and interactive contents to playback video using DirectShow inside the application. The Limitations/Rules: ====================== 1. The sequence of calls to get the application-created DirectDraw parameters to be used by OverlayMixer is as follows -- For DVD: - create the DVD graph builder object - call IDvdGraphBuilder::GetDvdInterface() for IDDrawExclModeVideo interface. This returns the IDDrawExclModeVideo interface of the OverlayMixer in the DVD playback filter graph. - call IDDrawExclModeVideo::SetDDrawObject() to set the DDraw object - call IDDrawExclModeVideo::SetDDrawSurface() to set the DDraw surface - call IDvdGraphBuilder::RenderDvdVideoVolume() to build DVD graph - call IDvdGraphBuilder::GetDvdInterface() to get IMixerPinConfig(2) interface pointer to the FIRST (only) input pin of the OverlayMixer. - get color key etc info using IMixerPinConfig(2)::GetColorKey() etc. method. Also set the aspect ratio mode to stretching from the default letter box mode of the OverlayMixer. - call IDDrawExclModeVideo::SetCallbackInterface() with the pointer to the object implementing the IDDrawExclModeVideoCallback interface. - get the native video size and aspect ratio through IDDrawExclModeVideo::GetNativeVideoProps() method, transform the width and height based on the retrieved aspect ratio, and set the final video size and position using IDDrawExclModeVideo::SetDDrawParameters() method. For AVI/MPEG: - create an empty filter graph - call IGraphBuilder::RenderFile() on the specified file to build graph. - instantiate the OverlayMixer filter and add it to the graph. - call IDDrawExclModeVideo::SetDDrawObject() - call IDDrawExclModeVideo::SetDDrawSurface() - connect the decoded video to the Overlay Mixer's first input pin - remove the Video Renderer filter as it's a windowless playback case. - get IMixerPinConfig(2) interface from the first input pin of the OverlayMixer to get the color key through GetColorKey() method. Also set the aspect ratio mode to stretching from the default letter box mode of the OverlayMixer. - call IDDrawExclModeVideo::SetCallbackInterface() with the pointer to the object implementing the IDDrawExclModeVideoCallback interface. - get the native video size and aspect ratio through IDDrawExclModeVideo::GetNativeVideoProps() method, transform the width and height based on the retrieved aspect ratio, and set the final video size and position using IDDrawExclModeVideo::SetDDrawParameters() method. 2. The object implementing IDDrawExclModeVideoCallback interface has been kept very simple. It stops color keying of the video area on the back buffer when it gets the OnUpdateOverlay() call with input parameter bBefore=TRUE. The color keying is turned on again on getting another OnUpdateOverlay() call with bBefore=FALSE and the dwFlags indicating that the overlay is visible. 3. The SetDDraw*() methods can be called only when the pins of the Overlay Mixer are not connected. Otherwise the calls will fail. 4. The application has to draw colorkey at the right position on the (back buffer of the) primary surface to get the video to show up. In the exclusive mode, the Overlay Mixer doesn't draw color key at all. 5. For DVDs, the subpicture and line21 (closed caption) data are intentionally not rendered in the exclusive mode. The DVD graph builder will not return S_FALSE for this only. Known Issues: ============= 1. The ball drawn on top of the video only moves when an arrow key is pressed AND released. Holding the arrow key down doesn't move the ball. This was a conscious decision made for the sample application. 2. The application stops playing the video and tears down the filter graph when it switches to non exclusive mode on getting an Alt-Tab keystroke. The playback is not resumed on activating the application. 3. The application fills the whole back buffer with black color and then Blts the color key to the target video rectangle. This is not required unless the video is continually changing position. For video playing at the same position, just erasing the previous position of the ball with color key should be sufficient. The comment at the top of the CDDrawObject::FillSurface() method should hopefully not cause any confusion. 4. Some AVI files (MS-CRAM, Duck compressed) fails to connect to the OverlayMixer filter on some display cards. This causes the sample app to fail in building the graph. As a result such files cannot be played back on some systems.