// IOSPlatform 初始化时注册 CADisplayLink
_displayLink = [CADisplayLink displayLinkWithTarget:self 
                                           selector:@selector(renderScene:)];
[_displayLink addToRunLoop:[NSRunLoop currentRunLoop] 
                   forMode:NSRunLoopCommonModes];

// FrameGraph 编译流程（伪代码）
void FrameGraph::compile() {
    sort();                          // Pass 拓扑排序
    cull();                          // 裁剪无用 Pass
    computeResourceLifetime();       // 计算资源生命周期
    mergePassNodes();                // 合并可合并的 Pass 节点
    computeStoreActionAndMemoryless(); // 计算 Store Action
    generateDevicePasses();          // 生成设备层 Pass 描述
}

// MTLSwapchain::acquire() 核心逻辑
- (void)acquire {
    id<CAMetalDrawable> drawable = [_metalLayer nextDrawable];
    // 将 drawable 封装到内部结构
    _swapchainObject.drawable = drawable;
    _swapchainObject.texture = drawable.texture;
}

id<MTLCommandBuffer> mtlCmdBuf = [_commandQueue commandBuffer];

MTLRenderPassDescriptor* desc = [MTLRenderPassDescriptor renderPassDescriptor];
desc.colorAttachments[0].texture = drawable.texture;
desc.colorAttachments[0].loadAction = MTLLoadActionClear;
desc.colorAttachments[0].storeAction = MTLStoreActionStore;

id<MTLRenderCommandEncoder> encoder = 
    [mtlCmdBuf renderCommandEncoderWithDescriptor:desc];

class CCMTLRenderCommandEncoder {
    // 脏状态标记
    bool _isViewportDirty;
    bool _isScissorDirty;
    bool _isCullModeDirty;
    bool _isDepthStencilStateDirty;
    id<MTLRenderPipelineState> _lastPSO;
    // ... 更多状态缓存
    
    void setRenderPipelineState(id<MTLRenderPipelineState> pso) {
        if (pso == _lastPSO) return;  // 状态未变，跳过
        _lastPSO = pso;
        [_encoder setRenderPipelineState:pso];
    }
};

[encoder drawIndexedPrimitives:MTLPrimitiveTypeTriangle
                    indexCount:indexCount
                     indexType:MTLIndexTypeUInt16
                   indexBuffer:indexBuffer
             indexBufferOffset:0];

[encoder endEncoding];

[mtlCmdBuf presentDrawable:drawable];  // 注册呈现目标
[mtlCmdBuf commit];                     // 提交到 GPU 队列

CCMTLDevice::CCMTLDevice() {
    _api = API::METAL;
    _deviceName = "Metal";

    // 关键差异：Metal 的裁剪空间坐标 Z 范围是 [0, 1]
    // OpenGL 则是 [-1, 1]，投影矩阵需据此调整
    _caps.clipSpaceMinZ = 0.0f;
    _caps.screenSpaceSignY = -1.0f;
    _caps.clipSpaceSignY = 1.0f;
}

bool CCMTLDevice::doInit(const DeviceInfo &info) {
    // 1. 获取系统默认的 Metal 设备
    id<MTLDevice> mtlDevice = MTLCreateSystemDefaultDevice();
    _mtlDevice = mtlDevice;

    // 2. 查询设备名称和特性集
    NSString *deviceName = [mtlDevice name];
    _deviceName = [deviceName UTF8String];
    _mtlFeatureSet = [mtlDevice supportsFamily:MTLGPUFamilyApple7]
        ? MTLGPUFamilyApple7 : MTLGPUFamilyApple6; // ...

    // 3. 创建命令队列
    _mtlCommandQueue = [mtlDevice newCommandQueue];

    // 4. 查询硬件限制
    _maxSamplerUnits = 16;  // Metal 最大采样器数量
    _maxBufferBindingIndex = 30; // Shader 中 buffer 绑定的最大索引

    // 5. 初始化逐帧资源
    for (int i = 0; i < MAX_FRAMES_IN_FLIGHT; i++) {
        _gpuStagingBufferPools[i] =
            ccnew CCMTLGPUStagingBufferPool((id<MTLDevice>)_mtlDevice);
    }
}

