GetSurface method
Returns a drawing surface of the requested size and format.
Syntax
HRESULT retVal = object.GetSurface(nWidth, nHeight, bfid, nPasses, dwHints, ppSurface);
Parameters
nWidth [in]
Type: LONG
A long integer that specifies width in pixels.
nHeight [in]
Type: LONG
A long integer that specifies height in pixels.
bfid [in]
Type: REFGUID
A GUID that specifies the destination format. See IImageDecodeEventSink::OnBeginDecode for a list of supported formats.
nPasses [in]
Type: unsigned long
An unsigned long integer that specifies the number of passes required by interlacing image formats.
dwHints [in]
Type: DWORD
Any combination of the following flags.
IMGDECODE_HINT_TOPDOWN (0x01)
The image is drawn from top to bottom.
IMGDECODE_HINT_BOTTOMUP (0x02)
(Unused) The image is drawn from bottom to top.
IMGDECODE_HINT_FULLWIDTH (0x04)
The image initially is drawn at full width, instead of by quadrants.
ppSurface [out]
Type: IUnknown
A pointer to a variable of type IUnknown that receives an object that implements the drawing surface.
Return value
Type: HRESULT
If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Remarks
The nPasses and dwHints parameter values are optional, and can be ignored by the event sink. Multi-pass decoding is possible even if the nPasses parameter is set to 1. Some event sinks dither RGB-8 images on consecutive calls to IImageDecodeEventSink::OnProgress, if IMGDECODE_HINT_TOPDOWN and IMGDECODE_HINT_FULLWIDTH are passed in dwHints.
If IMGDECODE_EVENT_USEDDRAW is returned by IImageDecodeEventSink::OnBeginDecode in the pdwEvents parameter, then the object returned in the ppSurface parameter provides minimal support for the IDirectDrawSurface interface. You must call Release on the pointer after querying it for the IDirectDrawSurface interface to subtract the additional reference count.
The following seven methods are supported by the drawing surface.