{"record":{"id":"b7c5905639c0b8e0","repo":"BabylonJS/Babylon.js","slug":"instanced-arrays-are-required-for-msdf-text-render","errorCode":null,"errorMessage":"Instanced arrays are required for MSDF text rendering.","messagePattern":"Instanced arrays are required for MSDF text rendering\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/dev/addons/src/msdfText/textRenderer.ts","lineNumber":426,"sourceCode":"    }\r\n\r\n    /**\r\n     * Creates a new TextRenderer instance asynchronously\r\n     * @param font define the font asset to use\r\n     * @param engine define the engine to use\r\n     * @returns a promise that resolves to the created TextRenderer instance\r\n     */\r\n    public static async CreateTextRendererAsync(font: FontAsset, engine: AbstractEngine) {\r\n        if (engine.isWebGPU) {\r\n            const { RegisterEnginesWebGPUExtensionsEngineAlphaToCoverage } = await import(\"core/Engines/WebGPU/Extensions/engine.alphaToCoverage.pure\");\r\n            RegisterEnginesWebGPUExtensionsEngineAlphaToCoverage();\r\n        } else {\r\n            const { RegisterEnginesExtensionsEngineAlphaToCoverage } = await import(\"core/Engines/Extensions/engine.alphaToCoverage.pure\");\r\n            RegisterEnginesExtensionsEngineAlphaToCoverage();\r\n        }\r\n\r\n        if (!engine.getCaps().instancedArrays || !engine._features.supportSpriteInstancing) {\r\n            throw new Error(\"Instanced arrays are required for MSDF text rendering.\");\r\n        }\r\n\r\n        let shaderLanguage = ShaderLanguage.GLSL;\r\n        let vertex: string;\r\n        let fragment: string;\r\n        if (engine.isWebGPU) {\r\n            shaderLanguage = ShaderLanguage.WGSL;\r\n            vertex = (await import(\"./shadersWGSL/msdf.vertex\")).msdfVertexShaderWGSL.shader;\r\n            fragment = (await import(\"./shadersWGSL/msdf.fragment\")).msdfPixelShaderWGSL.shader;\r\n        } else {\r\n            vertex = (await import(\"./shaders/msdf.vertex\")).msdfVertexShader.shader;\r\n            fragment = (await import(\"./shaders/msdf.fragment\")).msdfPixelShader.shader;\r\n        }\r\n\r\n        const textRenderer = new TextRenderer(engine, shaderLanguage, font);\r\n        textRenderer._setShaders(vertex, fragment);\r\n\r\n        return textRenderer;\r","sourceCodeStart":408,"sourceCodeEnd":444,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/addons/src/msdfText/textRenderer.ts#L408-L444","documentation":"MSDF text rendering draws glyphs with instanced quads for performance. CreateTextRendererAsync checks the engine for `instancedArrays` capability and sprite-instancing feature support, and throws when either is missing, since the renderer cannot function without instancing.","triggerScenarios":"Calling TextRenderer.CreateTextRendererAsync(...) on an engine whose caps lack instancedArrays (typically WebGL1 without the OES_element_index_uint/instanced_arrays extension or a software renderer) or where `engine._features.supportSpriteInstancing` is false.","commonSituations":"Running on old devices/browsers or headless/software GL (swiftshader) without instanced_arrays; using a legacy WebGL1 engine; embedded webviews with limited GPU support.","solutions":["Use a WebGL2 or WebGPU engine, both of which support instancing: `new BAB.Engine(canvas)` resolves WebGL2 where available.","Feature-check before creating: `if (!engine.getCaps().instancedArrays) { /* fallback to normal text (GUI text block / DynamicTexture) */ }`.","Test on the actual target device — if a specific browser/device lacks instancing, provide a non-instanced text fallback path."],"exampleFix":"// before\nconst renderer = await TextRenderer.CreateTextRendererAsync(msdf, engine, scene); // throws on WebGL1\n// after\nif (engine.getCaps().instancedArrays && engine._features.supportSpriteInstancing) {\n  const renderer = await TextRenderer.CreateTextRendererAsync(msdf, engine, scene);\n} else {\n  // fallback: DynamicTexture-based text\n}","handlingStrategy":"validation","validationCode":"function supportsMsdfText(engine: BABYLON.AbstractEngine): boolean {\n  return !!engine.getCaps().instancedArrays && engine._features.supportSpriteInstancing;\n}\nif (!supportsMsdfText(engine)) { /* use fallback text rendering */ }","typeGuard":"const isInstancingCapable = (e: BABYLON.AbstractEngine): boolean =>\n  e.isWebGPU || e.webGLVersion >= 2 || !!e.getCaps().instancedArrays;","tryCatchPattern":"try {\n  textRenderer = await TextRenderer.CreateTextRendererAsync(msdf, engine, scene);\n} catch (e) {\n  if (String(e).includes(\"Instanced arrays are required\")) {\n    textRenderer = null; // fallback: DynamicTexture text\n  } else throw e;\n}","preventionTips":["Check engine caps before choosing MSDF text over plain text UI.","Prefer WebGL2/WebGPU engines in modern projects.","Test MSDF features on the oldest supported target device."],"tags":["msdf","text-rendering","instancing","engine-capability","webgl"],"backgroundTag":"unsupported-engine-capability","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}