Class Image

Namespace

Stride.Graphics

Assembly

Stride.dll

Provides method to instantiate an image 1D/2D/3D supporting TextureArray and mipmaps on the CPU or to load/save an image from the disk.

[ContentSerializer(typeof(ImageSerializer))]
public sealed class Image : IDisposable

Inheritance

object

Image

Implements

IDisposable

Extension Methods

ComponentBaseExtensions.DisposeBy<T>(T, ICollectorHolder)

ComponentBaseExtensions.RemoveDisposeBy<T>(T, ICollectorHolder)

Fields

Description

Description of this image.

public ImageDescription Description

Field Value

ImageDescription

Properties

DataPointer

Gets a pointer to the image buffer in memory.

public IntPtr DataPointer { get; }

Property Value

IntPtr

A pointer to the image buffer in memory.

PixelBuffer

Provides access to all pixel buffers.

public PixelBufferArray PixelBuffer { get; }

Property Value

PixelBufferArray

Remarks

For Texture3D, each z slice of the Texture3D has a pixelBufferArray * by the number of mipmaps. For other textures, there is Description.MipLevels * Description.ArraySize pixel buffers.

TotalSizeInBytes

Gets the total number of bytes occupied by this image in memory.

public int TotalSizeInBytes { get; }

Property Value

int

Methods

CalculateMipLevels(int, MipMapCount)

Calculates the number of miplevels for a Texture 1D.

public static int CalculateMipLevels(int width, MipMapCount mipLevels)

Parameters

width int

The width of the texture.

mipLevels MipMapCount

A MipMapCount, set to true to calculates all mipmaps, to false to calculate only 1 miplevel, or > 1 to calculate a specific amount of levels.

Returns

int

The number of miplevels.

CalculateMipLevels(int, int, MipMapCount)

Calculates the number of miplevels for a Texture 2D.

public static int CalculateMipLevels(int width, int height, MipMapCount mipLevels)

Parameters

width int

The width of the texture.

height int

The height of the texture.

mipLevels MipMapCount

A MipMapCount, set to true to calculates all mipmaps, to false to calculate only 1 miplevel, or > 1 to calculate a specific amount of levels.

Returns

int

The number of miplevels.

CalculateMipLevels(int, int, int, MipMapCount)

Calculates the number of miplevels for a Texture 2D.

public static int CalculateMipLevels(int width, int height, int depth, MipMapCount mipLevels)

Parameters

width int

The width of the texture.

height int

The height of the texture.

depth int

The depth of the texture.

mipLevels MipMapCount

A MipMapCount, set to true to calculates all mipmaps, to false to calculate only 1 miplevel, or > 1 to calculate a specific amount of levels.

Returns

int

The number of miplevels.

CalculateMipSize(int, int)

public static int CalculateMipSize(int width, int mipLevel)

Parameters

width int

mipLevel int

Returns

int

Clear()

Reset the buffer (by default it is not cleared)

public void Clear()

ConvertFormatToNonSRgb()

Converts the format of the description and the pixel buffers to non sRGB.

public void ConvertFormatToNonSRgb()

ConvertFormatToSRgb()

Converts the format of the description and the pixel buffers to sRGB.

public void ConvertFormatToSRgb()

CountMips(int)

public static int CountMips(int width)

Parameters

width int

Returns

int

CountMips(int, int)

public static int CountMips(int width, int height)

Parameters

width int

height int

Returns

int

CountMips(int, int, int)

public static int CountMips(int width, int height, int depth)

Parameters

width int

height int

depth int

Returns

int

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetMipMapDescription(int)

Gets the mipmap description of this instance for the specified mipmap level.

public MipMapDescription GetMipMapDescription(int mipmap)

Parameters

mipmap int

The mipmap.

Returns

MipMapDescription

A description of a particular mipmap for this texture.

GetPixelBuffer(int, int)

Gets the pixel buffer for the specified array/z slice and mipmap level.

public PixelBuffer GetPixelBuffer(int arrayOrZSliceIndex, int mipmap)

Parameters

arrayOrZSliceIndex int

For 3D image, the parameter is the Z slice, otherwise it is an index into the texture array.

mipmap int

The mipmap.

Returns

PixelBuffer

A PixelBuffer.

Exceptions

ArgumentException

