CreateSurface method

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.

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