MTLCreateSystemDefaultDevice()
    → 查询 GPU 名称 / 特性集 / 能力
    → 创建 newCommandQueue
    → 统计采样器 / buffer 绑定上限
    → 初始化多帧 StagingBufferPool
    → 注册内存告警监听

void CCMTLSwapchain::doInit(const SwapchainInfo &info) {
    void *windowHandle = info.windowHandle;

    // 情况 1：直接传入 CAMetalLayer（纯 Metal 场景）
    if ([((__bridge id)windowHandle) isKindOfClass:[CAMetalLayer class]]) {
        _metalLayer = (__bridge CAMetalLayer *)windowHandle;
    }
    // 情况 2：传入 UIView，通过 +layerClass 获取 CAMetalLayer
    else if ([((__bridge id)windowHandle) isKindOfClass:[UIView class]]) {
        UIView *view = (__bridge UIView *)windowHandle;
        _metalLayer = (CAMetalLayer *)view.layer;
    }
    // 情况 3：传入 CocosView，用 cocosMetalLayer 方法获取
    else {
        _metalLayer = [view cocosMetalLayer];
    }

    // 配置 CAMetalLayer 属性
    _metalLayer.pixelFormat = MTLPixelFormatBGRA8Unorm;
    _metalLayer.framebufferOnly = NO;
    _metalLayer.device = (__bridge id<MTLDevice>)_device->getMTLDevice();
}

void CCMTLSwapchain::acquire() {
    // 从 CAMetalLayer 获取下一帧的 drawable
    id<CAMetalDrawable> drawable = [_metalLayer nextDrawable];

    if (drawable) {
        // 封装到内部结构体，供后续渲染阶段使用
        _gpuSwapchainObj->currentDrawable = drawable;
        _gpuSwapchainObj->mtlTexture = drawable.texture;
        _width = drawable.texture.width;
        _height = drawable.texture.height;
    }
}

CAMetalLayer 内部维护一个 drawable 池（通常 3 个）

    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ Drawable │    │ Drawable │    │ Drawable │
    │    #0    │    │    #1    │    │    #2    │
    │ (GPU 使用) │    │ (可用)    │    │ (可用)    │
    └──────────┘    └──────────┘    └──────────┘
         ↑
    nextDrawable 返回 #1 或 #2

如果所有 drawable 都在 GPU 使用中 → 阻塞等待 → 可能掉帧

void CCMTLSwapchain::resize(uint32_t width, uint32_t height) {
    _metalLayer.drawableSize = CGSizeMake(
        width * _metalLayer.contentsScale,
        height * _metalLayer.contentsScale
    );
}

class CCMTLRenderCommandEncoder {
    // ===== 状态缓存标记 =====
    bool _isViewportSet = false;         // 视口是否已设置
    bool _isScissorRectSet = false;      // 裁剪矩形是否已设置
    bool _isCullModeSet = false;         // 剔除模式是否已设置
    bool _isFrontFacingWinding = false;  // 正面环绕方向
    bool _isTriangleFillModeSet = false; // 三角形填充模式
    bool _isDepthClipModeSet = false;    // 深度裁剪模式
    bool _isDepthBiasSet = false;        // 深度偏移
    bool _isBlendColorSet = false;       // 混合颜色

    // ===== 缓存的上一次状态值 =====
    id<MTLRenderPipelineState> _pipelineState = nil;
    id<MTLDepthStencilState> _depthStencilState = nil;
    MTLCullMode _cullMode = MTLCullModeNone;
    MTLWinding _frontFacingWinding = MTLWindingClockwise;
    Viewport _viewport;
    Rect _scissorRect;

    // ===== 资源绑定缓存（按 slot index 组织）=====
    ccstd::unordered_map<uint32_t, BufferBinding> _vertexBufferMap;
    ccstd::unordered_map<uint32_t, BufferBinding> _fragmentBufferMap;
    ccstd::unordered_map<uint32_t, id<MTLTexture>> _vertexTextureMap;
    ccstd::unordered_map<uint32_t, id<MTLTexture>> _fragmentTextureMap;
    ccstd::unordered_map<uint32_t, id<MTLSamplerState>> _vertexSamplerMap;
    ccstd::unordered_map<uint32_t, id<MTLSamplerState>> _fragmentSamplerMap;
};

