Image

Inherits: Resource < Reference < Object

图像数据类型。

描述

本地图像数据类型。包含可转换为 ImageTexture 的图像数据,并提供常用的图像处理方法。 Image 的最大宽度和高度是 MAX_WIDTHMAX_HEIGHT

Image 不能直接分配给对象的 texture 属性,例如 Sprite,必须先手动转换为 ImageTexture

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

属性

Dictionary

data

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

方法

void

blend_rect ( Image src, Rect2 src_rect, Vector2 dst )

void

blend_rect_mask ( Image src, Image mask, Rect2 src_rect, Vector2 dst )

void

blit_rect ( Image src, Rect2 src_rect, Vector2 dst )

void

blit_rect_mask ( Image src, Image mask, Rect2 src_rect, Vector2 dst )

void

bumpmap_to_normalmap ( float bump_scale=1.0 )

void

clear_mipmaps ( )

Error

compress ( CompressMode mode, CompressSource source, float lossy_quality )

void

convert ( Format format )

void

copy_from ( Image src )

void

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

void

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

void

crop ( int width, int height )

Error

decompress ( )

AlphaMode

detect_alpha ( ) const

void

expand_x2_hq2x ( )

void

fill ( Color color )

void

fill_rect ( Rect2 rect, Color color )

void

fix_alpha_edges ( )

void

flip_x ( )

void

flip_y ( )

Error

generate_mipmaps ( bool renormalize=false )

PoolByteArray

get_data ( ) const

Format

get_format ( ) const

int

get_height ( ) const

int

get_mipmap_offset ( int mipmap ) const

Color

get_pixel ( int x, int y ) const

Color

get_pixelv ( Vector2 src ) const

Image

get_rect ( Rect2 rect ) const

Vector2

get_size ( ) const

Rect2

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 ( PoolByteArray buffer )

Error

load_jpg_from_buffer ( PoolByteArray buffer )

Error

load_png_from_buffer ( PoolByteArray buffer )

Error

load_tga_from_buffer ( PoolByteArray buffer )

Error

load_webp_from_buffer ( PoolByteArray buffer )

void

lock ( )

void

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

Error

save_exr ( String path, bool grayscale=false ) const

Error

save_png ( String path ) const

PoolByteArray

save_png_to_buffer ( ) const

void

set_pixel ( int x, int y, Color color )

void

set_pixelv ( Vector2 dst, Color color )

void

shrink_x2 ( )

void

srgb_to_linear ( )

void

unlock ( )

枚举

enum Format:

  • FORMAT_L8 = 0 --- 纹理格式,具有代表亮度的单一8位深度。

  • FORMAT_LA8 = 1 --- OpenGL 纹理格式,具有两个值,亮度和 alpha,每个值以 8 位存储。

  • FORMAT_R8 = 2 --- OpenGL 纹理格式 RED,具有单个分量和 8 位深度。

