Table of Contents

Class Image

Namespace
Godot
Assembly
GodotSharp.dll

Native image datatype. Contains image data which can be converted to an ImageTexture and provides commonly used image processing methods. The maximum width and height for an Image are MaxWidth and MaxHeight.

An Image cannot be assigned to a texture property of an object directly (such as Texture), and has to be converted manually to an ImageTexture first.

Note: The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images may fail to import.

public class Image : Resource, IDisposable
Inheritance
Image
Implements
Inherited Members

Constructors

Image() 

public Image()

Fields

MaxHeight

The maximal height allowed for Image resources.

public const long MaxHeight = 16777216

Field Value

long

MaxWidth

The maximal width allowed for Image resources.

public const long MaxWidth = 16777216

Field Value

long

Properties

Data

Holds all the image's color data in a given format. See Image.Format constants.

public Dictionary Data { get; set; }

Property Value

Dictionary

Methods

AdjustBcs(float, float, float)

Adjusts this image's brightness, contrast, and saturation by the given values. Does not work if the image is compressed (see IsCompressed()).

public void AdjustBcs(float brightness, float contrast, float saturation)

Parameters

brightness float
contrast float
saturation float

BlendRect(Image, Rect2I, Vector2I)

Alpha-blends srcRect from src image to this image at coordinates dst, clipped accordingly to both image bounds. This image and src image must have the same format. srcRect with non-positive size is treated as empty.

public void BlendRect(Image src, Rect2I srcRect, Vector2I dst)

Parameters

src Image
srcRect Rect2I
dst Vector2I

BlendRectMask(Image, Image, Rect2I, Vector2I)

Alpha-blends srcRect from src image to this image using mask image at coordinates dst, clipped accordingly to both image bounds. Alpha channels are required for both src and mask. dst pixels and src pixels will blend if the corresponding mask pixel's alpha value is not 0. This image and src image must have the same format. src image and mask image must have the same size (width and height) but they can have different formats. srcRect with non-positive size is treated as empty.

public void BlendRectMask(Image src, Image mask, Rect2I srcRect, Vector2I dst)

Parameters

src Image
mask Image
srcRect Rect2I
dst Vector2I

BlitRect(Image, Rect2I, Vector2I)

Copies srcRect from src image to this image at coordinates dst, clipped accordingly to both image bounds. This image and src image must have the same format. srcRect with non-positive size is treated as empty.

public void BlitRect(Image src, Rect2I srcRect, Vector2I dst)

Parameters

src Image
srcRect Rect2I
dst Vector2I

BlitRectMask(Image, Image, Rect2I, Vector2I)

Blits srcRect area from src image to this image at the coordinates given by dst, clipped accordingly to both image bounds. src pixel is copied onto dst if the corresponding mask pixel's alpha value is not 0. This image and src image must have the same format. src image and mask image must have the same size (width and height) but they can have different formats. srcRect with non-positive size is treated as empty.

public void BlitRectMask(Image src, Image mask, Rect2I srcRect, Vector2I dst)

Parameters

src Image
mask Image
srcRect Rect2I
dst Vector2I

BumpMapToNormalMap(float)

Converts a bump map to a normal map. A bump map provides a height offset per-pixel, while a normal map provides a normal direction per pixel.

public void BumpMapToNormalMap(float bumpScale = 1)

Parameters

bumpScale float

ClearMipmaps()

Removes the image's mipmaps.

public void ClearMipmaps()

Compress(CompressMode, CompressSource, AstcFormat)

Compresses the image to use less memory. Can not directly access pixel data while the image is compressed. Returns error if the chosen compression mode is not available.

The source parameter helps to pick the best compression method for DXT and ETC2 formats. It is ignored for ASTC compression.

For ASTC compression, the astcFormat parameter must be supplied.

public Error Compress(Image.CompressMode mode, Image.CompressSource source = CompressSource.Generic, Image.AstcFormat astcFormat = AstcFormat.Format4X4)

Parameters

mode Image.CompressMode
source Image.CompressSource
astcFormat Image.AstcFormat

Returns

Error

CompressFromChannels(CompressMode, UsedChannels, AstcFormat)

