IDirectDraw::EnumSurfaces

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method enumerates all of the existing or possible surfaces that meet the specified surface description.

Syntax

HRESULT EnumSurfaces( 
  DWORD dwFlags, 
  LPDDSURFACEDESC lpDDSD, 
  LPVOID lpContext, 
  LPDDENUMSURFACESCALLBACK 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 lpDDSD parameter 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 do not match the description in the lpDDSD parameter.

    Search type flag 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 flag 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.

    If this flag is used with DDENUMSURFACES_CANBECREATED, this method returns DDERR_UNSUPPORTED.

    DDENUMSURFACES_MATCH

    Searches for any surface that matches the surface description

    DDENUMSURFACES_NOMATCH

    Searches for any surface that does not match the surface description.
  • lpDDSD
    Address of a DDSURFACEDESC structure that defines the surface of interest. This parameter can be NULL if dwFlags includes the DDENUMSURFACES_ALL flag.
  • lpContext
    Address of an application-defined structure that will be passed to each enumeration member.
  • lpEnumSurfacesCallback
    Address of the EnumSurfacesCallback function the enumeration procedure will call every time a match is found.

Return Value

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

For more information on these error codes see DirectDraw Return Values.

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 IUnknown::Release to release it after each enumeration. If you will be using the surface, release it when it is no longer needed.

Requirements

Header ddraw.h
Library ddraw.lib
Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later