1'''OpenGL extension EXT.framebuffer_object
2
3This module customises the behaviour of the
4OpenGL.raw.GL.EXT.framebuffer_object to provide a more
5Python-friendly API
6
7Overview (from the spec)
8
9	This extension defines a simple interface for drawing to rendering
10	destinations other than the buffers provided to the GL by the
11	window-system.
12
13	In this extension, these newly defined rendering destinations are
14	known collectively as "framebuffer-attachable images".  This
15	extension provides a mechanism for attaching framebuffer-attachable
16	images to the GL framebuffer as one of the standard GL logical
17	buffers: color, depth, and stencil.  (Attaching a
18	framebuffer-attachable image to the accum logical buffer is left for
19	a future extension to define).  When a framebuffer-attachable image
20	is attached to the framebuffer, it is used as the source and
21	destination of fragment operations as described in Chapter 4.
22
23	By allowing the use of a framebuffer-attachable image as a rendering
24	destination, this extension enables a form of "offscreen" rendering.
25	Furthermore, "render to texture" is supported by allowing the images
26	of a texture to be used as framebuffer-attachable images.  A
27	particular image of a texture object is selected for use as a
28	framebuffer-attachable image by specifying the mipmap level, cube
29	map face (for a cube map texture), and z-offset (for a 3D texture)
30	that identifies the image.  The "render to texture" semantics of
31	this extension are similar to performing traditional rendering to
32	the framebuffer, followed immediately by a call to CopyTexSubImage.
33	However, by using this extension instead, an application can achieve
34	the same effect, but with the advantage that the GL can usually
35	eliminate the data copy that would have been incurred by calling
36	CopyTexSubImage.
37
38	This extension also defines a new GL object type, called a
39	"renderbuffer", which encapsulates a single 2D pixel image.  The
40	image of renderbuffer can be used as a framebuffer-attachable image
41	for generalized offscreen rendering and it also provides a means to
42	support rendering to GL logical buffer types which have no
43	corresponding texture format (stencil, accum, etc).  A renderbuffer
44	is similar to a texture in that both renderbuffers and textures can
45	be independently allocated and shared among multiple contexts.  The
46	framework defined by this extension is general enough that support
47	for attaching images from GL objects other than textures and
48	renderbuffers could be added by layered extensions.
49
50	To facilitate efficient switching between collections of
51	framebuffer-attachable images, this extension introduces another new
52	GL object, called a framebuffer object.  A framebuffer object
53	contains the state that defines the traditional GL framebuffer,
54	including its set of images.  Prior to this extension, it was the
55	window-system which defined and managed this collection of images,
56	traditionally by grouping them into a "drawable".  The window-system
57	API's would also provide a function (i.e., wglMakeCurrent,
58	glXMakeCurrent, aglSetDrawable, etc.) to bind a drawable with a GL
59	context (as is done in the WGL_ARB_pbuffer extension).  In this
60	extension however, this functionality is subsumed by the GL and the
61	GL provides the function BindFramebufferEXT to bind a framebuffer
62	object to the current context.  Later, the context can bind back to
63	the window-system-provided framebuffer in order to display rendered
64	content.
65
66	Previous extensions that enabled rendering to a texture have been
67	much more complicated.  One example is the combination of
68	ARB_pbuffer and ARB_render_texture, both of which are window-system
69	extensions.  This combination requires calling MakeCurrent, an
70	operation that may be expensive, to switch between the window and
71	the pbuffer drawables.  An application must create one pbuffer per
72	renderable texture in order to portably use ARB_render_texture.  An
73	application must maintain at least one GL context per texture
74	format, because each context can only operate on a single
75	pixelformat or FBConfig.  All of these characteristics make
76	ARB_render_texture both inefficient and cumbersome to use.
77
78	EXT_framebuffer_object, on the other hand, is both simpler to use
79	and more efficient than ARB_render_texture.  The
80	EXT_framebuffer_object API is contained wholly within the GL API and
81	has no (non-portable) window-system components.  Under
82	EXT_framebuffer_object, it is not necessary to create a second GL
83	context when rendering to a texture image whose format differs from
84	that of the window.  Finally, unlike the pbuffers of
85	ARB_render_texture, a single framebuffer object can facilitate
86	rendering to an unlimited number of texture objects.
87
88The official definition of this extension is available here:
89http://www.opengl.org/registry/specs/EXT/framebuffer_object.txt
90'''
91from OpenGL import platform, constant, arrays
92from OpenGL import extensions, wrapper
93import ctypes
94from OpenGL.raw.GL import _types, _glgets
95from OpenGL.raw.GL.EXT.framebuffer_object import *
96from OpenGL.raw.GL.EXT.framebuffer_object import _EXTENSION_NAME
97
98def glInitFramebufferObjectEXT():
99    '''Return boolean indicating whether this extension is available'''
100    from OpenGL import extensions
101    return extensions.hasGLExtension( _EXTENSION_NAME )
102
103# INPUT glDeleteRenderbuffersEXT.renderbuffers size not checked against n
104glDeleteRenderbuffersEXT=wrapper.wrapper(glDeleteRenderbuffersEXT).setInputArraySize(
105    'renderbuffers', None
106)
107glGenRenderbuffersEXT=wrapper.wrapper(glGenRenderbuffersEXT).setOutput(
108    'renderbuffers',size=lambda x:(x,),pnameArg='n',orPassIn=True
109)
110glGetRenderbufferParameterivEXT=wrapper.wrapper(glGetRenderbufferParameterivEXT).setOutput(
111    'params',size=_glgets._glget_size_mapping,pnameArg='pname',orPassIn=True
112)
113# INPUT glDeleteFramebuffersEXT.framebuffers size not checked against n
114glDeleteFramebuffersEXT=wrapper.wrapper(glDeleteFramebuffersEXT).setInputArraySize(
115    'framebuffers', None
116)
117glGenFramebuffersEXT=wrapper.wrapper(glGenFramebuffersEXT).setOutput(
118    'framebuffers',size=lambda x:(x,),pnameArg='n',orPassIn=True
119)
120glGetFramebufferAttachmentParameterivEXT=wrapper.wrapper(glGetFramebufferAttachmentParameterivEXT).setOutput(
121    'params',size=_glgets._glget_size_mapping,pnameArg='pname',orPassIn=True
122)
123### END AUTOGENERATED SECTION
124from OpenGL.lazywrapper import lazy as _lazy
125
126glGenFramebuffersEXT = wrapper.wrapper(glGenFramebuffersEXT).setOutput(
127                'framebuffers',
128                lambda x: (x,),
129                'n', orPassIn=True)
130
131glGenRenderbuffersEXT = wrapper.wrapper(glGenRenderbuffersEXT).setOutput(
132                'renderbuffers',
133                lambda x: (x,),
134                'n', orPassIn=True)
135
136@_lazy( glDeleteFramebuffersEXT )
137def glDeleteFramebuffersEXT( baseOperation, n, framebuffers=None ):
138    """glDeleteFramebuffersEXT( framebuffers ) -> None
139    """
140    if framebuffers is None:
141        framebuffers = arrays.GLuintArray.asArray( n )
142        n = arrays.GLuintArray.arraySize( framebuffers )
143    return baseOperation( n, framebuffers )
144