{"record":{"id":"d1f8e5752f3bfc7e","repo":"pixijs/pixijs","slug":"rendertargetsystem-clearing-array-layers-is-not","errorCode":null,"errorMessage":"[RenderTargetSystem] Clearing array layers is not supported in WebGL renderer.","messagePattern":"\\[RenderTargetSystem\\] Clearing array layers is not supported in WebGL renderer\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/rendering/renderers/gl/renderTarget/GlRenderTargetAdaptor.ts","lineNumber":404,"sourceCode":"        });\n\n        gpuRenderTarget.msaaRenderBuffer = null;\n    }\n\n    public clear(\n        renderTarget: RenderTarget,\n        clear: CLEAR_OR_BOOL,\n        clearColor?: RgbaArray,\n        _viewport?: Rectangle,\n        _mipLevel = 0,\n        layer = 0\n    )\n    {\n        if (!clear) return;\n\n        if (layer !== 0)\n        {\n            throw new Error('[RenderTargetSystem] Clearing array layers is not supported in WebGL renderer.');\n        }\n\n        const renderTargetSystem = this._renderTargetSystem;\n\n        // if clear is boolean..\n        if (typeof clear === 'boolean')\n        {\n            clear = clear ? CLEAR.ALL : CLEAR.NONE;\n        }\n\n        // Strip the COLOR bit for depth-only targets – there is no color buffer to clear.\n        if (renderTarget.colorAttachments.length === 0)\n        {\n            clear &= ~CLEAR.COLOR;\n\n            if (!clear) return;\n        }\n","sourceCodeStart":386,"sourceCodeEnd":422,"githubUrl":"https://github.com/pixijs/pixijs/blob/4b141e3ced7255b39c2114b6bca03421a37b2363/src/rendering/renderers/gl/renderTarget/GlRenderTargetAdaptor.ts#L386-L422","documentation":"Thrown by GlRenderTargetAdaptor.clear() when the layer argument is non-zero. WebGL's gl.clear clears the currently-bound framebuffer in its entirety — there is no way to clear a single array layer or cube face without first re-binding that specific layer as an attachment. So the GL adaptor refuses a per-layer clear rather than silently clearing the wrong surface.","triggerScenarios":"Calling clear(renderTarget, clear, clearColor, viewport, mipLevel, layer) with layer !== 0 on the WebGL renderer. Happens when shared code paths (that also serve WebGPU, where layer clears are expressible) pass a layer into the clear API.","commonSituations":"Engine code that clears a specific array layer uniformly across backends. Clearing a cube-map face through the clear path instead of the bind path. Porting a WebGPU-only feature to WebGL.","solutions":["Bind the specific layer first (bind with layer != 0 forces re-attachment to that face/layer), then call clear with layer 0.","Branch on backend: only pass non-zero layers to clear() when running on WebGPU.","Restructure so per-layer clears become a full bind+clear cycle on the layer of interest."],"exampleFix":"// before\nrtSystem.clear(arrayRt, CLEAR.ALL, color, viewport, 0, 3); // layer 3 on WebGL\n\n// after\nrtSystem.bind(arrayRt, CLEAR.ALL, color, viewport, 0, 3); // re-attach layer 3, clear during bind\n// subsequent clears on this layer use layer 0:\nrtSystem.clear(arrayRt, CLEAR.ALL, color, viewport, 0, 0);","handlingStrategy":"validation","validationCode":"// Branch on backend: only pass layer to clear() on WebGPU\nconst isWebGPU = app.renderer.type === 'webgpu';\nrtSystem.clear(rt, CLEAR.ALL, color, viewport, mipLevel, isWebGPU ? layer : 0);","typeGuard":null,"tryCatchPattern":"try {\n  rtSystem.clear(rt, CLEAR.ALL, color, viewport, mipLevel, layer);\n} catch (e) {\n  if (/Clearing array layers/.test((e as Error).message)) {\n    // bind the layer first, then clear with layer 0\n    rtSystem.bind(rt, CLEAR.ALL, color, viewport, mipLevel, layer);\n  } else throw e;\n}","preventionTips":["Treat clear() as a whole-framebuffer op on WebGL; never pass layer != 0.","Use bind() with a clear flag to clear a specific layer on WebGL.","Keep backend-specific clear logic centralized."],"tags":["webgl","render-target","clear","array-layer","backend-divergence"],"backgroundTag":null,"analyzedSha":"4b141e3ced7255b39c2114b6bca03421a37b2363","analyzedAt":"2026-08-12T17:27:29.507Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}