Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Image

繼承： Resource < RefCounted < Object

圖像資料型別。

說明

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 MAX_WIDTH and MAX_HEIGHT.

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

Note: Methods that modify the image data cannot be used on VRAM-compressed images. Use decompress() to convert the image to an uncompressed format first.

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

教學

屬性

Dictionary

data

{ "data": PackedByteArray(), "format": "Lum8", "height": 0, "mipmaps": false, "width": 0 }

方法

void	adjust_bcs(brightness: float, contrast: float, saturation: float)
void	blend_rect(src: Image, src_rect: Rect2i, dst: Vector2i)
void	blend_rect_mask(src: Image, mask: Image, src_rect: Rect2i, dst: Vector2i)
void	blit_rect(src: Image, src_rect: Rect2i, dst: Vector2i)
void	blit_rect_mask(src: Image, mask: Image, src_rect: Rect2i, dst: Vector2i)
void	bump_map_to_normal_map(bump_scale: float = 1.0)
void	clear_mipmaps()
Error	compress(mode: CompressMode, source: CompressSource = 0, astc_format: ASTCFormat = 0)
Error	compress_from_channels(mode: CompressMode, channels: UsedChannels, astc_format: ASTCFormat = 0)
Dictionary	compute_image_metrics(compared_image: Image, use_luma: bool)
void	convert(format: Format)
void	copy_from(src: Image)
Image	create(width: int, height: int, use_mipmaps: bool, format: Format) static
Image	create_empty(width: int, height: int, use_mipmaps: bool, format: Format) static
Image	create_from_data(width: int, height: int, use_mipmaps: bool, format: Format, data: PackedByteArray) static
void	crop(width: int, height: int)
Error	decompress()
AlphaMode	detect_alpha() const
UsedChannels	detect_used_channels(source: CompressSource = 0) const
void	fill(color: Color)
void	fill_rect(rect: Rect2i, color: Color)
void	fix_alpha_edges()
void	flip_x()
void	flip_y()
Error	generate_mipmaps(renormalize: bool = false)
PackedByteArray	get_data() const
int	get_data_size() const
Format	get_format() const
int	get_height() const
int	get_mipmap_count() const
int	get_mipmap_offset(mipmap: int) const
Color	get_pixel(x: int, y: int) const
Color	get_pixelv(point: Vector2i) const
Image	get_region(region: Rect2i) const
Vector2i	get_size() const
Rect2i	get_used_rect() const
int	get_width() const
bool	has_mipmaps() const
bool	is_compressed() const
bool	is_empty() const
bool	is_invisible() const
void	linear_to_srgb()
Error	load(path: String)
Error	load_bmp_from_buffer(buffer: PackedByteArray)
Error	load_dds_from_buffer(buffer: PackedByteArray)
Error	load_exr_from_buffer(buffer: PackedByteArray)
Image	load_from_file(path: String) static
Error	load_jpg_from_buffer(buffer: PackedByteArray)
Error	load_ktx_from_buffer(buffer: PackedByteArray)
Error	load_png_from_buffer(buffer: PackedByteArray)
Error	load_svg_from_buffer(buffer: PackedByteArray, scale: float = 1.0)
Error	load_svg_from_string(svg_str: String, scale: float = 1.0)
Error	load_tga_from_buffer(buffer: PackedByteArray)
Error	load_webp_from_buffer(buffer: PackedByteArray)
void	normal_map_to_xy()
void	premultiply_alpha()
void	resize(width: int, height: int, interpolation: Interpolation = 1)
void	resize_to_po2(square: bool = false, interpolation: Interpolation = 1)
Image	rgbe_to_srgb()
void	rotate_90(direction: ClockDirection)
void	rotate_180()
Error	save_dds(path: String) const
PackedByteArray	save_dds_to_buffer() const
Error	save_exr(path: String, grayscale: bool = false, color_image: bool = false, max_linear_value: float = -1.0) const
PackedByteArray	save_exr_to_buffer(grayscale: bool = false, color_image: bool = false, max_linear_value: float = -1.0) const
Error	save_jpg(path: String, quality: float = 0.75) const
PackedByteArray	save_jpg_to_buffer(quality: float = 0.75) const
Error	save_png(path: String) const
PackedByteArray	save_png_to_buffer() const
Error	save_webp(path: String, lossy: bool = false, quality: float = 0.75) const
PackedByteArray	save_webp_to_buffer(lossy: bool = false, quality: float = 0.75) const
void	set_data(width: int, height: int, use_mipmaps: bool, format: Format, data: PackedByteArray)
void	set_pixel(x: int, y: int, color: Color)
void	set_pixelv(point: Vector2i, color: Color)
void	shrink_x2()
void	srgb_to_linear()

