1'''OpenGL extension ARB.debug_output 2 3This module customises the behaviour of the 4OpenGL.raw.GL.ARB.debug_output to provide a more 5Python-friendly API 6 7Overview (from the spec) 8 9 This extension allows the GL to notify applications when various 10 events occur that may be useful during application development and 11 debugging. 12 13 These events are represented in the form of enumerable messages with 14 a human-readable string representation. Examples of debug events 15 include incorrect use of the GL, warnings of undefined behavior, and 16 performance 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 22 either describe components of the GL, the window system, 23 third-party external sources such as external debuggers, or even 24 the application itself. 25 26 The type of the message roughly identifies the nature of the event 27 that caused the message. Examples include errors, performance 28 warnings, or warnings about undefined behavior. 29 30 A message's ID for a given source and type further 31 distinguishes messages within those groups. For example, an error 32 caused by a negative parameter value or an invalid internal 33 texture format are both errors generated by the API, but would 34 likely have different message IDs. 35 36 Each message is also assigned to a severity level that denotes 37 roughly how "important" that message is in comparison to other 38 messages across all sources and types. For example, notification 39 of a GL error would likely have a higher severity than a performance 40 warning due to redundant state changes. 41 42 Finally, every message contains an implementation-dependent string 43 representation that provides a useful description of the event. 44 45 Messages are communicated to the application through an application- 46 defined callback function that is called by the GL implementation on 47 each debug message. The motivation for the callback routine is to 48 free application developers from actively having to query whether 49 a GL error, or any other debuggable event has happened after each 50 call to a GL function. With a callback, developers can keep their 51 code free of debug checks, and only have to react to messages as 52 they occur. In situations where using a callback is not possible, 53 a message log is also provided that stores copies of recent messages 54 until they are actively queried. 55 56 To control the volume of debug output, messages can be disabled 57 either individually by ID, or entire groups of messages can be 58 turned off based on combination of source and type. 59 60 The only requirement on the minimum quantity and type of messages 61 that implementations of this extension must support is that some 62 sort of message must be sent notifying the application whenever any 63 GL error occurs. Any further messages are left to the 64 implementation. Implementations do not have to output messages from 65 all sources nor do they have to use all types of messages listed 66 by this extension, and both new sources and types can be added by 67 other extensions. 68 69 For performance reasons it is recommended, but not required, that 70 implementations restrict supporting this extension only to 71 contexts created using the debug flag as provided by 72 WGL_create_context or GLX_create_context. This extension places no 73 limits on any other functionality provided by debug contexts through 74 other extensions. 75 76The official definition of this extension is available here: 77http://www.opengl.org/registry/specs/ARB/debug_output.txt 78''' 79from OpenGL import platform, constant, arrays 80from OpenGL import extensions, wrapper 81import ctypes 82from OpenGL.raw.GL import _types, _glgets 83from OpenGL.raw.GL.ARB.debug_output import * 84from OpenGL.raw.GL.ARB.debug_output import _EXTENSION_NAME 85 86def glInitDebugOutputARB(): 87 '''Return boolean indicating whether this extension is available''' 88 from OpenGL import extensions 89 return extensions.hasGLExtension( _EXTENSION_NAME ) 90 91# INPUT glDebugMessageControlARB.ids size not checked against count 92glDebugMessageControlARB=wrapper.wrapper(glDebugMessageControlARB).setInputArraySize( 93 'ids', None 94) 95# INPUT glDebugMessageInsertARB.buf size not checked against length 96glDebugMessageInsertARB=wrapper.wrapper(glDebugMessageInsertARB).setInputArraySize( 97 'buf', None 98) 99# INPUT glDebugMessageCallbackARB.userParam size not checked against 'callback' 100glDebugMessageCallbackARB=wrapper.wrapper(glDebugMessageCallbackARB).setInputArraySize( 101 'userParam', None 102) 103glGetDebugMessageLogARB=wrapper.wrapper(glGetDebugMessageLogARB).setOutput( 104 'lengths',size=lambda x:(x,),pnameArg='count',orPassIn=True 105).setOutput( 106 'ids',size=lambda x:(x,),pnameArg='count',orPassIn=True 107).setOutput( 108 'severities',size=lambda x:(x,),pnameArg='count',orPassIn=True 109).setOutput( 110 'sources',size=lambda x:(x,),pnameArg='count',orPassIn=True 111).setOutput( 112 'messageLog',size=lambda x:(x,),pnameArg='bufSize',orPassIn=True 113).setOutput( 114 'types',size=lambda x:(x,),pnameArg='count',orPassIn=True 115) 116### END AUTOGENERATED SECTION