Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
Image¶
继承： Resource < RefCounted < Object
图像数据类型。
描述¶
本机图像数据类型。包含可以被转换为 ImageTexture 的图像数据，并提供常用的图像处理方法。Image 的最大宽度和高度为 MAX_WIDTH 和 MAX_HEIGHT。
Image 不能被直接分配给对象的纹理属性（例如 Sprite2D.texture），必须先手动转换为 ImageTexture。
注意：由于图形硬件限制，最大图像大小为 16384×16384 像素。较大的图像可能无法导入。
教程¶
属性¶
|
方法¶
枚举¶
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
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
Format FORMAT_DXT5_RA_AS_RG = 34
Format FORMAT_ASTC_4x4 = 35
自适应可伸缩纹理压缩。这实现了 4x4（高质量）模式。
Format FORMAT_ASTC_4x4_HDR = 36
与 FORMAT_ASTC_4x4 相同的格式，但有提示以让 GPU 知道它用于 HDR。
Format FORMAT_ASTC_8x8 = 37
自适应可伸缩纹理压缩。这实现了 8x8（低质量）模式。
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
UsedChannels USED_CHANNELS_R = 2
UsedChannels USED_CHANNELS_RG = 3
UsedChannels USED_CHANNELS_RGB = 4
UsedChannels USED_CHANNELS_RGBA = 5
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
表示应该使用高质量 4x4 ASTC 压缩格式的提示。
ASTCFormat ASTC_FORMAT_8x8 = 1
表示应该使用低质量 8x8 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 ( float brightness, float contrast, float saturation )
目前没有这个方法的描述。请帮我们贡献一个！
void blend_rect ( Image src, Rect2i src_rect, Vector2i dst )
将 src 图像上的 src_rect 与该图像的坐标 dst 处进行 Alpha 混合，将根据两个图像的边界进行裁剪。该图像和 src 图像必须具有相同的格式。具有非正大小的 src_rect 将被视为空。
void blend_rect_mask ( Image src, Image mask, Rect2i src_rect, Vector2i dst )
使用遮罩图 mask，将源图像 src 中的 src_rect 区域的图像，Alpha 混合到本图像从坐标 dst 起的区域，会根据两者的图像区域进行裁剪。src 和 mask 都需要有 Alpha 通道。如果遮罩图 mask 上某个像素的 Alpha 值非 0，则相应的 dst 的像素和 src 的像素将混合。这张图像和 src 图像的格式必须一致。src 图像和 mask 图像的大小（宽度和高度）必须相同，格式可以不同。src_rect 的大小如果非正，则会作为空矩形处理。
void blit_rect ( Image src, Rect2i src_rect, Vector2i dst )
将 src 图像上的 src_rect 复制到该图像的坐标 dst 处，并根据两个图像边界进行裁剪。该图像和 src 图像必须具有相同的格式。具有非正大小的 src_rect 将被视为空矩形。
void blit_rect_mask ( Image src, Image mask, Rect2i src_rect, Vector2i dst )
将源图像 src 上的矩形区域 src_rect 复制到本图像从坐标 dst 起的区域，会根据两者的图像区域进行裁剪。如果遮罩图 mask 上某个像素的 Alpha 值非 0，就会把 src 上对应的像素复制到 dst 上。这张图像和 src 图像的格式必须一致。src 图像和 mask 图像的大小（宽度和高度）必须相同，格式可以不同。src_rect 的大小如果非正，则会作为空矩形处理。
void bump_map_to_normal_map ( float bump_scale=1.0 )
将凹凸贴图转换为法线贴图。凹凸贴图提供每个像素的高度偏移，而法线贴图提供每个像素的法线方向。
void clear_mipmaps ( )
删除图像的多级渐远纹理。
Error compress ( CompressMode mode, CompressSource source=0, ASTCFormat astc_format=0 )
压缩图像以减少内存的使用。当图像被压缩时，不能直接访问像素数据。如果选择的压缩模式不可用，则返回错误。
source 参数有助于为 DXT 和 ETC2 格式选择最佳压缩方法。对于 ASTC 压缩，它会被忽略。
对于 ASTC 压缩，必须提供 astc_format 参数。
Error compress_from_channels ( CompressMode mode, UsedChannels channels, ASTCFormat astc_format=0 )
压缩图像以减少内存的使用。当图像被压缩时，不能直接访问像素数据。如果选择的压缩模式不可用，则返回错误。
这是 compress 的一种替代方法，允许用户提供使用的通道，以便压缩器选择最佳的 DXT 和 ETC2 格式。对于其他格式（非 DXT 或 ETC2），将忽略此参数。
对于 ASTC 压缩，必须提供 astc_format 参数。
Dictionary compute_image_metrics ( Image compared_image, bool use_luma )
在当前图像和被比较图像上，计算图像指标。
该字典包含 max、mean、mean_squared、root_mean_squared 和 peak_snr。
void convert ( Format format )
转换图像的格式。请参阅 Format 常量。
void copy_from ( Image src )
将源图像 src 复制到本图像。
Image create ( int width, int height, bool use_mipmaps, Format format ) static
创建一个给定大小和格式的空图像。请参阅 Format 常量。如果 use_mipmaps 为 true，则为该图像生成 Mipmaps。请参阅 generate_mipmaps。
Image create_from_data ( int width, int height, bool use_mipmaps, Format format, PackedByteArray data ) static
创建一个给定大小和格式的新图像。请参阅 Format 常量。用给定的原始数据填充图像。如果 use_mipmaps 为 true，则从 data 为该图像加载 Mipmaps。请参阅 generate_mipmaps。
void crop ( int width, int height )
将该图像裁剪成给定的 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 ( CompressSource source=0 ) const
目前没有这个方法的描述。请帮我们贡献一个！
void fill ( Color color )
使用颜色 color 填充图像。
void fill_rect ( Rect2i rect, Color color )
使用颜色 color 填充矩形 rect。
void fix_alpha_edges ( )
将 Alpha 较低的像素与附近像素混合。
void flip_x ( )
水平翻转图像。
void flip_y ( )
垂直翻转图像。
Error generate_mipmaps ( bool renormalize=false )
为图像生成多级渐远纹理（Mipmap）。多级渐远纹理是预先计算好的图像的低分辨率副本，如果图像在渲染时需要按比例缩小，则会自动使用这些副本。它们有助于在渲染时提高图像质量和性能。如果图像被压缩，或采用自定义格式，或图像的宽度或高度为 0，则该方法返回错误。在为法线纹理生成多级渐远纹理时启用 renormalize 能够确保得到的所有向量值都是归一化的。
调用 has_mipmaps 或 get_mipmap_count 能够检查图像是否使用多级渐远纹理。在已拥有多级渐远纹理的图像上调用 generate_mipmaps 将替换该图像中已有的多级渐远纹理。
PackedByteArray get_data ( ) const
返回图像原始数据的副本。
Format get_format ( ) const
返回图像的格式。参阅 Format 常量。
int get_height ( ) const
返回图像的高度。
int get_mipmap_count ( ) const
返回多级渐远纹理级别数；如果该图像没有多级渐远纹理，则返回 0。该方法不会将最大的主要级别图像计为一个多级渐远纹理级别，因此如果你想将其包括在内，可以在该计数中加 1。
int get_mipmap_offset ( int mipmap ) const
返回存储在图像的 data 字典中的索引为 mipmap 的多级渐远纹理的偏移量。
Color get_pixel ( int x, int y ) const
返回 (x, y) 处的像素的颜色。
这与 get_pixelv 相同，但使用两个整数参数而不是一个 Vector2i 参数。
Color get_pixelv ( Vector2i point ) const
返回 point 处像素的颜色。
这与 get_pixel 相同，只是用一个 Vector2i 参数代替了两个整数参数。
Image get_region ( Rect2i region ) 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。
从文件 path 加载图像。有关支持的图像格式的列表和限制，请参阅支持的图像格式。
警告：该方法只能用于编辑器，或需要在运行时加载外部图像的情况，例如位于 user:// 目录的图像，并且可能不适用于导出的项目。
另请参阅 ImageTexture 说明，以获取使用示例。
Error load_bmp_from_buffer ( PackedByteArray buffer )
从 BMP 文件的二进制内容加载图像。
注意：Godot 的 BMP 模块不支持每像素 16 位的图像。仅支持每像素 1 位、4 位、8 位、24 位和 32 位的图