From cf9bf1d4a6dc3b26e2aa192517611eba3aa5be00 Mon Sep 17 00:00:00 2001 From: Emil Velikov Date: Fri, 12 Apr 2013 12:41:50 +0100 Subject: docs: move specs to a separate folder Handle legacy/obsolete specs as well List all specs in extensions.html Mark 'OLD' extensions as obsolete in extensions.html Update the spec location in old relnotes Signed-off-by: Emil Velikov Reviewed-by: Brian Paul --- docs/MESA_agp_offset.spec | 95 --- docs/MESA_copy_sub_buffer.spec | 96 --- docs/MESA_drm_image.spec | 153 ----- docs/MESA_multithread_makecurrent.spec | 158 ----- docs/MESA_pack_invert.spec | 138 ----- docs/MESA_pixmap_colormap.spec | 90 --- docs/MESA_release_buffers.spec | 85 --- docs/MESA_resize_buffers.spec | 81 --- docs/MESA_set_3dfx_mode.spec | 85 --- docs/MESA_shader_debug.spec | 264 --------- docs/MESA_swap_control.spec | 129 ----- docs/MESA_swap_frame_usage.spec | 201 ------- docs/MESA_texture_array.spec | 804 -------------------------- docs/MESA_texture_signed_rgba.spec | 214 ------- docs/MESA_window_pos.spec | 126 ---- docs/MESA_ycbcr_texture.spec | 204 ------- docs/OLD/MESA_packed_depth_stencil.spec | 230 -------- docs/OLD/MESA_program_debug.spec | 356 ------------ docs/OLD/MESA_sprite_point.spec | 190 ------ docs/OLD/MESA_trace.spec | 359 ------------ docs/WL_bind_wayland_display.spec | 175 ------ docs/enums.txt | 57 -- docs/extensions.html | 34 +- docs/relnotes/5.1 | 2 +- docs/specs/MESA_agp_offset.spec | 95 +++ docs/specs/MESA_copy_sub_buffer.spec | 96 +++ docs/specs/MESA_drm_image.spec | 153 +++++ docs/specs/MESA_multithread_makecurrent.spec | 158 +++++ docs/specs/MESA_pack_invert.spec | 138 +++++ docs/specs/MESA_pixmap_colormap.spec | 90 +++ docs/specs/MESA_release_buffers.spec | 85 +++ docs/specs/MESA_resize_buffers.spec | 81 +++ docs/specs/MESA_set_3dfx_mode.spec | 85 +++ docs/specs/MESA_shader_debug.spec | 264 +++++++++ docs/specs/MESA_swap_control.spec | 129 +++++ docs/specs/MESA_swap_frame_usage.spec | 201 +++++++ docs/specs/MESA_texture_array.spec | 804 ++++++++++++++++++++++++++ docs/specs/MESA_texture_signed_rgba.spec | 214 +++++++ docs/specs/MESA_window_pos.spec | 126 ++++ docs/specs/MESA_ycbcr_texture.spec | 204 +++++++ docs/specs/OLD/MESA_packed_depth_stencil.spec | 230 ++++++++ docs/specs/OLD/MESA_program_debug.spec | 356 ++++++++++++ docs/specs/OLD/MESA_sprite_point.spec | 190 ++++++ docs/specs/OLD/MESA_trace.spec | 359 ++++++++++++ docs/specs/WL_bind_wayland_display.spec | 175 ++++++ docs/specs/enums.txt | 57 ++ docs/xlibdriver.html | 6 +- 47 files changed, 4315 insertions(+), 4307 deletions(-) delete mode 100644 docs/MESA_agp_offset.spec delete mode 100644 docs/MESA_copy_sub_buffer.spec delete mode 100644 docs/MESA_drm_image.spec delete mode 100644 docs/MESA_multithread_makecurrent.spec delete mode 100644 docs/MESA_pack_invert.spec delete mode 100644 docs/MESA_pixmap_colormap.spec delete mode 100644 docs/MESA_release_buffers.spec delete mode 100644 docs/MESA_resize_buffers.spec delete mode 100644 docs/MESA_set_3dfx_mode.spec delete mode 100644 docs/MESA_shader_debug.spec delete mode 100644 docs/MESA_swap_control.spec delete mode 100644 docs/MESA_swap_frame_usage.spec delete mode 100644 docs/MESA_texture_array.spec delete mode 100644 docs/MESA_texture_signed_rgba.spec delete mode 100644 docs/MESA_window_pos.spec delete mode 100644 docs/MESA_ycbcr_texture.spec delete mode 100644 docs/OLD/MESA_packed_depth_stencil.spec delete mode 100644 docs/OLD/MESA_program_debug.spec delete mode 100644 docs/OLD/MESA_sprite_point.spec delete mode 100644 docs/OLD/MESA_trace.spec delete mode 100644 docs/WL_bind_wayland_display.spec delete mode 100644 docs/enums.txt create mode 100644 docs/specs/MESA_agp_offset.spec create mode 100644 docs/specs/MESA_copy_sub_buffer.spec create mode 100644 docs/specs/MESA_drm_image.spec create mode 100644 docs/specs/MESA_multithread_makecurrent.spec create mode 100644 docs/specs/MESA_pack_invert.spec create mode 100644 docs/specs/MESA_pixmap_colormap.spec create mode 100644 docs/specs/MESA_release_buffers.spec create mode 100644 docs/specs/MESA_resize_buffers.spec create mode 100644 docs/specs/MESA_set_3dfx_mode.spec create mode 100644 docs/specs/MESA_shader_debug.spec create mode 100644 docs/specs/MESA_swap_control.spec create mode 100644 docs/specs/MESA_swap_frame_usage.spec create mode 100644 docs/specs/MESA_texture_array.spec create mode 100644 docs/specs/MESA_texture_signed_rgba.spec create mode 100644 docs/specs/MESA_window_pos.spec create mode 100644 docs/specs/MESA_ycbcr_texture.spec create mode 100644 docs/specs/OLD/MESA_packed_depth_stencil.spec create mode 100644 docs/specs/OLD/MESA_program_debug.spec create mode 100644 docs/specs/OLD/MESA_sprite_point.spec create mode 100644 docs/specs/OLD/MESA_trace.spec create mode 100644 docs/specs/WL_bind_wayland_display.spec create mode 100644 docs/specs/enums.txt diff --git a/docs/MESA_agp_offset.spec b/docs/MESA_agp_offset.spec deleted file mode 100644 index 06e1d902edd..00000000000 --- a/docs/MESA_agp_offset.spec +++ /dev/null @@ -1,95 +0,0 @@ -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/MESA_copy_sub_buffer.spec b/docs/MESA_copy_sub_buffer.spec deleted file mode 100644 index 752a014b352..00000000000 --- a/docs/MESA_copy_sub_buffer.spec +++ /dev/null @@ -1,96 +0,0 @@ -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. - - and indicates the lower-left corner of the region to copy and - and 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/MESA_drm_image.spec b/docs/MESA_drm_image.spec deleted file mode 100644 index 1150a4c43e4..00000000000 --- a/docs/MESA_drm_image.spec +++ /dev/null @@ -1,153 +0,0 @@ -Name - - MESA_drm_image - -Name Strings - - EGL_MESA_drm_image - -Contact - - Kristian Høgsberg - -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 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 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 is non-NULL, a global name is assigned to the image and - written to , the handle (local to the DRM file descriptor, - for use with DRM kernel modesetting API) is written to if - non-NULL and the stride (in bytes) is written to , 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/MESA_multithread_makecurrent.spec b/docs/MESA_multithread_makecurrent.spec deleted file mode 100644 index 5065c2fc0a3..00000000000 --- a/docs/MESA_multithread_makecurrent.spec +++ /dev/null @@ -1,158 +0,0 @@ -Name - - MESA_multithread_makecurrent - -Name Strings - - GLX_MESA_multithread_makecurrent - -Contact - - Eric Anholt (eric@anholt.net) - -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/MESA_pack_invert.spec b/docs/MESA_pack_invert.spec deleted file mode 100644 index 33fb3c7bf80..00000000000 --- a/docs/MESA_pack_invert.spec +++ /dev/null @@ -1,138 +0,0 @@ -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 parameter of PixelStorei and PixelStoref - and the 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/MESA_pixmap_colormap.spec b/docs/MESA_pixmap_colormap.spec deleted file mode 100644 index fb0b441cc58..00000000000 --- a/docs/MESA_pixmap_colormap.spec +++ /dev/null @@ -1,90 +0,0 @@ -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/MESA_release_buffers.spec b/docs/MESA_release_buffers.spec deleted file mode 100644 index 52d1e5a9c7c..00000000000 --- a/docs/MESA_release_buffers.spec +++ /dev/null @@ -1,85 +0,0 @@ -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 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/MESA_resize_buffers.spec b/docs/MESA_resize_buffers.spec deleted file mode 100644 index dabc7c421da..00000000000 --- a/docs/MESA_resize_buffers.spec +++ /dev/null @@ -1,81 +0,0 @@ -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/MESA_set_3dfx_mode.spec b/docs/MESA_set_3dfx_mode.spec deleted file mode 100644 index 06d97ca021f..00000000000 --- a/docs/MESA_set_3dfx_mode.spec +++ /dev/null @@ -1,85 +0,0 @@ -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 ); - - 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 is valid and the operation completed - normally. GL_FALSE is returned if 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/MESA_shader_debug.spec b/docs/MESA_shader_debug.spec deleted file mode 100644 index fab92abc762..00000000000 --- a/docs/MESA_shader_debug.spec +++ /dev/null @@ -1,264 +0,0 @@ -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 parameter of GetObjectParameter{fi}vARB: - - DEBUG_OBJECT_MESA 0x8759 - - Accepted by the 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 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 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 , , and - implementation dependent double-quoted string, each of this - delimited by a white space. If the argument is not present, - it is meant as if it was of value 0. If the arguments and - 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/MESA_swap_control.spec b/docs/MESA_swap_control.spec deleted file mode 100644 index a002563c9dc..00000000000 --- a/docs/MESA_swap_control.spec +++ /dev/null @@ -1,129 +0,0 @@ -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 is set to a value of 0, buffer swaps are not synchro- - nized to a video frame. The 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/MESA_swap_frame_usage.spec b/docs/MESA_swap_frame_usage.spec deleted file mode 100644 index 5023eadd8a1..00000000000 --- a/docs/MESA_swap_frame_usage.spec +++ /dev/null @@ -1,201 +0,0 @@ -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 - 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 - 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 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 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 - . - - 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/MESA_texture_array.spec b/docs/MESA_texture_array.spec deleted file mode 100644 index b146821f72e..00000000000 --- a/docs/MESA_texture_array.spec +++ /dev/null @@ -1,804 +0,0 @@ -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 parameter of Enable, Disable, and IsEnabled, by - the parameter of GetBooleanv, GetIntegerv, GetFloatv, and - GetDoublev, and by the parameter of TexImage3D, GetTexImage, - GetTexLevelParameteriv, GetTexLevelParameterfv, GetTexParameteriv, and - GetTexParameterfv: - - TEXTURE_1D_ARRAY_EXT 0x8C18 - TEXTURE_2D_ARRAY_EXT 0x8C1A - - Accepted by the parameter of TexImage2D, TexSubImage2D, - CopyTexImage2D, CopyTexSubImage2D, CompressedTexImage2D, - CompressedTexSubImage2D, GetTexLevelParameteriv, and - GetTexLevelParameterfv: - - TEXTURE_1D_ARRAY_EXT - PROXY_TEXTURE_1D_ARRAY_EXT 0x8C19 - - Accepted by the parameter of TexImage3D, TexSubImage3D, - CopyTexSubImage3D, CompressedTexImage3D, CompressedTexSubImage3D, - GetTexLevelParameteriv, and GetTexLevelParameterfv: - - TEXTURE_2D_ARRAY_EXT - PROXY_TEXTURE_2D_ARRAY_EXT 0x8C1B - - Accepted by the 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 parameter of TexParameterf, TexParameteri, - TexParameterfv, and TexParameteriv when the 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 parameter of TexImage3D and - CompressedTexImage3D, and by the 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 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 - "" 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 is - TEXTURE_1D_ARRAY_EXT, and 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 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 . ..." - - -- 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 set to the desired texture target and 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 - texture coordinate, clamped to the range [0, 1]. For texture lookups - from two-dimensional array texture targets, let R be the interpolated - 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) - - ::= "MESA_texture_array" - - ::= "1D" - | "2D" - | "3D" - | "CUBE" - | "RECT" - | (if program option is present) - | (if program option is present) - - ::= "ARRAY1D" - | "ARRAY2D" - - ::= "SHADOW1D" - | "SHADOW2D" - | "SHADOWRECT" - | (if program option is present) - - ::= "SHADOWARRAY1D" - | "SHADOWARRAY2D" - - - -- Add Section 3.11.4.5.4 "Texture Stack Option" - - "If a fragment program specifies the "MESA_texture_array" program - option, the 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 - are used by all texture targets. Component usage for each - 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 , 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. is an integer indicating the - layer number, and is treated identically to the parameter in - FramebufferTexture3DEXT. The error INVALID_VALUE is generated if - is negative. The error INVALID_OPERATION is generated if - is non-zero and is not the name of a three dimensional - texture or one- or two-dimensional array texture. Unlike - FramebufferTexture3D, no parameter is accepted. - - If is non-zero and the command does not result in an error, - the framebuffer attachment state corresponding to is - updated as in the other FramebufferTexture commands, except that - FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT is set to ." - - -- 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 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 will contain the number of texture layer attached to the - attachment point. Otherwise, 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 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/MESA_texture_signed_rgba.spec b/docs/MESA_texture_signed_rgba.spec deleted file mode 100644 index e3a6b59afac..00000000000 --- a/docs/MESA_texture_signed_rgba.spec +++ /dev/null @@ -1,214 +0,0 @@ -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 parameter of - TexImage1D, TexImage2D, TexImage3D, CopyTexImage1D, and CopyTexImage2D: - - RGBA_SNORM 0x8F93 - RGBA8_SNORM 0x8F97 - - Returned by the 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 - 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/MESA_window_pos.spec b/docs/MESA_window_pos.spec deleted file mode 100644 index 9e81e9c4db4..00000000000 --- a/docs/MESA_window_pos.spec +++ /dev/null @@ -1,126 +0,0 @@ -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/MESA_ycbcr_texture.spec b/docs/MESA_ycbcr_texture.spec deleted file mode 100644 index 6a730e81ccf..00000000000 --- a/docs/MESA_ycbcr_texture.spec +++ /dev/null @@ -1,204 +0,0 @@ -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 and parameters of - TexImage2D and TexSubImage2D: - - YCBCR_MESA 0x8757 - - Accepted by the 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 is - MESA_YCBCR but is not MESA_YCBCR. - - INVALID_ENUM is generated by TexImage2D if is MESA_YCBCR but - is not MESA_YCBCR. - - INVALID_VALUE is generated by TexImage2D if is MESA_YCBCR and - is MESA_YCBCR and is not zero. - - INVALID_OPERATION is generated by TexSubImage2D if the internal image - format is YCBCR_MESA and 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/OLD/MESA_packed_depth_stencil.spec b/docs/OLD/MESA_packed_depth_stencil.spec deleted file mode 100644 index 112b730ecc2..00000000000 --- a/docs/OLD/MESA_packed_depth_stencil.spec +++ /dev/null @@ -1,230 +0,0 @@ -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 parameter of ReadPixels and DrawPixels: - - GL_DEPTH_STENCIL_MESA 0x8750 - - Accepted by the 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: - - 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 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 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/OLD/MESA_program_debug.spec b/docs/OLD/MESA_program_debug.spec deleted file mode 100644 index 7694fdcc425..00000000000 --- a/docs/OLD/MESA_program_debug.spec +++ /dev/null @@ -1,356 +0,0 @@ -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 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 parameter of Enable, Disable, IsEnabled, - GetBooleanv, GetDoublev, GetFloatv and GetIntegerv: - - FRAGMENT_PROGRAM_CALLBACK_MESA 0x8bb1 - VERTEX_PROGRAM_CALLBACK_MESA 0x8bb4 - - Accepted by the parameter GetBooleanv, GetDoublev, - GetFloatv and GetIntegerv: - - FRAGMENT_PROGRAM_POSITION_MESA 0x8bb0 - VERTEX_PROGRAM_POSITION_MESA 0x8bb4 - - Accepted by the 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. - 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 - 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, will either be - FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which - program is currently executing and 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. - - and 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 . If 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 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 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 - 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/OLD/MESA_sprite_point.spec b/docs/OLD/MESA_sprite_point.spec deleted file mode 100644 index b50d78e9e7b..00000000000 --- a/docs/OLD/MESA_sprite_point.spec +++ /dev/null @@ -1,190 +0,0 @@ -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 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/OLD/MESA_trace.spec b/docs/OLD/MESA_trace.spec deleted file mode 100644 index dc4166e6b6e..00000000000 --- a/docs/OLD/MESA_trace.spec +++ /dev/null @@ -1,359 +0,0 @@ -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 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 parameter of GetIntegerv, GetBooleanv, - GetFloatv, and GetDoublev: - - TRACE_MASK_MESA 0x8755 - - Accepted by the 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 ) - - 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. - - specifies a name or label for the trace. It is expected - that 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. - 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 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 with the texture object or display list specified - by . Logged commands which reference the named texture object or - display list will be annotated with . 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 with the address specified by or with - a range of addresses specified by through . - Any logged commands which reference or an address between - and will be annotated with . - - 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. - - 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 , , , and respectively. - Statements equivalent to the following will then be logged: - - glEnable(GL_DEPTH_TEST); (if is true) - glDisable(GL_DEPTH_TEST); (if is false) - glDepthFunc(); - glDepthMask(); - glClearDepth(); - - - 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 , , , and respectively. - The resulting trace might then look will like this: - - { - GLboolean b; - GLint i; - GLfloat f; - b = glIsEnabled(GL_DEPTH_TEST); - assert(b == ); - glGetIntegerv(GL_DEPTH_FUNC, &i); - assert(i == ); - glGetIntegerv(GL_DEPTH_MASK, &i); - assert(i == ); - glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f); - assert(f == ); - } - - -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/WL_bind_wayland_display.spec b/docs/WL_bind_wayland_display.spec deleted file mode 100644 index 02bd6ea2112..00000000000 --- a/docs/WL_bind_wayland_display.spec +++ /dev/null @@ -1,175 +0,0 @@ -Name - - WL_bind_wayland_display - -Name Strings - - EGL_WL_bind_wayland_display - -Contact - - Kristian Høgsberg - Benjamin Franzke - -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 in eglCreateImageKHR - - EGL_WAYLAND_BUFFER_WL 0x31D5 - - Accepted in the 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/enums.txt b/docs/enums.txt deleted file mode 100644 index b37768e2027..00000000000 --- a/docs/enums.txt +++ /dev/null @@ -1,57 +0,0 @@ - -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 - diff --git a/docs/extensions.html b/docs/extensions.html index 5d790fb6188..40f59d3b089 100644 --- a/docs/extensions.html +++ b/docs/extensions.html @@ -23,19 +23,27 @@ The specifications follow. diff --git a/docs/relnotes/5.1 b/docs/relnotes/5.1 index aed6e102b09..59b7964a080 100644 --- a/docs/relnotes/5.1 +++ b/docs/relnotes/5.1 @@ -106,7 +106,7 @@ Vertex/Fragment program debugger GL_MESA_program_debug is an experimental extension to support interactive debugging of vertex and fragment programs. See the -docs/MESA_program_debug.spec file for details. +docs/specs/OLD/MESA_program_debug.spec file for details. The bulk of the vertex/fragment program debugger is implemented outside of Mesa. The GL_MESA_program_debug extension just has minimal 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. + + and indicates the lower-left corner of the region to copy and + and 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 + +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 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 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 is non-NULL, a global name is assigned to the image and + written to , the handle (local to the DRM file descriptor, + for use with DRM kernel modesetting API) is written to if + non-NULL and the stride (in bytes) is written to , 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 (eric@anholt.net) + +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 parameter of PixelStorei and PixelStoref + and the 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 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 ); + + 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 is valid and the operation completed + normally. GL_FALSE is returned if 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 parameter of GetObjectParameter{fi}vARB: + + DEBUG_OBJECT_MESA 0x8759 + + Accepted by the 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 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 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 , , and + implementation dependent double-quoted string, each of this + delimited by a white space. If the argument is not present, + it is meant as if it was of value 0. If the arguments and + 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 is set to a value of 0, buffer swaps are not synchro- + nized to a video frame. The 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 + 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 + 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 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 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 + . + + 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 parameter of Enable, Disable, and IsEnabled, by + the parameter of GetBooleanv, GetIntegerv, GetFloatv, and + GetDoublev, and by the parameter of TexImage3D, GetTexImage, + GetTexLevelParameteriv, GetTexLevelParameterfv, GetTexParameteriv, and + GetTexParameterfv: + + TEXTURE_1D_ARRAY_EXT 0x8C18 + TEXTURE_2D_ARRAY_EXT 0x8C1A + + Accepted by the parameter of TexImage2D, TexSubImage2D, + CopyTexImage2D, CopyTexSubImage2D, CompressedTexImage2D, + CompressedTexSubImage2D, GetTexLevelParameteriv, and + GetTexLevelParameterfv: + + TEXTURE_1D_ARRAY_EXT + PROXY_TEXTURE_1D_ARRAY_EXT 0x8C19 + + Accepted by the parameter of TexImage3D, TexSubImage3D, + CopyTexSubImage3D, CompressedTexImage3D, CompressedTexSubImage3D, + GetTexLevelParameteriv, and GetTexLevelParameterfv: + + TEXTURE_2D_ARRAY_EXT + PROXY_TEXTURE_2D_ARRAY_EXT 0x8C1B + + Accepted by the 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 parameter of TexParameterf, TexParameteri, + TexParameterfv, and TexParameteriv when the 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 parameter of TexImage3D and + CompressedTexImage3D, and by the 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 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 + "" 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 is + TEXTURE_1D_ARRAY_EXT, and 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 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 . ..." + + -- 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 set to the desired texture target and 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 + texture coordinate, clamped to the range [0, 1]. For texture lookups + from two-dimensional array texture targets, let R be the interpolated + 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) + + ::= "MESA_texture_array" + + ::= "1D" + | "2D" + | "3D" + | "CUBE" + | "RECT" + | (if program option is present) + | (if program option is present) + + ::= "ARRAY1D" + | "ARRAY2D" + + ::= "SHADOW1D" + | "SHADOW2D" + | "SHADOWRECT" + | (if program option is present) + + ::= "SHADOWARRAY1D" + | "SHADOWARRAY2D" + + + -- Add Section 3.11.4.5.4 "Texture Stack Option" + + "If a fragment program specifies the "MESA_texture_array" program + option, the 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 + are used by all texture targets. Component usage for each + 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 , 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. is an integer indicating the + layer number, and is treated identically to the parameter in + FramebufferTexture3DEXT. The error INVALID_VALUE is generated if + is negative. The error INVALID_OPERATION is generated if + is non-zero and is not the name of a three dimensional + texture or one- or two-dimensional array texture. Unlike + FramebufferTexture3D, no parameter is accepted. + + If is non-zero and the command does not result in an error, + the framebuffer attachment state corresponding to is + updated as in the other FramebufferTexture commands, except that + FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT is set to ." + + -- 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 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 will contain the number of texture layer attached to the + attachment point. Otherwise, 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 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 parameter of + TexImage1D, TexImage2D, TexImage3D, CopyTexImage1D, and CopyTexImage2D: + + RGBA_SNORM 0x8F93 + RGBA8_SNORM 0x8F97 + + Returned by the 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 + 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 and parameters of + TexImage2D and TexSubImage2D: + + YCBCR_MESA 0x8757 + + Accepted by the 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 is + MESA_YCBCR but is not MESA_YCBCR. + + INVALID_ENUM is generated by TexImage2D if is MESA_YCBCR but + is not MESA_YCBCR. + + INVALID_VALUE is generated by TexImage2D if is MESA_YCBCR and + is MESA_YCBCR and is not zero. + + INVALID_OPERATION is generated by TexSubImage2D if the internal image + format is YCBCR_MESA and 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 parameter of ReadPixels and DrawPixels: + + GL_DEPTH_STENCIL_MESA 0x8750 + + Accepted by the 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: + + 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 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 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 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 parameter of Enable, Disable, IsEnabled, + GetBooleanv, GetDoublev, GetFloatv and GetIntegerv: + + FRAGMENT_PROGRAM_CALLBACK_MESA 0x8bb1 + VERTEX_PROGRAM_CALLBACK_MESA 0x8bb4 + + Accepted by the parameter GetBooleanv, GetDoublev, + GetFloatv and GetIntegerv: + + FRAGMENT_PROGRAM_POSITION_MESA 0x8bb0 + VERTEX_PROGRAM_POSITION_MESA 0x8bb4 + + Accepted by the 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. + 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 + 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, will either be + FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which + program is currently executing and 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. + + and 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 . If 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 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 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 + 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 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 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 parameter of GetIntegerv, GetBooleanv, + GetFloatv, and GetDoublev: + + TRACE_MASK_MESA 0x8755 + + Accepted by the 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 ) + + 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. + + specifies a name or label for the trace. It is expected + that 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. + 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 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 with the texture object or display list specified + by . Logged commands which reference the named texture object or + display list will be annotated with . 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 with the address specified by or with + a range of addresses specified by through . + Any logged commands which reference or an address between + and will be annotated with . + + 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. + + 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 , , , and respectively. + Statements equivalent to the following will then be logged: + + glEnable(GL_DEPTH_TEST); (if is true) + glDisable(GL_DEPTH_TEST); (if is false) + glDepthFunc(); + glDepthMask(); + glClearDepth(); + + + 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 , , , and respectively. + The resulting trace might then look will like this: + + { + GLboolean b; + GLint i; + GLfloat f; + b = glIsEnabled(GL_DEPTH_TEST); + assert(b == ); + glGetIntegerv(GL_DEPTH_FUNC, &i); + assert(i == ); + glGetIntegerv(GL_DEPTH_MASK, &i); + assert(i == ); + glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f); + assert(f == ); + } + + +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 + Benjamin Franzke + +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 in eglCreateImageKHR + + EGL_WAYLAND_BUFFER_WL 0x31D5 + + Accepted in the 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 + diff --git a/docs/xlibdriver.html b/docs/xlibdriver.html index 6b7b02903a1..ce1ff3b132e 100644 --- a/docs/xlibdriver.html +++ b/docs/xlibdriver.html @@ -221,7 +221,7 @@ See the xdemos/glxpixmap.c file for an example of how to use this extension.

-GLX_MESA_pixmap_colormap specification +GLX_MESA_pixmap_colormap specification

@@ -250,7 +250,7 @@ just before an X window is destroyed. For example: XDestroyWindow( dpy, window );

-GLX_MESA_release_buffers specification +GLX_MESA_release_buffers specification

This extension was added in Mesa 2.0. @@ -263,7 +263,7 @@ like glXSwapBuffers() but only copies a sub-region of the window instead of the whole window.

-GLX_MESA_copy_sub_buffer specification +GLX_MESA_copy_sub_buffer specification

This extension was added in Mesa 2.6 -- cgit v1.2.3