void setCullMode(MTLCullMode mode) {
    // 第一步：检查脏标记和值是否相同
    if (_isCullModeSet && (_cullMode == mode))
        return;  // 状态未变，跳过

    // 第二步：更新缓存
    _cullMode = mode;
    _isCullModeSet = true;

    // 第三步：调用 Metal API
    [_mtlEncoder setCullMode:mode];
}

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│ 检查脏标记   │ →   │ 值与上次相同？ │ →   │ 调用 Metal  │
│ 和值是否相同  │     │ → 是：跳过     │     │ API 并缓存   │
└─────────────┘     └──────────────┘     └─────────────┘

void setVertexBuffer(const id<MTLBuffer> buffer, uint32_t offset, uint32_t index) {
    // 检查 slot index 是否已绑定过相同的 buffer
    if (_vertexBufferMap.count(index) > 0) {
        const auto &bufferBinding = _vertexBufferMap[index];
        if (buffer == bufferBinding.buffer && offset == bufferBinding.offset) {
            return;  // 相同 buffer 且相同 offset，跳过
        }
    }

    // 更新缓存并调用 Metal API
    _vertexBufferMap[index] = {buffer, offset};
    [_mtlEncoder setVertexBuffer:buffer offset:offset atIndex:index];
}

void endEncoding() {
    [_mtlEncoder endEncoding];  // 结束 Metal 编码
    [_mtlEncoder release];       // 释放 encoder 引用
    _mtlEncoder = nil;
}

void CCMTLCommandBuffer::beginRenderPass(
    RenderPass *renderPass, Framebuffer *fbo,
    const Rect &renderArea, const Color *colors,
    float depth, uint32_t stencil,
    CommandBuffer *const *secondaryCBs, uint32_t secondaryCBCount)
{
    // 1. 从 Framebuffer 获取 MTLRenderPassDescriptor
    MTLRenderPassDescriptor *descriptor =
        static_cast<CCMTLFramebuffer *>(fbo)->getMTLRenderPassDescriptor();

    // 2. 配置颜色附件的清理值
    for (int i = 0; i < colorAttachmentCount; i++) {
        descriptor.colorAttachments[i].clearColor =
            MTLClearColorMake(colors[i].x, colors[i].y,
                              colors[i].z, colors[i].w);
    }

    // 3. 配置深度和模板清理值
    descriptor.depthAttachment.clearDepth = depth;
    descriptor.stencilAttachment.clearStencil = stencil;

    // 4. 创建 MTLRenderCommandEncoder
    _renderEncoder.initialize(_mtlCommandBuffer, descriptor);
}

MTLRenderPassDescriptor (Metal 原生)
    ├── colorAttachments[0]
    │   ├── texture        ← 从 Framebuffer 获取
    │   ├── loadAction     ← Clear / Load / DontCare
    │   ├── storeAction    ← Store / DontCare / MultisampleResolve
    │   └── clearColor     ← 清理颜色
    ├── colorAttachments[1..N]
    ├── depthAttachment
    │   ├── texture        ← 深度缓冲区纹理
    │   ├── loadAction
    │   ├── storeAction
    │   └── clearDepth
    └── stencilAttachment

void CCMTLCommandBuffer::draw(const DrawInfo &info) {
    // 1. 获取 InputAssembler 中的顶点/索引缓冲区
    CCMTLInputAssembler *ia = _inputAssembler;
    auto *indexBuffer  = ia->getIndexBuffer();
    auto *vertexBuffer = ia->getVertexBuffer();

    // 2. 根据是否有索引缓冲区选择绘制方式
    if (indexBuffer) {
        // 索引绘制（最常用）
        [_renderEncoder.getMTLEncoder()
            drawIndexedPrimitives:mu::toMTLPrimitive(_pipelineState->getPrimitive())
                        indexCount:info.indexCount
                         indexType:MTLIndexTypeUInt16
                       indexBuffer:indexBuffer->getMTLBuffer()
                 indexBufferOffset:info.firstIndex * sizeof(uint16_t)];
    } else {
        // 直接顶点绘制
        [_renderEncoder.getMTLEncoder()
            drawPrimitives:mu::toMTLPrimitive(_pipelineState->getPrimitive())
               vertexStart:info.firstVertex
               vertexCount:info.vertexCount];
    }

    // 3. 更新统计信息
    _numDrawCalls++;
    _numTriangles += info.indexCount / 3;
}

