Struct gdnative::prelude::Image

pub struct Image { /* fields omitted */ }

core class Image inherits Resource (reference counted).

Official documentation

See the documentation of this class in the Godot engine's official documentation.

Memory management

The lifetime of this object is automatically managed through reference counting.

Class hierarchy

Image inherits methods from:

• Resource
• Reference
• Object

Safety

All types in the Godot API have "interior mutability" in Rust parlance. To enforce that the official thread-safety guidelines are followed, the typestate pattern is used in the Ref and TRef smart pointers, and the Instance API. The typestate Access in these types tracks whether the access is unique, shared, or exclusive to the current thread. For more information, see the type-level documentation on Ref.

Implementations

impl Image

Constants

pub const ALPHA_BIT: i64

pub const ALPHA_BLEND: i64

pub const ALPHA_NONE: i64

pub const COMPRESS_ETC: i64

pub const COMPRESS_ETC2: i64

pub const COMPRESS_PVRTC2: i64

pub const COMPRESS_PVRTC4: i64

pub const COMPRESS_S3TC: i64

pub const COMPRESS_SOURCE_GENERIC: i64

pub const COMPRESS_SOURCE_NORMAL: i64

pub const COMPRESS_SOURCE_SRGB: i64

pub const FORMAT_BPTC_RGBA: i64

pub const FORMAT_BPTC_RGBF: i64

pub const FORMAT_BPTC_RGBFU: i64

pub const FORMAT_DXT1: i64

pub const FORMAT_DXT3: i64

pub const FORMAT_DXT5: i64

pub const FORMAT_ETC: i64

pub const FORMAT_ETC2_R11: i64

pub const FORMAT_ETC2_R11S: i64

pub const FORMAT_ETC2_RG11: i64

pub const FORMAT_ETC2_RG11S: i64

pub const FORMAT_ETC2_RGB8: i64

pub const FORMAT_ETC2_RGB8A1: i64

pub const FORMAT_ETC2_RGBA8: i64

pub const FORMAT_L8: i64

pub const FORMAT_LA8: i64

pub const FORMAT_MAX: i64

pub const FORMAT_PVRTC2: i64

pub const FORMAT_PVRTC2A: i64

pub const FORMAT_PVRTC4: i64

pub const FORMAT_PVRTC4A: i64

pub const FORMAT_R8: i64

pub const FORMAT_RF: i64

pub const FORMAT_RG8: i64

pub const FORMAT_RGB8: i64

pub const FORMAT_RGBA4444: i64

pub const FORMAT_RGBA5551: i64

pub const FORMAT_RGBA8: i64

pub const FORMAT_RGBAF: i64

pub const FORMAT_RGBAH: i64

pub const FORMAT_RGBE9995: i64

pub const FORMAT_RGBF: i64

pub const FORMAT_RGBH: i64

pub const FORMAT_RGF: i64

pub const FORMAT_RGH: i64

pub const FORMAT_RGTC_R: i64

pub const FORMAT_RGTC_RG: i64

pub const FORMAT_RH: i64

pub const INTERPOLATE_BILINEAR: i64

pub const INTERPOLATE_CUBIC: i64

pub const INTERPOLATE_LANCZOS: i64

pub const INTERPOLATE_NEAREST: i64

pub const INTERPOLATE_TRILINEAR: i64

pub const MAX_HEIGHT: i64

pub const MAX_WIDTH: i64

impl Image

pub fn new() -> Ref<Image, Unique>

Creates a new instance of this object.

This is a reference-counted type. The returned object is automatically managed by Ref.

pub fn blend_rect(
    &self,
    src: impl AsArg<Image>,
    src_rect: Rect<f32, UnknownUnit>,
    dst: Vector2D<f32, UnknownUnit>
)

Alpha-blends [code]src_rect[/code] from [code]src[/code] image to this image at coordinates [code]dest[/code].

pub fn blend_rect_mask(
    &self,
    src: impl AsArg<Image>,
    mask: impl AsArg<Image>,
    src_rect: Rect<f32, UnknownUnit>,
    dst: Vector2D<f32, UnknownUnit>
)

