IDirect3DDevice8::CreateCubeTexture

Creates a cube texture resource.

HRESULT CreateCubeTexture(
  UINT EdgeLength,
  UINT Levels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DCubeTexture8** ppCubeTexture
);

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] The number of levels in each face of the cube texture. If this is zero, Microsoft® Direct3D® will generate all cube texture sublevels down to 1×1 pixels for each face for hardware that supports mipmapped cube textures. Otherwise, it will create one level. Call IDirect3DBaseTexture8::GetLevelCount to see the number of levels generated.

Usage

[in] A combination of one or more of the following flags, describing the usage for this resource.

D3DUSAGE_DEPTHSTENCIL

Set to indicate that the surface is to be used as a depth-stencil surface. The resource can be passed to the pNewDepthStencil parameter of the IDirect3DDevice8::SetRenderTarget method. See Remarks.

D3DUSAGE_RENDERTARGET

Set to indicate that the surface is to be used as a render target. The resource can be passed to the pRenderTarget parameter of the SetRenderTarget method. See Remarks.

D3DUSAGE_DYNAMIC

Set to indicate that the usage for the surface is dynamic. See Using Dynamic Textures for more information.

If either D3DUSAGE_RENDERTARGET or D3DUSAGE_DEPTHSTENCIL is specified, the application should check that the device supports these operations by calling IDirect3D8::CheckDeviceFormat.

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 IDirect3DCubeTexture8 interface, representing the created cube texture resource.

Return Values

If the method succeeds, the return value is D3D_OK.

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

Remarks

Cube textures differ from other surfaces in that they are collections of surfaces. In order to call SetRenderTarget with a cube texture, you must select an individual face using IDirect3DCubeTexture8::GetCubeMapSurface and pass the resulting surface to SetRenderTarget.

A texture (mipmap) is a collection of successively downsampled (mipmapped) surfaces. On the other hand, a cube texture (created by 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).

In Microsoft® DirectX® 8.x, resource usage is enforced. An application that wants to use a resource in a certain operation must specify that operation at resource creation time.

Requirements

  Header: Declared in D3d8.h.
  Import Library: Use D3d8.lib.