[VideoFrame Input] 
      │
      ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Pre-Process    │────▶│  Core Enhance   │────▶│  Post-Process   │
│  (统一入口)     │     │  (业务可插拔)   │     │  (编码前对齐)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
      │                       │                       │
      ▼                       ▼                       ▼
- 格式统一化            - 超分/降噪/美颜         - 色域映射
- 旋转/镜像修正         - 背景虚化/替换          - 码率控制元数据注入
- 时间戳对齐            - 水印/字幕叠加          - 编码器专用格式转换

// common/utils.wgsl
fn bilinear_sample(tex: texture_2d<f32>, samp: sampler, uv: vec2<f32>) -> vec4<f32> {
  // 统一处理边界条件，规避不同 GPU 对 clamp_to_edge 实现差异
  return textureSample(tex, samp, uv);
}

// pipeline/preprocess.wgsl
@group(0) @binding(0) var input_tex: texture_2d<f32>;
@group(0) @binding(1) var samp: sampler;
@group(0) @binding(2) var<storage, read_write> out_tex: texture_storage_2d<rgba8unorm, write>;

@compute @workgroup_size(16, 16)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  let dims = textureDimensions(input_tex);
  if (gid.x >= dims.x || gid.y >= dims.y) { return; }
  let uv = (vec2<f32>(gid.xy) + 0.5) / vec2<f32>(dims.xy);
  let color = bilinear_sample(input_tex, samp, uv);
  // 旋转/镜像/色域转换均在此统一完成
  textureStore(out_tex, gid.xy, color);
}

// 运行时自适应选择
const adapter = await navigator.gpu.requestAdapter();
const limits = adapter.limits;
const workgroupSize = (() => {
  const vendor = adapter.info.vendor.toLowerCase();
  if (vendor.includes('qualcomm') || vendor.includes('arm')) return [8, 16];
  if (vendor.includes('intel') && limits.maxComputeWorkgroupSizeX >= 256) return [16, 16];
  return [16, 16]; // 默认回退
})();

graph TD
    A[业务层申请<br/>TextureDescriptor] --> B{Allocator Core}
    B --> C[L1: Slab Pool<br/>固定规格 256KB/1MB/4MB]
    B --> D[L2: Buddy System<br/>大块 16MB+ 按需切分]
    C --> E[GPUTexture/Buffer 实例]
    D --> E
    E --> F[Reference Counting + Frame Fence]
    F --> G[延迟回收至 Pool]

interface PoolEntry {
  resource: GPUTexture | GPUBuffer;
  size: number;           // 字节
  formatKey: string;      // "rgba8unorm-1920x1080" 或 "storage-buffer-4MB"
  frameId: number;        // 最后使用帧号
  refCount: number;       // 引用计数
  fence?: GPUFence;       // 跨队列同步栅栏
}

class GPUMemoryAllocator {
  private pools: Map<string, PoolEntry[]> = new Map();
  private buddy: BuddyAllocator; // 大块内存管理
  private frameId = 0;

  // 统一入口：按描述符复用或分配
  acquire(desc: GPUTextureDescriptor | GPUBufferDescriptor): GPUTexture | GPUBuffer {
    const key = this.genKey(desc);
    const pool = this.pools.get(key) ?? [];
    // 1. 尝试复用：refCount=0 且 fence 已 signaled
    const candidate = pool.find(e => e.refCount === 0 && this.isFenceSignaled(e.fence));
    if (candidate) {
      candidate.refCount = 1;
      candidate.frameId = this.frameId;
      return candidate.resource;
    }
    // 2. 新建：优先从 Buddy 切分，失败则直接 create
    const resource = this.createFromBuddyOrDevice(desc);
    pool.push({ resource, size: this.calcSize(desc), formatKey: key, frameId: this.frameId, refCount: 1 });
    this.pools.set(key, pool);
    return resource;
  }