列舉

enum Format: 🔗

Format FORMAT_L8 = 0

紋理格式，具有代表亮度的單一 8 位深度。

Format FORMAT_LA8 = 1

OpenGL 紋理格式，具有兩個值，亮度和 Alpha，都以 8 位元儲存。

Format FORMAT_R8 = 2

OpenGL 紋理格式 RED，具有單個分量和 8 位深度。

Format FORMAT_RG8 = 3

OpenGL 紋理格式 RG，具有兩個部分，每個部分的位元深度為 8。

Format FORMAT_RGB8 = 4

OpenGL texture format RGB with three components, each with a bitdepth of 8.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_RGBA8 = 5

OpenGL texture format RGBA with four components, each with a bitdepth of 8.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_RGBA4444 = 6

OpenGL 紋理格式 RGBA 有四個部分，每個分量部分的位元深度為 4。

Format FORMAT_RGB565 = 7

OpenGL texture format RGB with three components. Red and blue have a bitdepth of 5, and green has a bitdepth of 6.

Format FORMAT_RF = 8

OpenGL 紋理格式 GL_R32F，其中有一個分量，是32 位浮點值。

Format FORMAT_RGF = 9

OpenGL 紋理格式 GL_RG32F 這裡有兩個部分，每個部分是一個 32 位浮點值。

Format FORMAT_RGBF = 10

OpenGL 紋理格式 GL_RGB32F，其中有三個部分，每個部分都是 32 位元浮點值。

Format FORMAT_RGBAF = 11

OpenGL 紋理格式 GL_RGBA32F，其中有四個部分，每個部分都是 32 位元浮點值。

Format FORMAT_RH = 12

OpenGL 紋理格式 GL_R32F，其中有一個分量，即 16 位“半精度”浮點值。

Format FORMAT_RGH = 13

OpenGL 紋理格式 GL_RG32F，其中有兩個部分，每個部分都是 16 位元“半精度”浮點值。

Format FORMAT_RGBH = 14

OpenGL 紋理格式 GL_RGB32F，其中有三個部分，每個部分都是 16 位元“半精度”浮點值。

Format FORMAT_RGBAH = 15

OpenGL 紋理格式 GL_RGBA32F，其中有四個部分，每個都是 16 位“半精度”浮點值。

Format FORMAT_RGBE9995 = 16

一種特殊的 OpenGL 紋理格式，其中三個顏色成分的精度為 9 位，所有三個成分共用一個 5 比特位的指數。

Format FORMAT_DXT1 = 17

The S3TC texture format that uses Block Compression 1, and is the smallest variation of S3TC, only providing 1 bit of alpha and color data being premultiplied with alpha.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_DXT3 = 18

The S3TC texture format that uses Block Compression 2, and color data is interpreted as not having been premultiplied by alpha. Well suited for images with sharp alpha transitions between translucent and opaque areas.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_DXT5 = 19

The S3TC texture format also known as Block Compression 3 or BC3 that contains 64 bits of alpha channel data followed by 64 bits of DXT1-encoded color data. Color data is not premultiplied by alpha, same as DXT3. DXT5 generally produces superior results for transparent gradients compared to DXT3.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_RGTC_R = 20

使用紅綠貼圖壓縮的貼圖格式，使用與 DXT5 用於 Alpha 通道相同的壓縮演算法對紅色通道資料進行正規化。

Format FORMAT_RGTC_RG = 21

使用紅綠貼圖壓縮的貼圖格式，使用與 DXT5 用於 Alpha 的壓縮演算法相同的紅綠資料通道。

Format FORMAT_BPTC_RGBA = 22

Texture format that uses BPTC compression with unsigned normalized RGBA components.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_BPTC_RGBF = 23

使用 BPTC 壓縮和有符號浮點RGB分量的貼圖格式.

Format FORMAT_BPTC_RGBFU = 24

使用BPTC 壓縮和無符號浮點RGB分量的貼圖格式.

Format FORMAT_ETC = 25

愛立信紋理壓縮格式 1，又稱“ETC1”，是 OpenGL ES 圖形標準的一部分。這種格式無法存儲 Alpha 通道。

Format FORMAT_ETC2_R11 = 26

ETC2%E5%92%8CEAC]愛立信紋理壓縮格式 2（R11_EAC 變體），它提供一個無符號資料通道。

