LoadImage method

  • Article

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

Syntax

HRESULT retVal = object.LoadImage(pszFileName, pDirectDraw, pDDSurfaceDesc, pFormatID, riid, ppDXSurface);

Parameters

  • pszFileName [in]
    Type: LPWSTR

    File name or URL of the file to load.

  • pDirectDraw [in]
    Type: IUnknown

    Optional pointer to the DirectDraw interface to use. If NULL, the method calls the COM IServiceProvider::QueryService method to obtain a separate DirectDraw interface. This parameter is usually NULL.

  • pDDSurfaceDesc [in]
    Type: DDSURFACEDESC

    Pointer to the DDSURFACEDESC structure that describes the underlying DirectDrawSurface object.

  • pFormatID [in]
    Type: GUID

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

  • riid [in]
    Type: REFIID

    Interface to return from the new surface.

  • ppDXSurface [out]
    Type: void

    Address of a pointer to the new interface.

Remarks

Note  Internet Explorer 4.x or later must be installed for this method to work.

 

The pDDSurfaceDesc is not required. If it is NULL, the surface is created as a system memory DirectDrawSurface object with the default height and width of the loaded image file. If it is NULL, the surface is created as a system memory DirectDrawSurface object, with the height and width specified by the input image, 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 you 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 new 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 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 by using the surface description's pixel format, but treats the surface as though it has the format specified by pFormatID.

 

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.

See also

IDXSurfaceFactory::LoadImageFromStream