Chapter 92: Metal Architecture

Metal Architecture 要解决的核心问题，是把 Apple 平台上一帧图像从 CPU 侧对象构建到 GPU 侧执行的路径讲清楚。读完本章后，读者应能定位一帧 Metal 渲染里 MTLDevice、MTLCommandQueue、MTLCommandBuffer、MTLRenderPipelineState、render pass descriptor、drawable 和资源同步各自承担的责任，并能把黑屏、格式不匹配、资源复用冲突和提交延迟放回具体对象排查。

本章以一个最小三角形 frame 作为贯穿材料：窗口或视图提供一张可呈现的 drawable texture，CPU 创建命令缓冲，render encoder 绑定 pipeline state、vertex buffer 和 render target，GPU 执行 draw，最后把 drawable 交给显示系统。这个例子规模小，但覆盖 Metal 架构中最稳定的一条主路径。

Metal 的公开定位可以从 Apple Developer 的 Metal 页面 观察：它是面向 Apple 平台的图形与计算 API，强调低开销、对 GPU 任务的直接控制、Apple silicon 集成、调试和性能分析工具。本文不把 Metal 当作单纯语法集合，而是把它看成一个 frame contract：CPU 准备对象与状态，command buffer 记录工作，GPU 按队列顺序执行，资源状态和同步策略决定这帧是否稳定。

本文采用 Metal 4 时代的术语边界说明架构，但示例集中在长期稳定的 Metal 基础对象上：device、command queue、command buffer、render command encoder、pipeline state、buffer、texture、sampler、drawable。后续涉及 mesh shader、ray tracing、MetalFX 或 machine learning command 的能力，都建立在同一套提交和资源模型之上。

92.1 Apple Metal 的整体设计与定位

Metal 的工作定义是：Apple 平台上的显式图形与计算 API，负责让应用用对象化方式描述 GPU 工作，并把这些工作提交到 Apple GPU 或受支持的图形设备执行。它的位置在应用和驱动之间，向上连接 Swift、Objective-C、C++、Metal Shading Language 与引擎渲染层，向下连接 GPU 队列、内存、shader 编译、render target 和显示系统。

从一帧三角形看，Metal 架构可以压缩成六个角色。MTLDevice 表示当前可用 GPU 设备和能力入口；MTLCommandQueue 负责创建按顺序提交的 command buffer；MTLCommandBuffer 是一次 GPU 工作批次；render command encoder 把 draw、资源绑定和 pipeline state 写入 command buffer；MTLRenderPipelineState 是预先编译好的渲染状态组合；drawable texture 是最终可呈现的 render target。

下面的流程图只覆盖最小图形路径，暂不展开 compute pass、blit pass、多队列和离屏渲染。它的目标是让读者先建立对象顺序。

这条路径说明 Metal 的“显式”主要体现在 CPU 侧对象组装和提交顺序上。应用需要知道本帧使用哪张 render target、哪套 pipeline state、哪些 buffer 和 texture、什么时候提交、什么时候复用资源。驱动仍会管理硬件细节，例如具体调度、缓存、tile memory 和底层 hazard 处理，但应用对 frame 结构的责任比 OpenGL 时代更清晰。

Metal 的平台定位还包含两个 Apple 生态特征。第一，MTKView 和 CAMetalLayer 把 drawable 直接接入 UIKit、AppKit、SwiftUI 容器或自定义 layer；这让渲染输出和系统合成路径距离很近。第二，Apple silicon 上常见统一内存模型会减少 CPU 和 GPU 之间的显式复制路径，但缓冲区何时被 CPU 写入、何时被 GPU 读取、何时可以复用，仍然是同步问题。

在工程上，Metal Architecture 的主判断是：一帧 Metal 稳定运行，依赖对象生命周期、pipeline state 匹配、render pass 描述、资源绑定和同步顺序共同成立。单独看 shader 语法或单独看 device 创建，都不足以解释真实帧里的黑屏、闪烁、GPU hang 或 frame pacing 波动。

92.2 Metal 与其他 API 的异同对比

比较 Metal、Vulkan 和 Direct3D 12 时，应使用同一组维度：设备选择、命令录制、pipeline state、资源绑定、render target 描述、同步和平台集成。这样可以把差异落到一帧渲染的对象路径上，让 API 名称回到具体 frame 行为中。

