Binds the specified file name or URL and returns a DXSurface containing the image data.
HRESULT retVal = object.LoadImage(pszFileName, pDirectDraw, pDDSurfaceDesc, pFormatID, riid, ppDXSurface);
- 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 calls the COM IServiceProvider::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 object.
- 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 new surface.
- ppDXSurface [out]
Address of a pointer to the new interface.
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.