Image

Inherits: Resource < Reference < Object

图像数据类型。

描述

本地图像数据类型。包含可转换为 ImageTexture 的图像数据，并提供常用的图像处理方法。 Image 的最大宽度和高度是 MAX_WIDTH 和 MAX_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_rect 从 src 图像与坐标 dest 处的该图像进行 Alpha 混合。

从坐标dst处开始,对src_rect截取区域的src源图像使用mask图像进行Alpha混合到此图像。src和mask都需要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 ( )

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

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

  • void convert ( Format format )

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

  • void copy_from ( Image src )

将src图像复制到此图像。

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

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

  • void crop ( int width, int height )

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

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

如果图像有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。

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

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

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

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

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

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

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

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

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

  1. var img = Image.new()
  2. img.create(img_width, img_height, false, Image.FORMAT_RGBA8)
  3. img.lock()
  4. img.set_pixelv(Vector2(x, y), color) # Works
  5. img.unlock()
  6. img.set_pixelv(Vector2(x, y), color) # Does not have an effect
  • void shrink_x2 ( )

将图像缩小2倍。

  • void srgb_to_linear ( )

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

  • void unlock ( )

解锁数据并防止更改。