TextureCube Constructor (GraphicsDevice, Int32, Int32, ResourceUsage, SurfaceFormat)

Creates an uninitialized TextureCube resource of the specified dimensions. To initialize a Texture2D from an existing file, see the static method ContentManager.Load or FromFile.

Namespace: Microsoft.Xna.Framework.Graphics
Assembly: Microsoft.Xna.Framework (in microsoft.xna.framework.dll)

Syntax

public TextureCube (
         GraphicsDevice graphicsDevice,
         int edgeLength,
         int numberLevels,
         ResourceUsage usage,
         SurfaceFormat format
)

Parameters

• graphicsDevice
  The GraphicsDevice that will display the cube texture.

• edgeLength
  The 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.

• numberLevels
  The number of downsampled surfaces to create for each face of the cube texture when preprocessing the texture. These smaller versions of the texture, known as mip levels, are used when the texture is minified to fit a smaller area than the original texture size. The chain of downsampled surfaces associated with a texture is sometimes called a mipmap chain.

  If numberLevels is zero, all cube texture sublevels down to 1×1 pixels will be generated for each face for hardware that supports mipmapped cube textures. Use LevelCount to see the number of levels generated.

• usage
  A set of options identifying the behaviors of this resource.

• format
  The format of all levels in the cube texture.

Exceptions

Exception type	Condition
ArgumentException	One of the following conditions is true: The edgeLength requested would result in a resource too large for the graphics device. numberLevels is too large. It is either greater than 32, or if less than 32 it would result in a cube texture that is too large for this graphics device. Textures have a maximum of 32 levels. usage is not a valid value. Texture resources can only be created with the following ResourceUsage options: ResourceUsage.AutoGenerateMipMap, ResourceUsage.ResolveTarget, ResourceUsage.Dynamic, ResourceUsage.Tiled, ResourceUsage.Linear and ResourceUsage.Automatic. format is SurfaceFormat.Unknown. Textures cannot be created using SurfaceFormat.Unknown. resourceManagementMode is not a valid value. resourceManagementMode must be either ResourceManagementMode.Manual or ResourceManagementMode.Automatic. The parameters specified are not compatible: format and numberLevels are incompatible. Multi-element textures of type SurfaceFormat.Multi2Bgra32 cannot be mipmapped, set numberLevels to 1. usage and numberLevels are incompatible. Textures specifying the usage ResourceUsage.AutoGenerateMipMap must set numberLevels to either 0 or 1. usage and resourceManagementMode are incompatible. Textures using ResourceManagementMode.Automatic cannot specify ResourceUsage.Dynamic or ResourceUsage.ResolveTarget.
ArgumentNullException	graphicsDevice is null.
ArgumentOutOfRangeException	edgeLength is less than or equal to zero. edgeLength must be greater than or equal to zero.

Remarks

A mipmap (texture) is a collection of successively downsampled (mipmapped) surfaces. An application can discover support for automatic generation of mipmaps in a particular format by calling CheckDeviceFormat with ResourceUsage.AutoGenerateMipMap.

A texel represents the smallest unit of a texture that can be read from or written to by the GPU. A texel is composed of 1 to 4 components. Specifically, a texel may be any one of the available texture formats represented in the SurfaceFormat enumeration.

A cube texture is a collection of six textures, one for each face of the cube. 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). Figure 1 shows a fully populated texture cube.

Figure 1.  TextureCube Resource Architecture

See Also

Reference

ContentManager.Load Generic Method
TextureCube.FromFile Method
TextureCube Class
TextureCube Members
Microsoft.Xna.Framework.Graphics Namespace

Platforms

Xbox 360, Windows XP SP2, Windows Vista