DrawInfo.vertexCount    → vertexCount
DrawInfo.firstVertex    → vertexStart
DrawInfo.indexCount     → indexCount
DrawInfo.firstIndex     → indexBufferOffset
PipelineState.primitive → MTLPrimitiveType

void CCMTLCommandBuffer::updateBuffer(Buffer *buff, const void *data, uint32_t size) {
    // 使用 StagingBufferPool 分配临时缓冲区
    CCMTLGPUBuffer gpuBuffer;
    gpuBuffer.size = size;
    _gpuStagingBufferPool->alloc(&gpuBuffer);

    // 将数据拷贝到共享内存
    memcpy(gpuBuffer.mappedData, data, size);

    // 注册到 GC Pool，在当前帧使用完毕后释放
    _gpuStagingBufferPool->recycle(&gpuBuffer);
}

CPU 数据
    │
    ▼
memcpy → CCMTLGPUStagingBufferPool (共享内存, MTLStorageModeShared)
    │
    ▼
[_encoder setVertexBuffer:gpuBuffer.mtlBuffer offset:...]
    │
    ▼
GPU 直接从共享内存读取（零拷贝）

class CCMTLGPUStagingBufferPool {
    void alloc(CCMTLGPUBuffer *gpuBuffer) {
        // 1. 遍历现有 buffer，查找有足够空间的
        for (auto &buffer : _pool) {
            uint32_t offset = alignUp(buffer.curOffset, alignment);
            if (gpuBuffer->instanceSize + offset <= [buffer.mtlBuffer length]) {
                // 复用已有 buffer
                gpuBuffer->mtlBuffer = buffer.mtlBuffer;
                gpuBuffer->startOffset = offset;
                gpuBuffer->mappedData = buffer.mappedData + offset;
                buffer.curOffset = offset + gpuBuffer->instanceSize;
                return;
            }
        }

        // 2. 没有可用 buffer，创建新的
        uint32_t needs = alignUp(gpuBuffer->instanceSize, MEGA_BYTES);
        Buffer newBuffer;
        newBuffer.mtlBuffer = [_device newBufferWithLength:needs
            options:MTLResourceStorageModeShared];
        newBuffer.mappedData = (uint8_t *)newBuffer.mtlBuffer.contents;
        _pool.push_back(newBuffer);
        // ...
    }

    void reset() {
        for (auto &buffer : _pool) {
            buffer.curOffset = 0;  // 每帧重置偏移量
        }
    }
};

MTLBuffer (1MB)    MTLBuffer (1MB)    MTLBuffer (1MB)
┌─────────────────┐┌─────────────────┐┌─────────────────┐
│ UBO ─────►      ││ 已满             ││ VBO ────►       │
│ curOffset = 256 ││ curOffset = 1024 ││ curOffset = 512  │
└─────────────────┘└─────────────────┘└─────────────────┘
       ↑                                    ↑
  UBO 从偏移 0 开始写入              VBO 从偏移 0 开始写入

每帧结束时 reset() → 所有 curOffset 归零 → 下一帧从头写入

class CCMTLGPUGarbageCollectionPool {
    void collect(std::function<void(void)> destroyFunc) {
        uint8_t curFrameIndex = _getFrameIndex();
        _releaseQueue[curFrameIndex].push(destroyFunc);
    }

    void clear(uint8_t currentFrameIndex) {
        while (!_releaseQueue[currentFrameIndex].empty()) {
            auto &&gcFunc = _releaseQueue[currentFrameIndex].front();
            gcFunc();  // 现在 GPU 已经完成对该帧资源的使用，可以安全释放
            _releaseQueue[currentFrameIndex].pop();
        }
    }
};

帧索引:    0       1       2       3       4
         ────→  ────→  ────→  ────→  ────→

CPU:     [编码 0] [编码 1] [编码 2] [编码 3] [编码 4]
GPU:              [执行 0] [执行 1] [执行 2] [执行 3]

