Class Texture2D

Namespace

Microsoft.Xna.Framework.Graphics

Assembly

MonoGame.Framework.dll

Represents a 2D grid of texels.

public class Texture2D : Texture, IDisposable

Inheritance

object

GraphicsResource

Texture

Texture2D

Implements

IDisposable

Derived

RenderTarget2D

Inherited Members

Texture.Format

Texture.LevelCount

Texture.GraphicsDeviceResetting()

Texture.Dispose(bool)

GraphicsResource.Dispose()

GraphicsResource.Disposing

GraphicsResource.GraphicsDevice

GraphicsResource.IsDisposed

GraphicsResource.Name

GraphicsResource.Tag

GraphicsResource.ToString()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

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.

Constructors

Texture2D(GraphicsDevice, int, int)

Creates an uninitialized Texture2D resource with the specified parameters.

public Texture2D(GraphicsDevice graphicsDevice, int width, int height)

Parameters

graphicsDevice GraphicsDevice

The graphics device used to display the texture.

width int

The width, in pixels, of the texture.

height int

The height, in pixels, of the texture.

Remarks

To initialize the texture with data after creating, you can use one of the SetData method.

To initialize a Texture2D from an existing file use the ContentManager.Load method if loading a pipeline preprocessed Texture2D from an .xnb file or Texture2D.FromFile to load directly from a file.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height less than or equal to zero.

Texture2D(GraphicsDevice, int, int, bool, SurfaceFormat)

Creates an uninitialized Texture2D resource with the specified parameters.

public Texture2D(GraphicsDevice graphicsDevice, int width, int height, bool mipmap, SurfaceFormat format)

Parameters

graphicsDevice GraphicsDevice

The graphics device used to display the texture.

width int

The width, in pixels, of the texture.

height int

The height, in pixels, of the texture.

mipmap bool

true if mimapping is enabled for the texture; otherwise, false.

format SurfaceFormat

The surface format of the texture.

Remarks

To initialize the texture with data after creating, you can use one of the SetData method.

To initialize a Texture2D from an existing file use the ContentManager.Load method if loading a pipeline preprocessed Texture2D from an .xnb file or Texture2D.FromFile to load directly from a file.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height less than or equal to zero.

Texture2D(GraphicsDevice, int, int, bool, SurfaceFormat, SurfaceType, bool, int)

Creates an uninitialized Texture2D resource with the specified parameters.

protected Texture2D(GraphicsDevice graphicsDevice, int width, int height, bool mipmap, SurfaceFormat format, Texture2D.SurfaceType type, bool shared, int arraySize)

Parameters

graphicsDevice GraphicsDevice

The graphics device used to display the texture.

width int

The width, in pixels, of the texture.

height int

The height, in pixels, of the texture.

mipmap bool

true if mimapping is enabled for the texture; otherwise, false.

format SurfaceFormat

The surface format of the texture.

type Texture2D.SurfaceType

The surface type of the texture

shared bool

Whether this render target resource should be a shared resource accessible on another device. This property is only valid for DirectX targets.

arraySize int

The size of the texture array.

Remarks

To initialize the texture with data after creating, you can use one of the SetData method.

To initialize a Texture2D from an existing file use the ContentManager.Load method if loading a pipeline preprocessed Texture2D from an .xnb file or Texture2D.FromFile to load directly from a file.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height less than or equal to zero.

ArgumentException

The arraySize parameter is greater than 1 and the graphics device does not support texture arrays.

Texture2D(GraphicsDevice, int, int, bool, SurfaceFormat, int)

Creates an uninitialized Texture2D resource with the specified parameters.

public Texture2D(GraphicsDevice graphicsDevice, int width, int height, bool mipmap, SurfaceFormat format, int arraySize)

Parameters

graphicsDevice GraphicsDevice

The graphics device used to display the texture.

width int

The width, in pixels, of the texture.

height int

The height, in pixels, of the texture.

mipmap bool

true if mimapping is enabled for the texture; otherwise, false.

format SurfaceFormat

The surface format of the texture.

arraySize int

The size of the texture array.

Remarks

To initialize the texture with data after creating, you can use one of the SetData method.

To initialize a Texture2D from an existing file use the ContentManager.Load method if loading a pipeline preprocessed Texture2D from an .xnb file or Texture2D.FromFile to load directly from a file.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height less than or equal to zero.

ArgumentException

The arraySize parameter is greater than 1 and the graphics device does not support texture arrays.

Properties

Bounds

Gets the dimensions of the texture

public Rectangle Bounds { get; }

Property Value

Rectangle

Height

Gets the height of the texture in pixels.

public int Height { get; }

Property Value

int

Width

Gets the width of the texture in pixels.

public int Width { get; }

Property Value

int

Methods

FromFile(GraphicsDevice, string)

Creates a Texture2D from a file, supported formats bmp, gif, jpg, png, tif and dds (only for simple textures). May work with other formats, but will not work with tga files. This internally calls FromStream(GraphicsDevice, Stream, Action<byte[]>).

public static Texture2D FromFile(GraphicsDevice graphicsDevice, string path)