Format FORMAT_ETC2_R11S = 27

ETC2%E5%92%8CEAC]愛立信紋理壓縮格式 2（SIGNED_R11_EAC 變體），它提供一個有符號資料通道。

Format FORMAT_ETC2_RG11 = 28

ETC2%E5%92%8CEAC]愛立信紋理壓縮格式 2（RG11_EAC 變體），它提供一個無符號數據通道。

Format FORMAT_ETC2_RG11S = 29

ETC2%E5%92%8CEAC]愛立信紋理壓縮格式 2（SIGNED_RG11_EAC 變體），它提供兩個有符號資料通道。

Format FORMAT_ETC2_RGB8 = 30

Ericsson Texture Compression format 2 (RGB8 variant), which is a follow-up of ETC1 and compresses RGB888 data.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_ETC2_RGBA8 = 31

Ericsson Texture Compression format 2 (RGBA8variant), which compresses RGBA8888 data with full alpha support.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_ETC2_RGB8A1 = 32

Ericsson Texture Compression format 2 (RGB8_PUNCHTHROUGH_ALPHA1 variant), which compresses RGBA data to make alpha either fully transparent or fully opaque.

Note: When creating an ImageTexture, a nonlinear sRGB to linear encoding conversion is performed.

Format FORMAT_ETC2_RA_AS_RG = 33

Ericsson Texture Compression format 2 (RGBA8 variant), which compresses RA data and interprets it as two channels (red and green). See also FORMAT_ETC2_RGBA8.

Format FORMAT_DXT5_RA_AS_RG = 34

The S3TC texture format also known as Block Compression 3 or BC3, which compresses RA data and interprets it as two channels (red and green). See also FORMAT_DXT5.

Format FORMAT_ASTC_4x4 = 35

Adaptive Scalable Texture Compression. This implements the 4×4 (high quality) mode.

Format FORMAT_ASTC_4x4_HDR = 36

與 FORMAT_ASTC_4x4 相同的格式，但有提示以讓 GPU 知道它用於 HDR。

Format FORMAT_ASTC_8x8 = 37

Adaptive Scalable Texture Compression. This implements the 8×8 (low quality) mode.

Format FORMAT_ASTC_8x8_HDR = 38

與 FORMAT_ASTC_8x8 相同的格式，但有提示以讓 GPU 知道它用於 HDR。

Format FORMAT_R16 = 39

OpenGL texture format GL_R16 where there's one component, a 16-bit unsigned normalized integer value. Since the value is normalized, each component is clamped between 0.0 and 1.0 (inclusive).

Note: Due to limited hardware support, it is mainly recommended to be used on desktop or console devices. It may be unsupported on mobile or web, and will consequently be converted to FORMAT_RF.

Format FORMAT_RG16 = 40

OpenGL texture format GL_RG16 where there are two components, each a 16-bit unsigned normalized integer value. Since the value is normalized, each component is clamped between 0.0 and 1.0 (inclusive).

Note: Due to limited hardware support, it is mainly recommended to be used on desktop or console devices. It may be unsupported on mobile or web, and will consequently be converted to FORMAT_RGF.

Format FORMAT_RGB16 = 41

OpenGL texture format GL_RGB16 where there are three components, each a 16-bit unsigned normalized integer value. Since the value is normalized, each component is clamped between 0.0 and 1.0 (inclusive).

Note: Due to limited hardware support, it is mainly recommended to be used on desktop or console devices. It may be unsupported on mobile or web, and will consequently be converted to FORMAT_RGBF.

Format FORMAT_RGBA16 = 42

OpenGL texture format GL_RGBA16 where there are four components, each a 16-bit unsigned normalized integer value. Since the value is normalized, each component is clamped between 0.0 and 1.0 (inclusive).

Note: Due to limited hardware support, it is mainly recommended to be used on desktop or console devices. It may be unsupported on mobile or web, and will consequently be converted to FORMAT_RGBAF.

Format FORMAT_R16I = 43

OpenGL texture format GL_R16UI where there's one component, a 16-bit unsigned integer value. Each component is clamped between 0 and 65535 (inclusive).

Note: When used in a shader, the texture requires usage of usampler samplers. Additionally, it only supports nearest-neighbor filtering under the Compatibility renderer.

Note: When sampling using get_pixel(), returned Colors have to be divided by 65535 to get the correct color value.

Format FORMAT_RG16I = 44

