D3DMXCreateTextureFromFileEx

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function creates a texture object from a file.

Syntax

HRESULT WINAPI D3DMXCreateTextureFromFileExW(
  LPDIRECT3DMOBILEDEVICE   pDevice,
  LPCWSTR                  pSrcFile,
  UINT                     Width,
  UINT                     Height,
  UINT                     MipLevels,
  DWORD                    Usage,
  D3DMFORMAT               Format,
  D3DMPOOL                 Pool,
  DWORD                    Filter,
  DWORD                    MipFilter,
  D3DMCOLOR                ColorKey,
  D3DMXIMAGE_INFO*         pSrcInfo,
  PALETTEENTRY*            pPalette,
  LPDIRECT3DMOBILETEXTURE* ppTexture
);
#define D3DMXCreateTextureFromFileEx D3DMXCreateTextureFromFileExW

Parameters

• pDevice
  [in] Pointer to an IDirect3DMobileDevice interface, representing the device to be associated with the texture.

• pSrcFile
  [in] Pointer to a string that specifies the filename.

• Width
  [in] A UINT value that specifies the width of the texture in pixels. If this value is zero or D3DMX_DEFAULT, the dimensions are taken from the file.

• Height
  [in] A UINT value that specifies the height of the texture in pixels. If this value is zero or D3DMX_DEFAULT, the dimensions are taken from the file.

• MipLevels
  [in] A UINT value that specifies the number of mip levels requested. If this value is zero or D3DMX_DEFAULT, a complete mipmap chain is created.

• Usage
  [in] A DWORD value that is either 0, D3DMUSAGE_RENDERTARGET, or D3DMUSAGE_DYNAMIC (see D3DMUSAGE Values). 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 IDirect3DMobileDevice::SetRenderTarget method. If either D3DMUSAGE_RENDERTARGET or D3DMUSAGE_DYNAMIC is specified, the Pool parameter must be set to D3DMPOOL_DEFAULT, and the application should check that the device supports this operation by calling IDirect3DMobile::CheckDeviceFormat. D3DMUSAGE_DYNAMIC indicates that the surface should be handled dynamically.

• Format
  [in] An element of the D3DMFORMAT 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 Format is D3DMFMT_UNKNOWN, the format is taken from the file.

• Pool
  [in] An element of the D3DMPOOL enumerated type, describing the memory class into which the texture should be placed.

• Filter
  [in] A combination of one or more D3DMX_FILTER Values controlling how the image is filtered. Specifying D3DMX_DEFAULT for this parameter is the equivalent of specifying D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER.

• MipFilter
  [in] A combination of one or more D3DMX_FILTER values controlling how the image is filtered. Specifying D3DMX_DEFAULT for this parameter is the equivalent of specifying D3DMX_FILTER_BOX.

• ColorKey
  [in] A D3DMCOLOR 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 color keys. Thus, for opaque black, the value would be equal to 0xFF000000.

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

• pPalette
  [out] Pointer to a PALETTEENTRY structure, representing a 256-color palette to fill in, or NULL.

• ppTexture
  [out] Address of a pointer to an IDirect3DMobileTexture interface, representing the created texture object.

Return Value

If the function succeeds, the return value is D3DM_OK (see D3DM Values).

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

Remarks

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

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 D3DMXCreateTextureFromFileEx:

• 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 D3DMXFILTER_BOX. A box filter is much faster than other filter types such as D3DMXFILTER_TRIANGLE.

Requirements

See Also

Reference

D3DMX Functions
IDirect3DMobileDevice
D3DMUSAGE Values
IDirect3DMobileDevice::SetRenderTarget
IDirect3DMobile::CheckDeviceFormat
D3DMFORMAT
D3DMPOOL
D3DMX_FILTER Values
D3DMCOLOR
D3DMXIMAGE_INFO
IDirect3DMobileTexture
D3DM Values

Other Resources

PALETTEENTRY