D3DXLoadSurfaceFromFile

Loads a surface from a file.

HRESULT D3DXLoadSurfaceFromFile(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCTSTR pSrcFile,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

Parameters

pDestSurface

[in] Pointer to an IDirect3DSurface8 interface. Specifies the destination surface, which receives the image.

pDestPalette

[in] Pointer to a PALETTEENTRY structure, the destination palette of 256 colors or NULL.

pDestRect

[in] Pointer to a RECT structure. Specifies the destination rectangle. Set this parameter to NULL to specify the entire surface.

pSrcFile

[in] Pointer to a string that specifies the file name of the source image.

pSrcRect

[in] Pointer to a RECT structure. Specifies the source rectangle. Set this parameter to NULL to specify the entire image.

Filter

[in] A combination of one or more D3DX_FILTER flags controlling how the image is filtered. Specifying D3DX_DEFAULT for this parameter is the equivalent of specifying D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER.

ColorKey

[in] D3DCOLOR value to replace with transparent black, or 0 to disable the colorkey. This is always a 32-bit ARGB color, independent of the source image format. Alpha is significant and should usually be set to FF for opaque colorkeys. Thus, for opaque black, the value would be equal to 0xFF000000.

pSrcInfo

[in, out] Pointer to a D3DXIMAGE_INFO structure to be filled with a description of the data in the source image file, or NULL.

Return Values

If the function succeeds, the return value is D3D_OK.

If the function fails, the return value can be one of the following values.

Remarks

This function supports the following file formats: .bmp, .dds, .dib, .jpg, .png, and .tga.

This function handles conversion to and from compressed texture formats.

Writing to a non-level-zero surface will not cause the dirty rectangle to be updated. If D3DXLoadSurfaceFromFile is called and the surface was not already dirty (this is unlikely under normal usage scenarios), the application needs to explicitly call IDirect3DTexture8::AddDirtyRect on the surface.

This functions supports both Unicode and ANSI strings.

Requirements

  Header: Declared in D3dx8tex.h.
  Import Library: Use D3dx8.lib.