Compresses the image to use less memory. Can not directly access pixel data while the image is compressed. Returns error if the chosen compression mode is not available.

This is an alternative to Compress(CompressMode, CompressSource, AstcFormat) that lets the user supply the channels used in order for the compressor to pick the best DXT and ETC2 formats. For other formats (non DXT or ETC2), this argument is ignored.

For ASTC compression, the astcFormat parameter must be supplied.

public Error CompressFromChannels(Image.CompressMode mode, Image.UsedChannels channels, Image.AstcFormat astcFormat = AstcFormat.Format4X4)

Parameters

mode Image.CompressMode
channels Image.UsedChannels
astcFormat Image.AstcFormat

Returns

Error

ComputeImageMetrics(Image, bool)

Compute image metrics on the current image and the compared image.

The dictionary contains max, mean, mean_squared, root_mean_squared and peak_snr.

public Dictionary ComputeImageMetrics(Image comparedImage, bool useLuma)

Parameters

comparedImage Image
useLuma bool

Returns

Dictionary

Convert(Format)

Converts the image's format. See Image.Format constants.

public void Convert(Image.Format format)

Parameters

format Image.Format

CopyFrom(Image)

Copies src image to this image.

public void CopyFrom(Image src)

Parameters

src Image

Create(int, int, bool, Format)

Creates an empty image of given size and format. See Image.Format constants. If useMipmaps is true, then generate mipmaps for this image. See the GenerateMipmaps(bool).

public static Image Create(int width, int height, bool useMipmaps, Image.Format format)

Parameters

width int
height int
useMipmaps bool
format Image.Format

Returns

Image

CreateFromData(int, int, bool, Format, byte[])

Creates a new image of given size and format. See Image.Format constants. Fills the image with the given raw data. If useMipmaps is true then loads mipmaps for this image from data. See GenerateMipmaps(bool).

public static Image CreateFromData(int width, int height, bool useMipmaps, Image.Format format, byte[] data)

Parameters

width int
height int
useMipmaps bool
format Image.Format
data byte[]

Returns

Image

Crop(int, int)

Crops the image to the given width and height. If the specified size is larger than the current size, the extra area is filled with black pixels.

public void Crop(int width, int height)

Parameters

width int
height int

Decompress()

Decompresses the image if it is VRAM compressed in a supported format. Returns Ok if the format is supported, otherwise Unavailable.

Note: The following formats can be decompressed: DXT, RGTC, BPTC. The formats ETC1 and ETC2 are not supported.

public Error Decompress()

Returns

Error

DetectAlpha()

Returns Blend if the image has data for alpha values. Returns Bit if all the alpha values are stored in a single bit. Returns None if no data for alpha values is found.

public Image.AlphaMode DetectAlpha()

Returns

Image.AlphaMode

DetectUsedChannels(CompressSource)

Returns the color channels used by this image, as one of the Image.UsedChannels constants. If the image is compressed, the original source must be specified.

public Image.UsedChannels DetectUsedChannels(Image.CompressSource source = CompressSource.Generic)

Parameters

source Image.CompressSource

Returns

Image.UsedChannels

Fill(Color)

Fills the image with color.

public void Fill(Color color)

Parameters

color Color

FillRect(Rect2I, Color)

Fills rect with color.

public void FillRect(Rect2I rect, Color color)

Parameters

rect Rect2I
color Color

FixAlphaEdges()

Blends low-alpha pixels with nearby pixels.

public void FixAlphaEdges()

FlipX()

Flips the image horizontally.

public void FlipX()

FlipY()

Flips the image vertically.

public void FlipY()

GenerateMipmaps(bool)

Generates mipmaps for the image. Mipmaps are precalculated lower-resolution copies of the image that are automatically used if the image needs to be scaled down when rendered. They help improve image quality and performance when rendering. This method returns an error if the image is compressed, in a custom format, or if the image's width/height is 0. Enabling renormalize when generating mipmaps for normal map textures will make sure all resulting vector values are normalized.

It is possible to check if the image has mipmaps by calling HasMipmaps() or GetMipmapCount(). Calling GenerateMipmaps(bool) on an image that already has mipmaps will replace existing mipmaps in the image.

