D3DXLoadTextureFromFile

The D3DXLoadTextureFromFile function loads a texture from a file into a mipmap level, performing the necessary color conversion and re-scaling.

HRESULT D3DXLoadTextureFromFile(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPSTR pSrcName,
  RECT* pSrcRect,
  RECT* pDestRect,
  D3DX_FILTERTYPE filterType
);

Parameters

pd3dDevice

A pointer to the Direct3D device, an IDirect3DDevice7 interface, associated with the texture.

pTexture

A pointer to the DirectDrawSurface that was created with either the D3DXCreateTextureFromFile or D3DXCreateTexture functions. This parameter points to the texture surface object.

mipMapLevel

Indicates mipmap level. See remarks.

pSrcName

A pointer to the file name string. The following file types are supported: BMP, DIB, and DDS; for more information, see remarks.

pSrcRect

A pointer to a RECT structure, identifying the source rectangle. If NULL is specified for this parameter, the whole surface is used.

pDestRect

A pointer to a RECT structure, identifying the destination rectangle. If NULL is specified for this parameter, the whole surface is used.

filterType

A member of the D3DX_FILTERTYPE enumerated type, indicating the filter used for mipmap generation.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails, the return value may be NULL or one of the following values:

Remarks

This function provides a mechanism to copy pixels from a file to a surface.

Concerning the mipMapLevel parameter:

• If the specified mipmap level does not exist, as error is returned.
• If D3DX_DEFAULT is specified and an equal number of mipmap levels exist, then all of the source mipmap levels are loaded.
• If the source has mipmap levels and the destination does not, the top level is used.
• If the destination has mipmap levels and the source does not, expansion is used.
• If there are unequal numbers of mipmap levels between the source and destination, expansion is used.

In the pSrcName parameter, TGA is supported for the following cases: 16-, 24-, and 32-bpp direct color and 8-bpp palettized. Also, 8- and 16-bpp gray scale is supported. RLE versions of the preceding TGA formats are also supported. Note that colorkeying and premultiplied alpha are not currently supported for TGA files.

If the destination surface was created by Direct3DX, then the RECT structure should be specified in the original coordinates of that surface.

This function supports a full range of color-conversion for all surface formats that can be described by a D3DX_SURFACEFORMAT structure. It also implements filtered re-scaling and updates mipmaps automatically.

By taking pDestRect in the space of the original image, the application does not have to worry about how the surface may have been resized as part of the D3DXCreateTexture routine. For example, if an image was 100x150 pixels, then it may end up being 128x256 or 256x256 on different configurations. In both cases, the RECT structure to use to update the upper left quadrant is (0, 0, 50, 75); as if no resizing had taken place.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Version: Requires DirectX 7.0.
  Header: Declared in d3dxcore.h.
  Library: Use d3dx.lib.

See Also

D3DXCreateTextureFromFile, D3DXLoadTextureFromMemory, D3DXLoadTextureFromSurface