IDirectDraw4::EnumSurfaces

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The IDirectDraw4::EnumSurfacesmethod enumerates all of the existing or possible surfaces that meet the specified surface description.

HRESULT EnumSurfaces(
DWORD
dwFlags
,
LPDDSURFACEDESC2
lpDDSD2
,
LPVOID
lpContext
,
LPDDENUMSURFACESCALLBACK2
lpEnumSurfacesCallback
);

Parameters

dwFlags

A combination of one search type flag and one matching flag. The search type flag determines how the method searches for matching surfaces; you can search for surfaces that can be created using the description in the lpDDSD2parameter or you can search for existing surfaces that already match that description. The matching flag determines whether the method enumerates all surfaces, only those that match, or only those that don't match the description in the lpDDSD2parameter.

Search Type Flags	Description
DDENUMSURFACES_CANBECREATED	Enumerates the first surface that can be created and meets the search criterion. This flag can only be used with the DDENUMSURFACES_MATCH flag.
DDENUMSURFACES_DOESEXIST	Enumerates the already existing surfaces that meet the search criterion.

Matching flags	Description
DDENUMSURFACES_ALL	Enumerates all of the surfaces that meet the search criterion. This flag can only be used with the DDENUMSURFACES_DOESEXIST search type flag.
DDENUMSURFACES_MATCH	Searches for any surface that matches the surface description
DDENUMSURFACES_NOMATCH	Searches for any surface that does not match the surface description.

lpDDSD2

Address of a DDSURFACEDESC2structure that defines the surface of interest. This parameter can be NULL if dwFlagsincludes the DDENUMSURFACES_ALL flag.

lpContext

Address of an application-defined structure that will be passed to each enumeration member.

lpEnumSurfacesCallback

Address of the EnumSurfacesCallback2function the enumeration procedure will call every time a match is found.

Return Values

If the method succeeds, the return value is DD_OK.

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

If the DDENUMSURFACES_CANBECREATED flag is set, this method attempts to create a surface that temporarily meets the search criterion.

When using the DDENUMSURFACES_DOESEXIST flag, note that an enumerated surface's reference count is incremented.

If you are not going to use the surface, be sure to use IDirectDrawSurface4::Releaseto release it after each enumeration. If you will be using the surface, release it when it is no longer needed.

This method differs from its counterparts in previous interface versions in that it accepts a pointer to an EnumSurfacesCallback2function, rather than an EnumSurfacesCallbackfunction.

Requirements

Runs on	Versions	Declared in	Link to
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	ddraw.h	ddraw.lib