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