Debugging WebGL: chrome://gpu, Spector.js та помилки шейдерів

1. Чому WebGL ламається тихо

На відміну від більшості JavaScript API, виклик функції WebGL з неправильним станом рідко кидає виключення, яке можна перехопити. Шейдер, що не скомпілювався, все одно повертає об'єкт шейдера, який виглядає валідним (але непридатний до використання). Текстура, прив'язана до неправильного юніта, не видає помилку — вона просто семплить чорний колір, сміття або неправильне зображення. Оскільки WebGL відображає дизайн C-API OpenGL, інформація про помилку зберігається у внутрішньому прапорці помилки, який потрібно опитувати (gl.getError()), а не у виключенні, яке можна перехопити.

Практичний наслідок: «нічого не рендериться» або «неправильний колір» можуть мати десяток різних першопричин без жодного stack trace, що вказує на будь-яку з них. Інструменти нижче існують саме для того, щоб зробити цей невидимий стан знову видимим.

2. chrome://gpu — статус драйвера й функцій

Перейдіть на chrome://gpu у Chrome (або about:support у Firefox) для повного діагностичного звіту ще до написання жодного рядка коду для налагодження. Таблиця «Graphics Feature Status» — перше, що варто перевірити — кожен рядок має бути Hardware accelerated:

Нижче таблиці функцій розділ «Problems Detected» перелічує саме ті помилки драйвера, які Chrome заблокував для вашої конкретної комбінації GPU/драйвер — корисно, щоб відрізнити «мій шейдер неправильний» від «у цього драйвера є відома помилка з цим конкретним розширенням».

3. Пошук реального GPU за ANGLE

gl.getParameter(gl.RENDERER) у Chrome зазвичай повертає загальний рядок на кшталт "ANGLE (Google, Vulkan 1.3.0...)" — не дуже корисно, щоб зрозуміти, який фізичний GPU насправді виконує ваші шейдери. Розширення WEBGL_debug_renderer_info відкриває реальні значення:

const gl = canvas.getContext('webgl2');
const ext = gl.getExtension('WEBGL_debug_renderer_info');

if (ext) {
  console.log('Vendor:', gl.getParameter(ext.UNMASKED_VENDOR_WEBGL));
  console.log('Renderer:', gl.getParameter(ext.UNMASKED_RENDERER_WEBGL));
} else {
  // Розширення недоступне — часто заблоковане налаштуванням приватності чи старим браузером
  console.log('Masked renderer:', gl.getParameter(gl.RENDERER));
}

4. Покадрове захоплення через Spector.js

Spector.js (розширення браузера або npm-пакет) записує кожен виклик WebGL, зроблений протягом одного кадру, і дозволяє пройти по них крок за кроком: прив'язані текстури, активний шейдер, значення uniform-змінних, розкладку вершинних атрибутів і фактичний вміст framebuffer після кожного draw call.

// npm install --save-dev spectorjs
import { Spector } from 'spectorjs';

const spector = new Spector();
spector.displayUI(); // додає плаваючу кнопку захоплення
// або запустіть захоплення програмно:
spector.captureCanvas(canvas);

Типова сесія налагодження: захопіть один кадр, потім скануйте список викликів у пошуку draw call, який має рендерити відсутній об'єкт. Spector.js показує точний стан GL на цьому виклику — якщо мініатюра прив'язаної текстури порожня, це баг завантаження текстури; якщо кількість вершин 0 — це баг bufferData/налаштування атрибутів; якщо шейдер показує іконку помилки компіляції — переходьте одразу до розділу 5.

5. Правильна перевірка помилок компіляції/лінковки шейдерів

Це найцінніший фікс, якого бракує більшості кодових баз WebGL: gl.compileShader() та gl.linkProgram() ніколи не кидають виключення й нічого не логують за замовчуванням. Зламаний шейдер тихо створює непридатний об'єкт, якщо ви явно не перевірите це:

function compileShader(gl, type, source) {
  const shader = gl.createShader(type);
  gl.shaderSource(shader, source);
  gl.compileShader(shader);

  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    const log = gl.getShaderInfoLog(shader);
    gl.deleteShader(shader);
    throw new Error(`Shader compile failed:\n${log}`);
  }
  return shader;
}

function linkProgram(gl, vertexShader, fragmentShader) {
  const program = gl.createProgram();
  gl.attachShader(program, vertexShader);
  gl.attachShader(program, fragmentShader);
  gl.linkProgram(program);

  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
    const log = gl.getProgramInfoLog(program);
    gl.deleteProgram(program);
    throw new Error(`Program link failed:\n${log}`);
  }
  return program;
}

Помилки лінковки — окремий, легко пропустити тип збою: компіляція може успішно пройти для обох шейдерів окремо, поки лінковка все одно провалюється — найчастіше через невідповідність varying-змінних (змінна in у фрагментному шейдері без відповідної out у вершинному шейдері з тією ж назвою й типом), або перевищення максимальної кількості varying/uniform векторів для платформи.

6. Обробка втрати контексту WebGL

Драйвер GPU може відібрати контекст WebGL у будь-який момент — ноутбук перемикає GPU, інша вкладка вичерпує VRAM, ОС відновлюється після краху драйвера. Без обробника це залишає назавжди чорний canvas без жодної помилки:

canvas.addEventListener('webglcontextlost', (e) => {
  e.preventDefault(); // обов'язково — повідомляє браузеру про намір відновити контекст
  cancelAnimationFrame(rafId);
  console.warn('WebGL context lost — pausing render loop');
});

canvas.addEventListener('webglcontextrestored', () => {
  console.warn('WebGL context restored — reinitialising GL resources');
  initGLResources(); // буфери, текстури й програми потрібно перестворити повністю
  requestAnimationFrame(renderLoop);
});

Ви можете примусово викликати втрату контексту для тестування через розширення WEBGL_lose_context: gl.getExtension('WEBGL_lose_context').loseContext() — необхідно, щоб перевірити, чи справді працює ваш шлях відновлення, перш ніж це станеться з реальним користувачем.

7. Чекліст: типові підозрювані