diff options
Diffstat (limited to 'docs/specs')
22 files changed, 4290 insertions, 0 deletions
diff --git a/docs/specs/MESA_agp_offset.spec b/docs/specs/MESA_agp_offset.spec new file mode 100644 index 00000000000..06e1d902edd --- /dev/null +++ b/docs/specs/MESA_agp_offset.spec @@ -0,0 +1,95 @@ +Name + + MESA_agp_offset + +Name Strings + + GLX_MESA_agp_offset + +Contact + + Brian Paul, Tungsten Graphics, Inc. (brian.paul 'at' tungstengraphics.com) + Keith Whitwell, Tungsten Graphics, Inc. (keith 'at' tungstengraphics.com) + +Status + + Shipping (Mesa 4.0.4 and later. Only implemented in particular + XFree86/DRI drivers.) + +Version + + 1.0 + +Number + + TBD + +Dependencies + + OpenGL 1.0 or later is required + GLX_NV_vertex_array_range is required. + This extensions is written against the OpenGL 1.4 Specification. + +Overview + + This extensions provides a way to convert pointers in an AGP memory + region into byte offsets into the AGP aperture. + Note, this extension depends on GLX_NV_vertex_array_range, for which + no real specification exists. See GL_NV_vertex_array_range for more + information. + +IP Status + + None + +Issues + + None + +New Procedures and Functions + + unsigned int glXGetAGPOffsetMESA( const void *pointer ) + +New Tokens + + None + +Additions to the OpenGL 1.4 Specification + + None + +Additions to Chapter 3 the GLX 1.4 Specification (Functions and Errors) + + Add a new section, 3.6 as follows: + + 3.6 AGP Memory Access + + On "PC" computers, AGP memory can be allocated with glXAllocateMemoryNV + and freed with glXFreeMemoryNV. Sometimes it's useful to know where a + block of AGP memory is located with respect to the start of the AGP + aperture. The function + + GLuint glXGetAGPOffsetMESA( const GLvoid *pointer ) + + Returns the offset of the given memory block from the start of AGP + memory in basic machine units (i.e. bytes). If pointer is invalid + the value ~0 will be returned. + +GLX Protocol + + None. This is a client side-only extension. + +Errors + + glXGetAGPOffsetMESA will return ~0 if the pointer does not point to + an AGP memory region. + +New State + + None + +Revision History + + 20 September 2002 - Initial draft + 2 October 2002 - finished GLX chapter 3 additions + 27 July 2004 - use unsigned int instead of GLuint, void instead of GLvoid diff --git a/docs/specs/MESA_copy_sub_buffer.spec b/docs/specs/MESA_copy_sub_buffer.spec new file mode 100644 index 00000000000..752a014b352 --- /dev/null +++ b/docs/specs/MESA_copy_sub_buffer.spec @@ -0,0 +1,96 @@ +Name + + MESA_copy_sub_buffer + +Name Strings + + GLX_MESA_copy_sub_buffer + +Contact + + Brian Paul (brian.paul 'at' tungstengraphics.com) + +Status + + Shipping since Mesa 2.6 in February, 1998. + +Version + + Last Modified Date: 12 January 2009 + +Number + + 215 + +Dependencies + + OpenGL 1.0 or later is required. + GLX 1.0 or later is required. + +Overview + + The glxCopySubBufferMESA() function copies a rectangular region + of the back color buffer to the front color buffer. This can be + used to quickly repaint 3D windows in response to expose events + when the back color buffer cannot be damaged by other windows. + +IP Status + + Open-source; freely implementable. + +Issues + + None. + +New Procedures and Functions + + void glXCopySubBufferMESA( Display *dpy, GLXDrawable drawable, + int x, int y, int width, int height ); + +New Tokens + + None. + +Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors) + + Add to section 3.3.10 Double Buffering: + + The function + + void glXCopySubBufferMESA( Display *dpy, GLXDrawable drawable, + int x, int y, int width, int height ); + + may be used to copy a rectangular region of the back color buffer to + the front color buffer. This can be used to quickly repaint 3D windows + in response to expose events when the back color buffer cannot be + damaged by other windows. + + <x> and <y> indicates the lower-left corner of the region to copy and + <width> and <height> indicate the size in pixels. Coordinate (0,0) + corresponds to the lower-left pixel of the window, like glReadPixels. + + If dpy and drawable are the display and drawable for the calling + thread's current context, glXCopySubBufferMESA performs an + implicit glFlush before it returns. Subsequent OpenGL commands + may be issued immediately after calling glXCopySubBufferMESA, but + are not executed until the copy is completed. + +GLX Protocol + + None at this time. The extension is implemented in terms of ordinary + Xlib protocol inside of Mesa. + +Errors + + None. + +New State + + None. + +Revision History + + 12 January 2009 Ian Romanick - Added language about implicit flush + and command completion. + 8 June 2000 Brian Paul - initial specification + diff --git a/docs/specs/MESA_drm_image.spec b/docs/specs/MESA_drm_image.spec new file mode 100644 index 00000000000..1150a4c43e4 --- /dev/null +++ b/docs/specs/MESA_drm_image.spec @@ -0,0 +1,153 @@ +Name + + MESA_drm_image + +Name Strings + + EGL_MESA_drm_image + +Contact + + Kristian Høgsberg <[email protected]> + +Status + + Proposal + +Version + + Version 2, August 25, 2010 + +Number + + EGL Extension #not assigned + +Dependencies + + Requires EGL 1.4 or later. This extension is written against the + wording of the EGL 1.4 specification. + + EGL_KHR_base_image is required. + +Overview + + This extension provides entry points for integrating EGLImage with the + Linux DRM mode setting and memory management drivers. The extension + lets applications create EGLImages without a client API resource and + lets the application get the DRM buffer handles. + +IP Status + + Open-source; freely implementable. + +New Procedures and Functions + + EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy, + const EGLint *attrib_list); + + EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy, + EGLImageKHR image, + EGLint *name, + EGLint *handle, + EGLint *stride); + +New Tokens + + Accepted in the <attrib_list> parameter of eglCreateDRMImageMESA: + + EGL_DRM_BUFFER_FORMAT_MESA 0x31D0 + EGL_DRM_BUFFER_USE_MESA 0x31D1 + + Accepted as values for the EGL_IMAGE_FORMAT_MESA attribute: + + EGL_DRM_BUFFER_FORMAT_ARGB32_MESA 0x31D2 + + Bits accepted in EGL_DRM_BUFFER_USE_MESA: + + EGL_DRM_BUFFER_USE_SCANOUT_MESA 0x0001 + EGL_DRM_BUFFER_USE_SHARE_MESA 0x0002 + EGL_DRM_BUFFER_USE_CURSOR_MESA 0x0004 + + Accepted in the <target> parameter of eglCreateImageKHR: + + EGL_DRM_BUFFER_MESA 0x31D3 + + Use when importing drm buffer: + + EGL_DRM_BUFFER_STRIDE_MESA 0x31D4 + EGL_DRM_BUFFER_FORMAT_MESA 0x31D0 + +Additions to the EGL 1.4 Specification: + + To create a DRM EGLImage, call + + EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy, + const EGLint *attrib_list); + + In the attribute list, pass EGL_WIDTH, EGL_HEIGHT and format and + use in the attrib list using EGL_DRM_BUFFER_FORMAT_MESA and + EGL_DRM_BUFFER_USE_MESA. The only format specified by this + extension is EGL_DRM_BUFFER_FORMAT_ARGB32_MESA, where each pixel + is a CPU-endian, 32-bit quantity, with alpha in the upper 8 bits, + then red, then green, then blue. The bit values accepted by + EGL_DRM_BUFFER_USE_MESA are EGL_DRM_BUFFER_USE_SCANOUT_MESA, + EGL_DRM_BUFFER_USE_SHARE_MESA and EGL_DRM_BUFFER_USE_CURSOR_MESA. + EGL_DRM_BUFFER_USE_SCANOUT_MESA requests that the created EGLImage + should be usable as a scanout buffer with the DRM kernel + modesetting API. EGL_DRM_BUFFER_USE_SHARE_MESA requests that the + EGLImage can be shared with other processes by passing the + underlying DRM buffer name. EGL_DRM_BUFFER_USE_CURSOR_MESA + requests that the image must be usable as a cursor with KMS. When + EGL_DRM_BUFFER_USE_CURSOR_MESA is set, width and height must both + be 64. + + To create a process local handle or a global DRM name for a + buffer, call + + EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy, + EGLImageKHR image, + EGLint *name, + EGLint *handle, + EGLint *stride); + + If <name> is non-NULL, a global name is assigned to the image and + written to <name>, the handle (local to the DRM file descriptor, + for use with DRM kernel modesetting API) is written to <handle> if + non-NULL and the stride (in bytes) is written to <stride>, if + non-NULL. + + Import a shared buffer by calling eglCreateImageKHR with + EGL_DRM_BUFFER_MESA as the target, using EGL_WIDTH, EGL_HEIGHT, + EGL_DRM_BUFFER_FORMAT_MESA, EGL_DRM_BUFFER_STRIDE_MESA + in the attrib list. + +Issues + + 1. Why don't we use eglCreateImageKHR with a target that + indicates that we want to create an EGLImage from scratch? + + RESOLVED: The eglCreateImageKHR entry point is reserved for + creating an EGLImage from an already existing client API + resource. This is fine when we're creating the EGLImage from + an existing DRM buffer name, it doesn't seem right to overload + the function to also allocate the underlying resource. + + 2. Why don't we use an eglQueryImageMESA type functions for + querying the DRM EGLImage attributes (name, handle, and stride)? + + RESOLVED: The eglQueryImage function has been proposed often, + but it goes against the EGLImage design. EGLImages are opaque + handles to a 2D array of pixels, which can be passed between + client APIs. By referencing an EGLImage in a client API, the + EGLImage target (a texture, a renderbuffer or such) can be + used to query the attributes of the EGLImage. We don't have a + full client API for creating and querying DRM buffers, though, + so we use a new EGL extension entry point instead. + +Revision History + + Version 1, June 3, 2010 + Initial draft (Kristian Høgsberg) + Version 2, August 25, 2010 + Flesh out the extension a bit, add final EGL tokens, capture + some of the original discussion in the issues section. diff --git a/docs/specs/MESA_multithread_makecurrent.spec b/docs/specs/MESA_multithread_makecurrent.spec new file mode 100644 index 00000000000..5065c2fc0a3 --- /dev/null +++ b/docs/specs/MESA_multithread_makecurrent.spec @@ -0,0 +1,158 @@ +Name + + MESA_multithread_makecurrent + +Name Strings + + GLX_MESA_multithread_makecurrent + +Contact + + Eric Anholt ([email protected]) + +Status + + Not shipping. + +Version + + Last Modified Date: 21 February 2011 + +Number + + TBD + +Dependencies + + OpenGL 1.0 or later is required. + GLX 1.3 or later is required. + +Overview + + The GLX context setup encourages multithreaded applications to + create a context per thread which each operate on their own + objects in parallel, and leaves synchronization for write access + to shared objects up to the application. + + For some applications, maintaining per-thread contexts and + ensuring that the glFlush happens in one thread before another + thread starts working on that object is difficult. For them, + using the same context across multiple threads and protecting its + usage with a mutex is both higher performance and easier to + implement. This extension gives those applications that option by + relaxing the context binding requirements. + + This new behavior matches the requirements of AGL, while providing + a feature not specified in WGL. + +IP Status + + Open-source; freely implementable. + +Issues + + None. + +New Procedures and Functions + + None. + +New Tokens + + None. + +Changes to Chapter 2 of the GLX 1.3 Specification (Functions and Errors) + + Replace the following sentence from section 2.2 Rendering Contexts: + In addition, a rendering context can be current for only one + thread at a time. + with: + In addition, an indirect rendering context can be current for + only one thread at a time. A direct rendering context may be + current to multiple threads, with synchronization of access to + the context thruogh the GL managed by the application through + mutexes. + +Changes to Chapter 3 of the GLX 1.3 Specification (Functions and Errors) + + Replace the following sentence from section 3.3.7 Rendering Contexts: + If ctx is current to some other thread, then + glXMakeContextCurrent will generate a BadAccess error. + with: + If ctx is an indirect context current to some other thread, + then glXMakeContextCurrent will generate a BadAccess error. + + Replace the following sentence from section 3.5 Rendering Contexts: + If ctx is current to some other thread, then + glXMakeCurrent will generate a BadAccess error. + with: + If ctx is an indirect context current to some other thread, + then glXMakeCurrent will generate a BadAccess error. + +GLX Protocol + + None. The GLX extension only extends to direct rendering contexts. + +Errors + + None. + +New State + + None. + +Issues + + (1) What happens if the app binds a context/drawable in multiple + threads, then binds a different context/thread in one of them? + + As with binding a new context from the current thread, the old + context's refcount is reduced and the new context's refcount is + increased. + + (2) What happens if the app binds a context/drawable in multiple + threads, then binds None/None in one of them? + + The GLX context is unreferenced from that thread, and the other + threads retain their GLX context binding. + + (3) What happens if the app binds a context/drawable in 7 threads, + then destroys the context in one of them? + + As with GLX context destruction previously, the XID is destroyed + but the context remains usable by threads that have the context + current. + + (4) What happens if the app binds a new drawable/readable with + glXMakeCurrent() when it is already bound to another thread? + + The context becomes bound to the new drawable/readable, and + further rendering in either thread will use the new + drawable/readable. + + (5) What requirements should be placed on the user managing contexts + from multiple threads? + + The intention is to allow multithreaded access to the GL at the + minimal performance cost, so requiring that the GL do general + synchronization (beyond that already required by context sharing) + is not an option, and synchronizing of GL's access to the GL + context between multiple threads is left to the application to do + across GL calls. However, it would be unfortunate for a library + doing multithread_makecurrent to require that other libraries + share in synchronization for binding of their own contexts, so the + refcounting of the contexts is required to be threadsafe. + + (6) Does this apply to indirect contexts? + + This was ignored in the initial revision of the spec. Behavior + for indirect contexts is left as-is. + +Revision History + + 20 November 2009 Eric Anholt - initial specification + 22 November 2009 Eric Anholt - added issues from Ian Romanick. + 3 February 2011 Eric Anholt - updated with resolution to issues 1-3 + 3 February 2011 Eric Anholt - added issue 4, 5 + 21 February 2011 Eric Anholt - Include glXMakeCurrent() sentence + along with glXMakeContextCurrent() for removal. diff --git a/docs/specs/MESA_pack_invert.spec b/docs/specs/MESA_pack_invert.spec new file mode 100644 index 00000000000..33fb3c7bf80 --- /dev/null +++ b/docs/specs/MESA_pack_invert.spec @@ -0,0 +1,138 @@ +Name + + MESA_pack_invert + +Name Strings + + GL_MESA_pack_invert + +Contact + + Brian Paul, Tungsten Graphics, Inc. (brian.paul 'at' tungstengraphics.com) + Keith Whitwell, Tungsten Graphics, Inc. (keith 'at' tungstengraphics.com) + +Status + + Shipping (Mesa 4.0.4 and later) + +Version + + 1.0 + +Number + + TBD + +Dependencies + + OpenGL 1.0 or later is required + This extensions is written against the OpenGL 1.4 Specification. + +Overview + + This extension adds a new pixel storage parameter to indicate that + images are to be packed in top-to-bottom order instead of OpenGL's + conventional bottom-to-top order. Only pixel packing can be + inverted (i.e. for glReadPixels, glGetTexImage, glGetConvolutionFilter, + etc). + + Almost all known image file formats store images in top-to-bottom + order. As it is, OpenGL reads images from the frame buffer in + bottom-to-top order. Thus, images usually have to be inverted before + writing them to a file with image I/O libraries. This extension + allows images to be read such that inverting isn't needed. + +IP Status + + None + +Issues + + 1. Should we also define UNPACK_INVERT_MESA for glDrawPixels, etc? + + Resolved: No, we're only concerned with pixel packing. There are other + solutions for inverting images when using glDrawPixels (negative Y pixel + zoom) or glTexImage (invert the vertex T coordinates). It would be easy + enough to define a complementary extension for pixel packing in the + future if needed. + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <pname> parameter of PixelStorei and PixelStoref + and the <pname> parameter of GetIntegerv, GetFloatv, GetDoublev + and GetBooleanv: + + PACK_INVERT_MESA 0x8758 + +Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation) + + None + +Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization) + + None + +Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment +Operations and the Frame Buffer) + + Add the following entry to table 4.4 (PixelStore parameters) on page 182: + + Parameter Name Type Initial Value Valid Range + --------------------------------------------------------- + PACK_INVERT_MESA boolean FALSE TRUE/FALSE + + In the section labeled "Placement in Client Memory" on page 184 + insert the following text into the paragraph before the sentence + that starts with "If the format is RED, GREEN, BLUE...": + + "The parameter PACK_INVERT_MESA controls whether the image is packed + in bottom-to-top order (the default) or top-to-bottom order. Equation + 3.8 is modified as follows: + + ... the first element of the Nth row is indicated by + + p + Nk, if PACK_INVERT_MESA is false + p + k * (H - 1) - Nk, if PACK_INVERT_MESA is true, where H is the + image height + " + +Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions) + + None + +Additions to Chapter 6 of the OpenGL 1.4 Specification (State and +State Requests) + + None + +Additions to Appendix A of the OpenGL 1.4 Specification (Invariance) + + None + +Additions to the AGL/GLX/WGL Specifications + + None + +GLX Protocol + + None + +Errors + + None + +New State + + Add the following entry to table 6.20 (Pixels) on page 235: + + Get Value Type Get Cmd Initial Value Description Sec Attribute + -------------------------------------------------------------------------------------------------- + PACK_INVERT_MESA boolean GetBoolean FALSE Value of PACK_INVERT_MESA 4.3.2 pixel-store + +Revision History + + 21 September 2002 - Initial draft diff --git a/docs/specs/MESA_pixmap_colormap.spec b/docs/specs/MESA_pixmap_colormap.spec new file mode 100644 index 00000000000..fb0b441cc58 --- /dev/null +++ b/docs/specs/MESA_pixmap_colormap.spec @@ -0,0 +1,90 @@ +Name + + MESA_pixmap_colormap + +Name Strings + + GLX_MESA_pixmap_colormap + +Contact + + Brian Paul (brian.paul 'at' tungstengraphics.com) + +Status + + Shipping since Mesa 1.2.8 in May, 1996. + +Version + + Last Modified Date: 8 June 2000 + +Number + + 216 + +Dependencies + + OpenGL 1.0 or later is required. + GLX 1.0 or later is required. + +Overview + + Since Mesa allows RGB rendering into drawables with PseudoColor, + StaticColor, GrayScale and StaticGray visuals, Mesa needs a colormap + in order to compute pixel values during rendering. + + The colormap associated with a window can be queried with normal + Xlib functions but there is no colormap associated with pixmaps. + + The glXCreateGLXPixmapMESA function is an alternative to glXCreateGLXPixmap + which allows specification of a colormap. + +IP Status + + Open-source; freely implementable. + +Issues + + None. + +New Procedures and Functions + + GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual, + Pixmap pixmap, Colormap cmap ); + +New Tokens + + None. + +Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors) + + Add to section 3.4.2 Off Screen Rendering + + The Mesa implementation of GLX allows RGB rendering into X windows and + pixmaps of any visual class, not just TrueColor or DirectColor. In order + to compute pixel values from RGB values Mesa requires a colormap. + + The function + + GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual, + Pixmap pixmap, Colormap cmap ); + + allows one to create a GLXPixmap with a specific colormap. The image + rendered into the pixmap may then be copied to a window (which uses the + same colormap and visual) with the expected results. + +GLX Protocol + + None since this is a client-side extension. + +Errors + + None. + +New State + + None. + +Revision History + + 8 June 2000 - initial specification diff --git a/docs/specs/MESA_release_buffers.spec b/docs/specs/MESA_release_buffers.spec new file mode 100644 index 00000000000..52d1e5a9c7c --- /dev/null +++ b/docs/specs/MESA_release_buffers.spec @@ -0,0 +1,85 @@ +Name + + MESA_release_buffers + +Name Strings + + GLX_MESA_release_buffers + +Contact + + Brian Paul (brian.paul 'at' tungstengraphics.com) + +Status + + Shipping since Mesa 2.0 in October, 1996. + +Version + + Last Modified Date: 8 June 2000 + +Number + + 217 + +Dependencies + + OpenGL 1.0 or later is required. + GLX 1.0 or later is required. + +Overview + + Mesa's implementation of GLX is entirely implemented on the client side. + Therefore, Mesa cannot immediately detect when an X window or pixmap is + destroyed in order to free any ancillary data associated with the window + or pixmap. + + The glxMesaReleaseBuffers() function can be used to explicitly indicate + when the back color buffer, depth buffer, stencil buffer, and/or accumu- + lation buffer associated with a drawable can be freed. + +IP Status + + Open-source; freely implementable. + +Issues + + None. + +New Procedures and Functions + + Bool glXReleaseBuffersMESA( Display *dpy, GLXDrawable d ); + +New Tokens + + None. + +Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors) + + The function + + Bool glXReleaseBuffersMESA( Display *dpy, GLXDrawable d ); + + causes all software ancillary buffers (back buffer, depth, stencil, + accum, etc) associated with the named drawable to be immediately + deallocated. True is returned if <d> is a valid Mesa GLX drawable, + else False is returned. After calling glXReleaseBuffersMESA, the + drawable should no longer be used for GL rendering. Results of + attempting to do so are undefined. + + +GLX Protocol + + None, since this is a client-side operation. + +Errors + + None. + +New State + + None. + +Revision History + + 8 June 2000 - initial specification diff --git a/docs/specs/MESA_resize_buffers.spec b/docs/specs/MESA_resize_buffers.spec new file mode 100644 index 00000000000..dabc7c421da --- /dev/null +++ b/docs/specs/MESA_resize_buffers.spec @@ -0,0 +1,81 @@ +Name + + MESA_resize_buffers + +Name Strings + + GL_MESA_resize_buffers + +Contact + + Brian Paul (brian.paul 'at' tungstengraphics.com) + +Status + + Shipping (since Mesa version 2.2) + +Version + + +Number + + 196 + +Dependencies + + Mesa 2.2 or later is required. + +Overview + + Mesa is often used as a client library with no integration with + the computer's window system (an X server, for example). And since + Mesa does not have an event loop nor window system callbacks, it + cannot properly respond to window system events. In particular, + Mesa cannot automatically detect when a window has been resized. + + Mesa's glViewport command queries the current window size and updates + its internal data structors accordingly. This normally works fine + since most applications call glViewport in response to window size + changes. + + In some situations, however, the application may not call glViewport + when a window size changes but would still like Mesa to adjust to + the new window size. This extension exports a new function to solve + this problem. + +New Procedures and Functions + + void glResizeBuffersMESA( void ) + +New Tokens + + none + +Additions to the OpenGL Specification (no particular section) + + The glResizeBuffersMESA command may be called when the client + determines that a window has been resized. Calling + glResizeBuffersMESA causes Mesa to query the current window size + and adjust its internal data structures. This may include + reallocating depth, stencil, alpha and accumulation buffers. + +Additions to the AGL/GLX/WGL Specifications + + None + +Errors + + INVALID_OPERATION is generated if glResizeBuffersMESA is called between + Begin and End. + +New State + + None. + +New Implementation Dependent State + + None. + +Revision History + + * Revision 1.0 - Initial specification diff --git a/docs/specs/MESA_set_3dfx_mode.spec b/docs/specs/MESA_set_3dfx_mode.spec new file mode 100644 index 00000000000..06d97ca021f --- /dev/null +++ b/docs/specs/MESA_set_3dfx_mode.spec @@ -0,0 +1,85 @@ +Name + + MESA_set_3dfx_mode + +Name Strings + + GLX_MESA_set_3dfx_mode + +Contact + + Brian Paul (brian.paul 'at' tungstengraphics.com) + +Status + + Shipping since Mesa 2.6 in February, 1998. + +Version + + Last Modified Date: 8 June 2000 + +Number + + 218 + +Dependencies + + OpenGL 1.0 or later is required. + GLX 1.0 or later is required. + +Overview + + The Mesa Glide driver allows full-screen rendering or rendering into + an X window. The glXSet3DfxModeMESA() function allows an application + to switch between full-screen and windowed rendering. + +IP Status + + Open-source; freely implementable. + +Issues + + None. + +New Procedures and Functions + + GLboolean glXSet3DfxModeMESA( GLint mode ); + +New Tokens + + GLX_3DFX_WINDOW_MODE_MESA 0x1 + GLX_3DFX_FULLSCREEN_MODE_MESA 0x2 + +Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors) + + The Mesa Glide device driver allows either rendering in full-screen + mode or rendering into an X window. An application can switch between + full-screen and window rendering with the command: + + GLboolean glXSet3DfxModeMESA( GLint mode ); + + <mode> may either be GLX_3DFX_WINDOW_MODE_MESA to indicate window + rendering or GLX_3DFX_FULLSCREEN_MODE_MESA to indicate full-screen mode. + + GL_TRUE is returned if <mode> is valid and the operation completed + normally. GL_FALSE is returned if <mode> is invalid or if the Glide + driver is not being used. + + Note that only one drawable and context can be created at any given + time with the Mesa Glide driver. + +GLX Protocol + + None since this is a client-side extension. + +Errors + + None. + +New State + + None. + +Revision History + + 8 June 2000 - initial specification diff --git a/docs/specs/MESA_shader_debug.spec b/docs/specs/MESA_shader_debug.spec new file mode 100644 index 00000000000..fab92abc762 --- /dev/null +++ b/docs/specs/MESA_shader_debug.spec @@ -0,0 +1,264 @@ +Name + + MESA_shader_debug + +Name Strings + + GL_MESA_shader_debug + +Contact + + Brian Paul (brian.paul 'at' tungstengraphics.com) + Michal Krol (mjkrol 'at' gmail.com) + +Status + + Obsolete. + +Version + + Last Modified Date: July 30, 2006 + Author Revision: 0.2 + +Number + + TBD + +Dependencies + + OpenGL 1.0 is required. + + The ARB_shader_objects extension is required. + + The ARB_shading_language_100 extension is required. + + The extension is written against the OpenGL 1.5 specification. + + The extension is written against the OpenGL Shading Language 1.10 + Specification. + +Overview + + This extension introduces a debug object that can be attached to + a program object to enable debugging. Vertex and/or fragment shader, + during execution, issue diagnostic function calls that are logged + to the debug object's log. A separate debug log for each shader type + is maintained. A debug object can be attached, detached and queried + at any time outside the Begin/End pair. Multiple debug objects can + be attached to a single program object. + +IP Status + + None + +Issues + + None + +New Procedures and Functions + + handleARB CreateDebugObjectMESA(void) + void ClearDebugLogMESA(handleARB obj, enum logType, enum shaderType) + void GetDebugLogMESA(handleARB obj, enum logType, enum shaderType, + sizei maxLength, sizei *length, + charARB *debugLog) + sizei GetDebugLogLengthMESA(handleARB obj, enum logType, + enum shaderType) + +New Types + + None + +New Tokens + + Returned by the <params> parameter of GetObjectParameter{fi}vARB: + + DEBUG_OBJECT_MESA 0x8759 + + Accepted by the <logType> argument of ClearDebugLogMESA, + GetDebugLogLengthMESA and GetDebugLogMESA: + + DEBUG_PRINT_MESA 0x875A + DEBUG_ASSERT_MESA 0x875B + +Additions to Chapter 2 of the OpenGL 1.5 Specification +(OpenGL Operation) + + None + +Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization) + + None + +Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment +Operations and the Frame Buffer) + + None + +Additions to Chapter 5 of the OpenGL 1.5 Specification +(Special Functions) + + None + +Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State +Requests) + + None + +Additions to Appendix A of the OpenGL 1.5 Specification (Invariance) + + None + +Additions to Chapter 1 of the OpenGL Shading Language 1.10 Specification +(Introduction) + + None + +Additions to Chapter 2 of the OpenGL Shading Language 1.10 Specification +(Overview of OpenGL Shading) + + None + +Additions to Chapter 3 of the OpenGL Shading Language 1.10 Specification +(Basics) + + None + +Additions to Chapter 4 of the OpenGL Shading Language 1.10 Specification +(Variables and Types) + + None + +Additions to Chapter 5 of the OpenGL Shading Language 1.10 Specification +(Operators and Expressions) + + None + +Additions to Chapter 6 of the OpenGL Shading Language 1.10 Specification +(Statements and Structure) + + None + +Additions to Chapter 7 of the OpenGL Shading Language 1.10 Specification +(Built-in Variables) + + None + +Additions to Chapter 8 of the OpenGL Shading Language 1.10 Specification +(Built-in Functions) + + Add a new section 8.10 "Debug Functions": + + Debug functions are available to both fragment and vertex shaders. + They are used to track the execution of a shader by logging + passed-in arguments to the debug object's log. Those values can be + retrieved by the application for inspection after shader execution + is complete. + + The text, if any, produced by any of these functions is appended + to each debug object that is attached to the program object. + There are different debug log types + + Add a new section 8.10.1 "Print Function": + + The following printMESA prototypes are available. + + void printMESA(const float value) + void printMESA(const int value) + void printMESA(const bool value) + void printMESA(const vec2 value) + void printMESA(const vec3 value) + void printMESA(const vec4 value) + void printMESA(const ivec2 value) + void printMESA(const ivec3 value) + void printMESA(const ivec4 value) + void printMESA(const bvec2 value) + void printMESA(const bvec3 value) + void printMESA(const bvec4 value) + void printMESA(const mat2 value) + void printMESA(const mat3 value) + void printMESA(const mat4 value) + void printMESA(const sampler1D value) + void printMESA(const sampler2D value) + void printMESA(const sampler3D value) + void printMESA(const samplerCube value) + void printMESA(const sampler1DShadow value) + void printMESA(const sampler2DShadow value) + + The printMESA function writes the argument <value> to the "debug + print log" (XXX DEBUG_PRINT_MESA?). Each component is written in + text format (XXX format!) and is delimited by a white space (XXX 1 + or more?). + + Add a new section 8.10.2 "Assert Function": + + The following assertMESA prototypes are available. + + void assertMESA(const bool condition) + void assertMESA(const bool condition, const int cookie) + void assertMESA(const bool condition, const int cookie, + const int file, const int line) + + The assertMESA function checks if the argument <condition> is + true or false. If it is true, nothing happens. If it is false, + a diagnostic message is written to the "debug assert log". + The message contains the argument <file>, <line>, <cookie> and + implementation dependent double-quoted string, each of this + delimited by a white space. If the argument <cookie> is not present, + it is meant as if it was of value 0. If the arguments <file> and + <line> are not present, they are meant as if they were of values + __FILE__ and __LINE__, respectively. The following three calls + produce the same output, assuming they were issued from the same + file and line. + + assertMESA (false); + assertMESA (false, 0); + assertMESA (false, 0, __FILE__, __LINE__); + + The diagnostic message examples follow. + + 1 89 0 "" + 1 45 333 "all (lessThanEqual (fragColor, vec4 (1.0)))" + 1 66 1 "assertion failed in file 1, line 66, cookie 1" + +Additions to Chapter 9 of the OpenGL Shading Language 1.10 Specification +(Shading Language Grammar) + + None + +Additions to Chapter 10 of the OpenGL Shading Language 1.10 +Specification (Issues) + + None + +Additions to the AGL/EGL/GLX/WGL Specifications + + None + +GLX Protocol + + None + +Errors + + TBD + +New State + + TBD + +New Implementation Dependent State + + TBD + +Sample Code + + TBD + +Revision History + + 29 May 2006 + Initial draft. (Michal Krol) + 30 July 2006 + Add Overview, New Procedures and Functions, New Tokens sections. + Add sections 8.10.1, 8.10.2 to GLSL spec. diff --git a/docs/specs/MESA_swap_control.spec b/docs/specs/MESA_swap_control.spec new file mode 100644 index 00000000000..a002563c9dc --- /dev/null +++ b/docs/specs/MESA_swap_control.spec @@ -0,0 +1,129 @@ +Name + + MESA_swap_control + +Name Strings + + GLX_MESA_swap_control + +Contact + + Ian Romanick, IBM, idr at us.ibm.com + +Status + + Deployed in DRI drivers post-XFree86 4.3. + +Version + + Date: 5/1/2003 Revision: 1.1 + +Number + + ??? + +Dependencies + + None + + Based on GLX_SGI_swap_control version 1.9 and WGL_EXT_swap_control + version 1.5. + +Overview + + This extension allows an application to specify a minimum periodicity + of color buffer swaps, measured in video frame periods. + +Issues + + * Should implementations that export GLX_MESA_swap_control also export + GL_EXT_swap_control for compatibility with WGL_EXT_swap_control? + + UNRESOLVED. + +New Procedures and Functions + + int glXSwapIntervalMESA(unsigned int interval) + int glXGetSwapIntervalMESA(void) + +New Tokens + + None + +Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation) + + None + +Additions to Chapter 3 of the 1.4 GL Specification (Rasterization) + + None + +Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations +and the Framebuffer) + + None + +Additions to Chapter 5 of the 1.4 GL Specification (Special Functions) + + None + +Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests) + + None + +Additions to the GLX 1.3 Specification + + [Add the following to Section 3.3.10 of the GLX Specification (Double + Buffering)] + + glXSwapIntervalMESA specifies the minimum number of video frame periods + per buffer swap. (e.g. a value of two means that the color buffers + will be swapped at most every other video frame.) A return value + of zero indicates success; otherwise an error occurred. The interval + takes effect when glXSwapBuffers is first called subsequent to the + glXSwapIntervalMESA call. + + A video frame period is the time required by the monitor to display a + full frame of video data. In the case of an interlaced monitor, + this is typically the time required to display both the even and odd + fields of a frame of video data. + + If <interval> is set to a value of 0, buffer swaps are not synchro- + nized to a video frame. The <interval> value is silently clamped to + the maximum implementation-dependent value supported before being + stored. + + The swap interval is not part of the render context state. It cannot + be pushed or popped. The current swap interval for the window + associated with the current context can be obtained by calling + glXGetSwapIntervalMESA. The default swap interval is 0. + + On XFree86, setting the environment variable LIBGL_THROTTLE_REFRESH sets + the swap interval to 1. + +Errors + + glXSwapIntervalMESA returns GLX_BAD_CONTEXT if there is no current + GLXContext or if the current context is not a direct rendering context. + +GLX Protocol + + None. This extension only extends to direct rendering contexts. + +New State + + Get Value Get Command Type Initial Value + --------- ----------- ---- ------------- + [swap interval] GetSwapInterval Z+ 0 + +New Implementation Dependent State + + None + + +Revision History + + 1.1, 5/1/03 Added the issues section and contact information. + Changed the default swap interval to 0. + 1.0, 3/17/03 Initial version based on GLX_SGI_swap_control and + WGL_EXT_swap_control. diff --git a/docs/specs/MESA_swap_frame_usage.spec b/docs/specs/MESA_swap_frame_usage.spec new file mode 100644 index 00000000000..5023eadd8a1 --- /dev/null +++ b/docs/specs/MESA_swap_frame_usage.spec @@ -0,0 +1,201 @@ +Name + + MESA_swap_frame_usage + +Name Strings + + GLX_MESA_swap_frame_usage + +Contact + + Ian Romanick, IBM, idr at us.ibm.com + +Status + + Deployed in DRI drivers post-XFree86 4.3. + +Version + + Date: 5/1/2003 Revision: 1.1 + +Number + + ??? + +Dependencies + + GLX_SGI_swap_control affects the definition of this extension. + GLX_MESA_swap_control affects the definition of this extension. + GLX_OML_sync_control affects the definition of this extension. + + Based on WGL_I3D_swap_frame_usage version 1.3. + +Overview + + This extension allows an application to determine what portion of the + swap period has elapsed since the last swap operation completed. The + "usage" value is a floating point value on the range [0,max] which is + calculated as follows: + + td + percent = ---- + tf + + where td is the time measured from the last completed buffer swap (or + call to enable the statistic) to when the next buffer swap completes, tf + is the entire time for a frame which may be multiple screen refreshes + depending on the swap interval as set by the GLX_SGI_swap_control or + GLX_OML_sync_control extensions. + + The value, percent, indicates the amount of time spent between the + completion of the two swaps. If the value is in the range [0,1], the + buffer swap occurred within the time period required to maintain a + constant frame rate. If the value is in the range (1,max], a constant + frame rate was not achieved. The value indicates the number of frames + required to draw. + + This definition of "percent" differs slightly from + WGL_I3D_swap_frame_usage. In WGL_I3D_swap_frame_usage, the measurement + is taken from the completion of one swap to the issuance of the next. + This representation may not be as useful as measuring between + completions, as a significant amount of time may pass between the + issuance of a swap and the swap actually occurring. + + There is also a mechanism to determine whether a frame swap was + missed. + +New Procedures and Functions + + int glXGetFrameUsageMESA(Display *dpy, + GLXDrawable drawable, + float *usage) + + int glXBeginFrameTrackingMESA(Display *dpy, + GLXDrawable drawable) + + int glXEndFrameTrackingMESA(Display *dpy, + GLXDrawable drawable) + + int glXQueryFrameTrackingMESA(Display *dpy, + GLXDrawable drawable, + int64_t *swapCount, + int64_t *missedFrames, + float *lastMissedUsage) + +New Tokens + + None + +Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation) + + None + +Additions to Chapter 3 of the 1.4 GL Specification (Rasterization) + + None + +Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations +and the Framebuffer) + + None + +Additions to Chapter 5 of the 1.4 GL Specification (Special Functions) + + None + +Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests) + + None + +Additions to the GLX 1.3 Specification + + The frame usage is measured as the percentage of the swap period elapsed + between two buffer-swap operations being committed. In unextended GLX the + swap period is the vertical refresh time. If SGI_swap_control or + MESA_swap_control are supported, the swap period is the vertical refresh + time multiplied by the swap interval (or one if the swap interval is set + to zero). + + If OML_sync_control is supported, the swap period is the vertical + refresh time multiplied by the divisor parameter to + glXSwapBuffersMscOML. The frame usage in this case is less than 1.0 if + the swap is committed before target_msc, and is greater than or equal to + 1.0 otherwise. The actual usage value is based on the divisor and is + never less than 0.0. + + int glXBeginFrameTrackingMESA(Display *dpy, + GLXDrawable drawable, + float *usage) + + glXGetFrameUsageMESA returns a floating-point value in <usage> + that represents the current swap usage, as defined above. + + Missed frame swaps can be tracked by calling the following function: + + int glXBeginFrameTrackingMESA(Display *dpy, + GLXDrawable drawable) + + glXBeginFrameTrackingMESA resets a "missed frame" count and + synchronizes with the next frame vertical sync before it returns. + If a swap is missed based in the rate control specified by the + <interval> set by glXSwapIntervalSGI or the default swap of once + per frame, the missed frame count is incremented. + + The current missed frame count and total number of swaps since + the last call to glXBeginFrameTrackingMESA can be obtained by + calling the following function: + + int glXQueryFrameTrackingMESA(Display *dpy, + GLXDrawable drawable, + int64_t *swapCount, + int64_t *missedFrames, + float *lastMissedUsage) + + The location pointed to by <swapCount> will be updated with the + number of swaps that have been committed. This value may not match the + number of swaps that have been requested since swaps may be + queued by the implementation. This function can be called at any + time and does not synchronize to vertical blank. + + The location pointed to by <missedFrames> will contain the number + swaps that missed the specified frame. The frame usage for the + last missed frame is returned in the location pointed to by + <lastMissedUsage>. + + Frame tracking is disabled by calling the function + + int glXEndFrameTrackingMESA(Display *dpy, + GLXDrawable drawable) + + This function will not return until all swaps have occurred. The + application can call glXQueryFrameTrackingMESA for a final swap and + missed frame count. + + If these functions are successful, zero is returned. If the context + associated with dpy and drawable is not a direct context, + GLX_BAD_CONTEXT is returned. + +Errors + + If the function succeeds, zero is returned. If the function + fails, one of the following error codes is returned: + + GLX_BAD_CONTEXT The current rendering context is not a direct + context. + +GLX Protocol + + None. This extension only extends to direct rendering contexts. + +New State + + None + +New Implementation Dependent State + + None + +Revision History + + 1.1, 5/1/03 Added contact information. + 1.0, 3/17/03 Initial version based on WGL_I3D_swap_frame_usage. diff --git a/docs/specs/MESA_texture_array.spec b/docs/specs/MESA_texture_array.spec new file mode 100644 index 00000000000..b146821f72e --- /dev/null +++ b/docs/specs/MESA_texture_array.spec @@ -0,0 +1,804 @@ +Name + + MESA_texture_array + +Name Strings + + GL_MESA_texture_array + +Contact + + Ian Romanick, IBM (idr 'at' us.ibm.com) + +IP Status + + No known IP issues. + +Status + + Shipping in Mesa 7.1 + +Version + + +Number + + TBD + +Dependencies + + OpenGL 1.2 or GL_EXT_texture3D is required. + + Support for ARB_fragment_program is assumed, but not required. + + Support for ARB_fragment_program_shadow is assumed, but not required. + + Support for EXT_framebuffer_object is assumed, but not required. + + Written based on the wording of the OpenGL 2.0 specification and + ARB_fragment_program_shadow but not dependent on them. + +Overview + + There are a number of circumstances where an application may wish to + blend two textures out of a larger set of textures. Moreover, in some + cases the selected textures may vary on a per-fragment basis within + a polygon. Several examples include: + + 1. High dynamic range textures. The application stores several + different "exposures" of an image as different textures. On a + per-fragment basis, the application selects which exposures are + used. + + 2. A terrain engine where the altitude of a point determines the + texture applied to it. If the transition is from beach sand to + grass to rocks to snow, the application will store each texture + in a different texture map, and dynamically select which two + textures to blend at run-time. + + 3. Storing short video clips in textures. Each depth slice is a + single frame of video. + + Several solutions to this problem have been proposed, but they either + involve using a separate texture unit for each texture map or using 3D + textures without mipmaps. Both of these options have major drawbacks. + + This extension provides a third alternative that eliminates the major + drawbacks of both previous methods. A new texture target, + TEXTURE_2D_ARRAY, is added that functions identically to TEXTURE_3D in + all aspects except the sizes of the non-base level images. In + traditional 3D texturing, the size of the N+1 LOD is half the size + of the N LOD in all three dimensions. For the TEXTURE_2D_ARRAY target, + the height and width of the N+1 LOD is halved, but the depth is the + same for all levels of detail. The texture then becomes an array of + 2D textures. The per-fragment texel is selected by the R texture + coordinate. + + References: + + http://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=011557 + http://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=000516 + http://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=011903 + http://www.delphi3d.net/articles/viewarticle.php?article=terraintex.htm + +New Procedures and Functions + + All functions come directly from EXT_texture_array. + + void FramebufferTextureLayerEXT(enum target, enum attachment, + uint texture, int level, int layer); + +New Tokens + + All token names and values come directly from EXT_texture_array. + + Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, by + the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and + GetDoublev, and by the <target> parameter of TexImage3D, GetTexImage, + GetTexLevelParameteriv, GetTexLevelParameterfv, GetTexParameteriv, and + GetTexParameterfv: + + TEXTURE_1D_ARRAY_EXT 0x8C18 + TEXTURE_2D_ARRAY_EXT 0x8C1A + + Accepted by the <target> parameter of TexImage2D, TexSubImage2D, + CopyTexImage2D, CopyTexSubImage2D, CompressedTexImage2D, + CompressedTexSubImage2D, GetTexLevelParameteriv, and + GetTexLevelParameterfv: + + TEXTURE_1D_ARRAY_EXT + PROXY_TEXTURE_1D_ARRAY_EXT 0x8C19 + + Accepted by the <target> parameter of TexImage3D, TexSubImage3D, + CopyTexSubImage3D, CompressedTexImage3D, CompressedTexSubImage3D, + GetTexLevelParameteriv, and GetTexLevelParameterfv: + + TEXTURE_2D_ARRAY_EXT + PROXY_TEXTURE_2D_ARRAY_EXT 0x8C1B + + Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, + GetFloatv, and GetDoublev + + TEXTURE_BINDING_1D_ARRAY_EXT 0x8C1C + TEXTURE_BINDING_2D_ARRAY_EXT 0x8C1D + MAX_ARRAY_TEXTURE_LAYERS_EXT 0x88FF + + Accepted by the <param> parameter of TexParameterf, TexParameteri, + TexParameterfv, and TexParameteriv when the <pname> parameter is + TEXTURE_COMPARE_MODE_ARB: + + COMPARE_REF_DEPTH_TO_TEXTURE_EXT 0x884E + + (Note: COMPARE_REF_DEPTH_TO_TEXTURE_EXT is simply an alias for the + existing COMPARE_R_TO_TEXTURE token in OpenGL 2.0; the alternate name + reflects the fact that the R coordinate is not always used.) + + Accepted by the <internalformat> parameter of TexImage3D and + CompressedTexImage3D, and by the <format> parameter of + CompressedTexSubImage3D: + + COMPRESSED_RGB_S3TC_DXT1_EXT + COMPRESSED_RGBA_S3TC_DXT1_EXT + COMPRESSED_RGBA_S3TC_DXT3_EXT + COMPRESSED_RGBA_S3TC_DXT5_EXT + + Accepted by the <pname> parameter of + GetFramebufferAttachmentParameterivEXT: + + FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT 0x8CD4 + + (Note: FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER is simply an alias for the + FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT token provided in + EXT_framebuffer_object. This extension generalizes the notion of + "<zoffset>" to include layers of an array texture.) + +Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) + + None + +Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) + + -- Section 3.8.1 "Texture Image Specification" + + Change the first paragraph (page 150) to say (spec changes identical to + EXT_texture_array): + + "The command + + void TexImage3D(enum target, int level, int internalformat, + sizei width, sizei height, sizei depth, int border, + enum format, enum type, void *data); + + is used to specify a three-dimensional texture image. target must be one + one of TEXTURE_3D for a three-dimensional texture or + TEXTURE_2D_ARRAY_EXT for an two-dimensional array texture. + Additionally, target may be either PROXY_TEXTURE_3D for a + three-dimensional proxy texture, or PROXY_TEXTURE_2D_ARRAY_EXT for a + two-dimensional proxy array texture." + + Change the fourth paragraph on page 151 to say (spec changes identical + to EXT_texture_array): + + "Textures with a base internal format of DEPTH_COMPONENT are supported + by texture image specification commands only if target is TEXTURE_1D, + TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, TEXTURE_2D_ARRAY_EXT, + PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, PROXY_TEXTURE_1D_ARRAY_EXT, or + PROXY_TEXTURE_2D_ARRAY_EXT. Using this format in conjunction with any + other target will result in an INVALID_OPERATION error." + + + Change the fourth paragraph on page 156 to say (spec changes identical + to EXT_texture_array): + + "The command + + void TexImage2D(enum target, int level, + int internalformat, sizei width, sizei height, + int border, enum format, enum type, void *data); + + is used to specify a two-dimensional texture image. target must be one + of TEXTURE_2D for a two-dimensional texture, TEXTURE_1D_ARRAY_EXT for a + one-dimensional array texture, or one of TEXTURE_CUBE_MAP_POSITIVE_X, + TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y, + TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, or + TEXTURE_CUBE_MAP_NEGATIVE_Z for a cube map texture. Additionally, + target may be either PROXY_TEXTURE_2D for a two-dimensional proxy + texture, PROXY_TEXTURE_1D_ARRAY_EXT for a one-dimensional proxy array + texture, or PROXY TEXTURE_CUBE_MAP for a cube map proxy texture in the + special case discussed in section 3.8.11. The other parameters match + the corresponding parameters of TexImage3D. + + For the purposes of decoding the texture image, TexImage2D is + equivalent to calling TexImage3D with corresponding arguments and depth + of 1, except that + + * The border depth, d_b, is zero, and the depth of the image is + always 1 regardless of the value of border. + + * The border height, h_b, is zero if <target> is + TEXTURE_1D_ARRAY_EXT, and <border> otherwise. + + * Convolution will be performed on the image (possibly changing its + width and height) if SEPARABLE 2D or CONVOLUTION 2D is enabled. + + * UNPACK SKIP IMAGES is ignored." + + -- Section 3.8.2 "Alternate Texture Image Specification Commands" + + Change the second paragraph (page 159) (spec changes identical + to EXT_texture_array): + + "The command + + void CopyTexImage2D(enum target, int level, + enum internalformat, int x, int y, sizei width, + sizei height, int border); + + defines a two-dimensional texture image in exactly the manner of + TexImage2D, except that the image data are taken from the framebuffer + rather than from client memory. Currently, target must be one of + TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, TEXTURE_CUBE_MAP_POSITIVE_X, + TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE MAP_POSITIVE_Y, + TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, or + TEXTURE_CUBE_MAP_NEGATIVE_Z. + + + Change the last paragraph on page 160 to say (spec changes identical + to EXT_texture_array): + + "Currently the target arguments of TexSubImage1D and CopyTexSubImage1D + must be TEXTURE_1D, the target arguments of TexSubImage2D and + CopyTexSubImage2D must be one of TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, + TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_NEGATIVE_X, + TEXTURE_CUBE_MAP_POSITIVE_Y, TEXTURE_CUBE_MAP_NEGATIVE_Y, + TEXTURE_CUBE_MAP_POSITIVE_Z, or TEXTURE_CUBE_MAP_NEGATIVE_Z, and the + target arguments of TexSubImage3D and CopyTexSubImage3D must be + TEXTURE_3D or TEXTURE_2D_ARRAY_EXT. ..." + + + -- Section 3.8.4 "Texture Parameters" + + Change the first paragraph (page 166) to say: + + "Various parameters control how the texel array is treated when + specified or changed, and when applied to a fragment. Each parameter is + set by calling + + void TexParameter{if}(enum target, enum pname, T param); + void TexParameter{if}v(enum target, enum pname, T params); + + target is the target, either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, + TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT." + + + -- Section 3.8.8 "Texture Minification" in the section "Scale Factor and Level of Detail" + + Change the first paragraph (page 172) to say: + + "Let s(x,y) be the function that associates an s texture coordinate + with each set of window coordinates (x,y) that lie within a primitive; + define t(x,y) and r(x,y) analogously. Let u(x,y) = w_t * s(x,y), + v(x,y) = h_t * t(x,y), and w(x,y) = d_t * r(x,y), where w_t, h_t, + and d_t are as defined by equations 3.15, 3.16, and 3.17 with + w_s, h_s, and d_s equal to the width, height, and depth of the + image array whose level is level_base. For a one-dimensional + texture or a one-dimensional array texture, define v(x,y) = 0 and + w(x,y) = 0; for a two-dimensional texture or a two-dimensional array + texture, define w(x,y) = 0..." + + -- Section 3.8.8 "Texture Minification" in the section "Mipmapping" + + Change the third paragraph (page 174) to say: + + "For a two-dimensional texture, two-dimensional array texture, or + cube map texture," + + Change the fourth paragraph (page 174) to say: + + "And for a one-dimensional texture or a one-dimensional array texture," + + After the first paragraph (page 175) add: + + "For one-dimensional array textures, h_b and d_b are treated as 1, + regardless of the actual values, when performing mipmap calculations. + For two-dimensional array textures, d_b is always treated as one, + regardless of the actual value, when performing mipmap calculations." + + -- Section 3.8.8 "Automatic Mipmap Generation" in the section "Mipmapping" + + Change the third paragraph (page 176) to say (spec changes identical + to EXT_texture_array): + + "The contents of the derived arrays are computed by repeated, filtered + reduction of the level_base array. For one- and two-dimensional array + textures, each layer is filtered independently. ..." + + -- Section 3.8.8 "Manual Mipmap Generation" in the section "Mipmapping" + + Change first paragraph to say (spec changes identical to + EXT_texture_array): + + "Mipmaps can be generated manually with the command + + void GenerateMipmapEXT(enum target); + + where <target> is one of TEXTURE_1D, TEXTURE_2D, TEXTURE_CUBE_MAP, + TEXTURE_3D, TEXTURE_1D_ARRAY, or TEXTURE_2D_ARRAY. Mipmap generation + affects the texture image attached to <target>. ..." + + -- Section 3.8.10 "Texture Completeness" + + Change the second paragraph (page 177) to say (spec changes identical + to EXT_texture_array): + + "For one-, two-, or three-dimensional textures and one- or + two-dimensional array textures, a texture is complete if the following + conditions all hold true:" + + -- Section 3.8.11 "Texture State and Proxy State" + + Change the second and third paragraphs (page 179) to say (spec changes + identical to EXT_texture_array): + + "In addition to image arrays for one-, two-, and three-dimensional + textures, one- and two-dimensional array textures, and the six image + arrays for the cube map texture, partially instantiated image arrays + are maintained for one-, two-, and three-dimensional textures and one- + and two-dimensional array textures. Additionally, a single proxy image + array is maintained for the cube map texture. Each proxy image array + includes width, height, depth, border width, and internal format state + values, as well as state for the red, green, blue, alpha, luminance, + and intensity component resolutions. Proxy image arrays do not include + image data, nor do they include texture properties. When TexImage3D is + executed with target specified as PROXY_TEXTURE_3D, the + three-dimensional proxy state values of the specified level-of-detail + are recomputed and updated. If the image array would not be supported + by TexImage3D called with target set to TEXTURE 3D, no error is + generated, but the proxy width, height, depth, border width, and + component resolutions are set to zero. If the image array would be + supported by such a call to TexImage3D, the proxy state values are set + exactly as though the actual image array were being specified. No pixel + data are transferred or processed in either case. + + Proxy arrays for one- and two-dimensional textures and one- and + two-dimensional array textures are operated on in the same way when + TexImage1D is executed with target specified as PROXY_TEXTURE_1D, + TexImage2D is executed with target specified as PROXY_TEXTURE_2D or + PROXY_TEXTURE_1D_ARRAY_EXT, or TexImage3D is executed with target + specified as PROXY_TETXURE_2D_ARRAY_EXT." + + -- Section 3.8.12 "Texture Objects" + + Change section (page 180) to say (spec changes identical to + EXT_texture_array): + + "In addition to the default textures TEXTURE_1D, TEXTURE_2D, + TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and TEXTURE_2D_EXT, + named one-, two-, and three-dimensional, cube map, and one- and + two-dimensional array texture objects can be created and operated upon. + The name space for texture objects is the unsigned integers, with zero + reserved by the GL. + + A texture object is created by binding an unused name to TEXTURE_1D, + TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or + TEXTURE_2D_ARRAY_EXT. The binding is effected by calling + + void BindTexture(enum target, uint texture); + + with <target> set to the desired texture target and <texture> set to + the unused name. The resulting texture object is a new state vector, + comprising all the state values listed in section 3.8.11, set to the + same initial values. If the new texture object is bound to TEXTURE_1D, + TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or + TEXTURE_2D_ARRAY_EXT, it is and remains a one-, two-, + three-dimensional, cube map, one- or two-dimensional array texture + respectively until it is deleted. + + BindTexture may also be used to bind an existing texture object to + either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, + TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT. The error + INVALID_OPERATION is generated if an attempt is made to bind a texture + object of different dimensionality than the specified target. If the + bind is successful no change is made to the state of the bound texture + object, and any previous binding to target is broken. + + While a texture object is bound, GL operations on the target to which + it is bound affect the bound object, and queries of the target to which + it is bound return state from the bound object. If texture mapping of + the dimensionality of the target to which a texture object is bound is + enabled, the state of the bound texture object directs the texturing + operation. + + In the initial state, TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, + TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and TEXTURE_2D_ARRAY_EXT have + one-, two-, three-dimensional, cube map, and one- and two-dimensional + array texture state vectors respectively associated with them. In order + that access to these initial textures not be lost, they are treated as + texture objects all of whose names are 0. The initial one-, two-, + three-dimensional, cube map, one- and two-dimensional array textures + are therefore operated upon, queried, and applied as TEXTURE_1D, + TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and + TEXTURE_2D_ARRAY_EXT respectively while 0 is bound to the corresponding + targets. + + Change second paragraph on page 181 to say (spec changes identical to + EXT_texture_array): + + "... If a texture that is currently bound to one of the targets + TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, + TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT is deleted, it is as + though BindTexture had been executed with the same target and texture + zero. ..." + + Change second paragraph on page 182 to say (spec changes identical to + EXT_texture_array): + + "The texture object name space, including the initial one-, two-, and + three dimensional, cube map, and one- and two-dimensional array texture + objects, is shared among all texture units. ..." + + + -- Section 3.8.14 "Depth Texture Comparison Modes" in "Texture Comparison Modes" + + Change second through fourth paragraphs (page 188) to say: + + "Let D_t be the depth texture value, in the range [0, 1]. For + texture lookups from one- and two-dimensional, rectangle, and + one-dimensional array targets, let R be the interpolated <r> + texture coordinate, clamped to the range [0, 1]. For texture lookups + from two-dimensional array texture targets, let R be the interpolated + <q> texture coordinate, clamped to the range [0, 1]. Then the + effective texture value L_t, I_t, or A_t is computed as follows: + + If the value of TEXTURE_COMPARE_MODE is NONE, then + + r = Dt + + If the value of TEXTURE_COMPARE_MODE is + COMPARE_REF_DEPTH_TO_TEXTURE_EXT), then r depends on the texture + comparison function as shown in table 3.27." + + -- Section 3.8.15 "Texture Application" + + Change the first paragraph (page 189) to say: + + "Texturing is enabled or disabled using the generic Enable and Disable + commands, respectively, with the symbolic constants TEXTURE_1D, + TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or + TEXTURE_2D_ARRAY_EXT to enable one-, two-, three-dimensional, cube + map, one-dimensional array, or two-dimensional array texture, + respectively. If both two- and one-dimensional textures are enabled, + the two-dimensional texture is used. If the three-dimensional and + either of the two- or one-dimensional textures is enabled, the + three-dimensional texture is used. If the cube map texture and any of + the three-, two-, or one-dimensional textures is enabled, then cube map + texturing is used. If one-dimensional array texture is enabled and any + of cube map, three-, two-, or one-dimensional textures is enabled, + one-dimensional array texturing is used. If two-dimensional array + texture is enabled and any of cube map, three-, two-, one-dimensional + textures or one-dimensional array texture is enabled, two-dimensional + array texturing is used..." + + -- Section 3.11.2 of ARB_fragment_program (Fragment Program Grammar and Restrictions): + + (mostly add to existing grammar rules) + + <optionName> ::= "MESA_texture_array" + + <texTarget> ::= "1D" + | "2D" + | "3D" + | "CUBE" + | "RECT" + | <arrayTarget> (if program option is present) + | <shadowTarget> (if program option is present) + + <arrayTarget> ::= "ARRAY1D" + | "ARRAY2D" + + <shadowTarget> ::= "SHADOW1D" + | "SHADOW2D" + | "SHADOWRECT" + | <shadowArrayTarget> (if program option is present) + + <shadowArrayTarget> ::= "SHADOWARRAY1D" + | "SHADOWARRAY2D" + + + -- Add Section 3.11.4.5.4 "Texture Stack Option" + + "If a fragment program specifies the "MESA_texture_array" program + option, the <texTarget> rule is modified to add the texture targets + ARRAY1D and ARRAY2D (See Section 3.11.2)." + + -- Section 3.11.6 "Fragment Program Texture Instruction Set" + + (replace 1st and 2nd paragraphs with the following paragraphs) + + "The first three texture instructions described below specify the + mapping of 4-tuple input vectors to 4-tuple output vectors. + The sampling of the texture works as described in section 3.8, + except that texture environments and texture functions are not + applicable, and the texture enables hierarchy is replaced by explicit + references to the desired texture target (i.e., 1D, 2D, 3D, cube map, + rectangle, ARRAY1D, ARRAY2D). These texture instructions specify + how the 4-tuple is mapped into the coordinates used for sampling. The + following function is used to describe the texture sampling in the + descriptions below: + + vec4 TextureSample(vec4 coord, float lodBias, int texImageUnit, + enum texTarget); + + Note that not all four components of the texture coordinates <coord> + are used by all texture targets. Component usage for each <texTarget> + is defined in table X. + + coordinates used + texTarget Texture Type s t r layer shadow + ---------------- --------------------- ----- ----- ------ + 1D TEXTURE_1D x - - - - + 2D TEXTURE_2D x y - - - + 3D TEXTURE_3D x y z - - + CUBE TEXTURE_CUBE_MAP x y z - - + RECT TEXTURE_RECTANGLE_ARB x y - - - + ARRAY1D TEXTURE_1D_ARRAY_EXT x - - y - + ARRAY2D TEXTURE_2D_ARRAY_EXT x y - z - + SHADOW1D TEXTURE_1D x - - - z + SHADOW2D TEXTURE_2D x y - - z + SHADOWRECT TEXTURE_RECTANGLE_ARB x y - - z + SHADOWARRAY1D TEXTURE_1D_ARRAY_EXT x - - y z + SHADOWARRAY2D TEXTURE_2D_ARRAY_EXT x y - z w + + Table X: Texture types accessed for each of the <texTarget>, and + coordinate mappings. The "coordinates used" column indicate the + input values used for each coordinate of the texture lookup, the + layer selector for array textures, and the reference value for + texture comparisons." + + -- Section 3.11.6.2 "TXP: Project coordinate and map to color" + + Add to the end of the section: + + "A program will fail to load if the TXP instruction is used in + conjunction with the SHADOWARRAY2D target." + +Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment Operations) + + -- Section 4.4.2.3 "Attaching Texture Images to a Framebuffer" + + Add to the end of the section (spec changes identical to + EXT_texture_array): + + "The command + + void FramebufferTextureLayerEXT(enum target, enum attachment, + uint texture, int level, int layer); + + operates identically to FramebufferTexture3DEXT, except that it + attaches a single layer of a three-dimensional texture or a one- or + two-dimensional array texture. <layer> is an integer indicating the + layer number, and is treated identically to the <zoffset> parameter in + FramebufferTexture3DEXT. The error INVALID_VALUE is generated if + <layer> is negative. The error INVALID_OPERATION is generated if + <texture> is non-zero and is not the name of a three dimensional + texture or one- or two-dimensional array texture. Unlike + FramebufferTexture3D, no <textarget> parameter is accepted. + + If <texture> is non-zero and the command does not result in an error, + the framebuffer attachment state corresponding to <attachment> is + updated as in the other FramebufferTexture commands, except that + FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT is set to <layer>." + + -- Section 4.4.4.1 "Framebuffer Attachment Completeness" + + Add to the end of the list of completeness rules (spec changes + identical to EXT_texture_array): + + "* If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE and + FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT names a one- or + two-dimensional array texture, then + FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT must be smaller than the + number of layers in the texture." + +Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) + + -- Section 5.4 "Display Lists" + + Change the first paragraph on page 242 to say (spec changes + identical to EXT_texture_array): + + "TexImage3D, TexImage2D, TexImage1D, Histogram, and ColorTable are + executed immediately when called with the corresponding proxy arguments + PROXY_TEXTURE_3D or PROXY_TEXTURE_2D_ARRAY_EXT; PROXY_TEXTURE_2D, + PROXY_TEXTURE_CUBE_MAP, or PROXY_TEXTURE_1D_ARRAY_EXT; + PROXY_TEXTURE_1D; PROXY_HISTOGRAM; and PROXY_COLOR_TABLE, + PROXY_POST_CONVOLUTION_COLOR_TABLE, or + PROXY_POST_COLOR_MATRIX_COLOR_TABLE." + +Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State Requests) + + -- Section 6.1.3 "Enumerated Queries" + + Add after the line beginning "If the value of + FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE" (spec changes + identical to EXT_texture_array): + + "If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT and the + texture object named FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is a + three-dimensional texture or a one- or two-dimensional array texture, + then <params> will contain the number of texture layer attached to the + attachment point. Otherwise, <params> will contain the value zero." + + -- Section 6.1.4 "Texture Queries" + + Change the first three paragraphs (page 248) to say (spec changes + identical to EXT_texture_array): + + "The command + + void GetTexImage(enum tex, int lod, enum format, + enum type, void *img); + + is used to obtain texture images. It is somewhat different from the + other get commands; tex is a symbolic value indicating which texture + (or texture face in the case of a cube map texture target name) is to + be obtained. TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_1D_ARRAY_EXT, + and TEXTURE_2D_ARRAY_EXT indicate a one-, two-, or three-dimensional + texture, or one- or two-dimensional array texture, respectively. + TEXTURE_CUBE_MAP_POSITIVE_X, ... + + GetTexImage obtains... from the first image to the last for + three-dimensional textures. One- and two-dimensional array textures + are treated as two- and three-dimensional images, respectively, where + the layers are treated as rows or images. These groups are then... + + For three-dimensional and two-dimensional array textures, pixel storage + operations are applied as if the image were two-dimensional, except + that the additional pixel storage state values PACK_IMAGE_HEIGHT and + PACK_SKIP_IMAGES are applied. ..." + +Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) + + None + +Additions to the AGL/GLX/WGL Specifications + + None + +GLX Protocol + + None + +Dependencies on ARB_fragment_program + + If ARB_fragment_program is not supported, the changes to section 3.11 + should be ignored. + +Dependencies on EXT_framebuffer_object + + If EXT_framebuffer_object is not supported, the changes to section + 3.8.8 ("Manual Mipmap Generation"), 4.4.2.3, and 6.1.3 should be ignored. + +Dependencies on EXT_texture_compression_s3tc and NV_texture_compression_vtc + + (Identical dependency as EXT_texture_array.) + + S3TC texture compression is supported for two-dimensional array textures. + When <target> is TEXTURE_2D_ARRAY_EXT, each layer is stored independently + as a compressed two-dimensional textures. When specifying or querying + compressed images using one of the S3TC formats, the images are provided + and/or returned as a series of two-dimensional textures stored + consecutively in memory, with the layer closest to zero specified first. + For array textures, images are not arranged in 4x4x4 or 4x4x2 blocks as in + the three-dimensional compression format provided in the + EXT_texture_compression_vtc extension. Pixel store parameters, including + those specific to three-dimensional images, are ignored when compressed + image data are provided or returned, as in the + EXT_texture_compression_s3tc extension. + + S3TC compression is not supported for one-dimensional texture targets in + EXT_texture_compression_s3tc, and is not supported for one-dimensional + array textures in this extension. If compressed one-dimensional arrays + are needed, use a two-dimensional texture with a height of one. + + This extension allows the use of the four S3TC internal format types in + TexImage3D, CompressedTexImage3D, and CompressedTexSubImage3D calls. + +Errors + + None + +New State + + (add to table 6.15, p. 276) + + Initial + Get Value Type Get Command Value Description Sec. Attribute + ---------------------------- ----- ----------- ----- -------------------- ------ --------- + TEXTURE_BINDING_1D_ARRAY_EXT 2*xZ+ GetIntegerv 0 texture object bound 3.8.12 texture + to TEXTURE_1D_ARRAY + TEXTURE_BINDING_2D_ARRAY_EXT 2*xZ+ GetIntegerv 0 texture object bound 3.8.12 texture + to TEXTURE_2D_ARRAY + + +New Implementation Dependent State + + (add to Table 6.32, p. 293) + + Minimum + Get Value Type Get Command Value Description Sec. Attribute + ---------------------------- ---- ----------- ------- ------------------ ----- --------- + MAX_TEXTURE_ARRAY_LAYERS_EXT Z+ GetIntegerv 64 maximum number of 3.8.1 - + layers for texture + arrays + +Issues + + (1) Is "texture stack" a good name for this functionality? + + NO. The name is changed to "array texture" to match the + nomenclature used by GL_EXT_texture_array. + + (2) Should the R texture coordinate be treated as normalized or + un-normalized? If it were un-normalized, floor(R) could be thought + of as a direct index into the array texture. This may be more + convenient for applications. + + RESOLVED. All texture coordinates are normalized. The issue of + un-normalized texture coordinates has been discussed in the ARB + before and should be left for a layered extension. + + RE-RESOLVED. The R coordinate is un-normalized. Accessing an array + using [0, layers-1] coordinates is much more natural. + + (3) How does LOD selection work for stacked textures? + + RESOLVED. For 2D array textures the R coordinate is ignored, and + the LOD selection equations for 2D textures are used. For 1D + array textures the T coordinate is ignored, and the LOD selection + equations for 1D textures are used. The expected usage is in a + fragment program with an explicit LOD selection. + + (4) What is the maximum size of a 2D array texture? Is it the same + as for a 3D texture, or should a new query be added? How about for 1D + array textures? + + RESOLVED. A new query is added. + + (5) How are array textures exposed in GLSL? + + RESOLVED. Use GL_EXT_texture_array. + + (6) Should a 1D array texture also be exposed? + + RESOLVED. For orthogonality, yes. + + (7) How are stacked textures attached to framebuffer objects? + + RESOLVED. Layers of both one- and two-dimensional array textures + are attached using FreambufferTextureLayerEXT. Once attached, the + array texture layer behaves exactly as either a one- or + two-dimensional texture. + + (8) How is this extension related to GL_EXT_texture_array? + + This extension adapats GL_MESAX_texture_stack to the notation, + indexing, and FBO access of GL_EXT_texture_array. This extension + replaces the GLSL support of GL_EXT_texture_array with + GL_ARB_fragment_program support. + + Assembly program support is also provided by GL_NV_gpu_program4. + GL_NV_gpu_program4 also adds support for other features that are + specific to Nvidia hardware, while this extension adds only support + for array textures. + + Much of text of this extension that has changed since + GL_MESAX_texture_stack comes directly from either + GL_EXT_texture_array or GL_NV_gpu_program4. + +Revision History + + ||2005/11/15||0.1||idr||Initial draft MESAX version.|| + ||2005/12/07||0.2||idr||Added framebuffer object interactions.|| + ||2005/12/12||0.3||idr||Updated fragment program interactions.|| + ||2007/05/16||0.4||idr||Converted to MESA_texture_array. Brought in line with EXT_texture_array and NV_gpu_program4.|| diff --git a/docs/specs/MESA_texture_signed_rgba.spec b/docs/specs/MESA_texture_signed_rgba.spec new file mode 100644 index 00000000000..e3a6b59afac --- /dev/null +++ b/docs/specs/MESA_texture_signed_rgba.spec @@ -0,0 +1,214 @@ +Name + + MESA_texture_signed_rgba + +Name Strings + + GL_MESA_texture_signed_rgba + +Contact + + + +Notice + + + +IP Status + + No known IP issues + +Status + + + +Version + + 0.3, 2009-03-24 + +Number + + Not assigned ? + +Dependencies + + Written based on the wording of the OpenGL 2.0 specification. + + This extension trivially interacts with ARB_texture_float. + This extension shares some language with ARB_texture_compression_rgtc + but does not depend on it. + +Overview + + OpenGL prior to 3.1 does not support any signed texture formats. + ARB_texture_compression_rgtc introduces some compressed red and + red_green signed formats but no uncompressed ones, which might + still be useful. NV_texture_shader adds signed texture formats, + but also a lot of functionality which has been superseded by fragment + shaders. + It is usually possible to get the same functionality + using a unsigned format by doing scale and bias in a shader, but this + is undesirable since modern hardware has direct support for this. + This extension adds a signed 4-channel texture format by backporting + the relevant features from OpenGL 3.1, as a means to support this in + OpenGL implementations only supporting older versions. + +Issues + + 1) What should this extension be called? + + RESOLVED: MESA_texture_signed_rgba seems reasonable. + The rgba part is there because only 4 channel format is supported. + + + 2) Should the full set of signed formats (alpha, luminance, rgb, etc.) + be supported? + + RESOLVED: NO. To keep this extension simple, only add the most + universal format, rgba. alpha/luminance can't be trivially supported + since OpenGL 3.1 does not support them any longer, and there is some + implied dependency on ARB_texture_rg for red/red_green formats so + avoid all this. Likewise, only 8 bits per channel is supported. + + + 3) Should this extension use new enums for the texture formats? + + RESOLVED: NO. Same enums as those used in OpenGL 3.1. + + + 4) How are signed integer values mapped to floating-point values? + + RESOLVED: Same as described in issue 5) of + ARB_texture_compression_rgtc (quote): + A signed 8-bit two's complement value X is computed to + a floating-point value Xf with the formula: + + { X / 127.0, X > -128 + Xf = { + { -1.0, X == -128 + + This conversion means -1, 0, and +1 are all exactly representable, + however -128 and -127 both map to -1.0. Mapping -128 to -1.0 + avoids the numerical awkwardness of have a representable value + slightly more negative than -1.0. + + This conversion is intentionally NOT the "byte" conversion listed + in Table 2.9 for component conversions. That conversion says: + + Xf = (2*X + 1) / 255.0 + + The Table 2.9 conversion is incapable of exactly representing + zero. + + (Difference to ARB_texture_compression_rgtc): + This is the same mapping as OpenGL 3.1 uses. + This is also different to what NV_texture_shader used. + The above mapping should be considered the reference, but there + is some leeway so other mappings are allowed for implementations which + cannot do this. Particularly the mapping given in NV_texture_shader or + the standard OpenGL byte/float mapping is considered acceptable too, as + might be a mapping which represents -1.0 by -128, 0.0 by 0 and 1.0 by + 127 (that is, uses different scale factors for negative and positive + numbers). + Also, it is ok to store incoming GL_BYTE user data as-is, without + converting to GL_FLOAT (using the standard OpenGL float/byte mapping) + and converting back (using the mapping described here). + Other than those subtle issues there are no other non-standard + conversions used, so when using for instance CopyTexImage2D with + a framebuffer clamped to [0,1] all converted numbers will be in the range + [0, 127] (and not scaled and biased). + + + 5) How will signed components resulting from RGBA8_SNORM texture + fetches interact with fragment coloring? + + RESOLVED: Same as described in issue 6) of + ARB_texture_compression_rgtc (quote): + The specification language for this extension is silent + about clamping behavior leaving this to the core specification + and other extensions. The clamping or lack of clamping is left + to the core specification and other extensions. + + For assembly program extensions supporting texture fetches + (ARB_fragment_program, NV_fragment_program, NV_vertex_program3, + etc.) or the OpenGL Shading Language, these signed formats will + appear as expected with unclamped signed components as a result + of a texture fetch instruction. + + If ARB_color_buffer_float is supported, its clamping controls + will apply. + + NV_texture_shader extension, if supported, adds support for + fixed-point textures with signed components and relaxed the + fixed-function texture environment clamping appropriately. If the + NV_texture_shader extension is supported, its specified behavior + for the texture environment applies where intermediate values + are clamped to [-1,1] unless stated otherwise as in the case + of explicitly clamped to [0,1] for GL_COMBINE. or clamping the + linear interpolation weight to [0,1] for GL_DECAL and GL_BLEND. + + Otherwise, the conventional core texture environment clamps + incoming, intermediate, and output color components to [0,1]. + + This implies that the conventional texture environment + functionality of unextended OpenGL 1.5 or OpenGL 2.0 without + using GLSL (and with none of the extensions referred to above) + is unable to make proper use of the signed texture formats added + by this extension because the conventional texture environment + requires texture source colors to be clamped to [0,1]. Texture + filtering of these signed formats would be still signed, but + negative values generated post-filtering would be clamped to + zero by the core texture environment functionality. The + expectation is clearly that this extension would be co-implemented + with one of the previously referred to extensions or used with + GLSL for the new signed formats to be useful. + + + 6) Should the RGBA_SNORM tokens also be accepted by CopyTexImage + functions? + + RESOLVED: YES. + + + 7) What to do with GetTexParameter if ARB_texture_float is supported, + in particular what datatype should this return for TEXTURE_RED_TYPE_ARB, + TEXTURE_GREEN_TYPE_ARB, TEXTURE_BLUE_TYPE_ARB, TEXTURE_ALPHA_TYPE_ARB? + + RESOLVED: ARB_texture_float states type is either NONE, + UNSIGNED_NORMALIZED_ARB, or FLOAT. This extension adds a new enum, + SIGNED_NORMALIZED, which will be returned accordingly. This is the + same behaviour as in OpenGL 3.1. + + +New Tokens + + + Accepted by the <internalformat> parameter of + TexImage1D, TexImage2D, TexImage3D, CopyTexImage1D, and CopyTexImage2D: + + RGBA_SNORM 0x8F93 + RGBA8_SNORM 0x8F97 + + Returned by the <params> parameter of GetTexLevelParameter: + + SIGNED_NORMALIZED 0x8F9C + + +Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization): + + -- Section 3.8.1, Texture Image Specification + + Add to Table 3.16 (page 154): Sized internal formats + + Sized Base R G B A L I D + Internal Format Internal Format bits bits bits bits bits bits bits + --------------- --------------- ---- ---- ---- ---- ---- ---- ---- + RGBA8_SNORM RGBA 8 8 8 8 0 0 0 + + +Dependencies on ARB_texture_float extension: + + If ARB_texture_float is supported, GetTexParameter queries with <value> + of TEXTURE_RED_TYPE_ARB, TEXTURE_GREEN_TYPE_ARB, TEXTURE_BLUE_TYPE_ARB or + TEXTURE_ALPHA_TYPE_ARB return SIGNED_NORMALIZED if + the base internal format is RGBA_SNORM. diff --git a/docs/specs/MESA_window_pos.spec b/docs/specs/MESA_window_pos.spec new file mode 100644 index 00000000000..9e81e9c4db4 --- /dev/null +++ b/docs/specs/MESA_window_pos.spec @@ -0,0 +1,126 @@ +Name + + MESA_window_pos + +Name Strings + + GL_MESA_window_pos + +Contact + + Brian Paul, brian.paul 'at' tungstengraphics.com + +Status + + Shipping (since Mesa version 1.2.8) + +Version + + +Number + + 197 + +Dependencies + + OpenGL 1.0 is required. + The extension is written against the OpenGL 1.2 Specification + +Overview + + In order to set the current raster position to a specific window + coordinate with the RasterPos command, the modelview matrix, projection + matrix and viewport must be set very carefully. Furthermore, if the + desired window coordinate is outside of the window's bounds one must + rely on a subtle side-effect of the Bitmap command in order to circumvent + frustum clipping. + + This extension provides a set of functions to directly set the + current raster position, bypassing the modelview matrix, the + projection matrix and the viewport to window mapping. Furthermore, + clip testing is not performed. + + This greatly simplifies the process of setting the current raster + position to a specific window coordinate prior to calling DrawPixels, + CopyPixels or Bitmap. + +New Procedures and Functions + + void WindowPos2dMESA(double x, double y) + void WindowPos2fMESA(float x, float y) + void WindowPos2iMESA(int x, int y) + void WindowPos2sMESA(short x, short y) + void WindowPos2ivMESA(const int *p) + void WindowPos2svMESA(const short *p) + void WindowPos2fvMESA(const float *p) + void WindowPos2dvMESA(const double *p) + void WindowPos3iMESA(int x, int y, int z) + void WindowPos3sMESA(short x, short y, short z) + void WindowPos3fMESA(float x, float y, float z) + void WindowPos3dMESA(double x, double y, double z) + void WindowPos3ivMESA(const int *p) + void WindowPos3svMESA(const short *p) + void WindowPos3fvMESA(const float *p) + void WindowPos3dvMESA(const double *p) + void WindowPos4iMESA(int x, int y, int z, int w) + void WindowPos4sMESA(short x, short y, short z, short w) + void WindowPos4fMESA(float x, float y, float z, float w) + void WindowPos4dMESA(double x, double y, double z, double ) + void WindowPos4ivMESA(const int *p) + void WindowPos4svMESA(const short *p) + void WindowPos4fvMESA(const float *p) + void WindowPos4dvMESA(const double *p) + +New Tokens + + none + +Additions to Chapter 2 of the OpenGL 1.2 Specification (OpenGL Operation) + + - (2.12, p. 41) Insert after third paragraph: + + Alternately, the current raster position may be set by one of the + WindowPosMESA commands: + + void WindowPos{234}{sidf}MESA( T coords ); + void WindowPos{234}{sidf}vMESA( T coords ); + + WindosPos4MESA takes four values indicating x, y, z, and w. + WindowPos3MESA (or WindowPos2MESA) is analaguos, but sets only + x, y, and z with w implicitly set to 1 (or only x and y with z + implicitly set to 0 and w implicitly set to 1). + + WindowPosMESA operates like RasterPos except that the current modelview + matrix, projection matrix and viewport parameters are ignored and the + clip test operation always passes. The current raster position values + are directly set to the parameters passed to WindowPosMESA. The current + color, color index and texture coordinate update the current raster + position's associated data. + +Additions to the AGL/GLX/WGL Specifications + + None + +GLX Protocol + + Not specified at this time. However, a protocol message very similar + to that of RasterPos is expected. + +Errors + + INVALID_OPERATION is generated if WindowPosMESA is called between + Begin and End. + +New State + + None. + +New Implementation Dependent State + + None. + +Revision History + + * Revision 1.0 - Initial specification + * Revision 1.1 - Minor clean-up (7 Jan 2000, Brian Paul) + diff --git a/docs/specs/MESA_ycbcr_texture.spec b/docs/specs/MESA_ycbcr_texture.spec new file mode 100644 index 00000000000..6a730e81ccf --- /dev/null +++ b/docs/specs/MESA_ycbcr_texture.spec @@ -0,0 +1,204 @@ +Name + + MESA_ycbcr_texture + +Name Strings + + GL_MESA_ycbcr_texture + +Contact + + Brian Paul, Tungsten Graphics, Inc. (brian.paul 'at' tungstengraphics.com) + Keith Whitwell, Tungsten Graphics, Inc. (keith 'at' tungstengraphics.com) + +Status + + Shipping (Mesa 4.0.4 and later) + +Version + + 1.0 + +Number + + TBD + +Dependencies + + OpenGL 1.0 or later is required + This extension is written against the OpenGL 1.4 Specification. + NV_texture_rectangle effects the definition of this extension. + +Overview + + This extension supports texture images stored in the YCbCr format. + There is no support for converting YCbCr images to RGB or vice versa + during pixel transfer. The texture's YCbCr colors are converted to + RGB during texture sampling, after-which, all the usual per-fragment + operations take place. Only 2D texture images are supported (not + glDrawPixels, glReadPixels, etc). + + A YCbCr pixel (texel) is a 16-bit unsigned short with two components. + The first component is luminance (Y). For pixels in even-numbered + image columns, the second component is Cb. For pixels in odd-numbered + image columns, the second component is Cr. If one were to convert the + data to RGB one would need to examine two pixels from columns N and N+1 + (where N is even) to deduce the RGB color. + +IP Status + + None + +Issues + + None + +New Procedures and Functions + + None + +New Tokens + + Accepted by the <internalFormat> and <format> parameters of + TexImage2D and TexSubImage2D: + + YCBCR_MESA 0x8757 + + Accepted by the <type> parameter of TexImage2D and TexSubImage2D: + + UNSIGNED_SHORT_8_8_MESA 0x85BA /* same as Apple's */ + UNSIGNED_SHORT_8_8_REV_MESA 0x85BB /* same as Apple's */ + +Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation) + + None + +Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization) + + In section 3.6.4, Rasterization of Pixel Rectangles, on page 101, + add the following to Table 3.8 (Packed pixel formats): + + type Parameter GL Data Number of Matching + Token Name Type Components Pixel Formats + -------------- ------- ---------- ------------- + UNSIGNED_SHORT_8_8_MESA ushort 2 YCBCR_MESA + UNSIGNED_SHORT_8_8_REV_MESA ushort 2 YCBCR_MESA + + + In section 3.6.4, Rasterization of Pixel Rectangles, on page 102, + add the following to Table 3.10 (UNSIGNED_SHORT formats): + + UNSIGNED_SHORT_8_8_MESA: + + 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + +-------------------------------+-------------------------------+ + | 1st | 2nd | + +-------------------------------+-------------------------------+ + + UNSIGNED_SHORT_8_8_REV_MESA: + + 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + +-------------------------------+-------------------------------+ + | 2nd | 1st | + +-------------------------------+-------------------------------+ + + + In section 3.6.4, Rasterization of Pixel Rectangles, on page 104, + add the following to Table 3.12 (Packed pixel field assignments): + + First Second Third Fourth + Format Element Element Element Element + ------ ------- ------- ------- ------- + YCBCR_MESA luminance chroma + + + In section 3.8.1, Texture Image Specification, on page 125, add + another item to the list of TexImage2D and TexImage3D equivalence + exceptions: + + * The value of internalformat and format may be YCBCR_MESA to + indicate that the image data is in YCbCr format. type must + be either UNSIGNED_SHORT_8_8_MESA or UNSIGNED_SHORT_8_8_REV_MESA + as seen in tables 3.8 and 3.10. Table 3.12 describes the mapping + between Y and Cb/Cr to the components. + If NV_texture_rectangle is supported target may also be + TEXTURE_RECTANGLE_NV or PROXY_TEXTURE_RECTANGLE_NV. + All pixel transfer operations are bypassed. The texture is stored as + YCbCr, not RGB. Queries of the texture's red, green and blue component + sizes will return zero. The YCbCr colors are converted to RGB during + texture sampling using an implementation dependent conversion. + + + In section 3.8.1, Texture Image Specification, on page 126, add + another item to the list of TexImage1D and TexImage2D equivalence + exceptions: + + * The value of internalformat and format can not be YCBCR_MESA. + + + In section 3.8.2, Alternate Texture Image Specification Commands, on + page 129, insert this paragraph after the first full paragraph on the + page: + + "If the internal storage format of the image being updated by + TexSubImage2D is YCBCR_MESA then format must be YCBCR_MESA. + The error INVALID_OPERATION will be generated otherwise." + + +Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment +Operations and the Frame Buffer) + + None + +Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions) + + None + +Additions to Chapter 6 of the OpenGL 1.4 Specification (State and +State Requests) + + None + +Additions to Appendix A of the OpenGL 1.4 Specification (Invariance) + + None + +Additions to the AGL/GLX/WGL Specifications + + None + +GLX Protocol + + None + +Errors + + INVALID_ENUM is generated by TexImage2D if <internalFormat> is + MESA_YCBCR but <format> is not MESA_YCBCR. + + INVALID_ENUM is generated by TexImage2D if <format> is MESA_YCBCR but + <internalFormat> is not MESA_YCBCR. + + INVALID_VALUE is generated by TexImage2D if <format> is MESA_YCBCR and + <internalFormat> is MESA_YCBCR and <border> is not zero. + + INVALID_OPERATION is generated by TexSubImage2D if the internal image + format is YCBCR_MESA and <format> is not YCBCR_MESA. + + INVALID_OPERATION is generated by CopyTexSubImage2D if the internal + image is YCBCR_MESA. + +New State + + Edit table 6.16 on page 231: change the type of TEXTURE_INTERNAL_FORMAT + from n x Z42 to n x Z43 to indicate that internal format may also be + YCBCR_MESA. + +Revision History + + 20 September 2002 - Initial draft + 29 April 2003 - minor updates + 3 September 2003 - further clarify when YCbCr->RGB conversion takes place + 19 September 2003 - a few more updates prior to submitting to extension + registry. + 3 April 2004 - fix assorted inaccuracies diff --git a/docs/specs/OLD/MESA_packed_depth_stencil.spec b/docs/specs/OLD/MESA_packed_depth_stencil.spec new file mode 100644 index 00000000000..112b730ecc2 --- /dev/null +++ b/docs/specs/OLD/MESA_packed_depth_stencil.spec @@ -0,0 +1,230 @@ +Name + + MESA_packed_depth_stencil + +Name Strings + + GL_MESA_packed_depth_stencil + +Contact + + Keith Whitwell, VA Linux Systems Inc. (keithw 'at' valinux.com) + Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com) + +Status + + Obsolete. + +Version + + +Number + + ??? + +Dependencies + + EXT_abgr affects the definition of this extension + SGIS_texture4D affects the definition of this extension + EXT_cmyka affects the definition of this extension + ARB_packed_pixels affects the definition of this extension + +Overview + + Provides a mechanism for DrawPixels and ReadPixels to efficiently + transfer depth and stencil image data. Specifically, we defined new + packed pixel formats and types which pack both stencil and depth + into one value. + +Issues: + + 1. Is this the right way to distinguish between 24/8 and 8/24 + pixel formats? Should we instead provide both: + + GL_DEPTH_STENCIL_MESA + GL_STENCIL_DEPTH_MESA + + And perhaps just use GL_UNSIGNED_INT, GL_UNSIGNED_SHORT ? + + 2. If not, is it correct to use _REV to indicate that stencil + preceeds depth in the 1_15 and 8_24 formats? + + 3. Do we really want the GL_UNSIGNED_SHORT formats? + + +New Procedures and Functions + + None. + +New Tokens + + Accepted by the <format> parameter of ReadPixels and DrawPixels: + + GL_DEPTH_STENCIL_MESA 0x8750 + + Accepted by the <type> parameter of ReadPixels and DrawPixels: + + GL_UNSIGNED_INT_24_8_MESA 0x8751 + GL_UNSIGNED_INT_8_24_REV_MESA 0x8752 + GL_UNSIGNED_SHORT_15_1_MESA 0x8753 + GL_UNSIGNED_SHORT_1_15_REV_MESA 0x8754 + +Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation) + + None + +Additions to Chapter 3 of the 1.1 Specification (Rasterization) + + One entry is added to table 3.5 (DrawPixels and ReadPixels formats). + The new table is: + + Target + Format Name Buffer Element Meaning and Order + ----------- ------ ------------------------- + COLOR_INDEX Color Color index + STENCIL_INDEX Stencil Stencil index + DEPTH_COMPONENT Depth Depth component + RED Color R component + GREEN Color G component + BLUE Color B component + ALPHA Color A component + RGB Color R, G, B components + RGBA Color R, G, B, A components + BGRA Color B, G, R, A components + ABGR_EXT Color A, B, G, R components + CMYK_EXT Color Cyan, Magenta, Yellow, Black components + CMYKA_EXT Color Cyan, Magenta, Yellow, Black, A components + LUMINANCE Color Luminance component + LUMINANCE_ALPHA Color Luminance, A components + DEPTH_STENCIL Depth, Depth component, stencil index. + Stencil + + Table 3.5: DrawPixels and ReadPixels formats. The third column + gives a description of and the number and order of elements in a + group. + + Add to the description of packed pixel formats: + + <type> Parameter Data of Matching + Token Name Type Elements Pixel Formats + ---------------- ---- -------- ------------- + + UNSIGNED_BYTE_3_3_2 ubyte 3 RGB + UNSIGNED_BYTE_2_3_3_REV ubyte 3 RGB + UNSIGNED_SHORT_5_6_5 ushort 3 RGB + UNSIGNED_SHORT_5_6_5_REV ushort 3 RGB + UNSIGNED_SHORT_4_4_4_4 ushort 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT + UNSIGNED_SHORT_4_4_4_4_REV ushort 4 RGBA,BGRA + UNSIGNED_SHORT_5_5_5_1 ushort 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT + UNSIGNED_SHORT_1_5_5_5_REV ushort 4 RGBA,BGRA + UNSIGNED_INT_8_8_8_8 uint 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT + UNSIGNED_INT_8_8_8_8_REV uint 4 RGBA,BGRA + UNSIGNED_INT_10_10_10_2 uint 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT + UNSIGNED_INT_2_10_10_10_REV uint 4 RGBA,BGRA + UNSIGNED_SHORT_15_1_MESA ushort 2 DEPTH_STENCIL_MESA + UNSIGNED_SHORT_1_15_REV_MESA ushort 2 DEPTH_STENCIL_MESA + UNSIGNED_SHORT_24_8_MESA ushort 2 DEPTH_STENCIL_MESA + UNSIGNED_SHORT_8_24_REV_MESA ushort 2 DEPTH_STENCIL_MESA + + UNSIGNED_INT_8_24: + + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + +-----------------------+-----------------------------------------------------------------------+ + | | | + +-----------------------+-----------------------------------------------------------------------+ + + first second + element element + + + UNSIGNED_INT_24_8: + + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + +----------------------------------------------------------------------+------------------------+ + | | | + +----------------------------------------------------------------------+------------------------+ + + first second + element element + + UNSIGNED_SHORT_15_1: + + 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + +-----------------------------------------------------------+---+ + | | | + +-----------------------------------------------------------+---+ + + first second + element element + + + UNSIGNED_SHORT_1_15_REV: + + 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + +---+-----------------------------------------------------------+ + | | | + +---+-----------------------------------------------------------+ + + second first + element element + + The assignment of elements to fields in the packed pixel is as + described in the table below: + + First Second Third Fourth + Format Element Element Element Element + ------ ------- ------- ------- ------- + RGB red green blue + RGBA red green blue alpha + BGRA blue green red alpha + ABGR_EXT alpha blue green red + CMYK_EXT cyan magenta yellow black + DEPTH_STENCIL_MESA depth stencil + +Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations +and the Frame Buffer) + + The new format is added to the discussion of Obtaining Pixels from the + Framebuffer. It should read " If the <format> is one of RED, GREEN, + BLUE, ALPHA, RGB, RGBA, ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, and + the GL is in color index mode, then the color index is obtained." + + The new format is added to the discussion of Index Lookup. It should + read "If <format> is one of RED, GREEN, BLUE, ALPHA, RGB, RGBA, + ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, then the index is used to + reference 4 tables of color components: PIXEL_MAP_I_TO_R, + PIXEL_MAP_I_TO_G, PIXEL_MAP_I_TO_B, and PIXEL_MAP_I_TO_A." + + +Additions to Chapter 5 of the 1.1 Specification (Special Functions) + + None + +Additions to Chapter 6 of the 1.1 Specification (State and State Requests) + + None + +Additions to the GLX Specification + + None + +GLX Protocol + + TBD + +Errors + + None + +New State + + None + +Revision History + + Version 1.0 - 23 Sep 2000 + Keith's original version. + + Version 1.1 - 3 Nov 2000 + Brian's edits, assigned values to new enums. + diff --git a/docs/specs/OLD/MESA_program_debug.spec b/docs/specs/OLD/MESA_program_debug.spec new file mode 100644 index 00000000000..7694fdcc425 --- /dev/null +++ b/docs/specs/OLD/MESA_program_debug.spec @@ -0,0 +1,356 @@ +Name + + MESA_program_debug + +Name Strings + + GL_MESA_program_debug + +Contact + + Brian Paul (brian.paul 'at' tungstengraphics.com) + +Status + + XXX - Not complete yet!!! + +Version + + Last Modified Date: July 20, 2003 + Author Revision: 1.0 + +Number + + TBD + +Dependencies + + OpenGL 1.4 is required + The extension is written against the OpenGL 1.4 specification. + ARB_vertex_program or ARB_fragment_program or NV_vertex_program + or NV_fragment_program is required. + +Overview + + The extension provides facilities for implementing debuggers for + vertex and fragment programs. + + The concept is that vertex and fragment program debuggers will be + implemented outside of the GL as a utility package. This extension + only provides the minimal hooks required to implement a debugger. + + There are facilities to do the following: + 1. Have the GL call a user-specified function prior to executing + each vertex or fragment instruction. + 2. Query the current program string's execution position. + 3. Query the current values of intermediate program values. + + The main feature is the ProgramCallbackMESA function. It allows the + user to register a callback function with the GL. The callback will + be called prior to executing each vertex or fragment program instruction. + + From within the callback, the user may issue Get* commands to + query current GL state. The GetProgramRegisterfvMESA function allows + current program values to be queried (such as temporaries, input + attributes, and result registers). + + There are flags for enabling/disabling the program callbacks. + + The current execution position (as an offset from the start of the + program string) can be queried with + GetIntegerv(GL_FRAGMENT_PROGRAM_POSITION_MESA, &pos) or + GetIntegerv(GL_VERTEX_PROGRAM_POSITION_MESA, &pos). + + +IP Status + + None + +Issues + + 1. Is this the right model for a debugger? + + It seems prudent to minimize the scope of this extension and leave + it up to the developer (or developer community) to write debuggers + that layer on top of this extension. + + If the debugger were fully implemented within the GL it's not + clear how terminal and GUI-based interfaces would work, for + example. + + 2. There aren't any other extensions that register callbacks with + the GL. Isn't there another solution? + + If we want to be able to single-step through vertex/fragment + programs I don't see another way to do it. + + 3. How do we prevent the user from doing something crazy in the + callback function, like trying to call glBegin (leading to + recursion)? + + The rule is that the callback function can only issue glGet*() + functions and no other GL commands. It could be difficult to + enforce this, however. Therefore, calling any non-get GL + command from within the callback will result in undefined + results. + + 4. Is this extension amenable to hardware implementation? + + Hopefully, but if not, the GL implementation will have to fall + back to a software path when debugging. This may be acceptable + for debugging. + + 5. What's the <data> parameter to ProgramCallbackMESA for? + + It's a common programming practice to associate a user-supplied + value with callback functions. + + 6. Debuggers often allow one to modify intermediate program values, + then continue. Does this extension support that? + + No. + + +New Procedures and Functions (and datatypes) + + typedef void (*programcallbackMESA)(enum target, void *data) + + void ProgramCallbackMESA(enum target, programcallbackMESA callback, + void *data) + + void GetProgramRegisterfvMESA(enum target, sizei len, + const ubyte *registerName, float *v) + +New Tokens + + Accepted by the <cap> parameter of Enable, Disable, IsEnabled, + GetBooleanv, GetDoublev, GetFloatv and GetIntegerv: + + FRAGMENT_PROGRAM_CALLBACK_MESA 0x8bb1 + VERTEX_PROGRAM_CALLBACK_MESA 0x8bb4 + + Accepted by the <pname> parameter GetBooleanv, GetDoublev, + GetFloatv and GetIntegerv: + + FRAGMENT_PROGRAM_POSITION_MESA 0x8bb0 + VERTEX_PROGRAM_POSITION_MESA 0x8bb4 + + Accepted by the <pname> parameter of GetPointerv: + + FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x8bb2 + FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x8bb3 + VERTEX_PROGRAM_CALLBACK_FUNC_MESA 0x8bb6 + VERTEX_PROGRAM_CALLBACK_DATA_MESA 0x8bb7 + +Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation) + + None. + +Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization) + + None. + +Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment +Operations and the Frame Buffer) + + None. + +Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions) + + In section 5.4 "Display Lists", page 202, add the following command + to the list of those that are not compiled into display lists: + + ProgramCallbackMESA. + + + Add a new section 5.7 "Callback Functions" + + The function + + void ProgramCallbackMESA(enum target, programcallbackMESA callback, + void *data) + + registers a user-defined callback function with the GL. <target> + may be FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB. The enabled + callback functions registered with these targets will be called + prior to executing each instruction in the current fragment or + vertex program, respectively. The callbacks are enabled and + disabled by calling Enable or Disable with <cap> + FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB. + + The callback function's signature must match the typedef + + typedef void (*programcallbackMESA)(enum target, void *data) + + When the callback function is called, <target> will either be + FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which + program is currently executing and <data> will be the value + specified when ProgramCallbackMESA was called. + + From within the callback function, only the following GL commands + may be called: + + GetBooleanv + GetDoublev + GetFloatv + GetIntegerv + GetProgramLocalParameter + GetProgramEnvParameter + GetProgramRegisterfvMESA + GetProgramivARB + GetProgramStringARB + GetError + + Calling any other command from within the callback results in + undefined behaviour. + + +Additions to Chapter 6 of the OpenGL 1.4 Specification (State and +State Requests) + + Add a new section 6.1.3 "Program Value Queries": + + The command + + void GetProgramRegisterfvMESA(enum target, sizei len, + const ubyte *registerName, + float *v) + + Is used to query the value of program variables and registers + during program execution. GetProgramRegisterfvMESA may only be + called from within a callback function registered with + ProgramCallbackMESA. + + <registerName> and <len> specify the name a variable, input + attribute, temporary, or result register in the program string. + The current value of the named variable is returned as four + values in <v>. If <name> doesn't exist in the program string, + the error INVALID_OPERATION is generated. + +Additions to Appendix A of the OpenGL 1.4 Specification (Invariance) + + None. + +Additions to the AGL/GLX/WGL Specifications + + None. + +GLX Protocol + + XXX TBD + +Dependencies on NV_vertex_program and NV_fragment_program + + If NV_vertex_program and/or NV_fragment_program are supported, + vertex and/or fragment programs defined by those extensions may + be debugged as well. Register queries will use the syntax used + by those extensions (i.e. "v[X]" to query vertex attributes, + "o[X]" for vertex outputs, etc.) + +Errors + + INVALID_OPERATION is generated if ProgramCallbackMESA is called + between Begin and End. + + INVALID_ENUM is generated by ProgramCallbackMESA if <target> is not + a supported vertex or fragment program type. + + Note: INVALID_OPERAION IS NOT generated by GetProgramRegisterfvMESA, + GetBooleanv, GetDoublev, GetFloatv, or GetIntegerv if called between + Begin and End when a vertex or fragment program is currently executing. + + INVALID_ENUM is generated by ProgramCallbackMESA, + GetProgramRegisterfvMESA if <target> is not a program target supported + by ARB_vertex_program, ARB_fragment_program (or NV_vertex_program or + NV_fragment_program). + + INVALID_VALUE is generated by GetProgramRegisterfvMESA if <registerName> + does not name a known program register or variable. + + INVALID_OPERATION is generated by GetProgramRegisterfvMESA when a + register query is attempted for a program target that's not currently + being executed. + + +New State + + XXX finish + +(table 6.N, p. ###) + Initial + Get Value Type Get Command Value Description Sec. Attribute + --------- ---- ----------- ----- ----------- ---- --------- + FRAGMENT_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable + VERTEX_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable + FRAGMENT_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX - + VERTEX_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX - + FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX - + VERTEX_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX - + FRAGMENT_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX - + VERTEX_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX - + + XXX more? + +New Implementation Dependent State + + None. + +Revision History + + 8 July 2003 + Initial draft. (Brian Paul) + 11 July 2003 + Second draft. (Brian Paul) + 20 July 2003 + Third draft. Lots of fundamental changes. (Brian Paul) + 23 July 2003 + Added chapter 5 and 6 spec language. (Brian Paul) + +Example Usage + + The following is a very simple example of how this extension may + be used to print the values of R0, R1, R2 and R3 while executing + vertex programs. + + + /* This is called by the GL when the vertex program is executing. + * We can only make glGet* calls from within this function! + */ + void DebugCallback(GLenum target, GLvoid *data) + { + GLint pos; + GLuint i; + + /* Get PC and current instruction string */ + glGetIntegerv(GL_VERTEX_PROGRAM_POSITION_ARB, &pos); + + printf("Current position: %d\n", pos); + + printf("Current temporary registers:\n"); + for (i = 0; i < 4; i++) { + GLfloat v[4]; + char s[10]; + sprintf(s, "R%d", i); + glGetProgramRegisterfvMESA(GL_VERTEX_PROGRAM_ARB, strlen(s), s, v); + printf("R%d = %g, %g, %g, %g\n", i, v[0], v[1], v[2], v[3]); + } + } + + + /* + * elsewhere... + */ + + /* Register our debugger callback function */ + glProgramCallbackMESA(GL_VERTEX_PROGRAM_ARB, DebugCallback, NULL); + glEnable(GL_VERTEX_PROGRAM_CALLBACK_MESA); + + /* define/bind a vertex program */ + + glEnable(GL_VERTEX_PROGRAM); + + /* render something */ + glBegin(GL_POINTS); + glVertex2f(0, 0); + glEnd(); + diff --git a/docs/specs/OLD/MESA_sprite_point.spec b/docs/specs/OLD/MESA_sprite_point.spec new file mode 100644 index 00000000000..b50d78e9e7b --- /dev/null +++ b/docs/specs/OLD/MESA_sprite_point.spec @@ -0,0 +1,190 @@ +Name + + MESA_sprite_point + +Name Strings + + GL_MESA_sprite_point + +Contact + + Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com) + +Status + + Obsolete - see GL_ARB_point_sprite. + +Version + + +Number + + ??? + +Dependencies + + GL_EXT_point_parameters effects the definition of this extension + GL_ARB_multitexture effects the definition of this extension + +Overview + + This extension modifies the way in which points are rendered, + specifically when they're textured. When SPRITE_POINT_MESA is enabled + a point is rendered as if it were a quadrilateral with unique texture + coordinates at each vertex. This extension effectively turns points + into sprites which may be rendered more easily and quickly than using + conventional textured quadrilaterals. + + When using point size > 1 or attenuated points this extension is an + effective way to render many small sprite images for particle systems + or other effects. + +Issues: + + 1. How are the texture coordinates computed? + + The lower-left corner has texture coordinate (0,0,r,q). + The lower-right, (1,0,r,q). The upper-right, (1,1,r,q). + The upper-left, (0,1,r,q). + + 2. What about texgen and texture matrices? + + Texgen and the texture matrix have no effect on the point's s and t + texture coordinates. The r and q coordinates may have been computed + by texgen or the texture matrix. Note that with a 3D texture and/or + texgen that the r coordinate could be used to select a slice in the + 3D texture. + + 3. What about point smoothing? + + When point smoothing is enabled, a triangle fan could be rendered + to approximate a circular point. This could be problematic to + define and implement so POINT_SMOOTH is ignored when drawing sprite + points. + + Smoothed points can be approximated by using an appropriate texture + images, alpha testing and blending. + + POLYGON_SMOOTH does effect the rendering of the quadrilateral, however. + + 4. What about sprite rotation? + + There is none. Sprite points are always rendered as window-aligned + squares. One could define rotated texture images if desired. A 3D + texture and appropriate texture r coordinates could be used to + effectively specify image rotation per point. + + 5. What about POLYGON_MODE? + + POLYGON_MODE does not effect the rasterization of the quadrilateral. + + 6. What about POLYGON_CULL? + + TBD. Polygon culling is normally specified and implemented in the + transformation stage of OpenGL. However, some rasterization hardware + implements it later during triangle setup. + + Polygon culling wouldn't be useful for sprite points since the + quadrilaterals are always defined in counter-clockwise order in + window space. For that reason, polygon culling should probably be + ignored. + + 7. Should sprite points be alpha-attenuated if their size is below the + point parameter's threshold size? + + 8. Should there be an advertisized maximum sprite point size? + + No. Since we're rendering the point as a quadrilateral there's no + need to limit the size. + + +New Procedures and Functions + + None. + +New Tokens + + Accepted by the <pname> parameter of Enable, Disable, IsEnabled, + GetIntegerv, GetBooleanv, GetFloatv and GetDoublev: + + SPRITE_POINT_MESA 0x???? + MAX_SPRITE_POINT_SIZE_MESA 0x???? (need this?) + +Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation) + + None + +Additions to Chapter 3 of the 1.1 Specification (Rasterization) + + Section ???. + + When SPRITE_POINT_MESA is enabled points are rasterized as screen- + aligned quadrilaterals. If the four vertices of the quadrilateral + are labeled A, B, C, and D, starting at the lower-left corner and moving + counter-clockwise around the quadrilateral, then the vertex and + texture coordinates are computed as follows: + + vertex window coordinate texture coordinate + A (x-r, y-r, z, w) (0, 0, r, q) + B (x+r, y-r, z, w) (1, 0, r, q) + C (x+r, y+r, z, w) (1, 1, r, q) + D (x-r, y+r, z, w) (0, 1, r, q) + + where x, y, z, w are the point's window coordinates, r and q are the + point's 3rd and 4th texture coordinates and r is half the point's + size. The other vertex attributes (such as the color and fog coordinate) + are simply duplicated from the original point vertex. + + Point size may either be specified with PointSize or computed + according to the EXT_point_parameters extension. + + The new texture coordinates are not effected by texgen or the texture + matrix. Note, however, that the texture r and q coordinates are passed + unchanged and may have been computed with texgen and/or the texture + matrix. + + If multiple texture units are present the same texture coordinate is + used for all texture units. + + The point is then rendered as if it were a quadrilateral using the + normal point sampling rules. POLYGON_MODE does not effect the + rasterization of the quadrilateral but POLYGON_SMOOTH does. + + POINT_SMOOTH has no effect when SPRITE_POINT_MESA is enabled. + +Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations +and the Frame Buffer) + + None. + +Additions to Chapter 5 of the 1.1 Specification (Special Functions) + + None + +Additions to Chapter 6 of the 1.1 Specification (State and State Requests) + + None + +Additions to the GLX Specification + + None + +GLX Protocol + + TBD + +Errors + + None + +New State + + Add boolean variable SPRITE_POINT_MESA to the point attribute group. + +Revision History + + Version 1.0 - 4 Dec 2000 + Original draft. + + + diff --git a/docs/specs/OLD/MESA_trace.spec b/docs/specs/OLD/MESA_trace.spec new file mode 100644 index 00000000000..dc4166e6b6e --- /dev/null +++ b/docs/specs/OLD/MESA_trace.spec @@ -0,0 +1,359 @@ +Name + + MESA_trace + +Name Strings + + GL_MESA_trace + +Contact + + Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com + Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com + +Status + + Obsolete. + +Version + + +Number + + none yet + +Dependencies + + OpenGL 1.2 is required. + The extension is written against the OpenGL 1.2 Specification + +Overview + + Provides the application with means to enable and disable logging + of GL calls including parameters as readable text. The verbosity + of the generated log can be controlled. The resulting logs are + valid (but possibly incomplete) C code and can be compiled and + linked for standalone test programs. The set of calls and the + amount of static data that is logged can be controlled at runtime. + The application can add comments and enable or disable tracing of GL + operations at any time. The data flow from the application to GL + and back is unaffected except for timing. + + Application-side implementation of these features raises namespace + and linkage issues. In the driver dispatch table a simple + "chain of responsibility" pattern (aka "composable piepline") + can be added. + +IP Status + + The extension spec is in the public domain. The current implementation + in Mesa is covered by Mesa's XFree86-style copyright by the authors above. + This extension is partially inspired by the Quake2 QGL wrapper. + +Issues + + + (1) Is this Extension obsolete because it can + be implemented as a wrapper DLL? + + RESOLVED: No. While certain operating systems (Win32) provide linkers + that facilitate this kind of solution, other operating systems + (Linux) do not support hierarchical linking, so a wrapper solution + would result in symbol collisions. + Further, IHV's might have builtin support for tracing GL execution + that enjoys privileged access, or that they do not wish to separate + the tracing code from their driver code base. + + (2) Should the Trace API explicitely support the notion of "frames? + This would require hooking into glXSwapBuffers calls as well. + + RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA + and TraceComment along with external parsing tools to split the + trace into frames, in whatever way considered adequate. + + (2a) Should GLX calls be traced? + + PBuffers and other render-to-texture solutions demonstrate that + context level commands beyond SwapBuffers might have to be + traced. The GL DLL exports the entry points, so this would not + be out of the question. + + (3) Should the specification mandate the actual output format? + + RESOLVED: No. It is sufficient to guarantee that all data and commands + will be traced as requested by Enable/DisableTraceMESA, in the order + encountered. Whether the resulting trace is available as a readable + text file, binary metafile, compilable source code, much less which + indentation and formatting has been used, is up to the implementation. + For the same reason this specification does not enforce or prohibit + additional information added to the trace (statistics, profiling/timing, + warnings on possible error conditions). + + (4) Should the comment strings associated with names and pointer (ranges) + be considered persistent state? + + RESOLVED: No. The implementation is not forced to use this information + on subsequent occurences of name/pointer, and is free to consider it + transient state. + + (5) Should comment commands be prohibited between Begin/End? + + RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA + is transient, the other commands might cause storage of persistent + data in the context. There is no need to have the ability mark names + or pointers between Begin and End. + + +New Procedures and Functions + + void NewTraceMESA( bitfield mask, const ubyte * traceName ) + + void EndTraceMESA( void ) + + void EnableTraceMESA( bitfield mask ) + + void DisableTraceMESA( bitfield mask ) + + void TraceAssertAttribMESA( bitfield attribMask ) + + void TraceCommentMESA( const ubyte* comment ) + + void TraceTextureMESA( uint name, const ubyte* comment ) + + void TraceListMESA( uint name, const ubyte* comment ) + + void TracePointerMESA( void* pointer, const ubyte* comment ) + + void TracePointerRangeMESA( const void* first, + const void* last, + const ubyte* comment ) + +New Tokens + + Accepted by the <mask> parameter of EnableTrace and DisableTrace: + + TRACE_ALL_BITS_MESA 0xFFFF + TRACE_OPERATIONS_BIT_MESA 0x0001 + TRACE_PRIMITIVES_BIT_MESA 0x0002 + TRACE_ARRAYS_BIT_MESA 0x0004 + TRACE_TEXTURES_BIT_MESA 0x0008 + TRACE_PIXELS_BIT_MESA 0x0010 + TRACE_ERRORS_BIT_MESA 0x0020 + + Accepted by the <pname> parameter of GetIntegerv, GetBooleanv, + GetFloatv, and GetDoublev: + + TRACE_MASK_MESA 0x8755 + + Accepted by the <pname> parameter to GetString: + + TRACE_NAME_MESA 0x8756 + + +Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) + + None. + +Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation) + + None. + +Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation) + + None. + +Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) + + Add a new section: + + 5.7 Tracing + + The tracing facility is used to record the execution of a GL program + to a human-readable log. The log appears as a sequence of GL commands + using C syntax. The primary intention of tracing is to aid in program + debugging. + + A trace is started with the command + + void NewTraceMESA( bitfield mask, const GLubyte * traceName ) + + <mask> may be any value accepted by PushAttrib and specifies a set of + attribute groups. The state values included in those attribute groups + is written to the trace as a sequence of GL commands. + + <traceName> specifies a name or label for the trace. It is expected + that <traceName> will be interpreted as a filename in most implementations. + + A trace is ended by calling the command + + void EndTraceMESA( void ) + + It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End. + + The commands + + void EnableTraceMESA( bitfield mask ) + void DisableTraceMESA( bitfield mask ) + + enable or disable tracing of different classes of GL commands. + <mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA, + TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA, + and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA + indicates all classes of commands are to be logged. + + TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of + Begin/End, including Begin/End. + + TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of + Begin/End, including Begin/End. + + TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer, + ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands. + + TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by + TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and + TexSubImage3D commands. + + TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by + Bitmap and DrawPixels commands. + + TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is + set, GetError will be executed whereever applicable, and the result will + be added to the trace as a comment. The error returns are cached and + returned to the application on its GetError calls. If the user does not + wish the additional GetError calls to be performed, this bit should not + be set. + + The command + + void TraceCommentMESA( const ubyte* comment ) + + immediately adds the <comment> string to the trace output, surrounded + by C-style comment delimiters. + + The commands + + void TraceTextureMESA( uint name, const ubyte* comment ) + void TraceListMESA( uint name, const ubyte* comment ) + + associates <comment> with the texture object or display list specified + by <name>. Logged commands which reference the named texture object or + display list will be annotated with <comment>. If IsTexture(name) or + IsList(name) fail (respectively) the command is quietly ignored. + + The commands + + void TracePointerMESA( void* pointer, const ubyte* comment ) + + void TracePointerRangeMESA( const void* first, + const void* last, + const ubyte* comment ) + + associate <comment> with the address specified by <pointer> or with + a range of addresses specified by <first> through <last>. + Any logged commands which reference <pointer> or an address between + <first> and <last> will be annotated with <comment>. + + The command + + void TraceAssertAttribMESA( bitfield attribMask ) + + will add GL state queries and assertion statements to the log to + confirm that the current state at the time TraceAssertAttrib is + executed matches the current state when the trace log is executed + in the future. + + <attribMask> is any value accepted by PushAttrib and specifies + the groups of state variables which are to be asserted. + + The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA, + TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA, + TracePointerMESA and TracePointerRangeMESA are not compiled into display lists. + + + Examples: + + The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state + variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE + to get the values <test>, <func>, <mask>, and <clear> respectively. + Statements equivalent to the following will then be logged: + + glEnable(GL_DEPTH_TEST); (if <test> is true) + glDisable(GL_DEPTH_TEST); (if <test> is false) + glDepthFunc(<func>); + glDepthMask(<mask>); + glClearDepth(<clear>); + + + The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state + variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE + to get the values <test>, <func>, <mask>, and <clear> respectively. + The resulting trace might then look will like this: + + { + GLboolean b; + GLint i; + GLfloat f; + b = glIsEnabled(GL_DEPTH_TEST); + assert(b == <test>); + glGetIntegerv(GL_DEPTH_FUNC, &i); + assert(i == <func>); + glGetIntegerv(GL_DEPTH_MASK, &i); + assert(i == <mask>); + glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f); + assert(f == <clear>); + } + + +Additions to Chapter 6 of the OpenGL 1.2.1 Specification + (State and State Requests) + + Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or + GetDoublev returns the current command class trace mask. + + Querying TRACE_NAME_MESA with GetString returns the current trace name. + + +Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance) + + The MESA_trace extension can be used in a way that does not affect data + flow from application to OpenGL, as well as data flow from OpenGL to + application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA + will add additional GetError queries. Setting a trace mask with NewTraceMESA + as well as use of TraceAssertAttribMESA might cause additional state queries. + With the possible exception of performance, OpenGL rendering should not be + affected at all by a properly chosen logging operation. + +Additions to the AGL/GLX/WGL Specifications + + None. + +GLX Protocol + + None. The logging operation is carried out client-side, by exporting + entry points to the wrapper functions that execute the logging operation. + +Errors + + INVALID_OPERATION is generated if any trace command except TraceCommentMESA + is called between Begin and End. + +New State + + The current trace name and current command class mask are stored + per-context. + +New Implementation Dependent State + + None. + +Revision History + + * Revision 0.1 - Initial draft from template (bk000415) + * Revision 0.2 - Draft (bk000906) + * Revision 0.3 - Draft (bk000913) + * Revision 0.4 - Reworked text, fixed typos (bp000914) + * Revision 0.5 - Assigned final GLenum values (bp001103) + * Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916) + * Revision 0.7 - Added MESA postfix (bk010126) + diff --git a/docs/specs/WL_bind_wayland_display.spec b/docs/specs/WL_bind_wayland_display.spec new file mode 100644 index 00000000000..02bd6ea2112 --- /dev/null +++ b/docs/specs/WL_bind_wayland_display.spec @@ -0,0 +1,175 @@ +Name + + WL_bind_wayland_display + +Name Strings + + EGL_WL_bind_wayland_display + +Contact + + Kristian Høgsberg <[email protected]> + Benjamin Franzke <[email protected]> + +Status + + Proposal + +Version + + Version 1, March 1, 2011 + +Number + + EGL Extension #not assigned + +Dependencies + + Requires EGL 1.4 or later. This extension is written against the + wording of the EGL 1.4 specification. + + EGL_KHR_base_image is required. + +Overview + + This extension provides entry points for binding and unbinding the + wl_display of a Wayland compositor to an EGLDisplay. Binding a + wl_display means that the EGL implementation should provide one or + more interfaces in the Wayland protocol to allow clients to create + wl_buffer objects. On the server side, this extension also + provides a new target for eglCreateImageKHR, to create an EGLImage + from a wl_buffer + + Adding an implementation specific wayland interface, allows the + EGL implementation to define specific wayland requests and events, + needed for buffer sharing in an EGL wayland platform. + +IP Status + + Open-source; freely implementable. + +New Procedures and Functions + + EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy, + struct wl_display *display); + + EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy, + struct wl_display *display); + + EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy, + struct wl_buffer *buffer, + EGLint attribute, EGLint *value); + +New Tokens + + Accepted as <target> in eglCreateImageKHR + + EGL_WAYLAND_BUFFER_WL 0x31D5 + + Accepted in the <attrib_list> parameter of eglCreateImageKHR: + + EGL_WAYLAND_PLANE_WL 0x31D6 + + Possible values for EGL_TEXTURE_FORMAT: + + EGL_TEXTURE_Y_U_V_WL 0x31D7 + EGL_TEXTURE_Y_UV_WL 0x31D8 + EGL_TEXTURE_Y_XUXV_WL 0x31D9 + + +Additions to the EGL 1.4 Specification: + + To bind a server side wl_display to an EGLDisplay, call + + EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy, + struct wl_display *display); + + To unbind a server side wl_display from an EGLDisplay, call + + EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy, + struct wl_display *display); + + eglBindWaylandDisplayWL returns EGL_FALSE when there is already a + wl_display bound to EGLDisplay otherwise EGL_TRUE. + + eglUnbindWaylandDisplayWL returns EGL_FALSE when there is no + wl_display bound to the EGLDisplay currently otherwise EGL_TRUE. + + A wl_buffer can have several planes, typically in case of planar + YUV formats. Depending on the exact YUV format in use, the + compositor will have to create one or more EGLImages for the + various planes. The eglQueryWaylandBufferWL function should be + used to first query the wl_buffer texture format using + EGL_TEXTURE_FORMAT as the attribute. If the wl_buffer object is + not an EGL wl_buffer (wl_shm and other wayland extensions can + create wl_buffer objects of different types), this query will + return EGL_FALSE. In that case the wl_buffer can not be used with + EGL and the compositor should have another way to get the buffer + contents. + + If eglQueryWaylandBufferWL succeeds, the returned value will be + one of EGL_TEXTURE_RGB, EGL_TEXTURE_RGBA, EGL_TEXTURE_Y_U_V_WL, + EGL_TEXTURE_Y_UV_WL, EGL_TEXTURE_Y_XUXV_WL. The value returned + describes how many EGLImages must be used, which components will + be sampled from each EGLImage and how they map to rgba components + in the shader. The naming conventions separates planes by _ and + within each plane, the order or R, G, B, A, Y, U, and V indicates + how those components map to the rgba value returned by the + sampler. X indicates that the corresponding component in the rgba + value isn't used. + + RGB and RGBA buffer types: + + EGL_TEXTURE_RGB + One plane, samples RGB from the texture to rgb in the + shader. Alpha channel is not valid. + + EGL_TEXTURE_RGBA + One plane, samples RGBA from the texture to rgba in the + shader. + + YUV buffer types: + + EGL_TEXTURE_Y_U_V_WL + Three planes, samples Y from the first plane to r in + the shader, U from the second plane to r, and V from + the third plane to r. + + EGL_TEXTURE_Y_UV_WL + Two planes, samples Y from the first plane to r in + the shader, U and V from the second plane to rg. + + EGL_TEXTURE_Y_XUXV_WL + Two planes, samples Y from the first plane to r in + the shader, U and V from the second plane to g and a. + + After querying the wl_buffer layout, create EGLImages for the + planes by calling eglCreateImageKHR with wl_buffer as + EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target, NULL + context. If no attributes are given, an EGLImage will be created + for the first plane. For multi-planar buffers, specify the plane + to create the EGLImage for by using the EGL_WAYLAND_PLANE_WL + attribute. The value of the attribute is the index of the plane, + as defined by the buffer format. Writing to an EGLImage created + from a wl_buffer in any way (such as glTexImage2D, binding the + EGLImage as a renderbuffer etc) will result in undefined behavior. + + Further, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and + EGL_HEIGHT to query the width and height of the wl_buffer. + +Issues + +Revision History + + Version 1, March 1, 2011 + Initial draft (Benjamin Franzke) + Version 2, July 5, 2012 + Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage + for different planes of planar buffer. (Kristian Høgsberg) + Version 3, July 10, 2012 + Add eglQueryWaylandBufferWL and the various buffer + formats. (Kristian Høgsberg) + Version 4, July 19, 2012 + Use EGL_TEXTURE_FORMAT, EGL_TEXTURE_RGB, and EGL_TEXTURE_RGBA, + and just define the new YUV texture formats. Add support for + EGL_WIDTH and EGL_HEIGHT in the query attributes (Kristian Høgsberg) diff --git a/docs/specs/enums.txt b/docs/specs/enums.txt new file mode 100644 index 00000000000..b37768e2027 --- /dev/null +++ b/docs/specs/enums.txt @@ -0,0 +1,57 @@ + +See the OpenGL ARB enum registry at http://www.opengl.org/registry/api/enum.spec + +Blocks allocated to Mesa: + 0x8750-0x875F + 0x8BB0-0x8BBF + + +GL_MESA_packed_depth_stencil + GL_DEPTH_STENCIL_MESA 0x8750 + GL_UNSIGNED_INT_24_8_MESA 0x8751 + GL_UNSIGNED_INT_8_24_REV_MESA 0x8752 + GL_UNSIGNED_SHORT_15_1_MESA 0x8753 + GL_UNSIGNED_SHORT_1_15_REV_MESA 0x8754 + +GL_MESA_trace.spec: + GL_TRACE_ALL_BITS_MESA 0xFFFF + GL_TRACE_OPERATIONS_BIT_MESA 0x0001 + GL_TRACE_PRIMITIVES_BIT_MESA 0x0002 + GL_TRACE_ARRAYS_BIT_MESA 0x0004 + GL_TRACE_TEXTURES_BIT_MESA 0x0008 + GL_TRACE_PIXELS_BIT_MESA 0x0010 + GL_TRACE_ERRORS_BIT_MESA 0x0020 + GL_TRACE_MASK_MESA 0x8755 + GL_TRACE_NAME_MESA 0x8756 + +MESA_ycbcr_texture.spec: + GL_YCBCR_MESA 0x8757 + GL_UNSIGNED_SHORT_8_8_MESA 0x85BA /* same as Apple's */ + GL_UNSIGNED_SHORT_8_8_REV_MESA 0x85BB /* same as Apple's */ + +GL_MESA_pack_invert.spec + GL_PACK_INVERT_MESA 0x8758 + +GL_MESA_shader_debug.spec: (obsolete) + GL_DEBUG_OBJECT_MESA 0x8759 + GL_DEBUG_PRINT_MESA 0x875A + GL_DEBUG_ASSERT_MESA 0x875B + +GL_MESA_program_debug.spec: (obsolete) + GL_FRAGMENT_PROGRAM_CALLBACK_MESA 0x???? + GL_VERTEX_PROGRAM_CALLBACK_MESA 0x???? + GL_FRAGMENT_PROGRAM_POSITION_MESA 0x???? + GL_VERTEX_PROGRAM_POSITION_MESA 0x???? + GL_FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x???? + GL_FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x???? + GL_VERTEX_PROGRAM_CALLBACK_FUNC_MESA 0x???? + GL_VERTEX_PROGRAM_CALLBACK_DATA_MESA 0x???? + +GL_MESAX_texture_stack: + GL_TEXTURE_1D_STACK_MESAX 0x8759 + GL_TEXTURE_2D_STACK_MESAX 0x875A + GL_PROXY_TEXTURE_1D_STACK_MESAX 0x875B + GL_PROXY_TEXTURE_2D_STACK_MESAX 0x875C + GL_TEXTURE_1D_STACK_BINDING_MESAX 0x875D + GL_TEXTURE_2D_STACK_BINDING_MESAX 0x875E + |