public Error GenerateMipmaps(bool renormalize = false)

Parameters

renormalize bool

Returns

Error

GetData()

Returns a copy of the image's raw data.

public byte[] GetData()

Returns

byte[]

GetFormat()

Returns the image's format. See Image.Format constants.

public Image.Format GetFormat()

Returns

Image.Format

GetHeight()

Returns the image's height.

public int GetHeight()

Returns

int

GetMipmapCount()

Returns the number of mipmap levels or 0 if the image has no mipmaps. The largest main level image is not counted as a mipmap level by this method, so if you want to include it you can add 1 to this count.

public int GetMipmapCount()

Returns

int

GetMipmapOffset(int)

Returns the offset where the image's mipmap with index mipmap is stored in the Data dictionary.

public int GetMipmapOffset(int mipmap)

Parameters

mipmap int

Returns

int

GetPixel(int, int)

Returns the color of the pixel at (x, y).

This is the same as GetPixelv(Vector2I), but with two integer arguments instead of a Vector2I argument.

public Color GetPixel(int x, int y)

Parameters

x int
y int

Returns

Color

GetPixelv(Vector2I)

Returns the color of the pixel at point.

This is the same as GetPixel(int, int), but with a Vector2I argument instead of two integer arguments.

public Color GetPixelv(Vector2I point)

Parameters

point Vector2I

Returns

Color

GetRegion(Rect2I)

Returns a new Image that is a copy of this Image's area specified with region.

public Image GetRegion(Rect2I region)

Parameters

region Rect2I

Returns

Image

GetSize()

Returns the image's size (width and height).

public Vector2I GetSize()

Returns

Vector2I

GetUsedRect()

Returns a Rect2I enclosing the visible portion of the image, considering each pixel with a non-zero alpha channel as visible.

public Rect2I GetUsedRect()

Returns

Rect2I

GetWidth()

Returns the image's width.

public int GetWidth()

Returns

int

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

HasMipmaps()

Returns true if the image has generated mipmaps.

public bool HasMipmaps()

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

IsCompressed()

Returns true if the image is compressed.

public bool IsCompressed()

Returns

bool

IsEmpty()

Returns true if the image has no data.

public bool IsEmpty()

Returns

bool

IsInvisible()

Returns true if all the image's pixels have an alpha value of 0. Returns false if any pixel has an alpha value higher than 0.

public bool IsInvisible()

Returns

bool

Load(string)

Loads an image from file path. See Supported image formats for a list of supported image formats and limitations.

Warning: This method should only be used in the editor or in cases when you need to load external images at run-time, such as images located at the user:// directory, and may not work in exported projects.

See also ImageTexture description for usage examples.

public Error Load(string path)

Parameters

path string

Returns

Error

LoadBmpFromBuffer(byte[])

Loads an image from the binary contents of a BMP file.

Note: Godot's BMP module doesn't support 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported.

Note: This method is only available in engine builds with the BMP module enabled. By default, the BMP module is enabled, but it can be disabled at build-time using the module_bmp_enabled=no SCons option.

public Error LoadBmpFromBuffer(byte[] buffer)

Parameters

buffer byte[]

Returns

Error

LoadFromFile(string)

Creates a new Image and loads data from the specified file.

public static Image LoadFromFile(string path)

Parameters

path string

Returns

Image

LoadJpgFromBuffer(byte[])

Loads an image from the binary contents of a JPEG file.

public Error LoadJpgFromBuffer(byte[] buffer)

Parameters

buffer byte[]

Returns

Error

LoadKtxFromBuffer(byte[])

Loads an image from the binary contents of a KTX file. Unlike most image formats, KTX can store VRAM-compressed data and embed mipmaps.

Note: Godot's libktx implementation only supports 2D images. Cubemaps, texture arrays, and de-padding are not supported.

Note: This method is only available in engine builds with the KTX module enabled. By default, the KTX module is enabled, but it can be disabled at build-time using the module_ktx_enabled=no SCons option.

public Error LoadKtxFromBuffer(byte[] buffer)

Parameters

buffer byte[]

Returns

Error

