Texture3D Constructor

Creates an uninitialized volume texture resource of the given dimensions, specifying the memory management mode for the resource. To initialize a Texture3D 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 Texture3D (
         GraphicsDevice graphicsDevice,
         int width,
         int height,
         int depth,
         int numberLevels,
         ResourceUsage usage,
         SurfaceFormat format
)

Parameters

• graphicsDevice
  The GraphicsDevice that will display the volume texture.

• width
  The width, in pixels, of the top-level of the volume texture. This value must be a power of two if the RequiresPower2 property of graphicsDevice is true. The pixel dimensions of subsequent levels 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 two results in 0 (zero), 1 will be taken instead. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent.

• height
  The height, in pixels, of the top-level of the volume texture. This value must be a power of two if the RequiresPower2 property of graphicsDevice is true. The pixel dimensions of subsequent levels 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 two results in 0 (zero), 1 will be taken instead. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent.

• depth
  The depth, in pixels, of the top-level of the volume texture. This value must be a power of two if the RequiresVolumeMapPower2 property of graphicsDevice is true. The pixel dimensions of subsequent levels 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 two results in 0 (zero), 1 will be taken instead. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent.

• numberLevels
  The number of downsampled surfaces to create 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 texture sublevels down to 1×1 pixels will be generated for hardware that supports mipmapped textures. Use LevelCount to see the number of levels generated.

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

• format
  The format of all levels in the volume texture resource.

Exceptions

Exception type	Condition
ArgumentNullException	graphicsDevice is null.
ArgumentOutOfRangeException	width, height, or depth is less than or equal to zero. width, height and depth must be greater than zero.
ArgumentException	One of the following conditions is true: numberLevels is too large for a texture cube of this size. numberLevels is greater than 32. Textures have a maximum of 32 levels. format is SurfaceFormat.Unknown. Textures cannot be created using SurfaceFormat.Unknown. usage is not a valid value. Texture3D resources cannot specify ResourceUsage.ResolveTarget. Texture resources can only be created with the following ResourceUsage options: ResourceUsage.AutoGenerateMipMap, ResourceUsage.Dynamic, ResourceUsage.Tiled, ResourceUsage.Linear and ResourceUsage.Automatic. The combination of width, height and depth requested results in a resource that is too larg. format and numberLevels are incompatible. Multi-element textures of type SurfaceFormat.Multi2Bgra32 cannot be mipmapped, set numberLevels to 1. usage and resourceManagementMode are incompatible. Textures using ResourceManagementMode.Automatic cannot specify ResourceUsage.Dynamic or ResourceUsage.ResolveTarget. The format and usage requested are not supported by the graphics device. The device does not support creating a texture of the given format with the given ResourceUsage.
OutOfVideoMemoryException	Unable to create this resource on the graphics device.

Remarks

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 resource (also known as a volume texture) contains a 3D volume of texels. Since it is a texture resource, it may contain mipmap levels. Figure 1 shows a fully populated **** resource.

Figure 1.  Texture3D Resource Architecture

When a mipmap slice is bound as a render target output (by creating a RenderTargetCube), the **** behaves identically to an array of Texture2D objects with n array slices, where n is the depth (third dimension) of the .

See Also

Reference

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

Platforms

Xbox 360, Windows XP SP2, Windows Vista