WebGL WEBGL_lose_context Khronos Ratified Extension Specification

Name

WEBGL_lose_context

Contact

enne@chromium.org

Contributors

Members of the WebGL working group

Glenn Maynard

Version

Last modified date: February 06, 2020
Revision: 15

Number

WebGL extension #3

Dependencies

Written against the WebGL API 1.0 specification.

Overview

This extension exposes new functions which simulate losing and restoring the WebGL context, even on platforms where the context can never be lost. Consult the WebGL specification for documentation about the webglcontextlost and webglcontextrestored events.

When this extension is enabled:

• loseContext and restoreContext are allowed to generate INVALID_OPERATION errors even when the context is lost.

Note that this extension is not disconnected from the WebGLRenderingContext if that object loses its context as described in "The Context Lost Event" of the WebGL specification, either through use of this API or via actual circumstances such as a system failure.

Alias Name Strings (for draft extensions)

• WEBKIT_WEBGL_lose_context
• MOZ_WEBGL_lose_context

IDL

[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_lose_context {
      undefined loseContext();
      undefined restoreContext();
};
  

New Functions

undefined loseContext()

When this function is called and the context is not lost, simulate losing the context so as to trigger the steps described in the WebGL spec for handling context lost. The context will remain in the lost state according to the WebGL specification until restoreContext() is called. If the context is already lost when this function is called, generate an INVALID_OPERATION error.

Implementations should destroy the underlying graphics context and all graphics resources when this method is called. This is the recommended mechanism for applications to programmatically halt their use of the WebGL API.

undefined restoreContext()

When this function is called while the context is lost, and the conditions defined by the WebGL specification for restoring the context are met, simulate the context being restored so as to trigger the steps described in the WebGL spec for handling the context being restored. Because this only enqueues the 'webglcontextrestored' event, the context will not be immediately restored after restoreContext(), but rather is first usably restored within the 'webglcontextrestored' event callback. (i.e. ext.restoreContext(), gl.isContextLost() returns true)

If the context is already restored when this function is called, or if the conditions in the WebGL specification for restoring the context are not satisfied, or if the context was not lost via loseContext(), generate an INVALID_OPERATION error.

For example, if e.preventDefault() is not called on the 'webglcontextlost' event, the context will not be marked restorable, and restoreContext() will fail. Additionally, the context is not restorable before the 'webglcontextlost' event is complete: calling restoreContext() before 'webglcontextlost' has completed will fail.

Revision History

Revision 1, 2011/01/11

• Initial revision.

Revision 2, 2011/04/14

• Added explicit restoreContext() method based on discussion on public_webgl list, to enable testing of scenario where context stays lost for a period of time.

Revision 3, 2011/11/08

• Renamed from WEBKIT_lose_context to WEBGL_EXT_lose_context

Revision 4, 2011/11/11

• Changed to make it clear this extension should follow the WebGL spec for the steps involved in handling losing and restoring the context rather than just fire events.

Revision 5, 2011/12/06

• Added vendor-specific name strings for draft extension per discussion on WebGL mailing list
• Renamed from WEBGL_EXT_lose_context to WEBGL_lose_context

Revision 6, 2011/12/07

• Renamed "Name Strings" section to "Alias Name Strings".

Revision 7, 2012/01/03

• Removed webgl module per changes to Web IDL spec.

Revision 8, 2013/01/26

• Moved from draft to community approved status

Revision 9, 2013/05/15

• Ratified by Khronos Board of Promoters.

Revision 10, 2013/06/05

• Clarified error generation that conflicted with WebGL spec.

Revision 11, 2013/08/02

• Indicated that this extension is not disconnected from the WebGLRenderingContext when that object loses its drawing buffer (i.e. when it performs the steps outlined in "The Context Lost Event" of the WebGL specification).

Revision 12, 2014/05/08

• Added INVALID_OPERATION for restoreContext() without loseContext()

Revision 13, 2014/07/15

• Added NoInterfaceObject extended attribute.

Revision 14, 2017/02/03

• Per discussion in working group, document that this extension should destroy the underlying context and all graphics resources.

Revision 15, 2020/02/06

• Clarify timelines and behavior for restoreContext().