  // 每帧末尾调用：推进帧号、清理超龄资源
  tick(device: GPUDevice) {
    this.frameId++;
    // 标记本帧未使用的资源为可回收
    for (const pool of this.pools.values()) {
      for (const entry of pool) {
        if (entry.frameId !== this.frameId && entry.refCount === 0) {
          entry.fence = device.createFence(); // 插入栅栏等待 GPU 真正空闲
          this.queueFenceCheck(entry);
        }
      }
    }
    // 定期归还 Buddy 大块内存（如连续 60 帧未用）
    this.buddy.reclaimStaleBlocks(this.frameId, 60);
  }
}

[VideoFrame (CPU/GPU)] 
       │
       ▼
┌─────────────────────────────────────┐
│  WebGPU Import External Texture     │  ← 关键：无拷贝接入
│  (GPUExternalTexture /              │
│   GPUTexture via copyExternal...)   │
└─────────────────────────────────────┘
       │
       ▼
[Compute Shader Pipeline] → [GPUTexture Output]
       │                              │
       │                              ▼
       │                     ┌──────────────────┐
       │                     │ VideoEncoder     │
       │                     │ encode(texture)  │  ← WebCodecs 直接消费 GPUTexture
       │                     └──────────────────┘
       │
       ▼ (解码侧对称)
[VideoDecoder] → [VideoFrame (GPU)] → [WebGPU Import] → [CS Post-Process] → [Canvas/WebGPU SwapChain]

// 编码提交侧
async function submitEncode(encoder: VideoEncoder, gpuTexture: GPUTexture, timestamp: number) {
  // 1. 创建栅栏，标记 CS 写入完成
  const fence = device.createFence();
  queue.signal(fence, 1); // CS Pass 结束后 signal

  // 2. 导入为 VideoFrame (零拷贝)
  const videoFrame = new VideoFrame(gpuTexture, { timestamp, format: 'RGBA' });
  
  // 3. 编码器回调中等待栅栏
  encoder.encode(videoFrame, { keyFrame: false });
  
  // 4. 注册完成回调，安全释放
  encoder.encode(videoFrame).then(() => {
    // 等待 GPU 真正读完 (驱动层面)
    fence.wait(1).then(() => videoFrame.close()); 
  });
}

// C++ (Emscripten) 侧直接操作 WebGPU Buffer mapped pointer
EMSCRIPTEN_BINDINGS() {
  emscripten::function("processLandmarks", [](uintptr_t bufferPtr, size_t byteLength, float* landmarks, int count) {
    // bufferPtr 即 GPUBuffer.getMappedRange() 返回的 ArrayBuffer 地址
    auto* data = reinterpret_cast<float*>(bufferPtr);
    // 原地计算，无 memcpy
    for (int i = 0; i < count; ++i) data[i] = landmarks[i] * 2.0f; // 示例
  });
}

interface PerfTelemetry {
  // 静态指纹 (首帧采集一次)
  static: {
    gpuVendor: string; renderer: string; 
    maxTextureSize: number; maxBufferSize: number;
    subgroupSupport: boolean; f16Support: boolean;
    benchmarkScore: number; // 内置微基准分
  };
  // 动态遥测 (每秒上报)
  dynamic: {
    frameTimeP50: number; frameTimeP99: number;
    gpuTimeMS: number; cpuTimeMS: number;
    memoryUsageMB: number; thermalState: 'nominal'|'fair'|'serious'|'critical';
    batteryLevel: number; isCharging: boolean;
    networkRTT: number; packetLoss: number;
  };
}

class AdaptiveController {
  private state: 'HIGH' | 'MEDIUM' | 'LOW' | 'POWER_SAVE' = 'HIGH';
  private hysteresisFrames = 0;

  evaluate(telemetry: PerfTelemetry) {
    const target = this.computeTargetState(telemetry);
    if (target !== this.state) {
      this.hysteresisFrames++;
      if (this.hysteresisFrames >= 3) { // 3 帧确认
        this.applyStrategy(target);
        this.state = target;
        this.hysteresisFrames = 0;
      }
    } else {
      this.hysteresisFrames = 0;
    }
  }
}

