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

影像資料型別。

說明

本機影像資料型別。包含可以被轉換為 ImageTexture 的影像資料，並提供常用的影像處理方法。Image 的最大寬度和高度為 MAX_WIDTH 和 MAX_HEIGHT。

Image 不能被直接分配給物件的紋理屬性（例如 Sprite2D.texture），必須先手動轉換為 ImageTexture。

注意：修改影像資料的方法不能用於 VRAM 壓縮的影像。請先使用 decompress() 方法將影像轉換為未壓縮格式。

注意：由於圖形硬體限制，最大影像大小為 16384×16384 像素。較大的影像可能無法匯入。

教學

• 匯入影像

• 執行時檔案載入與儲存

屬性

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, profile: CompressProfile = 0)
Error	compress_from_channels(mode: CompressMode, channels: UsedChannels, profile: CompressProfile = 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, preserve_alpha_test_coverage: bool = false, alpha_test_threshold: float = 0.5)
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 紋理格式 RGB 具有三個分量，每個分量的位元深度度為 8。

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

Format FORMAT_RGBA8 = 5

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

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

Format FORMAT_RGBA4444 = 6

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

Format FORMAT_RGB565 = 7

OpenGL 紋理格式 RGB，具有三個元件。紅色和藍色的位元深度度為 5，綠色的位元深度度為 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

S3TC 紋理格式使用塊壓縮 1，並且是 S3TC 的最小變化，僅提供 1 位元的 Alpha 和顏色資料 預乘以 Alpha。

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

Format FORMAT_DXT3 = 18

使用塊壓縮 2 的 S3TC 貼圖格式,並且顏色資料被解析為沒有與 Alpha 預先相乘。非常適用於具有 半透明和不透明區域之間的清晰的 Alpha 過渡。

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

Format FORMAT_DXT5 = 19

S3TC 紋理格式也稱為塊壓縮 3 或 BC3，其中包含 64 位元的 Alpha 通道資料，後跟 64 位元的 DXT1 編碼顏色資料。顏色資料不會與 DXT3 預先乘以 Alpha。與 DXT3 相比，DXT5 對於透明漸變通常會產生更好的結果。

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

Format FORMAT_RGTC_R = 20

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

Format FORMAT_RGTC_RG = 21

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

Format FORMAT_BPTC_RGBA = 22

使用 BPTC 壓縮算法和無符號正規化 RGBA 分量的紋理格式。

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

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

愛立信紋理壓縮格式 2（RGB8 變體），它是 ETC1 的後續版本，可壓縮 RGB888 資料。

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

Format FORMAT_ETC2_RGBA8 = 31

愛立信紋理壓縮格式 2（RGBA8 變體），它可以壓縮 RGBA8888 資料，完全支援 Alpha。

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

Format FORMAT_ETC2_RGB8A1 = 32

愛立信紋理壓縮格式 2（RGB8_PUNCHTHROUGH_ALPHA1 變體），它可以壓縮 RGBA 資料，使 Alpha 完全透明或完全不透明。

注意：建立 ImageTexture 時，會執行非線性 sRGB 到線性編碼的轉換。

Format FORMAT_ETC2_RA_AS_RG = 33

愛立信紋理壓縮格式 2（RGBA8 變體），能夠壓縮 RA 資料，將其解釋為兩個通道（紅和綠）。另見 FORMAT_ETC2_RGBA8。

Format FORMAT_DXT5_RA_AS_RG = 34

S3TC 紋理格式，也叫 Block Compression 3、BC3。能夠壓縮 RA 資料並將其解釋為兩個通道（紅和綠）。另見 FORMAT_DXT5。

Format FORMAT_ASTC_4x4 = 35

Adaptive Scalable Texture Compression。這實作了 4×4（高品質）模式。

Format FORMAT_ASTC_4x4_HDR = 36

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

Format FORMAT_ASTC_8x8 = 37

Adaptive Scalable Texture Compression。這實作了 8×8（低品質）模式。

Format FORMAT_ASTC_8x8_HDR = 38

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

Format FORMAT_R16 = 39

OpenGL 紋理格式 GL_R16 只有一個分量，即 16 位元無符號正規化整數值。由於該值已正規化，因此每個分量的值都被限制在 0.0 到 1.0（含）之間。

