CopySurfaceToNewFormat method

  • Article

Copies one surface to another and changes its pixel format.

Syntax

HRESULT retVal = object.CopySurfaceToNewFormat(pSrc, pDirectDraw, pDDSurfaceDesc, pDestFormatID, ppNewSurface);

Parameters

  • pSrc [in]
    Type: IDXSurface

    Pointer to a DXSurface to copy.

  • pDirectDraw [in]
    Type: IUnknown

    Optional pointer to the DirectDraw object from which the DXSurface was created. Used only to copy DirectDraw information when multiple DirectDraw objects exist, for example, with dual monitors.

  • pDDSurfaceDesc [in]
    Type: const DDSURFACEDESC

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

  • pDestFormatID [in]
    Type: const GUID

    Pointer to the pixel format of the destination surface. If NULL, the pixel format for the current monitor display setting is used.

  • ppNewSurface [out]
    Type: IDXSurface

    Address of a pointer that contains the new DXSurface interface when the method returns.

Remarks

This method creates a new DirectDrawSurface object of the same height and width as the source and returns the interface pointer in ppNewSurface. If no pixel format is specified by pDestFormatID and none is specified by pDDSurfaceDesc, the surface is created by using the standard DirectDraw pixel format that matches the current display pixel format.

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 new underlying DirectDrawSurface object.

Flag Not set in dwFlags. Set in dwFlags.
DDSD_CAPS Surface is created in system memory. The specified capabilities in the surface description are used.
DDSD_PIXELFORMAT If pFormatId is NULL, the surface is created with the DirectDrawSurface object's default pixel format. If pFormatId is specified, the surface is created with that 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 using the surface description's pixel format but treats the surface as though it has the format specified by pFormatId.

 

If the pDDSurfaceDesc parameter specifies a pixel format, and a pFormatId is specified, the surface is created with DirectDraw by using the pixel format specified in pDDSurfaceDesc. However, 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 and not to specify a pixel format in pDDSurfaceDesc.

If the source surface has more bits per color channel than the destination, the method dithers the source image when copying to the new surface. If the source surface has transparency, and the new surface's pixel format does not support an alpha channel, a color key of 0xFFFF00FF (cyan) is set on the destination surface to preserve the transparency.

See also

DXSAMPLEFORMATENUM