{"record":{"id":"f916eab81c8f9660","repo":"BabylonJS/Babylon.js","slug":"readpixelsasync-only-work-on-webgl2","errorCode":null,"errorMessage":"_readPixelsAsync only work on WebGL2+","messagePattern":"_readPixelsAsync only work on WebGL2\\+","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/Engines/engine.pure.ts","lineNumber":1027,"sourceCode":"                        return false;\r\n                    }\r\n                    return true;\r\n                },\r\n                resolve,\r\n                reject,\r\n                intervalms\r\n            );\r\n        });\r\n    }\r\n\r\n    /**\r\n     * This function might return null synchronously, so it is technically not async.\r\n     * @internal\r\n     */\r\n    // eslint-disable-next-line no-restricted-syntax\r\n    public _readPixelsAsync(x: number, y: number, w: number, h: number, format: number, type: number, outputBuffer: ArrayBufferView): Nullable<Promise<ArrayBufferView>> {\r\n        if (this._webGLVersion < 2) {\r\n            throw new Error(\"_readPixelsAsync only work on WebGL2+\");\r\n        }\r\n\r\n        const gl = <WebGL2RenderingContext>(this._gl as any);\r\n        const buf = gl.createBuffer();\r\n        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, buf);\r\n        gl.bufferData(gl.PIXEL_PACK_BUFFER, outputBuffer.byteLength, gl.STREAM_READ);\r\n        gl.readPixels(x, y, w, h, format, type, 0);\r\n        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);\r\n\r\n        const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);\r\n        if (!sync) {\r\n            return null;\r\n        }\r\n\r\n        gl.flush();\r\n\r\n        // eslint-disable-next-line github/no-then\r\n        return this._clientWaitAsync(sync, 0, 10).then(() => {\r","sourceCodeStart":1009,"sourceCodeEnd":1045,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Engines/engine.pure.ts#L1009-L1045","documentation":"_readPixelsAsync relies on WebGL2's PIXEL_PACK_BUFFER and fence-sync readback, which do not exist in WebGL1. The engine guards on _webGLVersion < 2 and throws immediately rather than silently falling back.","triggerScenarios":"Calling engine._readPixelsAsync(...) on an engine running WebGL1 (old browser, forced WebGL1 fallback, or a context created without WebGL2 support).","commonSituations":"Legacy Safari/iOS versions before WebGL2 support, running on a machine/driver where WebGL2 is unavailable so the engine silently falls back, headless environments (old headless Chrome) lacking WebGL2.","solutions":["Use the synchronous engine.readPixels() on WebGL1 instead of _readPixelsAsync.","Ensure the runtime supports WebGL2 (update browser/headless flags: --enable-unsafe-swiftshader or use a GPU-enabled CI runner).","Check engine.webGLVersion (or getCaps().textureFloatRender etc.) at startup and branch your code accordingly."],"exampleFix":"// before\nconst data = await engine._readPixelsAsync(x, y, w, h, fmt, type, buf);\n// after\nif (engine.webGLVersion >= 2) {\n  const data = await engine._readPixelsAsync(x, y, w, h, fmt, type, buf);\n} else {\n  engine.readPixels(x, y, w, h, buf);\n}","handlingStrategy":"validation","validationCode":"if (engine.webGLVersion < 2) {\n  // use sync readPixels instead of _readPixelsAsync\n}","typeGuard":"function supportsAsyncReadback(e) {\n  return (e as { webGLVersion: number }).webGLVersion >= 2;\n}","tryCatchPattern":"try {\n  await engine._readPixelsAsync(x, y, w, h, fmt, type, buf);\n} catch (e) {\n  if (/only work on WebGL2/.test(e.message)) {\n    engine.readPixels(x, y, w, h, buf);\n  }\n}","preventionTips":["Check engine.webGLVersion at startup and record the capability set.","Ensure target environments (CI, kiosk browsers) support WebGL2.","Keep a WebGL1 fallback readback implementation."],"tags":["webgl1","webgl2","readback","capability-check"],"backgroundTag":"webgl2-required","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}