注意：由於硬體支援有限，推薦主要在桌面或遊戲主機裝置上使用。它可能不受移動或 Web 平台的支援，因此會被轉換為 FORMAT_RF 格式。

Format FORMAT_RG16 = 40

OpenGL 紋理格式 GL_RG16 包含兩個分量，每個分量都是一個 16 位元無符號正規化整數值。由於該值已正規化，因此每個分量的值都被限制在 0.0 到 1.0（含）之間。

注意：由於硬體支援有限，推薦主要在桌面或遊戲主機裝置上使用。它可能不受移動或 Web 平台的支援，因此會被轉換為 FORMAT_RGF 格式。

Format FORMAT_RGB16 = 41

OpenGL 紋理格式 GL_RGB16 包含三個分量，每個分量都是一個 16 位元無符號正規化整數值。由於該值已正規化，因此每個分量的值都被限制在 0.0 到 1.0（含）之間。

注意：由於硬體支援有限，推薦主要在桌面或遊戲主機裝置上使用。它可能不受移動或 Web 平台的支援，因此會被轉換為 FORMAT_RGBF 格式。

Format FORMAT_RGBA16 = 42

OpenGL 紋理格式 GL_RGBA16 包含四個分量，每個分量都是一個 16 位元無符號正規化整數值。由於該值已正規化，因此每個分量的值都被限制在 0.0 到 1.0（含）之間。

注意：由於硬體支援有限，推薦主要在桌面或遊戲主機裝置上使用。它可能不受移動或 Web 平台的支援，因此會被轉換為 FORMAT_RGBAF 格式。

Format FORMAT_R16I = 43

OpenGL 紋理格式 GL_R16UI 包含一個分量，該分量是一個 16 位元無符號整數值。每個分量的值都被限制在 0 到 65535（含）之間。

注意：在著色器中使用時，該紋理需要使用 usampler 取樣器。此外，在相容性渲染器下，它僅支援最近鄰過濾。

注意：使用 get_pixel() 進行取樣時，回傳的 Color 值需要除以 65535 才能獲得正確的顏色值。

Format FORMAT_RG16I = 44

OpenGL 紋理格式 GL_RG16UI 包含兩個分量，每個分量都是一個 16 位元無符號整數值。每個分量的值都被限制在 0 到 65535（含）之間。

注意：在著色器中使用時，該紋理需要使用 usampler 取樣器。此外，在相容性渲染器下，它僅支援最近鄰過濾。

注意：使用 get_pixel() 進行取樣時，回傳的 Color 值需要除以 65535 才能獲得正確的顏色值。

Format FORMAT_RGB16I = 45

OpenGL 紋理格式 GL_RGB16UI 包含三個分量，每個分量都是一個 16 位元無符號整數值。每個分量的值都被限制在 0 到 65535（含）之間。

注意：在著色器中使用時，該紋理需要使用 usampler 取樣器。此外，在相容性渲染器下，它僅支援最近鄰過濾。

注意：使用 get_pixel() 進行取樣時，回傳的 Color 值需要除以 65535 才能獲得正確的顏色值。

Format FORMAT_RGBA16I = 46

OpenGL 紋理格式 GL_RGBA16UI 包含四個分量，每個分量都是一個 16 位元無符號整數值。每個分量的值都被限制在 0 到 65535（含）之間。

注意：在著色器中使用時，該紋理需要使用 usampler 取樣器。此外，在相容性渲染器下，它僅支援最近鄰過濾。

注意：使用 get_pixel() 進行取樣時，回傳的 Color 值需要除以 65535 才能獲得正確的顏色值。

Format FORMAT_ASTC_6x6 = 47

Adaptive Scalable Texture Compression. This implements the 6×6 (medium quality) mode.

Format FORMAT_ASTC_6x6_HDR = 48

Same format as FORMAT_ASTC_6x6, but with the hint to let the GPU know it is used for HDR.

Format FORMAT_MAX = 49

代表 Format 列舉的大小。

---

enum Interpolation: 🔗

Interpolation INTERPOLATE_NEAREST = 0

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

