IDirect3DDevice9::CreateCubeTexture Method

Creates a cube texture resource.

Syntax

HRESULT CreateCubeTexture(      

    UINT EdgeLength,
    UINT Levels,
    DWORD Usage,
    D3DFORMAT Format,
    D3DPOOL Pool,
    IDirect3DCubeTexture9 **ppCubeTexture,
    HANDLE* pHandle
);

Parameters

EdgeLength

[in] Size of the edges of all the top-level faces of the cube texture. The pixel dimensions of subsequent levels of each face will be the truncated value of half of the previous level's pixel dimension (independently). Each dimension clamps at a size of 1 pixel. Thus, if the division by 2 results in 0 (zero), 1 will be taken instead.

Levels

[in] Number of levels in each face of the cube texture. If this is zero, Microsoft?Direct3D?will generate all cube texture sublevels down to 1x1 pixels for each face for hardware that supports mipmapped cube textures. Call IDirect3DBaseTexture9::GetLevelCount to see the number of levels generated.

Usage

[in] Usage can be 0, which indicates no usage value. However, if usage is desired, use a combination of one or more D3DUSAGE constants. It is good practice to match the usage parameter in CreateCubeTexture with the behavior flags in IDirect3D9::CreateDevice. For more information, see Remarks.

Format

[in] Member of the D3DFORMAT enumerated type, describing the format of all levels in all faces of the cube texture.

Pool

[in] Member of the D3DPOOL enumerated type, describing the memory class into which the cube texture should be placed.

ppCubeTexture

[out, retval] Address of a pointer to an IDirect3DCubeTexture9 interface, representing the created cube texture resource.

pHandle

[in] Reserved. Set this parameter to NULL.

Return Value

If the method succeeds, the return value is D3D_OK.

The method can also return:

D3DERR_INVALIDCALL	The method call is invalid. For example, a method's parameter may have an invalid value.
D3DERR_OUTOFVIDEOMEMORY	Direct3D does not have enough display memory to perform the operation.
E_OUTOFMEMORY	Direct3D could not allocate sufficient memory to complete the call.

Remarks

A mipmap (texture) is a collection of successively downsampled (mipmapped) surfaces. On the other hand, a cube texture (created by IDirect3DDevice9::CreateCubeTexture) is a collection of six textures (mipmaps), one for each face. All faces must be present in the cube texture. Also, a cube map surface must be the same pixel size in all three dimensions (x, y, and z).

An application can discover support for Automatic Generation of Mipmaps in a particular format by calling IDirect3D9::CheckDeviceFormat with D3DUSAGE_AUTOGENMIPMAP. If IDirect3D9::CheckDeviceFormat returns D3DOK_NOAUTOGEN, IDirect3DDevice9::CreateCubeTexture will succeed, but it will return a one level texture.