IDXSurfaceFactory Interface

The IDXSurfaceFactory interface provides methods to create and load data into DXSurface data objects. Perhaps the most commonly used method of this interface is CreateSurface, which creates an uninitialized DXSurface of a specified size and pixel format. Also very useful is the LoadImage method, which translates an image from a number of common image formats (such as .GIF, .JPG, and .BMP) and stores the result in a new DXSurface.

This interface is exposed by the IDXTransformFactory interface. The recommended way to expose the interface is by using the QueryService method on the IDXTransformFactory with SID_DXSurfaceFactory as the service ID. You can create procedural surfaces by specifying the class identifier (CLSID) of the procedural surface for the pFormatID parameter and by using the CreateSurface method.

IDXSurfaceFactory Methods

BitBlt Copies samples from one DXSurface to another.

CopySurfaceToNewFormat Copies one surface to another and changes its pixel format.

CreateD3DRMTexture Creates a Microsoft® Direct3D® Retained Mode texture from a DXSurface.

CreateFromDDSurface Creates a DXSurface object that is aggregated to a specified Microsoft DirectDraw® surface.

CreateSurface Creates a DXSurface object of the specified size and format.

LoadImage Binds the specified file name or URL and returns a DXSurface containing the image data.

LoadImageFromStream Loads an image from a specified stream and returns a DXSurface.

IDXSurfaceFactory::BitBlt

IDXSurfaceFactory Interface

Copies samples from one DXSurface to another.

Syntax

HRESULT BitBlt(
     IDXSurface *pDest,
     const DXVEC *pPlacement,
     IDXSurface *pSrc,
     const DXBNDS *pPortionBounds,
     DWORD dwFlags
);

Parameters

pDest
[in] Pointer to the destination DXSurface.

pPlacement
[in] Pointer to a DXVEC structure corresponding to the displaced position of the source surface on the destination surface. If this parameter is NULL, the data will be placed at the origin of the destination surface.
pSrc
[in] Pointer to the source DXSurface.

pPortionBounds
[in] Pointer to a DXBNDS structure corresponding to the portion of the source surface to copy to the destination. If this parameter is NULL, the entire source surface is copied.

dwFlags
[in] One of the DXBLTOPTIONS used to specify what type of blit operation to perform.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method performs all necessary clipping for the specified placement and/or clipping bounds. If no data is transferred (that is, the clipping results in an empty region), the call returns S_FALSE.
DXBOF_DO_OVER and DXBOF_DITHER are the two valid flags for this method. These flags can be used independently or in combination. If no flags are specified, the data is simply copied from the source to the destination. If the DXBOF_DO_OVER flag is set, the source data is blended with the destination data by alpha blending. If DXBOF_DITHER is set and the destination's pixel format has fewer bits per pixel of color information than the source, the data will be dithered before being copied to or blended with the destination.
The DXBitBlt helper function provided in Dxhelper.h does a faster blit operation than IDXSurfaceFactory::BitBlt, but with no clipping, parameter validation, or error checking.
Coordinates for both clipping and displacement are relative to the upper-left corner of the surfaces.

See Also

DXBLTOPTIONS

IDXSurfaceFactory::CopySurfaceToNewFormat

IDXSurfaceFactory Interface

Copies one surface to another surface and changes its pixel format.

Syntax

HRESULT CopySurfaceToNewFormat(
    IDXSurface *pSrc,
    IUnknown *pDirectDraw,
    const DDSURFACEDESC *pDDSurfaceDesc,
    const GUID *pDestFormatId,
    IDXSurface **ppNewSurface
);

Parameters

pSrc
[in] Pointer to a DXSurface to copy.

pDirectDraw
[in] 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] Optional pointer to the DDSURFACEDESC structure that describes the underlying DirectDrawSurface. For more information, see the Remarks section.

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

ppNewSurface
[out] Address of a pointer that will contain the new DXSurface interface when the method returns.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method creates a new DirectDrawSurface of the same height and width as the source and returns the interface pointer in ppNew. 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 DirectDraw's DDSURFACEDESC structure are used by this method. This table shows the effect of these flags on the creation of the new underlying DirectDrawSurface.

