graph LR
    A[WebRTC VideoTrack] --> B(VideoFrame Processor)
    B --> C{WebGPU Context}
    C --> D[Preprocess Shader<br/>YUV->RGB / Normalize]
    D --> E[SR/Enhance Compute Shader<br/>FSRCNN / Real-ESRGAN-light]
    E --> F[Postprocess Shader<br/>Denoise / Sharpen / Tonemap]
    F --> G[Canvas / VideoFrame Output]
    G --> H[WebRTC Sender / Local Preview]

// preprocess.wgsl
@group(0) @binding(0) var yTex: texture_2d<f32>;
@group(0) @binding(1) var uTex: texture_2d<f32>;
@group(0) @binding(2) var vTex: texture_2d<f32>;
@group(0) @binding(3) var outputTex: texture_storage_2d<rgba8unorm, write>;

@compute @workgroup_size(16, 16)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  let dims = textureDimensions(outputTex);
  if (gid.x >= dims.x || gid.y >= dims.y) { return; }

  // 采样 YUV (U/V 平面宽高减半)
  let y = textureLoad(yTex, vec2<u32>(gid.xy), 0).r;
  let u = textureLoad(uTex, vec2<u32>(gid.xy / 2u), 0).r;
  let v = textureLoad(vTex, vec2<u32>(gid.xy / 2u), 0).r;

  // BT.709 Full Range 转换
  let r = y + 1.5748 * (v - 0.5);
  let g = y - 0.1873 * (u - 0.5) - 0.4681 * (v - 0.5);
  let b = y + 1.8556 * (u - 0.5);

  textureStore(outputTex, vec2<u32>(gid.xy), vec4<f32>(r, g, b, 1.0));
}

// conv2d.wgsl 片段
struct ConvParams { kernel: u32, stride: u32, pad: u32, inC: u32, outC: u32 };
@group(0) @binding(0) var<storage, read> weight: array<f32>; // [outC, inC, kH, kW]
@group(0) @binding(1) var<storage, read> bias: array<f32>;
@group(0) @binding(2) var<storage, read> input: array<f32>;  // NHWC Layout
@group(0) @binding(3) var<storage, read_write> output: array<f32>;
@group(0) @binding(4) var<uniform> params: ConvParams;

var<workgroup> shmem: array<f32, 16 * 16 * 32>; // 动态调整大小

@compute @workgroup_size(16, 16, 1)
fn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
  // 1. 计算输出坐标 (n, oh, ow, oc)
  // 2. 协作加载 Input Tile 与 Weight Tile 至 shmem
  // 3. 累加计算 Dot Product
  // 4. 写回 Output (融合 ReLU/PReLU)
  // ... 详细边界检查与索引计算省略 ...
}

// enhance.wgsl
@group(0) @binding(0) var inputTex: texture_2d<f32>;
@group(0) @binding(1) var outputTex: texture_storage_2d<rgba8unorm, write>;
@group(0) @binding(2) var<uniform> params: EnhanceParams; // strength, sigma_spatial, sigma_range

@compute @workgroup_size(16, 16)
fn main(@builtin(global_invocation_id) gid: vec2<u32>) {
  let center = textureLoad(inputTex, gid.xy, 0).rgb;
  var acc = vec3<f32>(0.0);
  var w_sum = 0.0;

  // 3x3 或 5x5 邻域搜索 (近似 NLM)
  for (dy = -2i; dy <= 2; dy++) {
    for (dx = -2i; dx <= 2; dx++) {
      let neighbor = textureLoad(inputTex, vec2<i32>(gid) + vec2<i32>(dx, dy), 0).rgb;
      let dist_spatial = f32(dx*dx + dy*dy);
      let dist_range = distance(center, neighbor);
      let w = exp(-dist_spatial / params.sigma_spatial - dist_range / params.range);
      acc += neighbor * w;
      w_sum += w;
    }
  }
  let denoised = acc / w_sum;

  // Unsharp Mask 锐化
  let blur = textureSampleLevel(inputTex, sampler_linear, vec2<f32>(gid) / vec2<f32>(textureDimensions(inputTex)), 1.0).rgb; // 利用 Mipmap 近似模糊
  let sharpened = denoised + params.strength * (denoised - blur);

  textureStore(outputTex, gid, vec4<f32>(clamp(sharpened, 0.0, 1.0), 1.0));
}