释放队列:
  [0]: collect(destroy_A) ─────────→ clear(0) → destroy_A ✓
  [1]: collect(destroy_B) ─────────→ clear(1) → destroy_B ✓
  [2]: collect(destroy_C) ─────────→ clear(2) → destroy_C ✓

┌──────────────────────────────────────────────────────┐
│                   Cocos 引擎核心                       │
│         (RenderPipeline / FrameGraph / Scene)         │
├──────────────────────────────────────────────────────┤
│                  接口抽象层 (OSInterface)               │
│     ISystemWindow / IScreen / ISystemWindowManager     │
├─────────────────────────┬────────────────────────────┤
│     iOS 平台特化         │     macOS 平台特化           │
│  platform/ios/          │  platform/mac/             │
│  ├── IOSPlatform.mm     │  ├── MacPlatform.mm        │
│  ├── CocosView.mm       │  ├── CocosView.mm          │
│  ├── CocosRenderView.mm │  ├── View.mm               │
│  └── modules/           │  └── modules/              │
├─────────────────────────┴────────────────────────────┤
│              Metal 图形后端 (gfx-metal)                 │
│         CCMTLDevice / CCMTLSwapchain / ...            │
└──────────────────────────────────────────────────────┘

// IOSPlatform 支持两种定时器模式
typedef NS_ENUM(NSInteger, CocosTimerType) {
    COCOS_TIMER_DISPLAY_LINK,   // 默认：与屏幕刷新同步 (60/120Hz)
    COCOS_TIMER_SOURCE_TIMER,   // 备选：dispatch_source 定时器
};

// 切换定时器类型
- (void)changeCCTimerType:(CocosTimerType)type {
    if (_type == type) return;
    _type = type;
    if (_running) {
        [self pause];
        [self resume];
    }
}

// App 进入后台时挂起渲染
- (void)resignActive:(NSNotification *)notifacation {
    [self setInactive:YES];  // renderScene: 回调中会跳过
}

- (void)renderScene:(id)sender {
    if (_inactive) return;   // 后台静默，不执行渲染
    _platform->runTask();
}

@interface MyTimer : NSObject {
    CVDisplayLinkRef _displayLink;  // 与屏幕刷新同步
    NSTimer *_timer;                // 基于指定 FPS 的定时器
    NSInteger _framerate;           // >0 使用 NSTimer，0 使用 CVDisplayLink
}

- (void)start {
    _running = YES;
    if (_framerate > 0) {
        [self stopDisplayLink];
        [self startTimer];           // NSTimer 模式
    } else {
        [self stopTimer];
        [self startDiplayLink];      // CVDisplayLink 模式
    }
}

static CVReturn displayLinkCallback(
    CVDisplayLinkRef displayLink,
    const CVTimeStamp *inNow,
    const CVTimeStamp *inOutputTime,
    CVOptionFlags flagsIn,
    CVOptionFlags *flagsOut,
    void *displayLinkContext)
{
    MyTimer *timer = (__bridge MyTimer *)displayLinkContext;
    dispatch_async(dispatch_get_main_queue(), ^{
        [timer renderScene];
    });
    return kCVReturnSuccess;
}

@implementation CocosView

#ifdef CC_USE_METAL
+ (Class)layerClass {
    if (!FeatureSwitch::singletonMetalLayer) {
        return [CAMetalLayer class];  // 让 UIView 的 backing layer 就是 CAMetalLayer
    } else {
        return [CALayer class];       // 多窗口共享场景，用普通 CALayer
    }
}
#endif

- (id)initWithFrame:(CGRect)frame {
    self = [super initWithFrame:frame];
    float pixelRatio = [[UIScreen mainScreen] nativeScale];
    CGSize size = CGSizeMake(
        frame.size.width * pixelRatio,
        frame.size.height * pixelRatio);
    self.contentScaleFactor = pixelRatio;

    if (!FeatureSwitch::singletonMetalLayer) {
        // 配置 CAMetalLayer
        CAMetalLayer *layer = (CAMetalLayer *)self.layer;
        layer.pixelFormat = MTLPixelFormatBGRA8Unorm;
        layer.device = MTLCreateSystemDefaultDevice();
        layer.drawableSize = size;
    }
    return self;
}