Alpha-blends [code]src_rect[/code] from [code]src[/code] image to this image using [code]mask[/code] image at coordinates [code]dst[/code]. Alpha channels are required for both [code]src[/code] and [code]mask[/code]. [code]dst[/code] pixels and [code]src[/code] pixels will blend if the corresponding mask pixel's alpha value is not 0. [code]src[/code] image and [code]mask[/code] image [b]must[/b] have the same size (width and height) but they can have different formats.

pub fn blit_rect(
    &self,
    src: impl AsArg<Image>,
    src_rect: Rect<f32, UnknownUnit>,
    dst: Vector2D<f32, UnknownUnit>
)

Copies [code]src_rect[/code] from [code]src[/code] image to this image at coordinates [code]dst[/code].

pub fn blit_rect_mask(
    &self,
    src: impl AsArg<Image>,
    mask: impl AsArg<Image>,
    src_rect: Rect<f32, UnknownUnit>,
    dst: Vector2D<f32, UnknownUnit>
)

Blits [code]src_rect[/code] area from [code]src[/code] image to this image at the coordinates given by [code]dst[/code]. [code]src[/code] pixel is copied onto [code]dst[/code] if the corresponding [code]mask[/code] pixel's alpha value is not 0. [code]src[/code] image and [code]mask[/code] image [b]must[/b] have the same size (width and height) but they can have different formats.

pub fn bumpmap_to_normalmap(&self, bump_scale: f64)

Converts a bumpmap to a normalmap. A bumpmap provides a height offset per-pixel, while a normalmap provides a normal direction per pixel.

Default Arguments

• bump_scale - 1.0

pub fn clear_mipmaps(&self)

Removes the image's mipmaps.

pub fn compress(
    &self,
    mode: i64,
    source: i64,
    lossy_quality: f64
) -> Result<(), GodotError>

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 [enum CompressMode] and [enum CompressSource] constants.

pub fn convert(&self, format: i64)

Converts the image's format. See [enum Format] constants.

pub fn copy_from(&self, src: impl AsArg<Image>)

Copies [code]src[/code] image to this image.

pub fn create(&self, width: i64, height: i64, use_mipmaps: bool, format: i64)

Creates an empty image of given size and format. See [enum Format] constants. If [code]use_mipmaps[/code] is [code]true[/code] then generate mipmaps for this image. See the [method generate_mipmaps].

pub fn create_from_data(
    &self,
    width: i64,
    height: i64,
    use_mipmaps: bool,
    format: i64,
    data: TypedArray<u8>
)

Creates a new image of given size and format. See [enum Format] constants. Fills the image with the given raw data. If [code]use_mipmaps[/code] is [code]true[/code] then loads mipmaps for this image from [code]data[/code]. See [method generate_mipmaps].

pub fn crop(&self, width: i64, height: i64)

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

pub fn decompress(&self) -> Result<(), GodotError>

Decompresses the image if it is compressed. Returns an error if decompress function is not available.

pub fn detect_alpha(&self) -> AlphaMode

Returns [constant ALPHA_BLEND] if the image has data for alpha values. Returns [constant ALPHA_BIT] if all the alpha values are stored in a single bit. Returns [constant ALPHA_NONE] if no data for alpha values is found.

pub fn expand_x2_hq2x(&self)

Stretches the image and enlarges it by a factor of 2. No interpolation is done.

pub fn fill(&self, color: Color)

Fills the image with a given [Color].

pub fn fix_alpha_edges(&self)

Blends low-alpha pixels with nearby pixels.

pub fn flip_x(&self)

Flips the image horizontally.

pub fn flip_y(&self)

Flips the image vertically.

pub fn generate_mipmaps(&self, renormalize: bool) -> Result<(), GodotError>

Generates mipmaps for the image. Mipmaps are pre-calculated and lower resolution copies of the image. Mipmaps are automatically used if the image needs to be scaled down when rendered. This improves image quality and the performance of the rendering. Returns an error if the image is compressed, in a custom format or if the image's width/height is 0.

Default Arguments

• renormalize - false

pub fn get_data(&self) -> TypedArray<u8>

Returns a copy of the image's raw data.

pub fn get_format(&self) -> Format

Returns the image's format. See [enum Format] constants.

pub fn get_height(&self) -> i64

Returns the image's height.

pub fn get_mipmap_offset(&self, mipmap: i64) -> i64

Returns the offset where the image's mipmap with index [code]mipmap[/code] is stored in the [code]data[/code] dictionary.