OpenGL texture format GL_RG16UI where there are two components, each a 16-bit unsigned integer value. Each component is clamped between 0 and 65535 (inclusive).

Note: When used in a shader, the texture requires usage of usampler samplers. Additionally, it only supports nearest-neighbor filtering under the Compatibility renderer.

Note: When sampling using get_pixel(), returned Colors have to be divided by 65535 to get the correct color value.

Format FORMAT_RGB16I = 45

OpenGL texture format GL_RGB16UI where there are three components, each a 16-bit unsigned integer value. Each component is clamped between 0 and 65535 (inclusive).

Note: When used in a shader, the texture requires usage of usampler samplers. Additionally, it only supports nearest-neighbor filtering under the Compatibility renderer.

Note: When sampling using get_pixel(), returned Colors have to be divided by 65535 to get the correct color value.

Format FORMAT_RGBA16I = 46

OpenGL texture format GL_RGBA16UI where there are four components, each a 16-bit unsigned integer value. Each component is clamped between 0 and 65535 (inclusive).

Note: When used in a shader, the texture requires usage of usampler samplers. Additionally, it only supports nearest-neighbor filtering under the Compatibility renderer.

Note: When sampling using get_pixel(), returned Colors have to be divided by 65535 to get the correct color value.

Format FORMAT_MAX = 47

代表 Format 列舉的大小。

enum Interpolation: 🔗

Interpolation INTERPOLATE_NEAREST = 0

執行最近鄰插值。如果調整圖像大小，它將被圖元化。

Interpolation INTERPOLATE_BILINEAR = 1

執行雙線性插值。如果調整圖像大小，則圖像將模糊。此模式比 INTERPOLATE_CUBIC 更快，但品質較低。

Interpolation INTERPOLATE_CUBIC = 2

執行三次插值。如果調整圖像大小，則圖像將模糊。與 INTERPOLATE_BILINEAR 相比，此模式通常會產生更好的結果，但代價是速度較慢。

Interpolation INTERPOLATE_TRILINEAR = 3

在兩個最適合的多級漸遠紋理級別上分別執行雙線性取樣，然後在取樣結果之間進行線性插值。

它比 INTERPOLATE_BILINEAR 慢，但能產生更高品質的效果，減少鋸齒偽影。

如果圖像沒有多級漸遠紋理，它們將被生成並在內部使用，但不會在生成的圖像之上生成多級漸遠紋理。

注意：如果你打算縮放原始圖像的多個副本，最好事先對其呼叫 generate_mipmaps()，以避免在生成它們時反復浪費處理能力。

另一方面，如果圖像已經有了多級漸遠紋理，其將被使用，並為生成的圖像生成新的一組。

Interpolation INTERPOLATE_LANCZOS = 4

Performs Lanczos interpolation. This is the slowest image resizing mode, but it typically gives the best results, especially when downscaling images.

enum AlphaMode: 🔗

AlphaMode ALPHA_NONE = 0

Image is fully opaque. It does not store alpha data.

AlphaMode ALPHA_BIT = 1

Image stores either fully opaque or fully transparent pixels. Also known as punchthrough alpha.

AlphaMode ALPHA_BLEND = 2

Image stores alpha data with values varying between 0.0 and 1.0.

enum CompressMode: 🔗

CompressMode COMPRESS_S3TC = 0

使用 S3TC 壓縮。

CompressMode COMPRESS_ETC = 1

使用 ETC 壓縮。

CompressMode COMPRESS_ETC2 = 2

使用 ETC2 壓縮。

CompressMode COMPRESS_BPTC = 3

使用 BPTC 壓縮。

CompressMode COMPRESS_ASTC = 4

使用 ASTC 壓縮。

CompressMode COMPRESS_MAX = 5

代表 CompressMode 列舉的大小。

enum UsedChannels: 🔗

UsedChannels USED_CHANNELS_L = 0

The image only uses one channel for luminance (grayscale).

UsedChannels USED_CHANNELS_LA = 1

The image uses two channels for luminance and alpha, respectively.

UsedChannels USED_CHANNELS_R = 2

The image only uses the red channel.

UsedChannels USED_CHANNELS_RG = 3

The image uses two channels for red and green.

UsedChannels USED_CHANNELS_RGB = 4

The image uses three channels for red, green, and blue.

UsedChannels USED_CHANNELS_RGBA = 5

The image uses four channels for red, green, blue, and alpha.

enum CompressSource: 🔗

CompressSource COMPRESS_SOURCE_GENERIC = 0

