パフォーマンスとロバスト性 — 計測・コンテキストロスト

interface EXT_disjoint_timer_query_webgl2 {
  const GLenum QUERY_COUNTER_BITS_EXT      = 0x8864;
  const GLenum TIME_ELAPSED_EXT            = 0x88BF;
  const GLenum TIMESTAMP_EXT               = 0x8E28;
  const GLenum GPU_DISJOINT_EXT            = 0x8FBB;

  undefined queryCounterEXT(WebGLQuery query, GLenum target);
};

const ext = gl.getExtension('EXT_disjoint_timer_query_webgl2');
gl.getQuery(ext.TIME_ELAPSED_EXT, ext.QUERY_COUNTER_BITS_EXT); // → 64
gl.getQuery(ext.TIMESTAMP_EXT,    ext.QUERY_COUNTER_BITS_EXT); // → 0

const RING_SIZE = 4;
/** 移動平均の窓。読み出し行の rAF 間隔と同じ本数にしてある */
const SAMPLE_LIMIT = 30;

interface Slot {
  query: WebGLQuery;
  /** beginQuery 済みで、まだ結果を読んでいない */
  pending: boolean;
  /** この計測の区間に disjoint が起きた。結果が揃っても捨てる */
  spoiled: boolean;
}

    begin(): void {
      // 同時に 1 本だけという制約。end() を呼び忘れた場合もここで止まる
      if (active) return;
      const slot = slots.find((candidate) => !candidate.pending);
      // 全部飛んでいるフレームは測らない。無理に測るより穴が空くほうが安全
      if (!slot) return;
      slot.pending = true;
      slot.spoiled = false;
      active = slot;
      gl.beginQuery(ext.TIME_ELAPSED_EXT, slot.query);
    },

    end(): void {
      if (!active) return;
      gl.endQuery(ext.TIME_ELAPSED_EXT);
      active = null;
    },

    poll(): void {
      // 先に disjoint を見る。真なら、いま飛んでいる計測は全部信用できない
      if (gl.getParameter(ext.GPU_DISJOINT_EXT)) {
        for (const slot of slots) {
          if (slot.pending) slot.spoiled = true;
        }
      }
      for (const slot of slots) {
        if (!slot.pending || slot === active) continue;
        // 揃っていなければ次のフレームに持ち越す。ここでループして待つのは無意味で、
        // 仕様が「制御をユーザーエージェントへ返すまで結果は揃わない」と定めている
        if (!gl.getQueryParameter(slot.query, gl.QUERY_RESULT_AVAILABLE)) continue;
        const nanoseconds = gl.getQueryParameter(slot.query, gl.QUERY_RESULT) as number;
        slot.pending = false;
        if (slot.spoiled) {
          slot.spoiled = false;
          discarded++;
          continue;
        }
        samples.push(nanoseconds / 1e6);
        if (samples.length > SAMPLE_LIMIT) samples.shift();
      }
    },

      // ここからここまでが GPU 時間の計測区間。clear も入れてある
      timer.begin();
      gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
      gl.bindVertexArray(resources.vao);
      gl.drawElementsInstanced(
        gl.TRIANGLES,
        resources.indexCount,
        gl.UNSIGNED_SHORT,
        0,
        instanceCount,
      );
      gl.bindVertexArray(null);
      timer.end();
      // 揃っているものだけ回収する。ここで待つことはできない(本文 2 節)
      timer.poll();

    const delta = timestamp - lastTimestamp;
    if (lastTimestamp !== 0 && delta < 200) {
      frameTimes.push(delta);
      if (frameTimes.length > FRAME_SAMPLES) frameTimes.shift();
    }
    lastTimestamp = timestamp;

  function resizeIfNeeded(): void {
    // dpr のクランプ(第2章 4 節)の上に、さらに倍率を掛ける。これが 5 節の「一番効くつまみ」
    const dpr = Math.min(window.devicePixelRatio, MAX_DPR);
    const width = Math.max(1, Math.floor(canvas.clientWidth * dpr * resolutionScale));
    const height = Math.max(1, Math.floor(canvas.clientHeight * dpr * resolutionScale));
    if (canvas.width !== width || canvas.height !== height) {
      canvas.width = width;
      canvas.height = height;
      // viewport も必ずセットで切り替える。既定値は canvas の初期サイズ(300×150)のまま
      gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
    }
  }

  float wobble = 0.0;
  for (int i = 0; i < u_vertexWork; i++) {
    float k = float(i) + 1.0;
    wobble += sin(dot(worldPosition, vec3(k, k * 1.3, k * 0.7)) + u_time) / k;
  }
  worldPosition += normal * (wobble * 0.01 * u_scale);

  float extra = 0.0;
  for (int i = 0; i < u_fragmentWork; i++) {
    float k = float(i) + 1.0;
    extra += sin(dot(v_worldPosition, vec3(k * 0.9, k * 1.7, k * 1.1)) + u_time) / k;
  }
  color *= 1.0 + 0.03 * extra;