pub fn get_pixel(&self, x: i64, y: i64) -> Color

Returns the color of the pixel at [code](x, y)[/code] if the image is locked. If the image is unlocked, it always returns a [Color] with the value [code](0, 0, 0, 1.0)[/code]. This is the same as [method get_pixelv], but two integer arguments instead of a Vector2 argument.

pub fn get_pixelv(&self, src: Vector2D<f32, UnknownUnit>) -> Color

Returns the color of the pixel at [code]src[/code] if the image is locked. If the image is unlocked, it always returns a [Color] with the value [code](0, 0, 0, 1.0)[/code]. This is the same as [method get_pixel], but with a Vector2 argument instead of two integer arguments.

pub fn get_rect(
    &self,
    rect: Rect<f32, UnknownUnit>
) -> Option<Ref<Image, Shared>>

Returns a new image that is a copy of the image's area specified with [code]rect[/code].

pub fn get_size(&self) -> Vector2D<f32, UnknownUnit>

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

pub fn get_used_rect(&self) -> Rect<f32, UnknownUnit>

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

pub fn get_width(&self) -> i64

Returns the image's width.

pub fn has_mipmaps(&self) -> bool

Returns [code]true[/code] if the image has generated mipmaps.

pub fn is_compressed(&self) -> bool

Returns [code]true[/code] if the image is compressed.

pub fn is_empty(&self) -> bool

Returns [code]true[/code] if the image has no data.

pub fn is_invisible(&self) -> bool

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

pub fn load(&self, path: impl Into<GodotString>) -> Result<(), GodotError>