原始紋理（在壓縮前）是常規紋理。所有紋理的預設值。

CompressSource COMPRESS_SOURCE_SRGB = 1

Source texture (before compression) uses nonlinear sRGB encoding.

CompressSource COMPRESS_SOURCE_NORMAL = 2

原始紋理（在壓縮前）是法線紋理（例如可以壓縮為兩個通道）。

enum ASTCFormat: 🔗

ASTCFormat ASTC_FORMAT_4x4 = 0

Hint to indicate that the high quality 4×4 ASTC compression format should be used.

ASTCFormat ASTC_FORMAT_8x8 = 1

Hint to indicate that the low quality 8×8 ASTC compression format should be used.

常數

MAX_WIDTH = 16777216 🔗

Image 資源允許的最大寬度。

MAX_HEIGHT = 16777216 🔗

Image 資源允許的最大高度。

屬性說明

Dictionary data = { "data": PackedByteArray(), "format": "Lum8", "height": 0, "mipmaps": false, "width": 0 } 🔗

以給定的格式保存圖像的所有顏色資料。參閱 Format 常數。

方法說明

void adjust_bcs(brightness: float, contrast: float, saturation: float) 🔗

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

void blend_rect(src: Image, src_rect: Rect2i, dst: Vector2i) 🔗

將 src 圖像上的 src_rect 與該圖像的座標 dst 處進行 Alpha 混合，將根據兩個圖像的邊界進行裁剪。該圖像和 src 圖像必須具有相同的格式。具有非正大小的 src_rect 將被視為空。

void blend_rect_mask(src: Image, mask: Image, src_rect: Rect2i, dst: Vector2i) 🔗

使用遮罩圖 mask，將源圖像 src 中的 src_rect 區域的圖像，Alpha 混合到本圖像從座標 dst 起的區域，會根據兩者的圖像區域進行裁剪。src 和 mask 都需要有 Alpha 通道。如果遮罩圖 mask 上某個像素的 Alpha 值非 0，則相應的 dst 的圖元和 src 的圖元將混合。這張圖像和 src 圖像的格式必須一致。src 圖像和 mask 圖像的大小（寬度和高度）必須相同，格式可以不同。src_rect 的大小如果非正，則會作為空矩形處理。

void blit_rect(src: Image, src_rect: Rect2i, dst: Vector2i) 🔗

Copies src_rect 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. src_rect with non-positive size is treated as empty.

Note: The alpha channel data in src will overwrite the corresponding data in this image at the target position. To blend alpha channels, use blend_rect() instead.

void blit_rect_mask(src: Image, mask: Image, src_rect: Rect2i, dst: Vector2i) 🔗

將源圖像 src 上的矩形區域 src_rect 複製到本圖像從座標 dst 起的區域，會根據兩者的圖像區域進行裁剪。如果遮罩圖 mask 上某個像素的 Alpha 值非 0，就會把 src 上對應的圖元複製到 dst 上。這張圖像和 src 圖像的格式必須一致。src 圖像和 mask 圖像的大小（寬度和高度）必須相同，格式可以不同。src_rect 的大小如果非正，則會作為空矩形處理。

void bump_map_to_normal_map(bump_scale: float = 1.0) 🔗

將凹凸貼圖轉換為法線貼圖。凹凸貼圖提供每個圖元的高度偏移，而法線貼圖提供每個圖元的法線方向。

void clear_mipmaps() 🔗

刪除圖像的多級漸遠紋理。

Error compress(mode: CompressMode, source: CompressSource = 0, astc_format: ASTCFormat = 0) 🔗

Compresses the image with a VRAM-compressed format 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.

The astc_format parameter is only taken into account when using ASTC compression; it is ignored for all other formats.

Note: compress() is only supported in editor builds. When run in an exported project, this method always returns @GlobalScope.ERR_UNAVAILABLE.

Error compress_from_channels(mode: CompressMode, channels: UsedChannels, astc_format: ASTCFormat = 0) 🔗

Compresses the image with a VRAM-compressed format 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() 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.

The astc_format parameter is only taken into account when using ASTC compression; it is ignored for all other formats.

Note: compress_from_channels() is only supported in editor builds. When run in an exported project, this method always returns @GlobalScope.ERR_UNAVAILABLE.

Dictionary compute_image_metrics(compared_image: Image, use_luma: bool) 🔗

Compute image metrics on the current image and the compared image. This can be used to calculate the similarity between two images.

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

void convert(format: Format) 🔗

Converts this image's format to the given format.

