D3DXCreateCubeMapTexture

The D3DXCreateCubeMapTexture function creates a blank cube-map texture.

HRESULT D3DXCreateCubeMapTexture(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  DWORD cubefaces,
  D3DCOLOR colorEmptyFaces,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps
);

Parameters

pd3dDevice

A pointer to the Direct3D device, an IDirect3DDevice7 interface, associated with the texture.

pFlags

A pointer to a DWORD value. This parameter allows you to specify the D3DX_TEXTURE_NOMIPMAP flag if mipmap generation is not desired. This value can be NULL. The D3DX_TEXTURE_NOMIPMAP flag may be returned in the case where mipmap creation is not supported.

cubefaces

This parameter allows you to specify which faces of the cube map to generate. For more information, see remarks.

colorEmptyFaces

This parameter, a D3DCOLOR type, allows you to specify a single A8R8G8B8 color to take the place of the missing surfaces in the cube map (the faces that were not specified in the cubefaces parameter).

pWidth

A pointer to a DWORD value, indicating the width in pixels. If you specify zero or D3DX_DEFAULT, the width will be taken from the file. This parameter returns the corrected width.

pHeight

A pointer to a DWORD value, indicating the height in pixels. If you specify zero or D3DX_DEFAULT, the height will be taken from the file. This parameter returns the corrected height.

pPixelFormat

A pointer to a member of the D3DX_SURFACEFORMAT enumerated type, indicating the surface format. D3DX_DEFAULT is not valid for this parameter. This parameter returns the used surface format.

pDDPal

A pointer to the DirectDraw palette, an IDirectDrawPalette interface, that is set (if present) on paletted surfaces. It is ignored even if it is set, for non-paletted surfaces. So, it allows specification of the palette to use if the resulting surface is an 8-bit palettized surface.

ppDDSurf

The address of a pointer to the DirectDrawSurface object, the texture created that matched the specifications and the current hardware.

pNumMipMaps

A pointer to a DWORD value. The number of mipmaps generated for a particular face of the cube map.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails, the return value may be one of the following values:

Remarks

Cube maps may have up to 6 faces; and they may specify a color to use for the missing faces. See the Direct3D Immediate Mode documentation for more details about how to use cube maps for creating the illusion of reflections and refraction.

For the cubefaces parameter, D3DX_DEFAULT, 0, and DDSCAPS2_CUBEMAP_ALLFACES all indicate to create all 6 faces of the cube map. Any combination of DDSCAPS2_CUBEMAP_POSITIVEX, DDSCAPS2_CUBEMAP_NEGATIVEX, DDSCAPS2_CUBEMAP_POSITIVEY, DDSCAPS2_CUBEMAP_NEGATIVEY, DDSCAPS2_CUBEMAP_POSITIVEZ, or DDSCAPS2_CUBEMAP_NEGATIVEZ, is valid.

Unless the pFlags parameter is set to specifically prevent creating mipmaps, mipmaps are generated until reaching the minimum level size of 1x1.

For more information on mipmaps, see Texture Filtering With Mipmaps.

Width, height and pixelformat are altered based on available hardware. For example, mipmap dimensions may be required to be powers of 2 and width may be required to be equal to height for square textures. Also, if the specified pixel format is unavailable, a best fit will be made.

This function creates a surface whose size and pixel format has been adjusted to match the requirements of the current device. The surface created is a system memory which is marked as Texture-Managed; see the Direct3D Immediate Mode documentation for more details.

The surface created may be larger or smaller than that specified by the width and height parameters. The pixel format chosen may not be the format passed in. Attention to the actual width, height, and pixel formats is necessary only if you plan to directly access the surface returned by this function.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Version: Requires DirectX 7.0.
  Header: Declared in d3dxcore.h.
  Library: Use d3dx.lib.

See Also

D3DXCreateTexture