LoadPngFromBuffer(byte[])

Loads an image from the binary contents of a PNG file.

public Error LoadPngFromBuffer(byte[] buffer)

Parameters

buffer byte[]

Returns

Error

LoadSvgFromBuffer(byte[], float)

Loads an image from the UTF-8 binary contents of an uncompressed SVG file (.svg).

Note: Beware when using compressed SVG files (like .svgz), they need to be decompressed before loading.

Note: This method is only available in engine builds with the SVG module enabled. By default, the SVG module is enabled, but it can be disabled at build-time using the module_svg_enabled=no SCons option.

public Error LoadSvgFromBuffer(byte[] buffer, float scale = 1)

Parameters

buffer byte[]
scale float

Returns

Error

LoadSvgFromString(string, float)

Loads an image from the string contents of a SVG file (.svg).

Note: This method is only available in engine builds with the SVG module enabled. By default, the SVG module is enabled, but it can be disabled at build-time using the module_svg_enabled=no SCons option.

public Error LoadSvgFromString(string svgStr, float scale = 1)

Parameters

svgStr string
scale float

Returns

Error

LoadTgaFromBuffer(byte[])

Loads an image from the binary contents of a TGA file.

Note: This method is only available in engine builds with the TGA module enabled. By default, the TGA module is enabled, but it can be disabled at build-time using the module_tga_enabled=no SCons option.

public Error LoadTgaFromBuffer(byte[] buffer)

Parameters

buffer byte[]

Returns

Error

LoadWebpFromBuffer(byte[])

Loads an image from the binary contents of a WebP file.

public Error LoadWebpFromBuffer(byte[] buffer)

Parameters

buffer byte[]

Returns

Error

NormalMapToXy()

Converts the image's data to represent coordinates on a 3D plane. This is used when the image represents a normal map. A normal map can add lots of detail to a 3D surface without increasing the polygon count.

public void NormalMapToXy()

PremultiplyAlpha()

Multiplies color values with alpha values. Resulting color values for a pixel are (color * alpha)/256. See also BlendMode.

public void PremultiplyAlpha()

Resize(int, int, Interpolation)

Resizes the image to the given width and height. New pixels are calculated using the interpolation mode defined via Image.Interpolation constants.

public void Resize(int width, int height, Image.Interpolation interpolation = Interpolation.Bilinear)

Parameters

width int
height int
interpolation Image.Interpolation

ResizeToPo2(bool, Interpolation)

Resizes the image to the nearest power of 2 for the width and height. If square is true then set width and height to be the same. New pixels are calculated using the interpolation mode defined via Image.Interpolation constants.

public void ResizeToPo2(bool square = false, Image.Interpolation interpolation = Interpolation.Bilinear)

Parameters

square bool
interpolation Image.Interpolation

RgbeToSrgb()

Converts a standard RGBE (Red Green Blue Exponent) image to an sRGB image.

public Image RgbeToSrgb()

Returns

Image

Rotate180()

Rotates the image by 180 degrees. The width and height of the image must be greater than 1.

public void Rotate180()

Rotate90(ClockDirection)

Rotates the image in the specified direction by 90 degrees. The width and height of the image must be greater than 1. If the width and height are not equal, the image will be resized.

public void Rotate90(ClockDirection direction)

Parameters

direction ClockDirection

SaveExr(string, bool)

Saves the image as an EXR file to path. If grayscale is true and the image has only one channel, it will be saved explicitly as monochrome rather than one red channel. This function will return Unavailable if Godot was compiled without the TinyEXR module.

Note: The TinyEXR module is disabled in non-editor builds, which means SaveExr(string, bool) will return Unavailable when it is called from an exported project.

public Error SaveExr(string path, bool grayscale = false)

Parameters

path string
grayscale bool

Returns

Error

SaveExrToBuffer(bool)

Saves the image as an EXR file to a byte array. If grayscale is true and the image has only one channel, it will be saved explicitly as monochrome rather than one red channel. This function will return an empty byte array if Godot was compiled without the TinyEXR module.

Note: The TinyEXR module is disabled in non-editor builds, which means SaveExr(string, bool) will return an empty byte array when it is called from an exported project.

