Native image datatype. Contains image data which can be converted to an godot.ImageTexture
and provides commonly used image processing methods. The maximum width and height for an godot.Image
are godot.Image.maxWidth
and godot.Image.maxHeight
.
An godot.Image
cannot be assigned to a texture
property of an object directly (such as godot.Sprite
), and has to be converted manually to an godot.ImageTexture
first.
Note: The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images may fail to import.
Static variables
Constructor
Variables
data:Dictionary
Holds all the image's color data in a given format. See godot.Image_Format
constants.
Methods
blendRect(src:Image, srcRect:Rect2, dst:Vector2):Void
Alpha-blends src_rect
from src
image to this image at coordinates dest
.
blendRectMask(src:Image, mask:Image, srcRect:Rect2, dst:Vector2):Void
Alpha-blends src_rect
from src
image to this image using mask
image at coordinates dst
. 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. src
image and mask
image must have the same size (width and height) but they can have different formats.
blitRect(src:Image, srcRect:Rect2, dst:Vector2):Void
Copies src_rect
from src
image to this image at coordinates dst
.
blitRectMask(src:Image, mask:Image, srcRect:Rect2, dst:Vector2):Void
Blits src_rect
area from src
image to this image at the coordinates given by dst
. src
pixel is copied onto dst
if the corresponding mask
pixel's alpha value is not 0. src
image and mask
image must have the same size (width and height) but they can have different formats.
bumpmapToNormalmap(?bumpScale:Single):Void
Converts a bumpmap to a normalmap. A bumpmap provides a height offset per-pixel, while a normalmap provides a normal direction per pixel.
compress(mode:Image_CompressMode, source:Image_CompressSource, lossyQuality:Single):Error
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. See godot.Image_CompressMode
and godot.Image_CompressSource
constants.
create(width:Int, height:Int, useMipmaps:Bool, format:Image_Format):Void
Creates an empty image of given size and format. See godot.Image_Format
constants. If use_mipmaps
is true
then generate mipmaps for this image. See the godot.Image.generateMipmaps
.
createFromData(width:Int, height:Int, useMipmaps:Bool, format:Image_Format, data:HaxeArray<UInt8>):Void
Creates a new image of given size and format. See godot.Image_Format
constants. Fills the image with the given raw data. If use_mipmaps
is true
then loads mipmaps for this image from data
. See godot.Image.generateMipmaps
.
crop(width:Int, height:Int):Void
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.
decompress():Error
Decompresses the image if it is compressed. Returns an error if decompress function is not available.
detectAlpha():Image_AlphaMode
Returns godot.Image_AlphaMode.blend
if the image has data for alpha values. Returns godot.Image_AlphaMode.bit
if all the alpha values are stored in a single bit. Returns godot.Image_AlphaMode.none
if no data for alpha values is found.
generateMipmaps(?renormalize:Bool):Error
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
.
Note: Mipmap generation is done on the CPU, is single-threaded and is always done on the main thread. This means generating mipmaps will result in noticeable stuttering during gameplay, even if godot.Image.generateMipmaps
is called from a godot.Thread
.
getMipmapOffset(mipmap:Int):Int
Returns the offset where the image's mipmap with index mipmap
is stored in the data
dictionary.
getPixel(x:Int, y:Int):Color
Returns the color of the pixel at (x, y)
if the image is locked. If the image is unlocked, it always returns a godot.Color
with the value (0, 0, 0, 1.0)
. This is the same as godot.Image.getPixelv
, but two integer arguments instead of a Vector2 argument.
getPixelv(src:Vector2):Color
Returns the color of the pixel at src
if the image is locked. If the image is unlocked, it always returns a godot.Color
with the value (0, 0, 0, 1.0)
. This is the same as godot.Image.getPixel
, but with a Vector2 argument instead of two integer arguments.
getRect(rect:Rect2):Image
Returns a new image that is a copy of the image's area specified with rect
.
getUsedRect():Rect2
Returns a godot.Rect2
enclosing the visible portion of the image, considering each pixel with a non-zero alpha channel as visible.
isInvisible():Bool
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.
load(path:String):Error
Loads an image from file path
. See [https://docs.godotengine.org/en/3.4/tutorials/assets_pipeline/importing_images.html#supported-image-formats](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 godot.ImageTexture
description for usage examples.
loadBmpFromBuffer(buffer:HaxeArray<UInt8>):Error
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.
loadJpgFromBuffer(buffer:HaxeArray<UInt8>):Error
Loads an image from the binary contents of a JPEG file.
loadPngFromBuffer(buffer:HaxeArray<UInt8>):Error
Loads an image from the binary contents of a PNG file.
loadTgaFromBuffer(buffer:HaxeArray<UInt8>):Error
Loads an image from the binary contents of a TGA file.
loadWebpFromBuffer(buffer:HaxeArray<UInt8>):Error
Loads an image from the binary contents of a WebP file.
lock():Void
Locks the data for reading and writing access. Sends an error to the console if the image is not locked when reading or writing a pixel.
normalmapToXy():Void
Converts the image's data to represent coordinates on a 3D plane. This is used when the image represents a normalmap. A normalmap can add lots of detail to a 3D surface without increasing the polygon count.
premultiplyAlpha():Void
Multiplies color values with alpha values. Resulting color values for a pixel are (color * alpha)/256
.
resize(width:Int, height:Int, ?interpolation:Image_Interpolation):Void
Resizes the image to the given width
and height
. New pixels are calculated using the interpolation
mode defined via godot.Image_Interpolation
constants.
resizeToPo2(?square:Bool, ?interpolation:Image_Interpolation):Void
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 godot.Image_Interpolation
constants.
saveExr(path:String, ?grayscale:Bool):Error
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 ERR_UNAVAILABLE
if Godot was compiled without the TinyEXR module.
Note: The TinyEXR module is disabled in non-editor builds, which means godot.Image.saveExr
will return ERR_UNAVAILABLE
when it is called from an exported project.
setPixel(x:Int, y:Int, color:Color):Void
Sets the godot.Color
of the pixel at (x, y)
if the image is locked. Example:
var img = Image.new()
img.create(img_width, img_height, false, Image.FORMAT_RGBA8)
img.lock()
img.set_pixel(x, y, color) # Works
img.unlock()
img.set_pixel(x, y, color) # Does not have an effect
setPixelv(dst:Vector2, color:Color):Void
Sets the godot.Color
of the pixel at (dst.x, dst.y)
if the image is locked. Note that the dst
values must be integers. Example:
var img = Image.new()
img.create(img_width, img_height, false, Image.FORMAT_RGBA8)
img.lock()
img.set_pixelv(Vector2(x, y), color) # Works
img.unlock()
img.set_pixelv(Vector2(x, y), color) # Does not have an effect