// 伪代码：命令缓冲区录制
const encoder = device.createCommandEncoder();
const computePass = encoder.beginComputePass({ timestampWrites: querySet });

// Stage 1: Preprocess
computePass.setPipeline(preprocessPipeline);
computePass.setBindGroup(0, preprocessBindGroups[frameIndex % poolSize]);
computePass.dispatchWorkgroups(...);
computePass.writeTimestamp(0); // 记录阶段1结束

// Stage 2: SR
computePass.setPipeline(srPipeline);
computePass.setBindGroup(0, srBindGroups[frameIndex % poolSize]);
computePass.dispatchWorkgroups(...);
computePass.writeTimestamp(1);

// Stage 3: Enhance
computePass.setPipeline(enhancePipeline);
computePass.setBindGroup(0, enhanceBindGroups[frameIndex % poolSize]);
computePass.dispatchWorkgroups(...);
computePass.writeTimestamp(2);

computePass.end();
device.queue.submit([encoder.finish()]);

# Python 伪代码：导出量化参数供 WGSL 使用
import numpy as np
def quantize_per_tensor(w_f32: np.ndarray, bits=8):
    qmin, qmax = -128, 127 if bits == 8 else (0, 255)
    scale = (w_f32.max() - w_f32.min()) / (qmax - qmin)
    zero_point = int(round(qmin - w_f32.min() / scale))
    w_q = np.clip(np.round(w_f32 / scale + zero_point), qmin, qmax).astype(np.int8)
    return w_q.tobytes(), np.float32(scale), np.int32(zero_point)

// conv_int8.wgsl 关键片段
struct QuantParams { scale: f32, zp: i32 };
@group(0) @binding(0) var<storage, read> w_q: array<i32>; // 打包为 i32 节省绑定槽位
@group(0) @binding(1) var<uniform> q_params: QuantParams;
@group(0) @binding(2) var<storage, read> input_f16: array<f16>; // 输入建议保持 FP16
@group(0) @binding(3) var<storage, read_write> acc_f32: array<f32>; // 累加器必须 FP32 防溢出

fn dequantize(q_val: i32) -> f32 {
    return (f32(q_val) - f32(q_params.zp)) * q_params.scale;
}

@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) gid: u32) {
    // ... 索引计算省略 ...
    var sum: f32 = 0.0;
    // 手动展开 4 元素利用标量替代 SIMD (当前 WGSL 无原生 dot4_i8)
    loop 4 times {
        let packed_w = w_q[weight_idx++];
        // 解包 4 个 int8 (假设小端序)
        let w0 = i32(packed_w & 0xFF) - 128;
        let w1 = i32((packed_w >> 8) & 0xFF) - 128;
        let w2 = i32((packed_w >> 16) & 0xFF) - 128;
        let w3 = i32((packed_w >> 24) & 0xFF) - 128;
        
        // 输入为 f16，转 f32 参与运算
        let in0 = f32(input_f16[input_idx++]);
        // ... in1, in2, in3 ...
        
        sum += f32(w0) * in0 + f32(w1) * in1 + f32(w2) * in2 + f32(w3) * in3;
    }
    // 累加偏置 (FP16/FP32)
    acc_f32[out_idx] = sum + f32(bias_f16[oc]);
}

// VideoFrameProcessor.js (运行在 Dedicated Worker)
class ZeroCopyProcessor {
  constructor(device, canvasContext) {
    this.device = device;
    this.context = canvasContext;
    // 预创建 RGBA8Unorm 存储纹理池 (3帧缓冲)
    this.storageTextures = this.createStorageTexturePool(3); 
    this.importIdx = 0;
  }

  async processFrame(videoFrame) {
    const gpuFrame = this.importIdx % 3;
    const extTex = this.device.importExternalTexture({
      source: videoFrame, // 直接传入 VideoFrame 对象
      colorSpace: 'srgb', // 或 'display-p3' 配合 HDR
    });

    // 关键：使用 Copy Pass 而非 Render Pass 进行 YUV->RGB+Write Storage
    // 优势：无顶点着色器开销，驱动层面可融合色域转换与平面合并
    const encoder = this.device.createCommandEncoder();
    const copyPass = encoder.beginComputePass(); // 或 RenderPass 配合 Fullscreen Triangle
    
    // 绑定外部纹理 (只读) 与目标存储纹理 (写入)
    copyPass.setPipeline(this.yuvToRgbaPipeline);
    copyPass.setBindGroup(0, this.bindGroups[gpuFrame], [extTex]); // 动态绑定 externalTexture
    copyPass.dispatchWorkgroups(...);
    copyPass.end();

    this.device.queue.submit([encoder.finish()]);
    videoFrame.close(); // 尽早释放解码器引用

    // 返回存储纹理视图供下游 SR Pipeline 直接读取
    return this.storageTextureViews[gpuFrame];
  }
}

