The IDirectDrawMediaStream interface controls media streams that display on Microsoft DirectDraw® surfaces. To stream to a DirectDraw surface, DirectDraw must support the video stream format.
For sample code which implements the multimedia streaming interfaces see Multimedia Streaming Sample Code.
When to Implement
This interface isn't intended for implementation by application developers. It is exposed on DirectDraw media streams that can be added to a DirectShow multimedia stream.
When to Use
Use this interface when you want to output a video stream to a DirectDraw surface.
Methods in Vtable Order
| IUnknown methods | Description |
| QueryInterface | Retrieves pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| IDirectDrawMediaStream methods | Description |
| GetFormat | Retrieves the current media stream's format and, optionally, its desired format. |
| SetFormat | Sets the current media stream's format. If the stream already has allocated samples and the sample format doesn't match the specified format, this method fails. |
| GetDirectDraw | Retrieves a pointer to the DirectDraw object used by the current media stream. |
| SetDirectDraw | Sets the current media stream's DirectDraw object. |
| CreateSample | Creates a stream sample using the specified DirectDraw surface object. |
| GetTimePerFrame | Retrieves the average frames per second from a video stream. |
Creates a stream sample using the specified DirectDraw surface object.
HRESULT CreateSample(
IDirectDrawSurface* pSurface,
const RECT *pRect,
DWORD dwFlags,
IDirectDrawStreamSample** ppSample
)
Returns one of the following values.
| Value | Meaning |
| DDERR_INVALIDPIXELFORMAT | The specified pixel format is incompatible with the stream format. |
| DDERR_INVALIDRECT | The specified clipping rectangle is invalid. |
| DDERR_INVALIDSURFACETYPE | The specified surface is incompatible with the stream format. |
| E_POINTER | One or more of the required parameters is invalid. |
| MS_E_SAMPLEALLOC | The stream already has allocated samples and the surface doesn't match the sample format. |
| S_OK | Success. |
This method creates a sample from the current stream and attaches the sample to this surface.
If the stream doesn't have an allocated surface and the specified surface doesn't match the stream's format, this method calls the IDirectDrawMediaStream::SetFormat method on the stream so the two will match.
To perform a progressive render, create a single sample and repeatedly use that sample for successive frames of video. Video decompressors use this technique to do partial updates to the previous frame.
Note, the pRect parameter should match the format of the stream (see IDirectDrawMediaStream::GetFormat). If the wrong clip rectangle is set or no clip rectangle is set, and the surface size does not match the movie size, the movie may not play. If a primary surface is used it is advisable to use a clipping rectangle because the primary surface size may change if the user changes their display settings.
Retrieves a pointer to the DirectDraw object used by the current media stream.
HRESULT GetDirectDraw(
IDirectDraw** ppDirectDraw
)
Returns S_OK if successful or E_POINTER if the parameter is invalid.
If you haven't initialized the stream yet, the retrieved pointer will be null and the method will return S_OK. If you have initialized the stream, this method increments the retrieved pointer's reference count.
Retrieves the current media stream's format and, optionally, its desired format.
HRESULT GetFormat(
DDSURFACEDESC *pDDSDCurrent,
IDirectDrawPalette **ppDirectDrawPalette,
DDSURFACEDESC *pDDSDDesired,
DWORD* pdwFlags
)
| Value | Meaning |
| DDSD_HEIGHT | Indicates that the height member of the structure is valid. |
| DDSD_WIDTH | Indicates that the width member of the structure is valid. |
| DDSD_PIXELFORMAT | Indicates that the pixel format member of the structure is valid. |
| DDSD_CAPS | Indicates that the surface capability member of the structure is valid. |
Returns one of the following values.
| Value | Meaning |
| DDERR_INVALIDPARAMS | One of the DirectDraw surface parameters is invalid. |
| E_POINTER | One or more of the required parameters is invalid. |
| S_OK | Success. |
After you call this method, you can either conform to the current format or attempt to change the format by calling the IDirectDrawMediaStream::SetFormat method.
All of this method's parameters are optional; set any of them to NULL to indicate that you don't want to retrieve that information.
To perform a progressive render, create a single sample and repeatedly use that sample for successive frames of video. Video decompressors use this technique to do partial updates to the previous frame.
You are responsible for initializing the dwSize field of the DDSURFACEDESC structure before calling this method.
The DDSD_CAPS flag will return one of the values listed in the DDSCAPS structure or DDSCAPS_DATAEXCHANGE which is defined as DDSCAPS_SYSTEMMEMORY|DDSCAPS_VIDEOMEMORY in ddrawex.h.
Retrieves the average frames per second from a video stream.
HRESULT GetTimePerFrame(
STREAM_TIME *pFrameTime
)
Returns S_OK if successful or E_POINTER if the pointer is invalid.
Sets the current media stream's DirectDraw object.
HRESULT SetDirectDraw(
IDirectDraw* pDirectDraw
)
Returns S_OK if successful.
This method fails if the current stream already has allocated samples and its DirectDraw object differs from the specified one. It will always succeed if the specified DirectDraw object matches the stream's current object.
If this stream has no allocated samples, you can set pDirectDraw to NULL. This forces the stream to release its reference to the current DirectDraw object.
Sets the format of the current media stream.
HRESULT SetFormat(
const DDSURFACEDESC *pDDSurfaceDesc,
IDirectDrawPalette *pDirectDrawPalette
)
Returns one of the following values.
| Value | Meaning |
| S_OK | Success. |
| DDERR_INVALIDSURFACETYPE | The specified format is incompatible with the current stream. |
| MS_E_SAMPLEALLOC | Can't change the format because one or more stream samples are already allocated for this stream. |
If the stream already has allocated samples and the sample format doesn't match the specified format, this method fails. This method always succeeds if the specified format matches the current format.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.