## IDirectDrawStreamSample Interface

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

When to Implement

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

When to Use

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.

###

IDirectDrawStreamSample::GetSurface

IDirectDrawStreamSample Interface

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

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 Values

Returns S_OK if successful.

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

HRESULT SetRect (
const RECT * pRect
)

##### Parameters

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

##### Return Values

Returns one of the following values.

Value | Meaning
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.

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