维度	Metal	Vulkan	Direct3D 12
设备入口	MTLDevice 代表 GPU 能力入口	instance、physical device、logical device 分层更细	adapter、device 分层，常配合 DXGI
命令批次	command queue 创建 command buffer，encoder 写入命令	command pool 分配 command buffer，显式 recording 与 submit	command allocator 与 command list 分离，queue 负责执行
Pipeline state	MTLRenderPipelineState 预编译 shader 与 render target 契约	graphics pipeline 固化大量状态，pipeline layout 绑定 descriptor set 结构	PSO 固化 shader、input layout、blend、depth、RTV format 等
资源绑定	直接 set buffer/texture/sampler，也可用 argument buffer	descriptor set、descriptor pool、pipeline layout 显式组织	descriptor heap、root signature、descriptor table 显式组织
Render target	render pass descriptor 描述 attachment、load/store action 和 texture	render pass 或 dynamic rendering 描述 attachment 与 layout	RTV/DSV descriptor 与 resource state 共同描述输出目标
同步表达	command buffer 顺序、fence、event、resource usage 和 CPU/GPU inflight 管理	semaphore、fence、barrier、image layout、access mask 颗粒度更细	fence、resource barrier、queue、descriptor 生命周期边界更显式
平台边界	深度绑定 Apple 平台、工具链和显示系统	跨平台，显式复杂度高	以 Windows 和 Xbox 生态为中心

Metal 与 Vulkan 的共同点是都鼓励应用在提交前整理 GPU 工作。两者都要求开发者提前构建 pipeline，显式安排 command buffer，清楚知道资源如何进入 shader。差异在于 Vulkan 暴露了更多跨厂商硬件和驱动边界，例如 image layout、access mask、queue family ownership 和 descriptor pool；Metal 用更贴近 Apple 平台的对象模型吸收了一部分低层细节，把重点放在 device、encoder、resource option、storage mode、render pass descriptor 和工具链验证上。

Metal 与 Direct3D 12 的共同点是 pipeline state object 的思想很接近。Direct3D 12 的 PSO 会把 shader bytecode、input layout、blend、rasterizer、depth/stencil、render target format 和 sample count 组合起来；Metal 的 render pipeline descriptor 也会把 vertex function、fragment function、vertex descriptor、color attachment format、depth/stencil format 和 sample count 组合成 MTLRenderPipelineState。这两个 API 都把“draw 时临时拼状态”的空间压缩到 pipeline 创建阶段，从而让 draw call 执行时更可预测。

资源绑定是 Metal 最容易被 Vulkan 或 Direct3D 12 使用者误判的地方。Metal 基础写法可以在 encoder 上直接调用 setVertexBuffer、setFragmentTexture、setFragmentSamplerState，这让小项目的绑定代码更短。大型引擎仍需要按 frame、pass、material、object 分层组织绑定频率，使用 argument buffer 或资源表抽象减少频繁绑定开销。表面 API 短，并不意味着资源生命周期、绑定一致性和多帧复用问题消失。

同步表达也体现了 Metal 的平台取舍。Vulkan 和 Direct3D 12 常把资源状态转换写成显式 barrier；Metal 更强调 command buffer 内部顺序、encoder 边界、resource usage 声明、fence/event 和 storage mode 的组合。对于一个三角形 frame，开发者通常先遇到的是 CPU 写入 vertex buffer 后 GPU 还在读取的问题；解决顺序是先做多帧 ring buffer，再检查 command buffer 完成信号，最后才分析跨 encoder 或跨 queue 的 fence/event 需求。

工具证据也要按 API 生态区分。Vulkan 常见入口是 RenderDoc、vendor profiler 和 validation layer；Direct3D 12 常见入口是 PIX；Metal 常见入口是 Xcode GPU Frame Capture、Metal debugger、Metal Performance HUD 和 Instruments 的 Metal System Trace。工具名称不同，但它们回答的问题一致：本帧提交了哪些 draw、绑定了哪些资源、pipeline state 是否匹配、GPU 时间落在哪个 pass、CPU 是否过早等待 GPU。

92.3 Metal Render Pipeline State 结构解析

MTLRenderPipelineState 的工作定义是：由 MTLRenderPipelineDescriptor 创建出的不可变渲染管线状态对象，用来保证一次 draw 的 shader、顶点输入、render target 格式、混合、采样数和深度模板格式形成一致契约。它同时覆盖 shader、顶点输入和 render target 契约，是 draw call 进入 render encoder 前必须稳定下来的状态组合。

