Revision control
Copy as Markdown
Other Tools
<?xml version="1.0" encoding="UTF-8"?>
<proposal href="proposals/WEBGL_debug/">
<name>WEBGL_debug</name>
working group</a> (public_webgl 'at' khronos.org) </contact>
<contributors>
<contributor>Emmanuel Gil Peyrot, Collabora Ltd.</contributor>
<contributor>Members of the WebGL working group</contributor>
</contributors>
<number>NN</number>
<depends>
<api version="1.0"/>
</depends>
<overview id="overview">
<p>
This extension allows the GL to notify applications when various events
occur that may be useful during application development, debugging and
profiling.
</p>
name="KHR_debug">
<addendum>
References to debug contexts are deleted.
</addendum>
<addendum>
References to the debug message log and callback are deleted, replaced
with DOM events.
</addendum>
<addendum>
The <code>ObjectPtrLabel</code> and <code>GetObjectPtrLabel</code>
functions are replaced with <code>ObjectLabel</code> and
<code>GetObjectLabel</code>.
</addendum>
<addendum>
The <code>count</code> and <code>ids</code> arguments of
<code>DebugMessageControl</code> are replaced with a
<code>sequence<GLuint> ids</code> argument.
</addendum>
<addendum>
The <code>length</code> and <code>buf</code> arguments of
<code>DebugMessageInsert</code> and <code>PushDebugGroup</code> are
replaced with a <code>DOMString message</code> argument.
</addendum>
<addendum>
The <code>identifier</code> and <code>name</code> arguments of
<code>ObjectLabel</code> and <code>GetObjectLabel</code> are replaced
with a <code>WebGLObject object</code> argument.
</addendum>
<addendum>
The <code>length</code> and <code>label</code> arguments of
<code>ObjectLabel</code> are replaced with a <code>DOMString
label</code> argument.
</addendum>
<addendum>
The <code>bufSize</code>, <code>length</code> and <code>label</code>
arguments of <code>GetObjectLabel</code> are replaced with a
<code>DOMString</code> return type.
</addendum>
<addendum>
As per the usual WebGL binding rules, functions don’t keep the KHR
suffix they have in the GLES version, but tokens do.
</addendum>
</mirrors>
<features>
<feature>
The <code>WEBGL_debug</code> extension object is a DOM
<code>EventTarget</code>, obeying the rules of the <a
with a new <code>WebGLDebugMessage</code> event that gets fired
whenever the driver, browser or application emits a debug message.
</feature>
<feature>
<code>debugMessageInsertKHR</code> is exposed to allow the application
to insert debug messages into the WebGL stream.
</feature>
<feature>
<code>objectLabelKHR</code> and <code>getObjectLabelKHR</code> are
exposed, to assign a label to a <code>WebGLObject</code> and retrieve
it.
</feature>
<feature>
<code>pushDebugGroupKHR</code> and <code>popDebugGroupKHR</code> make
it possible to group a list of WebGL calls together.
</feature>
<feature>
<code>debugMessageControlKHR</code> allows the application to enable
and disable the debug messages which emit a
<code>WebGLDebugMessage</code> event. This state is part of the debug
group they are part of, and gets poped on
<code>popDebugGroupKHR</code>.
</feature>
</features>
</overview>
<idl xml:space="preserve"><![CDATA[
[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
]]></idl>
<newfun>
<p>On <code>WEBGL_debug</code>:</p>
<function name="debugMessageControlKHR" type="void">
<param name="source" type="GLenum"/>
<param name="type" type="GLenum"/>
<param name="severity" type="GLenum"/>
<param name="ids" type="sequence<GLuint>"/>
<param name="enabled" type="boolean"/>
Enables or disables the reporting of <code>WebGLDebugMessage</code>
events for the specified messages.
</function>
<function name="debugMessageInsertKHR" type="void">
<param name="source" type="GLenum"/>
<param name="type" type="GLenum"/>
<param name="id" type="GLuint"/>
<param name="severity" type="GLenum"/>
<param name="message" type="DOMString"/>
Inserts a custom message into the debug log.
</function>
<function name="pushDebugGroupKHR" type="void">
<param name="source" type="GLenum"/>
<param name="id" type="GLuint"/>
<param name="message" type="DOMString"/>
Pushes a debug group on the stack.
</function>
<function name="popDebugGroupKHR" type="void">
Closes a group opened with <code>pushDebugGroupKHR</code>.
</function>
<function name="objectLabelKHR" type="void">
<param name="object" type="WebGLObject?"/>
<param name="label" type="DOMString"/>
Assigns a label to a <code>WebGLObject</code>.
</function>
<function name="getObjectLabelKHR" type="DOMString">
<param name="object" type="WebGLObject?"/>
Retrieves the label associated with a <code>WebGLObject</code>.
</function>
<function name="addEventListener" type="void">
<param name="type" type="DOMString"/>
<param name="listener" type="EventListener"/>
Register an event handler of a specific event type on the EventTarget.
</function>
<function name="removeEventListener" type="void">
<param name="type" type="DOMString"/>
<param name="listener" type="EventListener"/>
Removes an event listener from the EventTarget.
</function>
<function name="dispatchEvent" type="boolean">
<param name="event" type="Event"/>
Dispatch an event to this EventTarget.
</function>
</newfun>
<samplecode><div class="example">
Common initialization of the extension, with an example of debug message
reporting.
<pre xml:space="preserve"><![CDATA[
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);
});
...
}]]></pre></div></samplecode>
<samplecode><div class="example">
Skip a section of the code.
<pre xml:space="preserve"><![CDATA[
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
}]]></pre></div></samplecode>
<samplecode><div class="example">
Only output a subsection of the code and disable some messages for the
entire application.
<pre xml:space="preserve"><![CDATA[
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
}]]></pre></div></samplecode>
<history>
<revision date="2015/09/18">
<change>Initial revision.</change>
</revision>
</history>
</proposal>