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, 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 纹理格式 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

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_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

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

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

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

astc_format 参数仅在使用 ASTC 压缩时才会生效；对于其他格式，它将被忽略。

注意：compress() 仅在编辑器构建中受支持。在导出的项目中运行时，该方法始终返回 @GlobalScope.ERR_UNAVAILABLE。

---

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

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

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

astc_format 参数仅在使用 ASTC 压缩时才会生效；对于其他格式，它将被忽略。

注意：compress_from_channels() 仅在编辑器构建中受支持。在导出的项目中运行时，该方法始终返回 @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) 🔗

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

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

---

PackedByteArray get_data() const 🔗

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

---

int get_data_size() const 🔗

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

---

Format get_format() const 🔗

返回图像的格式。

---

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

---

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）时请注意，在加载之前需要对其进行 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（插值）模式进行计算。

注意： 如果图像的格式为 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 输出的项目的截图时，请对 max_linear_value 使用 Window.get_output_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 输出的项目的截图时，请对 max_linear_value 使用 Window.get_output_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_pixel() 方法返回的颜色与此处设置的颜色完全相同；任何比较操作可能都需要使用近似比较方法，例如 Color.is_equal_approx()。

注意：在灰度图像格式中，仅使用 color 的红色通道（以及相关的 alpha 通道）。绿色和蓝色通道将被忽略。

---

void shrink_x2() 🔗

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

---

void srgb_to_linear() 🔗

使用查找表将非线性 sRGB 编码的原始数据转换为线性编码。仅适用于 FORMAT_RGB8 或 FORMAT_RGBA8 格式的图像。

注意：该方法所需的 8 位格式不适合存储线性编码值；在较暗的颜色值中会丢失大量颜色信息。为了保持图像质量，不应使用该方法。