最小三角形的 pipeline state 至少需要四类输入。第一类是 shader function，通常包含 vertex function 和 fragment function；第二类是 vertex descriptor，用来说明 vertex buffer 的 stride、attribute format、offset 和 buffer index；第三类是 attachment format，例如 color attachment 的 pixel format，以及需要时的 depth/stencil pixel format；第四类是 raster 输出相关配置，例如 sample count 和 blending。

下面是一段简化 Swift 代码，省略 view 创建和错误处理，只展示 pipeline state 创建时哪些字段会形成契约。

let library = device.makeDefaultLibrary()
let vertexFunction = library?.makeFunction(name: "triangleVertex")
let fragmentFunction = library?.makeFunction(name: "triangleFragment")

let vertexDescriptor = MTLVertexDescriptor()
vertexDescriptor.attributes[0].format = .float2
vertexDescriptor.attributes[0].offset = 0
vertexDescriptor.attributes[0].bufferIndex = 0
vertexDescriptor.layouts[0].stride = MemoryLayout<Float>.stride * 2

let pipelineDescriptor = MTLRenderPipelineDescriptor()
pipelineDescriptor.vertexFunction = vertexFunction
pipelineDescriptor.fragmentFunction = fragmentFunction
pipelineDescriptor.vertexDescriptor = vertexDescriptor
pipelineDescriptor.colorAttachments[0].pixelFormat = view.colorPixelFormat
pipelineDescriptor.sampleCount = view.sampleCount

let pipelineState = try device.makeRenderPipelineState(descriptor: pipelineDescriptor)

这段代码证明 pipeline state 是创建阶段完成校验和打包的状态契约。triangleVertex 的输入 attribute 必须和 vertex descriptor 对齐；fragment function 的输出必须能写入 color attachment；view.colorPixelFormat 必须和实际 drawable texture 的格式一致；sample count 必须和 render pass 中 attachment 的采样设置一致。任何一项错位，都可能表现为 pipeline 创建失败、validation 报错、输出为空或采样结果异常。

Pipeline state 的不可变性服务两个目标。第一，驱动可以在创建阶段完成 shader 编译、格式检查和硬件状态打包；第二，draw 阶段可以只绑定一个已验证对象，减少每次 draw 重新解释状态的成本。这个设计和 Vulkan graphics pipeline、Direct3D 12 PSO 的思路一致，只是 Metal descriptor 的字段更贴近 Apple API 对象。

Depth/stencil state 在 Metal 中通常由 MTLDepthStencilDescriptor 创建为 MTLDepthStencilState，再在 encoder 上绑定。它没有完全并入 render pipeline state，但 pipeline descriptor 仍需要知道 depth/stencil attachment 的 pixel format。原因很直接：shader 输出、深度测试和 render target 格式共同决定 GPU 如何写入 attachment；部分动态状态可以在 encoder 上切换，但 attachment 格式这类影响底层管线编译的字段必须提前固定。

一个稳定的 pipeline cache key 至少包含 shader function 名称或编译变体、vertex descriptor 摘要、color/depth/stencil pixel format、sample count、blend state 和需要的 function constant。引擎层如果只用材质名作为 key，换一个 HDR format 或 MSAA sample count 就可能复用错误 pipeline。排查这类问题时，先比较 render pass descriptor 的 attachment，再比较 pipeline descriptor 中对应字段，最后检查 shader function signature。

在 Xcode GPU Frame Capture 中，pipeline state 相关证据通常落在 draw call 的 state 面板：当前 pipeline、vertex function、fragment function、buffer binding、texture binding、render target format 和 depth/stencil state。看到黑屏时，先确认 draw 是否存在，再确认 pipeline 是否绑定，再确认 render target format 与 pipeline format 对齐；这个顺序比直接改 shader 更稳定。

92.4 Metal Device Command Buffer Render Pass and Resource Setup

Metal 的最小 frame setup 由五个对象串起来：device 提供创建能力，command queue 生产 command buffer，drawable 提供当前可呈现 texture，render pass descriptor 描述如何读写 attachment，encoder 把 draw call 和资源绑定写入 command buffer。理解这条链，才能判断一帧图像到底卡在对象创建、状态绑定、命令提交还是呈现阶段。

MTLDevice 是资源和 pipeline 的创建入口。buffer、texture、sampler、library、pipeline state、heap、command queue 都从 device 或 device 派生对象创建。实际工程中，device 还承担 feature 查询和 limits 判断入口；例如纹理格式支持、argument buffer 能力、family 支持和最大线程组限制，都应在初始化阶段集中整理成 renderer profile。

MTLCommandQueue 表示提交顺序。一个 queue 创建多个 command buffer，command buffer 按提交顺序进入 GPU 执行。小型渲染器通常一个 graphics queue 就足够；更复杂的场景会把 blit、compute、render 和 present 拆成不同批次。即使只有一个 queue，也需要把每帧 command buffer 的生命周期和资源复用绑定起来。

MTLCommandBuffer 是一批 GPU 工作的容器。它可以包含 render encoder、compute encoder 和 blit encoder。encoder 的边界有实际意义：render encoder 描述 render pass 内的 draw，compute encoder 描述线程组 dispatch，blit encoder 描述 copy、fill、mipmap 或同步类操作。一个 command buffer 内部可以先做资源准备，再做渲染，再 present drawable；多个 command buffer 之间则依赖队列提交顺序、fence/event 或 CPU 等待策略衔接。

Render pass descriptor 是 Metal 中解释输出目标的关键对象。它指定 color attachment、depth attachment、stencil attachment 的 texture、load action、store action、clear color、slice、level 和 resolve texture。最小三角形通常会把 drawable texture 放到 colorAttachments[0].texture，把 load action 设为 clear，把 store action 设为 store，这样 GPU 先清屏，再把 fragment shader 输出写入 drawable。

下面的简化代码展示一帧 draw 的核心顺序。代码省略异常处理、view delegate、shader 源码和资源创建，只表达对象关系。

let drawable = view.currentDrawable
let pass = MTLRenderPassDescriptor()
pass.colorAttachments[0].texture = drawable?.texture
pass.colorAttachments[0].loadAction = .clear
pass.colorAttachments[0].storeAction = .store
pass.colorAttachments[0].clearColor = MTLClearColor(red: 0.02, green: 0.02, blue: 0.04, alpha: 1.0)

let commandBuffer = commandQueue.makeCommandBuffer()
let encoder = commandBuffer?.makeRenderCommandEncoder(descriptor: pass)
encoder?.setRenderPipelineState(pipelineState)
encoder?.setVertexBuffer(vertexBuffer, offset: 0, index: 0)
encoder?.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)
encoder?.endEncoding()
commandBuffer?.present(drawable!)
commandBuffer?.commit()

这段代码的判断顺序很明确。若屏幕没有输出，先检查 drawable 是否有效，再检查 pass 的 color attachment texture 是否来自当前 drawable，然后检查 encoder 是否创建成功，再检查 pipeline state 和 vertex buffer 是否绑定，最后检查 draw 参数是否覆盖三个顶点。每一步都对应一个 Metal 对象，排查应从这些对象的有效性和绑定关系开始。

Resource setup 的核心是把 shader 需要的数据放到正确 stage、正确 index 和正确 lifetime。vertex shader 读取顶点位置时，buffer index 必须和 shader 参数约定一致；fragment shader 读取 texture 时，texture index 和 sampler index 必须一致；uniform buffer 或 constant buffer 更新时，offset 必须满足平台要求的对齐约束。绑定代码很短，但绑定契约跨越 Swift 侧对象、MSL 参数和 pipeline state。

一个简化 MSL shader 可以帮助定位这个契约。下面代码中的 buffer(0) 对应 CPU 侧 setVertexBuffer(..., index: 0)。如果 CPU 把 vertex buffer 绑定到 index 1，vertex shader 会从错误位置读数据。

struct VertexOut {
    float4 position [[position]];
};

vertex VertexOut triangleVertex(const device float2* positions [[buffer(0)]],
                                uint vertexID [[vertex_id]]) {
    VertexOut out;
    out.position = float4(positions[vertexID], 0.0, 1.0);
    return out;
}

fragment float4 triangleFragment() {
    return float4(1.0, 0.7, 0.2, 1.0);
}

Metal 的 frame setup 还有一个常见边界：present 调用放在 command buffer 上，表示当前 command buffer 完成渲染后把 drawable 交给显示系统。present 的时机通常在 encoder 结束后、commit 前设置。commit 只是把工作提交给 GPU 队列；它不代表 GPU 已经完成执行。CPU 如果在 commit 后立刻复用本帧仍被 GPU 读取的 buffer，就会制造跨帧写读冲突。

把这一节落到工程结构上，可以把 renderer 初始化和每帧提交分开。初始化阶段创建 device、queue、library、pipeline state、静态 buffer、sampler 和 depth texture；每帧阶段获取 drawable、更新动态 buffer、创建 pass descriptor、编码 draw、present、commit；帧结束阶段根据 completion handler、semaphore 或 frame index 释放临时资源。这个拆分能让对象生命周期和 GPU 工作边界对齐。

92.5 Metal 资源与同步机制

Metal 资源包括 buffer、texture、sampler、heap 和 acceleration structure 等对象。本章只围绕最小图形路径展开 buffer 和 texture。资源管理要回答三个问题：资源存放在哪里，哪个阶段读取或写入它，CPU 与 GPU 何时可以安全复用它。前两个问题决定绑定和性能，第三个问题决定稳定性。

Buffer 通常承载顶点、索引、uniform、instance data、skinning matrix、indirect argument 或 compute 输出。Texture 通常承载颜色贴图、normal map、depth attachment、shadow map、G-buffer、history buffer 或 drawable。Sampler 描述过滤、寻址和 mipmap 采样方式。Metal 的资源对象和 shader 参数相连，任何资源都应能回答“哪个 encoder 绑定、哪个 shader stage 使用、读写方向是什么、生命周期跨几帧”。

Storage mode 决定资源内存和 CPU/GPU 访问关系。storageModeShared 常用于 CPU 经常更新、GPU 读取的动态数据；storageModePrivate 常用于 GPU 侧长期使用、CPU 不直接访问的纹理或大 buffer；storageModeManaged 主要出现在部分 macOS 场景，需要显式同步 CPU 和 GPU 副本；storageModeMemoryless 常用于 tile-based 渲染中的临时 attachment。不同平台可用模式和性能特征存在差异，工程层应根据 device family 和资源用途选择。

统一内存容易带来一个误判：CPU 能看到同一段内存，不代表 CPU 可以在任意时刻覆盖它。GPU 执行是异步的，command buffer 提交后 CPU 会继续向前运行。若应用每帧写同一个 storageModeShared uniform buffer，而前一帧 GPU 仍在读取它，画面会闪烁、矩阵会跳变，甚至触发 validation 警告。稳定做法是为动态数据使用多帧 ring buffer，并用 inflight 控制保证 CPU 写入的区域已脱离 GPU 使用。

最小同步模型可以从三帧循环开始：准备三个 uniform buffer 区域，frame index 每帧递增，CPU 只写当前区域，GPU 读取提交时绑定的区域；当 inflight 数量达到上限，CPU 等待最早 command buffer 完成。这个模型解决最常见的 CPU 写、GPU 读冲突，也能解释为什么 commit 后立即修改同一 buffer 会产生跨帧不稳定。

Command buffer 的 completion handler、MTLSharedEvent、MTLFence、dispatch semaphore 都可以参与同步，但它们解决的问题层级不同。completion handler 适合知道一批 GPU 工作已经结束；dispatch semaphore 常用于限制 CPU 同时推进的帧数；MTLFence 更适合 GPU 侧 encoder 之间的资源可见性协调；MTLSharedEvent 可用于更细的 CPU/GPU 或跨 queue 时间线协调。选择同步对象前，应先确认冲突发生在 CPU/GPU 之间、同一 command buffer 的 encoder 之间，还是多个 queue 或多个 command buffer 之间。

资源同步还要考虑 attachment 的 load/store 行为。对于 drawable，loadAction = .clear 表示本 pass 开始时用 clear color 初始化 attachment；storeAction = .store 表示 pass 结束后保留结果用于呈现。对于临时 depth、MSAA 或中间纹理，store action 可以影响带宽和 tile memory 写回成本。Apple GPU 常见 tile-based 架构会让 memoryless attachment 和合适的 store action 对带宽更敏感；但具体收益必须用 Xcode GPU 工具看 tile memory、store、bandwidth 或 pass 时间证据。

在调试资源问题时，按四步走。第一，检查资源创建参数：storage mode、usage、pixel format、size、sample count。第二，检查绑定位置：stage、index、offset、array length、sampler。第三，检查写读顺序：CPU 写入、blit 写入、render pass 写入、shader 读取是否在正确 command buffer 或 encoder 顺序内。第四，检查复用时机：本帧临时资源、跨帧动态 buffer、drawable、history texture 是否被过早覆盖。

工具观察应服务这个判断顺序。Xcode GPU Frame Capture 可以查看某个 draw 的 buffer、texture、sampler、pipeline state 和 render target；Metal API validation 可以提示错误绑定、资源用法和生命周期风险；Metal System Trace 可以观察 CPU 提交、GPU 执行、等待和帧节奏。工具输出提供证据，最终结论要回到资源路径：谁写了资源，谁读了资源，读写之间是否有可靠顺序。