注意: 当使用 GLES2 后端时,它使用 alpha 通道而不是红色通道进行存储。

  • FORMAT_RG8 = 3 --- OpenGL 纹理格式 RG,具有两个部分,每个部分的位深度为 8。

  • FORMAT_RGB8 = 4 --- OpenGL 纹理格式 RGB 具有三个部分,每个分量部分的位深度为 8。

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

  • FORMAT_RGBA8 = 5 --- OpenGL 纹理格式 RGBA 有四个部分,每个分量部分的位深度为 8。

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

  • FORMAT_RGBA4444 = 6 --- OpenGL 纹理格式 RGBA 有四个部分,每个分量部分的位深度为 4。

  • FORMAT_RGBA5551 = 7 --- OpenGL纹理格式GL_RGB5_A1,其中RGB每个分量的深度为5位,alpha为1位。

  • FORMAT_RF = 8 --- OpenGL 纹理格式 GL_R32F,其中有一个分量,是32 位浮点值。

  • FORMAT_RGF = 9 --- OpenGL 纹理格式 GL_RG32F 这里有两个部分,每个部分是一个 32 位浮点值。

  • FORMAT_RGBF = 10 --- OpenGL纹理格式GL_RGB32F,其中有三个部分,每个部分都是32位浮点值。

  • FORMAT_RGBAF = 11 --- OpenGL纹理格式GL_RGBA32F,其中有四个部分,每个部分都是32位浮点值。

  • FORMAT_RH = 12 --- OpenGL纹理格式GL_R32F,其中有一个分量,即16位 "半精度 "浮点值。

  • FORMAT_RGH = 13 --- OpenGL纹理格式GL_RG32F,其中有两个部分,每个部分都是16位 "半精度 "浮点值。

  • FORMAT_RGBH = 14 --- OpenGL纹理格式GL_RGB32F,其中有三个部分,每个部分都是16位 "半精度 "浮点值。

  • FORMAT_RGBAH = 15 --- OpenGL纹理格式GL_RGBA32F,其中有四个部分,每个都是16位"半精度 "浮点值。

  • FORMAT_RGBE9995 = 16 --- 一种特殊的OpenGL纹理格式,其中三个颜色成分的精度为9位,所有三个成分共享一个5比特位的指数。

  • FORMAT_DXT1 = 17 --- S3TC 纹理格式使用块压缩1,并且是S3TC的最小变化,仅提供1位的alpha和颜色数据 预乘以alpha.

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

  • FORMAT_DXT3 = 18 --- 使用块压缩2的S3TC贴图格式,并且颜色数据被解析为没有与alpha预先相乘.非常适用于具有 半透明和不透明区域之间的清晰的alpha过渡.

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

  • FORMAT_DXT5 = 19 --- S3TC 纹理格式也称为块压缩3或BC3,其中包含64位的alpha通道数据,后跟64位的DXT1编码 颜色数据:颜色数据不会与DXT3预先乘以alpha.与DXT3相比,DXT5对于透明渐变通常会产生更好的结果.

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

  • FORMAT_RGTC_R = 20 --- 使用 红绿贴图压缩的贴图格式,使用与DXT5用于alpha通道相同的压缩算法对红色通道数据进行归一化.

  • FORMAT_RGTC_RG = 21 --- 使用 红绿贴图压缩的贴图格式,使用与DXT5用于alpha的压缩算法相同的红绿数据通道.

  • FORMAT_BPTC_RGBA = 22 --- 使用 BPTC压缩 和无符号归一化RGBA分量的贴图格式.

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

  • FORMAT_BPTC_RGBF = 23 --- 使用 BPTC 压缩和有符号浮点RGB分量的贴图格式.

  • FORMAT_BPTC_RGBFU = 24 --- 使用BPTC 压缩和无符号浮点RGB分量的贴图格式.

  • FORMAT_PVRTC2 = 25 --- PowerVR支持的移动平台上使用的贴图格式,使用2位颜色深度,没有alpha.更多信息可以在 这里找到.

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

  • FORMAT_PVRTC2A = 26 --- 与 PVRTC2相同,但带有alpha组件.

  • FORMAT_PVRTC4 = 27 --- 与 PVRTC2相似,但具有4位色深且没有Alpha通道.

  • FORMAT_PVRTC4A = 28 --- 与 PVRTC4相同,但带有alpha组件.

  • FORMAT_ETC = 29 --- Ericsson纹理压缩格式1,又称 "ETC1",是OpenGL ES图形标准的一部分.这种格式不能存储alpha通道.

  • FORMAT_ETC2_R11 = 30 --- Ericsson纹理压缩格式2 (R11_EACvariant),它提供一个无符号数据通道.

  • FORMAT_ETC2_R11S = 31 --- Ericsson纹理压缩格式2(SIGNED_R11_EACvariant),它提供一个通道的有符号数据.

  • FORMAT_ETC2_RG11 = 32 --- Ericsson纹理压缩格式2(RG11_EAC variant),它提供一个无符号数据通道.

  • FORMAT_ETC2_RG11S = 33 --- Ericsson纹理压缩格式2(SIGNED_RG11_EAC 变体),它提供两个通道的有符号数据。

  • FORMAT_ETC2_RGB8 = 34 --- Ericsson纹理压缩格式2 (RGB8 变体),它是ETC1的后续版本,可压缩RGB888数据.

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

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

  • FORMAT_ETC2_RGB8A1 = 36 --- Ericsson纹理压缩格式2(RGB8_PUNCHTHROUGH_ALPHA1 变体),它可以压缩RGBA数据,使alpha完全透明或完全不透明.

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

  • FORMAT_MAX = 37 --- 表示 Format 枚举的大小。


enum Interpolation:

  • INTERPOLATE_NEAREST = 0 --- 执行最近邻插值.如果调整图像大小,它将被像素化.

  • INTERPOLATE_BILINEAR = 1 --- 执行双线性插值。如果调整图像大小,则图像将模糊。此模式比 INTERPOLATE_CUBIC 更快,但质量较低。

  • INTERPOLATE_CUBIC = 2 --- 执行三次插值.如果调整图像大小,则图像将模糊.与INTERPOLATE_BILINEAR相比,此模式通常会产生更好的结果,但代价是速度较慢.

  • INTERPOLATE_TRILINEAR = 3 --- 在两个最适合的多级渐远纹理级别上分别执行双线性采样,然后在采样结果之间进行线性插值。