Interpolation INTERPOLATE_BILINEAR = 1

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

Interpolation INTERPOLATE_CUBIC = 2

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

Interpolation INTERPOLATE_TRILINEAR = 3

Performs bilinear separately on the two most-suited mipmap levels, then linearly interpolates between them.

It's slower than INTERPOLATE_BILINEAR, but produces higher-quality results with far fewer aliasing artifacts.

If the image does not have mipmaps, they will be generated and used internally, but no mipmaps will be generated on the resulting image.

Note: If you intend to scale multiple copies of the original image, it's better to call generate_mipmaps() on it in advance, to avoid wasting processing power in generating them again and again.

On the other hand, if the image already has mipmaps, they will be used, and a new set will be generated for the resulting image.

Interpolation INTERPOLATE_LANCZOS = 4

執行 Lanczos 插值。這是最慢的影像調整大小模式，但通常可以提供最佳效果，尤其是在縮小影像時。

---

enum AlphaMode: 🔗

AlphaMode ALPHA_NONE = 0

影像完全不透明。它不儲存 Alpha 通道資料。

AlphaMode ALPHA_BIT = 1

影像儲存的像素要麼完全不透明，要麼完全透明。也稱為穿透式 Alpha 通道。

AlphaMode ALPHA_BLEND = 2

影像儲存 alpha 資料，其值在 0.0 和 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

該影像僅使用一個通道表示亮度（灰度圖）。

UsedChannels USED_CHANNELS_LA = 1

該影像使用兩個通道，分別表示亮度和 Alpha。

UsedChannels USED_CHANNELS_R = 2

該影像僅使用紅色通道。

UsedChannels USED_CHANNELS_RG = 3

該影像使用紅色和綠色兩個通道。

UsedChannels USED_CHANNELS_RGB = 4

該影像使用紅、綠、藍三個通道。

UsedChannels USED_CHANNELS_RGBA = 5

該影像使用紅色、綠色、藍色和 Alpha 四個通道。

---

enum CompressSource: 🔗

CompressSource COMPRESS_SOURCE_GENERIC = 0

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

CompressSource COMPRESS_SOURCE_SRGB = 1

來源紋理（在壓縮前）使用非線性 sRGB 編碼。

CompressSource COMPRESS_SOURCE_NORMAL = 2

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

---

enum CompressProfile: 🔗

CompressProfile COMPRESS_PROFILE_AUTOMATIC = 0

Automatically adjusts the quality level based on the number of unique color channels present in the image. For ASTC, this corresponds to picking 8×8 when only one channel is detected (R, L), 6×6 when two channels are detected (RG, LA), and 4×4 in all other cases.

CompressProfile COMPRESS_PROFILE_MAX_QUALITY = 1

Prioritizes highest quality over compression. For ASTC, this corresponds to using a 4×4 block size.

CompressProfile COMPRESS_PROFILE_COMPRESSED = 2

Prioritizes some compression over quality. For ASTC, this corresponds to using a 6×6 block size.

CompressProfile COMPRESS_PROFILE_MAX_COMPRESSION = 3

Prioritizes highest compression over quality. For ASTC, this corresponds to using an 8×8 block size.

CompressProfile COMPRESS_PROFILE_MAX = 4

Represents the size of the CompressProfile enum.

---

enum ASTCFormat: 🔗

ASTCFormat ASTC_FORMAT_4x4 = 0

表示應該使用高品質 4×4 ASTC 壓縮格式的提示。

ASTCFormat ASTC_FORMAT_8x8 = 1

表示應該使用低品質 8×8 ASTC 壓縮格式的提示。

---

常數

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) 🔗

使用 brightness 調整影像的亮度，使用 contrast 調整影像的對比度，使用 saturation 調整影像的飽和度。對壓縮影像無效（見 is_compressed()）。

---

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

Alpha-blends 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: Simultaneously reading and writing to the same image reference may lead to unexpected results.

---

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) 🔗

將 src 影像上的 src_rect 複製到該影像的座標 dst 處，並根據兩個影像邊界進行裁剪。該影像和 src 影像的格式必須相同。非正數大小的 src_rect 將被視為空矩形。