Flag(s) Not set in dwFlags. Set in dwFlags.

DDSD_CAPS Surface will be created in system memory. The specified capabilities in the surface description will be used.

DDSD_PIXELFORMAT If pFormatId is NULL, the surface will be created with the DirectDrawSurface object's default pixel format. If pFormatId is specified, the surface is created with that format. Surface will be created with the pixel format specified in the surface description. IMPORTANT: If pFormatId is specified but does not match the format in the surface description, the DXSurface will create the surface using the surface description's pixel format but will treat the surface as though it has the format specified by pFormatId. For more information, see the Remarks section.

DDSD_HEIGHT | DDSD_WIDTH Surface will be created with the same height and width as the source surface. dwHeight and dwWidth parameters must match the height and width of the source surface.

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 DirectX Transform code to provide alpha channel support on versions of DirectDraw that do not support per-pixel alpha. You should never use this feature unless you fully 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.

Flag(s)	Not set in dwFlags.	Set in dwFlags.
DDSD_CAPS	Surface will be created in system memory.	The specified capabilities in the surface description will be used.
DDSD_PIXELFORMAT	If pFormatId is NULL, the surface will be created with the DirectDrawSurface object's default pixel format. If pFormatId is specified, the surface is created with that format.	Surface will be created with the pixel format specified in the surface description. IMPORTANT: If pFormatId is specified but does not match the format in the surface description, the DXSurface will create the surface using the surface description's pixel format but will treat the surface as though it has the format specified by pFormatId. For more information, see the Remarks section.
DDSD_HEIGHT \| DDSD_WIDTH	Surface will be created with the same height and width as the source surface.	dwHeight and dwWidth parameters must match the height and width of the source surface.

See Also

DXSAMPLEFORMATENUM, Supported Pixel Formats

IDXSurfaceFactory::CreateD3DRMTexture

IDXSurfaceFactory Interface

Creates a Microsoft® Direct3D® Retained Mode texture from a DXSurface.

Syntax

HRESULT CreateD3DRMTexture(
    IDXSurface *pSrc,
    IUnknown *pDirectDraw,
    IUnknown *pD3DRM3,
    REFIID riid,
    void **ppTexture3
);

Parameters

pSrc
[in] Pointer to the DXSurface to use to create the texture.
pDirectDraw
[in] Optional pointer to the DirectDraw object to use to create the texture.

pD3DRM
[in] Pointer to the IDirect3DRMMeshBuilder3 interface on the Direct3D Retained Mode object to use for creating the texture.

riid
[in] Interface identifier (IID) of the interface to return from the newly created surface.

ppTexture3
[out] Address of a pointer to the IDirect3DRMTexture3 interface on the created texture object.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IDXSurfaceFactory::CreateSurface, IDXSurfaceFactory::CreateFromDDSurface

IDXSurfaceFactory::CreateFromDDSurface

IDXSurfaceFactory Interface

Creates a DXSurface that contains a specified DirectDrawSurface.

Syntax

HRESULT CreateFromDDSurface(
    IUnknown *pDDrawSurface,
    const GUID *pFormatID,
    DWORD dwFlags,
    IUnknown *punkOuter,
    REFIID riid,
    void **ppDXSurface
);

Parameters

pDDrawSurface
[in] Pointer to a DirectDrawSurface to wrap with a new DXSurface.

pFormatID
[in] Optional pointer to the source pixel format. If the parameter is NULL, the pixel format of the DirectDrawSurface is used. If this parameter is non-NULL, the pixel format of the DirectDrawSurface is ignored, and the data is treated as though it were the format specified by this globally unique identifier (GUID). This is usually used to force a DirectDrawSurface that has no alpha channel to be treated as a 32-bit surface with alpha.

dwFlags
[in] DXSFCREATE creation flags. A value of DXSF_FORMAT_IS_CLSID specifies that the pFormatID parameter is the class identifier (CLSID) of a custom surface implementation.

