IDirectDrawMediaStream Interface

The IDirectDrawMediaStream interface controls media streams that appear on Microsoft® DirectDraw® surfaces. To stream to a DirectDraw surface, DirectDraw must support the video stream format.

For sample code that implements the multimedia streaming interfaces, see Multimedia Streaming Sample Code.

This interface isn't intended for implementation by application developers. It is exposed on DirectDraw media streams that can be added to a Microsoft® DirectShow® multimedia stream.

Use this interface when you want to send 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.

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.

IDirectDrawMediaStream::CreateSample

IDirectDrawMediaStream Interface

Creates a stream sample using the specified DirectDraw surface object.

Syntax

HRESULT CreateSample(
    IDirectDrawSurface *pSurface,
    const RECT *pRect,
    DWORD dwFlags,
    IDirectDrawStreamSample **ppSample
    );

Parameters

pSurface
[in] Pointer to an existing DirectDraw surface.
pRect
[in] Pointer to the clipping rectangle you want to use with the specified surface. Set this parameter to NULL if you want to use the entire surface.
dwFlags
[in] Flag that specifies whether the render should be progressive. To perform a progressive render, set this value to DDSFF_PROGRESSIVERENDER. If you don't set this flag, sample updates will copy the sample data to the surface.
ppSample
[out] Address of a pointer to an IDirectDrawStreamSample interface that will point to the newly created sample.

Return Value

Returns one of the following values.

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.

Remarks

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.
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 might not play. If a primary surface is used, it is advisable to use a clipping rectangle because the primary surface size can change if the user changes display settings.

IDirectDrawMediaStream::GetDirectDraw

IDirectDrawMediaStream Interface

Retrieves a pointer to the DirectDraw object used by the current media stream.

Syntax

HRESULT GetDirectDraw(
    IDirectDraw **ppDirectDraw
    );

Parameters

ppDirectDraw
[out] Address of a pointer to an IDirectDraw interface that will contain the current media stream's associated DirectDraw object.

Return Value

Returns S_OK if successful or E_POINTER if the parameter is invalid.

Remarks

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.

IDirectDrawMediaStream::GetFormat

IDirectDrawMediaStream Interface

Retrieves the current media stream's format and, optionally, its desired format.

Syntax

HRESULT GetFormat(
    DDSURFACEDESC *pDDSDCurrent,
    IDirectDrawPalette **ppDirectDrawPalette,
    DDSURFACEDESC *pDDSDDesired,
    DWORD *pdwFlags
    );

Parameters

pDDSDCurrent
[out] Pointer to a DirectDraw surface description that will contain the current media stream's format.
ppDirectDrawPalette
[out] Address of a pointer to an IDirectDrawPalette interface if one exists.
pDDSDDesired
[out] Pointer to a DirectDraw surface description that will contain the current media stream's desired format.
pdwFlags
[out] Pointer to the flags set in a DDSURFACEDESC structure. Fields of interest include:

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.

Return Value

Returns one of the following values.

DDERR_INVALIDPARAMS One of the DirectDraw surface parameters is invalid.
E_POINTER One or more of the required parameters is invalid.
S_OK Success.

Remarks

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 must initialize the dwSize member 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.

IDirectDrawMediaStream::GetTimePerFrame

IDirectDrawMediaStream Interface

Retrieves the average frames per second from a video stream.

Syntax

HRESULT GetTimePerFrame(
    STREAM_TIME *pFrameTime
    );

Parameters

pFrameTime
[out] Pointer to a STREAM_TIME value that indicates the average time per frame in 100-nanosecond units.

Return Value

Returns S_OK if successful or E_POINTER if the pointer is invalid.

IDirectDrawMediaStream::SetDirectDraw

IDirectDrawMediaStream Interface

Sets the current media stream's DirectDraw object.

Syntax

HRESULT SetDirectDraw(
    IDirectDraw *pDirectDraw
    );

Parameters

pDirectDraw
[in] Pointer to an IDirectDraw interface that contains the media stream's new DirectDraw object.

Return Value

Returns S_OK if successful or E_POINTER if the pointer is invalid.

Remarks

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.

IDirectDrawMediaStream::SetFormat

IDirectDrawMediaStream Interface

Sets the format of the current media stream.

Syntax

HRESULT SetFormat(
    const DDSURFACEDESC *pDDSurfaceDesc,
    IDirectDrawPalette *pDirectDrawPalette
    );

Parameters

pDDSurfaceDesc
[in] Pointer to a DirectDraw surface description that contains the new format.
pDirectDrawPalette
[in] Optional parameter that is a pointer to an IDirectDrawPalette interface.

Return Value

Returns one of the following values.

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.

Remarks

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.

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.

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.

DDERR_INVALIDPARAMS	One of the DirectDraw surface parameters is invalid.
E_POINTER	One or more of the required parameters is invalid.
S_OK	Success.