它比 INTERPOLATE_BILINEAR 慢,但能产生更高质量的效果,减少锯齿伪影。

如果图像没有多级渐远纹理,它们将被生成并在内部使用,但不会在生成的图像之上生成多级渐远纹理。

注意:如果你打算缩放原始图像的多个副本,最好事先对其调用 generate_mipmaps,以避免在生成它们时反复浪费处理能力。

另一方面,如果图像已经有了多级渐远纹理,其将被使用,并为生成的图像生成新的一组。

  • INTERPOLATE_LANCZOS = 4 --- 执行Lanczos插值.这是最慢的图像调整大小模式,但通常可以提供最佳效果,尤其是在缩小图像时.


enum AlphaMode:

  • ALPHA_NONE = 0 --- 图片没有Alpha通道.

  • ALPHA_BIT = 1 --- 图像将Alpha存储在单个bit中.

  • ALPHA_BLEND = 2 --- 图像使用阿尔法。


enum CompressMode:

  • COMPRESS_S3TC = 0 --- 使用S3TC压缩。

  • COMPRESS_PVRTC2 = 1 --- 使用PVRTC2压缩。

  • COMPRESS_PVRTC4 = 2 --- 使用PVRTC4压缩。

  • COMPRESS_ETC = 3 --- 使用ETC压缩。

  • COMPRESS_ETC2 = 4 --- 使用 ETC2 压缩。


enum CompressSource:

  • COMPRESS_SOURCE_GENERIC = 0 --- 原始纹理(在压缩前)是常规纹理。所有纹理的默认值。

  • COMPRESS_SOURCE_SRGB = 1 --- 原始纹理(在压缩前)使用 sRGB 空间。

  • COMPRESS_SOURCE_NORMAL = 2 --- 原始纹理(在压缩前)是法线纹理(例如,可以压缩为两个通道)。

常量

  • MAX_WIDTH = 16384 --- Image 资源允许的最大宽度。

  • MAX_HEIGHT = 16384 --- Image 资源允许的最大高度。

属性说明

Default

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

以给定的格式保存图像的所有颜色数据。参阅Format常量。

方法说明

src_rectsrc 图像与坐标 dest 处的该图像进行 Alpha 混合。


从坐标dst处开始,对src_rect截取区域的src源图像使用mask图像进行Alpha混合到此图像。srcmask都需要Alpha通道。如果相应的遮罩(mask)像素的Alpha不是0,在坐标dst处的像素和src像素将会混合。src图像和mask图像必须有相同的尺寸,即宽度和高度,但它们可以有不同的格式。


将指定src源图像按dst为起点坐标,以 src_rect 为矩形截取区域复制到此图像中。


将指定src源图像按dst为起点坐标,以 src_rect 为矩形截取区域复制到此图像中。如果对应的mask像素的alpha值不是0,src像素将被复制到dst上。src 图像和 mask ] 图像 必须 具有相同的尺寸(宽度和高度),但它们可以具有不同的格式。


  • void bumpmap_to_normalmap ( float bump_scale=1.0 )

将凹凸贴图转换为法线贴图。凹凸贴图提供每个像素的高度偏移,而法线贴图提供每个像素的法线方向。


  • void clear_mipmaps ( )

删除图像的多级渐远纹理。


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


  • void convert ( Format format )

转换图像的格式。参阅Format常量。


  • void copy_from ( Image src )

src图像复制到此图像。


创建一个给定大小和格式的空图像。见 Format 常量。use_mipmapstrue 时会为这个图像生成多级渐远纹理。请参阅 generate_mipmaps


创建一个给定大小和格式的新图像。参阅 Format 常量。用给定的原始数据填充图像。use_mipmapstrue 时会为该图像从 data 加载多级渐远纹理。请参阅 generate_mipmaps


  • void crop ( int width, int height )

将图像裁剪成给定的widthheight。如果指定的尺寸大于当前尺寸,多余的区域将被填充为黑色像素。


如果图像被压缩,则解压缩图像。如果解压缩功能不可用,则返回错误。


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


  • void expand_x2_hq2x ( )

