MeshTexture 类参考:用网格自绘纹理的 Texture2D 资源
MeshTexture 类参考:用网格自绘纹理的 Texture2D 资源
Godot Engine 的 MeshTexture 是一个特殊的 Texture2D 资源:它不直接保存像素数据,而是把一个 2D 网格(Mesh)渲染成纹理,用于 2D 精灵、粒子、GUI 控件等任何接受纹理的地方。本文将基于官方类参考文档,完整讲解它的继承关系、三个核心属性(base_texture、image_size、mesh)的语义与底层配合方式,并结合仓库中 class_texture2d.rst、class_mesh.rst、class_arraymesh.rst 等文档以及项目实际用法,给出可运行代码与踩坑要点,帮助你判断何时该用它、如何正确配置它。
概述:什么是 MeshTexture
根据 class_meshtexture.rst 中的官方描述:
"Simple texture that uses a mesh to draw itself."
简单来说,MeshTexture 是一种用网格来绘制自身的纹理。它不像 ImageTexture 那样直接承载一张位图,而是把「渲染一个 2D 网格」的结果当作纹理内容来使用。官方文档同时明确指出它的限制:
"It's limited because flags can't be changed and region drawing is not supported."
即两个关键约束:
- flags 无法修改:纹理的绘制标志位不可调整;
- 不支持 region 绘制:无法像常规
Texture2D那样通过draw_rect_region只绘制纹理的局部区域。
因此,凡是依赖「改 flags」「按区域裁剪绘制」的场景,都不适合使用 MeshTexture,而应改用其他 Texture2D 子类。
继承关系
MeshTexture 的完整继承链为(见 class_meshtexture.rst):
MeshTexture < Texture2D < Texture < Resource < RefCounted < Object
这一继承关系意味着:
- 它本身就是一种
Texture2D,凡是可以接受Texture2D的地方(如 Sprite2D、Sprite3D、TextureRect、粒子系统的纹理属性、StandardMaterial3D的 albedo 贴图等)都可以直接传入; - 作为 Resource /
RefCounted,它由引用计数管理生命周期,可保存为.tres资源文件并在多个节点间共享。
Texture2D 是其他纹理资源的基类,本身不能直接使用(见 class_texture2d.rst),而 MeshTexture 正是它的一个具体可实例化实现。
属性详解
MeshTexture 一共只有三个核心属性(属性表见 class_meshtexture.rst),外加一个从 Resource 继承并覆盖的 resource_local_to_scene:
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
base_texture |
Texture2D |
— | 网格绘制时使用的基础纹理 |
image_size |
Vector2 |
Vector2(0, 0) |
图像尺寸,供引用参考 |
mesh |
Mesh |
— | 用于绘制的网格,必须使用 2D 顶点 |
resource_local_to_scene |
bool |
false(覆盖父类) |
是否随场景本地化(继承自 Resource) |
下面逐一展开。
base_texture:网格采样的基础纹理
Sets the base texture that the Mesh will use to draw.
base_texture 就是网格渲染时所采样的那张 Texture2D(属性说明)。在运行时通过 set_base_texture(value) / get_base_texture() 读写。
它既可以是磁盘加载的普通图片(经 @GDScript.load() 得到的 CompressedTexture2D,参见 class_texture2d.rst),也可以是任意 Texture2D 子类——包括程序化纹理、AtlasTexture、甚至另一个 MeshTexture。
image_size:参考用的图像尺寸
Sets the size of the image, needed for reference.
image_size 记录「图像尺寸」,默认 Vector2(0, 0),通过 set_image_size() / get_image_size() 访问(属性说明)。官方文档用词是 "needed for reference"——它本身不直接存储像素,而是为渲染管线提供尺寸参考信息,供 UV 与采样逻辑计算使用。实际配置时,应将其设为网格将要覆盖的纹理区域大小(通常与 base_texture 的像素尺寸一致)。
mesh:负责绘制的 2D 网格
Sets the mesh used to draw. It must be a mesh using 2D vertices.
mesh 指定用于绘制的网格对象,约束是「必须使用 2D 顶点」(属性说明)。这意味着:
- 顶点坐标应以 2D 平面(XY)描述,网格会被当作一个纹理面片进行渲染;
- 一个很自然的起点是 QuadMesh——它是一个没有厚度的正方形 PrimitiveMesh,默认对齐 X/Y 轴,且默认朝向与 billboard 材质配合良好,相当于朝向 Z 的平面(见 class_quadmesh.rst);
- 也可以使用 ArrayMesh 等程序化构建的任意网格,但务必保证顶点布局在 2D 平面内。
class_mesh.rst 指出,Mesh 是一种包含「顶点数组几何体」的 Resource,由若干 surface 组成,每个 surface 拥有独立数组与材质。MeshTexture 内部的绘制就是让这个网格携带 base_texture 进行渲染,并把渲染结果作为纹理内容输出。
属性间的协作关系
把三个属性合起来看,MeshTexture 的工作方式可以这样理解:
mesh定义了几何形状(2D 顶点构成的面片);base_texture提供了采样内容(这张图会贴到网格上);image_size给出尺寸参考,让采样与尺寸换算有据可依。
三者缺一不可地决定了最终纹理长什么样。这也是它区别于普通纹理的本质:纹理的内容由网格的渲染结果动态决定,而不是静态像素。
与 resource_local_to_scene 的交互
MeshTexture 还覆盖了父类 Resource 的 resource_local_to_scene 属性,默认值为 false(见属性表)。resource_local_to_scene 决定资源是否作为场景的本地副本保存(每个场景实例拥有独立副本),由于 MeshTexture 依赖网格与基础纹理等子资源,通常保持默认 false 以便共享即可。
使用限制与适配建议
官方文档明确给出的限制,在实际项目中需要逐一核对:
- flags 不可修改:Texture2D 层面与绘制标志位(如镜像、mipmap 相关标志)相关的能力在 MeshTexture 上不可用;
- region 绘制不支持:
Texture2D基类的draw_rect_region()这类按源矩形绘制局部区域的接口对 MeshTexture 无效(相关方法见 class_texture2d.rst); - 必须使用 2D 顶点网格:传入 3D 网格或顶点不在 2D 平面的网格,渲染结果不符合预期;
image_size默认是零向量:如果不显式设置,尺寸参考可能不正确,应主动赋值。
另外在选用时还可参考 Texture2D 的通用注意点:受图形硬件限制,纹理最大尺寸为 16384×16384 像素,更大的纹理可能导入失败(见 class_texture2d.rst)。
在 Godot 中的典型使用场景
在 Godot 的图形体系中,凡是需要「把一个 2D 网格画成纹理」的地方都是 MeshTexture 的用武之地。典型的场景包括:
- 把程序化/手写网格的渲染结果作为 2D 精灵或 GUI 纹理;
- 让粒子系统、Shader 等对「由网格驱动的动态纹理」进行采样;
- 需要在一个统一的
Texture2D接口后面包装自绘内容的场合(例如自定义控件绘制时复用网格渲染)。
值得注意的是,MeshTexture 在仓库的 GDScript 高亮扩展中被列为内置类名(见 _extensions/gdscript.py),说明它是引擎标准 API 的一部分,可以在 GDScript 中直接以类型名使用。
可运行的 GDScript 示例
综合上面三个属性,一个最小的、可复制的用法如下(把一张 64×64 的贴图,通过 QuadMesh 包装成 MeshTexture):
# 1. 准备基础纹理(也可通过 load("res://icon.png") 加载)
var base_tex: Texture2D = load("res://icon.png")
# 2. 创建一个 2D 网格 —— QuadMesh 是正方形 PrimitiveMesh,
# 默认对齐 X/Y 轴,朝向 Z,非常适合作为纹理面片
var quad := QuadMesh.new()
quad.size = Vector2(64.0, 64.0)
# 3. 组装 MeshTexture
var mesh_tex := MeshTexture.new()
mesh_tex.base_texture = base_tex
mesh_tex.mesh = quad
mesh_tex.image_size = Vector2(64.0, 64.0) # 显式给出尺寸参考
# 4. 作为普通 Texture2D 使用:赋给 Sprite2D 或 TextureRect 等
var sprite := Sprite2D.new()
sprite.texture = mesh_tex
add_child(sprite)
如果想完全程序化,也可以不用 QuadMesh,而是用 ArrayMesh 手工构建 2D 顶点面片——这与 class_arraymesh.rst 中「用数组构建网格」的范例思路一致:构造 PackedVector3Array 顶点、arrays.resize(Mesh.ARRAY_MAX)、写入 Mesh.ARRAY_VERTEX、再 add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, arrays)。关键点是保证所有顶点都在同一 2D 平面内。
工程实践:在项目里如何使用 MeshTexture
在 Godot 编辑器中使用 MeshTexture 的典型流程:
- 在文件系统 Dock 或 Inspector 中新建一个
MeshTexture资源(也可保存为.tres供多处复用); - 在 Mesh 属性中新建或指定一个 2D 网格(如
QuadMesh); - 在 Base Texture 属性中指定要采样的
Texture2D; - 在 Image Size 属性中填入与网格/基础纹理匹配的尺寸;
- 把它赋给任何接受
Texture2D的节点或材质属性。
由于它是 Resource 类型且受引用计数管理,多处共享同一个 MeshTexture 实例不会产生额外内存拷贝;但要注意 image_size 不会自动跟随 base_texture 变化,换贴图后需手动同步。
小结
MeshTexture 是 Godot 中一个「小而专」的 Texture2D 实现:通过 base_texture + mesh + image_size 三个属性,把 2D 网格的渲染结果包装成可复用的纹理资源。它适合「网格即纹理」的场景,但受限于 flags 不可改、region 绘制不支持、网格必须使用 2D 顶点这三条硬性规则。使用时的关键实践是:网格务必保持 2D 平面顶点,image_size 务必显式设置,并在替换 base_texture 时同步尺寸参考。把握住这几点,就能在 2D 精灵、GUI 与粒子等场景中安全地把它当作普通 Texture2D 使用。