WebGL
Khronos
 

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:

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

When this extension is enabled:

IDL

[NoInterfaceObject]
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;

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

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

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

[NoInterfaceObject]
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:

void debugMessageControlKHR(GLenum source, GLenum type, GLenum severity, sequence<GLuint> ids, boolean enabled)
Enables or disables the reporting of WebGLDebugMessage events for the specified messages.
void debugMessageInsertKHR(GLenum source, GLenum type, GLuint id, GLenum severity, DOMString message)
Inserts a custom message into the debug log.
void pushDebugGroupKHR(GLenum source, GLuint id, DOMString message)
Pushes a debug group on the stack.
void popDebugGroupKHR()
Closes a group opened with pushDebugGroupKHR.
void objectLabelKHR(WebGLObject? object, DOMString label)
Assigns a label to a WebGLObject.
DOMString getObjectLabelKHR(WebGLObject? object)
Retrieves the label associated with a WebGLObject.
void addEventListener(DOMString type, EventListener listener)
Register an event handler of a specific event type on the EventTarget.
void removeEventListener(DOMString type, EventListener listener)
Removes an event listener from the EventTarget.
boolean dispatchEvent(Event event)
Dispatch an event to this EventTarget.

Sample Code

Common initialization of the extension, with an example of debug message reporting.
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);
  });
  ...
}
Skip a section of the code.
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
}
Only output a subsection of the code and disable some messages for the entire application.
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