Godot 引擎 Texture2D 纹理类完全指南:2D/3D 纹理的加载、绘制与子类体系
Godot 引擎 Texture2D 纹理类完全指南:2D/3D 纹理的加载、绘制与子类体系
Texture2D 是 Godot 引擎中承载 2D/3D 纹理数据的基础资源类,它负责把图像注册到视频硬件(GPU 显存)中,供 3D 模型、2D Sprite2D 和 GUI Control 使用。本篇以官方类参考 classes/class_texture2d.rst 为骨架,结合仓库中 ImageTexture、CompressedTexture2D、AtlasTexture、ViewportTexture 等相关类的文档与 tutorials/assets_pipeline/importing_images.rst 导入指南,系统讲解 Texture2D 的继承体系、虚拟方法契约、全部公开 API、运行时创建纹理的代码路径以及导入压缩的最佳实践。读完本文,你将能够:理解 Texture2D 在引擎渲染管线中的位置;熟练运用 draw / draw_rect / draw_rect_region 绘制纹理;用 ImageTexture 在运行时动态生成与更新纹理;并为 2D/3D 场景选择正确的纹理导入压缩策略。
一、类定位:Texture2D 在引擎资源体系中的位置
1.1 继承关系与核心语义
根据 classes/class_texture2d.rst 的类定义头,Texture2D 的完整继承链为:
Texture2D < Texture < Resource < RefCounted < Object
- Object:所有 Godot 对象的基类;
- RefCounted:引用计数内存管理,纹理资源在不再被引用时自动释放;
- Resource:可保存、可序列化、可被资源加载器管理的资产类型;
- Texture:所有纹理类型的抽象基类(见 classes/class_texture.rst),其下分叉出 Texture2D、Texture3D 与 TextureLayered 三大分支;
- Texture2D:二维纹理的抽象基类,本文主角。
关键语义有两点:其一,纹理的工作原理是把一张图像注册到视频硬件(GPU 显存),之后才能被 3D 模型、2D 精灵(Sprite2D)或 GUI 控件(Control)使用;其二,Texture2D 本身是基类,不能直接实例化使用,必须使用它的某个具体子类。文档同时给出硬件层面的硬性限制:由于图形硬件限制,最大纹理尺寸为 16384×16384 像素,更大的纹理可能导入失败。
1.2 继承自 Texture2D 的完整子类家族
参考文档的 "Inherited By" 列表,Texture2D 在引擎中拥有庞大的子类体系,覆盖了从静态贴图到程序化生成、从运行时截屏到压缩文件加载的全部场景:
| 子类 | 用途定位 |
|---|---|
| ImageTexture | 基于 Image 对象的运行时纹理,可在代码中动态创建/更新 |
| CompressedTexture2D | 从引擎内部 .ctex 文件加载的二维纹理(导入系统产物) |
| AtlasTexture | 从一张大图(atlas)中裁剪出局部区域 |
| ViewportTexture | 把某个 Viewport 的渲染结果作为动态纹理 |
| AnimatedTexture | 帧动画代理纹理(已标记 Deprecated,不推荐新项目使用) |
| CanvasTexture | 带专用 CanvasItem 参数的画布纹理 |
| NoiseTexture2D | 由噪声生成器(FastNoiseLite 等)填充的纹理 |
| GradientTexture1D / GradientTexture2D | 渐变纹理 |
| CurveTexture / CurveXYZTexture | 曲线数据纹理 |
| MeshTexture | 网格渲染结果纹理 |
| CameraTexture | 摄像头图像纹理 |
| ExternalTexture / DrawableTexture2D / StreamedTexture2D / DPITexture / PortableCompressedTexture2D / Texture2DRD | 各自面向视频流、DPI 缩放、RenderingDevice 等特殊场景 |
| PlaceholderTexture2D | 占位纹理,仅在专用服务器模式或缺失子类时使用 |
这些子类共同说明了一个重要事实:Texture2D 是所有二维贴图需求的统一抽象入口,无论是导入资产、程序化生成还是视口回读,最终都收敛到同一个 API 集合上,这正是本文后续要逐个讲解的方法契约。
二、方法总览:Texture2D 的完整公开 API
classes/class_texture2d.rst 的 Methods 表格列出了该类的全部方法,按其职责可分为四组:
绘制组(向 CanvasItem 画布绘制纹理,仅用于 2D 渲染):
_draw(to_canvas_item, pos, modulate, transpose)(虚拟方法)_draw_rect(to_canvas_item, rect, tile, modulate, transpose)(虚拟方法)_draw_rect_region(to_canvas_item, rect, src_rect, modulate, transpose, clip_uv)(虚拟方法)draw(canvas_item, position, modulate, transpose)(公开方法)draw_rect(canvas_item, rect, tile, modulate, transpose)(公开方法)draw_rect_region(canvas_item, rect, src_rect, modulate, transpose, clip_uv)(公开方法)
查询组(读取纹理元数据):
get_width()/get_height()/get_size():返回像素尺寸get_format():返回 Image.Format 枚举中的图像格式get_image():从 GPU 回读一份 Image 副本get_mipmap_count():返回 mipmap 数量has_alpha():是否含 Alpha 通道has_mipmaps():是否含 mipmap
虚拟查询契约组(供子类覆写的 _ 前缀方法,是自定义纹理类型的扩展点):
_get_width()、_get_height()(标有 required 标记,扩展时必须覆写)_get_format()、_get_image()、_get_mipmap_count()、_has_alpha()、_has_mipmaps()、_is_pixel_opaque(x, y)(virtual,通常需要覆写才有实际效果)
资源工具组:
create_placeholder():返回占位版本资源 PlaceholderTexture2D
在查看这些方法时需注意文档中的三个修饰标记(见文件末尾的替换定义):
virtual:该方法通常需要用户覆写才有效果;required:扩展基类时必须覆写的方法(即_get_width与_get_height);const:无副作用,不修改实例成员变量。
三、三种绘制方法:从整图到区域裁剪
绘制是 Texture2D 最核心的运行时能力。文档将绘制方法区分为两个层次:公开的 draw* 方法与子类可覆写的 _draw* 虚拟方法,二者是一一对应的桥接关系——公开方法最终通过虚拟方法完成实际绘制。
3.1 draw:按左上角坐标绘制整张纹理
void draw(canvas_item: RID, position: Vector2, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false) const
canvas_item:目标 CanvasItem 的 RID(RenderingServer 句柄),通常通过canvas_item.get_canvas_item()或RenderingServer.canvas_item_create()获得;position:纹理左上角在画布上的绘制位置;modulate:颜色乘数,默认Color(1, 1, 1, 1)(不调制),可用于整体调色/淡出;transpose:默认false。若为true,则按列主序(column-major)而非行主序绘制,结果是纹理顺时针旋转 90 度。
该方法通过 RenderingServer API 在指定的 CanvasItem 上绘制纹理。
3.2 draw_rect:填充到指定矩形(可平铺)
void draw_rect(canvas_item: RID, rect: Rect2, tile: bool, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false) const
与 draw 的关键差异在于多了 rect 与 tile 两个参数:
rect:纹理要绘制到的目标矩形区域;tile:是否平铺。为false时纹理拉伸填满矩形;为true时按原尺寸重复平铺铺满矩形。
modulate 与 transpose 语义同 draw。
3.3 draw_rect_region:仅绘制纹理的局部区域
void draw_rect_region(canvas_item: RID, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false, clip_uv: bool = true) const
这是三个公开方法中参数最丰富的一个:
src_rect:指定从纹理中取哪一块(源区域,以纹理像素坐标为参考);rect:该块区域绘制到目标画布上的矩形;clip_uv:默认true。为true时,目标矩形超出源区域边界之外的采样会被裁剪,避免从相邻区域"漏色"。
draw_rect_region 是精灵图集、帧动画、九宫格等一切"从一张大图里取小块"场景的底层基础,其语义与后面的 AtlasTexture 一致。
3.4 对应的虚拟方法:自定义纹理的绘制扩展点
与之对应的三个虚拟方法 _draw、_draw_rect、_draw_rect_region 拥有完全一致的参数语义,在"整张 Texture2D 被请求绘制到 CanvasItem 上"时被引擎调用,供子类提供自定义渲染实现。文档特别强调:这一组方法只在 2D 渲染中使用,不参与 3D 渲染。
四、纹理数据查询:尺寸、格式、Alpha 与 Mipmap
4.1 尺寸与格式
get_width()/get_height():返回纹理的像素宽高,均为int;get_size():返回Vector2形式的像素尺寸,等价于Vector2(get_width(), get_height());get_format():返回Image.Format枚举值(如FORMAT_RGB8、FORMAT_RGBA8、HDR 用的FORMAT_RGBH等),用于判断纹理在显存中的实际存储格式。
4.2 get_image:从 GPU 回读像素数据
get_image() 每次调用都会创建并返回一个全新的 Image 副本,其中包含从纹理 GPU 数据拷贝出来的像素内容,返回的 Image 可以被脚本直接访问和修改。文档给出了三条必须注意的约束:
- 如果 Texture2D 无效,返回
null; - 该操作会从 GPU 拉取数据,频繁调用会造成性能问题;
- 尤其不要每帧调用
get_image(),大纹理上更要避免。
也就是说,get_image() 应当用于一次性的数据回读(如导出截图、做一次像素分析、把视口纹理转成 ImageTexture 交给不支持视口纹理的节点),而不是常规渲染路径。
4.3 Alpha 与 Mipmap 状态
has_alpha():返回true表示纹理带 Alpha 通道(对透明贴图、UI 图标有意义);has_mipmaps():返回true表示纹理包含 mipmap 链;get_mipmap_count():返回 mipmap 的数量。例如一张 64×64 且开启 mipmap 生成的纹理会有 6 个 mipmap(32×32、16×16、8×8、4×4、2×2、1×1)。
mipmap 的实际生成与压缩策略不是 Texture2D 类本身决定的,而是在导入阶段由 Import dock 中的选项控制,详见第六节。
五、运行时创建纹理:ImageTexture 的完整工作流
虽然 Texture2D 不能直接实例化,但引擎提供了 ImageTexture 这个具体子类,用于在运行时把一张 Image 变成可显示的纹理。其官方示例给出了最标准的"图片 → 纹理 → 精灵"三步流程:
var image = Image.load_from_file("res://icon.svg")
var texture = ImageTexture.create_from_image(image)
$Sprite2D.texture = texture
5.1 create_from_image:一次性创建
ImageTexture.create_from_image(image) 是静态方法:创建新的 ImageTexture,并从 Image 分配、设置数据。创建完成后即可赋给 Sprite2D、TextureRect 等节点的 texture 属性。
5.2 set_image 与 update 的选择
创建之后,纹理数据可以通过两个方法替换:
set_image(image):重新分配新的显存。当需要改变纹理的参数(格式、尺寸)时使用;update(image):在不改变尺寸、格式和 mipmap 配置的前提下替换数据,因为不重新分配内存,所以性能更好,适合频繁更新(例如每帧刷新动态画面)。
update() 有一个前置条件:纹理必须先用 create_from_image() 创建或用 set_image() 初始化过,且新图像的尺寸、格式、mipmap 配置要与现有纹理一致,否则无法直接更新。
5.3 set_size_override
set_size_override(size: Vector2i) 可以把纹理缩放到指定尺寸,用于在不重新生成 Image 的前提下改变纹理的显示大小。
5.4 加载纹理的正确姿势:load() 优先于 Image.load()
ImageTexture 文档给出了一个重要警告:优先使用 load() 加载已导入的纹理,而不是在运行时用 Image.load() 从文件系统动态加载,因为后者在导出后的项目中可能无法工作:
var texture = load("res://icon.svg")
$Sprite2D.texture = texture
原因在于:图片必须先被导入系统转换为 CompressedTexture2D,之后才能用 load() 加载。如果确实需要像加载普通 Resource 一样加载图片文件,应当把图片导入为 Image 资源,再用 load() 正常加载。这一点可以从 classes/class_@gdscript.rst 中 load() 的说明得到印证:文件必须先在引擎中完成导入,运行时若想加载图片应使用 Image.load(),二者使用场景有明确分工。
反过来,从已导入纹理回读 Image 则用 get_image():
var texture = load("res://icon.svg")
var image = texture.get_image()
六、导入压缩:CompressedTexture2D 与四种压缩模式
6.1 CompressedTexture2D 是什么
CompressedTexture2D 是"从 .ctex 文件加载的二维纹理"。.ctex 是 Godot 引擎内部文件格式,由导入系统处理其他图像格式时生成。它有两个成员:
- 属性
load_path(默认""):指向.ctex文件的路径,配套get_load_path(); - 方法
load(path):从指定路径加载纹理,返回Error枚举。
6.2 五种压缩模式及其实质
CompressedTexture2D 文档列出的五种压缩方式(含无压缩),与 tutorials/assets_pipeline/importing_images.rst 中 "Compress > Mode" 的导入选项一一对应:
- Lossless(无损):存储为无损 WebP 或 PNG,GPU 上不解压。磁盘占用小,显存占用大;
- Lossy(有损):存储为有损 WebP,GPU 上不解压;
- VRAM Compressed:在 GPU 上压缩(S3TC/BPTC/ETC2 等,视平台而定);
- VRAM Uncompressed:GPU 上不压缩,以原始像素存储;
- Basis Universal:编码为可在加载时转码到多数 GPU 压缩格式的格式,文件更小,但压缩慢、质量低于 VRAM Compressed。
只有 VRAM Compressed(及 Basis Universal)真正降低 GPU 显存占用;Lossless 和 Lossy 只减小磁盘体积,纹理发送到 GPU 时仍是未压缩的。此外,VRAM Compressed 还显著缩短加载时间,但会引入明显压缩伪影,官方明确建议用于 3D 渲染而非 2D。
6.3 各压缩模式全面对比
导入指南给出了一张 5×6 的对比表,从磁盘大小、显存占用、性能、画质损失、加载时间五个维度评估:
| 维度 | Lossless | Lossy | VRAM Compressed | VRAM Uncompressed | Basis Universal |
|---|---|---|---|---|---|
| 存储方式 | 无损 WebP/PNG | 有损 WebP | S3TC/BPTC/ETC2(平台相关) | 原始像素 | 转码为 VRAM 压缩格式 |
| 磁盘占用 | 小 | 很小 | 小 | 大 | 很小 |
| 显存占用 | 大 | 大 | 小 | 大 | 小 |
| 性能 | 正常 | 正常 | 快 | 正常 | 快 |
| 画质损失 | 无 | 轻微 | 中等 | 无 | 中等 |
| 加载时间 | 慢 | 慢 | 快 | 正常 | 正常 |
以一张开启 mipmap 的 RGBA8 纹理为例,各尺寸下的显存估算如下(注意:无 Alpha 通道的 RGB8 纹理再省 25%,关闭 mipmap 再省 25%):
| 纹理尺寸 | Lossless | Lossy | VRAM Compressed | VRAM Uncompressed | Basis Universal |
|---|---|---|---|---|---|
| 128×128 | 85 KiB | 85 KiB | 21 KiB | 85 KiB | 21 KiB |
| 256×256 | 341 KiB | 341 KiB | 85 KiB | 341 KiB | 85 KiB |
| 512×512 | 1.33 MiB | 1.33 MiB | 341 KiB | 1.33 MiB | 341 KiB |
| 1024×1024 | 5.33 MiB | 5.33 MiB | 1.33 MiB | 5.33 MiB | 1.33 MiB |
| 2048×2048 | 21.33 MiB | 21.33 MiB | 5.33 MiB | 21.33 MiB | 5.33 MiB |
| 4096×4096 | 85.33 MiB | 85.33 MiB | 21.33 MiB | 85.33 MiB | 21.33 MiB |
表格揭示的规律很直观:分辨率越高,VRAM 压缩的优势越明显。4:1 的压缩比(不透明纹理用 S3TC 可达 6:1)意味着同样的显存预算下,纹理可以在每个轴向上放大一倍;同时 VRAM 压缩还降低了采样纹理所需的内存带宽,对集显和移动平台这类带宽受限场景能直接加速渲染。
6.4 关键导入选项速览
针对 2D/3D 不同使用场景,导入指南给出如下选项指引:
- Compress > Mode:2D 资产默认 Lossless(像素艺术推荐,无伪影);大尺寸 2D 资产可用 Lossy;3D 资产默认 VRAM Compressed;
- Compress > High Quality:开启后桌面用 BPTC(SDR 用 BC7、HDR 用 BC6H)、移动用 ASTC;关闭(默认)则用 S3TC(DXT1/BC1 用于不透明,DXT5/BC3 用于透明或法线贴图)与 ETC2。该选项仅 Forward+ 与 Mobile 渲染器支持,Compatibility 渲染器下始终视为关闭;
- Compress > HDR Compression:仅对
.hdr/.exr生效。Disabled 时转 RGBE9995(每像素 32 位);Opaque Only(默认)仅对不透明 HDR 纹理做 VRAM 压缩;Always 强制压缩并丢弃 Alpha; - Compress > Normal Map:默认 Detect,检测到用作法线贴图时自动切换为 RGTC 压缩并重导入;可强制 Enable/Disable;
- Compress > Channel Pack:sRGB Friendly(默认)禁止使用不支持 sRGB 的 RG 格式;Optimized 允许在不用蓝色通道时使用 RG 格式;
- Mipmaps > Generate:生成缩小版本链。避免远景/缩放下纹理变颗粒状,但显存增加约 33%。3D 建议开启,2D 视项目受益情况而定;
- Mipmaps > Preserve Alpha Test Coverage:解决 Alpha Scissor 材质在 mipmap 后覆盖率下降问题,仅对带 Alpha 的纹理生效;
- Process > Fix Alpha Border:默认开启,为透明↔不透明过渡区域补充同色像素,缓解双线性过滤下的描边效应;
- Process > Premult Alpha:预乘 Alpha,需搭配 CanvasItemMaterial / BaseMaterial3D 的 Premultiplied Alpha 混合模式(或 shader 中
render_mode blend_premul_alpha;)才能正确显示; - Process > Normal Map Invert Y:把 DirectX 风格法线贴图转换为 Godot 要求的 OpenGL 风格(X+、Y+、Z+);
- Process > Size Limit:大于 0 时限制导入尺寸(取较长边),用三次插值缩放,常用于移动/Web 平台 4096 上限限制;
- Detect 3D:纹理被 3D 场景使用时自动开启 mipmap、切换 VRAM Compressed 并自动重导入,输出面板会打印提示。
七、典型子类的运行机制
7.1 AtlasTexture:大图裁剪
AtlasTexture 从一张 atlas 大图中按 region 区域裁剪出局部纹理,另有 margin 可做细微调整。多个 AtlasTexture 可共享同一张 atlas,把大量小纹理打包进一张大图有助于优化显存开销与减少 draw call。其关键属性:
atlas:图集源纹理,可以是任意 Texture2D 子类(甚至另一个 AtlasTexture);region(默认Rect2(0, 0, 0, 0)):裁剪区域,某一维为 0 时该轴取 atlas 尺寸;实际区域会向下取整到整数像素;margin(默认零矩形):区域四周的边距,可用于微调;若设置了尺寸则绘制纹理被缩放到边距内;filter_clip(默认false):为true时裁剪 region 之外的区域,避免周围像素渗色(bleeding)。
使用限制:AtlasTexture 不能放进 AnimatedTexture,也不会在 TextureRect、Sprite2D 等节点中正常平铺——如需平铺应直接修改 region。
7.2 ViewportTexture:把视口变成动态纹理
ViewportTexture 把某个 Viewport 的渲染内容作为动态 Texture2D 提供,可组合 Control、Node2D、Node3D 的渲染结果——例如在 TextureRect 里显示 3D 场景,或把 2D 界面贴到 Sprite3D 上。代码中通过目标视口的 Viewport.get_texture() 获取。注意事项:
- 它始终是场景本地资源(
resource_local_to_scene),场景根未就绪时可能返回错误数据; - 实例化含高分辨率 ViewportTexture 的场景可能引起明显卡顿;
- 视口启用
use_hdr_2d时返回线性编码 HDR 图像,直接上屏会偏暗,可用Image.linear_to_srgb()转换; - Decal、Light3D、PointLight2D 等节点不支持直接使用 ViewportTexture,需用
get_image()+ImageTexture.create_from_image()转换(该转换较慢,不要每帧执行)。
7.3 PlaceholderTexture2D:占位机制
PlaceholderTexture2D 是 create_placeholder() 的产物,在两种情况下被引擎使用:专用服务器模式导出的项目(仅保留尺寸以支持玩法逻辑,大幅缩减 PCK 体积)或子类缺失(不同引擎版本/构建,如模块被禁用)。它不应用作真实渲染纹理,在 shader、材质(如 UV 计算)中不保证正常工作,仅暴露 size 属性。
7.4 程序化生成与视口联动示例
NoiseTexture2D 演示了 Texture2D 子类异步生成的范式——它内部用线程生成数据,因此生成未完成时 get_image() 可能返回 null,需先等待:
var texture = NoiseTexture2D.new()
texture.noise = FastNoiseLite.new()
await texture.changed
var image = texture.get_image()
var data = image.get_data()
这类"等待生成完成再回读数据"的模式,与 Texture2D 查询类 API(get_image、get_format 等)形成了完整的运行时数据流。
八、实战:在自定义绘制中直接使用 Texture2D
Texture2D 的 draw 系列方法面向 RenderingServer 的 RID 句柄,日常开发更常用的是 CanvasItem 的 draw_texture 系列。官方 2D 自定义绘制教程 tutorials/2d/custom_drawing_in_2d.rst 给出了一个完整的可运行示例:
extends Node2D
@export var texture : Texture2D:
set(value):
texture = value
queue_redraw()
func _draw():
draw_texture(texture, Vector2())
C# 版本:
using Godot;
public partial class MyNode2D : Node2D
{
private Texture2D _texture;
[Export]
public Texture2D Texture
{
get { return _texture; }
set { _texture = value; QueueRedraw(); }
}
public override void _Draw()
{
DrawTexture(_texture, new Vector2());
}
}
@export var texture : Texture2D 让纹理可以作为 Inspector 属性在编辑器中拖拽赋值(例如直接拖入默认的 icon.svg),setter 中调用 queue_redraw() 保证纹理变化时立即重绘。这一模式把 Texture2D 作为数据源与自定义绘制逻辑解耦,是 2D 工具、编辑器插件、程序化 UI 的常用写法。
九、最佳实践与性能红线
综合类文档与导入指南,使用 Texture2D 时值得记住以下原则:
- 避免每帧
get_image():该调用从 GPU 回读数据,属于慢操作,应一次性使用或缓存结果; - 优先
load()导入资源,慎用Image.load():前者在导出项目中可靠,后者可能失效;动态图片应导入为 Image 资源后再加载(见 classes/class_imagetexture.rst); - 2D 用 Lossless,3D 用 VRAM Compressed:VRAM 压缩伪影在低分辨率 2D 纹理上尤其明显,官方明确建议避免;像素艺术无论 2D/3D 都应关闭 VRAM 压缩;
- 3D 务必开 mipmap,2D 视需求开启:mipmap 避免远景颗粒感并提升带宽效率,代价是约 33% 的额外显存;
- 监控纹理尺寸上限:硬件限制 16384×16384,移动/Web 通常限 4096×4096,可配合 Process > Size Limit 在导入时约束;
- 图集是 2D 性能关键:用 AtlasTexture(或导入 TextureAtlas)把小纹理打包进大图,减少显存开销与 draw call;
- 区分 set_image 与 update:频繁更新同尺寸纹理用
update()避免反复分配显存(见 classes/class_imagetexture.rst)。
十、小结
Texture2D 是 Godot 一切二维贴图能力的抽象基类:它以"注册到视频硬件"的方式存储图像,通过 draw / draw_rect / draw_rect_region 三个公开方法(及对应的 _draw* 虚拟扩展点)完成 2D 画布绘制,以 get_width / get_height / get_size / get_format / get_image / has_alpha / has_mipmaps / get_mipmap_count 构成完整的元数据查询面。在实际项目中,静态资产走 CompressedTexture2D 导入链路(配以 Lossless / Lossy / VRAM Compressed / VRAM Uncompressed / Basis Universal 五选一的压缩策略),运行时动态纹理走 ImageTexture 创建链路,图集裁剪用 AtlasTexture,视口回读用 ViewportTexture,占位与降级用 PlaceholderTexture2D。理解这套类体系与导入选项,即可在 2D 与 3D 项目中做出正确的纹理方案选择。