graph LR
    A[WebRTC VideoTrack] --> B(VideoFrame Processor)
    B --> C{WebGPU Device Context}
    C --> D[External Texture Importer]
    D --> E[Resource Pool Manager]
    E --> F[Compute Pass 1: 预处理/去噪]
    F --> G[Compute Pass 2: 美颜/风格化]
    G --> H[Compute Pass 3: 后处理/锐化]
    H --> I[Output Target]
    I --> J[Canvas 渲染 / WebRTC Insertable Streams 编码]

// 核心导入代码片段
const videoFrameProcessor = new VideoFrameProcessor({
  // ... 配置
});

videoFrameProcessor.onframe = async (frame) => {
  // 1. 零拷贝导入 External Texture
  const externalTexture = device.importExternalTexture({
    source: frame,
    colorSpace: 'srgb', // 或 'display-p3' 根据业务需求
  });

  // 2. 录入当前帧资源上下文
  pipelineContext.setFrameResource(frame.timestamp, {
    externalTexture,
    width: frame.displayWidth,
    height: frame.displayHeight,
  });

  // 3. 提交计算命令
  await submitComputeWork(pipelineContext, frame.timestamp);
  
  // 4. 释放 VideoFrame (归还给解码器池)
  frame.close(); 
};

// WGSL 入口点定义
@group(0) @binding(0) var inputTex: texture_external;
@group(0) @binding(1) var outputTex: texture_storage_2d<rgba8unorm, write>;
@group(0) @binding(2) var<uniform> params: Params;

// 推荐 16x16 或 8x8 Workgroup，平衡占用率与共享内存
@compute @workgroup_size(16, 16, 1)
fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
  let dims = textureDimensions(inputTex);
  if (global_id.x >= dims.x || global_id.y >= dims.y) { return; }
  
  // ... 核心计算逻辑
}

const workgroupSize = 16;
const dispatchX = Math.ceil(width / workgroupSize);
const dispatchY = Math.ceil(height / workgroupSize);
pass.dispatchWorkgroups(dispatchX, dispatchY);

// 共享内存声明 (假设 16x16 Workgroup, 扩展 2px halo 用于 5x5 卷积)
var<workgroup> tile: array<vec4<f32>, 20 * 20>; 

fn load_tile(coords: vec2<u32>) {
  let local_id = vec2<u32>(local_invocation_id.xy);
  let tile_w = 20u;
  // 协作加载：每个线程加载 1-2 个像素
  // ... 边界检查与坐标映射逻辑 ...
  tile[local_id.y * tile_w + local_id.x] = textureLoad(inputTex, coords);
}
workgroupBarrier(); // 关键同步点

// 后续在共享内存中完成卷积计算，无需重复采样全局纹理

class TexturePool {
  constructor(device, width, height, format, count = 3) {
    this.freeList = [];
    this.inFlight = new Map(); // timestamp -> { texture, fence }
    
    for (let i = 0; i < count; i++) {
      this.freeList.push(device.createTexture({
        size: [width, height],
        format,
        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
      }));
    }
  }

  acquire(timestamp) {
    if (this.freeList.length === 0) {
      // 回收已完成的 fence
      this.reclaimCompleted();
    }
    const tex = this.freeList.pop();
    // 创建 fence 标记此纹理何时可复用
    const fence = device.createFence(); // 伪代码，实际需配合 queue.onSubmittedWorkDone 或 timeline semaphore
    this.inFlight.set(timestamp, { texture: tex, fence });
    return tex;
  }

  async reclaimCompleted() {
    // 轮询或等待 fence signaled，归还 texture 到 freeList
  }
}

// 伪代码：WebGPU Texture -> WebNN Tensor 零拷贝路径 (依赖浏览器支持 GPUBuffer/Texture 互导)
async function setupAIInterop(device, webnnContext) {
  // 1. 创建可映射的 Buffer 作为中间桥梁
  const stagingBuffer = device.createBuffer({
    size: width * height * 4, // RGBA32Float
    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_READ,
  });

  // 2. Compute Shader 写入结果到 Storage Buffer (而非 Texture)
  // @group(0) @binding(0) var<storage, write> outputBuffer: array<vec4<f32>>;
  
  // 3. 提交命令后，直接映射 Buffer 传给 WebNN (需浏览器支持 GPUBuffer -> ArrayBufferView 零拷贝)
  // 目前主流方案：Compute Shader 写 Storage Texture -> CopyTextureToBuffer -> MapAsync -> WebNN Input
  // 前沿方案 (Chrome 120+ 实验标志): GPUBufferMapAsync 直接获取 ArrayBuffer, 构造 MLTensor
}

interface FrameColorMetadata {
  primaries: 'BT709' | 'BT2020';
  transfer: 'SRGB' | 'PQ' | 'HLG' | 'LINEAR';
  matrix: 'BT709' | 'BT2020_NCL'; // YUV->RGB 矩阵
  maxLuminance: number; // nits, for PQ tone mapping
  minLuminance: number;
}

// 统一入口：任意输入 -> Linear Rec.2020 (FP16 Storage Texture)
fn toLinearRec2020(input: vec3<f32>, meta: ColorMetadata) -> vec3<f32> {
  // 1. YUV -> RGB (使用正确矩阵)
  let rgb = yuvToRgb(input, meta.matrix); 
  
  // 2. EOTF (Electro-Optical Transfer Function) -> Linear
  switch (meta.transfer) {
    case SRGB: return srgbToLinear(rgb);
    case PQ:   return pqToLinear(rgb); // ST 2084 Inverse
    case HLG:  return hlgToLinear(rgb, meta.maxLuminance);
    default:   return rgb; // Assume Linear
  }
}

