\n \n ```\n\n Note: (1) the setting string must be valid JSON. (2) any tag will do, ``, ``, etc. as the\n script just applies all tags it finds with `querySelectorAll('[data-gman-debug-helper]')` and applies\n the options in the order found.\n\n### Naming your WebGL objects (buffers, textures, programs, etc..)\n\nUsing the extension you can name your objects. This way when an error is printed\nthe names will be inserted where appropriate.\n\n```js\nconst ext = gl.getExtension('GMAN_debug_helper');\nconst tex = gl.createTexture();\next.tagObject(tex, 'background-tex');\n```\n\nNow if you get an error related to `tex` you might get an told it's related to 'background-tex'\ninstead of just that you got an error.\n\n4 suggestions for using naming\n\n1. make some helpers\n\n ```js\n const ext = gl.getExtension('GMAN_debug_helper');\n const tagObject = ext ? ext.tagObject.bind(ext) : () => ();\n ```\n\n now you can just unconditionally tag things and if the extension does\n not exist it will just be a no-op.\n\n ```js\n const tex = gl.createTexture();\n tagObject(tex, 'checkerboard');\n ```\n \n2. wrap the creations functions\n\n ```js\n const ext = gl.getExtension('GMAN_debug_helper');\n if (ext) {\n Object.keys(gl.__proto__)\n .filter(name => name.startsWith('create'))\n .forEach(name => {\n const origFn = gl[name];\n if (origFn) {\n gl[name] = function(...args) {\n const obj = origFn.call(this, ...args);\n if (obj) {\n ext.tagObject(obj, args[args.length - 1] || '*unknown*');\n }\n return obj;\n }\n }\n });\n }\n ```\n\n Which you use like this\n\n ```js\n const shader = gl.createShader(gl.VERTEX_SHADER, 'phongVertexShader');\n const tex = gl.createTexture('tree-texture');\n ```\n\n and they'll still work in normal WebGL as it will ignore\n the extra parameter.\n\n3. Same as above but not wrapped\n\n ```js\n const ext = gl.getExtension('GMAN_debug_helper');\n const api = Object.fromEntries(\n Object.keys(gl.__proto__)\n .filter(name => name.startsWith('create'))\n .map(name => {\n const func = (ext && gl[name])\n ? function(...args) {\n const obj = gl[name](...args);\n if (obj) {\n ext.tagObject(obj, args[args.length - 1] || '*unknown*');\n }\n return obj;\n }\n : function(...args) {\n return gl[name](...args);\n };\n return [name, func];\n }));\n ```\n\n Which you use like this\n\n ```js\n const shader = api.createShader(gl.VERTEX_SHADER, 'phongVertexShader');\n const tex = api.createTexture('tree-texture');\n ```\n\n If you're allergic to hacking native APIs this is better but you have to\n remember to use `api.createXXX` instead of `gl.createXXX`\n\n4. Use your own API.\n\n Lots of people have wrapped WebGL themselves with things like `class Texture` and\n `class Framebuffer` or other functions. Those would be a good place to integrate\n tagging.\n\nAs a simple example, naming buffers after the attributes they'll\nbe used with (eg. 'position', 'normal'), naming textures by the URL of the img where they\nget their data. Naming vertex array objects by the model ('tree', 'car', 'house'), naming\nframebuffers by their usage ('shadow-depth', 'post-processing'), naming programs by what they do ('phong-shading', 'sky-box')...\n\nYou can also untag an object with\n\n```js\next.untagObject(someObj);\n```\n\nArguably for debugging you probably don't want to untag. The problem with\nuntagging is if you untag and then have a bug where you reuse an untagged\nobject, for example using an object you deleted, there will be no tag for the\nobject, so your error will just say something like \"error: tried to use\nTexture(unknown)\" instead of \"error: tried to use Texture(yourTag)\". At the same\ntime, if you're running WebGL-lint indefinitely (see `maxDrawCalls`) and\ncreating and deleting lots of objects, for example sync objects, there is a tiny\nbit of memory involved keeping the label of each one so manually untagging\nshould mean you are not leaking memory. Honestly I wouldn't worry about\nuntagging but it's here just in case you've got special needs. Also see\n`makeDefaultTags` above.\n\nThe extension also includes `getTagForObject` if you want to look up\nwhat string you tagged an object with\n\n```js\nconst buf = gl.createBuffer();\next.tagObject(buf, 'normals');\nconsole.log(ext.getTagForObject(buf)); // prints 'normals'\n```\n\n## Checking for redundant calls\n\nAn example of a redundant call is calling `gl.useProgram` with the same program\nor calling `gl.vertexAttribPointer` with the same parameters and the same buffer.\nYou can get a count to date of the redundant state setting WebGL-Lint has detected\nby calling `ext.getAndResetRedundantCallInfo()`\n\nExample:\n\n```js\nfunction render() {\n // .. do stuff with webgl ..\n\n const info = ext.getAndResetRedundantCallInfo();\n console.log(JSON.stringify(info));\n requestAnimationFrame(render);\n}\n```\n\nAlternatively you can try adding this script to your page (**instead of `webgl-lint.js`**) and it will\nattempt to print redundant call info for you.\n\n```html\n\n```\n\nor\n\n```js\nimport 'https://greggman.github.io/webgl-lint/webgl-lint-check-redundant-state-setting.js';\n```\n\nNote: WebGL-Lint does not check every possible redundant set setting. At the moment it checks\n\n* `bindBuffer`\n* `bindFramebuffer`\n* `bindRenderbuffer`\n* `bindSampler`\n* `bindTexture`\n* `bindVertexArray`\n* `enable`\n* `disable`\n* `vertexAttribPointer`\n* `vertexAttribIPointer`\n\nIt's not important to avoid 100% of redundant state setting. Rather, you can use\nthis feature to see if you have too much redundant state setting. For example if\nyou're making 2000 draw calls and you see 500-5000 redundant state setting\ncounts then you should probably look into adding some state tracking in your own\ncode or organizing the way calls happen so state is not set. It's not so much\nthat setting state more than once is bad, it's rather than it's just proof your\ncode is doing extra work. If it's a lot of extra work then you probably want to\nlook into it. If it's only a small amount of extra work then don't worry about\nit.\n\n# Suggestions?\n\n[https://github.com/greggman/webgl-lint/issues](https://github.com/greggman/webgl-lint/issues)\n\n# Development\n\nYou can run the tests with the un-merged code with `http://localhost:8080/test/?src=true`. You can also filter the tests with `grep=` as in\n`http://localhost:8080/test/?grep=shader` or both \n`http://localhost:8080/test/?src=true&grep=shader`.\n\n# Repo\n\n[https://github.com/greggman/webgl-lint/](https://github.com/greggman/webgl-lint/)\n\n# License\n\n[MIT](LICENSE.md)\n","readmeFilename":"README.md"}
![](\"./webgl-lint.png\")
\n\nWebGL lint is a script you can throw into your WebGL project\nto check for common WebGL errors.\n\n* Calls `getError` after every function and throws if there was an error.\n\n* Checks that no arguments to any functions are `undefined`. \n\n Pass `0` or `false` or `null` where you mean `0` or `false` or `null`.\n\n* Checks that no numbers or values in arrays of numbers are `NaN`. \n\n* Checks that all non-sampler uniforms are set. (see configuration below)\n\n* Checks that uniform matrices are not all zero.\n\n* Warns if you try to access an undefined uniform.\n\n* Checks for out of range access issues and will tell you which attribute/s are out of range\n\n* Checks that shaders compile. On failure prints the shader and tries to highlight errors.\n\n* Checks that programs link. On failure prints the attached shaders.\n\n* If there is a WebGL error it tries to provide more info about why\n\n * for framebuffer feedback it will tell you which textures assigned to which uniforms and which attachments\n \n * for other errors it will try print extra info where possible.\n\n * it lets you name webgl objects so those names can be shown in the error messages.\n\n## Example\n\n**Open the JavaScript console**. You'll see the first example prints fewer\nerrors and less info where as the second prints much more info.\n\n* [without script](https://greggman.github.io/webgl-lint/test/?lint=false)\n* [with script](https://greggman.github.io/webgl-lint/test/)\n\n# Usage\n\n```\n\n```\n\nor \n\n```\nimport 'https://greggman.github.io/webgl-lint/webgl-lint.js';\n```\n\nWebGL Lint `throw`s a JavaScript exception when there is an issue so if you are\nusing `try`/`catch` to catch errors you might need to print the exceptions\ninside your catch block. You can also turn on \"pause on exception\" on your\nJavaScript debugger.\n\nThrowing seemed more a appropriate than just printing an error because if you\nget an error you should fix it! I tried the script out with all the\n[three.js examples](https://threejs.org/examples). It found 1 real bug and several half bugs.\nBy half bugs I mean there were several examples that functioned but were actually\npassing `NaN` or `null` in the wrong places for a few frames or they were not setting\nuniforms that probably should have been set. Arguably it's\nbetter to fix those so that you can continue to use the helper to find real\nerrors. In any case most of examples ran without error so you can do it\ntoo! 😉\n\n### `GMAN_debug_helper` extension\n\nWebGL Lint adds a special extension `GMAN_debug_helper` with these functions\n\n* `tagObject(obj: WebGLObject, name: string): void` - see naming below\n* `untagObject(obj: WebGLObject): void` - see naming below\n* `getTagForObject(obj: WebGLObject): string` - see naming below\n* `setConfiguration(settings): void` - see configuration below\n* `disable(): void` - turns off the checking\n* `getAndResetRedundantCallInfo(): RedundantCallInfo` - see below\n\n### Configuration\n\nYou don't need to configure anything to use in general but there are some settings\nfor special needs.\n\n* `maxDrawCalls` (default: 1000)\n\n Turns off the checking after this many draw calls. Set to 0 to check forever.\n\n* `failUnsetUniforms`: (default: true)\n\n Checks that you set uniforms except for samplers and fails if you didn't.\n It's a common error to forget to set a uniform or to mis-spell the name of\n a uniform and therefore not set the real one. The common exception is\n samplers because uniforms default to 0 so not setting a sampler means use\n texture unit 0 so samplers are not checked.\n \n Of course maybe you're not initializing some uniforms on purpose\n so you can turn off this check. I'd recommend setting them so you get the\n benefit of this check finding errors.\n\n Note: uniform blocks are not checked directly. They are checked by WebGL itself\n in the sense that if you fail to provide uniform buffers for your uniform blocks\n you'll get an error but there is no easy way to check that you set them.\n\n* `failUnsetSamplerUniforms`: (default: false)\n\n See above why sampler uniforms are not checked by default. You can force them\n to be checked by this setting.\n\n* `failZeroMatrixUniforms`: (default: true)\n\n Checks that a uniform matrix is not all zeros. It's a common source of errors to\n forget to set a matrix to the identity and it seems uncommon to have an all\n zero matrix. If you have a reason a matrix needs to be all zeros you may want\n to turn this off. \n\n* `failUnrenderableTextures`: (default: true)\n\n Unrenderable textures are not an error in WebGL, they just don't render.\n WebGL itself usually print's a warning but it's usually fairly cryptic\n just telling you an unrenderable texture exists but not much else.\n\n Examples of unrenderable textures are non-power of 2 textures in WebGL1\n with filtering set to need mips and wrap not set to `CLAMP_TO_EDGE` or\n in both WebGL and WebGL2 would be mips of different internal formats\n or the wrong size.\n\n* `failUndefinedUniforms`: (default: false)\n\n WebGL by default returns `null` when you call `gl.getUniformLocation` for\n a uniform that does not exist. It then silently ignores calling `gl.uniformXXX`\n if the location is `null`. This is great when you're editing a shader in that\n if you remove a uniform from the shader your code that is still setting\n the old uniform will keep working.\n \n For example if you are debugging and you go to the bottom of your fragment\n shader and add `gl_FragColor = vec4(1, 0, 0, 1);` all the uniforms in your\n fragment shader will be optimized out. If WebGL suddenly issues errors trying\n to set those it would be much more frustrating to debug. Conversely though, if\n you have a typo, for example you want to look up the location of `'u_color'` and\n you type `gl.getUniformLocation(prg, 'uColor')` you'll get no error and it\n will likely take you a while to find your typo.\n\n So, by default webgl-lint only prints a warning for undefined uniforms.\n You can make throw by setting `failUndefinedUniforms` to `true`.\n\n* `failBadShadersAndPrograms`: (default: true)\n\n Most WebGL programs expect all shaders to compile and all programs\n to link but often programmers don't check for errors. While it's likely\n they'd get an error about a bad program further in their code, at that point\n it's likely too late to tell them it's because the program didn't compile or\n link. Instead the message will just be something like \"no valid program in use\".\n\n If you're working on a project that expects shaders to fail to compile\n and/or programs to link you can set this to `false`.\n\n* `warnUndefinedUniforms`: (default: true)\n\n See `failUndefinedUniforms`. Setting this to false turns off warnings\n about undefined uniforms.\n\n* `ignoreUniforms`: (default: [])\n\n Lets you configure certain uniforms not to be checked. This way you can turn\n off checking for certain uniforms if they don't obey the rules above and still\n keep the rules on for other uniforms. This configuration is additive. In other words\n\n ```js\n ext.setConfiguration({ignoreUniforms: ['foo', 'bar']});\n ext.setConfiguration({ignoreUniforms: ['baz']});\n ```\n\n Ignores uniforms called 'foo', 'bar', and 'baz'.\n\n* `throwOnError`: (default: true)\n\n The default is to throw an exception on error. This has several benefits.\n\n 1. It encourages you to fix the bug.\n\n 2. You'll get a stack trace which you can drill down to find the bug.\n\n 3. If you use \"pause on exception\" in your browser's dev tools you'll\n get a live stack trace where you can explore all the local variables\n and state of your program.\n\n But, there might be times when you can't avoid the error, say you're\n running a 3rd party library that gets errors. You should go politely\n ask them to fix the bug or better, fix it yourself and send them a pull request.\n In any case, if you just want it to print an error instead of throw then\n you can set `throwOnError` to false.\n\n* `makeDefaultTags`: (default: true)\n\n If true, all objects get a default tag, Example `*UNTAGGED:Buffer1`,\n `*UNTAGGED:Buffer2` etc. This is a minor convenience to have something\n to distinguish one object from another though it's highly recommended\n you tag your objects. (See naming).\n\n The only reason to turn this off is if you're creating and deleting\n lots of objects and you want to make sure tags are not leaking memory\n since tags are never deleted automatically. (See \"naming).\n\nThere 2 ways to configure\n\n1. Via the extension and JavaScript.\n\n Example:\n\n ```js\n const gl = someCanvas.getContext('webgl');\n const ext = gl.getExtension('GMAN_debug_helper');\n if (ext) {\n ext.setConfiguration({\n maxDrawCalls: 2000,\n failUnsetSamplerUniforms: true,\n });\n }\n ```\n\n2. Via an HTML dataset attribute\n\n Example:\n\n ```html\n