API: WebGL documentation status

This page tracks ongoing documentation work in the MDN WebGL API section. Feel free to contribute!

Summary

See also localization status of this section.

Outdated pages

Found 3 pages. These pages haven't been updated in over a year. Outdated pages can have problems with both content and format. Look at these pages and consider: Is this page talking about the Web of today? Does it look consistent with newer pages in this topic area? If not, make any needed changes.

Localizations

Please help us to localize this documentation into different languages. Read more about how to translate.

Writing team

fscholz

Writer.

Notes

Tagging standard

• Grouping tag is: "WebGL"

Goals

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

Non-goals

• 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.

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 [DONE!]
  • Interfaces
  • Properties
  • Methods
  • Events
  • Extensions
• Landing pages [DONE!]
• Guides/tutorials [DONE for overview of WebGL1 only]
• Sample apps and web content [NOT DONE]

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.

• 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 https://hacks.mozilla.org/2013/04/the-concepts-of-webgl/
  • 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 http://www.songho.ca/opengl/gl_fbo.html 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).

Resources

• WebGL 1.0 specification (this is what we currently ship)
• WebGL 2.0 specification (we're currently working on implementing this)
• WebGL 2.0 implementation tracking bug
• http://learningwebgl.com
• https://hacks.mozilla.org/2013/04/the-concepts-of-webgl/
• http://bjacob.github.io/webgl-tutorial
• http://webglfundamentals.org/

Specifications

The interfaces defined in the following specifications are tracked by this status page: