必须通过 Objective-C++（.mm 文件）桥接或封装为 C 风格接口供 C++ 调用；不可在纯 .cpp 中导入 Metal 头文件；MTL 对象须由 ARC 管理，C++ 层仅持句柄；buffer 访问需同步与内存对齐。
如何在 macOS/iOS 上用 C++ 调用 Metal API
Metal 本身是 Objective-C/Swift API，C++ 无法直接调用 MTLDevice 或 MTLCommandQueue 这类类实例。必须通过 Objective-C++（.mm 文件）桥接，或封装成 C 风格接口供 C++ 消费。
常见错误是试图在纯 .cpp 文件里 #import <Metal/Metal.h> —— 编译器会报 expected a type 或 unknown type name 'id'，因为 C++ 不认识 Objective-C 的类型系统。
- 把所有含 Metal 头文件、创建
MTLDevice、MTLBuffer的代码放到.mm文件中 - 对外暴露纯 C 函数（如
metal_create_device()、metal_submit_render_command()），参数用void*或整数句柄，避免泄漏 ObjC 类型 - 在 C++ 侧只 include 自己定义的
metal_c_api.h，不碰任何MTL*名字
为什么不能直接用 C++ RAII 管理 MTL 对象
因为 MTLBuffer、MTLTexture 等是 Objective-C 对象，其生命周期由 ARC（自动引用计数）管理，不是 C++ 析构函数能控制的。你写一个 class MetalBuffer { ~MetalBuffer() { [m_buf release]; } } 是错的——ARC 下 release 手动调用会破坏引用计数，导致崩溃或提前释放。
正确做法是：在 .mm 层用 __bridge_transfer 或 __bridge_retained 显式交接所有权，并依赖 ARC 自动回收；C++ 层只负责持有句柄（如 uint64_t buffer_id）或 void* 指针，不尝试析构。
立即学习“C++免费学习笔记（深入）”；
- 在 .mm 中创建对象后，用
CFAutorelease或返回__bridge_retained指针给 C++，并在 C++ 销毁时调用metal_destroy_buffer(void* buf)（该函数内部做CFRelease） - 不要在 C++ 构造/析构中调用
[obj retain]/[obj release] - 注意 iOS 上
MTLTexture有iosGPUFamilyXXX兼容性限制，不同机型支持的纹理格式不同，硬编码MTLPixelFormatRGBA8Unorm在旧设备上可能返回 nil
render command encoder 提交后立即 map buffer 会失败
典型错误现象：buffer.contents 返回 nullptr，或读到全零数据，即使刚用 replaceRegion 写入过。这是因为 Metal 命令是异步执行的，CPU 不知道 GPU 是否已结束对该 buffer 的读写。
解决路径只有两条：等 GPU 完成（低效），或用 MTLHeap + MTLResourceStorageModeShared + MTLResourceHazardTrackingModeTracked 配合 didCompleteWithTimestamp: 回调判断时机。
- 对频繁 CPU-GPU 交互的 buffer（如 uniform 数据），优先用
MTLResourceStorageModeShared并确保 device 支持（supportsFamily(MTLGPUFamilyApple7)） - 避免在
commit后立刻map；改用waitUntilCompleted（仅调试用，性能极差）或监听MTLCommandBuffer的 completion handler - macOS 上可用
dispatch_semaphore_t+addCompletedHandler:实现同步，iOS 上推荐用MTLFence（iOS 13+）跨 encoder 协调
std::vector 直接传给 MTLBuffer contents 不安全
很多人写 auto* ptr = static_cast<float>(buf->contents()); std::copy(v.begin(), v.end(), ptr);</float>，结果偶发崩溃或渲染异常。根本原因是：MTLBuffer 的 contents() 返回地址不保证与 CPU 缓存一致，且未对齐、未按 Metal 要求 padding（如 float4 数组需 16 字节对齐）。
正确方式是：用 replaceRegion:withBytes:，或预分配 MTLResourceStorageModeManaged buffer 并显式 didModifyRange:。
- 永远不要假设
contents()返回的内存可直接 reinterpret_cast —— 先检查isCpuCacheCoherent，false 就必须用replaceRegion - struct 传入 shader 前，用
alignas(16)修饰，且字段顺序严格匹配[[buffer(0)]] struct {...}的 layout - macOS 上
MTLResourceStorageModeSharedbuffer 可能被 GPU 乱序写入，需在 shader 中加threadgroup_barrier(mem_flags::mem_threadgroup)配合
最易被忽略的是 Metal 的 memory barrier 语义和 CPU cache coherency 模式绑定极紧——同一段代码在 M1 Mac 上跑得通，在 A14 iPhone 上可能因 cache line 刷新策略不同而失效。
