Partager via

CreateSurface method

  • Article

Creates a DXSurface object of the specified size and format.

Syntax

HRESULT retVal = object.CreateSurface(pDirectDraw, pDDSurfaceDesc, pFormatID, pBounds, dwFlags, punkOuter, riid, ppDXSurface);

Parameters

  • pDirectDraw [in]
    Type: IUnknown

    Optional pointer to the DirectDraw object to use to create the surface. If NULL, the DirectDraw object is obtained from the IDXTransformFactory service provider.

  • pDDSurfaceDesc [in]
    Type: const DDSURFACEDESC

    Pointer to the DDSURFACEDESC structure that describes the underlying DirectDrawSurface object. For more information, see the Remarks section.

  • pFormatID [in]
    Type: const GUID

    Pointer to the pixel format of the DirectDrawSurface object. If NULL, a surface matching the display's pixel format is created.

  • pBounds [in]
    Type: const DXBNDS

    Pointer to a DXBNDS structure value that specifies the height, width, and depth of the surface, in samples.

  • dwFlags [in]
    Type: DWORD

    DXSFCREATE creation flags. If DXSF_FORMAT_IS_CLSID is set, it specifies that the pFormatID parameter is the CLSID of a custom surface implementation. If DXSF_NO_LAZY_DDRAW_LOCK is set, all calls to IDXSurface::LockSurface always calls the DirectDrawSurface object's lock method, even for system memory surfaces. If this flag is not set, system memory surfaces is not locked through the DirectDrawSurface object interface when the DXSurface is locked. In general, you should only set this flag if you plan to lock underlying DirectDrawSurface objects.

  • punkOuter [in]
    Type: IUnknown

    Optional outer IUnknown interface pointer for aggregation.

  • riid [in]
    Type: REFIID

    Interface to return from the new surface.

  • ppDXSurface [out]
    Type: void

    Address of a pointer to the new interface.

Remarks

If the computer is using a version of DirectDraw that allows aggregation, the DXSurface object aggregates with a DirectDrawSurface object.

If the flag DXSF_FORMAT_IS_CLSID is set, this method calls CoCreateInstance by using the pFormatID parameter as the CLSID to create a surface object of this class. After creating the surface object, this method calls the IDXSurfaceInit::InitSurface method on the object to initialize it. This is the case for procedural surfaces, such as surface modifiers.

It is important to understand the relationship among the parameters specified for pDDSurfaceDesc, pBounds, and pFormatID. The pDDSurfaceDesc parameter is not required. If it is NULL, the surface is created as a system memory DirectDrawSurface object with the height and width specified by the pBounds parameter, and optionally, the format specified by the pFormatID parameter. If a pDDSurfaceDesc is provided, it does not need to be a complete DirectDrawSurface object description. You should set the flags for the parameters that are valid in the DDSURFACEDESC structure that need to be overridden and can allow other flags to be set by the IDXSurfaceFactory::CreateSurface call.

The following flags from the dwFlags element of the DirectDraw DDSURFACEDESC structure are used by this method. This table shows the effect of these flags on the creation of the underlying DirectDrawSurface object.

Flag Not set in dwFlags Set in dwFlags
DDSD_CAPS Surface is created in system memory. The capabilities specified in the surface description are used.
DDSD_PIXELFORMAT If pFormatID is NULL, the surface is created with the DirectDraw object's default pixel format. If pFormatID is specified, the surface is created with the specified format. Surface is created with the pixel format specified in the surface description. If pFormatID is specified but does not match the format in the surface description, the DXSurface creates the surface by using the surface description's pixel format, but treats the surface as though it has the format specified by pFormatID. For more information, see the Remarks section.

 

If the pDDSurfaceDesc specifies a pixel format and a pFormatID is specified, the surface is created with DirectDraw using the pixel format specified in pDDSurfaceDesc, but the DXSurface treats the surface as though it has the format specified by pFormatID. This feature is used internally by the Microsoft DirectX Transform code to provide alpha channel support on versions of DirectDraw that do not support per-pixel alpha. Do not use this feature unless you understand the implications of the interaction between DirectDraw and DXSurfaces. In general, it is best to only specify a pFormatID, not to specify a pixel format in the pDDSurfaceDesc.

See also

Reference

IDXSurfaceFactory::CreateFromDDSurface

DXSFCREATE