punkOuter
[in] Optional outer IUnknown interface pointer for aggregation.

riid
[in] Interface to return from the newly created surface.

ppDXSurface
[out] Address of a pointer to the newly created interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The default behavior for a system memory DXSurface is to do all lock arbitration at the DXSurface level for performance and correct lock behavior. The DirectDrawSurface is locked once to obtain a memory pointer and then released. If the user plans to access the underlying IDirectDrawSurface::Lock method directly (not via the DXSurface interface), DXSF_NO_LAZY_DDRAW_LOCK must be used. In this case, a lock to the DXSurface will always lock the underlying DirectDrawSurface assuring safe access. This is the default for video memory based surfaces.
The resulting DXSurface uses the source color key of the underlying DirectDrawSurface.

See Also

IDXSurfaceFactory::CreateSurface, IDXSurfaceFactory::CreateD3DRMTexture, DXSFCREATE

IDXSurfaceFactory::CreateSurface

IDXSurfaceFactory Interface

Creates a DXSurface object of the specified size and format.

Syntax

HRESULT CreateSurface(
    IUnknown *pDirectDraw,
    const DDSURFACEDESC *pDDSurfaceDesc,
    const GUID *pFormatID,
    const DXBNDS *pBounds,
    DWORD dwFlags,
    IUnknown *punkOuter,
    REFIID riid,
    void **ppDXSurface
);

Parameters

pDirectDraw
[in] Optional pointer to the DirectDraw object to use to create the surface. If NULL, the DirectDraw object is obtained from the IDXTransformFactory's service provider.

pDDSurfaceDesc
[in] Pointer to the DDSURFACEDESC structure that describes the underlying DirectDrawSurface. For more information, see the Remarks section.

pFormatID
[in] Pointer to the pixel format of the DirectDrawSurface. If NULL, a surface matching the display's pixel format is created.

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

dwFlags
[in] 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 will always call the DirectDrawSurface's lock method, even for system memory surfaces. If this flag is not set, system memory surfaces will not be locked through the DirectDrawSurface interface when the DXSurface is locked. In general, this flag should only be set if you plan on locking underlying DirectDrawSurfaces.

punkOuter
[in] Optional outer IUnknown interface pointer for aggregation.

riid
[in] Interface to return from the newly created surface.

ppDXSurface
[out] Address of a pointer to the newly created interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

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

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 will be created as a system memory DirectDrawSurface 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 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 CreateSurface call.

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

Flag(s) Not set in dwFlags Set in dwFlags

DDSD_CAPS Surface will be created in system memory. The Caps specified in the surface description will be 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. IMPORTANT: 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.

DDSD_HEIGHT | DDSD_WIDTH pBounds is required. Surfaces are created with height and width specified by pBounds. pBounds can be NULL. If pBounds is not NULL, the heights and widths of the surface description and the bounds structure must match.

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 DirectX Transform code to provide alpha channel support on versions of DirectDraw that do not support per-pixel alpha. You should never use this feature unless you fully 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.

Flag(s)	Not set in dwFlags	Set in dwFlags
DDSD_CAPS	Surface will be created in system memory.	The Caps specified in the surface description will be 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. IMPORTANT: 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.
DDSD_HEIGHT \| DDSD_WIDTH	pBounds is required. Surfaces are created with height and width specified by pBounds.	pBounds can be NULL. If pBounds is not NULL, the heights and widths of the surface description and the bounds structure must match.

See Also

IDXSurfaceFactory::CreateD3DRMTexture, IDXSurfaceFactory::CreateFromDDSurface, DXSFCREATE

IDXSurfaceFactory::LoadImage

IDXSurfaceFactory Interface

Binds the specified file name or URL and returns a DXSurface containing the image data.
Note: Internet Explorer 4.x or later must be installed for this method to work.

Syntax

HRESULT LoadImage(
   const LPWSTR pszFileName,
   IUnknown *pDirectDraw,
   const DDSURFACEDESC *pDDSurfaceDesc,
   const GUID *pFormatID,
   REFIID riid,
   void **ppDXSurface
);

