1286265 - Develop a MDN documentation site that covers the unintuitive performance pitfalls of WebGL

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: Games, enhancement)

Description

[Jukka Jylänki]

Marking this bug item under "Developer Documentation - Games", since that is closest, although this would be "Developer Documentation - WebGL", as this is not games specific.

Using WebGL has quite a different performance pitfall landscape compared to native OpenGL (ES) development, caused by having to impose extra security restrictions or having to perform API emulation under the hood. Even expert native GL developers can easily be bit by these, since the the overhead is not intuitive or have the same characteristics that native APIs do. Firefox WebGL backend has begun to post these kind of issues as WebGL performance errors onto page console, which is good, but these performance errors only appear after one has developed the slow code in the first place, and they don't offer any detailed information about the underlying cause of the issue.

Some recent examples include:

1. texImage2D can yell "Error: WebGL: texImage2D: Chosen format/type incured an expensive reformat: 0x1908/0x1401" when it receives an image format that Firefox does not like. STR: Visit https://www.khronos.org/registry/webgl/sdk/tests/conformance/textures/misc/tex-image-with-format-and-type.html?webglVersion=1&quiet=0

For example, here we could document which texture formats are the slow ones, why they are slow, and under which conditions those should be avoided. What alternatives do developers have for the slow formats? 

2. copyTexImage2D is reported to be slow: "Error: WebGL: CopyTexImage2D: This operation requires zeroing texture data. This is slow.". STR: Visit https://www.khronos.org/registry/webgl/sdk/tests/conformance/textures/misc/copy-tex-image-and-sub-image-2d.html?webglVersion=1&quiet=0

What is the preferred code path to take instead?

3. texImage2D can hit a slow path and error "Error: WebGL: texImage2D: Failed to hit GPU-copy fast-path. Falling back to CPU upload.". STR: https://www.khronos.org/registry/webgl/sdk/tests/conformance/extensions/oes-texture-float-with-video.html?webglVersion=1&quiet=0

Under which conditions does this occur? What to do instead?

4. The WebGL specific FLIP_Y and PREMULTIPLY_ALPHA are slow and give a performance warning: "Error: WebGL: texSubImage2D: Uploading ArrayBuffers with FLIP_Y or PREMULTIPLY_ALPHA is slow." STR: https://www.khronos.org/registry/webgl/sdk/tests/conformance/textures/misc/tex-image-and-sub-image-2d-with-array-buffer-view.html?webglVersion=1&quiet=0

Developers are likely preferred to implement these features manually in shaders, so we should advocate them to not be used.

5. If developer is not careful, texSubImage2D can be used in a fashion that is slow, giving the error "Error: WebGL: texSubImage2D: Texture has not been initialized prior to a partial upload, forcing the browser to clear it. This may be slow.". STR: https://www.khronos.org/registry/webgl/sdk/tests/conformance/textures/misc/texture-sub-image-cube-maps.html?webglVersion=1&quiet=0

We could highlight slow and fast code sequences to offer instructions how one fixes the problem.

6. glBufferData() falls off the performance cliff if it resizes the underlying buffer. https://bugzilla.mozilla.org/show_bug.cgi?id=1253463

glBufferSubData() could be advocated to be used here, along with manual size management.

7. Instanced rendering element array buffer type should not change(?), or an error "Error: WebGL: drawElementsInstanced: bound element array buffer previously used with a type other than UNSIGNED_BYTE, this will affect performance." might be reported. STR: https://www.khronos.org/registry/webgl/sdk/tests/conformance/extensions/angle-instanced-arrays.html?webglVersion=1&quiet=0

Not sure what this is about. What is the cause of this? What should one do instead?

8. On Windows, GL vertex buffer uploads may hit an expensive relayouting of the vertex data per-vertex inside ANGLE (to emulate D3D11?). https://bugzilla.mozilla.org/show_bug.cgi?id=1223870

When does this occur and why? What kind of vertex layout is optimal?

9. Batching or instancing is much more critical in WebGL compared to native, because CPU side draw call overhead on individual draws is much higher in Firefox WebGL compared to native. https://bugzilla.mozilla.org/show_bug.cgi?id=1133570

Offer explanations of why this is, and advocate batching and instancing techniques.

10. Uploading index data buffers is slow, since it incurs a per-index security check. (slightly related, https://bugzilla.mozilla.org/show_bug.cgi?id=1224717)

Advocate and recommend avoiding dynamic index buffer uploads if possible.


What I am envisioning is that there would exist an MDN documentation page that looks like these:
  - https://developer.apple.com/library/ios/documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesforWorkingwithVertexData/TechniquesforWorkingwithVertexData.html
  - https://developer.apple.com/library/prerelease/content/documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/BestPracticesforShaders/BestPracticesforShaders.html

Naturally the documentation would not need to reiterate the existing known good practices, but highlight the above types of cases where WebGL is fundamentally different to Direct3D or OpenGL (ES). Some of the above cases may be internal bugs (e.g. #8), in which case we know those would be only transient issues that will be fixed, so we would not likely want to document them. Other issues however, like #9 and #10, might be unfixable issues, in which case we should focus on developer education.

There does exist the page https://developer.mozilla.org/fi/docs/Web/API/WebGL_API/WebGL_best_practices, although it is focused towards beginner developers and not on WebGL performance cliffs itself.

Comment 1

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.