## 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.

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.

###

IDirectDrawMediaStream::CreateSample

IDirectDrawMediaStream Interface

Creates a stream sample using the specified DirectDraw surface object.

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 Values

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.

##### 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.

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.

###

IDirectDrawMediaStream::GetDirectDraw

IDirectDrawMediaStream Interface

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

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 Values

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.

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.

  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.

##### Return Values

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.

##### 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.

HRESULT GetTimePerFrame(
STREAM_TIME *pFrameTime
)

##### Parameters

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

##### Return Values

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.

HRESULT SetDirectDraw(
IDirectDraw* pDirectDraw
)

##### Parameters

pDirectDraw
  [in] Address of a pointer to an IDirectDraw interface that contains the media stream's new DirectDraw object.

##### Return Values

Returns S_OK if successful.

##### 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.

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 Values

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.

##### 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.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.