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