void copy_from(src: Image) 🔗

將源圖像 src 複製到本圖像。

Image create(width: int, height: int, use_mipmaps: bool, format: Format) static 🔗

已棄用： Use create_empty().

Creates an empty image of the given size and format. If use_mipmaps is true, generates mipmaps for this image (see generate_mipmaps()).

Image create_empty(width: int, height: int, use_mipmaps: bool, format: Format) static 🔗

Creates an empty image of the given size and format. If use_mipmaps is true, generates mipmaps for this image (see generate_mipmaps()).

Image create_from_data(width: int, height: int, use_mipmaps: bool, format: Format, data: PackedByteArray) static 🔗

Creates a new image of the given size and format. Fills the image with the given raw data. If use_mipmaps is true, loads the mipmaps for this image from data. See generate_mipmaps().

void crop(width: int, height: int) 🔗

將該圖像裁剪成給定的 width 和 height。如果指定的大小大於目前大小，則額外的區域用黑色圖元填充。

Error decompress() 🔗

Decompresses the image if it is VRAM-compressed in a supported format. This increases memory utilization, but allows modifying the image. Returns @GlobalScope.OK if the format is supported, otherwise @GlobalScope.ERR_UNAVAILABLE. All VRAM-compressed formats supported by Godot can be decompressed with this method, except FORMAT_ETC2_R11S, FORMAT_ETC2_RG11S, and FORMAT_ETC2_RGB8A1.

AlphaMode detect_alpha() const 🔗

如果圖像有 Alpha 值的資料，則返回 ALPHA_BLEND。如果所有的 Alpha 值都儲存在一個位上，則返回 ALPHA_BIT。如果沒有找到 Alpha 值的資料，則返回 ALPHA_NONE。

UsedChannels detect_used_channels(source: CompressSource = 0) const 🔗

Returns the color channels used by this image. If the image is compressed, the original source must be specified.

void fill(color: Color) 🔗

使用顏色 color 填充圖像。

void fill_rect(rect: Rect2i, color: Color) 🔗

使用顏色 color 填充矩形 rect。

void fix_alpha_edges() 🔗

將 Alpha 較低的圖元與附近圖元混合。

void flip_x() 🔗

水平翻轉圖像。

void flip_y() 🔗

垂直翻轉圖像。

Error generate_mipmaps(renormalize: bool = false) 🔗

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 has_mipmaps() or get_mipmap_count(). Calling generate_mipmaps() on an image that already has mipmaps will replace existing mipmaps in the image.

PackedByteArray get_data() const 🔗

返回圖像原始資料的副本。

int get_data_size() const 🔗

Returns size (in bytes) of the image's raw data.

Format get_format() const 🔗

Returns this image's format.

int get_height() const 🔗

返回圖像的高度。

int get_mipmap_count() const 🔗

傳回mipmap 級別數，如果影像沒有mipmap，則傳回0。透過此方法，最大的主級別影像不會被計為mipmap 級別，因此如果您想要包含它，您此計數可加 1。

int get_mipmap_offset(mipmap: int) const 🔗

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

Color get_pixel(x: int, y: int) const 🔗

返回 (x, y) 處的圖元的顏色。

這與 get_pixelv() 相同，但使用兩個整數參數而不是一個 Vector2i 參數。

Color get_pixelv(point: Vector2i) const 🔗

返回 point 處圖元的顏色。

這與 get_pixel() 相同，只是用一個 Vector2i 參數代替了兩個整數參數。

Image get_region(region: Rect2i) const 🔗

返回一個新的 Image，它是使用 region 指定的該 Image 區域的副本。

Vector2i get_size() const 🔗

返回圖像的大小（寬度和高度）。

Rect2i get_used_rect() const 🔗

返回一個包含該圖像可見部分的 Rect2i，將具有非零 alpha 通道的每個圖元視為可見。

int get_width() const 🔗

返回圖像的寬度。

bool has_mipmaps() const 🔗

如果圖像已經生成多級漸遠紋理，則返回 true。

bool is_compressed() const 🔗

如果圖像被壓縮，返回 true。

bool is_empty() const 🔗

如果圖像沒有資料，返回 true。

bool is_invisible() const 🔗

如果圖像中所有圖元的 Alpha 都是 0，則返回 true。如果有任何圖元的 Alpha 高於 0，則返回 false。

void linear_to_srgb() 🔗

Converts the entire image from linear encoding to nonlinear sRGB encoding by using a lookup table. Only works on images with FORMAT_RGB8 or FORMAT_RGBA8 formats.