Parameters

graphicsDevice GraphicsDevice

The graphics device to use to create the texture.

path string

The path to the image file.

Returns

Texture2D

The Texture2D created from the given file.

Remarks

Note that different image decoders may generate slight differences between platforms, but perceptually the images should be identical. This call does not premultiply the image alpha, but areas of zero alpha will result in black color data.

FromFile(GraphicsDevice, string, Action<byte[]>)

Creates a Texture2D from a file, supported formats bmp, gif, jpg, png, tif and dds (only for simple textures). May work with other formats, but will not work with tga files. This internally calls FromFile(GraphicsDevice, string, Action<byte[]>).

public static Texture2D FromFile(GraphicsDevice graphicsDevice, string path, Action<byte[]> colorProcessor)

Parameters

graphicsDevice GraphicsDevice

The graphics device to use to create the texture.

path string

The path to the image file.

colorProcessor Action<byte[]>

Function that is applied to the data in RGBA format before the texture is sent to video memory. Could be null(no processing then).

Returns

Texture2D

The Texture2D created from the given file.

Remarks

Note that different image decoders may generate slight differences between platforms, but perceptually the images should be identical.

FromStream(GraphicsDevice, Stream)

Creates a Texture2D from a stream, supported formats bmp, gif, jpg, png, tif and dds (only for simple textures). May work with other formats, but will not work with tga files.

public static Texture2D FromStream(GraphicsDevice graphicsDevice, Stream stream)

Parameters

graphicsDevice GraphicsDevice

The graphics device to use to create the texture.

stream Stream

The stream from which to read the image data.

Returns

Texture2D

The Texture2D created from the image stream.

Remarks

Note that different image decoders may generate slight differences between platforms, but perceptually the images should be identical. This call does not premultiply the image alpha, but areas of zero alpha will result in black color data.

FromStream(GraphicsDevice, Stream, Action<byte[]>)

Creates a Texture2D from a stream, supported formats bmp, gif, jpg, png, tif and dds (only for simple textures). May work with other formats, but will not work with tga files.

public static Texture2D FromStream(GraphicsDevice graphicsDevice, Stream stream, Action<byte[]> colorProcessor)

Parameters

graphicsDevice GraphicsDevice

The graphics device to use to create the texture.

stream Stream

The stream from which to read the image data.

colorProcessor Action<byte[]>

Function that is applied to the data in RGBA format before the texture is sent to video memory. Could be null(no processing then).

Returns

Texture2D

The Texture2D created from the image stream.

Remarks

Note that different image decoders may generate slight differences between platforms, but perceptually the images should be identical.

GetData<T>(int, int, Rectangle?, T[], int, int)

Copies texture data into an array

public void GetData<T>(int level, int arraySlice, Rectangle? rect, T[] data, int startIndex, int elementCount) where T : struct

Parameters

level int

The mipmap level to copy from.

arraySlice int

Index inside the texture array

rect Rectangle?

The section of the texture where the data will be copied from. null indicates the data will be copied over the entire texture.

data T[]

The array to receive texture data. If rect is null, the number of elements in the array must be equal to the size of the texture, which is Width x Height; otherwise, the number of elements in the array should be equal to the size of the rectangle.

startIndex int

The index of the element in the array at which to start copying.

elementCount int

The number of elements to copy.

Type Parameters

T

The type of the elements in the array.

Exceptions

ArgumentException

One of the following conditions is true:

• The level parameter is larger than the number of levels in this texture.
• The arraySlice parameter is greater than zero and the texture arrays are not supported on the graphics device.
• The arraySlice parameter is less than zero or is greater than or equal to the internal array buffer of this texture.
• The rect is outside the bounds of the texture.
• The T type size is invalid for the format of this texture.
• The startIndex parameter is less than zero or is greater than or equal to the length of the data array.
• The data array parameter is too small. length of the data array.

ArgumentNullException

The data parameter is null.

GetData<T>(int, Rectangle?, T[], int, int)

Copies texture data into an array

public void GetData<T>(int level, Rectangle? rect, T[] data, int startIndex, int elementCount) where T : struct

Parameters

level int

The mipmap level to copy from.

rect Rectangle?

The section of the texture where the data will be copied from. null indicates the data will be copied over the entire texture.

data T[]

The array to receive texture data. If rect is null, the number of elements in the array must be equal to the size of the texture, which is Width x Height; otherwise, the number of elements in the array should be equal to the size of the rectangle.

startIndex int

The index of the element in the array at which to start copying.

elementCount int

The number of elements to copy.

Type Parameters

T

The type of the elements in the array.

Exceptions

ArgumentException

One of the following conditions is true:

• The level parameter is larger than the number of levels in this texture.
• The rect is outside the bounds of the texture.
• The T type size is invalid for the format of this texture.
• The startIndex parameter is less than zero or is greater than or equal to the length of the data array.
• The data array parameter is too small. length of the data array.

ArgumentNullException

The data parameter is null.

GetData<T>(T[])

Copies texture data into an array

public void GetData<T>(T[] data) where T : struct