本章建立的 Metal Architecture 理解可以收束成一句话：Metal 用对象化 API 把一帧渲染拆成 device 能力、pipeline state 契约、command buffer 执行、render pass 输出和资源同步五条线；稳定的 Metal 工程，需要让这五条线在每个 draw call 上同时对齐。

最小自检任务

你正在调试一个 Metal 三角形程序。程序能创建 MTLDevice 和 MTLCommandQueue，也能进入每帧 draw 函数；清屏颜色有时能显示，但三角形一直没有出现。最近你把 MTKView 的 colorPixelFormat 从 .bgra8Unorm 改成 .rgba16Float，但没有重新整理 pipeline 创建代码。请按本章的对象顺序写出排查步骤，并判断最可能的错误位置。

答案要点

先确认 drawable 有效，并且 render pass descriptor 的 colorAttachments[0].texture 指向当前 drawable texture。若清屏颜色能显示，说明 drawable、render pass attachment、command buffer 提交和 present 路径大概率已经走通，问题应继续定位到 pipeline state、vertex buffer 和 draw 参数。

接着比较 MTKView.colorPixelFormat、drawable texture 的 pixel format、MTLRenderPipelineDescriptor.colorAttachments[0].pixelFormat 三者。最近把 view 改为 .rgba16Float 后，如果 pipeline descriptor 仍使用旧的 .bgra8Unorm，pipeline state 与 render pass 输出契约不一致。最可能的错误位置是 pipeline 创建阶段的 color attachment format 没有同步更新。

然后检查 setRenderPipelineState 是否绑定当前重新创建的 pipeline state，检查 vertex shader 的 buffer(0) 是否对应 CPU 侧 setVertexBuffer(..., index: 0)，再检查 drawPrimitives 的 vertexCount 是否为 3。若 pipeline format 已修正而三角形仍缺失，再继续查 vertex buffer 内容、offset、stride 和 shader position 输出。

最后确认动态 vertex 或 uniform buffer 的复用时机。若程序每帧覆盖同一 buffer，并且 CPU 没有等待相关 command buffer 完成，就可能出现间歇性错误；但在“清屏稳定、改过 colorPixelFormat 后三角形缺失”的条件下，pipeline descriptor 与 render target format 不一致是优先级最高的判断。

本章知识点总结

• Metal 定位：Metal 是 Apple 平台上的显式图形与计算 API，负责把应用描述的 GPU 工作组织成可提交的对象和命令。
• Frame 主线：一帧 Metal 渲染通常从 device、command queue、drawable、render pass descriptor、command buffer、encoder、draw、present、commit 顺序展开。
• 对象责任：MTLDevice 负责能力和资源创建，MTLCommandQueue 负责提交顺序，MTLCommandBuffer 负责承载一批 GPU 工作。
• Encoder 边界：render、compute、blit encoder 分别描述不同类型 GPU 工作，encoder 顺序构成 command buffer 内部的重要执行结构。
• API 对比：Metal、Vulkan 和 Direct3D 12 都强调提前组织 GPU 工作，但资源绑定、同步表达和平台集成边界不同。
• PSO 契约：MTLRenderPipelineState 把 shader、vertex layout、attachment format、sample count 和 blend 等状态组合成 draw call 契约。
• 格式匹配：pipeline descriptor 的 color/depth/stencil format 必须和实际 render pass attachment 对齐，格式错位会直接影响输出稳定性。
• Pass 描述：render pass descriptor 决定本 pass 写入哪些 attachment，以及 load/store action 如何影响清屏、保留结果和带宽。
• 资源绑定：buffer、texture、sampler 的 stage、index、offset 和生命周期必须与 MSL shader 参数保持一致。
• Storage Mode：shared、private、managed、memoryless 反映 CPU/GPU 访问关系和平台内存路径，应按资源用途选择。
• 同步核心：commit 后 CPU 会继续执行，动态 buffer 需要通过 ring buffer、inflight 限制或完成信号控制复用时机。
• 工具证据：Xcode GPU Frame Capture、Metal validation、Performance HUD 和 System Trace 应用于确认 draw 状态、资源绑定、GPU 时间和等待点。
• 排查顺序：黑屏或缺失 draw 应先查 drawable 和 render pass，再查 pipeline state，再查资源绑定，最后查同步和跨帧复用。