D3DXCreateTextureFromFile

The D3DXCreateTextureFromFile function creates a texture object from a stand-alone file or from the resource.

HRESULT D3DXCreateTextureFromFile(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps,
  LPSTR pSrcName,
  D3DX_FILTERTYPE filterType
);

Parameters

pd3dDevice

The Direct3D device, an IDirect3DDevice7 interface, associated with the texture.

pFlags

A pointer to a DWORD value. This parameter allows you to specify the D3DX_TEXTURE_NOMIPMAP flag if mipmap generation is not desired. This value can be NULL. The D3DX_TEXTURE_NOMIPMAP flag may be returned in the case where mipmap creation is not supported.

pWidth

A pointer to a DWORD value, indicating the width in pixels. If you specify zero or D3DX_DEFAULT, the width will be taken from the file. This parameter returns the corrected width.

pHeight

A pointer to a DWORD value, indicating the height in pixels. If you specify zero or D3DX_DEFAULT, the height will be taken from the file. This parameter returns the corrected height.

pPixelFormat

A pointer to a member of the D3DX_SURFACEFORMAT enumerated type. D3DX_DEFAULT is not valid for this parameter. The input value for this parameter should be the desired texture format. The return value will be the closest texture format that is supported by the hardware. If D3DX_SF_UNKNOWN is passed in, pixel format closest to the bitmap will be chosen.

pDDPal

A pointer to the DirectDraw palette, an IDirectDrawPalette interface, that is set (if present) on paletted surfaces. It is ignored even if it is set, for non-paletted surfaces.

ppDDSurf

The address of a pointer to a DirectDrawSurface object, the texture created that matched the specifications and the current hardware.

pNumMipMaps

A pointer to a DWORD value. The number of mipmaps generated.

pSrcName

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

filterType

A member of the D3DX_FILTERTYPE enumerated type, indicating what filtering function should be used for any necessary resizing or 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

Only BMP and DIB files are supported from the resource portion of the executable.

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.

Specifying a numeric ID for the pSrcName parameter instructs the D3DXLoadTextureFromFile function to load bitmap images from the executable's resource; otherwise, pSrcName is assumed to be a file name. Note that you cannot use the string resource name, since the D3DXCreateTextureFromFile function treats a string pointer as a file name.

Unless the pFlags parameter is set to specifically prevent creating mipmaps, mipmaps are generated until reaching the minimum level size of 1x1.

For more information on mipmaps, see Texture Filtering With Mipmaps.

Width, height and pixel format are altered based on available hardware. For example, mipmap dimensions may be required to be powers of 2 and width may be required to be equal to height for square textures. Also, if the specified pixel format is unavailable, a best fit will be made.

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

D3DXLoadTextureFromFile