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