diff options
Diffstat (limited to 'third_party/rust/khronos_api/api_webgl/extensions/proposals/WEBGL_debug/extension.xml')
| -rw-r--r-- | third_party/rust/khronos_api/api_webgl/extensions/proposals/WEBGL_debug/extension.xml | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/third_party/rust/khronos_api/api_webgl/extensions/proposals/WEBGL_debug/extension.xml b/third_party/rust/khronos_api/api_webgl/extensions/proposals/WEBGL_debug/extension.xml new file mode 100644 index 0000000000..3daa9e0c70 --- /dev/null +++ b/third_party/rust/khronos_api/api_webgl/extensions/proposals/WEBGL_debug/extension.xml @@ -0,0 +1,359 @@ +<?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<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 + 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<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> |