Texture2D Constructor (GraphicsDevice, Int32, Int32, Int32, ResourceUsage, SurfaceFormat, ResourceManagementMode)

Creates an uninitialized Texture2D resource of the given dimensions, specifying the memory management mode for the resource. To initialize a Texture2D from an existing file, see the static method ContentManager.Load or Texture2D.FromFile.

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

Syntax

public Texture2D (
         GraphicsDevice graphicsDevice,
         int width,
         int height,
         int numberLevels,
         ResourceUsage usage,
         SurfaceFormat format,
         ResourceManagementMode resourceManagementMode
)

Parameters

• graphicsDevice
  The GraphicsDevice used to display the texture.

• width
  The width of the texture, in pixels. This value must be a power of two if the RequiresPower2 property of graphicsDevice is true. If this value is 0, a value of 1 is used.

• height
  The height of the texture, in pixels. This value must be a power of two if the RequiresPower2 property of graphicsDevice is true. If this value is 0, a value of 1 is used.

• 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 texture resource. If resourceManagementMode is ResourceManagementMode.Automatic, this value cannot be ResourceUsage.Dynamic. If the texture is to be used as a destination texture in a call to GraphicsDevice.ResolveBackBuffer, this value must be ResourceUsage.ResolveTarget.

• format
  A SurfaceFormat value specifying the requested pixel format for the texture. The returned texture may be of a different format if the device does not support the requested format. Applications should check the format of the returned texture to ensure that it matches the requested format.

• resourceManagementMode
  The memory management mode for this texture resource. If this value is ResourceManagementMode.Automatic, the runtime will recreate the resource when the graphics device is reset. If this value is ResourceManagementMode.Manual, this resource should be reinitialized when the graphics device is reset.

Exceptions

Exception type	Condition
ArgumentNullException	graphicsDevice is null.
ArgumentException	One of the following conditions is true: width is larger than MaxTextureWidth. height is larger than MaxTextureHeight. numberLevels is greater than 32. 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. 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.
ArgumentOutOfRangeException	width or height is less than or equal to zero. width and height must be greater than zero.
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 Texture2D resource contains a 2D grid of texels. Each texel is addressable by a u, v vector. Since it is a texture resource, it may contain mipmap levels. Figure 1 shows a fully populated 2D texture resource.

Figure 1.  Texture2D Resource Architecture

This texture resource contains a single 3×5 texture with three mipmap levels.

Example

In this example, a new Texture2D is created for use as a render target, the data is initialized with a call to ResolveBackBuffer, and the generation of mipmaps for the resolved render target is requested.

Texture2D renderTargetTexture;

renderTargetTexture = new Texture2D(
    graphics.GraphicsDevice, 
    graphics.GraphicsDevice.PresentationParameters.BackBufferWidth,
    graphics.GraphicsDevice.PresentationParameters.BackBufferHeight, 
    0, 
    ResourceUsage.ResolveTarget | ResourceUsage.AutoGenerateMipMap, 
    graphics.GraphicsDevice.PresentationParameters.BackBufferFormat,
    ResourceManagementMode.Manual 
    );

graphics.GraphicsDevice.ResolveBackBuffer( renderTargetTexture );
renderTargetTexture.GenerateMipMaps( TextureFilter.Linear );

See Also

Tasks

How to: Load Resources

Reference

ContentManager.Load Generic Method
GraphicsDeviceManager.DeviceReset Event
Texture2D.FromFile Method
Texture2D.SetData Method
GraphicsDevice.ResolveBackBuffer Method
Texture2D Class
Texture2D Members
Microsoft.Xna.Framework.Graphics Namespace

Platforms

Xbox 360, Windows XP SP2, Windows Vista