D3DXLoadVolumeFromFile Function

Loads a volume from a file.

Syntax

HRESULT D3DXLoadVolumeFromFile(      

    LPDIRECT3DVOLUME9 pDestVolume,
    const PALETTEENTRY *pDestPalette,
    const D3DBOX *pDestBox,
    LPCTSTR pSrcFile,
    const D3DBOX *pSrcBox,
    DWORD Filter,
    D3DCOLOR ColorKey,
    D3DXIMAGE_INFO pSrcInfo
);

Parameters

pDestVolume

[in] Pointer to an IDirect3DVolume9 interface. Specifies the destination volume.

pDestPalette

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

pDestBox

[in] Pointer to a D3DBOX structure. Specifies the destination box. Set this parameter to NULL to specify the entire volume.

pSrcFile

[in] 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.

pSrcBox

[in] Pointer to a D3DBOX structure. Specifies the source box. Set this parameter to NULL to specify the entire volume.

Filter

[in] Combination of one or more D3DX_FILTER, 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 color keys. Thus, for opaque black, the value would be equal to 0xFF000000.

pSrcInfo

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

Return Value

If the function succeeds, the return value is D3D_OK.

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

D3DERR_INVALIDCALL	The method call is invalid. For example, a method's parameter may have an invalid value.
D3DXERR_INVALIDDATA	The data is invalid.

Remarks

The compiler setting also determines the function version. If Unicode is defined, the function call resolves to D3DXLoadVolumeFromFileW. Otherwise, the function call resolves to D3DXLoadVolumeFromFileA because ANSI strings are being used.

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 of the volume texture will not cause the dirty rectangle to be updated. If D3DXLoadVolumeFromFile is called and the texture was not already dirty (this is unlikely under normal usage scenarios), the application needs to explicitly call IDirect3DVolumeTexture9::AddDirtyBox on the volume texture.

Function Information

Header	d3dx9tex.h
Import library	d3dx9.lib
Minimum operating systems	Windows 98

See Also

D3DXLoadVolumeFromFileInMemory, D3DXLoadVolumeFromMemory, D3DXLoadVolumeFromResource, D3DXLoadVolumeFromVolume, Texture Color Conversions