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。

注意：由于图形硬件限制，最大图像大小为 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, 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)
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_exr(path: String, grayscale: bool = false) const
PackedByteArray	save_exr_to_buffer(grayscale: bool = false) 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_R16F，其中有一个分量，即 16 位“半精度”浮点值。

Format FORMAT_RGH = 13

OpenGL 纹理格式 GL_RG16F，其中有两个分量，每个分量都是 16 位“半精度”浮点值。

Format FORMAT_RGBH = 14

OpenGL 纹理格式 GL_RGB16F，其中有三个分量，每个分量都是 16 位“半精度”浮点值。

Format FORMAT_RGBAH = 15

OpenGL 纹理格式 GL_RGBA16F，其中有四个分量，每个都是 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

ETC2%E5%92%8CEAC]爱立信纹理压缩格式 2（RGB8 变体），它是 ETC1 的后续版本，可压缩 RGB888 数据。

注意：创建 ImageTexture 时，会执行 sRGB 到线性色彩空间的转换。

Format FORMAT_ETC2_RGBA8 = 31

ETC2%E5%92%8CEAC]爱立信纹理压缩格式 2（RGBA8 变体），它可以压缩 RGBA8888 数据，完全支持 Alpha。

注意：创建 ImageTexture 时，会执行 sRGB 到线性色彩空间的转换。

Format FORMAT_ETC2_RGB8A1 = 32

ETC2%E5%92%8CEAC]爱立信纹理压缩格式 2（RGB8_PUNCHTHROUGH_ALPHA1 变体），它可以压缩 RGBA 数据，使 Alpha 完全透明或完全不透明。

注意：创建 ImageTexture 时，会执行 sRGB 到线性色彩空间的转换。

Format FORMAT_ETC2_RA_AS_RG = 33

ETC2%E5%92%8CEAC]爱立信纹理压缩格式 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

自适应可伸缩纹理压缩。这实现了 4×4（高质量）模式。

Format FORMAT_ASTC_4x4_HDR = 36

与 FORMAT_ASTC_4x4 相同的格式，但有提示以让 GPU 知道它用于 HDR。

Format FORMAT_ASTC_8x8 = 37

自适应可伸缩纹理压缩。这实现了 8×8（低质量）模式。

Format FORMAT_ASTC_8x8_HDR = 38

与 FORMAT_ASTC_8x8 相同的格式，但有提示以让 GPU 知道它用于 HDR。

Format FORMAT_MAX = 39

代表 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

执行 Lanczos 插值。这是最慢的图像调整大小模式，但通常可以提供最佳效果，尤其是在缩小图像时。

---

enum AlphaMode: 🔗

AlphaMode ALPHA_NONE = 0

图片没有 Alpha 通道。

AlphaMode ALPHA_BIT = 1

图像将 Alpha 存储在单个 bit 中。

AlphaMode ALPHA_BLEND = 2

图像使用 Alpha。

---

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

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

将 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, astc_format: ASTCFormat = 0) 🔗

压缩图像以减少内存的使用。当图像被压缩时，不能直接访问像素数据。如果选择的压缩模式不可用，则返回错误。

source 参数有助于为 DXT 和 ETC2 格式选择最佳压缩方法。对于 ASTC 压缩，它会被忽略。

对于 ASTC 压缩，必须提供 astc_format 参数。

---

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

压缩图像以减少内存的使用。当图像被压缩时，不能直接访问像素数据。如果选择的压缩模式不可用，则返回错误。

这是 compress() 的一种替代方法，允许用户提供使用的通道，以便压缩器选择最佳的 DXT 和 ETC2 格式。对于其他格式（非 DXT 或 ETC2），将忽略此参数。

对于 ASTC 压缩，必须提供 astc_format 参数。

---

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().

创建一个给定大小和格式的空图像。请参阅 Format 常量。如果 use_mipmaps 为 true，则为该图像生成 Mipmaps。请参阅 generate_mipmaps()。

---

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

创建一个给定大小和格式的空图像。请参阅 Format 常量。如果 use_mipmaps 为 true，则为该图像生成 Mipmaps。请参阅 generate_mipmaps()。

---

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