# .github/workflows/webgpu-perf.yml
jobs:
  perf-regression:
    runs-on: [self-hosted, gpu-nvidia-t4] # 专用 GPU Runner
    steps:
      - uses: actions/checkout@v4
      - name: Run Headless Benchmark
        run: |
          xvfb-run -a node bench/perf_suite.mjs --iterations=100 --format=json > result.json
      - name: Compare with Baseline
        run: |
          python scripts/compare_perf.py --current result.json --baseline artifacts/baseline.json --threshold 0.05
      - name: Upload Flamegraph
        uses: actions/upload-artifact@v4
        with:
          name: flamegraph-${{ github.sha }}
          path: profile/*.speedscope.json

# 1. 语法/风格检查
npx wgsl-analyzer lint shaders/**/*.wgsl --config .wgslintrc.json

# 2. 交叉编译验证 (DXC -> SPIR-V -> NIR)
dxc -T cs_6_5 -E main shader.wgsl -Fo shader.dxil
spirv-val shader.spv  # 验证 SPIR-V 合法性

# 3. 资源绑定布局哈希固化
node scripts/gen_bindings_hash.mjs > src/gpu/bindings_hash.ts
# CI 中对比哈希，防止 BindGroupLayout 意外变更导致 Pipeline 重建

// 仅请求必要特性，拒绝指纹采集滥用
const adapter = await navigator.gpu.requestAdapter({
  powerPreference: 'high-performance',
  // 显式声明不需要的特性，减少指纹熵
  // featureLevel: 'core' // 如业务允许，锁定核心特性集
});

// 禁止读取无关适配器信息
// adapter.info // 仅在首次初始化上报指纹库使用，运行期不持久化

// WebGL Texture -> WebGPU Texture (零拷贝需扩展支持，否则走 copy)
async function importWebGLTexture(gl, glTex, device) {
  // 方案 A: CHROMIUM_shared_image (Chrome/Edge 支持最好)
  if (gl.getExtension('CHROMIUM_shared_image')) {
    const si = gl.createSharedImageCHROMIUM(glTex, { usage: GL.SHARED_IMAGE_USAGE_WEBGPU_CHROMIUM });
    return device.createTexture({ 
      // 通过 SharedImage 直接导入，无驱动拷贝
      ...descriptor, 
      __sharedImage: si  // 非标准属性，需封装层处理
    });
  }
  // 方案 B: 兜底 Copy (性能损耗 ~0.3ms/1080p)
  const gpuTex = device.createTexture({ usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING, ... });
  device.queue.copyExternalImageToTexture(
    { source: gl.canvas }, // 或 OffscreenCanvas
    { texture: gpuTex },
    [width, height]
  );
  return gpuTex;
}

// config/production.webgpu.json
{
  "memory": {
    "poolStrategy": "two-tier",
    "maxPoolSizeMB": 512,
    "slabSizesKB": [256, 1024, 4096],
    "reclaimFramesThreshold": 60,
    "buddyMinBlockMB": 16
  },
  "pipeline": {
    "defaultWorkgroup": [16, 16],
    "adrenoWorkgroup": [8, 16],
    "maliWorkgroup": [8, 16],
    "enableSubgroup": true,
    "enableF16Storage": false,
    "timestampQueryEnabled": true
  },
  "adaptive": {
    "targetFPS": 30,
    "frameBudgetMS": 16.6,
    "thermalThrottleEnabled": true,
    "degradeSteps": [
      { "trigger": "gpuTime>12", "action": "disableSuperRes" },
      { "trigger": "thermal=serious", "action": "downscaleEncode(0.75)" },
      { "trigger": "mem>0.9", "action": "shrinkPool(0.5)" }
    ]
  },
  "compat": {
    "fallbackOrder": ["webgpu", "webgl2", "wasm-cpu"],
    "denyList": {
      "drivers": ["Mesa 22.0", "Adreno 6xx (Android 11)"],
      "devices": ["Pixel 4", "iPhone 12 (iOS 16.0)"]
    }
  },
  "observability": {
    "sampleRate": 0.1,
    "uploadEndpoint": "https://telemetry.example.com/webgpu",
    "piiScrubber": "strict"
  }
}