Error load(path: String) 🔗

從檔 path 載入圖像。有關支援的圖像格式的列表和限制，請參閱支援的圖像格式。

警告：該方法只能用於編輯器，或需要在運作時載入外部圖像的情況，例如位元於 user:// 目錄的圖像，並且可能不適用於匯出的專案。

另請參閱 ImageTexture 說明，以獲取使用範例。

Error load_bmp_from_buffer(buffer: PackedByteArray) 🔗

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.

Error load_dds_from_buffer(buffer: PackedByteArray) 🔗

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

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

Error load_exr_from_buffer(buffer: PackedByteArray) 🔗

Loads an image from the binary contents of an OpenEXR file.

Image load_from_file(path: String) static 🔗

建立一個新的 Image 並從指定檔載入資料。

Error load_jpg_from_buffer(buffer: PackedByteArray) 🔗

從 JPEG 檔的二進位內容載入圖像。

Error load_ktx_from_buffer(buffer: PackedByteArray) 🔗

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.

Error load_png_from_buffer(buffer: PackedByteArray) 🔗

從 PNG 檔的二進位內容載入圖像。

Error load_svg_from_buffer(buffer: PackedByteArray, scale: float = 1.0) 🔗

從未壓縮 SVG 檔案 (.svg) 的 UTF-8 二進位內容載入映像。

注意： 使用壓縮的 SVG 檔案（例如 .svgz）時請注意，在載入之前需要對其進行解壓縮。

注意：此方法僅在啟用了 SVG 模組的引擎版本中可用。預設情況下，SVG 模組處於啟用狀態，但可以使用 module_svg_enabled=no SCons 選項在建置時停用它。

Error load_svg_from_string(svg_str: String, scale: float = 1.0) 🔗

Loads an image from the string contents of an 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.

Error load_tga_from_buffer(buffer: PackedByteArray) 🔗

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.

Error load_webp_from_buffer(buffer: PackedByteArray) 🔗

從 WebP 檔的二進位內容載入圖像。

void normal_map_to_xy() 🔗

轉換圖像的資料以表示 3D 平面上的座標。可以在該圖像標記法線貼圖時使用。法線貼圖可以在不增加多邊形數量的情況下向 3D 表面新增大量細節。

void premultiply_alpha() 🔗

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

void resize(width: int, height: int, interpolation: Interpolation = 1) 🔗

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

Note: If the image's format is FORMAT_RGBA4444, FORMAT_RGB565, or FORMAT_RGBE9995, it will be temporarily converted to either FORMAT_RGBA8 or FORMAT_RGBAH. This can affect the quality of the resized image.

void resize_to_po2(square: bool = false, interpolation: Interpolation = 1) 🔗

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

Image rgbe_to_srgb() 🔗

Converts a standard linear RGBE (Red Green Blue Exponent) image to an image that uses nonlinear sRGB encoding.

void rotate_90(direction: ClockDirection) 🔗

將該圖像按照 direction 指定的方向旋轉 90 度。該圖像的寬度和高度必須大於 1。如果寬和高不相等，則會調整圖像的大小。

void rotate_180() 🔗

將該圖像旋轉 180 度。該圖像的寬度和高度必須大於 1。

Error save_dds(path: String) const 🔗

Saves the image as a DDS (DirectDraw Surface) file to path. DDS is a container format that can store textures in various compression formats, such as DXT1, DXT5, or BC7. This function will return @GlobalScope.ERR_UNAVAILABLE if Godot was compiled without the DDS module.

Note: The DDS module may be disabled in certain builds, which means save_dds() will return @GlobalScope.ERR_UNAVAILABLE when it is called from an exported project.

PackedByteArray save_dds_to_buffer() const 🔗

Saves the image as a DDS (DirectDraw Surface) file to a byte array. DDS is a container format that can store textures in various compression formats, such as DXT1, DXT5, or BC7. This function will return an empty byte array if Godot was compiled without the DDS module.

Note: The DDS module may be disabled in certain builds, which means save_dds_to_buffer() will return an empty byte array when it is called from an exported project.

Error save_exr(path: String, grayscale: bool = false, color_image: bool = false, max_linear_value: float = -1.0) const 🔗

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. Set color_image to true when saving a color image, such as a screenshot. Negative values will be included when color_image is false, which may be useful for saving raw floating point data such as a lightmap that includes negative light information. Color component values in the resulting EXR file will not exceed max_linear_value if max_linear_value is not negative. This function will return @GlobalScope.ERR_UNAVAILABLE if Godot was compiled without the TinyEXR module.