注意：src 中的 Alpha 通道資料會覆蓋影像目標位置上對應的資料。要對 Alpha 通道進行混合，請改用 blend_rect()。

---

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, profile: CompressProfile = 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 profile lets the user pick whether the compression should prioritize quality or a smaller size. Only ASTC compression uses this currently.

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, profile: CompressProfile = 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, ETC2, and ASTC formats. For other formats (non DXT, ETC2, or ASTC), this argument is ignored.

The profile lets the user pick whether the compression should prioritize quality or a smaller size. Only ASTC compression uses this currently.

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) 🔗

計算目前影像和被比較影像的影像指標。這可用於計算兩幅影像之間的相似度。

該字典包含 max、mean、mean_squared、root_mean_squared 和 peak_snr。

---

void convert(format: Format) 🔗

將影像格式轉換為 format。

---

void copy_from(src: Image) 🔗

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

---

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

已棄用： Use create_empty().

建立一個給定大小和格式的空影像。如果 use_mipmaps 為 true，則為該影像生成 mipmap（參見 generate_mipmaps()）。

---

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

建立一個給定大小和格式的空影像。如果 use_mipmaps 為 true，則為該影像生成 mipmap（參見 generate_mipmaps()）。

---

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

建立一個給定大小和格式的新影像。用給定的原始資料填充影像。如果 use_mipmaps 為 true，則從 data 為該影像載入 Mipmap。見 generate_mipmaps()。

---

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

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

---

Error decompress() 🔗

如果影像採用受支援的 VRAM 壓縮格式，則對其進行解壓縮。這會增加記憶體佔用，但允許修改影像。如果格式受支援，則回傳 @GlobalScope.OK，否則回傳 @GlobalScope.ERR_UNAVAILABLE。Godot 支援的所有 VRAM 壓縮格式都可以使用該方法解壓縮，但 FORMAT_ETC2_R11S、FORMAT_ETC2_RG11S 和 FORMAT_ETC2_RGB8A1 除外。

---

AlphaMode detect_alpha() const 🔗

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

---

UsedChannels detect_used_channels(source: CompressSource = 0) const 🔗

回傳影像所使用的顏色通道。如果為壓縮影像，則必須使用 source 指定原始影像。

---

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, preserve_alpha_test_coverage: bool = false, alpha_test_threshold: float = 0.5) 🔗

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.

If preserve_alpha_test_coverage is true it automatically adjusts alpha values to maintain consistent coverage when alpha testing is used. This is especially useful for hair, foliage, or other alpha-tested materials, as it prevents fading or popping artifacts across mipmap levels (LODs). This option is intended for color textures and clamps the alpha channel in the 0.0 - 1.0 range.

The alpha_test_threshold parameter is the alpha threshold used when preserving alpha test coverage across mipmap levels. The coverage is measured at mipmap 0 using the setting and the lower mipmaps are adjusted to match that coverage. Higher values preserve more detail, lower values create softer edges. Note that this threshold is independent from the Alpha Scissor Threshold set on the material and they both may need to be tuned for optimal results.

---

PackedByteArray get_data() const 🔗

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

---

int get_data_size() const 🔗

回傳影像原始資料的大小（單位為位元組）。

---

Format get_format() const 🔗

回傳影像的格式。

---

int get_height() const 🔗

返回影像的高度。

---

int get_mipmap_count() const 🔗

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

---

int get_mipmap_offset(mipmap: int) const 🔗

回傳儲存在影像的 data 字典中的索引為 mipmap 的多級漸遠紋理的偏移量。

---

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. Only works on images with FORMAT_RGB8, FORMAT_RGBA8, FORMAT_RGBH, or FORMAT_RGBAH format.

---

Error load(path: String) 🔗

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

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

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

---

Error load_bmp_from_buffer(buffer: PackedByteArray) 🔗

從 BMP 檔案的二進位內容載入影像。

注意：Godot 的 BMP 模組不支援每像素 16 位元的影像。僅支援每像素 1 位元、4 位元、8 位元、24 位元和 32 位元的影像。

注意：該方法僅在啟用了 BMP 模組的引擎版本中可用。預設情況下，BMP 模組是啟用的，但可以在建置時使用 module_bmp_enabled=no SCons 選項停用它。