public byte[] SaveExrToBuffer(bool grayscale = false)

Parameters

grayscale bool

Returns

byte[]

SaveJpg(string, float)

Saves the image as a JPEG file to path with the specified quality between 0.01 and 1.0 (inclusive). Higher quality values result in better-looking output at the cost of larger file sizes. Recommended quality values are between 0.75 and 0.90. Even at quality 1.00, JPEG compression remains lossy.

Note: JPEG does not save an alpha channel. If the Image contains an alpha channel, the image will still be saved, but the resulting JPEG file won't contain the alpha channel.

public Error SaveJpg(string path, float quality = 0.75)

Parameters

path string
quality float

Returns

Error

SaveJpgToBuffer(float)

Saves the image as a JPEG file to a byte array with the specified quality between 0.01 and 1.0 (inclusive). Higher quality values result in better-looking output at the cost of larger byte array sizes (and therefore memory usage). Recommended quality values are between 0.75 and 0.90. Even at quality 1.00, JPEG compression remains lossy.

Note: JPEG does not save an alpha channel. If the Image contains an alpha channel, the image will still be saved, but the resulting byte array won't contain the alpha channel.

public byte[] SaveJpgToBuffer(float quality = 0.75)

Parameters

quality float

Returns

byte[]

SavePng(string)

Saves the image as a PNG file to the file at path.

public Error SavePng(string path)

Parameters

path string

Returns

Error

SavePngToBuffer()

Saves the image as a PNG file to a byte array.

public byte[] SavePngToBuffer()

Returns

byte[]

SaveWebp(string, bool, float)

Saves the image as a WebP (Web Picture) file to the file at path. By default it will save lossless. If lossy is true, the image will be saved lossy, using the quality setting between 0.0 and 1.0 (inclusive). Lossless WebP offers more efficient compression than PNG.

Note: The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images.

public Error SaveWebp(string path, bool lossy = false, float quality = 0.75)

Parameters

path string
lossy bool
quality float

Returns

Error

SaveWebpToBuffer(bool, float)

Saves the image as a WebP (Web Picture) file to a byte array. By default it will save lossless. If lossy is true, the image will be saved lossy, using the quality setting between 0.0 and 1.0 (inclusive). Lossless WebP offers more efficient compression than PNG.

Note: The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images.

public byte[] SaveWebpToBuffer(bool lossy = false, float quality = 0.75)

Parameters

lossy bool
quality float

Returns

byte[]

SetData(int, int, bool, Format, byte[])

Overwrites data of an existing Image. Non-static equivalent of CreateFromData(int, int, bool, Format, byte[]).

public void SetData(int width, int height, bool useMipmaps, Image.Format format, byte[] data)

Parameters

width int
height int
useMipmaps bool
format Image.Format
data byte[]

SetPixel(int, int, Color)

Sets the Color of the pixel at (x, y) to color.

Example: 

int imgWidth = 10;
  int imgHeight = 5;
  var img = Image.Create(imgWidth, imgHeight, false, Image.Format.Rgba8);

img.SetPixel(1, 2, Colors.Red); // Sets the color at (1, 2) to red.

This is the same as SetPixelv(Vector2I, Color), but with a two integer arguments instead of a Vector2I argument.

public void SetPixel(int x, int y, Color color)

Parameters

x int
y int
color Color

SetPixelv(Vector2I, Color)

Sets the Color of the pixel at point to color.

Example: 

int imgWidth = 10;
  int imgHeight = 5;
  var img = Image.Create(imgWidth, imgHeight, false, Image.Format.Rgba8);

img.SetPixelv(new Vector2I(1, 2), Colors.Red); // Sets the color at (1, 2) to red.

This is the same as SetPixel(int, int, Color), but with a Vector2I argument instead of two integer arguments.

public void SetPixelv(Vector2I point, Color color)

Parameters

point Vector2I
color Color

ShrinkX2()

Shrinks the image by a factor of 2 on each axis (this divides the pixel count by 4).

public void ShrinkX2()

SrgbToLinear()

Converts the raw data from the sRGB colorspace to a linear scale.

public void SrgbToLinear()
Edit this page