Parameters

data T[]

The array to receive texture data.

Type Parameters

T

The type of the elements in the array.

Exceptions

ArgumentException

One of the following conditions is true:

• The T type size is invalid for the format of this texture.
• The data array parameter is too small. length of the data array.

ArgumentNullException

The data parameter is null.

GetData<T>(T[], int, int)

Copies texture data into an array

public void GetData<T>(T[] data, int startIndex, int elementCount) where T : struct

Parameters

data T[]

The array to receive texture data.

startIndex int

The index of the element in the array at which to start copying.

elementCount int

The number of elements to copy.

Type Parameters

T

The type of the elements in the array.

Exceptions

ArgumentException

One of the following conditions is true:

• The T type size is invalid for the format of this texture.
• The startIndex parameter is less than zero or is greater than or equal to the length of the data array.
• The data array parameter is too small. length of the data array.

ArgumentNullException

The data parameter is null.

Reload(Stream)

Reloads the texture

public void Reload(Stream textureStream)

Parameters

textureStream Stream

Remarks

This method allows games that use Texture2D.FromStream to reload their textures after the GL context is lost.

SaveAsJpeg(Stream, int, int)

Converts the texture to a JPG image

public void SaveAsJpeg(Stream stream, int width, int height)

Parameters

stream Stream

Destination for the image

width int

The width, in pixels, of the image.

height int

The height, in pixels, of the image.

SaveAsPng(Stream, int, int)

Converts the texture to a PNG image

public void SaveAsPng(Stream stream, int width, int height)

Parameters

stream Stream

Destination for the image

width int

The width, in pixels, of the image.

height int

The height, in pixels, of the image.

SetData<T>(int, int, Rectangle?, T[], int, int)

Copies an array of data to the texture.

public void SetData<T>(int level, int arraySlice, Rectangle? rect, T[] data, int startIndex, int elementCount) where T : struct

Parameters

level int

The mipmap level where the data will be placed.

arraySlice int

Index inside the texture array

rect Rectangle?

The section of the texture where the data will be placed. null indicates the data will be copied over the entire texture.

data T[]

The array of data to copy. If rect is null, the number of elements in the array must be equal to the size of the texture, which is Width x Height; otherwise, the number of elements in the array should be equal to the size of the rectangle.

startIndex int

The index of the element in the array at which to start copying.

elementCount int

The number of elements to copy.

Type Parameters

T

The type of the elements in the array.

Exceptions

ArgumentException

One of the following conditions is true:

• The level parameter is larger than the number of levels in this texture.
• The arraySlice parameter is greater than zero and the texture arrays are not supported on the graphics device.
• The arraySlice parameter is less than zero or is greater than or equal to the internal array buffer of this texture.
• The rect is outside the bounds of the texture.
• The T type size is invalid for the format of this texture.
• The startIndex parameter is less than zero or is greater than or equal to the length of the data array.
• The data array parameter is too small. length of the data array.

ArgumentNullException

The data parameter is null.

SetData<T>(int, Rectangle?, T[], int, int)

Copies an array of data to the texture.

public void SetData<T>(int level, Rectangle? rect, T[] data, int startIndex, int elementCount) where T : struct

Parameters

level int

The mipmap level where the data will be placed.

rect Rectangle?

The section of the texture where the data will be placed. null indicates the data will be copied over the entire texture.

data T[]

The array of data to copy. If rect is null, the number of elements in the array must be equal to the size of the texture, which is Width x Height; otherwise, the number of elements in the array should be equal to the size of the rectangle.

startIndex int

The index of the element in the array at which to start copying.

elementCount int

The number of elements to copy.

Type Parameters

T

The type of the elements in the array.

Exceptions

ArgumentException

One of the following conditions is true:

• The level parameter is larger than the number of levels in this texture.
• The rect is outside the bounds of the texture.
• The T type size is invalid for the format of this texture.
• The startIndex parameter is less than zero or is greater than or equal to the length of the data array.
• The data array parameter is too small. length of the data array.

ArgumentNullException

The data parameter is null.

SetData<T>(T[])

Copies an array of data to the texture.

public void SetData<T>(T[] data) where T : struct

Parameters

data T[]

The array of data to copy.

Type Parameters

T

The type of the elements in the array.

Exceptions

ArgumentException

One of the following conditions is true:

• The T type size is invalid for the format of this texture.
• The data array parameter is too small. length of the data array.

ArgumentNullException

The data parameter is null.

SetData<T>(T[], int, int)

Copies an array of data to the texture.

public void SetData<T>(T[] data, int startIndex, int elementCount) where T : struct

Parameters

data T[]

The array of data to copy.

startIndex int

The index of the element in the array at which to start copying.

elementCount int

The number of elements to copy.

Type Parameters

T

The type of the elements in the array.

Exceptions

ArgumentException

One of the following conditions is true:

• The T type size is invalid for the format of this texture.
• The startIndex parameter is less than zero or is greater than or equal to the length of the data array.
• The data array parameter is too small. length of the data array.

ArgumentNullException

The data parameter is null.