---

Error load_dds_from_buffer(buffer: PackedByteArray) 🔗

從 DDS 檔案的二進位內容載入影像。

注意：該方法僅在啟用了 DDS 模組的引擎版本中可用。預設情況下，DDS 模組是啟用的，但可以在建置時使用 module_dds_enabled=no SCons 選項停用它。

---

Error load_exr_from_buffer(buffer: PackedByteArray) 🔗

從 OpenEXR 檔案的二進位內容載入影像。

---

Image load_from_file(path: String) static 🔗

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

---

Error load_jpg_from_buffer(buffer: PackedByteArray) 🔗

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

---

Error load_ktx_from_buffer(buffer: PackedByteArray) 🔗

從 KTX 檔案的二進位內容載入影像。與大多數影像格式不同，KTX 可以儲存 VRAM 壓縮資料並嵌入 mipmap。

注意：Godot 的 libktx 實作僅支援 2D 影像。不支援立方體貼圖、紋理陣列和去填充。

注意：該方法僅在啟用了 KTX 模組的引擎版本中可用。預設情況下，KTX 模組是啟用的，但可以在建置時使用 module_ktx_enabled=no SCons 選項停用它。

---

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) 🔗

從 SVG 檔案（.svg）的字串內容載入影像。

注意：該方法僅在啟用了 SVG 模組的引擎版本中可用。SVG 模組預設是啟用的，但可以在建置時使用 module_svg_enabled=no SCons 選項停用它。

---

Error load_tga_from_buffer(buffer: PackedByteArray) 🔗

從 TGA 檔案的二進位內容載入影像。

注意：該方法僅在啟用了 TGA 模組的引擎版本中可用。預設情況下，TGA 模組是啟用的，但可以在建置時使用 module_tga_enabled=no SCons 選項停用它。

---

Error load_webp_from_buffer(buffer: PackedByteArray) 🔗

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

---

void normal_map_to_xy() 🔗

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

---

void premultiply_alpha() 🔗

將顏色值與 Alpha 值相乘。像素的最終顏色值為 (color * alpha)/256。另見 CanvasItemMaterial.blend_mode。

---

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

將影像調整為指定的 width（寬度）和 height（高度）。新的像素將使用通過 Interpolation 常數定義的 interpolation（插值）模式進行計算。

注意： 如果影像的格式為 FORMAT_RGBA4444、FORMAT_RGB565 或 FORMAT_RGBE9995，它將被暫時轉換為 FORMAT_RGBA8 或 FORMAT_RGBAH。這可能會影響調整大小後影像的品質。

---

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

將影像的寬度和高度調整為最接近的 2 的冪。如果 square 為 true，則將寬度和高度設定為相同。新像素將通過使用 Interpolation 常數定義的 interpolation 模式計算。

---

Image rgbe_to_srgb() 🔗

將標準的線性 RGBE（紅綠藍指數）影像轉換為使用非線性 sRGB 編碼的影像。

---

void rotate_90(direction: ClockDirection) 🔗

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

---

void rotate_180() 🔗

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

---

Error save_dds(path: String) const 🔗

將影像以 DDS（DirectDraw Surface）檔案的形式儲存至 path 路徑。DDS 是一種能夠以 DXT1、DXT5、BC7 等壓縮格式儲存紋理的容器格式。如果編譯 Godot 時未包含 DDS 模組，則該函式回傳 @GlobalScope.ERR_UNAVAILABLE。

注意：某些建置會停用 DDS 模組，這意味著當 save_dds() 從匯出的專案中被呼叫時將回傳 @GlobalScope.ERR_UNAVAILABLE。

---

PackedByteArray save_dds_to_buffer() const 🔗

將影像以 DDS（DirectDraw Surface）檔案的形式儲存為位元組陣列。DDS 是一種能夠以 DXT1、DXT5、BC7 等壓縮格式儲存紋理的容器格式。如果編譯 Godot 時未包含 DDS 模組，則該函式回傳空位元組陣列。

注意：某些建置會停用 DDS 模組，這意味著當 save_dds_to_buffer() 從匯出的專案中被呼叫時將回傳一個空位元組陣列。