// 统一出口：Linear Rec.2020 -> 目标输出设备编码
fn fromLinearRec2020(linear: vec3<f32>, targetMeta: ColorMetadata) -> vec3<f32> {
  // Gamut Mapping (BT2020 -> Target Primaries) - 使用 ICtCp 或简单裁剪/压缩
  let mapped = gamutMap(linear, targetMeta.primaries);
  
  // OETF (Opto-Electronic Transfer Function)
  switch (targetMeta.transfer) {
    case PQ:   return linearToPq(mapped);
    case HLG:  return linearToHlg(mapped, targetMeta.maxLuminance);
    case SRGB: return linearToSrgb(mapped);
    default:   return mapped;
  }
}

// WGSL Bindless 示例 (需启用 'bindless' feature)
@group(0) @binding(0) var textures: binding_array<texture_2d<f32>>;
@group(0) @binding(1) var samplers: binding_array<sampler>;
@group(0) @binding(2) var storageBuffers: binding_array<buffer<vec4<f32>>>;

// Shader 侧通过动态索引访问
fn sampleTexture(handle: u32, uv: vec2<f32>) -> vec4<f32> {
  return textureSample(textures[handle], samplers[0], uv);
}

class BindlessHeap {
  constructor(device, maxTextures = 4096) {
    this.device = device;
    this.textureViews = new Array(maxTextures);
    this.freeIndices = new Uint32Array(maxTextures); // 空闲索引栈
    // ... 初始化 binding_array 资源 ...
  }

  allocateTextureView(view) {
    const idx = this.freeIndices.pop();
    this.textureViews[idx] = view;
    // 更新 BindGroup 内部缓冲区 (或使用 Buffer 指针更新)
    this.updateDescriptorBuffer(idx, view);
    return idx; // 返回句柄传给 Shader
  }
  
  release(handle) {
    this.freeIndices.push(handle);
    this.textureViews[handle] = null;
  }
}

interface PerfMetrics {
  gpuComputeMs: number;      // GPU 计算耗时 (Timestamp Query)
  gpuRenderMs: number;
  cpuEncodeMs: number;       // JS 主线程耗时
  thermalState: 'nominal' | 'fair' | 'serious' | 'critical'; // navigator.getThermalState()
  batteryLevel: number;
  frameDropCount: number;
  resolution: [number, number];
  shaderComplexityLevel: number; // 当前算法等级
}

class AdaptiveQualityController {
  private pid = new PIDController({ Kp: 0.5, Ki: 0.05, Kd: 0.1, setpoint: 30.0 }); // 目标 30ms/帧
  private currentLevel = 3; // 0:Low, 1:Med, 2:High, 3:Ultra
  private currentScale = 1.0;

  update(metrics: PerfMetrics) {
    // 1. 热力学保护：最高优先级
    if (metrics.thermalState === 'critical') this.forceLevel(0, 0.5);
    else if (metrics.thermalState === 'serious') this.forceLevel(1, 0.75);

    // 2. PID 闭环控制
    const error = metrics.gpuComputeMs - 30.0;
    const adjustment = this.pid.compute(error);
    
    // 3. 离散化映射到档位
    this.currentLevel = clamp(Math.round(this.currentLevel - adjustment), 0, 3);
    this.currentScale = [0.5, 0.75, 1.0, 1.0][this.currentLevel]; // 分辨率缩放
    
    // 4. 下发新配置 (下一帧生效)
    pipeline.updateQualityPreset(this.currentLevel, this.currentScale);
  }
}

// 统一入口，通过 qualityLevel 控制采样半径/迭代次数
@group(0) @binding(0) var<uniform> quality: QualityParams; // level, radiusScale, iterCount

fn bilateralFilter(coord: vec2<u32>) -> vec4<f32> {
  let radius = u32(quality.baseRadius * quality.radiusScale[quality.level]);
  let iterations = quality.iterCount[quality.level];
  
  // 低画质: 单次 3x3 近似; 高画质: 双次 7x7 迭代
  // 利用分支预测友好写法，或预编译变体
}

// 1. 创建 QuerySet
const querySet = device.createQuerySet({ type: 'timestamp', count: 2 * PASS_COUNT });

// 2. Command Encoder 写入时间戳
pass.writeTimestamp(querySet, passIndex * 2);     // Pass Start
// ... dispatch ...
pass.writeTimestamp(querySet, passIndex * 2 + 1); // Pass End

// 3. Resolve 到 Buffer -> MapAsync 读回
const resolveBuffer = device.createBuffer({
  size: querySet.count * 8, // BigInt64
  usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_READ,
});
commandEncoder.resolveQuerySet(querySet, 0, querySet.count, resolveBuffer, 0);

// 4. 计算耗时 (ns -> ms)
const timestamps = new BigInt64Array(await resolveBuffer.mapAsync());
const durationMs = Number(timestamps[end] - timestamps[start]) / 1_000_000;

interface PipelineBundle {
  version: string; // SemVer + Git Commit Hash
  wgslModules: Record<string, string>; // 源码或 SPIRV-WASM
  pipelineLayoutDesc: GPUPipelineLayoutDescriptor;
  computePasses: ComputePassConfig[];
  qualityPresets: QualityPreset[];
  abTestBucket: string; // 'control' | 'treatment_a'
}