1'''OpenGL extension KHR.debug 2 3This module customises the behaviour of the 4OpenGL.raw.GL.KHR.debug to provide a more 5Python-friendly API 6 7Overview (from the spec) 8 9 This extension allows the GL to notify applications when various events 10 occur that may be useful during application development, debugging and 11 profiling. 12 13 These events are represented in the form of enumerable messages with a 14 human-readable string representation. Examples of debug events include 15 incorrect use of the GL, warnings of undefined behavior, and performance 16 warnings. 17 18 A message is uniquely identified by a source, a type and an 19 implementation-dependent ID within the source and type pair. 20 21 A message's source identifies the origin of the message and can either 22 describe components of the GL, the window system, third-party external 23 sources such as external debuggers, or even the application itself. 24 25 The type of the message roughly identifies the nature of the event that 26 caused the message. Examples include errors, performance warnings, 27 warnings about undefined behavior or notifications identifying that the 28 application is within a specific section of the application code. 29 30 A message's ID for a given source and type further distinguishes messages 31 within namespaces. For example, an error caused by a negative parameter 32 value or an invalid internal texture format are both errors generated by 33 the API, but would likely have different message IDs. 34 35 Each message is also assigned to a severity level that denotes roughly how 36 "important" that message is in comparison to other messages across all 37 sources and types. For example, notification of a GL error would likely 38 have a higher severity than a performance warning due to redundant state 39 changes. 40 41 Furthermore, every message contains an implementation-dependent string 42 representation that provides a useful description of the event. 43 44 Messages are communicated to the application through an application- 45 defined callback function that is called by the GL implementation on each 46 debug message. The motivation for the callback routine is to free 47 application developers from actively having to query whether a GL error, 48 or any other debuggable event has happened after each call to a GL 49 function. With a callback, developers can keep their code free of debug 50 checks, set breakpoints in the callback function, and only have to react 51 to messages as they occur. In situations where using a callback is not 52 possible, a message log is also provided that stores only copies of recent 53 messages until they are actively queried. 54 55 To control the volume of debug output, messages can be disabled either 56 individually by ID, or entire sets of messages can be turned off based on 57 combination of source and type, through the entire application code or 58 only section of the code encapsulated in debug groups. A debug group may 59 also be used to annotate the command stream using descriptive texts. 60 61 This extension also defines debug markers, a mechanism for the OpenGL 62 application to annotate the command stream with markers for discrete 63 events. 64 65 When profiling or debugging an OpenGL application with a built-in or an 66 external debugger or profiler, it is difficult to relate the commands 67 within the command stream to the elements of the scene or parts of the 68 program code to which they correspond. Debug markers and debug groups help 69 obviate this by allowing applications to specify this link. For example, a 70 debug marker can be used to identify the beginning of a frame in the 71 command stream and a debug group can encapsulate a specific command stream 72 to identify a rendering pass. Debug groups also allow control of the debug 73 outputs volume per section of an application code providing an effective 74 way to handle the massive amount of debug outputs that drivers can 75 generate. 76 77 Some existing implementations of ARB_debug_output only expose the 78 ARB_debug_output extension string if the context was created with the 79 debug flag {GLX|WGL}_CONTEXT_DEBUG_BIT_ARB as specified in 80 {GLX|WGL}_ARB_create_context. The behavior is not obvious when the 81 functionality is brought into the OpenGL core specification because the 82 extension string and function entry points must always exist. 83 84 This extension modifies the existing ARB_debug_output extension to allow 85 implementations to always have an empty message log. The specific messages 86 written to the message log or callback routines are already implementation 87 defined, so this specification simply makes it explicit that it's fine for 88 there to be zero messages generated, even when a GL error occurs, which is 89 useful if the context is non-debug. 90 91 Debug output can be enabled and disabled by changing the DEBUG_OUTPUT 92 state. It is implementation defined how much debug output is generated if 93 the context was created without the CONTEXT_DEBUG_BIT set. This is a new 94 query bit added to the existing GL_CONTEXT_FLAGS state to specify whether 95 the context was created with debug enabled. 96 97 Finally, this extension defines a mechanism for OpenGL applications to 98 label their objects (textures, buffers, shaders, etc.) with a descriptive 99 string. 100 101 When profiling or debugging an OpenGL application within an external or 102 built-in (debut output API) debugger or profiler it is difficult to 103 identify objects from their object names (integers). 104 105 Even when the object itself is viewed it can be problematic to 106 differentiate between similar objects. Attaching a descriptive string, a 107 label, to an object obviates this difficulty. 108 109 The intended purpose of this extension is purely to improve the user 110 experience within OpenGL development tools and application built-in 111 profilers and debuggers. This extension typically improves OpenGL 112 programmers efficiency by allowing them to instantly detect issues and the 113 reason for these issues giving him more time to focus on adding new 114 features to an OpenGL application. 115 116The official definition of this extension is available here: 117http://www.opengl.org/registry/specs/KHR/debug.txt 118''' 119from OpenGL import platform, constant, arrays 120from OpenGL import extensions, wrapper 121import ctypes 122from OpenGL.raw.GL import _types, _glgets 123from OpenGL.raw.GL.KHR.debug import * 124from OpenGL.raw.GL.KHR.debug import _EXTENSION_NAME 125 126def glInitDebugKHR(): 127 '''Return boolean indicating whether this extension is available''' 128 from OpenGL import extensions 129 return extensions.hasGLExtension( _EXTENSION_NAME ) 130 131# INPUT glDebugMessageControl.ids size not checked against count 132glDebugMessageControl=wrapper.wrapper(glDebugMessageControl).setInputArraySize( 133 'ids', None 134) 135# INPUT glDebugMessageInsert.buf size not checked against 'buf,length' 136glDebugMessageInsert=wrapper.wrapper(glDebugMessageInsert).setInputArraySize( 137 'buf', None 138) 139glGetDebugMessageLog=wrapper.wrapper(glGetDebugMessageLog).setOutput( 140 'ids',size=lambda x:(x,),pnameArg='count',orPassIn=True 141).setOutput( 142 'lengths',size=lambda x:(x,),pnameArg='count',orPassIn=True 143).setOutput( 144 'messageLog',size=lambda x:(x,),pnameArg='bufSize',orPassIn=True 145).setOutput( 146 'severities',size=lambda x:(x,),pnameArg='count',orPassIn=True 147).setOutput( 148 'sources',size=lambda x:(x,),pnameArg='count',orPassIn=True 149).setOutput( 150 'types',size=lambda x:(x,),pnameArg='count',orPassIn=True 151) 152# INPUT glPushDebugGroup.message size not checked against 'message,length' 153glPushDebugGroup=wrapper.wrapper(glPushDebugGroup).setInputArraySize( 154 'message', None 155) 156# INPUT glObjectLabel.label size not checked against 'label,length' 157glObjectLabel=wrapper.wrapper(glObjectLabel).setInputArraySize( 158 'label', None 159) 160glGetObjectLabel=wrapper.wrapper(glGetObjectLabel).setOutput( 161 'label',size=lambda x:(x,),pnameArg='bufSize',orPassIn=True 162).setOutput( 163 'length',size=(1,),orPassIn=True 164) 165# INPUT glObjectPtrLabel.label size not checked against 'label,length' 166glObjectPtrLabel=wrapper.wrapper(glObjectPtrLabel).setInputArraySize( 167 'label', None 168) 169glGetObjectPtrLabel=wrapper.wrapper(glGetObjectPtrLabel).setOutput( 170 'label',size=lambda x:(x,),pnameArg='bufSize',orPassIn=True 171).setOutput( 172 'length',size=(1,),orPassIn=True 173) 174glGetPointerv=wrapper.wrapper(glGetPointerv).setOutput( 175 'params',size=(1,),orPassIn=True 176) 177# INPUT glGetDebugMessageLogKHR.ids size not checked against count 178# INPUT glGetDebugMessageLogKHR.lengths size not checked against count 179# INPUT glGetDebugMessageLogKHR.messageLog size not checked against bufSize 180# INPUT glGetDebugMessageLogKHR.severities size not checked against count 181# INPUT glGetDebugMessageLogKHR.sources size not checked against count 182# INPUT glGetDebugMessageLogKHR.types size not checked against count 183glGetDebugMessageLogKHR=wrapper.wrapper(glGetDebugMessageLogKHR).setInputArraySize( 184 'ids', None 185).setInputArraySize( 186 'lengths', None 187).setInputArraySize( 188 'messageLog', None 189).setInputArraySize( 190 'severities', None 191).setInputArraySize( 192 'sources', None 193).setInputArraySize( 194 'types', None 195) 196# INPUT glGetObjectLabelKHR.label size not checked against bufSize 197glGetObjectLabelKHR=wrapper.wrapper(glGetObjectLabelKHR).setInputArraySize( 198 'label', None 199) 200# INPUT glGetObjectPtrLabelKHR.label size not checked against bufSize 201glGetObjectPtrLabelKHR=wrapper.wrapper(glGetObjectPtrLabelKHR).setInputArraySize( 202 'label', None 203).setInputArraySize( 204 'length', 1 205) 206### END AUTOGENERATED SECTION