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_WIDTHMAX_HEIGHT

Image 不能被直接分配给对象的纹理属性(例如 Sprite2D.texture),必须先手动转换为 ImageTexture

注意:由于图形硬件限制,最大图像大小为 16384×16384 像素。较大的图像可能无法导入。

教程

属性

Dictionary

data

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

方法

void

adjust_bcs ( float brightness, float contrast, float saturation )

void

blend_rect ( Image src, Rect2i src_rect, Vector2i dst )

void

blend_rect_mask ( Image src, Image mask, Rect2i src_rect, Vector2i dst )

void

blit_rect ( Image src, Rect2i src_rect, Vector2i dst )

void

blit_rect_mask ( Image src, Image mask, Rect2i src_rect, Vector2i dst )

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 )

Error

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

Dictionary

compute_image_metrics ( Image compared_image, bool use_luma )

void

convert ( Format format )

void

copy_from ( Image src )

Image

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

Image

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

void

crop ( int width, int height )

Error

decompress ( )

AlphaMode

detect_alpha ( ) const

UsedChannels

detect_used_channels ( CompressSource source=0 ) const

void

fill ( Color color )

void

fill_rect ( Rect2i rect, Color color )

void

fix_alpha_edges ( )

void

flip_x ( )

void

flip_y ( )

Error

generate_mipmaps ( bool renormalize=false )

PackedByteArray

get_data ( ) const

Format

get_format ( ) const

int

get_height ( ) const

int

get_mipmap_count ( ) const

int

get_mipmap_offset ( int mipmap ) const

Color

get_pixel ( int x, int y ) const

Color

get_pixelv ( Vector2i point ) const

Image

get_region ( Rect2i region ) 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

Error

load ( String path )

Error

load_bmp_from_buffer ( PackedByteArray buffer )

Image

load_from_file ( String path ) static

Error

load_jpg_from_buffer ( PackedByteArray buffer )

Error

load_ktx_from_buffer ( PackedByteArray buffer )

Error

load_png_from_buffer ( PackedByteArray buffer )

Error

load_svg_from_buffer ( PackedByteArray buffer, float scale=1.0 )

Error

load_svg_from_string ( String svg_str, float scale=1.0 )

Error

load_tga_from_buffer ( PackedByteArray buffer )

Error

load_webp_from_buffer ( PackedByteArray buffer )

void

normal_map_to_xy ( )

void

premultiply_alpha ( )

void

resize ( int width, int height, Interpolation interpolation=1 )

void

resize_to_po2 ( bool square=false, Interpolation interpolation=1 )

Image

rgbe_to_srgb ( )

void

rotate_90 ( ClockDirection direction )

void

rotate_180 ( )

Error

save_exr ( String path, bool grayscale=false ) const

PackedByteArray

save_exr_to_buffer ( bool grayscale=false ) const

Error

save_jpg ( String path, float quality=0.75 ) const

PackedByteArray

save_jpg_to_buffer ( float quality=0.75 ) const

Error

save_png ( String path ) const

PackedByteArray

save_png_to_buffer ( ) const

Error

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

PackedByteArray

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

void

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

void

set_pixel ( int x, int y, Color color )

void

set_pixelv ( Vector2i point, 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]爱立信纹理压缩格式 2R11_EAC 变体),它提供一个无符号数据通道。

Format FORMAT_ETC2_R11S = 27

ETC2%E5%92%8CEAC]爱立信纹理压缩格式 2SIGNED_R11_EAC 变体),它提供一个有符号数据通道。

Format FORMAT_ETC2_RG11 = 28

ETC2%E5%92%8CEAC]爱立信纹理压缩格式 2RG11_EAC 变体),它提供一个无符号数据通道。

Format FORMAT_ETC2_RG11S = 29

ETC2%E5%92%8CEAC]爱立信纹理压缩格式 2SIGNED_RG11_EAC 变体),它提供两个有符号数据通道。

Format FORMAT_ETC2_RGB8 = 30

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

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

Format FORMAT_ETC2_RGBA8 = 31

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

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

Format FORMAT_ETC2_RGB8A1 = 32

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

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

Format FORMAT_ETC2_RA_AS_RG = 33

ETC2%E5%92%8CEAC]爱立信纹理压缩格式 2RGBA8 变体),能够压缩 RA 数据,将其解释为两个通道(红和绿)。另见 FORMAT_ETC2_RGBA8

Format FORMAT_DXT5_RA_AS_RG = 34

S3TC 纹理格式,也叫 Block Compression 3、BC3。能够压缩 RA 数据并将其解释为两个通道(红和绿)。另见 FORMAT_DXT5

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

该图像使用两个通道,分别表示亮度和 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

表示应该使用高质量 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 )

使用 brightness 调整图像的亮度,使用 contrast 调整图像的对比度,使用 saturation 调整图像的饱和度。对压缩图像无效(见 is_compressed)。


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 起的区域,会根据两者的图像区域进行裁剪。srcmask 都需要有 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 )

在当前图像和被比较图像上,计算图像指标。

该字典包含 maxmeanmean_squaredroot_mean_squaredpeak_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_mipmapstrue,则为该图像生成 Mipmaps。请参阅 generate_mipmaps


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

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


void crop ( int width, int height )

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


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

返回某个 UsedChannels 常量,表示该图像所使用的颜色通道。如果为压缩图像,则必须使用 source 指定原始图像的属性。


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