文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载导读Texture2DArrayRD是 Godot 引擎中面向RenderingDeviceVulkan 等现代低层图形 API 的抽象层的 2D 纹理数组资源。它的核心作用是把你在RenderingDevice上直接创建的 2D 数组纹理以RID标识包装成一个可被材质、网格等高层资源直接引用的Texture资源。读完本文你将掌握其继承关系、texture_rd_rid属性的用法、从RDTextureFormat到texture_create()的完整创建流程以及它与常规Texture2DArray的取舍差异。类概览与继承关系Texture2DArrayRD的定义位于 classes/class_texture2darrayrd.rst完整继承链如下Texture2DArrayRD TextureLayeredRD # RD 系列分层纹理的抽象基类 TextureLayered # 多图层纹理的抽象基类 Texture Resource RefCounted Object从文档描述看它是「绑定到 RenderingDevice 上创建的纹理对象的 2D 纹理数组」让你能够把直接在RenderingDevice上生成的 2D 数组纹理用作材质、网格等的纹理。官方文档同时给出了一条明确的注意事项Texture2DArrayRD 面向 RenderingDevice 的低层使用场景绝大多数情况下应使用 Texture2DArray 替代。这意味着它是一个「桥接型」工具类服务于需要直连 GPU 资源的渲染管线而非日常资源导入路径。在TextureLayeredRD的继承体系中与它并列的还有两个兄弟类TextureCubemapRDCubemap 纹理与TextureCubemapArrayRDCubemap 数组纹理三者共享同一套基于 RID 的访问机制。核心基类 TextureLayeredRD 与 texture_rd_rid 属性Texture2DArrayRD本身不定义任何新的属性或方法全部能力来自其直接基类 TextureLayeredRD。该基类是「RD 分层纹理类型的抽象基类」不能直接使用但包含访问所有派生资源类型所需的函数。官方文档注明它同样面向RenderingDevice低层使用常规场景请改用TextureLayered。基类只暴露一个属性也是整个 RD 纹理桥接机制的关键属性类型说明texture_rd_ridRID在RenderingDevice上创建的纹理对象的 RID对应存取方法set_texture_rd_rid(value: RID)get_texture_rd_rid() - RID工作机制可以概括为RenderingDevice.texture_create()返回一个指向 GPU 纹理资源的RID通过texture_rd_rid将这个 RID 绑定到Texture2DArrayRD实例上Godot 的材质、网格等渲染管线便可通过该资源间接访问这块 GPU 纹理。从源码结构看TextureLayeredRD的兄弟类TextureCubemapRD采用了完全相同的设计同样仅暴露texture_rd_rid印证了「RID 包装 高层资源桥接」是该系列的统一模式。从 RenderingDevice 创建 2D 纹理数组要获得一个可被Texture2DArrayRD引用的 RID需要走RenderingDevice的完整纹理创建流程。第一步获取 RenderingDevice 实例RenderingDevice是现代低层图形 APIVulkan、Direct3D 12、Metal、WebGPU 等的抽象其类文档位于 classes/class_renderingdevice.rst。获取途径有两种全局设备RenderingServer.get_rendering_device()负责向屏幕绘制Godot 启动时自动创建见 class_renderingserver.rst。局部设备RenderingServer.create_local_rendering_device()用于在独立线程上执行绘制与 GPU 计算不能绘制到屏幕也不能与全局设备共享数据。根据 compute_shaders 教程典型写法是# 创建局部渲染设备 var rd : RenderingServer.create_local_rendering_device()需要特别留意两个限制均来自官方文档原文RenderingDevice在headless 模式或使用Compatibility 渲染方法时不可用使用 OpenGL 渲染驱动或 headless 模式时create_local_rendering_device()始终返回null。第二步配置 RDTextureFormat纹理的创建参数封装在RDTextureFormat对象中见 classes/class_rdtextureformat.rst其属性及默认值如下属性默认值含义width1纹理宽度像素height1纹理高度像素depth1纹理深度2D 纹理恒为1array_layers1图层数量仅对 2D 纹理数组有意义mipmaps1纹理可用的 mipmap 数量format8像素数据格式RenderingDevice.DataFormat枚举texture_type1纹理类型RenderingDevice.TextureType枚举samples0采样时使用的样本数多重采样usage_bits0用途位掩码TextureUsageBits决定纹理可被做什么操作is_discardablefalse内容是否无需跨帧保留仅作为绘制列表目标时相关is_resolve_bufferfalse是否用作 resolve 操作的目标关键点创建 2D 纹理数组时必须将texture_type设为TEXTURE_TYPE_2D_ARRAY值5并通过array_layers指定图层数量。RenderingDevice.TextureType枚举完整定义见 class_renderingdevice.rst如下枚举值值含义TEXTURE_TYPE_1D01D 纹理TEXTURE_TYPE_2D12D 纹理TEXTURE_TYPE_3D23D 纹理TEXTURE_TYPE_CUBE3Cubemap 纹理TEXTURE_TYPE_1D_ARRAY41D 纹理数组TEXTURE_TYPE_2D_ARRAY52D 纹理数组TEXTURE_TYPE_CUBE_ARRAY6Cubemap 纹理数组TEXTURE_TYPE_MAX7枚举大小哨兵值第三步指定 usage_bitsusage_bits是决定纹理用途的位掩码TextureUsageBits见 class_renderingdevice.rst常用位如下位标志值含义TEXTURE_USAGE_SAMPLING_BIT1可被采样作为纹理采样TEXTURE_USAGE_COLOR_ATTACHMENT_BIT2可作为帧缓冲的颜色附件TEXTURE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT4可作为深度/模板附件TEXTURE_USAGE_STORAGE_BIT8可作为 storage image如计算着色器写入TEXTURE_USAGE_STORAGE_ATOMIC_BIT16可作为支持原子操作的 storage imageTEXTURE_USAGE_CPU_READ_BIT32可用texture_get_data()回读数据常驻系统内存TEXTURE_USAGE_CAN_UPDATE_BIT64可用texture_update()更新TEXTURE_USAGE_CAN_COPY_FROM_BIT128可作为复制操作的源TEXTURE_USAGE_CAN_COPY_TO_BIT256可作为复制操作的目标TEXTURE_USAGE_INPUT_ATTACHMENT_BIT512可作为输入附件TEXTURE_USAGE_DEPTH_RESOLVE_ATTACHMENT_BIT4096可作为深度/模板 resolve 附件针对Texture2DArrayRD的典型用途至少要设置TEXTURE_USAGE_SAMPLING_BIT如果后续还要更新纹理数据需追加TEXTURE_USAGE_CAN_UPDATE_BIT如果需要从 GPU 回读结果如计算着色器输出则需追加TEXTURE_USAGE_CPU_READ_BIT。第四步调用 texture_create()RenderingDevice.texture_create()的签名见 class_renderingdevice.rsttexture_create(format: RDTextureFormat, view: RDTextureView, data: Array[PackedByteArray] []) - RID关于data参数官方文档有一个容易踩坑的关键说明对于TEXTURE_TYPE_1D、TEXTURE_TYPE_2D、TEXTURE_TYPE_3D类型data数组只能有一个元素即包含全部纹理数据的单个PackedByteArray对于_ARRAY和_CUBE类型数组长度应与format.array_layers的数量一致。也就是说2D 纹理数组的每一层必须作为独立的PackedByteArray传入data数组长度必须等于array_layers。综合以上步骤一个创建 2D 纹理数组并包装为Texture2DArrayRD的完整流程如下基于官方文档中的 API 签名与 compute_shaders 教程模式组织var rd : RenderingServer.create_local_rendering_device() # 1. 配置纹理格式2D 纹理数组4 层每层一张图 var fmt : RDTextureFormat.new() fmt.texture_type RenderingDevice.TEXTURE_TYPE_2D_ARRAY fmt.width 256 fmt.height 256 fmt.array_layers 4 fmt.mipmaps 1 fmt.format RenderingDevice.DATA_FORMAT_R8G8B8A8_UNORM fmt.usage_bits RenderingDevice.TEXTURE_USAGE_SAMPLING_BIT # 2. 每层准备独立的像素数据此处示意为空数据 var layers: Array[PackedByteArray] [] for i in fmt.array_layers: layers.append(PackedByteArray()) # 实际应填充该层的像素字节 # 3. 在 RenderingDevice 上创建纹理得到 RID var rid : rd.texture_create(fmt, RDTextureView.new(), layers) # 4. 包装为 Texture2DArrayRD 供材质/网格引用 var tex : Texture2DArrayRD.new() tex.texture_rd_rid rid完成上述步骤后tex即可赋值给StandardMaterial3D的albedo_texture、Texture2DArray类型的采样器等位置。纹理数据更新与 GPU 回读Texture2DArrayRD绑定的是 GPU 上的纹理对象数据更新与回读均通过RenderingDevice完成。更新单个图层texture_update()texture_update(texture: RID, layer: int, data: PackedByteArray) - Error见 class_renderingdevice.rst它会原地替换已有纹理数据要求新数据与原有纹理具有相同的尺寸和格式。官方文档给出三条重要约束更新后的数据必须与原纹理尺寸、格式一致在绘制列表或计算列表创建期间禁止更新纹理纹理必须携带TEXTURE_USAGE_CAN_UPDATE_BIT位才可更新。# 更新第 2 层的数据示例 var new_data : PackedByteArray() # 实际为尺寸/格式匹配的像素字节 rd.texture_update(rid, 1, new_data)从 GPU 回读texture_get_data() 与异步版本texture_get_data(texture: RID, layer: int) - PackedByteArray同步回读官方文档明确警告该方法会阻塞 GPU 直到数据取回texture_get_data_async(texture: RID, layer: int, callback: Callable) - Error异步版本RenderingDevice 会在若干帧后携带请求时刻的纹理数据调用callback性能更优。如果希望回读更快创建纹理时应附带TEXTURE_USAGE_CPU_READ_BIT因为该位使纹理常驻系统内存。资源清理与生命周期管理RenderingDevice是低层 API 抽象所有创建的 GPU 资源都必须显式释放。texture_create()返回 RID 后官方文档特别提醒用完你的 RID 后应使用 RenderingDevice 的free_rid()方法释放该 RID。free_rid(rid: RID)的定义见 class_renderingdevice.rst。正确的生命周期应该是RenderingDevice创建 RID → 赋值给Texture2DArrayRD.texture_rd_rid使用 → 不再需要时调用rd.free_rid(rid)释放。这与 Godot 高层Resource的自动引用计数机制不同属于典型的低层资源管理模式务必与纹理的创建一一配对避免 GPU 资源泄漏。Texture2DArray 与 Texture2DArrayRD 如何选择两者名字相近但定位截然不同官方文档给出了明确指引。常规方案Texture2DArray见 classes/class_texture2darray.rst。它由多个独立Image组成每个图像尺寸与 mipmap 级别相同与Texture3D不同它不支持图像间的三线性插值无混合与AtlasTexture不同它的所有图像相互独立处理mipmap 链按层单独生成。可通过编辑器导入预设生成或从代码调用ImageTextureLayered.create_from_images()创建也可由ResourceLoader.load()加载。日常资源管理、序列化、编辑器中可见的场景都应走这条路。低层方案Texture2DArrayRD。它没有内置的数据存储只是 GPU 纹理 RID 的「包装器」无法从磁盘资源直接加载必须在运行时配合RenderingDevice手动创建、更新与释放。适合以下场景在计算着色器中生成或修改纹理数据后需要把结果交给材质使用官方推荐的 Compute Texture demo 即属此类教程框架参见 compute_shaders.rst需要对接外部 Vulkan 等低层 API 创建的纹理texture_create_from_extension()可包装外部VkImage需要精细控制usage_bits、mipmap 层级、图层切片等底层细节如texture_create_shared_from_slice()的layers参数只对 2D 纹理数组等多层纹理有意义见 class_renderingdevice.rst。从TextureLayered基类见 classes/class_texturelayered.rst的角度看两者都满足「所有图层图像尺寸与 mipmap 数一致」这一分层纹理前提区别只在于数据来源一个是常规图像数据一个是 GPU 设备侧资源。使用注意事项小结适用渲染后端RenderingDevice在 headless 模式与 Compatibility 渲染方法下不可用OpenGL 驱动下create_local_rendering_device()返回null层级概念2D 纹理数组的「层」对应RDTextureFormat.array_layerstexture_create()的data数组长度必须等于层数texture_update()/texture_get_data()也按层索引访问用法标志采样、更新、回读分别依赖TEXTURE_USAGE_SAMPLING_BIT、TEXTURE_USAGE_CAN_UPDATE_BIT、TEXTURE_USAGE_CPU_READ_BIT缺失对应位会导致相应操作失败手动释放texture_rd_rid指向的 RID 必须通过rd.free_rid()显式释放不会随RefCounted自动回收默认选择非低层定制场景一律优先使用Texture2DArray其导入、加载、编辑器支持更完善。需要进一步深入时可对照阅读 class_renderingdevice.rsttexture_create/texture_update/texture_get_data等全部低层 API、class_rdtextureformat.rst纹理格式参数、class_texturelayeredrd.rsttexture_rd_rid属性以及 compute_shaders.rst完整的 RenderingDevice 计算管线实践。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot RenderingDevice 纹理格式完全指南RDTextureFormat 属性、枚举与创建流程详解Godot RenderingDevice 纹理格式完全指南RDTextureFormat 属性、枚举与创建流程详解 导读 本文以 Godot 官方文档 R文档教程游戏开发Godot 4 RenderingDevice 纹理视图RDTextureView详解格式覆盖与通道重映射实战Godot 4 RenderingDevice 纹理视图RDTextureView详解格式覆盖与通道重映射实战 导读 RDTextureView 是 Go文档教程游戏开发Godot 分层纹理导入器 ResourceImporterLayeredTexture 指南Texture3D、Cubemap 与纹理数组的导入与压缩配置详解Godot 分层纹理导入器 ResourceImporterLayeredTexture 指南Texture3D、Cubemap 与纹理数组的导入与压缩配置详文档教程游戏开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
