WebGL WEBGL_debug Extension Proposed Specification

DO NOT IMPLEMENT!!!

Name

WEBGL_debug

Contact

WebGL working group (public_webgl 'at' khronos.org)

Contributors

Emmanuel Gil Peyrot, Collabora Ltd.

Members of the WebGL working group

Version

Last modified date: September 18, 2015
Revision: 1

Number

WebGL extension #NN

Dependencies

Written against the WebGL API 1.0 specification.

Overview

This extension allows the GL to notify applications when various events occur that may be useful during application development, debugging and profiling.

This extension exposes the KHR_debug functionality to WebGL.

The following WebGL-specific behavioral changes apply:

• References to debug contexts are deleted.
• References to the debug message log and callback are deleted, replaced with DOM events.
• The ObjectPtrLabel and GetObjectPtrLabel functions are replaced with ObjectLabel and GetObjectLabel.
• The count and ids arguments of DebugMessageControl are replaced with a sequence<GLuint> ids argument.
• The length and buf arguments of DebugMessageInsert and PushDebugGroup are replaced with a DOMString message argument.
• The identifier and name arguments of ObjectLabel and GetObjectLabel are replaced with a WebGLObject object argument.
• The length and label arguments of ObjectLabel are replaced with a DOMString label argument.
• The bufSize, length and label arguments of GetObjectLabel are replaced with a DOMString return type.
• As per the usual WebGL binding rules, functions don't keep the KHR suffix they have in the GLES version, but tokens do.

Consult the above extension for documentation, issues and new functions and enumerants.

When this extension is enabled:

• The WEBGL_debug extension object is a DOM EventTarget, obeying the rules of the DOM Level 3 Events, with a new WebGLDebugMessage event that gets fired whenever the driver, browser or application emits a debug message.
• debugMessageInsertKHR is exposed to allow the application to insert debug messages into the WebGL stream.
• objectLabelKHR and getObjectLabelKHR are exposed, to assign a label to a WebGLObject and retrieve it.
• pushDebugGroupKHR and popDebugGroupKHR make it possible to group a list of WebGL calls together.
• debugMessageControlKHR allows the application to enable and disable the debug messages which emit a WebGLDebugMessage event. This state is part of the debug group they are part of, and gets poped on popDebugGroupKHR.

IDL

