Microsoft DirectX 9.0


Creates a stream sample using the specified DirectDraw surface object.


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



[in] Pointer to an existing DirectDraw surface. Use QueryInterface to obtain the IDirectDrawSurface interface from an IDirectDrawSurface7 interface.


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


[in] Specifies miscellaneous flags. The following flag is defined:

Value Description
DDSFF_PROGRESSIVERENDER If this flag is set, sample updates are performed directly on the surface. When this flag is absent, if the decoder uses delta frames, an extra copy is performed internally. Setting this flag can improve performance but can also introduce tearing.


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

Return code Description
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.

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.

See Also