---

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

將影像以 EXR 檔案格式儲存到 path。如果 grayscale 為 true 且影像只有一個通道，則會顯式地將其儲存為單色影像，而不是僅儲存一個紅色通道。儲存彩色影像（例如螢幕截圖）時，請將 color_image 設定為 true。如果 color_image 為 false，則會包含負值，這對於儲存包含負光照資訊的原始浮點資料（例如光照貼圖）非常有用。如果 max_linear_value 不為負數，則生成的 EXR 檔案中的顏色分量值不會超過 max_linear_value。如果 Godot 編譯時未包含 TinyEXR 模組，則該方法將回傳 @GlobalScope.ERR_UNAVAILABLE。

儲存使用 HDR 輸出的專案的螢幕截圖時，請使用 Window.get_output_max_linear_value() 來取得 max_linear_value。

---

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

將影像以 EXR 檔案格式儲存到位元組陣列中。如果 grayscale 為 true 且影像只有一個通道，則會顯式地將其儲存為單色影像，而不是僅儲存一個紅色通道。儲存彩色影像（例如螢幕截圖）時，請將 color_image 設定為 true。如果 color_image 為 false，則會包含負值，這對於儲存包含負光照資訊的原始浮點資料（例如光照貼圖）非常有用。如果 max_linear_value 不為負數，則生成的 EXR 檔案中的顏色分量值不會超過 max_linear_value。如果 Godot 編譯時未安裝 TinyEXR 模組，則該方法將回傳一個空位元組陣列。

儲存使用 HDR 輸出的專案的螢幕截圖時，請使用 Window.get_output_max_linear_value() 來取得 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 🔗

將該影像作為 WebP（Web 圖片）檔案儲存到 path 中的檔案中。預設情況下，它將無損儲存。如果 lossy 為 true，則該影像將使用介於 0.0 和 1.0（包含）之間的 quality 設定進行有損儲存。無損 WebP 提供比 PNG 更有效的壓縮。

注意：WebP 格式的大小限制為 16383×16383 像素，而 PNG 可以儲存更大的影像。

---

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

將該影像作為 WebP（Web 圖片）檔案儲存到位元組陣列中。預設情況下，它將無損儲存。如果 lossy 為 true，則該影像將使用介於 0.0 和 1.0（包含）之間的 quality 設定進行有損儲存。無損 WebP 提供比 PNG 更有效的壓縮。

注意：WebP 格式的大小限制為 16383×16383 像素，而 PNG 可以儲存更大的影像。

---

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) 🔗

將 (x, y) 處像素的 Color 設定為 color。

GDScriptC#

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) # 將 (1, 2) 處的顏色設定為紅色。

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

注意：根據影像格式的不同，此處設定的顏色可能會受到限制或失去精度。請勿假定 get_pixel() 方法回傳的顏色與此處設定的顏色完全相同；任何比較操作可能都需要使用近似比較方法，例如 Color.is_equal_approx()。

注意：在灰度影像格式中，僅使用 color 的紅色通道（以及相關的 alpha 通道）。綠色和藍色通道將被忽略。

---

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

將 point 處像素的 Color 設定為 color。

GDScriptC#

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) # 將 (1, 2) 處的顏色設定為紅色。

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

注意：根據影像格式的不同，此處設定的顏色可能會受到限制或失去精度。請勿假定 get_pixelv() 方法回傳的顏色與此處設定的顏色完全相同；任何比較操作可能都需要使用近似比較方法，例如 Color.is_equal_approx()。

注意：在灰度影像格式中，僅使用 color 的紅色通道（以及相關的 alpha 通道）。綠色和藍色通道將被忽略。

---

void shrink_x2() 🔗

在每個軸上將影像縮小 2 倍（這會將像素數除以 4）。

---

void srgb_to_linear() 🔗

Converts the raw data from nonlinear sRGB encoding to linear encoding. Only works on images with FORMAT_RGB8, FORMAT_RGBA8, FORMAT_RGBH, or FORMAT_RGBAH format.

Note: The 8-bit formats are not suitable for storing linearly encoded values; a significant amount of color information will be lost in darker values. Use this function on images that use a floating point format instead.