[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_debug : EventTarget {
  const GLenum MAX_DEBUG_MESSAGE_LENGTH_KHR = 0x9143;
  const GLenum MAX_DEBUG_GROUP_STACK_DEPTH_KHR = 0x826C;
  const GLenum DEBUG_GROUP_STACK_DEPTH_KHR = 0x826D;
  const GLenum MAX_LABEL_LENGTH_KHR = 0x82E8;

  const GLenum DEBUG_SOURCE_API_KHR = 0x8246;
  const GLenum DEBUG_SOURCE_WINDOW_SYSTEM_KHR = 0x8247;
  const GLenum DEBUG_SOURCE_SHADER_COMPILER_KHR = 0x8248;
  const GLenum DEBUG_SOURCE_THIRD_PARTY_KHR = 0x8249;
  const GLenum DEBUG_SOURCE_APPLICATION_KHR = 0x824A;
  const GLenum DEBUG_SOURCE_OTHER_KHR = 0x824B;

  const GLenum DEBUG_TYPE_ERROR_KHR = 0x824C;
  const GLenum DEBUG_TYPE_DEPRECATED_BEHAVIOR_KHR = 0x824D;
  const GLenum DEBUG_TYPE_UNDEFINED_BEHAVIOR_KHR = 0x824E;
  const GLenum DEBUG_TYPE_PORTABILITY_KHR = 0x824F;
  const GLenum DEBUG_TYPE_PERFORMANCE_KHR = 0x8250;
  const GLenum DEBUG_TYPE_OTHER_KHR = 0x8251;
  const GLenum DEBUG_TYPE_MARKER_KHR = 0x8268;

  const GLenum DEBUG_TYPE_PUSH_GROUP_KHR = 0x8269;
  const GLenum DEBUG_TYPE_POP_GROUP_KHR = 0x826A;

  const GLenum DEBUG_SEVERITY_HIGH_KHR = 0x9146;
  const GLenum DEBUG_SEVERITY_MEDIUM_KHR = 0x9147;
  const GLenum DEBUG_SEVERITY_LOW_KHR = 0x9148;
  const GLenum DEBUG_SEVERITY_NOTIFICATION_KHR = 0x826B;

  const GLenum STACK_UNDERFLOW_KHR = 0x0504;
  const GLenum STACK_OVERFLOW_KHR = 0x0503;

  undefined debugMessageControlKHR(GLenum source, GLenum type, GLenum severity, sequence<GLuint> ids, boolean enabled);
  undefined debugMessageInsertKHR(GLenum source, GLenum type, GLuint id, GLenum severity, DOMString buf);

  undefined pushDebugGroupKHR(GLenum source, GLuint id, DOMString message);
  undefined popDebugGroupKHR();

  undefined objectLabelKHR(WebGLObject? object, DOMString label);
  DOMString getObjectLabelKHR(WebGLObject? object);
}; // interface WEBGL_debug

[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WebGLDebugMessage : Event {
  readonly attribute GLenum source;
  readonly attribute GLenum type;
  readonly attribute GLuint id;
  readonly attribute GLenum severity;
  readonly attribute DOMString message;
}; // interface WebGLDebugMessage
  

New Functions

On WEBGL_debug:

undefined debugMessageControlKHR(GLenum source, GLenum type, GLenum severity, sequence<GLuint> ids, boolean enabled)

Enables or disables the reporting of WebGLDebugMessage events for the specified messages.

undefined debugMessageInsertKHR(GLenum source, GLenum type, GLuint id, GLenum severity, DOMString message)

Inserts a custom message into the debug log.

undefined pushDebugGroupKHR(GLenum source, GLuint id, DOMString message)

Pushes a debug group on the stack.

undefined popDebugGroupKHR()

Closes a group opened with pushDebugGroupKHR.

undefined objectLabelKHR(WebGLObject? object, DOMString label)

Assigns a label to a WebGLObject.

DOMString getObjectLabelKHR(WebGLObject? object)

Retrieves the label associated with a WebGLObject.

undefined addEventListener(DOMString type, EventListener listener)

Register an event handler of a specific event type on the EventTarget.

undefined removeEventListener(DOMString type, EventListener listener)

Removes an event listener from the EventTarget.

boolean dispatchEvent(Event event)

Dispatch an event to this EventTarget.

Sample Code

function init(gl) {
  ...
  var ext = gl.getExtension('WEBGL_debug');

  ext.addEventListener('message', function(evt) {
    console.log(evt.source, evt.type, evt.id, evt.severity, evt.message);
  });
  ...
}

function draw(gl, ext) {
  ...

  // Setup of the default active debug group: Filter everything in
  ext.debugMessageControlKHR(gl.DONT_CARE, gl.DONT_CARE, gl.DONT_CARE, [], true);

  // Generate a debug marker debug output message
  ext.debugMessageInsertKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR,
    ext.DEBUG_TYPE_MARKER_KHR, 100,
    ext.DEBUG_SEVERITY_NOTIFICATION_KHR,
    "Message 1");

  // Push debug group 1
  ext.pushDebugGroupKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR,
    1,
    "Message 2");

  // Setup of the debug group 1: Filter everything out
  ext.debugMessageControlKHR(gl.DONT_CARE, gl.DONT_CARE, gl.DONT_CARE, [], false);

  // This message won't appear in the debug output log of
  ext.debugMessageInsertKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR,
    ext.DEBUG_TYPE_MARKER_KHR, 100,
    ext.DEBUG_SEVERITY_NOTIFICATION_KHR,
    "Message 3");

  // Pop debug group 1, restore the volume control of the default debug group.
  ext.popDebugGroupKHR();

  // Generate a debug marker debug output message
  ext.debugMessageInsertKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR,
    ext.DEBUG_TYPE_MARKER_KHR, 100,
    ext.DEBUG_SEVERITY_NOTIFICATION_KHR,
    "Message 5");

  ...

  // Expected debug output in the JS console:
  // Message 1
  // Message 2
  // Message 2
  // Message 5
}

function draw(gl, ext) {
  ...

  // Setup the control of the debug output for the default debug group
  ext.debugMessageControlKHR(
    gl.DONT_CARE, gl.DONT_CARE, gl.DONT_CARE, [], false);
  ext.debugMessageControlKHR(
    ext.DEBUG_SOURCE_THIRD_PARTY_KHR, gl.DONT_CARE, gl.DONT_CARE, [], false);
  var messages = [1234, 2345, 3456, 4567];
  ext.debugMessageControlKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR, gl.DEBUG_TYPE_OTHER, gl.DONT_CARE,
    messages, false);
  ext.debugMessageControlKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR, ext.DEBUG_TYPE_PORTABILITY_KHR, gl.DONT_CARE,
    messages, false);

  // Push debug group 1
  // Inherit the default debug group debug output volume control
  // Filtered out by ext.debugMessageControlKHR
  ext.pushDebugGroupKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR,
    1,
    "Message 1");

  // In this section of the code, we are interested in performances.
  ext.debugMessageControlKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR, ext.DEBUG_TYPE_PERFORMANCE_KHR, gl.DONT_CARE, [], true);
  // But we already identify that some messages are not really useful for us.
  ext.debugMessageControlKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR, ext.DEBUG_TYPE_OTHER_KHR, gl.DONT_CARE,
    [5678, 6789], false);

  ext.debugMessageInsertKHR(
    ext.DEBUG_SOURCE_APPLICATION_KHR,
    ext.DEBUG_TYPE_PERFORMANCE_KHR, 1357,
    ext.DEBUG_SEVERITY_MEDIUM_KHR,
    "Message 2");
  ext.debugMessageInsertKHR(
    ext.DEBUG_SOURCE_THIRD_PARTY_KHR, // We still filter out these messages.
    ext.DEBUG_TYPE_OTHER_KHR, 3579,
    ext.DEBUG_SEVERITY_MEDIUM_KHR,
    "Message 3");

  ext.popDebugGroupKHR();

  ...

  // Expected debug output in the JS console:
  // Message 2
}

Revision History

Revision 1, 2015/09/18

• Initial revision.