Parameters

pszFileName
[in] File name or URL of the file to load.

pDirectDraw
[in] Optional pointer to the DirectDraw interface to use. If NULL, the method will call the COM QueryService method to obtain a separate DirectDraw interface. This parameter is usually NULL.

pDDSurfaceDesc
[in] Pointer to the DDSURFACEDESC structure that describes the underlying DirectDrawSurface.

pFormatID
[in] Pointer to the overriding pixel format.If NULL, the format is determined by the source data loader.

riid
[in] Interface to return from the newly created surface.

ppDXSurface
[out] Address of a pointer to the newly created interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The pDDSurfaceDesc is not required. If it is NULL, the surface is created as a system memory DirectDrawSurface, 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 description. You should set the flags for the parameters that are valid in the DDSURFACEDESC structure that need to be overridden, and you can allow other flags to be set by the CreateSurface call.
The following flags from the dwFlags element of DirectDraw's DDSURFACEDESC structure are used by this method. This table shows the effect of these flags on the creation of the new underlying DirectDrawSurface.

Flag(s) Not set in dwFlags Set in dwFlags

DDSD_CAPS Surface is created in system memory. The capabilities specified in the surface description will be 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 that format. Surface is created with the pixel format specified in the surface description. IMPORTANT: 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.

DDSD_HEIGHT | DDSD_WIDTH pBounds is required. Surface is created with height and width specified by pBounds. pBounds can be NULL. If pBounds is not NULL, the heights and widths of the surface description and the bounds structure must match.

If the values for the dwHeight and dwWidth members of the DDSURFACEDESC structure are smaller than the actual height and width of the image being loaded, the load fails and returns a DXTERR_INVALID_BOUNDS error message. In general, height and width should not be specified; the method determines them.

Flag(s)	Not set in dwFlags	Set in dwFlags
DDSD_CAPS	Surface is created in system memory.	The capabilities specified in the surface description will be 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 that format.	Surface is created with the pixel format specified in the surface description. IMPORTANT: 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.
DDSD_HEIGHT \| DDSD_WIDTH	pBounds is required. Surface is created with height and width specified by pBounds.	pBounds can be NULL. If pBounds is not NULL, the heights and widths of the surface description and the bounds structure must match.

See Also

IDXSurfaceFactory::LoadImageFromStream

IDXSurfaceFactory::LoadImageFromStream

IDXSurfaceFactory Interface

Loads an image from a specified stream and returns a DXSurface.

Syntax

HRESULT LoadImageFromStream(
    IStream *pStream,
    IUnknown *pDirectDraw,
    const DDSURFACEDESC *pDDSurfaceDesc,
    const GUID *pFormatID,
    REFIID riid,
    void **ppDXSurface
);

Parameters

pStream
[in] Pointer to the stream to use for the image load.

pDirectDraw
[in] Pointer to the DirectDraw object to use.

pDDSurfaceDesc
[in] Pointer to the DDSURFACEDESC structure that describes the underlying DirectDrawSurface.

pFormatID
[in] Pointer to the overriding pixel format. If NULL, the format is determined by the source data loader.

riid
[in] Interface to return from the newly created surface.

ppDXSurface
[out] Address of a pointer to the newly created interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

All parameters except pStream are identical to the parameters of the IDXSurfaceFactory::LoadImage method.
For more information about using the IStream interface, consult a Component Object Model (COM) reference.

See Also

IDXSurfaceFactory::LoadImage

BitBlt	Copies samples from one DXSurface to another.
CopySurfaceToNewFormat	Copies one surface to another and changes its pixel format.
CreateD3DRMTexture	Creates a Microsoft® Direct3D® Retained Mode texture from a DXSurface.
CreateFromDDSurface	Creates a DXSurface object that is aggregated to a specified Microsoft DirectDraw® surface.
CreateSurface	Creates a DXSurface object of the specified size and format.
LoadImage	Binds the specified file name or URL and returns a DXSurface containing the image data.
LoadImageFromStream	Loads an image from a specified stream and returns a DXSurface.