@implementation CocosView

+ (Class)layerClass {
    return [CAMetalLayer class];
}

- (id)initWithFrame:(CGRect)frame {
    self = [super initWithFrame:frame];
    float pixelRatio = [[CocosCreator sharedInstance] getPixelRatio];
    CGSize size = CGSizeMake(
        frame.size.width * pixelRatio,
        frame.size.height * pixelRatio);

    // AppKit 必须显式启用 layer-backed 模式
    self.wantsLayer = YES;
    self.autoresizesSubviews = YES;
    self.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;

    // 手动配置 CAMetalLayer
    CAMetalLayer *layer = (CAMetalLayer *)self.layer;
    layer.drawableSize = size;
    layer.pixelFormat = MTLPixelFormatBGRA8Unorm;
    layer.device = MTLCreateSystemDefaultDevice();
    layer.autoresizingMask = kCALayerWidthSizable | kCALayerHeightSizable;
    self.layerContentsPlacement =
        NSViewLayerContentsPlacementScaleProportionallyToFill;

    return self;
}

// 手动创建 backing layer（而非依赖 layerClass）
- (CALayer *)makeBackingLayer {
    CAMetalLayer *layer = [CAMetalLayer layer];
    layer.delegate = self;
    layer.autoresizingMask = true;
    layer.needsDisplayOnBoundsChange = true;
    return layer;
}

- (void)dispatchTouchEvent:(cc::TouchEvent::Type)type
                 withEvent:(NSSet *)touches {
    cc::TouchEvent touchEvent;
    touchEvent.type = type;
    for (UITouch *touch in touches) {
        touchEvent.touches.push_back({
            [touch locationInView:[touch view]].x,
            [touch locationInView:[touch view]].y,
            (intptr_t)touch
        });
    }
    cc::events::Touch::broadcast(touchEvent);
}

- (void)sendMouseEvent:(int)button
                  type:(cc::MouseEvent::Type)type
                 event:(NSEvent *)event {
    _mouseEvent.type = type;
    _mouseEvent.button = button;
    _mouseEvent.xDelta = [event deltaX];
    _mouseEvent.yDelta = [event deltaY];
    NSPoint location = [self convertPoint:[event locationInWindow]
                                 fromView:nil];
    _mouseEvent.x = location.x;
    _mouseEvent.y = self.frame.size.height - location.y;
    cc::events::Mouse::broadcast(_mouseEvent);
}

[[NSNotificationCenter defaultCenter]
    addObserver:self
       selector:@selector(resignActive:)
           name:UIApplicationWillResignActiveNotification
         object:nil];

- (void)resignActive:(NSNotification *)notifacation {
    [self setInactive:YES];   // 标记 inactive
    // renderScene: 中检测 _inactive 为 true 时直接 return
}

void MacPlatform::onPause() {
    cc::WindowEvent ev;
    ev.type = cc::WindowEvent::Type::HIDDEN;
    cc::events::WindowEvent::broadcast(ev);
}

void MacPlatform::onResume() {
    cc::WindowEvent ev;
    ev.type = cc::WindowEvent::Type::SHOW;
    cc::events::WindowEvent::broadcast(ev);
}

                 OSInterface (抽象接口)
                      │
        ┌─────────────┼─────────────┐
        │             │             │
   IOSPlatform   MacPlatform    AndroidPlatform
        │             │             │
   ISystemWindow  ISystemWindow  ISystemWindow
   IScreen        IScreen        IScreen
   IAccelerometer IAccelerometer ...

CMakeLists.txt
├── include(cmake/predefine.cmake)     # 预定义宏和工具函数
├── 选项定义 (USE_SE_V8 / CC_USE_METAL / ...)
├── 源文件收集 (COCOS_SOURCE_LIST)
├── add_library(${ENGINE_NAME} STATIC ...)  # 静态库目标
├── 平台特化编译选项 (APPLE / ANDROID / ...)
└── source_group 源码组织

if(MACOSX OR IOS)
    cc_set_if_undefined(CC_USE_METAL ON)
    cc_set_if_undefined(CC_USE_VULKAN OFF)
    cc_set_if_undefined(CC_USE_GLES3 OFF)
