D3DXSaveVolumeToFile function

Article
03/15/2021

Saves a volume to a file on disk.

Syntax

HRESULT D3DXSaveVolumeToFile(
  _In_       LPCTSTR              pDestFile,
  _In_       D3DXIMAGE_FILEFORMAT DestFormat,
  _In_       LPDIRECT3DVOLUME9    pSrcVolume,
  _In_ const PALETTEENTRY         *pSrcPalette,
  _In_ const D3DBOX               *pSrcBox
);

Parameters

pDestFile [in]

Type: LPCTSTR

Pointer to a string that specifies the file name of the destination image. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.

DestFormat [in]

Type: D3DXIMAGE_FILEFORMAT

D3DXIMAGE_FILEFORMAT specifying the file format to use when saving. This function supports saving to all D3DXIMAGE_FILEFORMAT formats except Portable Pixmap (.ppm) and Targa/Truevision Graphics Adapter (.tga).

pSrcVolume [in]

Type: LPDIRECT3DVOLUME9

Pointer to IDirect3DVolume9 interface containing the image to be saved.

pSrcPalette [in]

Type: const PALETTEENTRY*

Pointer to a PALETTEENTRY structure containing a palette of 256 colors. This parameter can be NULL.

pSrcBox [in]

Type: const D3DBOX*

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

Return value

Type: HRESULT

If the function succeeds, the return value is D3D_OK. If the function fails, the return value can be the following: D3DERR_INVALIDCALL

Remarks

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

This function handles conversion to and from compressed texture formats.

If the volume is nondynamic (because of a usage parameter set to 0 at the creation) and located in video memory (the memory pool set to D3DPOOL_DEFAULT), D3DXSaveTextureToFile will fail because D3DX cannot lock nondynamic volumes located in video memory.

Requirements

Requirement	Value
Header	D3dx9tex.h
Library	D3dx9.lib