When saving screenshots of a project that uses HDR output, use Window.get_output_max_linear_value() for max_linear_value.

PackedByteArray save_exr_to_buffer(grayscale: bool = false, color_image: bool = false, max_linear_value: float = -1.0) const 🔗

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. Set color_image to true when saving a color image, such as a screenshot. Negative values will be included when color_image is false, which may be useful for saving raw floating point data such as a lightmap that includes negative light information. Color component values in the resulting EXR file will not exceed max_linear_value if max_linear_value is not negative. This function will return an empty byte array if Godot was compiled without the TinyEXR module.

When saving screenshots of a project that uses HDR output, use Window.get_output_max_linear_value() for max_linear_value.

Error save_jpg(path: String, quality: float = 0.75) const 🔗

將該圖像作為 JPEG 檔保存到 path，指定的 quality 介於 0.01 和 1.0（包括）之間。更高的 quality 值會以更大的檔大小為代價產生更好看的輸出。推薦的 quality 值介於 0.75 和 0.90 之間。即使品質為 1.00，JPEG 壓縮仍然是有損的。

注意：JPEG 不保存 alpha 通道。如果該 Image 包含 alpha 通道，該圖像仍將被保存，但產生的 JPEG 檔將不包含 alpha 通道。

PackedByteArray save_jpg_to_buffer(quality: float = 0.75) const 🔗

將該圖像作為 JPEG 檔保存到位元組陣列中，指定的 quality 介於 0.01 和 1.0（包括）之間。更高的 quality 值會以更大的位元組陣列大小（以及因此的記憶體使用）為代價產生更好看的輸出。推薦的 quality 值介於 0.75 和 0.90 之間。即使品質為 1.00，JPEG 壓縮仍然是有損的。

注意：JPEG 不保存 alpha 通道。如果該 Image 包含 alpha 通道，該圖像仍將被保存，但產生的位元組陣列將不包含 alpha 通道。

Error save_png(path: String) const 🔗

將該圖像作為 PNG 檔保存到位於 path 的檔中。

PackedByteArray save_png_to_buffer() const 🔗

將該圖像作為 PNG 檔保存到位元組陣列中。

Error save_webp(path: String, lossy: bool = false, quality: float = 0.75) const 🔗

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.

PackedByteArray save_webp_to_buffer(lossy: bool = false, quality: float = 0.75) const 🔗

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.

void set_data(width: int, height: int, use_mipmaps: bool, format: Format, data: PackedByteArray) 🔗

覆蓋現有 Image 的資料。create_from_data() 的非靜態等價物。

void set_pixel(x: int, y: int, color: Color) 🔗

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

var img_width = 10
var img_height = 5
var img = Image.create(img_width, img_height, false, Image.FORMAT_RGBA8)

img.set_pixel(1, 2, Color.RED) # Sets the color at (1, 2) to red.

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 set_pixelv(), but with a two integer arguments instead of a Vector2i argument.

Note: Depending on the image's format, the color set here may be clamped or lose precision. Do not assume the color returned by get_pixel() to be identical to the one set here; any comparisons will likely need to use an approximation like Color.is_equal_approx().

Note: On grayscale image formats, only the red channel of color is used (and alpha if relevant). The green and blue channels are ignored.

void set_pixelv(point: Vector2i, color: Color) 🔗

Sets the Color of the pixel at point to color.

var img_width = 10
var img_height = 5
var img = Image.create(img_width, img_height, false, Image.FORMAT_RGBA8)

img.set_pixelv(Vector2i(1, 2), Color.RED) # Sets the color at (1, 2) to red.

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 set_pixel(), but with a Vector2i argument instead of two integer arguments.

Note: Depending on the image's format, the color set here may be clamped or lose precision. Do not assume the color returned by get_pixelv() to be identical to the one set here; any comparisons will likely need to use an approximation like Color.is_equal_approx().

Note: On grayscale image formats, only the red channel of color is used (and alpha if relevant). The green and blue channels are ignored.

void shrink_x2() 🔗

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

void srgb_to_linear() 🔗

Converts the raw data from nonlinear sRGB encoding to linear encoding using a lookup table. Only works on images with FORMAT_RGB8 or FORMAT_RGBA8 formats.

Note: The 8-bit formats required by this method are not suitable for storing linearly encoded values; a significant amount of color information will be lost in darker values. To maintain image quality, this method should not be used.