创建一个给定大小和格式的新图像。请参阅 Format 常量。用给定的原始数据填充图像。如果 use_mipmaps 为 true，则从 data 为该图像加载 Mipmaps。请参阅 generate_mipmaps()。

---

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

将该图像裁剪成给定的 width 和 height。如果指定的大小大于当前大小，则额外的区域用黑色像素填充。

---

Error decompress() 🔗

如果图像是以一个支持的格式压缩的 VRAM，则解压缩该图像。如果该格式受支持，则返回 @GlobalScope.OK，否则返回 @GlobalScope.ERR_UNAVAILABLE。

注意：可以解压的格式有：DXT、RGTC、BPTC。不支持 ETC1 和 ETC2 格式。

---

AlphaMode detect_alpha() const 🔗

如果图像有 Alpha 值的数据，则返回 ALPHA_BLEND。如果所有的 Alpha 值都存储在一个位上，则返回 ALPHA_BIT。如果没有找到 Alpha 值的数据，则返回 ALPHA_NONE。

---

UsedChannels detect_used_channels(source: CompressSource = 0) const 🔗

返回某个 UsedChannels 常量，表示该图像所使用的颜色通道。如果为压缩图像，则必须使用 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) 🔗

为图像生成多级渐远纹理（Mipmap）。多级渐远纹理是预先计算好的图像的低分辨率副本，如果图像在渲染时需要按比例缩小，则会自动使用这些副本。它们有助于在渲染时提高图像质量和性能。如果图像被压缩，或采用自定义格式，或图像的宽度或高度为 0，则该方法返回错误。在为法线纹理生成多级渐远纹理时启用 renormalize 能够确保得到的所有向量值都是归一化的。

调用 has_mipmaps() 或 get_mipmap_count() 能够检查图像是否使用多级渐远纹理。在已拥有多级渐远纹理的图像上调用 generate_mipmaps() 将替换该图像中已有的多级渐远纹理。

---

PackedByteArray get_data() const 🔗

返回图像原始数据的副本。

---

int get_data_size() const 🔗

返回图像原始数据的大小（单位为字节）。

---

Format get_format() const 🔗

返回图像的格式。参阅 Format 常量。

---

int get_height() const 🔗

返回图像的高度。

---

int get_mipmap_count() const 🔗

返回多级渐远纹理级别数；如果该图像没有多级渐远纹理，则返回 0。该方法不会将最大的主要级别图像计为一个多级渐远纹理级别，因此如果你想将其包括在内，可以在该计数中加 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() 🔗

将整个图像从线性色彩空间转换至 sRGB 色彩空间。仅适用于 FORMAT_RGB8 和 FORMAT_RGBA8 格式的图像。

---

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 选项禁用它。

---

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）时请注意，在加载之前需要对其进行 decompressed。

注意：该方法仅在启用了 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 常量定义。

---

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_exr(path: String, grayscale: bool = false) const 🔗

将图像作为 EXR 文件保存到 path。如果 grayscale 为 true，并且图像只有一个通道，它将被明确地保存为单色而不是一个红色通道。如果 Godot 是在没有 TinyEXR 模块的情况下编译的，则该函数将返回 @GlobalScope.ERR_UNAVAILABLE。

注意：TinyEXR 模块在非编辑器构建中被禁用，这意味着当 save_exr() 从导出的项目中被调用时将返回 @GlobalScope.ERR_UNAVAILABLE。

---

PackedByteArray save_exr_to_buffer(grayscale: bool = false) const 🔗

将图像作为 EXR 文件保存到一个字节数组。如果 grayscale 为 true 并且图像只有一个通道，它将被明确地保存为单色而不是一个红色通道。如果 Godot 是在没有 TinyEXR 模块的情况下编译的，则该函数将返回一个空字节数组。

注意：TinyEXR 模块在非编辑器构建中被禁用，这意味着当 save_exr() 从导出的项目中被调用时将返回一个空字节数组。

---

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 参数。

---

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 参数而不是两个整数参数。

---

void shrink_x2() 🔗

在每个轴上将图像缩小 2 倍（这会将像素数除以 4）。

---

void srgb_to_linear() 🔗

将原始数据从 sRGB 色彩空间转换至线性尺度。仅对格式为 FORMAT_RGB8 和 FORMAT_RGBA8 的图像有效。