文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载RDAttachmentFormat 是 Godot 引擎底层渲染接口 RenderingDevice 中描述帧缓冲附件的核心配置对象用于为离屏渲染、后处理、延迟光照与 VR 多视图渲染声明每个附件的像素格式、多重采样数量与允许的用途。本文以 Godot 官方文档 class_rdattachmentformat.rst 为主体结合仓库内 RenderingDevice 的枚举与帧缓冲方法定义逐项讲解 format、samples、usage_flags 三个属性及配套 API读完即可独立搭建一个可用的自定义帧缓冲渲染管线。一、RDAttachmentFormat 是什么RDAttachmentFormat 是一个继承自 RefCounted进而继承 Object的资源对象专门供 RenderingDevice 使用。它本身不承载图像数据只负责描述一个附件应该如何被创建和访问——包括数据的存储布局format、多重采样级别samples以及该附件可以被哪些操作使用usage_flags。在 Godot 的底层渲染流程中帧缓冲framebuffer由若干个附件attachment组成常见附件包括颜色附件color attachment保存渲染结果的颜色值深度附件depth attachment保存深度值用于遮挡剔除模板附件stencil attachment保存模板值用于局部遮罩输入/解析附件input / resolve attachment用于子通道间传递数据或 MSAA 解析。RDAttachmentFormat 就是这些附件的规格说明书。从源码结构看文档生成工具将 Godot 引擎源码doc/classes/RDAttachmentFormat.xml自动转换为 RST其内容完全对应引擎中RDAttachmentFormat类的公开属性与 setter/getter 方法因此本页的每一项声明都可在引擎公开 API 中直接调用。二、属性总览RDAttachmentFormat 仅包含三个属性官方文档给出的默认值与类型如下属性类型默认值说明formatRenderingDevice.DataFormat36附件的数据格式samplesRenderingDevice.TextureSamples0采样附件的样本数量usage_flagsint位标志0附件的用法标志决定允许对其执行的操作每个属性都提供成对的访问方法set_format()/get_format()、set_samples()/get_samples()、set_usage_flags()/get_usage_flags()。需要注意的是默认值36、0、0是未显式配置时的初始值在实际创建帧缓冲格式前通常需要根据渲染目标重新赋值。三、format决定附件的像素存储格式format属性的类型是 RenderingDevice.DataFormat这是 Godot 对 Vulkan 数据格式VkFormat的完整封装枚举值从0一直延伸到深度/模板格式。文档默认值36对应DATA_FORMAT_R8G8B8A8_UNORM每通道 8 位、红绿蓝透明四通道、归一化normalized的浮点数据格式值域为[0.0, 1.0]。这是最常见的颜色附件格式之一也是许多后处理帧缓冲的默认选择。3.1 常见的颜色附件格式围绕36周边R8G8B8A8 系列在 class_renderingdevice.rst 中定义完整枚举值数值含义DATA_FORMAT_R8G8B8A8_UNORM368 位/通道 RGBA归一化值域[0.0, 1.0]DATA_FORMAT_R8G8B8A8_SNORM378 位/通道有符号 RGBA归一化值域[-1.0, 1.0]DATA_FORMAT_R8G8B8A8_UINT408 位/通道无符号整数 RGBA值域[0, 255]DATA_FORMAT_R8G8B8A8_SINT418 位/通道有符号整数 RGBA值域[-127, 127]DATA_FORMAT_R8G8B8A8_SRGB428 位/通道 RGBA归一化并带非线性 sRGB 编码此外还有通道顺序相反的B8G8R8A8_*系列43–49以及兼容 CPU 端A8B8G8R8内存排布的DATA_FORMAT_A8B8G8R8_UNORM_PACK3250。选择格式时应遵循颜色线性、纹理 sRGB、HDR 用浮点的通用原则归一化格式节省带宽整数格式适合掩码/ID 缓冲浮点格式如DATA_FORMAT_R16G16B16A16_SFLOAT用于 HDR 中间结果。3.2 深度 / 模板附件格式深度与模板格式集中在枚举尾部class_renderingdevice.rst枚举值数值说明DATA_FORMAT_D16_UNORM12316 位归一化深度DATA_FORMAT_X8_D24_UNORM_PACK3212424 位归一化深度 8 位未用DATA_FORMAT_D32_SFLOAT12532 位浮点深度精度最高DATA_FORMAT_S8_UINT126纯 8 位模板DATA_FORMAT_D16_UNORM_S8_UINT12716 位深度 8 位模板DATA_FORMAT_D24_UNORM_S8_UINT12824 位深度 8 位模板桌面端常见折中DATA_FORMAT_D32_SFLOAT_S8_UINT12932 位浮点深度 8 位模板移动端常见在配置深度附件时应把format设为上述深度/模板格式之一同时把usage_flags中加上TEXTURE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT二者缺一不可否则帧缓冲无法正确绑定该附件。四、samples多重采样与 MSAAsamples属性决定附件在渲染时的多重采样数量类型为 RenderingDevice.TextureSamples 枚举默认值0表示每个像素只采样 1 次即关闭 MSAA。官方文档对各取值有明确说明枚举值数值说明TEXTURE_SAMPLES_101 次采样最快但抗锯齿质量最低TEXTURE_SAMPLES_212 次采样TEXTURE_SAMPLES_424 次采样TEXTURE_SAMPLES_838 次采样移动 GPU含 Apple Silicon不支持TEXTURE_SAMPLES_16416 次采样移动 GPU 与许多桌面 GPU 不支持TEXTURE_SAMPLES_32532 次采样大多数 GPU 不支持TEXTURE_SAMPLES_64664 次采样最慢但抗锯齿质量最高大多数 GPU 不支持TEXTURE_SAMPLES_MAX7枚举大小占位不应直接使用从数值可看出该枚举是按采样次数而非二进制位来编码的2次对应14次对应2与 Vulkan 的VkSampleCountFlagBits并非一一映射Godot 会在内部做转换。选择建议颜色附件使用与目标分辨率、性能预算匹配的采样数移动端优先考虑TEXTURE_SAMPLES_1或TEXTURE_SAMPLES_4深度附件若要与颜色附件共同做 MSAA两者的samples必须一致否则渲染器会拒绝绑定高采样数会成倍增加显存带宽与存储占用TEXTURE_SAMPLES_8及以上务必先用texture_is_format_supported_for_usage()做硬件能力探测。五、usage_flags约束附件用途的位标志usage_flags是一个按位组合的整数对应 RenderingDevice.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可被 CPU 通过texture_get_data()读回且始终驻留系统内存TEXTURE_USAGE_CAN_UPDATE_BIT64可通过texture_update()更新TEXTURE_USAGE_CAN_COPY_FROM_BIT128可作为texture_copy()的拷贝源TEXTURE_USAGE_CAN_COPY_TO_BIT256可作为texture_copy()的拷贝目标TEXTURE_USAGE_INPUT_ATTACHMENT_BIT512可作帧缓冲中的输入附件子通道数据传递TEXTURE_USAGE_DEPTH_RESOLVE_ATTACHMENT_BIT4096可作深度/模板解析附件MSAA 解析典型组合示例# 颜色附件既要写入、又要回读还要用于拷贝 usage_flags ( RenderingDevice.TEXTURE_USAGE_COLOR_ATTACHMENT_BIT | RenderingDevice.TEXTURE_USAGE_CPU_READ_BIT | RenderingDevice.TEXTURE_USAGE_CAN_COPY_FROM_BIT ) # 深度附件仅用于深度测试 usage_flags RenderingDevice.TEXTURE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT标志声明得越充分驱动越容易提前优化内存布局但也要避免声明根本不会用到的能力如既不需要 CPU 回读却加上CPU_READ_BIT这会不必要地占用系统内存与带宽。声明顺序本身没有意义usage_flags是纯位掩码。六、把 RDAttachmentFormat 接入 RenderingDeviceRDAttachmentFormat 自身只描述属性真正让它生效的是 RenderingDevice 提供的帧缓冲格式创建方法framebuffer_format_create(attachments, view_count 1)以附件数组创建普通帧缓冲格式返回唯一格式 IDframebuffer_format_create_multipass(attachments, passes, view_count 1)以附件数组加 RDFramebufferPass 数组创建多子通道帧缓冲格式framebuffer_format_create_empty(samples 0)创建不绑定任何附件的空格式。其中view_count 2会启用多视图multiview用于 VR 渲染但需要硬件支持 Vulkan multiview 扩展见 framebuffer_format_create 说明。多子通道场景中RDFramebufferPass 通过color_attachments、depth_attachment、input_attachments、resolve_attachments、preserve_attachments等数组引用附件索引索引-1ATTACHMENT_UNUSED表示该通道不绑定对应附件。6.1 最小可运行示例var rd : RenderingDevice.new() # 1) 描述颜色附件RGBA8关闭 MSAA可写入、可采样、可拷贝 var color_att : RDAttachmentFormat.new() color_att.format RenderingDevice.DATA_FORMAT_R8G8B8A8_UNORM color_att.samples RenderingDevice.TEXTURE_SAMPLES_1 color_att.usage_flags ( RenderingDevice.TEXTURE_USAGE_COLOR_ATTACHMENT_BIT | RenderingDevice.TEXTURE_USAGE_SAMPLING_BIT | RenderingDevice.TEXTURE_USAGE_CAN_COPY_FROM_BIT ) # 2) 描述深度附件24 位深度 8 位模板 var depth_att : RDAttachmentFormat.new() depth_att.format RenderingDevice.DATA_FORMAT_D24_UNORM_S8_UINT depth_att.samples RenderingDevice.TEXTURE_SAMPLES_1 depth_att.usage_flags RenderingDevice.TEXTURE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT # 3) 创建帧缓冲格式并取得唯一 ID var fmt_id : rd.framebuffer_format_create([color_att, depth_att])之后可继续创建对应纹理、调用framebuffer_create()得到帧缓冲 RID并基于该 RID 启动绘制。官方 draw_list_begin 文档给出了完整的绘制骨架var clear_colors PackedColorArray([Color(0, 0, 0, 0), Color(0, 0, 0, 0), Color(0, 0, 0, 0)]) var draw_list rd.draw_list_begin(framebuffers[i], RenderingDevice.CLEAR_COLOR_ALL, clear_colors) rd.draw_list_bind_render_pipeline(draw_list, raster_pipeline) rd.draw_list_bind_uniform_set(draw_list, raster_base_uniform, 0) rd.draw_list_set_push_constant(draw_list, raster_push_constant, raster_push_constant.size()) rd.draw_list_draw(draw_list, false, 1, slice_triangle_count[i] * 3) rd.draw_list_end()6.2 资源生命周期帧缓冲格式 ID 由framebuffer_format_create*系列返回格式 ID 本身无需显式释放而framebuffer_create()返回的 RID 必须在使用完毕后通过 free_rid() 手动释放否则会泄漏资源。文档同时指出framebuffer_create()创建的帧缓冲会在任一绑定纹理被释放时自动随之释放见 framebuffer_create 说明这为简单场景提供了自动清理的兜底路径。七、配套查询与硬件校验 APIRenderingDevice 还提供了与附件格式配套的查询/校验方法用于在运行时验证配置是否合法framebuffer_format_get_texture_samples(format, render_pass 0)查询给定格式 ID 使用的纹理采样数常用于把帧缓冲的格式回读出来核对 MSAA 配置framebuffer_get_format(framebuffer)由帧缓冲 RID 取回其格式 ID且文档保证相同格式会得到唯一 ID无需释放framebuffer_is_valid(framebuffer)判断帧缓冲 RID 是否仍然有效texture_is_format_supported_for_usage(format, usage_flags)在创建附件前探测数据格式 × 用法标志组合在当前设备上是否受支持是高采样数、深度/模板混合格式落地前的必做检查。八、最佳实践小结按用途裁剪 usage_flags只为实际会用到的能力声明标志避免过度声明导致显存与带宽浪费。颜色与深度附件保持 samples 一致开启 MSAA 时所有参与同一帧缓冲的附件采样数应统一并优先选择TEXTURE_SAMPLES_1/TEXTURE_SAMPLES_4以兼容移动端。深度格式先探测后使用D24_UNORM_S8_UINT与D32_SFLOAT_S8_UINT在不同平台的硬件支持不同创建前调用texture_is_format_supported_for_usage()确认。记住手动释放 RIDRenderingDevice 是低层接口不会自动做内存管理free_rid 说明用完framebuffer_create()返回的 RID 必须显式free_rid()。多子通道注意附件索引使用 framebuffer_format_create_multipass 时RDFramebufferPass 中的索引必须与附件数组顺序一致未使用的槽位置-1。RDAttachmentFormat 虽只有三个属性却是连接附件描述与帧缓冲格式之间的关键一环正确配置 format 决定像素布局samples 决定抗锯齿质量usage_flags 决定数据流向。配合 RenderingDevice 的帧缓冲创建与绘制 API即可在 Godot 中构建完整的自定义渲染管线包括后处理、延迟着色与 VR 多视图渲染。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot 渲染帧缓冲缓存 FramebufferCacheRD 完全指南RenderingDevice 多通道帧缓冲的复用与生命周期管理Godot 渲染帧缓冲缓存 FramebufferCacheRD 完全指南RenderingDevice 多通道帧缓冲的复用与生命周期管理 导读 Frameb文档教程游戏开发Godot 4 渲染缓冲区管理RenderSceneBuffersRD 类深度解析与 Compositor 实战指南Godot 4 渲染缓冲区管理RenderSceneBuffersRD 类深度解析与 Compositor 实战指南 RenderSceneBuffersRD文档教程游戏开发如何使用Sokol实现高性能帧缓冲跨平台渲染技术完全指南如何使用Sokol实现高性能帧缓冲跨平台渲染技术完全指南 Sokol是一个轻量级跨平台C语言头文件库提供了简洁而强大的API来处理帧缓冲等高级渲染技术。本文图形学3D渲染游戏开发上一篇英雄联盟智能助手Seraphine让每一场排位赛都占据先机的秘密武器下一篇HsMod55项功能全面解锁打造你的专属炉石传说体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考