D3DXCreateTextureFromFileEx function
Creates a texture from a file. This is a more advanced function than D3DXCreateTextureFromFile.
Syntax
HRESULT D3DXCreateTextureFromFileEx(
_In_ LPDIRECT3DDEVICE9 pDevice,
_In_ LPCTSTR pSrcFile,
_In_ UINT Width,
_In_ UINT Height,
_In_ UINT MipLevels,
_In_ DWORD Usage,
_In_ D3DFORMAT Format,
_In_ D3DPOOL Pool,
_In_ DWORD Filter,
_In_ DWORD MipFilter,
_In_ D3DCOLOR ColorKey,
_Inout_ D3DXIMAGE_INFO *pSrcInfo,
_Out_ PALETTEENTRY *pPalette,
_Out_ LPDIRECT3DTEXTURE9 *ppTexture
);
Parameters
-
pDevice [in]
-
Type: LPDIRECT3DDEVICE9
Pointer to an IDirect3DDevice9 interface, representing the device to be associated with the texture.
-
pSrcFile [in]
-
Type: LPCTSTR
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
-
Width [in]
-
Type: UINT
Width in pixels. If this value is zero or D3DX_DEFAULT, the dimensions are taken from the file and rounded up to a power of two. If the device supports non-power of 2 textures and D3DX_DEFAULT_NONPOW2 is specified, the size will not be rounded.
-
Height [in]
-
Type: UINT
Height, in pixels. If this value is zero or D3DX_DEFAULT, the dimensions are taken from the file and rounded up to a power of two. If the device supports non-power of 2 textures and D3DX_DEFAULT_NONPOW2 is sepcified, the size will not be rounded.
-
MipLevels [in]
-
Type: UINT
Number of mip levels requested. If this value is zero or D3DX_DEFAULT, a complete mipmap chain is created. If D3DX_FROM_FILE, the size will be taken exactly as it is in the file, and the call will fail if this violates device capabilities.
-
Usage [in]
-
Type: DWORD
0, D3DUSAGE_RENDERTARGET, or D3DUSAGE_DYNAMIC. Setting this flag to D3DUSAGE_RENDERTARGET indicates that the surface is to be used as a render target. The resource can then be passed to the pNewRenderTarget parameter of the SetRenderTarget method. If either D3DUSAGE_RENDERTARGET or D3DUSAGE_DYNAMIC is specified, Pool must be set to D3DPOOL_DEFAULT, and the application should check that the device supports this operation by calling CheckDeviceFormat. D3DUSAGE_DYNAMIC indicates that the surface should be handled dynamically. See Using Dynamic Textures.
-
Format [in]
-
Type: D3DFORMAT
Member of the D3DFORMAT enumerated type, describing the requested pixel format for the texture. The returned texture might have a different format from that specified by Format. Applications should check the format of the returned texture. If D3DFMT_UNKNOWN, the format is taken from the file. If D3DFMT_FROM_FILE, the format is taken exactly as it is in the file, and the call will fail if this violates device capabilities.
-
Pool [in]
-
Type: D3DPOOL
Member of the D3DPOOL enumerated type, describing the memory class into which the texture should be placed.
-
Filter [in]
-
Type: DWORD
A combination of one or more D3DX_FILTER constants controlling how the image is filtered. Specifying D3DX_DEFAULT for this parameter is the equivalent of specifying D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER.
-
MipFilter [in]
-
Type: DWORD
A combination of one or more D3DX_FILTER constants controlling how the image is filtered. Specifying D3DX_DEFAULT for this parameter is the equivalent of specifying D3DX_FILTER_BOX. In addition, use bits 27-31 to specify the number of mip levels to be skipped (from the top of the mipmap chain) when a .dds texture is loaded into memory; this allows you to skip up to 32 levels.
-
ColorKey [in]
-
Type: D3DCOLOR
D3DCOLOR value to replace with transparent black, or 0 to disable the color key. 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 color keys. Thus, for opaque black, the value would be equal to 0xFF000000.
-
pSrcInfo [in, out]
-
Type: D3DXIMAGE_INFO*
Pointer to a D3DXIMAGE_INFO structure to be filled in with a description of the data in the source image file, or NULL.
-
pPalette [out]
-
Type: PALETTEENTRY*
Pointer to a PALETTEENTRY structure, representing a 256-color palette to fill in, or NULL.
-
ppTexture [out]
-
Type: LPDIRECT3DTEXTURE9*
Address of a pointer to an IDirect3DTexture9 interface, representing the created texture object.
Return value
Type: HRESULT
If the function succeeds, the return value is D3D_OK. If the function fails, the return value can be one of the following: D3DERR_INVALIDCALL, D3DERR_NOTAVAILABLE, D3DERR_OUTOFVIDEOMEMORY, D3DXERR_INVALIDDATA, E_OUTOFMEMORY.
Remarks
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to D3DXCreateTextureFromFileExW. Otherwise, the function call resolves to D3DXCreateTextureFromFileExA because ANSI strings are being used.
Use D3DXCheckTextureRequirements to determine if your device can support the texture given the current state.
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See D3DXIMAGE_FILEFORMAT.
Mipmapped textures automatically have each level filled with the loaded texture. When loading images into mipmapped textures, some devices are unable to go to a 1x1 image and this function will fail. If this happens, then the images need to be loaded manually.
For the best performance when using D3DXCreateTextureFromFileEx:
- Doing image scaling and format conversion at load time can be slow. Store images in the format and resolution they will be used. If the target hardware requires power of 2 dimensions, then create and store images using power of 2 dimensions.
- For mipmap image creation at load time, filter using D3DX_FILTER_BOX. A box filter is much faster than other filter types such as D3DX_FILTER_TRIANGLE.
- Consider using DDS files. Since DDS files can be used to represent any Direct3D 9 texture format, they are very easy for D3DX to read. Also, they can store mipmaps, so any mipmap-generation algorithms can be used to author the images.
When skipping mipmap levels while loading a .dds file, use the D3DX_SKIP_DDS_MIP_LEVELS macro to generate the MipFilter value. This macro takes the number of levels to skip and the filter type and returns the filter value, which would then be passed into the MipFilter parameter.
Requirements
| Requirement | Value |
|---|---|
| Header |
|
| Library |
|
See also