If arrayOrZSliceIndex or mipmap are out of range.

GetPixelBuffer(int, int, int)

Gets the pixel buffer for the specified array/z slice and mipmap level.

public PixelBuffer GetPixelBuffer(int arrayIndex, int zIndex, int mipmap)

Parameters

arrayIndex int

Index into the texture array. Must be set to 0 for 3D images.

zIndex int

Z index for 3D image. Must be set to 0 for all 1D/2D images.

mipmap int

The mipmap.

Returns

PixelBuffer

A PixelBuffer.

Exceptions

ArgumentException

If arrayIndex, zIndex or mipmap are out of range.

Load(DataPointer, bool, bool)

Loads an image from an unmanaged memory pointer.

public static Image Load(DataPointer dataBuffer, bool makeACopy = false, bool loadAsSRGB = false)

Parameters

dataBuffer DataPointer

Pointer to an unmanaged memory. If makeACopy is false, this buffer must be allocated with AllocateMemory(int, int).

makeACopy bool

True to copy the content of the buffer to a new allocated buffer, false otherwise.

loadAsSRGB bool

Indicate if the image should be loaded as an sRGB texture

Returns

Image

An new image.

Remarks

If makeACopy is set to false, the returned image is now the holder of the unmanaged pointer and will release it on Dispose.

Load(byte[], bool)

Loads an image from a managed buffer.

public static Image Load(byte[] buffer, bool loadAsSRGB = false)

Parameters

buffer byte[]

Reference to a managed buffer.

loadAsSRGB bool

Indicate if the image should be loaded as an sRGB texture

Returns

Image

An new image.

Remarks

This method support the following format: dds, bmp, jpg, png, gif, tiff, wmp, tga.

Load(Stream, bool)

Loads the specified image from a stream.

public static Image Load(Stream imageStream, bool loadAsSRGB = false)

Parameters

imageStream Stream

The image stream.

loadAsSRGB bool

Indicate if the image should be loaded as an sRGB texture. If false, the image is loaded in its default format.

Returns

Image

An new image.

Remarks

This method support the following format: dds, bmp, jpg, png, gif, tiff, wmp, tga.

Load(IntPtr, int, bool, bool)

Loads an image from an unmanaged memory pointer.

public static Image Load(IntPtr dataPointer, int dataSize, bool makeACopy = false, bool loadAsSRGB = false)

Parameters

dataPointer IntPtr

Pointer to an unmanaged memory. If makeACopy is false, this buffer must be allocated with AllocateMemory(int, int).

dataSize int

Size of the unmanaged buffer.

makeACopy bool

True to copy the content of the buffer to a new allocated buffer, false otherwise.

loadAsSRGB bool

Indicate if the image should be loaded as an sRGB texture

Returns

Image

An new image.

Remarks

If makeACopy is set to false, the returned image is now the holder of the unmanaged pointer and will release it on Dispose.

New(ImageDescription)

Creates a new instance of Image from an image description.

public static Image New(ImageDescription description)

Parameters

description ImageDescription

The image description.

Returns

Image

A new image.

New(ImageDescription, IntPtr)

Creates a new instance of Image from an image description.

public static Image New(ImageDescription description, IntPtr dataPointer)

Parameters

description ImageDescription

The image description.

dataPointer IntPtr

Pointer to an existing buffer.

Returns

Image

A new image.

New(ImageDescription, IntPtr, int, GCHandle?, bool)

Initializes a new instance of the Image class.

public static Image New(ImageDescription description, IntPtr dataPointer, int offset, GCHandle? handle, bool bufferIsDisposable)

Parameters

description ImageDescription

The image description.

dataPointer IntPtr

The pointer to the data buffer.

offset int

The offset from the beginning of the data buffer.

handle GCHandle?

The handle (optionnal).

bufferIsDisposable bool

if set to true [buffer is disposable].

Returns

Image

Exceptions

InvalidOperationException

If the format is invalid, or width/height/depth/arraysize is invalid with respect to the dimension.

New1D(int, MipMapCount, PixelFormat, int)

Creates a new instance of a 1D Image.

public static Image New1D(int width, MipMapCount mipMapCount, PixelFormat format, int arraySize = 1)

Parameters

width int

The width.

mipMapCount MipMapCount

The mip map count.

