diff options
Diffstat (limited to 'docs/MESA_shader_debug.spec')
| -rw-r--r-- | docs/MESA_shader_debug.spec | 139 |
1 files changed, 105 insertions, 34 deletions
diff --git a/docs/MESA_shader_debug.spec b/docs/MESA_shader_debug.spec index 0aef8f7df84..dbd22b3c667 100644 --- a/docs/MESA_shader_debug.spec +++ b/docs/MESA_shader_debug.spec @@ -17,9 +17,9 @@ Status Version - Last Modified Date: May 29, 2006 - Author Revision: 0.1 - $Date: 2006/05/30 09:35:36 $ $Revision: 1.1 $ + Last Modified Date: July 30, 2006 + Author Revision: 0.2 + $Date: 2006/07/30 14:28:38 $ $Revision: 1.2 $ Number @@ -27,16 +27,26 @@ Number Dependencies - OpenGL 1.5 is required. + OpenGL 1.0 is required. + + The ARB_shader_objects extension is required. + + The ARB_shading_language_100 extension is required. + The extension is written against the OpenGL 1.5 specification. - ARB_shading_language_100 is required. - ARB_shader_objects is required. - The extension is written against the OpenGL Shading Language - 1.10 Specification. + + The extension is written against the OpenGL Shading Language 1.10 + Specification. Overview - TBD + This extension introduces a debug object that can be attached to + a program object to enable debugging. Vertex and/or fragment shader, + during execution, issue diagnostic function calls that are logged + to the debug object's log. A separate debug log for each shader type + is maintained. A debug object can be attached, detached and queried + at any time outside the Begin/End pair. Multiple debug objects can + be attached to a single program object. IP Status @@ -48,7 +58,13 @@ Issues New Procedures and Functions - TBD + handleARB CreateDebugObjectMESA(void) + void ClearDebugLogMESA(handleARB obj, enum logType, enum shaderType) + void GetDebugLogMESA(handleARB obj, enum logType, enum shaderType, + sizei maxLength, sizei *length, + charARB *debugLog) + sizei GetDebugLogLengthMESA(handleARB obj, enum logType, + enum shaderType) New Types @@ -56,7 +72,15 @@ New Types New Tokens - TBD + Returned by the <params> parameter of GetObjectParameter{fi}vARB: + + DEBUG_OBJECT_MESA 0x8759 + + Accepted by the <logType> argument of ClearDebugLogMESA, + GetDebugLogLengthMESA and GetDebugLogMESA: + + DEBUG_PRINT_MESA 0x875A + DEBUG_ASSERT_MESA 0x875B Additions to Chapter 2 of the OpenGL 1.5 Specification (OpenGL Operation) @@ -128,31 +152,75 @@ Additions to Chapter 8 of the OpenGL Shading Language 1.10 Specification Debug functions are available to both fragment and vertex shaders. They are used to track the execution of a shader by logging - passed-in arguments to the shader's info log. That values can be - retrieved and validated by the application after shader execution + passed-in arguments to the debug object's log. Those values can be + retrieved by the application for inspection after shader execution is complete. - void printMESA(const float value); - void printMESA(const int value); - void printMESA(const bool value); - void printMESA(const vec2 value); - void printMESA(const vec3 value); - void printMESA(const vec4 value); - void printMESA(const ivec2 value); - void printMESA(const ivec3 value); - void printMESA(const ivec4 value); - void printMESA(const bvec2 value); - void printMESA(const bvec3 value); - void printMESA(const bvec4 value); - void printMESA(const mat2 value); - void printMESA(const mat3 value); - void printMESA(const mat4 value); - void printMESA(const sampler1D value); - void printMESA(const sampler2D value); - void printMESA(const sampler3D value); - void printMESA(const samplerCube value); - void printMESA(const sampler1DShadow value); - void printMESA(const sampler2DShadow value); + The text, if any, produced by any of these functions is appended + to each debug object that is attached to the program object. + There are different debug log types + + Add a new section 8.10.1 "Print Function": + + The following printMESA prototypes are available. + + void printMESA(const float value) + void printMESA(const int value) + void printMESA(const bool value) + void printMESA(const vec2 value) + void printMESA(const vec3 value) + void printMESA(const vec4 value) + void printMESA(const ivec2 value) + void printMESA(const ivec3 value) + void printMESA(const ivec4 value) + void printMESA(const bvec2 value) + void printMESA(const bvec3 value) + void printMESA(const bvec4 value) + void printMESA(const mat2 value) + void printMESA(const mat3 value) + void printMESA(const mat4 value) + void printMESA(const sampler1D value) + void printMESA(const sampler2D value) + void printMESA(const sampler3D value) + void printMESA(const samplerCube value) + void printMESA(const sampler1DShadow value) + void printMESA(const sampler2DShadow value) + + The printMESA function writes the argument <value> to the "debug + print log" (XXX DEBUG_PRINT_MESA?). Each component is written in + text format (XXX format!) and is delimited by a white space (XXX 1 + or more?). + + Add a new section 8.10.2 "Assert Function": + + The following assertMESA prototypes are available. + + void assertMESA(const bool condition) + void assertMESA(const bool condition, const int cookie) + void assertMESA(const bool condition, const int cookie, + const int file, const int line) + + The assertMESA function checks if the argument <condition> is + true or false. If it is true, nothing happens. If it is false, + a diagnostic message is written to the "debug assert log". + The message contains the argument <file>, <line>, <cookie> and + implementation dependent double-quoted string, each of this + delimited by a white space. If the argument <cookie> is not present, + it is meant as if it was of value 0. If the arguments <file> and + <line> are not present, they are meant as if they were of values + __FILE__ and __LINE__, respectively. The following three calls + produce the same output, assuming they were issued from the same + file and line. + + assertMESA (false); + assertMESA (false, 0); + assertMESA (false, 0, __FILE__, __LINE__); + + The diagnostic message examples follow. + + 1 89 0 "" + 1 45 333 "all (lessThanEqual (fragColor, vec4 (1.0)))" + 1 66 1 "assertion failed in file 1, line 66, cookie 1" Additions to Chapter 9 of the OpenGL Shading Language 1.10 Specification (Shading Language Grammar) @@ -192,3 +260,6 @@ Revision History 29 May 2006 Initial draft. (Michal Krol) + 30 July 2006 + Add Overview, New Procedures and Functions, New Tokens sections. + Add sections 8.10.1, 8.10.2 to GLSL spec. |