extension.xml - mozsearch

mozilla-central/third_party/rust/khronos_api/api_webgl/extensions/proposals/WEBGL_debug/extension.xml

Enable keyboard shortcuts

Source code

File a bug in Firefox Build System :: General

Revision control

Copy as Markdown

Other Tools

<?xml version="1.0" encoding="UTF-8"?>

<proposal href="proposals/WEBGL_debug/">

  <name>WEBGL_debug</name>

  <contact> <a href="https://www.khronos.org/webgl/public-mailing-list/">WebGL

  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>

    <mirrors href="https://www.opengl.org/registry/specs/KHR/debug.txt"

             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&lt;GLuint&gt; 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

        href="http://www.w3.org/TR/DOM-Level-3-Events/">DOM Level 3 Events</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&lt;GLuint&gt;"/>

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