format PixelFormat

The format.

arraySize int

Size of the array.

Returns

Image

A new image.

New1D(int, MipMapCount, PixelFormat, int, IntPtr)

Creates a new instance of a 1D Image.

public static Image New1D(int width, MipMapCount mipMapCount, PixelFormat format, int arraySize, IntPtr dataPointer)

Parameters

width int

The width.

mipMapCount MipMapCount

The mip map count.

format PixelFormat

The format.

arraySize int

Size of the array.

dataPointer IntPtr

Pointer to an existing buffer.

Returns

Image

A new image.

New2D(int, int, MipMapCount, PixelFormat, int, int)

Creates a new instance of a 2D Image.

public static Image New2D(int width, int height, MipMapCount mipMapCount, PixelFormat format, int arraySize = 1, int rowStride = 0)

Parameters

width int

The width.

height int

The height.

mipMapCount MipMapCount

The mip map count.

format PixelFormat

The format.

arraySize int

Size of the array.

rowStride int

Returns

Image

A new image.

New2D(int, int, MipMapCount, PixelFormat, int, IntPtr, int)

Creates a new instance of a 2D Image.

public static Image New2D(int width, int height, MipMapCount mipMapCount, PixelFormat format, int arraySize, IntPtr dataPointer, int rowStride = 0)

Parameters

width int

The width.

height int

The height.

mipMapCount MipMapCount

The mip map count.

format PixelFormat

The format.

arraySize int

Size of the array.

dataPointer IntPtr

Pointer to an existing buffer.

rowStride int

Specify a specific rowStride, only valid when mipMapCount == 1 and pixel format is not compressed.

Returns

Image

A new image.

New3D(int, int, int, MipMapCount, PixelFormat)

Creates a new instance of a 3D Image.

public static Image New3D(int width, int height, int depth, MipMapCount mipMapCount, PixelFormat format)

Parameters

width int

The width.

height int

The height.

depth int

The depth.

mipMapCount MipMapCount

The mip map count.

format PixelFormat

The format.

Returns

Image

A new image.

New3D(int, int, int, MipMapCount, PixelFormat, IntPtr)

Creates a new instance of a 3D Image.

public static Image New3D(int width, int height, int depth, MipMapCount mipMapCount, PixelFormat format, IntPtr dataPointer)

Parameters

width int

The width.

height int

The height.

depth int

The depth.

mipMapCount MipMapCount

The mip map count.

format PixelFormat

The format.

dataPointer IntPtr

Pointer to an existing buffer.

Returns

Image

A new image.

NewCube(int, MipMapCount, PixelFormat)

Creates a new instance of a Cube Image.

public static Image NewCube(int width, MipMapCount mipMapCount, PixelFormat format)

Parameters

width int

The width.

mipMapCount MipMapCount

The mip map count.

format PixelFormat

The format.

Returns

Image

A new image.

NewCube(int, MipMapCount, PixelFormat, IntPtr)

Creates a new instance of a Cube Image.

public static Image NewCube(int width, MipMapCount mipMapCount, PixelFormat format, IntPtr dataPointer)

Parameters

width int

The width.

mipMapCount MipMapCount

The mip map count.

format PixelFormat

The format.

dataPointer IntPtr

Pointer to an existing buffer.

Returns

Image

A new image.

Register(ImageFileType, ImageLoadDelegate, ImageSaveDelegate)

Registers a loader/saver for a specified image file type.

public static void Register(ImageFileType type, Image.ImageLoadDelegate loader, Image.ImageSaveDelegate saver)

Parameters

type ImageFileType

The file type (use integer and explicit casting to ImageFileType to register other fileformat.

loader Image.ImageLoadDelegate

The loader delegate (can be null).

saver Image.ImageSaveDelegate

The saver delegate (can be null).

Exceptions

ArgumentException

Save(Stream, ImageFileType)

Saves this instance to a stream.

public void Save(Stream imageStream, ImageFileType fileType)

Parameters

imageStream Stream

The destination stream.

fileType ImageFileType

Specify the output format.

Remarks

This method support the following format: dds, bmp, jpg, png, gif, tiff, wmp, tga.

ToDataBox()

Gets the databox from this image.

public DataBox[] ToDataBox()

Returns

DataBox[]

The databox of this image.