// BandwidthEstimator 集成示例
class SRAdaptiveController {
  constructor(sender, srReceiver) {
    this.sender = sender;
    this.srReceiver = srReceiver; // 接收端 SR 能力上报对象
    this.currentTier = 'high'; // high / mid / low
  }

  onBandwidthChange(bps, rtt, pl) {
    const targetTier = this.calculateTier(bps, pl);
    if (targetTier !== this.currentTier) {
      this.applyEncodingParams(targetTier);
      this.currentTier = targetTier;
    }
  }

  applyEncodingParams(tier) {
    const params = this.sender.getParameters();
    const encodings = params.encodings[0];
    
    switch(tier) {
      case 'high':
        encodings.scaleResolutionDownBy = 1.0;
        encodings.maxBitrate = 2500000;
        this.srReceiver.setSREnabled(false); // 关闭 SR 省电
        break;
      case 'mid':
        encodings.scaleResolutionDownBy = 2.0; // 发送 540p
        encodings.maxBitrate = 800000;
        this.srReceiver.setSREnabled(true, 2.0); // 开启 2x SR
        break;
      case 'low':
        encodings.scaleResolutionDownBy = 3.0; // 发送 360p
        encodings.maxBitrate = 300000;
        encodings.maxFramerate = 30; // 保持高帧率供帧插值
        this.srReceiver.setSREnabled(true, 2.0); 
        this.srReceiver.enableFrameInterpolation(true);
        break;
    }
    this.sender.setParameters(params);
  }
}

graph TD
    Main[主线程<br/>UI / Signaling / WebRTC API] -->|MessagePort / postMessage| Worker[渲染/推理 Worker<br/>OffscreenCanvas + WebGPU]
    Worker -->|VideoFrame / EncodedVideoChunk| DecoderWorker[解码 Worker<br/>WebCodecs VideoDecoder]
    DecoderWorker -->|VideoFrame| Worker
    Worker -->|GPU Texture / Readback| Main

// worker.js
const canvas = self.offscreenCanvas; // 从主线程 transferControlToOffscreen() 传入
const context = canvas.getContext('webgpu');
const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
const device = await adapter.requestDevice({ requiredFeatures: ['timestamp-query', 'shader-f16'] });
context.configure({ device, format: 'rgba8unorm', alphaMode: 'premultiplied' });
// 后续所有 device 操作均在 Worker 完成

// Decoder Worker -> Render Worker
// VideoFrame 是可序列化对象，结构化克隆算法会转移底层像素缓冲区所有权，无拷贝
renderWorkerPort.postMessage({ type: 'frame', frame }, [frame]); 

// Render Worker 接收
self.onmessage = (e) => {
  if (e.data.type === 'frame') {
    const videoFrame = e.data.frame; // 直接可用
    processor.processFrame(videoFrame);
  }
};

// 仅在需要录制/截图时触发，避免常态化回读杀性能
async function readbackForRecording(storageTextureView) {
  const buffer = device.createBuffer({
    size: width * height * 4,
    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
  });
  const encoder = device.createCommandEncoder();
  encoder.copyTextureToBuffer(
    { texture: storageTextureView.texture },
    { buffer, bytesPerRow: width * 4 },
    { width, height }
  );
  device.queue.submit([encoder.finish()]);
  await buffer.mapAsync(GPUMapMode.READ);
  const pixels = new Uint8Array(buffer.getMappedRange());
  buffer.unmap();
  return pixels; // 发送给主线程或 MediaRecorder Worker
}

# .github/workflows/webgpu-sr.yml
jobs:
  perf-test:
    runs-on: [self-hosted, gpu-adreno-730] # 标签路由到真机
    steps:
      - uses: actions/checkout@v4
      - name: Run Headless Test
        run: |
          node run-perf-test.js 
            --model=fsrcnn_x2_int8 
            --input=test_720p.y4m 
            --frames=300 
            --assert-p50-ms=12 
            --assert-p99-ms=20 
            --assert-memory-mb=150 
            --assert-fidelity-psnr=32.5