elseif(ANDROID OR WINDOWS OR OHOS)
    cc_set_if_undefined(CC_USE_GLES3 ON)
    cc_set_if_undefined(CC_USE_VULKAN OFF)
elseif(NX)
    cc_set_if_undefined(CC_USE_VULKAN ON)
    cc_set_if_undefined(CC_USE_GLES3 OFF)
endif()

if(APPLE)
    target_link_libraries(${ENGINE_NAME} PUBLIC
        "-framework Metal"
        "-framework MetalKit"
        "-framework QuartzCore"
        "-framework MetalPerformanceShaders"
        "-framework Foundation"
        "-framework GameController"
        # ...
    )

    # macOS 额外框架
    if(MACOSX)
        target_link_libraries(${ENGINE_NAME} PUBLIC
            "-framework OpenGL"    # macOS 需要 OpenGL
            "-framework AppKit"    # 桌面 UI 框架
        )
        target_compile_definitions(${ENGINE_NAME} PUBLIC
            CC_KEYBOARD_SUPPORT    # 桌面独有的键盘支持
        )
    elseif(IOS)
        # iOS 额外框架
        target_link_libraries(${ENGINE_NAME} PUBLIC
            "-framework UIKit"         # 移动端 UI 框架
            "-framework WebKit"
            "-framework CoreMotion"    # 传感器
            "-framework AVKit"
            "-framework CoreVideo"
        )
        # 设置部署目标和关闭 Bitcode
        set_property(TARGET ${ENGINE_NAME} PROPERTY
            XCODE_ATTRIBUTE_IPHONEOS_DEPLOYMENT_TARGET ${TARGET_IOS_VERSION})
        set_property(TARGET ${ENGINE_NAME} PROPERTY
            XCODE_ATTRIBUTE_ENABLE_BITCODE "NO")
    endif()
endif()

set_target_properties(${ENGINE_NAME} PROPERTIES
    XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH "YES"
    OSX_ARCHITECTURES "arm64;x86_64"
    ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/archives
)

# 构建 ARM64 真机静态库
cmake .. -G Xcode \
    -DCMAKE_SYSTEM_NAME=iOS \
    -DCMAKE_OSX_ARCHITECTURES=arm64 \
    -DCMAKE_OSX_SYSROOT=iphoneos
cmake --build . --config Release

# 构建 ARM64 模拟器静态库
cmake .. -G Xcode \
    -DCMAKE_SYSTEM_NAME=iOS \
    -DCMAKE_OSX_ARCHITECTURES=arm64 \
    -DCMAKE_OSX_SYSROOT=iphonesimulator
cmake --build . --config Release

# 打包为 XCFramework
xcodebuild -create-xcframework \
    -library build/ios-device/libcocos_engine.a \
    -library build/ios-simulator/libcocos_engine.a \
    -output CocosEngine.xcframework

# 隐藏所有符号，仅导出指定 API
set(CMAKE_CXX_VISIBILITY_PRESET hidden)
set(CMAKE_C_VISIBILITY_PRESET hidden)
set(CMAKE_VISIBILITY_INLINES_HIDDEN YES)

# 需要导出的 API 使用 __attribute__((visibility("default")))

检查脏标记和缓存值 → 相同则 return → 不同则调用 Metal API 并更新缓存

帧索引:    0       1       2       3       4
         ────→  ────→  ────→  ────→  ────→
CPU:     [编码 0] [编码 1] [编码 2] [编码 3] [编码 4]
GPU:              [执行 0] [执行 1] [执行 2] [执行 3]

释放:
  帧 0 的资源 → 入队到 releaseQueue[0] → 帧 2 才安全释放
  帧 1 的资源 → 入队到 releaseQueue[1] → 帧 3 才安全释放

MTLBuffer (1MB, MTLStorageModeShared)
┌────────────────────────────────────────┐
│ UBO_A │ UBO_B │ VBO_C │    空闲     │
│ offset=0  offset=256  offset=512  curOffset=640  │
└────────────────────────────────────────┘

OSInterface（抽象接口，如 ISystemWindow、IScreen）
    ├── IOSPlatform（+layerClass 静态绑定 UIView）
    └── MacPlatform（makeBackingLayer 手动创建 NSView）