IDirectDrawStreamSample Interface

The IDirectDrawStreamSample interface provides methods that set and retrieve pointers to the Microsoft® DirectDraw® surface associated with the current stream sample.

This interface isn't intended for implementation by application developers. It is exposed by sample objects created by the DirectDraw stream.

Use this interface when applications need to set clipping rectangles and retrieve the rendering surface for DirectDraw stream samples.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IDirectDrawStreamSample methods Description

GetSurface Retrieves pointers to the current sample's DirectDraw surface and associated clipping rectangle.
SetRect Changes the clipping rectangle for a sample.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDirectDrawStreamSample methods	Description
GetSurface	Retrieves pointers to the current sample's DirectDraw surface and associated clipping rectangle.
SetRect	Changes the clipping rectangle for a sample.

IDirectDrawStreamSample::GetSurface

IDirectDrawStreamSample Interface

Retrieves pointers to the current sample's DirectDraw surface and associated clipping rectangle.

Syntax

HRESULT GetSurface(

  IDirectDrawSurface **ppDirectDrawSurface,

  RECT *pRect

  );

Parameters

ppDirectDrawSurface
[out] Address of a pointer to an IDirectDrawSurface interface that specifies the sample's new surface. Set this parameter to NULL if you don't want to specify a new surface.
pRect
[out] Pointer to a RECT structure that will contain the current sample's clipping rectangle. Set this parameter to NULL if you don't want to retrieve the clipping rectangle.

Return Value

Returns an HRESULT value.

Remarks

Both parameters are optional. All implementations of this interface must support null values as valid parameters. If you retrieve a surface pointer, this method increments its reference count, so you must release the reference.

IDirectDrawStreamSample::SetRect

IDirectDrawStreamSample Interface

Changes the clipping rectangle for a sample.

Syntax

HRESULT SetRect (

  const RECT *pRect

  );

Parameters

pRect
[in] Pointer to a RECT structure that specifies the stream's new clipping rectangle.

Return Value

Returns one of the following values.

DDERR_INVALIDPIXELFORMAT The stream isn't compatible with the pixel format.
DDERR_INVALIDRECT The specified rectangle is invalid.
DDERR_INVALIDSURFACETYPE The stream isn't compatible with the surface.
E_POINTER One of the pointers is invalid.
MS_E_SAMPLEALLOC The stream format doesn't match the surface and samples are currently allocated to the stream.
S_OK Success.

Remarks

Both parameters are optional; set either to NULL to avoid changing that value. If the surface format doesn't match the stream format, this method fails.
If the new rectangle's size isn't the same as the current rectangle, a call to this method will fail.

DDERR_INVALIDPIXELFORMAT	The stream isn't compatible with the pixel format.
DDERR_INVALIDRECT	The specified rectangle is invalid.
DDERR_INVALIDSURFACETYPE	The stream isn't compatible with the surface.
E_POINTER	One of the pointers is invalid.
MS_E_SAMPLEALLOC	The stream format doesn't match the surface and samples are currently allocated to the stream.
S_OK	Success.