function createResources(gl: WebGL2RenderingContext, geometry: Geometry): Resources {
  const program = linkProgram(
    gl,
    compileShader(gl, gl.VERTEX_SHADER, vertexSource),
    compileShader(gl, gl.FRAGMENT_SHADER, resolveIncludes(fragmentTemplate)),
  );

  // --- CPU 側のデータ。コンテキストがロストしても生き残る -------------------------
  // 1 体 45 頂点・192 インデックス。5 万体を回すので粗くしてある
  const geometry = createSphere(0.5, 8, 4);

  // --- GPU 側。ロストしたらまるごと作り直す ---------------------------------------
  let resources: Resources | null = createResources(gl, geometry);
  let timer: GpuTimer = createGpuTimer(gl);

  canvas.addEventListener('webglcontextlost', (event) => {
    // これを呼ばないと webglcontextrestored は来ない。仕様は
    // 「イベントの canceled フラグが立っていなければ以降の手順を中止する」と書いている
    event.preventDefault();
    lostAt = performance.now();
    // GPU 側のものは全部無効になった。参照を捨てるだけで、deleteXxx は呼ばない —
    // 無効化されたオブジェクトは、復帰後に引数として渡すと INVALID_OPERATION になる
    // (WebGL 1.0 仕様。ロスト中は既定値が返るだけでエラーにはならない)。持ち越さないのが安全
    resources = null;
    timer = createGpuTimer(gl); // ロスト中なので中身は空のタイマーになる
    resetFrameSamples();
    updateReadout();
    buildOptionButtons();
  });

  canvas.addEventListener('webglcontextrestored', () => {
    // ここが「usably restored」になる最初の場所(WEBGL_lose_context の restoreContext の項)。
    // 拡張は復元されないので、タイマークエリも取り直す
    resources = createResources(gl, geometry);
    timer = createGpuTimer(gl);
    resetFrameSamples();

    // ロスト中はループを止めずに描画だけ飛ばす。止めてしまうと、復帰したときに
    // 誰がループを再開するのかを別に考えることになる(本文 8 節)
    if (resources && !gl.isContextLost()) {

// 第35章: パフォーマンスとロバスト性 — 計測・コンテキストロスト
//
// 1 つのシーン(インスタンシングした球)に、つまみを 3 つ付けてある。
//   ① インスタンス数        100 / 1,000 / 10,000 / 50,000
//   ② 追加の仕事の置き場所  なし / 頂点 / フラグメント / 両方
//   ③ 解像度スケール        1.0 / 0.75 / 0.5 / 0.25
// デモ 1〜3 は、このうち 1 つだけを動かせるようにしたもの。デモに入るときに
// 3 つとも既定値へ戻すので、「いま何を測っているか」が読み出し行だけで言える。
//
// デモ 4 はコンテキストロストと復帰。このページの唯一のコンテキストを壊すので、
// GPU 側のものは全部 createResources() 1 か所で作り、復帰時にもう一度呼ぶだけで
// 戻るようにしてある(本文 8 節)。CPU 側のデータ(ジオメトリ・カメラ・つまみ)は
// ロストしても生き残るので、作り直すのは GPU 側だけ。
//
// この章は、この本で GPU 時間を出す唯一の章。測定条件は読み出し行に全部出している。

import { mat4, type ReadonlyVec3, vec3 } from 'gl-matrix';
import { createSphere, type Geometry, interleave } from '../../lib/geometry';
import { compileShader, linkProgram } from '../../lib/shader';
import colorChunkSource from './color.glsl?raw';
import { createGpuTimer, type GpuTimer } from './gpu-timer';
import fragmentTemplate from './scene.frag?raw';
import vertexSource from './scene.vert?raw';

// #include の解決は第23章からの文字列置換。置換文字列を関数で渡しているのは、
// String.replace が `$&` などを特別扱いするため
function resolveIncludes(source: string): string {
  return source.replace('#include "color.glsl"', () => colorChunkSource.trim());
}

// ---------------------------------------------------------------------------
// 定数
// ---------------------------------------------------------------------------

// カメラ定数(第3部の標準): fovy 45°・near 0.1・far 100
const FOVY = (45 * Math.PI) / 180;
const NEAR = 0.1;
const FAR = 100;

const FLOAT_BYTES = Float32Array.BYTES_PER_ELEMENT;

const UP: ReadonlyVec3 = vec3.fromValues(0, 1, 0);
const TARGET: ReadonlyVec3 = vec3.fromValues(0, 0, 0);
// 面から光源へ向かう単位ベクトル(第17章の約束)
const LIGHT_DIRECTION: ReadonlyVec3 = vec3.normalize(
  vec3.create(),
  vec3.fromValues(0.4, 0.75, 0.52),
);
// どちらもリニア値。出す直前に scene.frag が sRGB へ変換する(第27章)
const COLOR_INNER: ReadonlyVec3 = vec3.fromValues(0.85, 0.42, 0.14);
const COLOR_OUTER: ReadonlyVec3 = vec3.fromValues(0.09, 0.24, 0.62);

// 球を散らす範囲の半径(ワールド)
const BALL_RADIUS = 5.2;
// 1 体の基準の大きさ。実際にはここに (REFERENCE_COUNT / count)^(1/3) を掛ける
const REFERENCE_COUNT = 1000;
const REFERENCE_SCALE = 0.32;

// 追加の仕事の反復回数。頂点側とフラグメント側で別々に持つ
const VERTEX_WORK = 96;
const FRAGMENT_WORK = 64;

// devicePixelRatio の上限(第2章 4 節)。解像度スケールはこの上からさらに掛ける
const MAX_DPR = 2;

// 移動平均の窓。gpu-timer.ts の SAMPLE_LIMIT と同じ本数にしてある
const FRAME_SAMPLES = 30;

type WorkMode = 'none' | 'vertex' | 'fragment' | 'both';

const WORK_LABELS: Record<WorkMode, string> = {
  none: 'なし',
  vertex: '頂点',
  fragment: 'フラグメント',
  both: '両方',
};

function vertexWorkOf(mode: WorkMode): number {
  return mode === 'vertex' || mode === 'both' ? VERTEX_WORK : 0;
}

function fragmentWorkOf(mode: WorkMode): number {
  return mode === 'fragment' || mode === 'both' ? FRAGMENT_WORK : 0;
}

// ---------------------------------------------------------------------------
// GPU 側のリソース(コンテキストロストで全部無効になるもの)
// ---------------------------------------------------------------------------

interface SceneLocations {
  view: WebGLUniformLocation | null;
  projection: WebGLUniformLocation | null;
  time: WebGLUniformLocation | null;
  count: WebGLUniformLocation | null;
  ballRadius: WebGLUniformLocation | null;
  scale: WebGLUniformLocation | null;
  vertexWork: WebGLUniformLocation | null;
  lightDirection: WebGLUniformLocation | null;
  cameraPosition: WebGLUniformLocation | null;
  colorInner: WebGLUniformLocation | null;
  colorOuter: WebGLUniformLocation | null;
  fragmentWork: WebGLUniformLocation | null;
}

interface Resources {
  program: WebGLProgram;
  locations: SceneLocations;
  vao: WebGLVertexArrayObject;
  indexCount: number;
  /** 読み出し行に出す「このレンダラで測った」の材料 */
  renderer: string;
}

/**
 * レンダラ名。WEBGL_debug_renderer_info は取れないことがある(拡張仕様自身が
 * 「実装はフィンガープリンティング対策として値を伏せることがある」と書いている)ので、
 * 取れなかったらコアの RENDERER に落とす。それも空なら諦める(本文 2 節)。
 * どのブラウザがどれだけ伏せるかは調べていない
 */
function readRendererName(gl: WebGL2RenderingContext): string {
  const info = gl.getExtension('WEBGL_debug_renderer_info');
  if (info) {
    const unmasked = gl.getParameter(info.UNMASKED_RENDERER_WEBGL);
    if (typeof unmasked === 'string' && unmasked.length > 0) return unmasked;
  }
  const generic = gl.getParameter(gl.RENDERER);
  return typeof generic === 'string' && generic.length > 0 ? generic : '不明';
}

/**
 * GPU 側のものを全部ここで作る。コンテキストが復帰したら、もう一度これを呼ぶだけで戻る。
 * 「作る手続きが 1 か所にまとまっていること」がロスト対応の設計の要点(本文 8 節)
 */
function createResources(gl: WebGL2RenderingContext, geometry: Geometry): Resources {
  const program = linkProgram(
    gl,
    compileShader(gl, gl.VERTEX_SHADER, vertexSource),
    compileShader(gl, gl.FRAGMENT_SHADER, resolveIncludes(fragmentTemplate)),
  );

  const at = (name: string): WebGLUniformLocation | null => gl.getUniformLocation(program, name);
  const locations: SceneLocations = {
    view: at('u_view'),
    projection: at('u_projection'),
    time: at('u_time'),
    count: at('u_count'),
    ballRadius: at('u_ballRadius'),
    scale: at('u_scale'),
    vertexWork: at('u_vertexWork'),
    lightDirection: at('u_lightDirection'),
    cameraPosition: at('u_cameraPosition'),
    colorInner: at('u_colorInner'),
    colorOuter: at('u_colorOuter'),
    fragmentWork: at('u_fragmentWork'),
  };

  const vbo = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
  gl.bufferData(gl.ARRAY_BUFFER, interleave(geometry), gl.STATIC_DRAW);
  const ibo = gl.createBuffer();
  gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
  gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, geometry.indices, gl.STATIC_DRAW);

  const vao = gl.createVertexArray();
  gl.bindVertexArray(vao);
  const stride = 8 * FLOAT_BYTES; // interleave() は [位置 3, 法線 3, UV 2](第14章)
  gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
  gl.enableVertexAttribArray(0);
  gl.vertexAttribPointer(0, 3, gl.FLOAT, false, stride, 0);
  gl.enableVertexAttribArray(1);
  gl.vertexAttribPointer(1, 3, gl.FLOAT, false, stride, 3 * FLOAT_BYTES);
  // UV は使わないので配線しない
  gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
  gl.bindVertexArray(null);
  gl.bindBuffer(gl.ARRAY_BUFFER, null);
  gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, null);

  // コンテキストの状態も作り直す。WebGL 1.0 仕様の復帰の手順が明記しているのは
  // 「描画バッファを作り直す」「エラー状態をリセットする」「オブジェクトは全部無効」
  // 「拡張は復元されない」の 4 つで、gl.enable などをどう戻すかは、手順のあとの注記が
  // 「アプリケーションは変更した状態を全部戻したくなるだろう」と書いているだけ。
  // だから初期値に戻る前提で書き直しておく(本文 8 節)
  gl.enable(gl.DEPTH_TEST);
  gl.enable(gl.CULL_FACE); // geometry.ts の三角形は外から見て CCW(第14章)
  gl.clearColor(0.06, 0.07, 0.09, 1.0);
  gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);

  // ジオメトリのバッファは VAO が参照し続けるので、ここで deleteBuffer を呼んでも
  // 実体は消えない(ES 3.0.6 Appendix D.1.3)。とはいえ紛らわしいので呼ばない。
  // このデモは VAO ごと作り直すことがないため、7 節の表でいう「作りっぱなし」に当たる

  return {
    program,
    locations,
    vao,
    indexCount: geometry.indices.length,
    renderer: readRendererName(gl),
  };
}

// ---------------------------------------------------------------------------
// デモ
// ---------------------------------------------------------------------------

interface OptionButton {
  label: string;
  isActive: () => boolean;
  select: () => void;
}

interface Demo {
  id: string;
  label: string;
  /** このデモに入るときに 3 つのつまみをここへ戻す */
  preset: { count: number; work: WorkMode; scale: number };
  options: () => OptionButton[];
  note: string;
}

// ---------------------------------------------------------------------------
// デモ本体
// ---------------------------------------------------------------------------

function setup(
  gl: WebGL2RenderingContext,
  canvas: HTMLCanvasElement,
  demoControls: HTMLParagraphElement,
  optionControls: HTMLParagraphElement,
  readout: HTMLParagraphElement,
): void {
  // --- CPU 側のデータ。コンテキストがロストしても生き残る -------------------------
  // 1 体 45 頂点・192 インデックス。5 万体を回すので粗くしてある
  const geometry = createSphere(0.5, 8, 4);

  // --- GPU 側。ロストしたらまるごと作り直す ---------------------------------------
  let resources: Resources | null = createResources(gl, geometry);
  let timer: GpuTimer = createGpuTimer(gl);

  // --- 3 つのつまみ ---------------------------------------------------------------
  let instanceCount = 1000;
  let workMode: WorkMode = 'none';
  let resolutionScale = 1;

  // --- 軌道カメラ(第15章。第23章 main.ts と同じ形) -------------------------------

  const orbit = { theta: 0.7, phi: 0.35, radius: 15 };
  const PHI_LIMIT = Math.PI / 2 - 0.05;
  const MIN_RADIUS = 7;
  const MAX_RADIUS = 40;

  let dragging = false;
  let activePointerId: number | null = null;
  let lastX = 0;
  let lastY = 0;

  canvas.addEventListener('pointerdown', (event) => {
    if (event.button !== 0) return;
    dragging = true;
    activePointerId = event.pointerId;
    lastX = event.clientX;
    lastY = event.clientY;
    canvas.setPointerCapture(event.pointerId);
  });

  canvas.addEventListener('pointermove', (event) => {
    if (!dragging || event.pointerId !== activePointerId) return;
    const speed = (2 * Math.PI) / canvas.clientHeight;
    orbit.theta -= (event.clientX - lastX) * speed;
    orbit.phi += (event.clientY - lastY) * speed;
    orbit.phi = Math.min(PHI_LIMIT, Math.max(-PHI_LIMIT, orbit.phi));
    lastX = event.clientX;
    lastY = event.clientY;
  });

  function endDrag(event: PointerEvent): void {
    if (event.pointerId !== activePointerId) return;
    dragging = false;
    activePointerId = null;
    if (canvas.hasPointerCapture(event.pointerId)) {
      canvas.releasePointerCapture(event.pointerId);
    }
  }
  canvas.addEventListener('pointerup', endDrag);
  canvas.addEventListener('pointercancel', endDrag);

  canvas.addEventListener(
    'wheel',
    (event) => {
      event.preventDefault();
      const scale = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? 100 : 1;
      orbit.radius *= Math.exp(event.deltaY * scale * 0.001);
      orbit.radius = Math.min(MAX_RADIUS, Math.max(MIN_RADIUS, orbit.radius));
    },
    { passive: false },
  );

  // --- コンテキストロスト(デモ 4) ------------------------------------------------

  // この拡張だけは、ロストしても無効化されない(WebGL 1.0 仕様「The Context Lost Event」の
  // 「WEBGL_lose_context 以外のすべての拡張を無効にする」)。だから参照を持ち続けてよい
  const loseContextExtension = gl.getExtension('WEBGL_lose_context');

  /** ロストしていた合計時間の記録。読み出し行に出す */
  let lostAt: number | null = null;
  let lastLostDurationMs: number | null = null;
  let restoreCount = 0;

  canvas.addEventListener('webglcontextlost', (event) => {
    // これを呼ばないと webglcontextrestored は来ない。仕様は
    // 「イベントの canceled フラグが立っていなければ以降の手順を中止する」と書いている
    event.preventDefault();
    lostAt = performance.now();
    // GPU 側のものは全部無効になった。参照を捨てるだけで、deleteXxx は呼ばない —
    // 無効化されたオブジェクトは、復帰後に引数として渡すと INVALID_OPERATION になる
    // (WebGL 1.0 仕様。ロスト中は既定値が返るだけでエラーにはならない)。持ち越さないのが安全
    resources = null;
    timer = createGpuTimer(gl); // ロスト中なので中身は空のタイマーになる
    resetFrameSamples();
    updateReadout();
    buildOptionButtons();
  });

  canvas.addEventListener('webglcontextrestored', () => {
    // ここが「usably restored」になる最初の場所(WEBGL_lose_context の restoreContext の項)。
    // 拡張は復元されないので、タイマークエリも取り直す
    resources = createResources(gl, geometry);
    timer = createGpuTimer(gl);
    resetFrameSamples();
    if (lostAt !== null) {
      lastLostDurationMs = performance.now() - lostAt;
      lostAt = null;
    }
    restoreCount++;
    updateReadout();
    buildOptionButtons();
  });

  // --- デモ 4 本 -------------------------------------------------------------------

  const countOption = (value: number): OptionButton => ({
    label: `${value.toLocaleString('en-US')} 体`,
    isActive: () => instanceCount === value,
    select: () => {
      instanceCount = value;
      resetSamples();
    },
  });

  const workOption = (mode: WorkMode): OptionButton => ({
    label: WORK_LABELS[mode],
    isActive: () => workMode === mode,
    select: () => {
      workMode = mode;
      resetSamples();
    },
  });

  const scaleOption = (value: number): OptionButton => ({
    label: value.toFixed(2),
    isActive: () => resolutionScale === value,
    select: () => {
      resolutionScale = value;
      resetSamples();
    },
  });

  const demos: readonly Demo[] = [
    {
      id: 'load',
      label: '1. 負荷を上げる',
      preset: { count: 1000, work: 'none', scale: 1 },
      options: () => [countOption(100), countOption(1000), countOption(10000), countOption(50000)],
      note: '体数だけを変える。1 体の大きさは count^(-1/3) に比例(体積の総和は一定・投影面積の総和は count^(1/3) で増える)',
    },
    {
      id: 'where',
      label: '2. どこが重いのか',
      preset: { count: 10000, work: 'none', scale: 1 },
      options: () => [
        workOption('none'),
        workOption('vertex'),
        workOption('fragment'),
        workOption('both'),
      ],
      note: '同じ絵のまま、追加の反復を頂点側とフラグメント側に置き分ける',
    },
    {
      id: 'resolution',
      label: '3. 解像度スケール',
      preset: { count: 10000, work: 'fragment', scale: 1 },
      options: () => [scaleOption(1), scaleOption(0.75), scaleOption(0.5), scaleOption(0.25)],
      note: 'CSS サイズはそのままで、描画バッファだけを縮める。ピクセル数は倍率の 2 乗',
    },
    {
      id: 'lost',
      label: '4. コンテキストロスト',
      preset: { count: 1000, work: 'none', scale: 1 },
      options: () => [
        {
          label: 'ロストさせる',
          isActive: () => gl.isContextLost(),
          select: () => {
            if (!loseContextExtension || gl.isContextLost()) return;
            loseContextExtension.loseContext();
          },
        },
        {
          label: '復帰させる',
          isActive: () => !gl.isContextLost(),
          select: () => {
            if (!loseContextExtension || !gl.isContextLost()) return;
            loseContextExtension.restoreContext();
          },
        },
      ],
      note: 'ページの唯一のコンテキストを壊して、戻す',
    },
  ];

  let current = demos[0];

  // --- 切替ボタン(第31章と同じ作り) ----------------------------------------------

  for (const demo of demos) {
    const button = document.createElement('button');
    button.type = 'button';
    button.textContent = demo.label;
    button.setAttribute('aria-pressed', demo === current ? 'true' : 'false');
    button.addEventListener('click', () => {
      current = demo;
      // つまみを既定へ戻す。戻さないと「前のデモで動かしたつまみ」が残って、
      // 読み出し行の値がどの条件のものか言えなくなる
      instanceCount = demo.preset.count;
      workMode = demo.preset.work;
      resolutionScale = demo.preset.scale;
      resetSamples();
      for (const other of demoControls.querySelectorAll('button')) {
        other.setAttribute('aria-pressed', 'false');
      }
      button.setAttribute('aria-pressed', 'true');
      buildOptionButtons();
    });
    demoControls.append(button);
  }

  /** デモを切り替えるたびにオプション行を作り直す */
  function buildOptionButtons(): void {
    optionControls.replaceChildren();
    const options = current.options();
    optionControls.hidden = options.length === 0;
    for (const option of options) {
      const button = document.createElement('button');
      button.type = 'button';
      button.textContent = option.label;
      button.setAttribute('aria-pressed', option.isActive() ? 'true' : 'false');
      button.addEventListener('click', () => {
        option.select();
        // 押した結果を状態から読み直す。デモ 4 の 2 つは「押しても状態が変わらない」
        // ことがある(ロスト中に「ロストさせる」を押した場合など)
        optionControls.querySelectorAll('button').forEach((other, index) => {
          other.setAttribute('aria-pressed', options[index].isActive() ? 'true' : 'false');
        });
      });
      optionControls.append(button);
    }
  }
  buildOptionButtons();

  // --- リサイズと解像度スケール -----------------------------------------------------

  /** いま実際に使っている描画バッファのサイズ。読み出し行が読む */
  function resizeIfNeeded(): void {
    // dpr のクランプ(第2章 4 節)の上に、さらに倍率を掛ける。これが 5 節の「一番効くつまみ」
    const dpr = Math.min(window.devicePixelRatio, MAX_DPR);
    const width = Math.max(1, Math.floor(canvas.clientWidth * dpr * resolutionScale));
    const height = Math.max(1, Math.floor(canvas.clientHeight * dpr * resolutionScale));
    if (canvas.width !== width || canvas.height !== height) {
      canvas.width = width;
      canvas.height = height;
      // viewport も必ずセットで切り替える。既定値は canvas の初期サイズ(300×150)のまま
      gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
    }
  }

  // --- 読み出し行 -------------------------------------------------------------------

  const frameTimes: number[] = [];
  let lastTimestamp = 0;
  let lastReadoutAt = 0;

  function resetFrameSamples(): void {
    frameTimes.length = 0;
  }

  /** CPU 側と GPU 側、両方の移動平均を捨てる。条件を変えたら必ず呼ぶ */
  function resetSamples(): void {
    resetFrameSamples();
    timer.reset();
  }

  function averageFrameMs(): number | null {
    if (frameTimes.length === 0) return null;
    let total = 0;
    for (const value of frameTimes) total += value;
    return total / frameTimes.length;
  }

  function updateReadout(): void {
    const n = (value: number): string => value.toLocaleString('en-US');
    if (!resources || gl.isContextLost()) {
      readout.textContent =
        'コンテキストはロスト中です。GPU 側のオブジェクトはすべて無効で、描画はスキップしています。' +
        '「復帰させる」を押すと createResources() をもう一度呼んでシーンを組み直します(本文 8 節)';
      return;
    }
    const frameMs = averageFrameMs();
    const gpuMs = timer.averageMs();
    const gpuText = !timer.supported
      ? 'GPU 時間 拡張なし'
      : gpuMs === null
        ? 'GPU 時間 —(まだ結果が揃っていません)'
        : `GPU 時間 ${gpuMs.toFixed(2)} ms(${timer.sampleCount()} 標本の移動平均・disjoint で捨てた計測 ${timer.discardedCount()} 回)`;
    const pixels = gl.drawingBufferWidth * gl.drawingBufferHeight;
    const restored =
      lastLostDurationMs === null
        ? ''
        : ` / 復帰 ${restoreCount} 回(直近のロストは ${(lastLostDurationMs / 1000).toFixed(1)} 秒)`;
    readout.textContent =
      `${current.note} / 球 ${n(instanceCount)} 体 / ドローコール 1 回 / ` +
      `頂点 ${n(resources.indexCount)} × ${n(instanceCount)} = ${n(resources.indexCount * instanceCount)} / ` +
      `描画バッファ ${gl.drawingBufferWidth}×${gl.drawingBufferHeight} = ${n(pixels)} px` +
      `(倍率 ${resolutionScale.toFixed(2)} / dpr 上限 ${MAX_DPR})/ ` +
      `追加の反復 ${WORK_LABELS[workMode]}(頂点 ${vertexWorkOf(workMode)} 回・フラグメント ${fragmentWorkOf(workMode)} 回)/ ` +
      `${gpuText} / ` +
      `rAF 間隔 ${frameMs === null ? '—' : `${frameMs.toFixed(1)} ms`}(CPU 側。表示のリフレッシュ間隔に張り付いていないかは 3 節)/ ` +
      `レンダラ ${resources.renderer}${restored}`;
  }

  // --- 毎フレーム使い回す入れ物 -----------------------------------------------------

  const eye = vec3.create();
  const view = mat4.create();
  const projection = mat4.create();

  // --- 描画ループ -------------------------------------------------------------------

  function frame(timestamp: DOMHighResTimeStamp): void {
    // rAF の間隔。タブが裏に回っているあいだ rAF は止まるので、復帰直後の巨大な差分は
    // 平均に混ぜない(計測ではなく、単に呼ばれなかっただけなので。本文 3 節)
    const delta = timestamp - lastTimestamp;
    if (lastTimestamp !== 0 && delta < 200) {
      frameTimes.push(delta);
      if (frameTimes.length > FRAME_SAMPLES) frameTimes.shift();
    }
    lastTimestamp = timestamp;

    // ロスト中はループを止めずに描画だけ飛ばす。止めてしまうと、復帰したときに
    // 誰がループを再開するのかを別に考えることになる(本文 8 節)
    if (resources && !gl.isContextLost()) {
      resizeIfNeeded();
      const time = timestamp / 1000;
      const scale = REFERENCE_SCALE * (REFERENCE_COUNT / instanceCount) ** (1 / 3);

      eye[0] = orbit.radius * Math.cos(orbit.phi) * Math.sin(orbit.theta);
      eye[1] = orbit.radius * Math.sin(orbit.phi);
      eye[2] = orbit.radius * Math.cos(orbit.phi) * Math.cos(orbit.theta);
      mat4.lookAt(view, eye, TARGET, UP);
      const aspect = gl.drawingBufferWidth / gl.drawingBufferHeight;
      mat4.perspective(projection, FOVY, aspect, NEAR, FAR);

      const { locations } = resources;
      gl.useProgram(resources.program);
      gl.uniformMatrix4fv(locations.view, false, view); // transpose は常に false
      gl.uniformMatrix4fv(locations.projection, false, projection);
      gl.uniform1f(locations.time, time);
      gl.uniform1f(locations.count, instanceCount);
      gl.uniform1f(locations.ballRadius, BALL_RADIUS);
      gl.uniform1f(locations.scale, scale);
      gl.uniform1i(locations.vertexWork, vertexWorkOf(workMode));
      gl.uniform1i(locations.fragmentWork, fragmentWorkOf(workMode));
      gl.uniform3f(
        locations.lightDirection,
        LIGHT_DIRECTION[0],
        LIGHT_DIRECTION[1],
        LIGHT_DIRECTION[2],
      );
      gl.uniform3f(locations.cameraPosition, eye[0], eye[1], eye[2]);
      gl.uniform3f(locations.colorInner, COLOR_INNER[0], COLOR_INNER[1], COLOR_INNER[2]);
      gl.uniform3f(locations.colorOuter, COLOR_OUTER[0], COLOR_OUTER[1], COLOR_OUTER[2]);

      // ここからここまでが GPU 時間の計測区間。clear も入れてある
      timer.begin();
      gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
      gl.bindVertexArray(resources.vao);
      gl.drawElementsInstanced(
        gl.TRIANGLES,
        resources.indexCount,
        gl.UNSIGNED_SHORT,
        0,
        instanceCount,
      );
      gl.bindVertexArray(null);
      timer.end();
      // 揃っているものだけ回収する。ここで待つことはできない(本文 2 節)
      timer.poll();
    }

    if (timestamp - lastReadoutAt > 250) {
      updateReadout();
      lastReadoutAt = timestamp;
    }
    requestAnimationFrame(frame);
  }

  // このページのデモはページと寿命を共にするので、rAF ループの停止もリスナーの解除も
  // していない。この章の 7 節が扱っているのは、まさにこの行のことです
  requestAnimationFrame(frame);
}

// ---------------------------------------------------------------------------
// 要素とコンテキストの取得
// ---------------------------------------------------------------------------

const canvas = document.querySelector<HTMLCanvasElement>('#demo');
const demoControls = document.querySelector<HTMLParagraphElement>('#demo-buttons');
const optionControls = document.querySelector<HTMLParagraphElement>('#option-buttons');
const readout = document.querySelector<HTMLParagraphElement>('#readout');
if (!canvas || !demoControls || !optionControls || !readout) {
  throw new Error('デモに必要な要素が見つかりません');
}

const gl = canvas.getContext('webgl2');
if (!gl) {
  throw new Error('このブラウザは WebGL2 に対応していません');
}

setup(gl, canvas, demoControls, optionControls, readout);

// 第35章: GPU 時間を測るためのリングバッファ(この章ローカル。src/lib へは上げない)
//
// EXT_disjoint_timer_query_webgl2 は「WebGL2 のコアのクエリ API に
// TIME_ELAPSED_EXT / TIMESTAMP_EXT / GPU_DISJOINT_EXT を足すだけ」の拡張で、
// createQuery / beginQuery / endQuery / getQueryParameter はコアのものを使う。
//
// この小さなモジュールが引き受けているのは、次の 3 つの約束(本文 2 節):
//
//  ① 結果は同じフレームでは絶対に取れない。WebGL 2.0 仕様が
//     「クエリの結果を、発行したフレームと同じフレームでアプリへ渡してはならない」と
//     定めている。だからクエリオブジェクトを 1 個で使い回すと、結果を読む前に
//     次の beginQuery で上書きすることになる → 何本かをリングにして順に使う
//  ② TIME_ELAPSED のクエリは同時に 1 本だけ。ES 3.0.6 §2.14 の BeginQuery は
//     「その target の active query が非ゼロなら INVALID_OPERATION」と定めていて、
//     EXT_disjoint_timer_query の Issue (6) も「複数のタイマークエリを同時には
//     実行できない」と書いている → 走っているあいだは begin() を素通りさせる
//  ③ GPU_DISJOINT_EXT が真なら、前回の問い合わせ以降に埋まった時間はすべて未定義。
//     捨てる。捨てた回数は読み出し行に出す
//
// 拡張が取れない環境では supported が false になり、他のメソッドは何もしない。

/** getExtension が返すオブジェクトのうち、この章で使う定数だけ */
interface TimerQueryExtension {
  TIME_ELAPSED_EXT: GLenum;
  GPU_DISJOINT_EXT: GLenum;
}

export interface GpuTimer {
  /** 拡張が取れたか。false なら begin / end / poll は何もしない */
  readonly supported: boolean;
  /** 計測区間の開始。空きスロットが無いフレームは黙って測らない */
  begin(): void;
  /** 計測区間の終了。begin が素通りしたフレームでは何もしない */
  end(): void;
  /** 揃った結果を回収する。フレームの終わりに 1 回だけ呼ぶ */
  poll(): void;
  /** 移動平均(ミリ秒)。まだ 1 本も揃っていなければ null */
  averageMs(): number | null;
  /** 平均に使っている標本の本数 */
  sampleCount(): number;
  /** disjoint で捨てた計測の累計 */
  discardedCount(): number;
  /** 移動平均の標本を捨てる(デモを切り替えたとき) */
  reset(): void;
}

/** 同時に飛ばせる計測の本数。結果は最短でも次のフレームなので、数フレームぶんあれば足りる */
const RING_SIZE = 4;
/** 移動平均の窓。読み出し行の rAF 間隔と同じ本数にしてある */
const SAMPLE_LIMIT = 30;

interface Slot {
  query: WebGLQuery;
  /** beginQuery 済みで、まだ結果を読んでいない */
  pending: boolean;
  /** この計測の区間に disjoint が起きた。結果が揃っても捨てる */
  spoiled: boolean;
}

/**
 * 拡張が取れなかったときに返す「何もしないタイマー」。
 * 呼ぶ側に if を撒かずに済ませるための空実装で、読み出し行だけが supported を見る
 */
function createNullTimer(): GpuTimer {
  return {
    supported: false,
    begin() {},
    end() {},
    poll() {},
    averageMs: () => null,
    sampleCount: () => 0,
    discardedCount: () => 0,
    reset() {},
  };
}

export function createGpuTimer(gl: WebGL2RenderingContext): GpuTimer {
  // 拡張が無い環境は珍しくない。ここで落とさずに、読み出し行に「拡張なし」と出す
  const ext = gl.getExtension('EXT_disjoint_timer_query_webgl2') as TimerQueryExtension | null;
  if (!ext) return createNullTimer();

  const slots: Slot[] = [];
  for (let i = 0; i < RING_SIZE; i++) {
    const query = gl.createQuery();
    if (!query) {
      // 途中で作れなくなったら、そこまでに作ったぶんを消してから諦める。
      // 「作りかけで投げ出さない」は 7 節の話そのもの
      for (const made of slots) gl.deleteQuery(made.query);
      return createNullTimer();
    }
    slots.push({ query, pending: false, spoiled: false });
  }

  // GPU_DISJOINT_EXT は「前回この問い合わせをしてから今までに disjoint が起きたか」を
  // 返すので、読むとクリアされる。測り始める前に 1 回読んで、それまでの分を落としておく
  // (EXT_disjoint_timer_query のサンプルコードがそうしている)
  gl.getParameter(ext.GPU_DISJOINT_EXT);

  let active: Slot | null = null;
  const samples: number[] = [];
  let discarded = 0;

  return {
    supported: true,

    begin(): void {
      // 同時に 1 本だけという制約。end() を呼び忘れた場合もここで止まる
      if (active) return;
      const slot = slots.find((candidate) => !candidate.pending);
      // 全部飛んでいるフレームは測らない。無理に測るより穴が空くほうが安全
      if (!slot) return;
      slot.pending = true;
      slot.spoiled = false;
      active = slot;
      gl.beginQuery(ext.TIME_ELAPSED_EXT, slot.query);
    },

    end(): void {
      if (!active) return;
      gl.endQuery(ext.TIME_ELAPSED_EXT);
      active = null;
    },

    poll(): void {
      // 先に disjoint を見る。真なら、いま飛んでいる計測は全部信用できない
      if (gl.getParameter(ext.GPU_DISJOINT_EXT)) {
        for (const slot of slots) {
          if (slot.pending) slot.spoiled = true;
        }
      }
      for (const slot of slots) {
        if (!slot.pending || slot === active) continue;
        // 揃っていなければ次のフレームに持ち越す。ここでループして待つのは無意味で、
        // 仕様が「制御をユーザーエージェントへ返すまで結果は揃わない」と定めている
        if (!gl.getQueryParameter(slot.query, gl.QUERY_RESULT_AVAILABLE)) continue;
        const nanoseconds = gl.getQueryParameter(slot.query, gl.QUERY_RESULT) as number;
        slot.pending = false;
        if (slot.spoiled) {
          slot.spoiled = false;
          discarded++;
          continue;
        }
        samples.push(nanoseconds / 1e6);
        if (samples.length > SAMPLE_LIMIT) samples.shift();
      }
    },

    averageMs(): number | null {
      if (samples.length === 0) return null;
      let total = 0;
      for (const value of samples) total += value;
      return total / samples.length;
    },

    sampleCount: () => samples.length,
    discardedCount: () => discarded,

    reset(): void {
      samples.length = 0;
    },
  };
}

#version 300 es

// 第35章: 負荷をつまみで変えられるシーン(インスタンシングした球)
//
// 位置は gl_InstanceID から作るので、per-instance 属性は 1 本も無い(第31章 5 節と同じ形)。
// インスタンス数を変えてもバッファを作り直さずに済むので、
// 「体数だけを変えて測る」がそのままできる。
//
// u_vertexWork が「頂点側だけを重くする」つまみ(本文 2 節・6 節)。

// 頂点言語の既定は precision highp float; / precision highp int;(GLSL ES 3.00 §4.5.4)なので、
// ここでの precision 文は「明示している」だけで、書かなくても同じ

precision highp float;
precision highp int;

layout(location = 0) in vec3 a_position;
layout(location = 1) in vec3 a_normal;

uniform mat4 u_view;
uniform mat4 u_projection;
uniform float u_time;
/** いま描いているインスタンス数 */
uniform float u_count;
/** 球を散らす範囲の半径(ワールド) */
uniform float u_ballRadius;
/** 球 1 個の大きさ。CPU 側で count^(-1/3) に比例させてある(本文 6 節) */
uniform float u_scale;
/** 追加で回す反復回数。0 なら 1 回も回らない */
uniform int u_vertexWork;

out vec3 v_normal;
out vec3 v_worldPosition;
/** 中心からの距離(0〜1)。色の混ぜ率に使う */
out float v_radial;

// 黄金角 π(3 − √5) と、それを 2π で割った比
const float GOLDEN_ANGLE = 2.399963229728653;

void main() {
  float index = float(gl_InstanceID);

  // 向きはフィボナッチ球。極角の cos を等分し、方位角を黄金角ずつ回す
  float cosPolar = 1.0 - 2.0 * (index + 0.5) / u_count;
  float sinPolar = sqrt(max(0.0, 1.0 - cosPolar * cosPolar));

  // 半径は向きと別の系列から取る。fract(index × 黄金比) は index が数万になると
  // float の刻み(2^24 分の 1 相当)に負けて段が出るので、整数の剰余で作る。
  // 7919 は奇素数で 65536 = 2^16 と互いに素なので、i → 7919i mod 65536 は
  // 0〜65535 を 1 回ずつ通る = 偏りが出ない
  int scrambled = (gl_InstanceID * 7919) % 65536;
  // 3 乗根は「球の体積で均す」ため。これを付けないと外側が薄くなる
  float radial = pow((float(scrambled) + 0.5) / 65536.0, 1.0 / 3.0);

  // 内側ほど速く回す。全体が同じ速さで回ると、カメラを回したのと区別がつかない
  float azimuth = index * GOLDEN_ANGLE + u_time * 0.5 / (0.35 + radial);

  vec3 center =
    u_ballRadius * radial * vec3(sinPolar * cos(azimuth), cosPolar, sinPolar * sin(azimuth));

  // モデル変換は「平行移動 + 一様スケール」だけなので、法線は変換しなくてよい。
  // 法線行列が要るのは非一様スケールや回転が入るとき(第17章)
  vec3 normal = a_normal;
  vec3 worldPosition = center + a_position * u_scale;

  // --- 頂点側のつまみ --------------------------------------------------------
  // 反復回数を uniform で持つので、コンパイラが展開して畳み込むことはできない。
  // 結果を位置に足しているのは、どこにも使われない値なら消してよいから(本文 6 節)。
  // wobble は sin(…)/k の和なので大きさは調和級数どまり(96 回で 5 強)。
  // 係数 0.01 を掛けて、球の半径の 1 割に届かない変位に抑えてある —
  // 0 ではないので、切り替えると形はわずかに変わる
  float wobble = 0.0;
  for (int i = 0; i < u_vertexWork; i++) {
    float k = float(i) + 1.0;
    wobble += sin(dot(worldPosition, vec3(k, k * 1.3, k * 0.7)) + u_time) / k;
  }
  worldPosition += normal * (wobble * 0.01 * u_scale);

  v_normal = normal;
  v_worldPosition = worldPosition;
  v_radial = radial;
  gl_Position = u_projection * u_view * vec4(worldPosition, 1.0);
}

#version 300 es

// 第35章: シーンのフラグメントシェーダー。
// ライティングは第17章の Blinn-Phong そのままで、この章の主題ではない。
// u_fragmentWork が「フラグメント側だけを重くする」つまみ(本文 2 節・6 節)。
//
// この章のシェーダーには discard が 1 つも無く、深度書き込みも切っていない。
// 6 節で early-Z の話をするときの前提がこれ。

precision highp float;
// 整数の既定は mediump(GLSL ES 3.00 §4.5.4)。u_fragmentWork の範囲は数十なので
// mediump の保証(±32767・§4.5.1)で足りる。ここを highp にする必要は無い

in vec3 v_normal;
in vec3 v_worldPosition;
in float v_radial;

/** 面から光源へ向かう単位ベクトル(第17章の約束) */
uniform vec3 u_lightDirection;
uniform vec3 u_cameraPosition;
/** 中心側・外側の色(どちらもリニア値) */
uniform vec3 u_colorInner;
uniform vec3 u_colorOuter;
uniform float u_time;
/** 追加で回す反復回数。0 なら 1 回も回らない */
uniform int u_fragmentWork;

out vec4 fragColor;

#include "color.glsl"

void main() {
  vec3 N = normalize(v_normal);
  vec3 L = u_lightDirection;
  vec3 V = normalize(u_cameraPosition - v_worldPosition);
  vec3 H = normalize(L + V);

  vec3 base = mix(u_colorInner, u_colorOuter, v_radial);
  float diffuse = max(dot(N, L), 0.0);
  float specular = pow(max(dot(N, H), 0.0), 48.0);
  vec3 color = base * (0.10 + 0.90 * diffuse) + vec3(0.30) * specular;

  // --- フラグメント側のつまみ ------------------------------------------------
  // 頂点側と同じ形。回数は uniform なので、束の中で分岐先が割れることはない
  // (このループは「割れる分岐」の例にはなっていない。本文 6 節)
  float extra = 0.0;
  for (int i = 0; i < u_fragmentWork; i++) {
    float k = float(i) + 1.0;
    extra += sin(dot(v_worldPosition, vec3(k * 0.9, k * 1.7, k * 1.1)) + u_time) / k;
  }
  color *= 1.0 + 0.03 * extra;

  // 出す直前に 1 回だけ sRGB へ(第27章)
  fragColor = vec4(linearToSrgb(color), 1.0);
}

// 第35章 出力の最後の 1 行のための色変換。
// 中身は第27章の src/lessons/27-color-and-palette/color.glsl からの複製(内容は同一)で、
// srgbToLinear / linearToSrgb の 2 関数だけを持ってきている。
// 片方を直したらもう片方も直すこと(第25→26章の noise.glsl と同じ流儀。理由は
// docs/plan.md の抽象化タイムライン: 読者が壊して遊ぶ対象なので章をまたいだ結合を作らない)。
//
// この章で使うのは linearToSrgb のほう。球の色はリニア値として組み立て、
// 画面へ出す直前にここでエンコードする。変換の体系そのものは第27章 2 節。

/**
 * sRGB エンコード値 → リニア値。
 * 出典: OpenGL ES 3.0.6 §3.8.16 式 (3.26)。GPU が sRGB テクスチャを読むときの変換そのもの。
 * 境界 (0.04045) では 2 つの式の差が 2.3e-9 しかないので、等号がどちら側かは問題にならない。
 */
vec3 srgbToLinear(vec3 c) {
  vec3 lo = c / 12.92;
  vec3 hi = pow((c + 0.055) / 1.055, vec3(2.4));
  return mix(lo, hi, step(vec3(0.04045), c));
}

/**
 * リニア値 → sRGB エンコード値。画面へ出す最後の 1 行はこれになる。
 * 出典: OpenGL ES 3.0.6 §4.1.8 式 (4.1)。仕様は指数を 0.41666 と書いているが、
 * これは 1/2.4 = 0.4166666… を打ち切った値で、8 ビット出力での差は最大 1 段。1/2.4 を使う。
 * 仕様の式は 0 以下と 1 以上を切り落とすので、clamp がその 2 本の枝にあたる。
 */
vec3 linearToSrgb(vec3 c) {
  c = clamp(c, 0.0, 1.0);
  vec3 lo = c * 12.92;
  vec3 hi = 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055;
  return mix(lo, hi, step(vec3(0.0031308), c));
}