拉伸图像并将其放大2倍,不进行插值。


  • void fill ( Color color )

Fills the image with color.


Fills rect with color.


  • void fix_alpha_edges ( )

将低透明度(alpha)像素与附近像素混合。


  • void flip_x ( )

水平翻转图像。


  • void flip_y ( )

垂直翻转图像。


  • Error generate_mipmaps ( bool renormalize=false )

为图像生成多级渐远纹理。多级渐远纹理是预先计算好的图像的低分辨率副本,如果图像在渲染时需要缩小,就会自动使用。其有助于提高图像质量和渲染时的性能。如果图像被压缩,或采用自定义格式,或图像的宽度或高度为 0,则此方法返回错误。

注意:多级渐远纹理的生成是在 CPU 上完成的,是单线程的,并且总是在主线程上完成。这意味着在游戏过程中生成多级渐远纹理会导致明显的卡顿,即使从 Thread 调用generate_mipmaps


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


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


  • int get_height ( ) const

返回图像的高度。


  • int get_mipmap_offset ( int mipmap ) const

返回存储在图像 data 字典中索引为 mipmap 的偏移量。


如果图像被锁定,则返回 (x, y) 处像素的颜色。如果图像被解锁,它总是返回 (0, 0, 0, 1.0) 值的 Color。这与 get_pixelv 相同,但有两个整数参数而不是 Vector2 参数。


如果图像已锁定,返回 src 处的像素的颜色。如果图像未被锁定,它总是返回值为 (0, 0, 0, 1.0)Color。这与 get_pixel 相同,只是用一个 Vector2 参数代替了两个整数参数。


返回一个新图像,它是用 rect 所截取图像区域的副本。


返回图像的大小(宽度和高度)。


  • Rect2 get_used_rect ( ) const

返回一个包围图像可见部分的 Rect2 矩形,像素的 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


Loads an image from file path. See Supported image formats for a list of supported image formats and limitations.

Warning: This method should only be used in the editor or in cases when you need to load external images at run-time, such as images located at the user:// directory, and may not work in exported projects.

See also ImageTexture description for usage examples.


从BMP文件的二进制内容中加载图像。

注意: Godot的BMP模块不支持16位像素的图像。只支持1位、4位、8位、24位和32位像素的图像。


从 JPEG 文件的二进制内容加载图像。


从 PNG 文件的二进制内容加载图像。


从 TGA 文件的二进制内容加载图像。


从 WebP 文件的二进制内容加载图像。


  • void lock ( )

锁定数据的读写访问。如果在读或写像素时,图像没有被锁定,则向控制台发送一个错误。


  • void normalmap_to_xy ( )

转换图像的数据以表示 3D 平面上的坐标。当图像表示法线贴图时使用。法线贴图可以在不增加多边形数量的情况下向 3D 表面添加大量细节。


  • void premultiply_alpha ( )

将颜色值与alpha值相乘。一个像素的结果颜色值是(color * alpha)/256


调整图像大小到给定的widthheight。新像素通过Interpolation常数定义的interpolation插值模式计算。


将图像的宽度和高度调整到最接近的2次方。如果squaretrue,那么设置宽度和高度为相同。新像素通过Interpolation常数定义的interpolation插值模式计算。


将标准 RGBE(红绿蓝指数)图像转换为 sRGB 图像。


将图像作为EXR文件保存到path。如果grayscaletrue并且图像只有一个通道,它将被明确地保存为单色而不是红色通道。如果Godot在编译时没有TinyEXR模块,这个函数将返回@GlobalScope.ERR_UNAVAILABLE

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


将图像作为 PNG 文件保存到 path



如果图像被锁定,设置(x, y)处像素的Color。例子:

var img = Image.new()
img.create(img_width, img_height, false, Image.FORMAT_RGBA8)
img.lock()
img.set_pixel(x, y, color) # Works
img.unlock()
img.set_pixel(x, y, color) # Does not have an effect

如果图像被锁定,设置(dst.x, dst.y)处的像素的Color。注意,dst值必须是整数。例:

var img = Image.new()
img.create(img_width, img_height, false, Image.FORMAT_RGBA8)
img.lock()
img.set_pixelv(Vector2(x, y), color) # Works
img.unlock()
img.set_pixelv(Vector2(x, y), color) # Does not have an effect

  • void shrink_x2 ( )

将图像缩小2倍。


  • void srgb_to_linear ( )

将原始数据从 sRGB 色彩空间转换为线性比例。


  • void unlock ( )

解锁数据并防止更改。