Loads an image from file [code]path[/code]. See [url=https://docs.godotengine.org/en/latest/getting_started/workflow/assets/importing_images.html#supported-image-formats]Supported image formats[/url] for a list of supported image formats and limitations.

pub fn load_jpg_from_buffer(
    &self,
    buffer: TypedArray<u8>
) -> Result<(), GodotError>

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

pub fn load_png_from_buffer(
    &self,
    buffer: TypedArray<u8>
) -> Result<(), GodotError>

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

pub fn load_tga_from_buffer(
    &self,
    buffer: TypedArray<u8>
) -> Result<(), GodotError>

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

pub fn load_webp_from_buffer(
    &self,
    buffer: TypedArray<u8>
) -> Result<(), GodotError>

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

pub fn lock(&self)

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.

pub fn normalmap_to_xy(&self)

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.

pub fn premultiply_alpha(&self)

Multiplies color values with alpha values. Resulting color values for a pixel are [code](color * alpha)/256[/code].

pub fn resize(&self, width: i64, height: i64, interpolation: i64)

Resizes the image to the given [code]width[/code] and [code]height[/code]. New pixels are calculated using [code]interpolation[/code]. See [code]interpolation[/code] constants.

Default Arguments

• interpolation - 1

pub fn resize_to_po2(&self, square: bool)

Resizes the image to the nearest power of 2 for the width and height. If [code]square[/code] is [code]true[/code] then set width and height to be the same.

Default Arguments

• square - false

pub fn rgbe_to_srgb(&self) -> Option<Ref<Image, Shared>>

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

pub fn save_exr(
    &self,
    path: impl Into<GodotString>,
    grayscale: bool
) -> Result<(), GodotError>

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

Default Arguments

• grayscale - false

pub fn save_png(&self, path: impl Into<GodotString>) -> Result<(), GodotError>

Saves the image as a PNG file to [code]path[/code].

pub fn save_png_to_buffer(&self) -> TypedArray<u8>

pub fn set_pixel(&self, x: i64, y: i64, color: Color)

Sets the [Color] of the pixel at [code](x, y)[/code] if the image is locked. Example:
				[codeblock]
				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
				[/codeblock]

pub fn set_pixelv(&self, dst: Vector2D<f32, UnknownUnit>, color: Color)

Sets the [Color] of the pixel at [code](dst.x, dst.y)[/code] if the image is locked. Note that the [code]dst[/code] values must be integers. Example:
				[codeblock]
				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
				[/codeblock]

pub fn shrink_x2(&self)

Shrinks the image by a factor of 2.

pub fn srgb_to_linear(&self)

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

pub fn unlock(&self)

Unlocks the data and prevents changes.

Methods from Deref<Target = Resource>

pub fn duplicate(&self, subresources: bool) -> Option<Ref<Resource, Shared>>

Duplicates the resource, returning a new resource. By default, sub-resources are shared between resource copies for efficiency. This can be changed by passing [code]true[/code] to the [code]subresources[/code] argument which will copy the subresources.
				[b]Note:[/b] If [code]subresources[/code] is [code]true[/code], this method will only perform a shallow copy. Nested resources within subresources will not be duplicated and will still be shared.

Default Arguments

• subresources - false

pub fn get_local_scene(&self) -> Option<Ref<Node, Shared>>

If [member resource_local_to_scene] is enabled and the resource was loaded from a [PackedScene] instantiation, returns the local scene where this resource's unique copy is in use. Otherwise, returns [code]null[/code].

pub fn name(&self) -> GodotString

The name of the resource. This is an optional identifier.

pub fn path(&self) -> GodotString

The path to the resource. In case it has its own file, it will return its filepath. If it's tied to the scene, it will return the scene's path, followed by the resource's index.

pub fn get_rid(&self) -> Rid

Returns the RID of the resource (or an empty RID). Many resources (such as [Texture], [Mesh], etc) are high-level abstractions of resources stored in a server, so this function will return the original RID.

pub fn is_local_to_scene(&self) -> bool

If [code]true[/code], the resource will be made unique in each instance of its local scene. It can thus be modified in a scene instance without impacting other instances of that same scene.

pub fn set_local_to_scene(&self, enable: bool)

If [code]true[/code], the resource will be made unique in each instance of its local scene. It can thus be modified in a scene instance without impacting other instances of that same scene.

pub fn set_name(&self, name: impl Into<GodotString>)

The name of the resource. This is an optional identifier.

pub fn set_path(&self, path: impl Into<GodotString>)

The path to the resource. In case it has its own file, it will return its filepath. If it's tied to the scene, it will return the scene's path, followed by the resource's index.

pub fn setup_local_to_scene(&self)

This method is called when a resource with [member resource_local_to_scene] enabled is loaded from a [PackedScene] instantiation. Its behavior can be customized by overriding [method _setup_local_to_scene] from script.
				For most resources, this method performs no base logic. [ViewportTexture] performs custom logic to properly set the proxy texture and flags in the local viewport.

pub fn take_over_path(&self, path: impl Into<GodotString>)

Sets the path of the resource, potentially overriding an existing cache entry for this path. This differs from setting [member resource_path], as the latter would error out if another resource was already cached for the given path.

Trait Implementations

impl Debug for Image

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deref for Image

type Target = Resource

The resulting type after dereferencing.

fn deref(&self) -> &Resource

Dereferences the value.

impl DerefMut for Image

fn deref_mut(&mut self) -> &mut Resource

Mutably dereferences the value.

impl GodotObject for Image

type RefKind = RefCounted

The memory management kind of this type. This modifies the behavior of the Ref smart pointer. See its type-level documentation for more information.

fn class_name() -> &'static str

fn null() -> Null<Self>

Creates an explicitly null reference of Self as a method argument. This makes type inference easier for the compiler compared to Option.

fn new() -> Ref<Self, Unique> where
    Self: Instanciable, 

Creates a new instance of Self using a zero-argument constructor, as a Unique reference.

fn cast<T>(&self) -> Option<&T> where
    T: GodotObject + SubClass<Self>, 

Performs a dynamic reference downcast to target type.

fn upcast<T>(&self) -> &T where
    Self: SubClass<T>,
    T: GodotObject, 

Performs a static reference upcast to a supertype that is guaranteed to be valid.

unsafe fn assume_shared(&self) -> Ref<Self, Shared>

Creates a persistent reference to the same Godot object with shared thread access.

unsafe fn assume_thread_local(&self) -> Ref<Self, ThreadLocal> where
    Self: GodotObject<RefKind = RefCounted>, 

Creates a persistent reference to the same Godot object with thread-local thread access.

unsafe fn assume_unique(&self) -> Ref<Self, Unique>

Creates a persistent reference to the same Godot object with unique access.

impl Instanciable for Image

fn construct() -> Ref<Image, Unique>

impl SubClass<Object> for Image

impl SubClass<Reference> for Image

impl SubClass<Resource> for Image