Godot 引擎纹理数组详解：Texture2DArray 的创建、导入与着色器采样实战

文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载Texture2DArray 是 Godot Engine 中一种把多张独立 2D 图像打包进单个纹理资源的分层纹理类型常用于骨骼动画纹理、地形多层混合、实例化粒子纹理等需要同时管理大量同类贴图的场景。本文以 Godot 官方文档中的 Texture2DArray 类参考 为骨架结合其基类 ImageTextureLayered、TextureLayered、导入管线文档 importing_images.rst 与着色器文档 shading_language.rst、shader_functions.rst 展开带读者掌握代码创建 → 编辑器导入 → 着色器采样的完整链路。Texture2DArray 是什么定位与继承体系根据类参考文档的定义Texture2DArray是一个由多张相互独立的图像组成的单一纹理资源其中每张图像都必须具有相同的尺寸宽、高和相同的 mipmap 级数。它相当于 GPU 上一整块连续的二维纹理数组2D texture array每一张子图被称为一个layer层。从继承链可以清楚看到它的地位Texture2DArray ImageTextureLayered # 面向内存图像的基类提供 create_from_images / update_layer TextureLayered # 分层纹理基类提供尺寸、层数、格式等查询接口 Texture Resource RefCounted Object这一继承结构在 class_texture2darray.rst 中明确给出。其中 TextureLayered 是抽象基类无法直接实例化但定义了访问所有分层纹理所需的核心方法ImageTextureLayered 则承接了Cubemap、CubemapArray、Texture2DArray三个可直接使用的派生类型的数据创建与更新职责。值得强调的是 TextureLayered 在底层的映射方式文档指出 Godot 内部会将这类文件映射到目标渲染驱动Vulkan、OpenGL3中对应的纹理数组对象并且TextureLayered 资源可以直接通过ResourceLoader.load()加载。这意味着无论是编辑器导入生成的.ctexarray压缩文件还是代码运行时动态构建的数组对渲染层而言都统一抽象为分层纹理。与其他纹理类型的本质区别类参考文档用两段对比把 Texture2DArray 的定位讲得非常清楚这是理解它最关键的切入点。与 Texture3D 的区别没有层间插值Texture2DArray 与 Texture3D 最大的不同在于Texture2DArray 不支持在层与层图像与图像之间做三线性插值trilinear interpolation也就是没有层间混合blending。每一层都是完全独立、可离散寻址的采样器通过显式指定的 layer 索引取值而不会像 3D 纹理那样在 Z 轴上平滑过渡。这正是纹理数组用于动画帧切换材质分层等场景的基础你希望得到的是精确取到第 N 层而不是第 N 层和第 N1 层的渐变结果。与 AtlasTexture 的区别区域尺寸与 mipmap 处理AtlasTexture图集纹理是从一张大纹理中裁剪出某个region区域来绘制的子纹理。与 Texture2DArray 相比差异体现在三点区域尺寸图集中各区域即各张子图的尺寸可以不同而 Texture2DArray 要求所有层尺寸完全一致UV 防串扰图集通常需要给每个区域额外留 padding边距防止 UV 采样时意外映射到相邻区域而纹理数组每一层天然隔离不需要这种人工留白mipmap 链纹理数组中每一层都有自己独立的 mipmap 链由引擎按层分别生成而在图集中做 mipmap 时必须自己在片元着色器里手动处理切片逻辑。类参考原文明确写道In a Texture2DArray, all images are treated separately... Mipmap chains are handled separately for each layer. In an atlas, the slicing has to be done manually in the fragment shader.与 Cubemap / CubemapArray 的关系从继承关系看Cubemap 与 CubemapArray 同属 ImageTextureLayered 的派生类它们只是带立方体贴图专用语义的纹理数组Cubemap 是恰好 6 层每个面一层CubemapArray 是 6 的倍数层每个立方体 6 层。CubemapArray 文档 提到Godot 内部大量使用这类纹理数组例如当项目设置rendering/reflections/sky_reflections/texture_array_reflections为true默认值见 class_projectsettings.rst时天空反射就是以纹理数组形式存储的。Texture2DArray 则是面向普通 2D 图像的通用数组形态。用代码创建 Texture2DArraycreate_from_images 全流程虽然编辑器导入是日常最常用的途径但运行时动态生成纹理数组的能力在很多场合程序化地形、动态贴图集、运行时拼装动画帧同样关键。类参考明确指出要由代码创建 Texture2DArray应在 Texture2DArray 实例上调用基类 ImageTextureLayered 的create_from_images()方法。方法签名与约束Error create_from_images(images: Array[Image])来自 class_imagetexturelayered.rst 的说明给出了三条硬性约束第一张图像决定基准数组的宽度、高度、图像格式format与 mipmap 设置全部以images中的第一张为准其余图像必须一致后续每张图像都必须与第一张具有相同的宽度、高度、图像格式和 mipmap 设置否则创建会失败一张图像对应一个 layer数组中每个Image代表纹理数组的一个层。返回值为Error枚举可用于判断创建是否成功。官方完整示例ImageTextureLayered 文档附带了一段可直接运行的 GDScript 示例完整覆盖生成图像 → 创建数组 → 保存为资源三个步骤# 用不同颜色填充一组 Image。 var images [] const LAYERS 6 for i in LAYERS: var image Image.create_empty(128, 128, false, Image.FORMAT_RGB8) if i % 3 0: image.fill(Color.RED) elif i % 3 1: image.fill(Color.GREEN) else: image.fill(Color.BLUE) images.push_back(image) # 创建并保存一个 2D 纹理数组。图像数组至少要有 1 张 Image。 var texture_2d_array Texture2DArray.new() texture_2d_array.create_from_images(images) ResourceSaver.save(texture_2d_array, res://texture_2d_array.res, ResourceSaver.FLAG_COMPRESS)要点拆解Image.create_empty(width, height, use_mipmaps, format)生成空图像其中 mipmap 标志false表示本示例不生成 mipmapcreate_from_images()在调用后会立刻把数据上传给渲染驱动因此可以直接交给ResourceSaver.save()落盘ResourceSaver.FLAG_COMPRESS让保存结果采用 Godot 内部的压缩格式对应运行时的 CompressedTexture2DArray。同一文档还展示了 Cubemap 与 CubemapArray 的对照写法Cubemap 要求恰好 6 张图像CubemapArray 要求 6 的倍数且顺序均为X, X-, Y, Y-, Z, Z-Godot 坐标系中 Y 为上、Z- 为前。运行时更新单层update_layer除了整体创建基类还提供了单层更新的能力void update_layer(image: Image, layer: int)该方法把指定layer上的现有图像数据替换为新图像。来自 class_imagetexturelayered.rst 的约束包括新图像必须与其余层宽度、高度、图像格式、mipmap 标志完全一致如果传入的格式不受支持引擎会将其解压并转换为相近且受支持的Image.Format更新是立即生效的与当前帧的绘制同步The update is immediate: its synchronized with drawing不需要等下一帧。这意味着你可以把 Texture2DArray 当作一块可部分改写的 GPU 显存来用——例如逐层流式加载 LOD 或动态更新动画帧。通过编辑器导入创建Import dock 导入管线对于美术资产最标准的工作流是在 Godot 编辑器的Import dock导入面板中把图片改为Texture2DArray导入类型。官方导入文档 importing_images.rst 对这类导入类型的定位描述是Texture2DArray把图像导入为 2D 纹理的集合。它与 3D 纹理相似但层与层之间没有插值。内置的 2D/3D 着色器无法直接显示纹理数组因此必须编写自定义着色器2D 的 canvas item shader 或 3D 的 spatial shader来从纹理数组中采样纹理。分层图像的布局约定纹理数组的源图本质是一张把多层图像按网格排布的大图。类参考提到多层图像在默认的垂直导入选项下是自上而下堆叠的第一层在最上方也可以在导入选项中改用水平布局第一层在最左侧。至于每一层内部的像素布局Cubemap 类文档提供了 2×3、3×2、1×6、6×1 四种模板图见 tutorials/assets_pipeline/img/ 下的cubemap_template_*.webp普通 2D 数组则按行/列切片规则拆分即可。关键导入选项在将导入类型切换为 Texture2DArray 后以下导入选项需要特别关注Compress Mode压缩模式——importing_images.rst 列出五种模式及其权衡模式磁盘占用显存占用质量适用场景Lossless小WebP/PNG大GPU 上不压缩无损失2D 资产、像素艺术默认模式Lossy很小WebP大GPU 上不压缩轻微损失大尺寸 2D 资产VRAM Compressed小S3TC/BPTC/ETC2小约 1/41/6中等损失3D 资产的默认模式VRAM Uncompressed大原始像素大无损失无法压缩的浮点格式Basis Universal很小小中等损失需要跨平台转码的极小型文件这张表的详细对照同样收录在 importing_images.rst。只有 VRAM Compressed 会真正降低 GPU 显存占用Lossless/Lossy 只减小磁盘体积同时 VRAM Compressed 还能显著加快加载时间。但要注意它会产生可见压缩伪影官方建议用于 3D 渲染而非 2D。Mipmaps Generate生成 mipmap——importing_images.rst 指出开启后会在导入时生成逐级缩小版本例如 64×64 会生成 6 级 mipmap避免远景采样发灰并提升远距离采样性能代价是显存增加约 33%。由于纹理数组中每一层都有独立的 mipmap 链开启后所有层都会统一生成。Compress Channel Pack通道打包——对于分层纹理Cubemap、CubemapArray、Texture2DArray、Texture3D额外提供Normal Map (RG Channels)选项见 importing_images.rst。它强制所有层以仅保留 R、G 通道的 RG 颜色格式导入配合 RGTC 压缩可以在同样显存下显著保留法线贴图细节仅在 VRAM Compressed 或 Basis Universal 模式下生效。压缩纹理形态CompressedTexture2DArray导入系统把源图转换为 Godot 内部格式后运行时会加载为CompressedTexture2DArray对应.ctexarray文件。其文档 class_compressedtexture2darray.rst 明确列出了该形态支持的压缩方法Lossless、Lossy、VRAM Compressed、VRAM Uncompressed、Basis Universal并重申了关键结论只有 VRAM Compressed 真正降低 GPU 显存且这类纹理加载更快。压缩纹理的基类 CompressedTextureLayered 还提供了load(path)方法与load_path属性支持显式指定加载路径。在着色器中采样纹理数组由于内置材质与内置着色器默认不消费纹理数组实际使用时几乎必然要写自定义着色器。Godot 着色语言为纹理数组提供了专门的采样器类型映射关系在 shading_language.rst 的Godot 类型 ↔ 着色语言类型对照表中给出着色器采样器类型Godot 资源类型读取语义sampler2DArrayTexture2DArray以 float 读取isampler2DArrayTexture2DArray以有符号整数读取usampler2DArrayTexture2DArray以无符号整数读取声明 uniform 与基本采样shader_type spatial; uniform sampler2DArray terrain_layers; void fragment() { // p 的 xy 为 UV 坐标z 为 layer 索引必须显式指定层 vec3 uv_layer vec3(UV, 2.0); vec4 color texture(terrain_layers, uv_layer); ALBEDO color.rgb; }关键点采样二维纹理数组时纹理坐标从 vec2 扩展为 vec3最后一个分量就是 layer 索引。着色器函数文档 shader_functions.rst 对texture()的签名与说明写得非常明确texture(gsampler2DArray s, vec3 p [, float bias])—— 对于非阴影变体数组层array layer来自p的最后一个分量。常用数组采样函数族以下函数都支持sampler2DArray签名与用途来自 shader_functions.rst函数签名用途texturetexture(s, vec3 p [, bias])常规采样可选 LOD 偏移textureLodtextureLod(s, vec3 p, float lod)显式指定 mipmap 级别采样textureGradtextureGrad(s, vec3 p, vec2 dPdx, vec2 dPdy)用自定义导数做 LOD 计算textureSizetextureSize(s, int lod)→ivec3返回数组尺寸含层数第三维texelFetchtexelFetch(s, ivec3 p, int lod)直接按整数像素坐标取纹素不做过滤textureGathertextureGather(s, vec3 p [, comps])取 2×2 纹素用于自实现过滤textureQueryLodtextureQueryLod(s, vec2 p)→vec2查询将被使用的 LODtextureQueryLevelstextureQueryLevels(s)→int查询可访问的 mipmap 级数特别提示文档在textureSize条目下注明这类查询总是执行一次完整的纹理读取应避免频繁调用优先以 uniform 传入尺寸。textureLod的完整定义见 shader_functions.rst它执行显式 LOD 采样将偏导数全部置零δu/δxδv/δxδw/δx0 等适合在需要固定清晰度的场景如 UI 放大、透视校正使用。可视化着色器中的对应节点如果你使用 Visual Shader 而非手写着色器可以直接添加VisualShaderNodeTexture2DArray节点。其文档 class_visualshadernodetexture2darray.rst 说明该节点会被翻译为uniform sampler2DArray并提供texture_array属性绑定源纹理数组当采样源设为 SOURCE_TEXTURE 时生效。需要留意的是自 Godot 4.4 起该属性类型已从Texture2DArray放宽为基类TextureLayered兼容性变更见 upgrading_to_godot_4.4.rst。运行时查询 APITextureLayered 方法族分层纹理基类 TextureLayered 提供了一组只读查询方法无论在 GDScript 还是 C# 中都可以直接使用方法返回值含义get_width()int纹理宽度X 轴像素单位get_height()int纹理高度Y 轴像素单位get_layers()int引用的 Image 总数即层数get_format()Image.Format当前使用的图像格式get_layer_data(layer)Image取回指定层的 Image 数据get_layered_type()LayeredType分层类型见下has_mipmaps()bool各层是否已生成 mipmap其中LayeredType枚举有三个取值定义在 class_texturelayered.rstLAYERED_TYPE_2D_ARRAY 0通用 Texture2DArrayLAYERED_TYPE_CUBEMAP 1Cubemap每个面一个层共 6 层LAYERED_TYPE_CUBEMAP_ARRAY 2CubemapArray每个立方体占 6 层。get_layered_type()决定了数据的访问语义立方体贴图拥有特殊类型。这些查询在 C#/GDScript 侧调用时会通过类内部的_get_*虚方法回调到具体实现如_get_width()、_get_layer_data()等这是引擎为不同分层资源统一提供信息的方式。create_placeholder 与专用服务器导出Texture2DArray 类唯一的自有方法就是Resource create_placeholder() const它创建一个该资源的占位版本PlaceholderTexture2DArray。根据占位类的文档占位纹理出现在两种典型场景专用服务器dedicated server导出当项目以专用服务器模式导出时所有视觉资源都会被占位替换仅保留纹理的尺寸信息因为这些尺寸可能被游戏逻辑依赖用于摆放或定位其他元素从而显著减小 PCK 体积资源类型缺失当使用不同引擎版本或构建如某些模块被禁用导致原类型无法加载时用占位类兜底。导出文档 exporting_projects.rst 也印证了这一点Export as dedicated server会把包括 Texture2DArray 在内的一批视觉资源替换为占位符你可以在导出列表中单独指定希望保留的视觉资源。需要特别强调的是占位纹理不是真正的渲染纹理——官方明确指出它不保证能在着色器或材质中像真实纹理那样工作例如 UV 计算因此只应出现在上述兜底场景中。实战小结与选型建议综合类参考文档、导入管线与着色器文档可以提炼出 Texture2DArray 的完整使用路径资产准备把多张尺寸一致、格式一致、mipmap 策略一致的图像按网格排布成一张源图导入在 Import dock 中把导入类型改为Texture2DArray按需设置压缩模式3D 优先 VRAM Compressed、2D 优先 Lossless、开启 mipmap、必要时使用 Channel Pack 的 Normal Map (RG Channels)运行时代码创建可选用ImageTextureLayered.create_from_images(images)动态构建用update_layer()逐层更新采样编写自定义着色器声明uniform sampler2DArray用texture(s, vec3(uv, layer))采样LOD 控制用textureLod数据查询用get_layers()/get_layer_data()/get_width()/get_height()等接口读取数组信息。选型时抓住两个核心判据需要层间离散寻址且各层尺寸统一时选 Texture2DArray需要层间平滑插值时选 Texture3D需要变尺寸区域复用单张贴图时选 AtlasTexture需要天空盒/环境反射时选 Cubemap 或 CubemapArray。它们共享同一套分层纹理抽象理解 Texture2DArray 的创建与采样机制后其余分层纹理类型即可举一反三。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot CubemapArray 纹理数组完全指南多立方体贴图的高效存储、导入与着色器采样Godot CubemapArray 纹理数组完全指南多立方体贴图的高效存储、导入与着色器采样 CubemapArray 是 Godot Engine 中用于文档教程游戏开发Godot 曲线纹理 CurveTexture 全解析将 Curve 数据烘焙为一维纹理并在着色器中采样Godot 曲线纹理 CurveTexture 全解析将 Curve 数据烘焙为一维纹理并在着色器中采样 CurveTexture 是 Godot 引擎中用于文档教程游戏开发Godot 分层纹理导入器 ResourceImporterLayeredTexture 指南Texture3D、Cubemap 与纹理数组的导入与压缩配置详解Godot 分层纹理导入器 ResourceImporterLayeredTexture 指南Texture3D、Cubemap 与纹理数组的导入与压缩配置详文档教程游戏开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考