WebGL documentation plan

This page is not complete.

WebGL is a low-level general graphics API for the Web which allows Web content to use an API that's very similar to OpenGL ES 2.0 to draw 2D and 3D graphics using the host computer's graphics acceleration hardware. It can be used for most kinds of 2D and 3D graphics, and is exposed as a context for the <canvas> element. This project's goal is to produce quality documentation for WebGL, including both a general reference and appropriate and useful how-to guides and tutorials, with code samples.

Name: Graphics (#)
Description: Mozilla graphics API
Owner: Jeff Muizelaar(Thebes, QCMS, YCbCr, Cairo/Pixman, Regions, OS X, Other), Robert O'Callahan
Peer(s): Joe Drew, Vladimir Vukicevic, Bas Schouten(Layers, Windows), Benoit Jacob(gfx/gl), Benoit Girard(Compositor, Performance), Ali Juma, Jeff Gilbert(WebGL, ANGLE), George Wright(Canvas2D, Skia), Matt Woodrow(Layers API), John Daggett(text/fonts), Jonathan Kew(text/fonts), Nicolas Silva(MozSurface), Nick Cameron, Sotaro Ikeda(B2G), James Willcox(Android), Christopher Lord
Source Dir(s): gfx/, content/canvas/src/
Bugzilla Component(s): Core::Graphics, Core::Graphics: Layers, Core::Graphics: Text, Core::GFX: Color Management, Core::Canvas: 2D, Core::Canvas: WebGL
DiscussionĀ Group: dev-platform


A team has not been determined yet for this documentation project.

Join the project

MDN is built by you, the reader! If you'd like to help make this documentation real, we'd like to hear from you. You may contact the writing team by clicking on their names above, or on our mailing list. If you're a new MDN contributor, please have a look at our contributor guide. You can also join the conversation in our IRC channel, #mdn.


Note: It is not currently a goal of this project to document the OpenGL ES-like API implemented by WebGL. Instead of documenting every method/property/type/event/etc, this content will link to the manpages on the official OpenGL site. Linking to OpenGL docs is often good enough, but in reality is not a perfect solution due to the differences between WebGL and OpenGL. So we should be looking into adding that documentation to the scope of this project.

This project will only involve documenting the WebGL interfaces (without diving into the individual methods and such; see References needed for details), including references, tutorials, and example code. This also includes whatever minor updates are needed to other documentation in order to properly integrate the WebGL documentation; for example, cross-referencing between the WebGL documentation and <canvas> or other existing content.

We will include what documentation we need to cover WebGL 2.0 functionality is implemented by Gecko, since some of that is expected to land in the next few months.

Other goals we wish to achieve:

  • Help new developers learn WebGL
  • Ease the transition for native OpenGL programmers to move to WebGL
  • Provide guidelines for porting desktop or mobile native apps to the Web using WebGL
  • Show how to use WebGL to accelerate 3D graphics
  • Demonstrate how to integrate WebGL with other content
  • Teach WebGL use without using external libraries
  • Offer a discussion of external libraries that can help make WebGL development easier


  • Documenting related technologies like asm.js and Emscripten are not in scope for this project, although they do need to be approached properly at some point. They'll be mentioned here, and possibly used to some extent in samples. But they're separate documentation projects.

Target milestones

These milestones are estimates and may bear no resemblance to reality. We don't even have a writer for the project yet, so we certainly can't set realistic timeframes for milestones.

Q3 2014
Write documentation plan and get it reviewed by appropriate people. Find and assign a writer to the project.
Once a writer is assigned, we will be able to project future milestones.

Note: WebGL 2.0 support is tentatively expected to ship in Firefox 35. There is a slim possibility of it launching in Firefox 34, and of course a chance it could slip to 36.

Note: Each milestone bug should block bugĀ 986498, which is a tracking/meta bug for this project.

User stories

  • I'm an experienced Web developer who wants to create a Web app using WebGL.
  • I'm a newcomer to Web development, but am an expert at C++ and have used OpenGL in the past; I just want to create a new Web app using WebGL.
  • I'm an experienced developer who wants to port a C/C++ application to the Web using WebGL.
  • I'm developing a Web site that needs some 3D elements and wonder if/how I can use WebGL for that.
  • I want to use WebGL for high-performance 2D graphics.

Documents needed

The lists here detail specific types of content that need to be produced, as well as precise pages that we know need to be produced or updated.

Types of pages

The following types of pages will need to be produced.

  • Reference
    • Interfaces
    • Properties
    • Methods
    • Events
  • Landing pages
  • Guides/tutorials
  • Sample apps and web content

Developer guides needed

WebGL developer manual

This documentation covers every area of WebGL one at a time, detailing how they work and how they're used. This structure may or may not be complete, and may need to be cleaned up and reconfigured to make sense. It's not mandatory for the author to follow this exact content structure, as long as everything is covered.

Note: This likely needs a better title.

  • Introduction to WebGL
    • What it is and how it relates to OpenGL
    • Relationship to existing <canvas> API.
    • Benefits of WebGL
    • Availability
    • Overview of the documentation and what to expect
  • Working with contexts
    • Creating and destroying a context
      • Creating a context
      • Context attributes
      • Destroying a context
    • Configuring a context
      • Size
      • State (blending, color depth, etc)
      • Clipping and viewport
  • Buffers
    • The framebuffer and the frontbuffer
      • Covers these two buffers and how drawing into the framebuffer must be done in a single JavaScript callback, since it is automatically copied to the frontbuffer at appropriate times between JS calls
      • Explain how this differs from OpenGL
      • See
    • Creating and destroying buffers
    • Configuring buffers
  • Working with textures
    • Creating and destroying textures
    • Configuring textures
    • Generating texture content
  • Programs and shaders
    • Introduction and definitions
    • Introduction to GLSL
    • Creating and using shaders
      • Creating vertices
        • Assigning attributes to vertices
      • Building vertex arrays
      • Configuring uniforms
    • Creating and deleting programs
      • What they're for
      • Details about using programs
  • Using alternate framebuffers
    • Intro and use cases
    • Creating and binding framebuffers
    • Configuring framebuffers
    • Using renderbuffers for offscreen image data
      • Types of surfaces you need to render to that aren't used as textures to sample from
        • Depth buffers
        • Stencil buffers
        • (etc?)
      • Creating and using renderbuffers
    • See for extra information.
  • Drawing the rendered frame
    • How to let the browser blit to the frontbuffer
      • Using requestAnimationFrame()
      • Blit happens between JavaScript callbacks
    • Clearing the frame
    • Reading the back pixels
      • How to do it
      • Performance implications
  • Handling WebGL events
    • Handling loss and restoration of the rendering context
  • Integrating WebGL with other Web content
    • Overlaying WebGL using the alpha context attribute
    • Using WebGL alongside other content in a page
    • Using a video as a texture
    • Using a canvas as a texture
      • Drawing text in a 3D scene
      • Other concepts as appropriate
    • Using arbitrary Web content as a texture
  • Putting it all together
    • This chapter would take all the information above and present a complete WebGL demonstration, explaining briefly what's going on throughout, with links to the previous chapters for in-depth coverage.
  • WebGL extensions
  • Differences between WebGL 1.0 and WebGL 2.0
  • Differences between WebGL and OpenGL ES 3.0

WebGL stories

This documentation provides training through examples and solutions to specific use cases, instead of the topic-by-topic details from the WebGL developer manual.

  • Using WebGL for 2D graphics acceleration
    • Creating new projects using WebGL for 2D graphics
    • Updating existing Web games to use WebGL for better performance
  • Using WebGL for 3D graphics
    • Various examples; we need to come up with a good list, starting with something very bare-bones and simple and eventually covering all major topics.
  • Porting OpenGL software to WebGL (likely cross-references with Emscripten and asm.js documentation, as well as Game Center content).

Canvas documentation updates

Updates will be needed to cover the WebGL context creation methods thoroughly. In addition, the webglcontextcreationerror canvas event needs to be documented.

References needed

We will need to document all interfaces from both the WebGL 1.0 and WebGL 2.0 specifications. The list here is based on the specs as of August 5, 2014.

Note: Initially, we will minimally document the interfaces, with a brief description and a link to the official documentation for each property, method, or attribute (or constant, or type, etc) within.

  • WebGL data types (GLenum, GLboolean, etc)
  • Ensure Typed Arrays documentation is all up-to-date
  • WebGLContextAttributes
  • WebGLObject
  • WebGLBuffer
  • WebGLFramebuffer
  • WebGLProgram
  • WebGLRenderbuffer
  • WebGLShader
  • WebGLTexture
  • WebGLUnivormLocation
  • WebGLActiveInfo
  • WebGLShaderPrecisionFormat
  • WebGLRenderingContext
  • WebGLContextEvent
  • WebGLQuery
  • WebGLSampler
  • WebGLSync
  • WebGLTransformFeedback
  • WebGLVertexArrayObject
  • WebGL2RenderingContext


Existing content

We have a multi-part tutorial already, but it's somewhat out of date.

Other notes

None at this time.

Document Tags and Contributors

Contributors to this page: Sheppy, bjacob
Last updated by: Sheppy,
Hide Sidebar