vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions 12 Packages Projects Releases Wiki Activity

mesa-clc: vendor as full-fork recipe (path=source, patches baked)

Browse Source
This commit is contained in:
vasilito
2026-08-01 04:44:05 +03:00
parent f8e4789a2b
commit 406ee9fbeb
12522 changed files with 6035591 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/recipes/dev/mesa-clc/source/docs/ARB_color_buffer_float.txt
+4
View File
@@ -0,0 +1,4 @@
Known issues in the ARB_color_buffer_float implementation:
- Rendering to multiple render targets, some fixed-point, some floating-point, with FIXED_ONLY fragment clamping and polygon smooth enabled may write incorrect values to the fixed point buffers (depends on spec interpretation)
- For fragment programs with ARB_fog_* options, colors are clamped before fog application regardless of the fragment clamping setting (this depends on spec interpretation)
local/recipes/dev/mesa-clc/source/docs/README.UVD
+44
View File
@@ -0,0 +1,44 @@
The software may implement third party technologies (e.g. third party
libraries) that are not licensed to you by AMD and for which you may need
to obtain licenses from other parties. Unless explicitly stated otherwise,
these third party technologies are not licensed hereunder. Such third
party technologies include, but are not limited, to H.264, H.265, HEVC, MPEG-2,
MPEG-4, AVC, and VC-1.
For MPEG-2 Encoding Products ANY USE OF THIS PRODUCT IN ANY MANNER OTHER
THAN PERSONAL USE THAT COMPLIES WITH THE MPEG-2 STANDARD FOR ENCODING VIDEO
INFORMATION FOR PACKAGED MEDIA IS EXPRESSLY PROHIBITED WITHOUT A LICENSE
UNDER APPLICABLE PATENTS IN THE MPEG-2 PATENT PORTFOLIO, WHICH LICENSES IS
AVAILABLE FROM MPEG LA, LLC, 6312 S. Fiddlers Green Circle, Suite 400E,
Greenwood Village, Colorado 80111 U.S.A.
WARRANTY DISCLAIMER: THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
KIND. AMD DISCLAIMS ALL WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING
BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, THAT THE SOFTWARE WILL RUN
UNINTERRUPTED OR ERROR-FREE OR WARRANTIES ARISING FROM CUSTOM OF TRADE OR
COURSE OF USAGE. THE ENTIRE RISK ASSOCIATED WITH THE USE OF THE SOFTWARE IS
ASSUMED BY YOU. Some jurisdictions do not allow the exclusion of implied
warranties, so the above exclusion may not apply to You.
LIMITATION OF LIABILITY AND INDEMNIFICATION: AMD AND ITS LICENSORS WILL NOT,
UNDER ANY CIRCUMSTANCES BE LIABLE FOR ANY PUNITIVE, DIRECT, INCIDENTAL,
INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM USE OF THE SOFTWARE OR
THIS AGREEMENT EVEN IF AMD AND ITS LICENSORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES. In no event shall AMD's total liability to You
for all damages, losses, and causes of action (whether in contract, tort
(including negligence) or otherwise) exceed the amount of $100 USD. You agree
to defend, indemnify and hold harmless AMD and its licensors, and any of their
directors, officers, employees, affiliates or agents from and against any and
all loss, damage, liability and other expenses (including reasonable
attorneys' fees), resulting from Your use of the Software or violation of the
terms and conditions of this Agreement.
U.S. GOVERNMENT RESTRICTED RIGHTS: The Software is provided with "RESTRICTED
RIGHTS." Use, duplication, or disclosure by the Government is subject to the
restrictions as set forth in FAR 52.227-14 and DFAR252.227-7013, et seq., or
its successor. Use of the Software by the Government constitutes
acknowledgement of AMD's proprietary rights in them.
EXPORT RESTRICTIONS: The Software may be subject to export restrictions as
stated in the Software License Agreement.
local/recipes/dev/mesa-clc/source/docs/README.VCE
+43
View File
@@ -0,0 +1,43 @@
The software may implement third party technologies (e.g. third party
libraries) that are not licensed to you by AMD and for which you may need
to obtain licenses from other parties. Unless explicitly stated otherwise,
these third party technologies are not licensed hereunder. Such third
party technologies include, but are not limited, to H.264, MPEG-2, MPEG-4,
AVC, and VC-1.
For MPEG-2 Intermediate Products: ANY USE OF THIS PRODUCT IN ANY MANNER OTHER
THAN PERSONAL USE THAT COMPLIES WITH THE MPEG-2 STANDARD IS EXPRESSLY
PROHIBITED WITHOUT A LICENSE UNDER APPLICABLE PATENTS IN THE MPEG-2 PATENT
PORTFOLIO, WHICH LICENSES IS AVAILABLE FROM MPEG LA, LLC, 6312 S. Fiddlers
Green Circle, Suite 400E, Greenwood Village, Colorado 80111 U.S.A.
WARRANTY DISCLAIMER: THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
KIND. AMD DISCLAIMS ALL WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING
BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, THAT THE SOFTWARE WILL RUN
UNINTERRUPTED OR ERROR-FREE OR WARRANTIES ARISING FROM CUSTOM OF TRADE OR
COURSE OF USAGE. THE ENTIRE RISK ASSOCIATED WITH THE USE OF THE SOFTWARE IS
ASSUMED BY YOU. Some jurisdictions do not allow the exclusion of implied
warranties, so the above exclusion may not apply to You.
LIMITATION OF LIABILITY AND INDEMNIFICATION: AMD AND ITS LICENSORS WILL NOT,
UNDER ANY CIRCUMSTANCES BE LIABLE FOR ANY PUNITIVE, DIRECT, INCIDENTAL,
INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM USE OF THE SOFTWARE OR
THIS AGREEMENT EVEN IF AMD AND ITS LICENSORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES. In no event shall AMD's total liability to You
for all damages, losses, and causes of action (whether in contract, tort
(including negligence) or otherwise) exceed the amount of $100 USD. You agree
to defend, indemnify and hold harmless AMD and its licensors, and any of their
directors, officers, employees, affiliates or agents from and against any and
all loss, damage, liability and other expenses (including reasonable
attorneys' fees), resulting from Your use of the Software or violation of the
terms and conditions of this Agreement.
U.S. GOVERNMENT RESTRICTED RIGHTS: The Software is provided with "RESTRICTED
RIGHTS." Use, duplication, or disclosure by the Government is subject to the
restrictions as set forth in FAR 52.227-14 and DFAR252.227-7013, et seq., or
its successor. Use of the Software by the Government constitutes
acknowledgement of AMD's proprietary rights in them.
EXPORT RESTRICTIONS: The Software may be subject to export restrictions as
stated in the Software License Agreement.
local/recipes/dev/mesa-clc/source/docs/_extra/_redirects
+14
View File
@@ -0,0 +1,14 @@
/webmaster.html https://www.mesa3d.org/website/
/developers.html https://www.mesa3d.org/developers/
/thanks.html https://gitlab.freedesktop.org/mesa/mesa/-/blob/amber/docs/thanks.rst
/drivers/vmware-guest.html /drivers/svga3d.html 301
/gallium/drivers/freedreno.html /drivers/freedreno.html 301
/gallium/drivers/freedreno/ir3-notes.html /drivers/freedreno/ir3-notes.html 301
/gallium/drivers/llvmpipe.html /drivers/llvmpipe.html 301
/gallium/drivers/zink.html /drivers/zink.html 301
/llvmpipe.html /drivers/llvmpipe.html 301
/postprocess.html /gallium/postprocess.html 301
/versions.html /relnotes.html 301
/vmware-guest.html /drivers/vmware-guest.html 301
/shading.html /glsl.html
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/3.1
+145
View File
@@ -0,0 +1,145 @@
Mesa 3.1 release notes
PLEASE READ!!!!
New copyright
-------------
Mesa 3.1 will be distributed under an XFree86-style copyright instead
of the GNU LGPL.
New directories
---------------
All documentation files are now in the docs/ directory.
All shell scripts are now in the bin/ directory.
New library names
-----------------
Formerly, the main Mesa library was named libMesaGL.so (or libMesaGL.a)
and the GLU library was named libMesaGLU.so (or libMesaGLU.a).
Now, the main library is named libGL.so (or libGL.a) and the GLU library
is named libGLU.so (or libGLU.a).
The change allows Mesa to be more easily substituted for OpenGL.
Specifically, the linker/loader on some Unix-like systems won't
allow libMesaGL.so to be used instead of libGL.so if the application
was linked with the former.
Warning: if you have another OpenGL implementation installed on your
system (i.e. you have another OpenGL libGL.so) you'll have to be
carefull about which library (OpenGL or Mesa) you link against. Be
aware of -L linker flags and the value of the LD_LIBRARY_PATH environment
variable.
New library versioning
----------------------
Previously, the Mesa GL library was named libMesaGL.so.3.0
To better support Linux/OpenGL standards, the Mesa GL library is now
named libGL.so.1.2.030100 This indicates version 1.2 of the OpenGL spec
and Mesa implementation 3.1.0
In the long term this will allow better interoperability with other
OpenGL implementations, especially on Linux. In the short term,
OpenGL apps may have to be relinked to use the new library naming.
New makefiles
-------------
The old Makefiles found in the various directories have been renamed
to Makefile.X11 in order to prevent filename collisions with autoconfig-
generated Makefiles.
The top-level Makefile simply includes Makefile.X11
If your top-level Makefile get's overwritten/destroyed you can restore
it by copying Makefile.X11 to Makefile
New extensions
--------------
GL_EXT_stencil_wrap
Implements two new stencil operations: GL_INCR_WRAP_EXT and
GL_DECR_WRAP_EXT which allow stencil increment and decrement
without clamping.
GL_INGR_blend_func_separate
Allows specification of blend factors for RGB and Alpha independently.
(INGR = Intergraph)
GL_ARB_multitexture
Multiple simultaneous textures. (ARB = Architecture Review Board)
GL_NV_texgen_reflection
nVidia texgen extension for better reflection mapping.
GL_PGI_misc_hints
Assorted transformation hints.
GL_EXT_compiled_vertex_array
Compiled vertex arrays.
GL_EXT_clip_volume_hint
Allows one to disable clip volume (frustum) testing.
Extensions removed
------------------
GL_EXT_multitexture - obsolete in favor of GL_ARB_multitexture
Config file
-----------
By default, /etc/mesa.conf will be read when Mesa starts. This
file controls default hints, enable/disable of extensions, and
more. See the CONFIG file for documentation.
Optimizations
-------------
Keith Whitwell has contributed significant optimizations to Mesa's
vertex transformation code. Basically, the whole transformation
stage of Mesa has been rewritten.
It's impossible to give a speedup factor. You'll just have to
try your app and see how it performs.
Device Driver changes
---------------------
A bunch of new device driver functions have been added. See src/dd.h
Keith Harrison contributed many of them. I've been planning on adding
a bunch of functions like these to make writing hardware drivers easier.
More such function will probably be added in the near future.
Miscellaneous
-------------
util/glstate.c has some handy functions for debugging. Basically, it
offers a simple function for printing GL state variables. It's not
finished yet. There's a LOT more GLenum records to be added (see the
code). Anyone want to help?
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/3.2
+11
View File
@@ -0,0 +1,11 @@
Mesa 3.2 release notes
PLEASE READ!!!!
Mesa 3.2 is a stabilization of the Mesa 3.1 release. No new features
have been added. For a list of bug fixes please read the VERSIONS file.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/3.2.1
+31
View File
@@ -0,0 +1,31 @@
Mesa 3.2.1 release notes
PLEASE READ!!!!
The Mesa 3.2.1 release mainly just fixes bugs since the 3.2 release.
See the VERSIONS file for the exact list.
GLU Polygon Tessellator
-----------------------
The GLU tessellator has been reverted back to the version included
with Mesa 3.0 since it's more stable. The Mesa 3.1/3.2 tessellator
implemented the GLU 1.3 specification but suffered from a number of
bugs.
Mesa implements GLU 1.1.
Ideally, people should use the GLU 1.3 library included in SGI's
OpenGL Sample Implementation (SI) available from
http://oss.sgi.com/projects/ogl-sample/
People are working to make easy-to-install Linux RPMs of the
GLU library.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/3.3
+270
View File
@@ -0,0 +1,270 @@
Mesa 3.3 release notes
July 21, 2000
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.3) designate new developmental releases.
Even numbered versions (such as 3.2.1) designate stable releases.
Mesa 3.3 has a undergone many internal changes since version 3.2
and features a lot of new extensions. 3.3 is expected to be pretty
stable, but perhaps not as stable as 3.2 which has been used by
thousands of users over the past months.
Everyone is encouraged to try Mesa 3.3. Bugs should be reported to
the Mesa bug database on www.sourceforge.net.
Header file / GLenum changes
----------------------------
The gl.h and glu.h headers now use #defines to define all GL_* tokens
instead of C-language enums. This change improves Mesa/OpenGL
interoperability.
New API dispatch code
---------------------
The core Mesa gl* functions are now implemented with a new dispatch
(jump table) which will allow simultaneous direct/indirect rendering.
The code is found in the glapi*.[ch] files.
Of interest: the actual "glFooBar" functions are generated with
templatized code defined in glapitemp.h and included by glapi.c
The glapitemp.h template should be reusable for all sorts of OpenGL
projects.
The new dispatch code has also optimized with x86 assembly code.
This optimization eliminates copying the function arguments during
dispatch.
New thread support
------------------
Thread support in Mesa has been rewritten. The glthread.[ch] files
replace mthreads.[ch]. Thread safety is always enabled (on platforms
which support threads, that is). There is virtually no performance
penalty for typical single-thread applications. See the glapi.c
file for details.
The Xlib driver (XMesa) is now thread-safe as well. Be sure to
call XInitThreads() in your app first. See the xdemos/glthreads.c
demo for an example.
Make configuration changes
--------------------------
If you use the old-style (non GNU automake) method to build Mesa note
that several of the configuration names have changed:
Old name New name
------------- ----------------
linux-elf linux
linux linux-static
linux-386-elf linux-386
linux-386 linux-386-static
etc.
New extensions
--------------
GL_ARB_transpose_matrix
Adds glLoadTransposeMatrixARB() and glMultTransposeMatrixARB()
functions.
GL_ARB_texture_cube_map
For cube-based reflection mapping.
GL_EXT_texture_add_env
Adds GL_ADD texture environment mode.
See http://www.berkelium.com/OpenGL/EXT/texture_env_add.txt
GL_EXT_texture_lod_bias
Allows mipmapped texture blurring and sharpening.
GLX_EXT_visual_rating extension
This extension has no effect in stand-alone Mesa (used for DRI).
GL_HP_occlusion_test
Used for bounding box occlusion testing (see demos/occlude.c).
GL_SGIX_pixel_texture / GL_SGIS_pixel_texture
Lets glDraw/CopyPixels draw a texture coordinate image.
GL_SGI_color_matrix
Adds a color matrix and another set of scale and bias parameters
to the glDraw/CopyPixels paths.
GL_SGI_color_table
Adds additional color tables to the glDraw/Read/CopyPixels paths.
GL_EXT_histogram
Compute histograms for glDraw/Read/CopyPixels.
GL_EXT_blend_func_separate
This is the same as GL_INGR_blend_func_separate.
GL_ARB_texture_cube_mapping
6-face cube mapping, nicer than sphere mapping
GL_EXT_texture_env_combine
For advanced texture environment effects.
Documentation for all these functions can be found at
http://oss.sgi.com/projects/ogl-sample/registry/
GLX_SGI_make_current_read functionality
---------------------------------------
The functionality of this extension is needed for GLX 1.3 (and required
for the Linux/OpenGL standards base).
Implementing this function required a **DEVICE DRIVER CHANGE**.
The old SetBuffer() function has been replaced by SetReadBuffer() and
SetDrawBuffer(). All device drivers will have to be updated because
of this change.
The new function, glXMakeContextCurrent(), in GLX 1.3 now works in Mesa.
The xdemos/wincopy.c program demonstrates it.
Image-related code changes
--------------------------
The imaging path code used by glDrawPixels, glTexImage[123]D,
glTexSubImage[123], etc has been rewritten. It's now faster,
uses less memory and has several bug fixes. This work was
actually started in Mesa 3.1 with the glTexImage paths but has now
been carried over to glDrawPixels as well.
Device driver interface changes
-------------------------------
Added new functions for hardware stencil buffer support:
WriteStencilSpan
ReadStencilSpan
WriteStencilPixels
ReadStencilPixels
Removed old depth buffer functions:
AllocDepthBuffer
DepthTestSpan
DepthTestPixels
ReadDepthSpanFloat
ReadDepthSpanInt
Added new depth buffer functions:
WriteDepthSpan
ReadDepthSpan
WriteDepthPixels
ReadDepthPixels
These functions always read/write 32-bit GLuints. This will allow
drivers to have anywhere from 0 to 32-bit Z buffers without
recompiling for 16 vs 32 bits as was previously needed.
New texture image functions
The entire interface for texture image specification has been updated.
With the new functions, it's optional for Mesa to keep an internal copy
of all textures. Texture download should be a lot faster when the extra
copy isn't made.
Misc changes
TexEnv now takes a target argument
Removed UseGlobalTexturePalette (use Enable function instead)
Also added
ReadPixels
CopyPixels
The SetBufffer function has been replaced by SetDrawBuffer and
SetReadBuffer functions. This lets core Mesa independently
specify which buffer is to be used for reading and which for
drawing.
The Clear function's mask parameter has changed. Instead of
mask being the flags specified by the user to glClear, the
mask is now a bitmask of the DD_*_BIT flags in dd.h. Now
multiple color buffers can be specified for clearing (ala
glDrawBuffers). The driver's Clear function must also
check the glColorMask glIndexMask, and glStencilMask settings
and do the right thing. See the X/Mesa, OS/Mesa, or FX/Mesa
drivers for examples.
The depth buffer changes shouldn't be hard to make for existing
drivers. In fact, it should simply the code. Be careful with
the depthBits value passed to gl_create_context(). 1 is a bad
value! It should normally be 0, 16, 24, or 32.
gl_create_framebuffer() takes new arguments which explicitly tell
core Mesa which ancillary buffers (depth, stencil, accum, alpha)
should be implemented in software. Mesa hardware drivers should
carefully set these flags depending on which buffers are in the
graphics card.
Internal constants
------------------
Point and line size range and granularity limits are now stored
in the gl_constants struct, which is the Const member of GLcontext.
The limits are initialized from values in config.h but may be
overridden by device drivers to reflect the limits of that driver's
hardware.
Also added constants for NumAuxBuffers and SubPixelBits.
OpenGL Conformance
------------------
Mesa now passes all the OpenGL 1.1 conformance tests, except for
antialiased lines. AA lines fail on some, but not all, the tests.
In order to fix the remaining failures, a new AA line algorithm will
be needed (which computes coverage values for end-point fragments).
This will be done for Mesa 3.5/3.6.
OpenGL 1.2 GL_ARB_imaging subset
--------------------------------
Mesa 3.3 implements all the features of GL_ARB_imaging except for
image convolution. This will (hopefully) be done for Mesa 3.5/3.6.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/3.4
+21
View File
@@ -0,0 +1,21 @@
Mesa 3.4 release notes
November 3, 2000
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.3) designate new developmental releases.
Even numbered versions (such as 3.4) designate stable releases.
Mesa 3.4 simply fixes bugs found in the Mesa 3.3 release. For details,
see the VERSIONS file.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/3.4.1
+21
View File
@@ -0,0 +1,21 @@
Mesa 3.4.1 release notes
February 9, 2001
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.3) designate new developmental releases.
Even numbered versions (such as 3.4) designate stable releases.
Mesa 3.4.1 is a maintenance release that simply fixes bugs found since
the Mesa 3.4 release. For details, see the VERSIONS file.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/3.4.2
+21
View File
@@ -0,0 +1,21 @@
Mesa 3.4.2 release notes
May 17, 2001
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.3) designate new developmental releases.
Even numbered versions (such as 3.4) designate stable releases.
Mesa 3.4.2 is a maintenance release that simply fixes bugs found since
the Mesa 3.4.1 release. For details, see the VERSIONS file.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/3.5
+227
View File
@@ -0,0 +1,227 @@
Mesa 3.5 release notes
June 21, 2001
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.5) designate new developmental releases.
Even numbered versions (such as 3.4) designate stable releases.
The biggest change in Mesa 3.5 is a complete overhaul of the source
code in order to make it more modular. This was driven by the DRI
hardware drivers. It simplifies the DRI drivers and opens the door
to hardware transform/clip/lighting (TCL). Keith Whitwell can take
the credit for that.
Driver Support
--------------
The device driver interface in Mesa 3.5 has changed a lot since Mesa 3.4
Not all of the older Mesa drivers have been updated. Here's the status:
Driver Status
---------------------- -----------
XMesa (Xlib) updated
OSMesa (off-screen) updated
FX (3dfx Voodoo1/2) updated
SVGA updated
GGI not updated
Windows/Win32 not updated
DOS/DJGPP not updated
BeOS not updated
Allegro not updated
D3D not updated
DOS not updated
We're looking for volunteers to update the remaining drivers. Please
post to the Mesa3d-dev mailing list if you can help.
GLU 1.3
-------
Mesa 3.5 includes the SGI Sample Implementation (SI) GLU library.
This version of GLU supports the GLU 1.3 specification. The old
Mesa GLU library implemented the 1.1 specification. The SI GLU
library should work much better.
You'll need a C++ compiler to compile the SI GLU library. This may
be a problem on some systems.
New Extensions
--------------
GL_EXT_convolution
Adds image convolution to glRead/Copy/DrawPixels/TexImage.
GL_ARB_imaging
This is the optional imaging subset of OpenGL 1.2.
It's the GL_EXT_convolution, GL_HP_convolution_border_modes,
GL_EXT_histogram, GL_EXT_color_table, GL_EXT_color_subtable
GL_EXT_blend_color, GL_EXT_blend_minmax, GL_EXT_blend_subtract
and GL_SGI_color_matrix extensions all rolled together.
This is supported in all software renderers but not in all
hardware drivers (3dfx for example).
GL_ARB_texture_compression
This is supported in Mesa but only used by the 3dfx DRI drivers
for Voodoo4 and later.
GL_ARB_texture_env_add
This is identical to GL_EXT_texture_env_add.
GL_NV_blend_square
Adds extra blend source and dest factors which allow squaring
of color values.
GL_EXT_fog_coord
Allows specification of a per-vertex fog coordinate instead of
having fog always computed from the eye distance.
GL_EXT_secondary_color
Allows specifying the secondary (specular) color for each vertex
instead of getting it only from lighting in GL_SEPARATE_SPECULAR_COLOR
mode.
GL_ARB_texture_env_combine
Basically the same as GL_EXT_texture_env_combine
GL_ARB_texture_env_add extension
Texture addition mode.
GL_ARB_texture_env_dot3 extension
Dot product texture environment.
GL_ARB_texture_border_clamp
Adds GL_CLAMP_TO_BORDER_ARB texture wrap mode
GL_SGIX_depth_texture, GL_SGIX_shadow and GL_SGIX_shadow_ambient
Implements a shadow casting algorithm based on depth map textures
GL_SGIS_generate_mipmap
Automatically generate lower mipmap images whenever the base mipmap
image is changed with glTexImage, glCopyTexImage, etc.
libOSMesa.so
------------
libOSMesa.so is a new library which contains the OSMesa interface for
off-screen rendering. Apps which need the OSMesa interface should link
with both -lOSMesa and -lGL. This change was made so that stand-alone
Mesa works the same way as XFree86/DRI's libGL.
Device Driver Changes / Core Mesa Changes
-----------------------------------------
The ctx->Driver.LogicOp() function has been removed. It used to
be called during state update in order to determine if the driver
could do glLogicOp() operations, and if not, set the SWLogicOpEnabled
flag. Drivers should instead examine the LogicOp state themselves
and choose specialized point, line, and triangle functions appropriately,
or fall back to software rendering. The Xlib driver was the only driver
to use this function. And since the Xlib driver no longer draws
points, lines or triangles using Xlib, the LogicOp function isn't needed.
The ctx->Driver.Dither() function has been removed. Drivers should
detect dither enable/disable via ctx->Driver.Enable() instead.
The ctx->Driver.IndexMask() and ctx->Driver.ColorMask() functions
are now just called from glIndexMask and glColorMask like the other
GL state-changing functions. They are no longer called from inside
gl_update_state(). Also, they now return void. The change was made
mostly for sake of uniformity.
The NEW_DRVSTATE[0123] flags have been removed. They weren't being used
and are obsolete w.r.t. the way state updates are done in DRI drivers.
Removed obsolete gl_create_visual() and gl_destroy_visual().
Renamed functions (new namespace):
old new
gl_create_framebuffer _mesa_create_framebuffer
gl_destroy_framebuffer _mesa_destroy_framebuffer
gl_create_context _mesa_create_context
gl_destroy_context _mesa_destroy_context
gl_context_initialize _mesa_context_initialize
gl_copy_context _mesa_copy_context
gl_make_current _mesa_make_current
gl_make_current2 _mesa_make_current2
gl_get_current_context _mesa_get_current_context
gl_flush_vb _mesa_flush_vb
gl_warning _mesa_warning
gl_compile_error _mesa_compile_error
All the drivers have been updated, but not all of them have been
tested since I can't test some platforms (DOS, Windows, Allegro, etc).
X/Mesa Driver
-------------
The source files for the X/Mesa driver in src/X have been renamed.
The xmesa[1234].c files are gone. The new files are xm_api.c,
xm_dd.c, xm_line.c, xm_span.c and xm_tri.c.
Multitexture
------------
Eight texture units are now supported by default.
OpenGL SI related changes
-------------------------
In an effort to make Mesa's internal interfaces more like the OpenGL
SI interfaces, a number of changes have been made:
1. Importing the SI's glcore.h file which defines a number of
interface structures like __GLimports and __GLexports.
2. Renamed "struct gl_context" to "struct __GLcontextRec".
3. Added __glCoreCreateContext() and __glCoreNopDispatch() functions.
4. The GLcontext member Visual is no longer a pointer.
5. New file: imports.c to setup default import functions for Mesa.
16-bit color channels
---------------------
There's experimental support for 16-bit color channels (64-bit pixels)
in Mesa 3.5. Only the OSMesa interface can be used for 16-bit rendering.
Type "make linux-osmesa16" in the top-level directory to build the
special libOSMesa16.so library.
This hasn't been tested very thoroughly yet so please file bug reports
if you have trouble.
In the future I hope to implement support for 32-bit, floating point
color channels.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/4.0
+162
View File
@@ -0,0 +1,162 @@
Mesa 4.0 release notes
October 18, 2001
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.3) designate new developmental releases.
Even numbered versions (such as 3.4) designate stable releases.
Mesa version 4.0 signifies two things:
1. A stabilization of the 3.5 development release
2. Implementation of the OpenGL 1.3 specification
Note that the Mesa major version number is incremented with the OpenGL
minor version number:
Mesa 1.x == OpenGL 1.0
Mesa 2.x == OpenGL 1.1
Mesa 3.x == OpenGL 1.2
Mesa 4.x == OpenGL 1.3
New Features
------------
Mesa 3.5 already had all the new features of OpenGL 1.3, implemented as
extensions. These extensions were simply promoted to standard features:
GL_ARB_multisample
GL_ARB_multitexture
GL_ARB_texture_border_clamp
GL_ARB_texture_compression
GL_ARB_texture_cube_map
GL_ARB_texture_env_add
GL_ARB_texture_env_combine
GL_ARB_texture_env_dot3
GL_ARB_transpose_matrix
In Mesa 4.0 the functions defined by these extensions are now available
without the "ARB" suffix. For example, glLoadTransposeMatrixf() is now
a standard API function. The new functions in OpenGL 1.3 and Mesa 4.0 are:
glActiveTexture
glClientActiveTexture
glCompressedTexImage1D
glCompressedTexImage2D
glCompressedTexImage3D
glCompressedTexSubImage1D
glCompressedTexSubImage2D
glCompressedTexSubImage3D
glGetCompressedTexImage
glLoadTransposeMatrixd
glLoadTransposeMatrixf
glMultiTexCoord1d
glMultiTexCoord1dv
glMultiTexCoord1f
glMultiTexCoord1fv
glMultiTexCoord1i
glMultiTexCoord1iv
glMultiTexCoord1s
glMultiTexCoord1sv
glMultiTexCoord2d
glMultiTexCoord2dv
glMultiTexCoord2f
glMultiTexCoord2fv
glMultiTexCoord2i
glMultiTexCoord2iv
glMultiTexCoord2s
glMultiTexCoord2sv
glMultiTexCoord3d
glMultiTexCoord3dv
glMultiTexCoord3f
glMultiTexCoord3fv
glMultiTexCoord3i
glMultiTexCoord3iv
glMultiTexCoord3s
glMultiTexCoord3sv
glMultiTexCoord4d
glMultiTexCoord4dv
glMultiTexCoord4f
glMultiTexCoord4fv
glMultiTexCoord4i
glMultiTexCoord4iv
glMultiTexCoord4s
glMultiTexCoord4sv
glMultTransposeMatrixd
glMultTransposeMatrixf
glSampleCoverage
glSamplePass
GLX 1.4 is the companion to OpenGL 1.3. The only new features in GLX 1.4
are support for multisampling and the GLX_ARB_get_proc_address extension.
glXGetProcAddress() is the only new function in GLX 1.4.
Multisample and Texture Compression
-----------------------------------
The OpenGL 1.3 specification allows the multisample and texture compression
features to essentially be no-ops. For example, if you query for multisample
support you'll find none, but the API functions work.
Similarly, texture compression is not implemented by any of the software
drivers but you can specify a generic compressed texture format (like
GL_COMPRESSED_RGBA) to glTexImage2D and it'll be accepted.
Device Drivers
--------------
Mesa advertises itself as either OpenGL 1.2 or OpenGL 1.3 depending on the
device driver. If the driver enables all the ARB extensions which are part
of OpenGL 1.3 then glGetString(GL_VERSION) will return "1.3". Otherwise,
it'll return "1.2".
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of the drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.3
OSMesa (off-screen) implements OpenGL 1.3
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.3
GGI needs updating
DOS/DJGPP needs updating
BeOS needs updating
Allegro needs updating
D3D needs updating
DOS needs updating
Special thanks go to Karl Schultz for updating the Windows driver.
The XFree86/DRI drivers have not yet been updated to use Mesa 4.0 as of
September 2001, but that should happen eventually.
Other Changes
-------------
See the VERSIONS file for more details about bug fixes, etc. in Mesa 4.0.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/4.0.1
+21
View File
@@ -0,0 +1,21 @@
Mesa 4.0.1 release notes
December 17, 2001
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.3) designate new developmental releases.
Even numbered versions (such as 3.4) designate stable releases.
Mesa 4.0.1 only contains bug fixes since version 4.0.
See the docs/VERSIONS file for the list of bug fixes.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/4.0.2
+49
View File
@@ -0,0 +1,49 @@
Mesa 4.0.2 release notes
March 25, 2002
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.3) designate new developmental releases.
Even numbered versions (such as 3.4) designate stable releases.
Mesa 4.0.2 only contains bug fixes and a new DOS driver since version 4.0.1.
See the docs/VERSIONS file for the list of bug fixes.
Device Drivers
--------------
Mesa advertises itself as either OpenGL 1.2 or OpenGL 1.3 depending on the
device driver. If the driver enables all the ARB extensions which are part
of OpenGL 1.3 then glGetString(GL_VERSION) will return "1.3". Otherwise,
it'll return "1.2".
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of the drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.3
OSMesa (off-screen) implements OpenGL 1.3
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.3
DOS/DJGPP implements OpenGL 1.3 (new in Mesa 4.0.2)
GGI needs updating
BeOS needs updating
Allegro needs updating
D3D needs updating
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/4.0.3
+51
View File
@@ -0,0 +1,51 @@
Mesa 4.0.3 release notes
June 25, 2002
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 3.3) designate new developmental releases.
Even numbered versions (such as 3.4) designate stable releases.
Mesa 4.0.3 basically just contains bug fixes version 4.0.2.
See the docs/VERSIONS file for the list of bug fixes.
The GGI driver has been updated, thanks to Filip Spacek.
Device Drivers
--------------
Mesa advertises itself as either OpenGL 1.2 or OpenGL 1.3 depending on the
device driver. If the driver enables all the ARB extensions which are part
of OpenGL 1.3 then glGetString(GL_VERSION) will return "1.3". Otherwise,
it'll return "1.2".
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of the drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.3
OSMesa (off-screen) implements OpenGL 1.3
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.3
DOS/DJGPP implements OpenGL 1.3 (new in Mesa 4.0.2)
GGI implements OpenGL 1.3
BeOS needs updating
Allegro needs updating
D3D needs updating
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/4.1
+307
View File
@@ -0,0 +1,307 @@
Mesa 4.1 release notes
October 29, 2002
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Even numbered versions (such as 4.0) designate stable releases.
Odd numbered versions (such as 4.1) designate new developmental releases.
New Features in Mesa 4.1
------------------------
New extensions. Docs at http://oss.sgi.com/projects/ogl-sample/registry/
GL_NV_vertex_program
NVIDIA's vertex programming extension
GL_NV_vertex_program1_1
A few features built on top of GL_NV_vertex_program
GL_ARB_window_pos
This is the ARB-approved version of GL_MESA_window_pos
GL_ARB_depth_texture
This is the ARB-approved version of GL_SGIX_depth_texture.
It allows depth (Z buffer) data to be stored in textures.
This is used by GL_ARB_shadow
GL_ARB_shadow
Shadow mapping with depth textures.
This is the ARB-approved version of GL_SGIX_shadow.
GL_ARB_shadow_ambient
Allows one to specify the luminance of shadowed pixels.
This is the ARB-approved version of GL_SGIX_shadow_ambient.
GL_EXT_shadow_funcs
Extends the set of GL_ARB_shadow texture comparision functions to
include all eight of standard OpenGL dept-test functions.
GL_ARB_point_parameters
This is basically the same as GL_EXT_point_parameters.
GL_ARB_texture_env_crossbar
Allows any texture combine stage to reference any texture source unit.
GL_NV_point_sprite
For rendering points as textured quads. Useful for particle effects.
GL_NV_texture_rectangle (new in 4.0.4 actually)
Allows one to use textures with sizes that are not powers of two.
Note that mipmapping and several texture wrap modes are not allowed.
GL_EXT_multi_draw_arrays
Allows arrays of vertex arrays to be rendered with one call.
GL_EXT_stencil_two_side
Separate stencil modes for front and back-facing polygons.
GLX_SGIX_fbconfig & GLX_SGIX_pbuffer
Off-screen rendering support.
GL_ATI_texture_mirror_once
Adds two new texture wrap modes: GL_MIRROR_CLAMP_ATI and
GL_MIRROR_CLAMP_TO_EDGE_ATI.
Device Driver Status
--------------------
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of these drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.3
OSMesa (off-screen) implements OpenGL 1.3
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.3
DOS/DJGPP implements OpenGL 1.3
GGI implements OpenGL 1.3
BeOS needs updating (underway)
Allegro needs updating
D3D needs updating
DOS needs updating
New features in GLUT
--------------------
1. Frames per second printing
GLUT now looks for an environment variable called "GLUT_FPS". If it's
set, GLUT will print out a frames/second statistic to stderr when
glutSwapBuffers() is called. By default, frames/second is computed
and displayed once every 5 seconds. You can specify a different
interval (in milliseconds) when you set the env var. For example
'export GLUT_FPS=1000' or 'setenv GLUT_FPS 1000' will set the interval
to one second.
NOTE: the demo or application must call the glutInit() function for
this to work. Otherwise, the env var will be ignored.
Finally, this feature may not be reliable in multi-window programs.
2. glutGetProcAddress() function
The new function:
void *glutGetProcAddress(const char *procName)
is a wrapper for glXGetProcAddressARB() and wglGetProcAddress(). It
lets you dynamically get the address of an OpenGL function at runtime.
The GLUT_API_VERSION has been bumped to 5, but I haven't bumped the
GLUT version number from 3.7 since that's probably Mark Kilgard's role.
This function should probably also be able to return the address of
GLUT functions themselves, but it doesn't do that yet.
XXX Things To Do Yet XXXX
-------------------------
isosurf with vertex program exhibits some missing triangles (probably
when recycling the vertex buffer for long prims).
Porting Info
------------
If you're porting a DRI or other driver from Mesa 4.0.x to Mesa 4.1 here
are some things to change:
1. ctx->Texture._ReallyEnabled is obsolete.
Since there are now 5 texture targets (1D, 2D, 3D, cube and rect) that
left room for only 6 units (6*5 < 32) in this field.
This field is being replaced by ctx->Texture._EnabledUnits which has one
bit per texture unit. If the bit k of _EnabledUnits is set, that means
ctx->Texture.Unit[k]._ReallyEnabled is non-zero. You'll have to look at
ctx->Texture.Unit[k]._ReallyEnabled to learn if the 1D, 2D, 3D, cube or
rect texture is enabled for unit k.
This also means that the constants TEXTURE1_*, TEXTURE2_*, etc are
obsolete.
The tokens TEXTURE0_* have been replaced as well (since there's no
significance to the "0" part:
old token new token
TEXTURE0_1D TEXTURE_1D_BIT
TEXTURE0_2D TEXTURE_2D_BIT
TEXTURE0_3D TEXTURE_3D_BIT
TEXTURE0_CUBE TEXTURE_CUBE_BIT
<none> TEXTURE_RECT_BIT
These tokens are only used for the ctx->Texture.Unit[i].Enabled and
ctx->Texture.Unit[i]._ReallyEnabled fields. Exactly 0 or 1 bits will
be set in _ReallyEnabled at any time!
Q: "What's the purpose of Unit[i].Enabled vs Unit[i]._ReallyEnabled?"
A: The user can enable GL_TEXTURE_1D, GL_TEXTURE_2D, etc for any
texure unit all at once (an unusual thing to do).
OpenGL defines priorities that basically say GL_TEXTURE_2D has
higher priority than GL_TEXTURE_1D, etc. Also, just because a
texture target is enabled by the user doesn't mean we'll actually
use that texture! If a texture object is incomplete (missing mip-
map levels, etc) it's as if texturing is disabled for that target.
The _ReallyEnabled field will have a bit set ONLY if the texture
target is enabled and complete. This spares the driver writer from
examining a _lot_ of GL state to determine which texture target is
to be used.
2. Tnl tokens changes
During the implementation of GL_NV_vertex_program some of the vertex
buffer code was changed. Specifically, the VERT_* bits defined in
tnl/t_context.h have been renamed to better match the conventions of
GL_NV_vertex_program. The old names are still present but obsolete.
Drivers should use the newer names.
For example: VERT_RGBA is now VERT_BIT_COLOR0 and
VERT_SPEC_RGB is now VERT_BIT_COLOR1.
3. Read/Draw Buffer changes
The business of setting the current read/draw buffers in Mesa 4.0.x
was complicated. It's much simpler now in Mesa 4.1.
Here are the changes:
- Renamed ctx->Color.DrawDestMask to ctx->Color._DrawDestMask
- Removed ctx->Color.DriverDrawBuffer
- Removed ctx->Pixel.DriverReadBuffer
- Removed ctx->Color.MultiDrawBuffer
- Removed ctx->Driver.SetDrawBuffer()
- Removed swrast->Driver.SetReadBuffer().
- Added ctx->Color._DrawDestMask - a bitmask of FRONT/BACK_LEFT/RIGHT_BIT
values to indicate the current draw buffers.
- Added ctx->Pixel._ReadSrcMask to indicate the source for pixel reading.
The value is _one_ of the FRONT/BACK_LEFT/RIGHT_BIT values.
- Added ctx->Driver.DrawBuffer() and ctx->Driver.ReadBuffer().
These functions exactly correspond to glDrawBuffer and glReadBuffer calls.
Many drivers will set ctx->Driver.DrawBuffer = _swrast_DrawBuffer and
leave ctx->Draw.ReadBuffer NULL.
DRI drivers should implement their own function for ctx->Driver.DrawBuffer
and use it to set the current hardware drawing buffer. You'll probably
also want to check for GL_FRONT_AND_BACK mode and fall back to software.
Call _swrast_DrawBuffer() too, to update the swrast state.
- Added swrast->Driver.SetBuffer().
This function should be implemented by all device drivers that use swrast.
Mesa will call it to specify the buffer to use for span reading AND
writing and point/line/triangle rendering.
There should be no confusion between current read or draw buffer anymore.
- Added swrast->CurrentBuffer to indicate which color buffer to read/draw.
Will be FRONT_LEFT_BIT, BACK_LEFT_BIT, FRONT_RIGHT_BIT or BACK_RIGHT_BIT.
This value is usually passed to swrast->Driver.SetBuffer().
4. _mesa_create_context() changes. This function now takes a pointer to
a __GLimports object. The __GLimports structure contains function
pointers to system functions like fprintf(), malloc(), etc.
The _mesa_init_default_imports() function can be used to initialize
a __GLimports object. Most device drivers (like the DRI drivers)
should use this.
5. In tnl's struct vertex_buffer, the field "ProjectedClipCoords"
has been replaced by "NdcPtr" to better match the OpenGL spec's
terminology.
6. Since GL_EXT_stencil_two_side has been implemented, many of the
ctx->Stencil fields are now 2-element arrays. For example,
"GLenum Ref" is now "GLenum Ref[2]" The [0] elements are the front-face
values and the [1] elements are the back-face values.
ctx->Stencil.ActiveFace is 0 or 1 to indicate the current face for
the glStencilOp/Func/Mask() functions.
ctx->Stencil.TestTwoSide controls whether or not 1 or 2-sided stenciling
is enabled.
7. Removed ctx->Polygon._OffsetAny. Removed ctx->Polygon.OffsetMRD.
8. GLfloat / GLchan changes:
- Changed ctx->Driver.ClearColor() to take GLfloat[4] instead of GLchan[4].
ctx->Color.ClearColor is now GLfloat[4] too.
- Changed ctx->Driver.AlphaRef() to take GLfloat instead of GLchan.
- ctx->Color.AlphaRef is now GLfloat.
- texObj->BorderColor is now GLfloat[4]. texObj->_BorderChan is GLchan[4].
This is part of an effort to remove all GLchan types from core Mesa so
that someday we can support 8, 16 and 32-bit color channels dynamically
at runtime, instead of at compile-time.
9. GLboolean ctx->Tranform.ClipEnabled[MAX_CLIP_PLANES] has been replaced
by GLuint ctx->Transform.ClipPlanesEnabled. The later is a bitfield.
10. There's a new matrix_stack type in mtypes.h used for the Modelview,
Projection, Color and Texcoord matrix stacks.
11. The ctx->Current.* fields have changed a lot. Now, there's a
ctx->Current.Attrib[] array for all vertex attributes which matches
the NV vertex program conventions.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/5.0
+84
View File
@@ -0,0 +1,84 @@
Mesa 5.0 release notes
November 13, 2002
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Even-numbered versions (such as 5.0) designate stable releases.
Odd-numbered versions (such as 4.1) designate new developmental releases.
Mesa 5.0 is basically just a stabilization of Mesa 4.1. To see a list of
bug fixes, etc. see the VERSIONS file.
New Features in Mesa 5.0
------------------------
Mesa 5.0 supports OpenGL 1.4. Note Mesa's versioning convention:
OpenGL Version Mesa Version
------------------------------
1.0 1.x
1.1 2.x
1.2 3.x
1.3 4.x
1.4 5.x
OpenGL 1.4 (and Mesa 5.0) incorporates the following OpenGL extensions as
standard features:
GL_ARB_depth_texture
GL_ARB_shadow
GL_ARB_texture_env_crossbar
GL_ARB_texture_mirror_repeat
GL_ARB_window_pos
GL_EXT_blend_color
GL_EXT_blend_func_separate
GL_EXT_blend_logic_op
GL_EXT_blend_minmax
GL_EXT_blend_subtract
GL_EXT_fog_coord
GL_EXT_multi_draw_arrays
GL_EXT_point_parameters
GL_EXT_secondary_color
GL_EXT_stencil_wrap
GL_SGIS_generate_mipmap
Device Driver Status
--------------------
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of these drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.4
OSMesa (off-screen) implements OpenGL 1.4
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.4
DOS/DJGPP implements OpenGL 1.3
GGI implements OpenGL 1.3
DOS implements OpenGL 1.4
BeOS needs updating (underway)
Allegro needs updating
D3D needs updating
Note: supporting OpenGL 1.4 (vs. 1.3 or 1.2) usually only requires that the
driver call the _mesa_enable_1_4_extensions() function.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/5.0.1
+45
View File
@@ -0,0 +1,45 @@
Mesa 5.0.1 release notes
March 30, 2003
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Even-numbered versions (such as 5.0.x) designate stable releases.
Odd-numbered versions (such as 4.1.x) designate new developmental releases.
Mesa 5.0.1 just fixes bugs found since the 5.0 release. See the VERSIONS
file for details.
Device Driver Status
--------------------
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of these drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.4
OSMesa (off-screen) implements OpenGL 1.4
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.4
DJGPP implements OpenGL 1.4
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.4
Allegro needs updating
D3D needs updating
Note: supporting OpenGL 1.4 (vs. 1.3 or 1.2) usually only requires that the
driver call the _mesa_enable_1_4_extensions() function.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/5.0.2
+45
View File
@@ -0,0 +1,45 @@
Mesa 5.0.2 release notes
September 5, 2003
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Even-numbered versions (such as 5.0.x) designate stable releases.
Odd-numbered versions (such as 4.1.x) designate new developmental releases.
Mesa 5.0.2 just fixes bugs found since the 5.0.1 release. See the VERSIONS
file for details.
Device Driver Status
--------------------
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of these drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.4
OSMesa (off-screen) implements OpenGL 1.4
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.4
DJGPP implements OpenGL 1.4
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.4
Allegro needs updating
D3D needs updating
Note: supporting OpenGL 1.4 (vs. 1.3 or 1.2) usually only requires that the
driver call the _mesa_enable_1_4_extensions() function.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/5.1
+279
View File
@@ -0,0 +1,279 @@
Mesa 5.1 release notes
December 17, 2003
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Even-numbered versions (such as 5.0) designate stable releases.
Odd-numbered versions (such as 5.1) designate new developmental releases.
Bug fixes
---------
See the VERSIONS file for a list of bugs fixed in this release.
New Features in Mesa 5.1
------------------------
GL_ARB_vertex_program / GL_ARB_fragment_program
Michal Krol and Karl Rasche implemented these extensions. Thanks!
Be aware that there may be some rough edges and lurking bugs.
GL_ATI_texture_env_combine3 extension
This adds a few new texture combine modes.
Contributed by Ian Romanick.
GL_SGI_texture_color_table
Adds a color table lookup to the RGBA texture path. There's a separate
color table for each texture unit.
Contributed by Eric Plante.
GL_NV_fragment_program
NVIDIA's fragment-level programming feature.
Possible lurking bugs:
- the DDX and DDY commands aren't fully tested
- there may be bugs in the parser
- the TEX and TXP instructions both do perspective correction
- the pack/unpack instructions may not be correct
GL_EXT_depth_bounds_test
This extension adds a scissor-like test for the Z axis. It's used to
optimize stencil-volume shadow algorithms.
GL_NV_light_max_exponent
Lifts the 128 limit for max light exponent.
GL_EXT_texture_rectangle
Identical to GL_NV_texture_rectangle
GL_ARB_occlusion_query
Useful for visibility-based culling.
GL_ARB_texture_non_power_of_two
Removes the restriction that texture dimensions must be powers of two.
GL_ARB_vertex_buffer_object
Allows server-side vertex arrays, optimized host/card data transfers, etc.
GL_ARB_point_sprite
ARB-approved version of GL_NV_point_sprite. Basically allows textures
to be applied to points.
GL_IBM_multimode_draw_arrays
Allows multiple vertex arrays to be drawn with one call, including arrays
of different types of primitives.
GL_SUN_multi_draw_arrays
An alias for GL_EXT_multi_draw_arrays, standard in OpenGL 1.4.
Faster glDrawPixels / glCopyPixels in X11 driver
If your X screen is 32bpp, glDrawPixels to the front color buffer will
be accelerated (via XPutImage()) if the image format is GL_BGRA and the
type is GL_UNSIGNED_BYTE. No raster operations, such as depth test,
blend, fog, etc. can be enabled.
If your X screen is 16bpp, glDrawPixels to the front color buffer will
be accelerated (via XPutImage()) if the image format is GL_RGB and the
type is GL_UNSIGNED_SHORT_5_6_5. No raster operations, such as depth
test, blend, fog, etc. can be enabled.
glCopyPixels() calls for the front color buffer will be accelerated
(via XCopyArea()) if no raster operations, such as depth test, blend,
fog, pixel zoom, etc. are enabled.
The speed-up over typical software rendering is a factor of 10 for
glDrawPixels and 100 for glCopyPixels.
With the addition of GL_ARB_occlusion_query, GL_ARB_vertex_buffer_object,
GL_ARB_texture_non_power_of_two and GL_EXT_shadow_funcs, Mesa 5.1 supports
all the new features of OpenGL 1.5. Mesa 6.0 (the next stable release)
will advertise GL_VERSION = "1.5".
Vertex/Fragment program debugger
--------------------------------
GL_MESA_program_debug is an experimental extension to support
interactive debugging of vertex and fragment programs. See the
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
hooks for stopping running programs and inspecting programs.
The progs/tests/debugger.c (only in CVS) program is an example of how
the extension can be used. Presently, the debugger code and demo code
is in the same file. Eventually the debugger code should be moved
into a reusable module.
As it is now, the demo lets you set breakpoings in vertex/fragment
programs, single step, and print intermediate register values. It's
basically just a proof of concept.
Directory tree reorganization
-----------------------------
The directory structure for Mesa has been overhauled to improve its layout.
All source code for Mesa, GLU, GLUT, etc is now under the src/ directory
in appropriate subdirectories.
The Mesa source code and drivers has been reorganized under src/mesa/.
All demonstration programs and tests are now in subdirectories under progs/.
Build System Changes
--------------------
The GNU automake/autoconf support has been removed. As it was, it seldom
worked on anything but Linux. The Mesa developers aren't big fans of
automake/autoconf/libtool and didn't have the time to maintain it.
If someone wants to contribute new automake/autoconf support (and is
willing to maintain it), it may be re-incorporated into Mesa, subject
to some requirements.
The "old style" makefile system has been updated:
1. Make-config has been trimmed down to fewer, modern configurations.
2. Most of the bin/mklib.* scripts have been rolled into a new "mklib"
script that works on all sorts of systems. There are probably some
bugs in it, but it's been tested on Linux, SunOS 5.8 and IRIX 6.5.
Improvements/contributes are greatly appreciated.
3. The Makefile.X11 files have been cleaned up in various ways
Source File Changes
-------------------
The mmath.[ch] files are obsolete. Their contents have been moved
into the imports.[ch] and macros.[ch] files.
The files related to vertex and fragment programming have changed.
Old files:
vpexec.[ch]
vpparse.[ch]
vpstate.[ch]
New files:
program.[ch] - generic ARB/NV program code
arbprogram.[ch] - ARB program API functions
arbfragparse.[ch] - ARB fragment program parsing
arbvertparse.[ch] - ARB vertex program parsing
arbparse.[ch] - ARB vertex/fragment parsing
arbparse_syn.h - vertex/fragment program syntax
nvprogram.[ch] - NV program API functions
nvvertprog.h - NV vertex program definitions
nvfragprog.h - NV fragment program definitions
nvvertparse.[ch] - NV vertex program parser
nvfragparse.[ch] - NV fragment program parser
nvvertexec.[ch] - NV vertex program execution
swrast/s_nvfragprog.[ch] - NV fragment program execution
The files related to per-vertex handling have changed.
Old files:
tnl/t_eval_api.c - old per-vertex code
tnl/t_imm_alloc.c - old per-vertex code
tnl/t_imm_api.c - old per-vertex code
tnl/t_imm_debug.c - old per-vertex code
tnl/t_imm_dlist.c - old per-vertex code
tnl/t_imm_elt.c - old per-vertex code
tnl/t_imm_eval.c - old per-vertex code
tnl/t_imm_exec.c - old per-vertex code
tnl/t_imm_fixup.c - old per-vertex code
tnl/t_vtx_sse.c - old per-vertex code
tnl/t_vtx_x86.c - old per-vertex code
New files:
tnl/t_save_api.c - new per-vertex code
tnl/t_save_loopback.c - new per-vertex code
tnl/t_save_playback.c - new per-vertex code
tnl/t_vtx_eval.c - old per-vertex code
Other new files:
bufferobj.[ch] - GL_ARB_vertex_buffer_object functions
version.h - defines the Mesa version info
Other removed files:
swrast/s_histogram.[ch] - moved into src/histogram.c
Other Changes
-------------
The ctx->Driver.CreateTexture function has been removed - it wasn't used.
New device driver hook functions:
NewTextureObject - used to allocate struct gl_texture_objects
NewTextureImage - used to allocate struct gl_texture_images
New ctx->Texture._EnabledCoordUnits field:
With the addition of GL_NV_fragment_program we may need to interpolate
various sets of texture coordinates even when the corresponding texture
unit is not enabled. That is, glEnable(GL_TEXTURE_xD) may never get
called but we still may have to interpolate texture coordinates across
triangles so that the fragment program will get them.
This new field indicates which sets of texture coordinates are needed.
If a bit is set in the ctx->Texture._EnabledUnits bitmask is set, the
same bit MUST be set in ctx->Texture._EnabledCoordUnits.
The ctx->_TriangleCaps field is deprecated.
Instead of testing the DD_* bits in _TriangleCaps, you should instead
directly test the relevant state variables, or use one of the helper
functions like NEED_SECONDARY_COLOR() at the bottom of context.h
While testing _TriangleCaps bits was fast, it was kludgey, and setting
the bits in the first place could be error prone.
New vertex processing code.
The code behind glBegin, glEnd, glVertex, glNormal, etc. has been
totally rewritten. It's a cleaner implementation now and should use
less memory. (Keith)
To Do
-----
Add screen-awareness to fakeglx.c
Device Driver Status
--------------------
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of these drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.4
OSMesa (off-screen) implements OpenGL 1.4
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.4
DJGPP implements OpenGL 1.4
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.4
Allegro needs updating
D3D needs updating
Note: supporting OpenGL 1.4 (vs. 1.3 or 1.2) usually only requires that the
driver call the _mesa_enable_1_4_extensions() function.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/6.0
+86
View File
@@ -0,0 +1,86 @@
Mesa 6.0 release notes
January 16, 2004
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 5.1) designate new developmental releases.
Even numbered versions (such as 6.0) designate stable releases.
Mesa version 6.0 signifies two things:
1. A stabilization of the 5.1 development release
2. Implementation of the OpenGL 1.5 specification. When you query
glGetString(GL_VERSION) "1.5" will be returned (as long as the
driver supports all the required features).
Note that the Mesa major version number is incremented with the OpenGL
minor version number:
Mesa 1.x == OpenGL 1.0
Mesa 2.x == OpenGL 1.1
Mesa 3.x == OpenGL 1.2
Mesa 4.x == OpenGL 1.3
Mesa 5.x == OpenGL 1.4
Mesa 6.x == OpenGL 1.5
New Features
------------
Mesa 5.1 already had all the new features of OpenGL 1.5, implemented as
extensions. These extensions were simply promoted to standard features:
GL_ARB_occlusion_query extension
GL_ARB_texture_non_power_of_two extension
GL_ARB_vertex_buffer_object extension
GL_EXT_shadow_funcs
Device Drivers
--------------
Mesa advertises itself as either OpenGL 1.2 or OpenGL 1.3 depending on
the device driver. For example, if the driver enables all the ARB
extensions which are part of OpenGL 1.3 then glGetString(GL_VERSION)
will return "1.3". Otherwise, it'll return "1.2".
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of the drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.5
OSMesa (off-screen) implements OpenGL 1.5
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.5
DJGPP implements OpenGL 1.5
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.5
Allegro needs updating
D3D needs updating
Other Changes
-------------
See the VERSIONS file for more details about bug fixes, etc. in Mesa 6.0.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/6.0.1
+49
View File
@@ -0,0 +1,49 @@
Mesa 6.0.1 release notes
April 2, 2003
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Even-numbered versions (such as 6.0.x) designate stable releases.
Odd-numbered versions (such as 6.1.x) designate new developmental releases.
Mesa 6.0.1 just fixes bugs found since the 6.0 release. See the VERSIONS
file for details.
Device Drivers
--------------
Mesa advertises itself as supporting OpenGL 1.2, 1.3, 1.4 or 1.5
depending on the device driver's capabilities. For example, if the
driver enables all the ARB extensions which are part of OpenGL 1.5
then glGetString(GL_VERSION) will return "1.5". Otherwise, it'll
return "1.4" or the next lower version that implements all required
functionality.
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of the drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.5
OSMesa (off-screen) implements OpenGL 1.5
FX (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.5
DJGPP implements OpenGL 1.5
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.5
Allegro needs updating
D3D needs updating
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/6.1
+111
View File
@@ -0,0 +1,111 @@
Mesa 6.1 release notes
August 18, 2004
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 6.1) designate new developmental releases.
Even numbered versions (such as 6.0) designate stable releases.
New Features
------------
Half-precision floating point (GLhalf) pixel formats are supported
in Mesa, but the feature isn't exposed yet since the ARB extension
hasn't been finalized yet.
Texture image handling
----------------------
The code which implements image conversion, pixel transfer ops, etc
for glTexImage commands has been rewritten.
Now the gl_texture_format struct has a new StoreImage function
pointer. Each texture format must implement this function. The
function is totally responsible for converting the user's texture
image into the specific format. A few helper functions makes this
relatively simple.
Overall, the code is much simpler, cleaner and easier to work with
now. Adding new texture formats is straight-forward and there's no
longer any distinction between "hardware" and "software" formats.
Finally, the code for compressed texture images has been reorganized
as well.
Removed files:
texutil.c
texutil.h
texutil_tmp.h
New files:
texcompress_s3tc.c
texcompress_fxt1.c
Driver / context changes
------------------------
The _mesa_create_context() and _mesa_initialize_context() function
parameters have changed. They now take a pointer to a struct
dd_function_table. Drivers can initialize this table by calling
_mesa_init_driver_functions(). Drivers should then plug in the special
functions they implement. In particular, the ctx->Driver.NewTextureObject
pointer _must_ be set so that the default texture objects created in
_mesa_create/initialize_context() are correctly built.
The _mesa_init_driver_functions() function allows a lot of redundant code
to be removed from the device drivers (such as initializing
ctx->Driver.Accum to point to _swrast_Accum). Adding new functions to
the dd_function_table can be done with less hassle since the pointer can
be initialized in _mesa_init_driver_functions() rather than in _all_ the
drivers.
Device Drivers
--------------
Mesa advertises itself as supporting OpenGL 1.2, 1.3, 1.4 or 1.5
depending on the device driver's capabilities. For example, if the
driver enables all the ARB extensions which are part of OpenGL 1.5
then glGetString(GL_VERSION) will return "1.5". Otherwise, it'll
return "1.4" or the next lower version that implements all required
functionality.
A number of Mesa's software drivers haven't been actively maintained for
some time. We rely on volunteers to maintain many of the drivers.
Here's the current status of all included drivers:
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.5
OSMesa (off-screen) implements OpenGL 1.5
Glide (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.5
DJGPP implements OpenGL 1.5
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.5
Allegro needs updating
D3D needs updating
Other Changes
-------------
See the VERSIONS file for more details about bug fixes, etc. in Mesa 6.1.
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/6.2
+51
View File
@@ -0,0 +1,51 @@
Mesa 6.2 release notes
October 2, 2004
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 6.1) designate new developmental releases.
Even numbered versions (such as 6.2) designate stable releases.
This release primarily just fixes bugs found in the Mesa 6.1 release.
See the VERSIONS file for details.
ToDo: PBO for polygon stipple, convolution filter, etc.
Known Issues
------------
The GL_EXT_pixel_buffer_object extension isn't fully implemented for
functions like glPolygonStipple, glConvolutionFilter, glColorTable,
etc. The important functions like glRead/DrawPixels, glTex[Sub]Image,
and glBitmap work with PBOs.
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.5
OSMesa (off-screen) implements OpenGL 1.5
Glide (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.5
DJGPP implements OpenGL 1.5
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.5
Allegro needs updating
D3D needs updating
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/6.2.1
+49
View File
@@ -0,0 +1,49 @@
Mesa 6.2.1 release notes
December 9, 2004
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 6.1) designate new developmental releases.
Even numbered versions (such as 6.2.x) designate stable releases.
This release primarily just fixes bugs found in the Mesa 6.2 release.
See the VERSIONS file for details.
Known Issues
------------
The GL_EXT_pixel_buffer_object extension isn't fully implemented for
functions like glPolygonStipple, glConvolutionFilter, glColorTable,
etc. The important functions like glRead/DrawPixels, glTex[Sub]Image,
and glBitmap work with PBOs. This has been fixed for Mesa 6.3.
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.5
OSMesa (off-screen) implements OpenGL 1.5
Glide (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.5
DJGPP implements OpenGL 1.5
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.5
Allegro needs updating
D3D needs updating
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/6.3
+114
View File
@@ -0,0 +1,114 @@
Mesa 6.3 release notes
July 20, 2005
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 6.3) designate new developmental releases.
Even numbered versions (such as 6.2) designate stable releases.
New Features
------------
GL_ARB_draw_buffers - allows a fragment program to write to a number of
separate color buffers, instead of just one.
GL_OES_read_format - allows one to query the fastest glReadPixels format
and datatype.
GL_ARB_pixel_buffer_object - buffer objects for pixel read/write functions.
GL_EXT_framebuffer_object - allows render-to-texture and provides a
window-system indepedent Pbuffer facility.
The Mesa CVS tree contains a couple tests of this extension.
DirectFB driver, contributed by Claudio Ciccani. See docs/README.directfb
for details.
Vertex/Fragment Program PRINT Instruction
-----------------------------------------
The GL_NV_vertex_program and GL_NV_fragment_program languages have been
extended with a PRINT instruction.
glDeleteTextures(), glDeletePrograms() and glDeleteBuffers() Changed
--------------------------------------------------------------------
To match the behaviour of other OpenGL implementations, glDeleteTextures,
glDeletePrograms and glDeleteBuffers have been modified so that:
* The named texture/program/buffer ID is immediately freed for re-use.
* The actual texture object, program or buffers isn't really deleted until
it is no longer bound in any rendering context (the reference count
is zero).
Previously, the texture/program/buffer ID wasn't freed until the object
was really deleted.
Note that textures, programs and buffers can be shared by several rendering
contexts so they can't be deleted until they're unbound in _all_ contexts.
GL_EXT_framebuffer_object changes
---------------------------------
Implementing this extension involved changing a lot of code (for the better).
The gl_framebuffer object now a collection of gl_renderbuffer objects.
Renderbuffers may store colors, stencil indices, or depth values. The
gl_framebuffer and gl_renderbuffer types are object-oriented in design.
All the old RGB, color index, stencil and depth-related span functions for
reading/writing pixels from/to buffers has changed. Now, all pixels are
read/written through a set of common renderbuffer functions (methods).
Most device drivers have been updated for these changes, but some haven't.
To Do (someday) items
---------------------
Switch to freeglut
Increase MAX_DRAWBUFFERS
driver hooks for BeginQuery/EndQuery
Miscellaneous
-------------
The main/get.c file is now generated with a Python script (get_gen.py).
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.5
OSMesa (off-screen) implements OpenGL 1.5
Glide (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.5
DJGPP implements OpenGL 1.5
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.5
Allegro needs updating
D3D needs updating
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/6.3.1
+48
View File
@@ -0,0 +1,48 @@
Mesa 6.3.1 release notes
July XX, 2005
PLEASE READ!!!!
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 6.3) designate new developmental releases.
Even numbered versions (such as 6.2) designate stable releases.
DRI drivers
-----------
This release includes the DRI drivers and GLX code for hardware rendering.
Bug fixes
---------
Bugs fixed in 6.3.1 are listed in the VERSIONS file.
Driver Status
---------------------- ---------------------
XMesa (Xlib) implements OpenGL 1.5
OSMesa (off-screen) implements OpenGL 1.5
Glide (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.5
DJGPP implements OpenGL 1.5
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.5
Allegro needs updating
D3D needs updating
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/relnotes/6.3.2
+36
View File
@@ -0,0 +1,36 @@
Mesa 6.3.2 Release Notes
August 19, 2005
Introduction
------------
Mesa uses an even/odd version number scheme like the Linux kernel.
Odd numbered versions (such as 6.3) designate new developmental releases.
Even numbered versions (such as 6.2) designate stable releases.
6.3.2 is primarily a bug-fix release. See the VERSIONS file for details.
Driver Status
---------------------- ----------------------
DRI drivers varies with the driver
XMesa (Xlib) implements OpenGL 1.5
OSMesa (off-screen) implements OpenGL 1.5
Glide (3dfx Voodoo1/2) implements OpenGL 1.3
SVGA implements OpenGL 1.3
Wind River UGL implements OpenGL 1.3
Windows/Win32 implements OpenGL 1.5
DJGPP implements OpenGL 1.5
GGI implements OpenGL 1.3
BeOS implements OpenGL 1.5
Allegro needs updating
D3D needs updating
----------------------------------------------------------------------
local/recipes/dev/mesa-clc/source/docs/_extra/specs/EGL_MESA_device_software.txt
+82
View File
@@ -0,0 +1,82 @@
Name
MESA_device_software
Name Strings
EGL_MESA_device_software
Contributors
Adam Jackson <ajax@redhat.com>
Emil Velikov <emil.velikov@collabora.com>
Contacts
Adam Jackson <ajax@redhat.com>
Status
DRAFT
Version
Version 2, 2018-10-03
Number
EGL Extension #TODO
Extension Type
EGL device extension
Dependencies
Requires EGL_EXT_device_query.
This extension is written against the EGL 1.5 Specification.
Overview
This extension defines a software EGL "device". The device is not backed by
any actual device node and simply renders into client memory.
By defining this as an extension, EGL_EXT_device_enumeration is able to
sanely enumerate a software device.
New Types
None
New Procedures and Functions
None
New Tokens
None
Additions to the EGL Specification
None
New Behavior
The device list produced by eglQueryDevicesEXT will include a software
device. This can be distinguished from other device classes in the usual
way by calling eglQueryDeviceStringEXT(EGL_EXTENSIONS) and matching this
extension's string in the result.
Issues
None
Revision History
Version 2, 2018-10-03 (Emil Velikov)
- Drop "fallback" from "software fallback device"
- Add Emil Velikov as contributor
Version 1, 2017-07-06 (Adam Jackson)
- Initial version
local/recipes/dev/mesa-clc/source/docs/_extra/specs/EGL_MESA_drm_image_formats.txt
+98
View File
@@ -0,0 +1,98 @@
Name
MESA_drm_image_formats
Name Strings
EGL_MESA_drm_image_formats
Contributors
Nicolai Hähnle <Nicolai.Haehnle@amd.com>
Qiang Yu <Qiang.Yu@amd.com>
Contact
Nicolai Hähnle <Nicolai.Haehnle@amd.com>
Status
Proposal
Version
Version 1, January 26, 2017
Number
EGL Extension #??
Dependencies
This extension requires the EGL_MESA_drm_image extension.
This extension is written against the wording of EGL_MESA_drm_image
specification.
Overview
This extension extends the functionality of EGL_MESA_drm_image by adding
additional formats required by Glamor for use with DRM buffers.
IP Status
Open-source; freely implementable.
New Procedures and Functions
None
New Tokens
Accepted as values for the EGL_IMAGE_FORMAT_MESA attribute:
EGL_DRM_BUFFER_FORMAT_ARGB2101010_MESA 0x3290
EGL_DRM_BUFFER_FORMAT_ARGB1555_MESA 0x3291
EGL_DRM_BUFFER_FORMAT_RGB565_MESA 0x3292
Additions to the EGL_MESA_drm_image Specification:
Remove the sentence "The only format specified ..." from the paragraph
describing eglCreateDRMImageMESA and add the following paragraph:
The formats specified for use with EGL_DRM_BUFFER_FORMAT_MESA are:
* 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,
* EGL_DRM_BUFFER_FORMAT_ARGB2101010_MESA, where each pixel is a CPU-
endian, 32-bit quantity, with alpha in the most significant 2 bits,
followed by 10 bits each for red, green, and blue,
* EGL_DRM_BUFFER_FORMAT_ARGB1555_MESA, where each pixel is a CPU-endian
16-bit quantity, with alpha in the most significant bit, followed by
5 bits each for red, green, and blue, and
* EGL_DRM_BUFFER_FORMAT_RGB565_MESA, where each pixel is a CPU-endian
16-bit quantity, with red in the 5 most significant bits, followed by
6 bits of green and 5 bits of blue.
Issues
1. Should we expose the full set of channel permutations for the formats,
e.g. ABGR2101010, RGBA1010102, and BGRA1010102 in addition to
ARGB2101010?
RESOLVED: No.
DISCUSSION: The original extension sets a precedent of only exposing one
of the possible permutations of 8-bit channel formats. It is also not
clear where the additional permutations would be used. For example,
Glamor has a fixed mapping from pixmap/screen depth to format that
doesn't allow for the other permutations.
Revision History
Version 1, January, 2017
Initial draft (Nicolai Hähnle)
local/recipes/dev/mesa-clc/source/docs/_extra/specs/EGL_MESA_platform_surfaceless.txt
+120
View File
@@ -0,0 +1,120 @@
Name
MESA_platform_surfaceless
Name Strings
EGL_MESA_platform_surfaceless
Contributors
Chad Versace <chadversary@google.com>
Haixia Shi <hshi@google.com>
Stéphane Marchesin <marcheu@google.com>
Zach Reizner <zachr@chromium.org>
Gurchetan Singh <gurchetansingh@google.com>
Contacts
Chad Versace <chadversary@google.com>
Status
DRAFT
Version
Version 2, 2016-10-13
Number
EGL Extension #TODO
Extension Type
EGL client extension
Dependencies
Requires EGL 1.5 or later; or EGL 1.4 with EGL_EXT_platform_base.
This extension is written against the EGL 1.5 Specification (draft
20140122).
This extension interacts with EGL_EXT_platform_base as follows. If the
implementation supports EGL_EXT_platform_base, then text regarding
eglGetPlatformDisplay applies also to eglGetPlatformDisplayEXT;
eglCreatePlatformWindowSurface to eglCreatePlatformWindowSurfaceEXT; and
eglCreatePlatformPixmapSurface to eglCreatePlatformPixmapSurfaceEXT.
Overview
This extension defines a new EGL platform, the "surfaceless" platform. This
platfom's defining property is that it has no native surfaces, and hence
neither eglCreatePlatformWindowSurface nor eglCreatePlatformPixmapSurface
can be used. The platform is independent of any native window system.
The platform's intended use case is for enabling OpenGL and OpenGL ES
applications on systems where no window system exists. However, the
platform's permitted usage is not restricted to this case. Since the
platform is independent of any native window system, it may also be used on
systems where a window system is present.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as the <platform> argument of eglGetPlatformDisplay:
EGL_PLATFORM_SURFACELESS_MESA 0x31DD
Additions to the EGL Specification
None.
New Behavior
To determine if the EGL implementation supports this extension, clients
should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY.
To obtain an EGLDisplay on the surfaceless platform, call
eglGetPlatformDisplay with <platform> set to EGL_PLATFORM_SURFACELESS_MESA.
The <native_display> parameter must be EGL_DEFAULT_DISPLAY.
eglCreatePlatformWindowSurface fails when called with a <display> that
belongs to the surfaceless platform. It returns EGL_NO_SURFACE and
generates EGL_BAD_NATIVE_WINDOW. The justification for this unconditional
failure is that the surfaceless platform has no native windows, and
therefore the <native_window> parameter is always invalid.
Likewise, eglCreatePlatformPixmapSurface also fails when called with a
<display> that belongs to the surfaceless platform. It returns
EGL_NO_SURFACE and generates EGL_BAD_NATIVE_PIXMAP.
The surfaceless platform imposes no platform-specific restrictions on the
creation of pbuffers, as eglCreatePbufferSurface has no native surface
parameter. Specifically, if the EGLDisplay advertises an EGLConfig whose
EGL_SURFACE_TYPE attribute contains EGL_PBUFFER_BIT, then the EGLDisplay
permits the creation of pbuffers with that config.
Issues
None.
Revision History
Version 2, 2016-10-13 (Chad Versace)
- Assign enum values
- Define interfactions with EGL 1.4 and EGL_EXT_platform_base.
- Add Gurchetan as contributor, as he implemented the pbuffer support.
Version 1, 2016-09-23 (Chad Versace)
- Initial version
- Posted for review at
https://lists.freedesktop.org/archives/mesa-dev/2016-September/129549.html
local/recipes/dev/mesa-clc/source/docs/_extra/specs/EGL_MESA_query_driver.txt
+95
View File
@@ -0,0 +1,95 @@
Name
MESA_query_driver
Name Strings
EGL_MESA_query_driver
Contact
Rob Clark <robdclark 'at' gmail.com>
Nicolai Hähnle <Nicolai.Haehnle 'at' amd.com>
Contibutors
Veluri Mithun <velurimithun38 'at' gmail.com>
Status
Complete
Version
Version 3, 2019-01-24
Number
EGL Extension 131
Dependencies
EGL 1.0 is required.
Overview
When an application has to query the name of a driver and for
obtaining driver's option list (UTF-8 encoded XML) of a driver
the below functions are useful.
XML file formally describes all available options and also
includes verbal descriptions in multiple languages. Its main purpose
is to be automatically processed by configuration GUIs.
The XML shall respect the following DTD:
<!ELEMENT driinfo (section*)>
<!ELEMENT section (description+, option+)>
<!ELEMENT description (enum*)>
<!ATTLIST description lang CDATA #REQUIRED
text CDATA #REQUIRED>
<!ELEMENT option (description+)>
<!ATTLIST option name CDATA #REQUIRED
type (bool|enum|int|float) #REQUIRED
default CDATA #REQUIRED
valid CDATA #IMPLIED>
<!ELEMENT enum EMPTY>
<!ATTLIST enum value CDATA #REQUIRED
text CDATA #REQUIRED>
New Procedures and Functions
char* eglGetDisplayDriverConfig(EGLDisplay dpy);
const char* eglGetDisplayDriverName(EGLDisplay dpy);
Description
By passing EGLDisplay as parameter to `eglGetDisplayDriverName` one can retrieve
driverName. Similarly passing EGLDisplay to `eglGetDisplayDriverConfig` we can retrieve
driverConfig options of the driver in XML format.
The string returned by `eglGetDisplayDriverConfig` is heap-allocated and caller
is responsible for freeing it.
EGL_BAD_DISPLAY is generated if `disp` is not an EGL display connection.
EGL_NOT_INITIALIZED is generated if `disp` has not been initialized.
If the implementation does not have enough resources to allocate the XML then an
EGL_BAD_ALLOC error is generated.
New Tokens
No new tokens
Issues
None
Revision History
Version 1, 2018-11-05 - First draft (Veluri Mithun)
Version 2, 2019-01-23 - Final version (Veluri Mithun)
Version 3, 2019-01-24 - Mark as complete, add Khronos extension
number, fix parameter name in prototypes,
write revision history (Eric Engestrom)
local/recipes/dev/mesa-clc/source/docs/_extra/specs/EGL_MESA_x11_native_visual_id.txt
+80
View File
@@ -0,0 +1,80 @@
Name
MESA_x11_native_visual_id
Name Strings
EGL_MESA_x11_native_visual_id
Contact
Eric Engestrom <eric@engestrom.ch>
Status
Complete, shipping.
Version
Version 2, May 10, 2024
Number
EGL Extension #TBD
Extension Type
EGL display extension
Dependencies
None. This extension is written against the
wording of the EGL 1.5 specification.
Overview
This extension allows EGL_NATIVE_VISUAL_ID to be used in
eglChooseConfig() for a display of type EGL_PLATFORM_X11_EXT.
IP Status
Open-source; freely implementable.
New Types
None
New Procedures and Functions
None
New Tokens
None
In section 3.4.1.1 "Selection of EGLConfigs" of the EGL 1.5
Specification, replace:
If EGL_MAX_PBUFFER_WIDTH, EGL_MAX_PBUFFER_HEIGHT,
EGL_MAX_PBUFFER_PIXELS, or EGL_NATIVE_VISUAL_ID are specified in
attrib list, then they are ignored [...]
with:
If EGL_MAX_PBUFFER_WIDTH, EGL_MAX_PBUFFER_HEIGHT,
or EGL_MAX_PBUFFER_PIXELS are specified in attrib list, then they
are ignored [...]. EGL_NATIVE_VISUAL_ID is ignored except on
a display of type EGL_PLATFORM_X11_EXT when EGL_ALPHA_SIZE is
greater than zero.
Issues
None.
Revision History
Version 1, March 27, 2024 (Eric Engestrom)
Initial draft
Version 2, May 10, 2024 (David Heidelberg)
add EGL_ALPHA_SIZE condition
add Extension type and set it to display extension
local/recipes/dev/mesa-clc/source/docs/_extra/specs/EXT_shader_integer_mix.spec
+138
View File
@@ -0,0 +1,138 @@
Name
EXT_shader_integer_mix
Name Strings
GL_EXT_shader_integer_mix
Contact
Matt Turner (matt.turner 'at' intel.com)
Contributors
Matt Turner, Intel
Ian Romanick, Intel
Status
Shipping
Version
Last Modified Date: 09/12/2013
Author Revision: 6
Number
TBD
Dependencies
OpenGL 3.0 or OpenGL ES 3.0 is required. This extension interacts with
GL_ARB_ES3_compatibility.
This extension is written against the OpenGL 4.4 (core) specification
and the GLSL 4.40 specification.
Overview
GLSL 1.30 (and GLSL ES 3.00) expanded the mix() built-in function to
operate on a boolean third argument that does not interpolate but
selects. This extension extends mix() to select between int, uint,
and bool components.
New Procedures and Functions
None.
New Tokens
None.
Additions to Chapter 8 of the GLSL 4.40 Specification (Built-in Functions)
Modify Section 8.3, Common Functions
Additions to the table listing common built-in functions:
Syntax Description
--------------------------- --------------------------------------------------
genIType mix(genIType x, Selects which vector each returned component comes
genIType y, from. For a component of a that is false, the
genBType a) corresponding component of x is returned. For a
genUType mix(genUType x, component of a that is true, the corresponding
genUType y, component of y is returned.
genBType a)
genBType mix(genBType x,
genBType y,
genBType a)
Additions to the AGL/GLX/WGL Specifications
None.
Modifications to The OpenGL Shading Language Specification, Version 4.40
Including the following line in a shader can be used to control the
language features described in this extension:
#extension GL_EXT_shader_integer_mix : <behavior>
where <behavior> is as specified in section 3.3.
New preprocessor #defines are added to the OpenGL Shading Language:
#define GL_EXT_shader_integer_mix 1
Interactions with ARB_ES3_compatibility
On desktop implementations that support ARB_ES3_compatibility,
GL_EXT_shader_integer_mix can be enabled (and the new functions
used) in shaders declared with '#version 300 es'.
GLX Protocol
None.
Errors
None.
New State
None.
New Implementation Dependent State
None.
Issues
1) Should we allow linear interpolation of integers via a non-boolean
third component?
RESOLVED: No.
2) Should we allow mix() to select between boolean components?
RESOLVED: Yes. Implementing the same functionality using casts would be
possible but ugly.
Revision History
Rev. Date Author Changes
---- -------- -------- ---------------------------------------------
6 09/12/2013 idr After discussions in Khronos, change vendor
prefix to EXT.
5 09/09/2013 idr Add ARB_ES3_compatibility interaction.
4 09/06/2013 mattst88 Allow extension on OpenGL ES 3.0.
3 08/28/2013 mattst88 Add #extension/#define changes.
2 08/26/2013 mattst88 Change vendor prefix to MESA. Add mix() that
selects between boolean components.
1 08/26/2013 mattst88 Initial revision
local/recipes/dev/mesa-clc/source/docs/_extra/specs/EXT_shader_samples_identical.txt
+176
View File
@@ -0,0 +1,176 @@
Name
EXT_shader_samples_identical
Name Strings
GL_EXT_shader_samples_identical
Contact
Ian Romanick, Intel (ian.d.romanick 'at' intel.com)
Contributors
Chris Forbes, Mesa
Magnus Wendt, Intel
Neil S. Roberts, Intel
Graham Sellers, AMD
Status
XXX - Not complete yet.
Version
Last Modified Date: November 19, 2015
Revision: 6
Number
TBD
Dependencies
OpenGL 3.2, or OpenGL ES 3.1, or ARB_texture_multisample is required.
This extension is written against the OpenGL 4.5 (Core Profile)
Specification
Overview
Multisampled antialiasing has become a common method for improving the
quality of rendered images. Multisampling differs from supersampling in
that the color of a primitive that covers all or part of a pixel is
resolved once, regardless of the number of samples covered. If a large
polygon is rendered, the colors of all samples in each interior pixel will
be the same. This suggests a simple compression scheme that can reduce
the necessary memory bandwidth requirements. In one such scheme, each
sample is stored in a separate slice of the multisample surface. An
additional multisample control surface (MCS) contains a mapping from pixel
samples to slices.
If all the values stored in the MCS for a particular pixel are the same,
then all the samples have the same value. Applications can take advantage
of this information to reduce the bandwidth of reading multisample
textures. A custom multisample resolve filter could optimize resolving
pixels where every sample is identical by reading the color once.
color = texelFetch(sampler, coordinate, 0);
if (!textureSamplesIdenticalEXT(sampler, coordinate)) {
for (int i = 1; i < MAX_SAMPLES; i++) {
vec4 c = texelFetch(sampler, coordinate, i);
//... accumulate c into color
}
}
New Procedures and Functions
None.
New Tokens
None.
Additions to the OpenGL 4.5 (Core Profile) Specification
None.
Modifications to The OpenGL Shading Language Specification, Version 4.50.5
Including the following line in a shader can be used to control the
language features described in this extension:
#extension GL_EXT_shader_samples_identical
A new preprocessor #define is added to the OpenGL Shading Language:
#define GL_EXT_shader_samples_identical
Add to the table in section 8.7 "Texture Lookup Functions"
Syntax:
bool textureSamplesIdenticalEXT(gsampler2DMS sampler, ivec2 coord)
bool textureSamplesIdenticalEXT(gsampler2DMSArray sampler,
ivec3 coord)
Description:
Returns true if it can be determined that all samples within the texel
of the multisample texture bound to <sampler> at <coord> contain the
same values or false if this cannot be determined."
Additions to the AGL/EGL/GLX/WGL Specifications
None
Errors
None
New State
None
New Implementation Dependent State
None
Issues
1) What should the new functions be called?
RESOLVED: textureSamplesIdenticalEXT. Initially
textureAllSamplesIdenticalEXT was considered, but
textureSamplesIdenticalEXT is more similar to the existing textureSamples
function.
2) It seems like applications could implement additional optimization if
they were provided with raw MCS data. Should this extension also
provide that data?
There are a number of challenges in providing raw MCS data. The biggest
problem being that the amount of MCS data depends on the number of
samples, and that is not known at compile time. Additionally, without new
texelFetch functions, applications would have difficulty utilizing the
information.
Another option is to have a function that returns an array of tuples of
sample number and count. This also has difficulties with the maximum
array size not being known at compile time.
RESOLVED: Do not expose raw MCS data in this extension.
3) Should this extension also extend SPIR-V?
RESOLVED: Yes, but this has not yet been written.
4) Is it possible for textureSamplesIdenticalEXT to report false negatives?
RESOLVED: Yes. It is possible that the underlying hardware may not detect
that separate writes of the same color to different samples of a pixel are
the same. The shader function is at the whim of the underlying hardware
implementation. It is also possible that a compressed multisample surface
is not used. In that case the function will likely always return false.
Revision History
Rev Date Author Changes
--- ---------- -------- ---------------------------------------------
1 2014/08/20 cforbes Initial version
2 2015/10/23 idr Change from MESA to EXT. Rebase on OpenGL 4.5,
and add dependency on OpenGL ES 3.1. Initial
draft of overview section and issues 1 through
3.
3 2015/10/27 idr Typo fixes.
4 2015/11/10 idr Rename extension from EXT_shader_multisample_compression
to EXT_shader_samples_identical.
Add issue #4.
5 2015/11/18 idr Fix some typos spotted by gsellers. Change the
name of the name of the function to
textureSamplesIdenticalEXT.
6 2015/11/19 idr Fix more typos spotted by Nicolai Hähnle.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/INTEL_shader_atomic_float_minmax.txt
+200
View File
@@ -0,0 +1,200 @@
Name
INTEL_shader_atomic_float_minmax
Name Strings
GL_INTEL_shader_atomic_float_minmax
Contact
Ian Romanick (ian . d . romanick 'at' intel . com)
Contributors
Status
In progress
Version
Last Modified Date: 06/22/2018
Revision: 4
Number
TBD
Dependencies
OpenGL 4.2, OpenGL ES 3.1, ARB_shader_storage_buffer_object, or
ARB_compute_shader is required.
This extension is written against version 4.60 of the OpenGL Shading
Language Specification.
Overview
This extension provides GLSL built-in functions allowing shaders to
perform atomic read-modify-write operations to floating-point buffer
variables and shared variables. Minimum, maximum, exchange, and
compare-and-swap are enabled.
New Procedures and Functions
None.
New Tokens
None.
IP Status
None.
Modifications to the OpenGL Shading Language Specification, Version 4.60
Including the following line in a shader can be used to control the
language features described in this extension:
#extension GL_INTEL_shader_atomic_float_minmax : <behavior>
where <behavior> is as specified in section 3.3.
New preprocessor #defines are added to the OpenGL Shading Language:
#define GL_INTEL_shader_atomic_float_minmax 1
Additions to Chapter 8 of the OpenGL Shading Language Specification
(Built-in Functions)
Modify Section 8.11, "Atomic Memory Functions"
(add a new row after the existing "atomicMin" table row, p. 179)
float atomicMin(inout float mem, float data)
Computes a new value by taking the minimum of the value of data and
the contents of mem. If one of these is an IEEE signaling NaN (i.e.,
a NaN with the most-significant bit of the mantissa cleared), it is
always considered smaller. If one of these is an IEEE quiet NaN
(i.e., a NaN with the most-significant bit of the mantissa set), it is
always considered larger. If both are IEEE quiet NaNs or both are
IEEE signaling NaNs, the result of the comparison is undefined.
(add a new row after the exiting "atomicMax" table row, p. 179)
float atomicMax(inout float mem, float data)
Computes a new value by taking the maximum of the value of data and
the contents of mem. If one of these is an IEEE signaling NaN (i.e.,
a NaN with the most-significant bit of the mantissa cleared), it is
always considered larger. If one of these is an IEEE quiet NaN (i.e.,
a NaN with the most-significant bit of the mantissa set), it is always
considered smaller. If both are IEEE quiet NaNs or both are IEEE
signaling NaNs, the result of the comparison is undefined.
(add to "atomicExchange" table cell, p. 180)
float atomicExchange(inout float mem, float data)
(add to "atomicCompSwap" table cell, p. 180)
float atomicCompSwap(inout float mem, float compare, float data)
Interactions with OpenGL 4.6 and ARB_gl_spirv
If OpenGL 4.6 or ARB_gl_spirv is supported, then
SPV_INTEL_shader_atomic_float_minmax must also be supported.
The AtomicFloatMinmaxINTEL capability is available whenever the OpenGL or
OpenGL ES implementation supports INTEL_shader_atomic_float_minmax.
Issues
1) Why call this extension INTEL_shader_atomic_float_minmax?
RESOLVED: Several other extensions already set the precedent of
VENDOR_shader_atomic_float and VENDOR_shader_atomic_float64 for extensions
that enable floating-point atomic operations. Using that as a base for
the name seems logical.
There already exists NV_shader_atomic_float, but the two extensions have
nearly zero overlap in functionality. NV_shader_atomic_float adds
atomicAdd and image atomic operations that currently shipping Intel GPUs
do not support. Calling this extension INTEL_shader_atomic_float would
likely have been confusing.
Adding something to describe the actual functions added by this extension
seemed reasonable. INTEL_shader_atomic_float_compare was considered, but
that name was deemed to be not properly descriptive. Calling this
extension INTEL_shader_atomic_float_min_max_exchange_compswap is right
out.
2) What atomic operations should we support for floating-point targets?
RESOLVED. Exchange, min, max, and compare-swap make sense, and these are
all supported by the hardware. Future extensions may add other functions.
For buffer variables and shared variables it is not possible to bit-cast
the memory location in GLSL, so existing integer operations, such as
atomicOr, cannot be used. However, the underlying hardware implementation
can do this by treating the memory as an integer. It would be possible to
implement atomicNegate using this technique with atomicXor. It is unclear
whether this provides any actual utility.
3) What should be said about the NaN behavior?
RESOLVED. There are several aspects of NaN behavior that should be
documented in this extension. However, some of this behavior varies based
on NaN concepts that do not exist in the GLSL specification.
* atomicCompSwap performs the comparison as the floating-point equality
operator (==). That is, if either 'mem' or 'compare' is NaN, the
comparison result is always false.
* atomicMin and atomicMax implement the IEEE specification with respect to
NaN. IEEE considers two different kinds of NaN: signaling NaN and quiet
NaN. A quiet NaN has the most significant bit of the mantissa set, and
a signaling NaN does not. This concept does not exist in SPIR-V,
Vulkan, or OpenGL. Let qNaN denote a quiet NaN and sNaN denote a
signaling NaN. atomicMin and atomicMax specifically implement
- fmin(qNaN, x) = fmin(x, qNaN) = fmax(qNaN, x) = fmax(x, qNaN) = x
- fmin(sNaN, x) = fmin(x, sNaN) = fmax(sNaN, x) = fmax(x, sNaN) = sNaN
- fmin(sNaN, qNaN) = fmin(qNaN, sNaN) = fmax(sNaN, qNaN) =
fmax(qNaN, sNaN) = sNaN
- fmin(sNaN, sNaN) = sNaN. This specification does not define which of
the two arguments is stored.
- fmax(sNaN, sNaN) = sNaN. This specification does not define which of
the two arguments is stored.
- fmin(qNaN, qNaN) = qNaN. This specification does not define which of
the two arguments is stored.
- fmax(qNaN, qNaN) = qNaN. This specification does not define which of
the two arguments is stored.
Further details are available in the Skylake Programmer's Reference
Manuals available at
https://01.org/linuxgraphics/documentation/hardware-specification-prms.
4) What about atomicMin and atomicMax with (+0.0, -0.0) or (-0.0, +0.0)
arguments?
RESOLVED. atomicMin should store -0.0, and atomicMax should store +0.0.
Due to a known issue in shipping Skylake GPUs, the incorrectly signed 0 is
stored. This behavior may change in later GPUs.
Revision History
Rev Date Author Changes
--- ---------- -------- ---------------------------------------------
1 04/19/2018 idr Initial version
2 05/05/2018 idr Describe interactions with the capabilities
added by SPV_INTEL_shader_atomic_float_minmax.
3 05/29/2018 idr Remove mention of 64-bit float support.
4 06/22/2018 idr Resolve issue #2.
Add issue #3 (regarding NaN behavior).
Add issue #4 (regarding atomicMin(-0, +0).
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_bgra.txt
+106
View File
@@ -0,0 +1,106 @@
Name
MESA_bgra
Name Strings
GL_MESA_bgra
Contact
Gert Wollny (gert.wollny 'at' collabora.com)
Notice
Copyright (c) 2021 Collabora LTD
Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Version
Version 1, 2021/04/30.
Based on EXT_bgra version 1, modified 1997/05/19.
Number
TBD
Dependencies
OpenGL ES 2.0 is required.
Written based on the wording of the OpenGL ES 3.2 specification.
There are interactions with the extensions EXT_clear_texture.
Overview
MESA_bgra extends the list of combinations host-memory color formats
with internal formats to include BGRA and BGR as acceptable formats
with RGB8/SRGB8 and RGBA/sRGB8_ALPHA8 as internal formats respectively.
This feature is of interest in virtualized environments, where the host
supports OpenGL ES only, and the virtualized guest is supposed to support
a subset of OpenGL including textures created with the format BGRA.
IP Status
Open-source; freely implementable.
Issues
None.
New Procedures and Functions
None
New Tokens
Accepted by the <format> parameter of TexImage2D and TexSubImage2D:
GL_BGR_EXT 0x80E0
GL_BGRA_EXT 0x80E1
Additions to Chapter 8 of the GLES 3.2 Specification (Textures and Samplers)
Add to table 8.2 (Pixels data formats, valid combinations of format,
type, and unsized internalformat).
Format Type External Internal Format
Bytes
per Pixel
-------------------------------------------------------------
BGRA UNSIGNED_BYTE 4 RGBA
BGR UNSIGNED_BYTE 3 RGB
Add to table 8.5 (Pixels data formats).
Format Name Elements Meaning and Order Target Buffer
-------------------------------------------------------------
BGR_EXT B, G, R Color
BGRA_EXT B, G, R, A Color
Add to table 8.9 (Effective internal format corresponding to
external format).
Format Type Effective
Internal format
-------------------------------------------------------------
BGRA_EXT UNSIGNED_BYTE RGBA8
BGR_EXT UNSIGNED_BYTE RGB8
Interactions with EXT_clear_texture
When EXT_clear_texture is supported the accepted formats for
ClearTextureEXT and ClearSubTextureEXT are extended to include
the entries added above.
Revision History
Original draft, revision 1.0, May 4, 2021 (Gert Wollny)
rewrite EXT_bgra against OpenGL ES 3.2 instead of OpenGL 1,0.
Revision 1.1 (May 5. 2021): Add the new tokens, and fix
Clear*Texture function names.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_configless_context.spec
+129
View File
@@ -0,0 +1,129 @@
Name
MESA_configless_context
Name Strings
EGL_MESA_configless_context
Contact
Neil Roberts <neil.s.roberts@intel.com>
Status
Superseded by the functionally identical EGL_KHR_no_config_context
extension.
Version
Version 2, September 9, 2016
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.
Overview
This extension provides a means to use a single context to render to
multiple surfaces which have different EGLConfigs. Without this extension
the EGLConfig for every surface used by the context must be compatible
with the one used by the context. The only way to render to surfaces with
different formats would be to create multiple contexts but this is
inefficient with modern GPUs where this restriction is unnecessary.
IP Status
Open-source; freely implementable.
New Procedures and Functions
None.
New Tokens
Accepted as <config> in eglCreateContext
EGL_NO_CONFIG_MESA ((EGLConfig)0)
Additions to the EGL Specification section "2.2 Rendering Contexts and Drawing
Surfaces"
Add the following to the 3rd paragraph:
"EGLContexts can also optionally be created with respect to an EGLConfig
depending on the parameters used at creation time. If a config is provided
then additional restrictions apply on what surfaces can be used with the
context."
Replace the last sentence of the 6th paragraph with:
"In order for a context to be compatible with a surface they both must have
been created with respect to the same EGLDisplay. If the context was
created without respect to an EGLConfig then there are no further
constraints. Otherwise they are only compatible if:"
Remove the last bullet point in the list of constraints.
Additions to the EGL Specification section "3.7.1 Creating Rendering Contexts"
Replace the paragraph starting "If config is not a valid EGLConfig..."
with
"The config argument can either be a valid EGLConfig or EGL_NO_CONFIG_MESA.
If it is neither of these then an EGL_BAD_CONFIG error is generated. If a
valid config is passed then the error will also be generated if the config
does not support the requested client API (this includes requesting
creation of an OpenGL ES 1.x context when the EGL_RENDERABLE_TYPE
attribute of config does not contain EGL_OPENGL_ES_BIT, or creation of an
OpenGL ES 2.x context when the attribute does not contain
EGL_OPENGL_ES2_BIT).
Passing EGL_NO_CONFIG_MESA will create a configless context. When a
configless context is used with the OpenGL API it can be assumed that the
initial values of the context's state will be decided when the context is
first made current. In particular this means that the decision of whether
to use GL_BACK or GL_FRONT for the initial value of the first output in
glDrawBuffers will be decided based on the config of the draw surface when
it is first bound."
Additions to the EGL Specification section "3.7.3 Binding Contexts and
Drawables"
Replace the first bullet point with the following:
"* If draw or read are not compatible with ctx as described in section 2.2,
then an EGL_BAD_MATCH error is generated."
Add a second bullet point after that:
"* If draw and read are not compatible with each other as described in
section 2.2, then an EGL_BAD_MATCH error is generated."
Issues
1. What happens when an OpenGL context with a double-buffered surface and
draw buffer set to GL_BACK is made current with a single-buffered
surface?
NOT RESOLVED: There are a few options here. An implementation can
raise an error, change the drawbuffer state to GL_FRONT or just do
nothing, expecting the application to set GL_FRONT drawbuffer before
drawing. However, this extension deliberately does not specify any
required behavior in this corner case and applications should avoid
mixing single- and double-buffered surfaces with configless contexts.
Future extensions may specify required behavior in this case.
Revision History
Version 2, September 9, 2016
Defer to EGL_KHR_no_config_context (Adam Jackson)
Version 1, February 28, 2014
Initial draft (Neil Roberts)
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_copy_sub_buffer.spec
+96
View File
@@ -0,0 +1,96 @@
Name
MESA_copy_sub_buffer
Name Strings
GLX_MESA_copy_sub_buffer
Contact
Brian Paul (brian.paul 'at' tungstengraphics.com)
Status
Shipping since Mesa 2.6 in February, 1998.
Version
Last Modified Date: 12 January 2009
Number
215
Dependencies
OpenGL 1.0 or later is required.
GLX 1.0 or later is required.
Overview
The glxCopySubBufferMESA() function copies a rectangular region
of the back color buffer to the front color buffer. This can be
used to quickly repaint 3D windows in response to expose events
when the back color buffer cannot be damaged by other windows.
IP Status
Open-source; freely implementable.
Issues
None.
New Procedures and Functions
void glXCopySubBufferMESA( Display *dpy, GLXDrawable drawable,
int x, int y, int width, int height );
New Tokens
None.
Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors)
Add to section 3.3.10 Double Buffering:
The function
void glXCopySubBufferMESA( Display *dpy, GLXDrawable drawable,
int x, int y, int width, int height );
may be used to copy a rectangular region of the back color buffer to
the front color buffer. This can be used to quickly repaint 3D windows
in response to expose events when the back color buffer cannot be
damaged by other windows.
<x> and <y> indicates the lower-left corner of the region to copy and
<width> and <height> indicate the size in pixels. Coordinate (0,0)
corresponds to the lower-left pixel of the window, like glReadPixels.
If dpy and drawable are the display and drawable for the calling
thread's current context, glXCopySubBufferMESA performs an
implicit glFlush before it returns. Subsequent OpenGL commands
may be issued immediately after calling glXCopySubBufferMESA, but
are not executed until the copy is completed.
GLX Protocol
None at this time. The extension is implemented in terms of ordinary
Xlib protocol inside of Mesa.
Errors
None.
New State
None.
Revision History
12 January 2009 Ian Romanick - Added language about implicit flush
and command completion.
8 June 2000 Brian Paul - initial specification
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_drm_image.spec
+153
View File
@@ -0,0 +1,153 @@
Name
MESA_drm_image
Name Strings
EGL_MESA_drm_image
Contact
Kristian Høgsberg <krh@bitplanet.net>
Status
Proposal
Version
Version 2, August 25, 2010
Number
EGL Extension #not assigned
Dependencies
Requires EGL 1.4 or later. This extension is written against the
wording of the EGL 1.4 specification.
EGL_KHR_base_image is required.
Overview
This extension provides entry points for integrating EGLImage with the
Linux DRM mode setting and memory management drivers. The extension
lets applications create EGLImages without a client API resource and
lets the application get the DRM buffer handles.
IP Status
Open-source; freely implementable.
New Procedures and Functions
EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy,
const EGLint *attrib_list);
EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy,
EGLImageKHR image,
EGLint *name,
EGLint *handle,
EGLint *stride);
New Tokens
Accepted in the <attrib_list> parameter of eglCreateDRMImageMESA:
EGL_DRM_BUFFER_FORMAT_MESA 0x31D0
EGL_DRM_BUFFER_USE_MESA 0x31D1
Accepted as values for the EGL_IMAGE_FORMAT_MESA attribute:
EGL_DRM_BUFFER_FORMAT_ARGB32_MESA 0x31D2
Bits accepted in EGL_DRM_BUFFER_USE_MESA:
EGL_DRM_BUFFER_USE_SCANOUT_MESA 0x0001
EGL_DRM_BUFFER_USE_SHARE_MESA 0x0002
EGL_DRM_BUFFER_USE_CURSOR_MESA 0x0004
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_DRM_BUFFER_MESA 0x31D3
Use when importing drm buffer:
EGL_DRM_BUFFER_STRIDE_MESA 0x31D4
EGL_DRM_BUFFER_FORMAT_MESA 0x31D0
Additions to the EGL 1.4 Specification:
To create a DRM EGLImage, call
EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy,
const EGLint *attrib_list);
In the attribute list, pass EGL_WIDTH, EGL_HEIGHT and format and
use in the attrib list using EGL_DRM_BUFFER_FORMAT_MESA and
EGL_DRM_BUFFER_USE_MESA. The only format specified by this
extension is EGL_DRM_BUFFER_FORMAT_ARGB32_MESA, where each pixel
is a CPU-endian, 32-bit quantity, with alpha in the upper 8 bits,
then red, then green, then blue. The bit values accepted by
EGL_DRM_BUFFER_USE_MESA are EGL_DRM_BUFFER_USE_SCANOUT_MESA,
EGL_DRM_BUFFER_USE_SHARE_MESA and EGL_DRM_BUFFER_USE_CURSOR_MESA.
EGL_DRM_BUFFER_USE_SCANOUT_MESA requests that the created EGLImage
should be usable as a scanout buffer with the DRM kernel
modesetting API. EGL_DRM_BUFFER_USE_SHARE_MESA requests that the
EGLImage can be shared with other processes by passing the
underlying DRM buffer name. EGL_DRM_BUFFER_USE_CURSOR_MESA
requests that the image must be usable as a cursor with KMS. When
EGL_DRM_BUFFER_USE_CURSOR_MESA is set, width and height must both
be 64.
To create a process local handle or a global DRM name for a
buffer, call
EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy,
EGLImageKHR image,
EGLint *name,
EGLint *handle,
EGLint *stride);
If <name> is non-NULL, a global name is assigned to the image and
written to <name>, the handle (local to the DRM file descriptor,
for use with DRM kernel modesetting API) is written to <handle> if
non-NULL and the stride (in bytes) is written to <stride>, if
non-NULL.
Import a shared buffer by calling eglCreateImageKHR with
EGL_DRM_BUFFER_MESA as the target, using EGL_WIDTH, EGL_HEIGHT,
EGL_DRM_BUFFER_FORMAT_MESA, EGL_DRM_BUFFER_STRIDE_MESA
in the attrib list.
Issues
1. Why don't we use eglCreateImageKHR with a target that
indicates that we want to create an EGLImage from scratch?
RESOLVED: The eglCreateImageKHR entry point is reserved for
creating an EGLImage from an already existing client API
resource. This is fine when we're creating the EGLImage from
an existing DRM buffer name, it doesn't seem right to overload
the function to also allocate the underlying resource.
2. Why don't we use an eglQueryImageMESA type functions for
querying the DRM EGLImage attributes (name, handle, and stride)?
RESOLVED: The eglQueryImage function has been proposed often,
but it goes against the EGLImage design. EGLImages are opaque
handles to a 2D array of pixels, which can be passed between
client APIs. By referencing an EGLImage in a client API, the
EGLImage target (a texture, a renderbuffer or such) can be
used to query the attributes of the EGLImage. We don't have a
full client API for creating and querying DRM buffers, though,
so we use a new EGL extension entry point instead.
Revision History
Version 1, June 3, 2010
Initial draft (Kristian Høgsberg)
Version 2, August 25, 2010
Flesh out the extension a bit, add final EGL tokens, capture
some of the original discussion in the issues section.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_framebuffer_flip_y.txt
+106
View File
@@ -0,0 +1,106 @@
Name
MESA_framebuffer_flip_y
Name Strings
GL_MESA_framebuffer_flip_y
Contact
Fritz Koenig <frkoenig@google.com>
Contributors
Fritz Koenig, Google
Kristian Høgsberg, Google
Chad Versace, Google
Heinrich Fink, DAQRI
Status
Proposal
Version
Version 3, August, 2019
Number
OpenGL Extension #540
OpenGL ES Extension #302
Dependencies
Requires OpenGL ES 3.0, OpenGL 4.3, or ARB_framebuffer_no_attachments.
Overview
This extension defines a new framebuffer parameter,
GL_FRAMEBUFFER_FLIP_Y_MESA, that changes the behavior of the reads and
writes to the framebuffer attachment points. When GL_FRAMEBUFFER_FLIP_Y_MESA
is GL_TRUE, render commands and pixel transfer operations access the
backing store of each attachment point with an y-inverted coordinate
system. This y-inversion is relative to the coordinate system set when
GL_FRAMEBUFFER_FLIP_Y_MESA is GL_FALSE.
Access through TexSubImage2D and similar calls will notice the effect of
the flip when they are not attached to framebuffer objects because
GL_FRAMEBUFFER_FLIP_Y_MESA is associated with the framebuffer object and
not the attachment points.
IP Status
None
Issues
None
New Procedures and Functions
OpenGL ES must provide the following functions:
void FramebufferParameteriMESA(enum target, enum pname, int param);
void GetFramebufferParameterivMESA(enum target, enum pname, int *params);
New Types
None
New Tokens
Accepted by the <pname> argument of FramebufferParameteriMESA and
GetFramebufferParameterivMESA:
GL_FRAMEBUFFER_FLIP_Y_MESA 0x8BBB
Interactions with OpenGL 4.3, OpenGL ES 3.1, ARB_framebuffer_no_attachments
and any other versions and extensions that provide the entry points
FramebufferParameteri and GetFramebufferParameteriv
Token GL_FRAMEBUFFER_FLIP_Y_MESA is accepted as the <pname> argument of
FramebufferParameteri and GetFramebufferParameteriv.
Errors
An INVALID_OPERATION error is generated by GetFramebufferParameteriv or
GetFramebufferParameterivMESA if the default framebuffer is bound
to <target> and <pname> is GL_FRAMEBUFFER_FLIP_Y_MESA.
Revision History
Version 3, August, 2019
Allow OpenGL ES 3.0 to implement by adding functions
FramebufferParameteriMESA and GetFramebufferParameterivMESA which were
previously only available in OpenGL ES 3.1.
Version 2, June, 2019
Enable extension for OpenGL 4.3 and beyond
Version 1, June, 2018
Initial draft (Fritz Koenig)
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_image_dma_buf_export.txt
+147
View File
@@ -0,0 +1,147 @@
Name
MESA_image_dma_buf_export
Name Strings
EGL_MESA_image_dma_buf_export
Contributors
Dave Airlie
Contact
Dave Airlie (airlied 'at' redhat 'dot' com)
Status
Complete, shipping.
Version
Version 3, May 5, 2015
Number
EGL Extension #87
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.
The EGL implementation must be running on a Linux kernel supporting the
dma_buf buffer sharing mechanism.
Overview
This extension provides entry points for integrating EGLImage with the
dma-buf infrastructure. The extension allows creating a Linux dma_buf
file descriptor or multiple file descriptors, in the case of multi-plane
YUV image, from an EGLImage.
It is designed to provide the complementary functionality to
EGL_EXT_image_dma_buf_import.
IP Status
Open-source; freely implementable.
New Types
This extension uses the 64-bit unsigned integer type EGLuint64KHR
first introduced by the EGL_KHR_stream extension, but does not
depend on that extension. The typedef may be reproduced separately
for this extension, if not already present in eglext.h.
typedef khronos_uint64_t EGLuint64KHR;
New Procedures and Functions
EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy,
EGLImageKHR image,
int *fourcc,
int *num_planes,
EGLuint64KHR *modifiers);
EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy,
EGLImageKHR image,
int *fds,
EGLint *strides,
EGLint *offsets);
New Tokens
None
Additions to the EGL 1.4 Specification:
To mirror the import extension, this extension attempts to return
enough information to enable an exported dma-buf to be imported
via eglCreateImageKHR and EGL_LINUX_DMA_BUF_EXT token.
Retrieving the information is a two step process, so two APIs
are required.
The first entrypoint
EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy,
EGLImageKHR image,
int *fourcc,
int *num_planes,
EGLuint64KHR *modifiers);
is used to retrieve the pixel format of the buffer, as specified by
drm_fourcc.h, the number of planes in the image and the Linux
drm modifiers. <fourcc>, <num_planes> and <modifiers> may be NULL,
in which case no value is retrieved.
The second entrypoint retrieves the dma_buf file descriptors,
strides and offsets for the image. The caller should pass
arrays sized according to the num_planes values retrieved previously.
Passing arrays of the wrong size will have undefined results.
If the number of fds is less than the number of planes, then
subsequent fd slots should contain -1.
EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy,
EGLImageKHR image,
int *fds,
EGLint *strides,
EGLint *offsets);
<fds>, <strides>, <offsets> can be NULL if the infomatation isn't
required by the caller.
Issues
1. Should the API look more like an attribute getting API?
ANSWER: No, from a user interface pov, having to iterate across calling
the API up to 12 times using attribs seems like the wrong solution.
2. Should the API take a plane and just get the fd/stride/offset for that
plane?
ANSWER: UNKNOWN,this might be just as valid an API.
3. Does ownership of the file descriptor remain with the app?
ANSWER: Yes, the app is responsible for closing any fds retrieved.
4. If number of planes and number of fds differ what should we do?
ANSWER: Return -1 for the secondary slots, as this avoids having
to dup the fd extra times to make the interface sane.
Revision History
Version 3, May, 2015
Just use the KHR 64-bit type.
Version 2, March, 2015
Add a query interface (Dave Airlie)
Version 1, June 3, 2014
Initial draft (Dave Airlie)
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_pack_invert.spec
+138
View File
@@ -0,0 +1,138 @@
Name
MESA_pack_invert
Name Strings
GL_MESA_pack_invert
Contact
Brian Paul, Tungsten Graphics, Inc. (brian.paul 'at' tungstengraphics.com)
Keith Whitwell, Tungsten Graphics, Inc. (keith 'at' tungstengraphics.com)
Status
Shipping (Mesa 4.0.4 and later)
Version
1.0
Number
TBD
Dependencies
OpenGL 1.0 or later is required
This extensions is written against the OpenGL 1.4 Specification.
Overview
This extension adds a new pixel storage parameter to indicate that
images are to be packed in top-to-bottom order instead of OpenGL's
conventional bottom-to-top order. Only pixel packing can be
inverted (i.e. for glReadPixels, glGetTexImage, glGetConvolutionFilter,
etc).
Almost all known image file formats store images in top-to-bottom
order. As it is, OpenGL reads images from the frame buffer in
bottom-to-top order. Thus, images usually have to be inverted before
writing them to a file with image I/O libraries. This extension
allows images to be read such that inverting isn't needed.
IP Status
None
Issues
1. Should we also define UNPACK_INVERT_MESA for glDrawPixels, etc?
Resolved: No, we're only concerned with pixel packing. There are other
solutions for inverting images when using glDrawPixels (negative Y pixel
zoom) or glTexImage (invert the vertex T coordinates). It would be easy
enough to define a complementary extension for pixel packing in the
future if needed.
New Procedures and Functions
None
New Tokens
Accepted by the <pname> parameter of PixelStorei and PixelStoref
and the <pname> parameter of GetIntegerv, GetFloatv, GetDoublev
and GetBooleanv:
PACK_INVERT_MESA 0x8758
Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
None
Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
Operations and the Frame Buffer)
Add the following entry to table 4.4 (PixelStore parameters) on page 182:
Parameter Name Type Initial Value Valid Range
---------------------------------------------------------
PACK_INVERT_MESA boolean FALSE TRUE/FALSE
In the section labeled "Placement in Client Memory" on page 184
insert the following text into the paragraph before the sentence
that starts with "If the format is RED, GREEN, BLUE...":
"The parameter PACK_INVERT_MESA controls whether the image is packed
in bottom-to-top order (the default) or top-to-bottom order. Equation
3.8 is modified as follows:
... the first element of the Nth row is indicated by
p + Nk, if PACK_INVERT_MESA is false
p + k * (H - 1) - Nk, if PACK_INVERT_MESA is true, where H is the
image height
"
Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
None
Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
State Requests)
None
Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
None
Additions to the AGL/GLX/WGL Specifications
None
GLX Protocol
None
Errors
None
New State
Add the following entry to table 6.20 (Pixels) on page 235:
Get Value Type Get Cmd Initial Value Description Sec Attribute
--------------------------------------------------------------------------------------------------
PACK_INVERT_MESA boolean GetBoolean FALSE Value of PACK_INVERT_MESA 4.3.2 pixel-store
Revision History
21 September 2002 - Initial draft
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_pixmap_colormap.spec
+90
View File
@@ -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
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_query_renderer.spec
+385
View File
@@ -0,0 +1,385 @@
Name
MESA_query_renderer
Name Strings
GLX_MESA_query_renderer
Contact
Ian Romanick <ian.d.romanick@intel.com>
IP Status
No known IP claims.
Status
Shipping as of Mesa 10.0
Version
Version 9, 09 November 2018
Number
OpenGL Extension #446
Dependencies
GLX 1.4 is required.
GLX_ARB_create_context and GLX_ARB_create_context_profile are required.
Overview
In many situations, applications want to detect characteristics of a
rendering device before creating a context for that device. Information
gathered at this stage may guide choices the application makes about
color depth, number of samples per-pixel, texture quality, and so on.
In addition, versions of supported APIs and implementation API
preference may also guide start-up decisions made by the application.
For example, one implementation may prefer vertex data be supplied using
methods only available in a compatibility profile, but another
implementation may only support the desired version in a core profile.
There are also cases where more than one renderer may be available per
display. For example, there is typically a hardware implementation and
a software based implementation. There are cases where an application
may want to pick one over the other. One such situation is when the
software implementation supports more features than the hardware
implementation. Another situation is when a particular version of the
hardware implementation is blacklisted due to known bugs.
This extension provides a mechanism for the application to query all of
the available renderers for a particular display and screen. In
addition, this extension provides a mechanism for applications to create
contexts with respect to a specific renderer.
New Procedures and Functions
Bool glXQueryRendererIntegerMESA(Display *dpy, int screen,
int renderer, int attribute,
unsigned int *value);
Bool glXQueryCurrentRendererIntegerMESA(int attribute, unsigned int *value);
const char *glXQueryRendererStringMESA(Display *dpy, int screen,
int renderer, int attribute);
const char *glXQueryCurrentRendererStringMESA(int attribute);
New Tokens
Accepted as an <attribute> in glXQueryRendererIntegerMESA and
glXQueryCurrentRendererIntegerMESA:
GLX_RENDERER_VENDOR_ID_MESA 0x8183
GLX_RENDERER_DEVICE_ID_MESA 0x8184
GLX_RENDERER_VERSION_MESA 0x8185
GLX_RENDERER_ACCELERATED_MESA 0x8186
GLX_RENDERER_VIDEO_MEMORY_MESA 0x8187
GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA 0x8188
GLX_RENDERER_PREFERRED_PROFILE_MESA 0x8189
GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA 0x818A
GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA 0x818B
GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA 0x818C
GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA 0x818D
Accepted as an <attribute> in glXQueryRendererStringMESA and
glXQueryCurrentRendererStringMESA:
GLX_RENDERER_VENDOR_ID_MESA
GLX_RENDERER_DEVICE_ID_MESA
Additions to the OpenGL / WGL Specifications
None. This specification is written for GLX.
Additions to the GLX 1.4 Specification
[Add to Section 3.3.2 "GLX Versioning" of the GLX Specification]
To obtain information about the available renderers for a particular
display and screen,
Bool glXQueryRendererIntegerMESA(Display *dpy, int screen, int renderer,
int attribute, unsigned int *value);
can be used. The value for <attribute> will be returned in one or more
integers specified by <value>. The values, data sizes, and descriptions
of each renderer attribute are listed in the table below.
GLX renderer attribute number description
of values
---------------------- --------- -----------
GLX_RENDERER_VENDOR_ID_MESA 1 PCI ID of the device vendor
GLX_RENDERER_DEVICE_ID_MESA 1 PCI ID of the device
GLX_RENDERER_VERSION_MESA 3 Major, minor, and patch level of
the renderer implementation
GLX_RENDERER_ACCELERATED_MESA 1 Boolean indicating whether or
not the renderer is hardware
accelerated
GLX_RENDERER_VIDEO_MEMORY_MESA 1 Number of megabytes of video
memory available to the renderer
GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA
1 Boolean indicating whether or
not the renderer uses a unified
memory architecture or has
separate "on-card" and GART
memory.
GLX_RENDERER_PREFERRED_PROFILE_MESA
1 Bitmask of the preferred context
profile for this renderer. This
value is suitable to be supplied
with the
GLX_CONTEXT_PROFILE_MASK_ARB
attribute to
glXCreateContextAttribsARB
GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA
2 Maximum core profile major and
minor version supported by the
renderer
GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA
2 Maximum compatibility profile
major and minor version
supported by the renderer
GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA
2 Maximum OpenGL ES 1.x
major and minor version
supported by the renderer
GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA
2 Maximum OpenGL ES 2.x or 3.x
major and minor version
supported by the renderer
In the table, boolean attributes will have either the value 0 or 1.
GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA,
GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA,
GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA, and
GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA each return <0, 0> in
*value if no version of that profile is supported.
GLX_RENDERER_VENDOR_ID_MESA and GLX_RENDERER_DEVICE_ID_MESA may return
0xFFFFFFFF if the device does not have a PCI ID (because it is not a PCI
device) or if the PCI ID is not available. In this case the application
should rely on the string query instead.
If <attribute> is not a recognized value, False is returned, but no GLX
error is generated. Otherwise, True is returned.
String versions of some attributes may also be queried using
const char *glXQueryRendererStringMESA(Display *dpy, int screen,
int renderer, int attribute);
The value for <attribute> will be returned in one or more
integers specified by <value>. The values, data sizes, and descriptions
of each renderer attribute are listed in the table below.
GLX renderer attribute description
---------------------- -----------
GLX_RENDERER_VENDOR_ID_MESA Name of the renderer provider. This may
differ from the vendor name of the
underlying hardware.
GLX_RENDERER_DEVICE_ID_MESA Name of the renderer. This may differ from
the name of the underlying hardware (e.g.,
for a software renderer).
If <attribute> is not a recognized value, NULL is returned, but no GLX
error is generated.
The string returned for GLX_RENDERER_VENDOR_ID_MESA will have the same
format as the string that would be returned by glGetString of GL_VENDOR.
It may, however, have a different value.
The string returned for GLX_RENDERER_DEVICE_ID_MESA will have the same
format as the string that would be returned by glGetString of GL_RENDERER.
It may, however, have a different value.
Issues
1) How should the difference between on-card and GART memory be exposed?
UNRESOLVED.
2) How should memory limitations of unified memory architecture (UMA)
systems be exposed?
UNRESOLVED. Some hardware has different per-process and global
limits for memory that can be accessed within a single draw call.
3) How should the renderer's API preference be advertised?
UNRESOLVED. The common case for desktop renderers is to prefer
either core or compatibility. However, some renderers may actually
prefer an ES context. This leaves the application in a tough spot
if it can only support core or compatibility and the renderer says it
wants ES.
4) Should OpenGL ES 2.0 and OpenGL ES 3.0 be treated separately?
RESOLVED. No. OpenGL ES 3.0 is backwards compatible with OpenGL ES
2.0. Applications can detect OpenGL ES 3.0 support by querying
GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA.
5) How can applications tell the difference between different hardware
renderers for the same device? For example, whether the renderer is the
open-source driver or the closed-source driver.
RESOLVED. Assuming this extension is ever implemented outside Mesa,
applications can query GLX_RENDERER_VENDOR_ID_MESA from
glXQueryRendererStringMESA. This will almost certainly return
different strings for open-source and closed-source drivers.
6) What is the value of GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA for
software renderers?
UNRESOLVED. Video (display) memory and texture memory is not unified
for software implementations, so it seems reasonable for this to be
False.
7) How does an application determine the number of available renderers?
UNRESOLVED.
8) What happens if a fbconfig is used to create context on a renderer
that cannot support it? For example, if a multisampled config is used
with a software renderer that does not support multisampling.
RESOLVED. The language for glXCreateContextAttribsARB already covers
this case. Context creation will fail, and BadMatch is generated.
9) In addition to being able to query the supported versions, should
applications also be able to query the supported extensions?
RESOLVED. No. Desktop OpenGL core profiles and OpenGL ES 3.0 have
moved away from the monolithic string returned by glGetString of
GL_EXTENSIONS. Providing the newer indexed query would require adding
a lot of extra infrastructure, and it would probably provide little
benefit to applications.
10) What combination of values for GLX_RENDERER_PREFERRED_PROFILE_MESA,
GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA, and
GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA should be returned
for a renderer that only supports OpenGL 3.1 without the
GL_ARB_compatibility extension?
RESOLVED. The renderer will return GLX_CONTEXT_CORE_PROFILE_BIT_ARB
for GLX_RENDERER_PREFERRED_PROFILE_MESA.
Further, the renderer will return <3,0> for
GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA because OpenGL
3.1 without GL_ARB_compatibility is not backwards compatible with
previous versions of OpenGL. The render will return <3,1> for
GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA indicating that support
for OpenGL 3.1 is available.
Even though there is no OpenGL 3.1 core profile, the values
returned for GLX_RENDERER_PREFERRED_PROFILE_MESA and
GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA can be supplied
with the GLX_CONTEXT_PROFILE_MASK_ARB and
GLX_CONTEXT_{MAJOR,MINOR}_VERSION_ARB attributes of
glXCreateContextAttribsARB without error. If the requested
OpenGL version is less than 3.2, the
GLX_CONTEXT_PROFILE_MASK_ARB attribute is ignored by
glXCreateContextAttribsARB.
11) How can application learn about multi-GPU (e.g., SLI, CrossFireX,
etc.) configurations?
UNRESOLVED. Based on ISV feedback, this is important information to
provide to the application. Given the variety of possible hardware
configurations (e.g., Hybrid CrossFireX) and different rendering
modes (e.g., split-frame rendering vs. alternate-frame rendering),
it's not clear how this information can be communicated.
It is likely that this will be left to a layered extension.
12) Should capability queries similar to those in
GL_ARB_internalformat_query or GL_ARB_internalformat_query2 be added?
RESOLVED. No. With the possible exception of the texture size
queries, it seems unlikely that applications would ever use this
information before creating a context.
13) Existing GL extensions (e.g., GL_ATI_meminfo and
GL_NVX_gpu_memory_info) allow easy queries after context creation. With
this extension it is a bit of a pain for a portable application to query
the information after context creation.
RESOLVED. Add versions of the queries that implicitly take the
display, screen, and renderer from the currently bound context.
14) Why not make the queries from issue #13 GL functions (instead of GLX)?
RESOLVED. It is fairly compelling for the post-creation queries to
just use glGetInteger and glGetString. However, the GL enums and
the GLX enums would have different names and would almost certainly
have different values. It seems like this would cause more problems
than it would solve.
15) Should the string queries be required to return the same values as
glGetString(GL_VENDOR) and glGetString(GL_RENDERER)?
UNRESOLVED. This may be useful for applications that already do
device detection based on these strings.
16) What type should the value parameter of glXQueryRendererIntegerMESA
and glXQueryCurrentRendererIntegerMESA be?
UNRESOLVED. Other similar GLX query functions just use int or
unsigned int, so that's what this extension uses for now. However,
an expeclitly sized value, such as uint32_t or uint64_t, seems
preferable.
17) What about SoCs and other systems that don't have PCI?
RESOLVED. The GLX_RENDERER_VENDOR_ID_MESA and
GLX_RENDERER_DEVICE_ID_MESA integer queries may return 0xFFFFFFFF if a
PCI ID either does not exist or is not available. Implementations
should make every attempt to return as much information as is
possible. For example, if the implementation is running on a non-PCI
SoC with a Qualcomm GPU, GLX_RENDERER_VENDOR_ID_MESA should return
0x5143, but GLX_RENDERER_DEVICE_ID_MESA will return 0xFFFFFFFF.
Revision History
Version 1, 2012/08/27 - Initial version
Version 2, 2012/09/04 - Specify behavior of implementations that
do not support certain profiles.
Change wording of issue #8 to be more
clear.
Make some wording changes to issue #10 to
clarify the resolution a bit.
Version 3, 2012/09/23 - Add issue #11 regarding multi-GPU systems.
Version 4, 2013/02/01 - Add issue #12 regarding texture / renderbuffer
format queries.
Version 5, 2013/02/14 - Add issues #13 and #14 regarding simpler queries
after the context is created and made current.
Add issue #15 regarding the string query.
Add issue #16 regarding the value type returned
by the Integer functions.
Version 6, 2013/10/25 - Fix a typo. Update the list of functions to
which the new enums can be passed. The "Current"
versions were previously missing.
Version 7, 2013/11/07 - Fix a couple more typos. Add issue #17 regarding
the PCI queries on systems that don't have PCI.
Version 8, 2014/02/14 - Fix a couple typos. GLX_RENDER_ID_MESA should
read GLX_RENDERER_ID_MESA. The VENDOR/DEVICE_ID
example given in issue #17 should be 0x5143 and
0xFFFFFFFF respectively.
Version 9, 2018/11/09 - Remove GLX_RENDERER_ID_MESA, which has never been
implemented. Remove the unnecessary interactions
with the GLX GLES profile extensions. Note the
official GL extension number. Specify the section
of the GLX spec to modify.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_release_buffers.spec
+85
View File
@@ -0,0 +1,85 @@
Name
MESA_release_buffers
Name Strings
GLX_MESA_release_buffers
Contact
Brian Paul (brian.paul 'at' tungstengraphics.com)
Status
Shipping since Mesa 2.0 in October, 1996.
Version
Last Modified Date: 8 June 2000
Number
217
Dependencies
OpenGL 1.0 or later is required.
GLX 1.0 or later is required.
Overview
Mesa's implementation of GLX is entirely implemented on the client side.
Therefore, Mesa cannot immediately detect when an X window or pixmap is
destroyed in order to free any ancillary data associated with the window
or pixmap.
The glxMesaReleaseBuffers() function can be used to explicitly indicate
when the back color buffer, depth buffer, stencil buffer, and/or accumu-
lation buffer associated with a drawable can be freed.
IP Status
Open-source; freely implementable.
Issues
None.
New Procedures and Functions
Bool glXReleaseBuffersMESA( Display *dpy, GLXDrawable d );
New Tokens
None.
Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors)
The function
Bool glXReleaseBuffersMESA( Display *dpy, GLXDrawable d );
causes all software ancillary buffers (back buffer, depth, stencil,
accum, etc) associated with the named drawable to be immediately
deallocated. True is returned if <d> is a valid Mesa GLX drawable,
else False is returned. After calling glXReleaseBuffersMESA, the
drawable should no longer be used for GL rendering. Results of
attempting to do so are undefined.
GLX Protocol
None, since this is a client-side operation.
Errors
None.
New State
None.
Revision History
8 June 2000 - initial specification
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_sampler_objects.spec
+105
View File
@@ -0,0 +1,105 @@
Name
MESA_sampler_objects
Name Strings
GL_MESA_sampler_objects
Contact
Adam Jackson <ajax@redhat.com>
Contributors
Emma Anholt
The contributors to ARB_sampler_objects and OpenGL ES 3
Status
Shipping
Version
Last Modified Date: 14 Sep 2021
Author Revision: 3
Number
TBD
Dependencies
OpenGL ES 2.0 is required.
This extension interacts with:
- EXT_shadow_samplers
- EXT_texture_filter_anisotropic
- EXT_texture_sRGB_decode
- OES_texture_border_clamp
Overview
This extension makes the sampler object subset of OpenGL ES 3.0 available
in OpenGL ES 2.0 contexts. As the intent is to allow access to the API
without necessarily requiring additional renderer functionality, some
sampler state that would be mandatory in GLES 3 is dependent on the
presence of additional extensions. Under GLES 3.0 or above this extension's
name string may be exposed for compatibility, but it is otherwise without
effect.
Refer to the OpenGL ES 3.0 specification for API details not covered here.
New Procedures and Functions
void glGenSamplers (GLsizei count, GLuint *samplers);
void glDeleteSamplers (GLsizei count, const GLuint *samplers);
GLboolean glIsSampler (GLuint sampler);
void glBindSampler (GLuint unit, GLuint sampler);
void glSamplerParameteri (GLuint sampler, GLenum pname, GLint param);
void glSamplerParameteriv (GLuint sampler, GLenum pname, const GLint *param);
void glSamplerParameterf (GLuint sampler, GLenum pname, GLfloat param);
void glSamplerParameterfv (GLuint sampler, GLenum pname, const GLfloat *param);
void glGetSamplerParameteriv (GLuint sampler, GLenum pname, GLint *params);
void glGetSamplerParameterfv (GLuint sampler, GLenum pname, GLfloat *params);
Note that these names are exactly as in ES3, with no MESA suffix.
New Tokens
SAMPLER_BINDING 0x8919
Interactions
If EXT_shadow_samplers is not supported then TEXTURE_COMPARE_MODE and
TEXTURE_COMPARE_FUNC will generate INVALID_ENUM.
If EXT_texture_filter_anisotropic is not supported then
TEXTURE_MAX_ANISOTROPY_EXT will generate INVALID_ENUM.
If EXT_texture_sRGB_decode is not supported then TEXTURE_SRGB_DECODE_EXT
will generate INVALID_ENUM.
If OES_texture_border_clamp is not supported then TEXTURE_BORDER_COLOR
will generate INVALID_ENUM.
Issues
1) Why bother?
Sampler objects, at least in Mesa, are generically supported without any
driver-dependent requirements, so enabling this is essentially free. This
simplifies application support for otherwise GLES2 hardware, and for
drivers in development that haven't yet achieved GLES3.
Revision History
Rev. Date Author Changes
---- -------- -------- ---------------------------------------------
1 2019/10/22 ajax Initial revision
2 2019/11/14 ajax Add extension interactions:
- EXT_shadow_samplers
- EXT_texture_filter_anisotropic
- EXT_texture_sRGB_decode
- OES_texture_border_clamp
3 2021/09/14 ajax Expand the justification and ES3 interaction
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_shader_integer_functions.txt
+522
View File
@@ -0,0 +1,522 @@
Name
MESA_shader_integer_functions
Name Strings
GL_MESA_shader_integer_functions
Contact
Ian Romanick <ian.d.romanick@intel.com>
Contributors
All the contributors of GL_ARB_gpu_shader5
Status
Supported by all GLSL 1.30 capable drivers in Mesa 12.1 and later
Version
Version 3, March 31, 2017
Number
OpenGL Extension #495
Dependencies
This extension is written against the OpenGL 3.2 (Compatibility Profile)
Specification.
This extension is written against Version 1.50 (Revision 09) of the OpenGL
Shading Language Specification.
GLSL 1.30 (OpenGL) or GLSL ES 3.00 (OpenGL ES) is required.
This extension interacts with ARB_gpu_shader5.
This extension interacts with ARB_gpu_shader_fp64.
This extension interacts with NV_gpu_shader5.
Overview
GL_ARB_gpu_shader5 extends GLSL in a number of useful ways. Much of this
added functionality requires significant hardware support. There are many
aspects, however, that can be easily implemented on any GPU with "real"
integer support (as opposed to simulating integers using floating point
calculations).
This extension provides a set of new features to the OpenGL Shading
Language to support capabilities of these GPUs, extending the
capabilities of version 1.30 of the OpenGL Shading Language and version
3.00 of the OpenGL ES Shading Language. Shaders using the new
functionality provided by this extension should enable this
functionality via the construct
#extension GL_MESA_shader_integer_functions : require (or enable)
This extension provides a variety of new features for all shader types,
including:
* support for implicitly converting signed integer types to unsigned
types, as well as more general implicit conversion and function
overloading infrastructure to support new data types introduced by
other extensions;
* new built-in functions supporting:
* splitting a floating-point number into a significand and exponent
(frexp), or building a floating-point number from a significand and
exponent (ldexp);
* integer bitfield manipulation, including functions to find the
position of the most or least significant set bit, count the number
of one bits, and bitfield insertion, extraction, and reversal;
* extended integer precision math, including add with carry, subtract
with borrow, and extenended multiplication;
The resulting extension is a strict subset of GL_ARB_gpu_shader5.
IP Status
No known IP claims.
New Procedures and Functions
None
New Tokens
None
Additions to Chapter 2 of the OpenGL 3.2 (Compatibility Profile) Specification
(OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 3.2 (Compatibility Profile) Specification
(Rasterization)
None.
Additions to Chapter 4 of the OpenGL 3.2 (Compatibility Profile) Specification
(Per-Fragment Operations and the Frame Buffer)
None.
Additions to Chapter 5 of the OpenGL 3.2 (Compatibility Profile) Specification
(Special Functions)
None.
Additions to Chapter 6 of the OpenGL 3.2 (Compatibility Profile) Specification
(State and State Requests)
None.
Additions to Appendix A of the OpenGL 3.2 (Compatibility Profile)
Specification (Invariance)
None.
Additions to the AGL/GLX/WGL Specifications
None.
Modifications to The OpenGL Shading Language Specification, Version 1.50
(Revision 09)
Including the following line in a shader can be used to control the
language features described in this extension:
#extension GL_MESA_shader_integer_functions : <behavior>
where <behavior> is as specified in section 3.3.
New preprocessor #defines are added to the OpenGL Shading Language:
#define GL_MESA_shader_integer_functions 1
Modify Section 4.1.10, Implicit Conversions, p. 27
(modify table of implicit conversions)
Can be implicitly
Type of expression converted to
--------------------- -----------------
int uint, float
ivec2 uvec2, vec2
ivec3 uvec3, vec3
ivec4 uvec4, vec4
uint float
uvec2 vec2
uvec3 vec3
uvec4 vec4
(modify second paragraph of the section) No implicit conversions are
provided to convert from unsigned to signed integer types or from
floating-point to integer types. There are no implicit array or structure
conversions.
(insert before the final paragraph of the section) When performing
implicit conversion for binary operators, there may be multiple data types
to which the two operands can be converted. For example, when adding an
int value to a uint value, both values can be implicitly converted to uint
and float. In such cases, a floating-point type is chosen if either
operand has a floating-point type. Otherwise, an unsigned integer type is
chosen if either operand has an unsigned integer type. Otherwise, a
signed integer type is chosen.
Modify Section 5.9, Expressions, p. 57
(modify bulleted list as follows, adding support for implicit conversion
between signed and unsigned types)
Expressions in the shading language are built from the following:
* Constants of type bool, int, int64_t, uint, uint64_t, float, all vector
types, and all matrix types.
...
* The operator modulus (%) operates on signed or unsigned integer scalars
or vectors. If the fundamental types of the operands do not match, the
conversions from Section 4.1.10 "Implicit Conversions" are applied to
produce matching types. ...
Modify Section 6.1, Function Definitions, p. 63
(modify description of overloading, beginning at the top of p. 64)
Function names can be overloaded. The same function name can be used for
multiple functions, as long as the parameter types differ. If a function
name is declared twice with the same parameter types, then the return
types and all qualifiers must also match, and it is the same function
being declared. For example,
vec4 f(in vec4 x, out vec4 y); // (A)
vec4 f(in vec4 x, out uvec4 y); // (B) okay, different argument type
vec4 f(in ivec4 x, out uvec4 y); // (C) okay, different argument type
int f(in vec4 x, out ivec4 y); // error, only return type differs
vec4 f(in vec4 x, in vec4 y); // error, only qualifier differs
vec4 f(const in vec4 x, out vec4 y); // error, only qualifier differs
When function calls are resolved, an exact type match for all the
arguments is sought. If an exact match is found, all other functions are
ignored, and the exact match is used. If no exact match is found, then
the implicit conversions in Section 4.1.10 (Implicit Conversions) will be
applied to find a match. Mismatched types on input parameters (in or
inout or default) must have a conversion from the calling argument type
to the formal parameter type. Mismatched types on output parameters (out
or inout) must have a conversion from the formal parameter type to the
calling argument type.
If implicit conversions can be used to find more than one matching
function, a single best-matching function is sought. To determine a best
match, the conversions between calling argument and formal parameter
types are compared for each function argument and pair of matching
functions. After these comparisons are performed, each pair of matching
functions are compared. A function definition A is considered a better
match than function definition B if:
* for at least one function argument, the conversion for that argument
in A is better than the corresponding conversion in B; and
* there is no function argument for which the conversion in B is better
than the corresponding conversion in A.
If a single function definition is considered a better match than every
other matching function definition, it will be used. Otherwise, a
semantic error occurs and the shader will fail to compile.
To determine whether the conversion for a single argument in one match is
better than that for another match, the following rules are applied, in
order:
1. An exact match is better than a match involving any implicit
conversion.
2. A match involving an implicit conversion from float to double is
better than a match involving any other implicit conversion.
3. A match involving an implicit conversion from either int or uint to
float is better than a match involving an implicit conversion from
either int or uint to double.
If none of the rules above apply to a particular pair of conversions,
neither conversion is considered better than the other.
For the function prototypes (A), (B), and (C) above, the following
examples show how the rules apply to different sets of calling argument
types:
f(vec4, vec4); // exact match of vec4 f(in vec4 x, out vec4 y)
f(vec4, uvec4); // exact match of vec4 f(in vec4 x, out ivec4 y)
f(vec4, ivec4); // matched to vec4 f(in vec4 x, out vec4 y)
// (C) not relevant, can't convert vec4 to
// ivec4. (A) better than (B) for 2nd
// argument (rule 2), same on first argument.
f(ivec4, vec4); // NOT matched. All three match by implicit
// conversion. (C) is better than (A) and (B)
// on the first argument. (A) is better than
// (B) and (C).
Modify Section 8.3, Common Functions, p. 84
(add support for single-precision frexp and ldexp functions)
Syntax:
genType frexp(genType x, out genIType exp);
genType ldexp(genType x, in genIType exp);
The function frexp() splits each single-precision floating-point number in
<x> into a binary significand, a floating-point number in the range [0.5,
1.0), and an integral exponent of two, such that:
x = significand * 2 ^ exponent
The significand is returned by the function; the exponent is returned in
the parameter <exp>. For a floating-point value of zero, the significant
and exponent are both zero. For a floating-point value that is an
infinity or is not a number, the results of frexp() are undefined.
If the input <x> is a vector, this operation is performed in a
component-wise manner; the value returned by the function and the value
written to <exp> are vectors with the same number of components as <x>.
The function ldexp() builds a single-precision floating-point number from
each significand component in <x> and the corresponding integral exponent
of two in <exp>, returning:
significand * 2 ^ exponent
If this product is too large to be represented as a single-precision
floating-point value, the result is considered undefined.
If the input <x> is a vector, this operation is performed in a
component-wise manner; the value passed in <exp> and returned by the
function are vectors with the same number of components as <x>.
(add support for new integer built-in functions)
Syntax:
genIType bitfieldExtract(genIType value, int offset, int bits);
genUType bitfieldExtract(genUType value, int offset, int bits);
genIType bitfieldInsert(genIType base, genIType insert, int offset,
int bits);
genUType bitfieldInsert(genUType base, genUType insert, int offset,
int bits);
genIType bitfieldReverse(genIType value);
genUType bitfieldReverse(genUType value);
genIType bitCount(genIType value);
genIType bitCount(genUType value);
genIType findLSB(genIType value);
genIType findLSB(genUType value);
genIType findMSB(genIType value);
genIType findMSB(genUType value);
The function bitfieldExtract() extracts bits <offset> through
<offset>+<bits>-1 from each component in <value>, returning them in the
least significant bits of corresponding component of the result. For
unsigned data types, the most significant bits of the result will be set
to zero. For signed data types, the most significant bits will be set to
the value of bit <offset>+<base>-1. If <bits> is zero, the result will be
zero. The result will be undefined if <offset> or <bits> is negative, or
if the sum of <offset> and <bits> is greater than the number of bits used
to store the operand. Note that for vector versions of bitfieldExtract(),
a single pair of <offset> and <bits> values is shared for all components.
The function bitfieldInsert() inserts the <bits> least significant bits of
each component of <insert> into the corresponding component of <base>.
The result will have bits numbered <offset> through <offset>+<bits>-1
taken from bits 0 through <bits>-1 of <insert>, and all other bits taken
directly from the corresponding bits of <base>. If <bits> is zero, the
result will simply be <base>. The result will be undefined if <offset> or
<bits> is negative, or if the sum of <offset> and <bits> is greater than
the number of bits used to store the operand. Note that for vector
versions of bitfieldInsert(), a single pair of <offset> and <bits> values
is shared for all components.
The function bitfieldReverse() reverses the bits of <value>. The bit
numbered <n> of the result will be taken from bit (<bits>-1)-<n> of
<value>, where <bits> is the total number of bits used to represent
<value>.
The function bitCount() returns the number of one bits in the binary
representation of <value>.
The function findLSB() returns the bit number of the least significant one
bit in the binary representation of <value>. If <value> is zero, -1 will
be returned.
The function findMSB() returns the bit number of the most significant bit
in the binary representation of <value>. For positive integers, the
result will be the bit number of the most significant one bit. For
negative integers, the result will be the bit number of the most
significant zero bit. For a <value> of zero or negative one, -1 will be
returned.
(support for unsigned integer add/subtract with carry-out)
Syntax:
genUType uaddCarry(genUType x, genUType y, out genUType carry);
genUType usubBorrow(genUType x, genUType y, out genUType borrow);
The function uaddCarry() adds 32-bit unsigned integers or vectors <x> and
<y>, returning the sum modulo 2^32. The value <carry> is set to zero if
the sum was less than 2^32, or one otherwise.
The function usubBorrow() subtracts the 32-bit unsigned integer or vector
<y> from <x>, returning the difference if non-negative or 2^32 plus the
difference, otherwise. The value <borrow> is set to zero if x >= y, or
one otherwise.
(support for signed and unsigned multiplies, with 32-bit inputs and a
64-bit result spanning two 32-bit outputs)
Syntax:
void umulExtended(genUType x, genUType y, out genUType msb,
out genUType lsb);
void imulExtended(genIType x, genIType y, out genIType msb,
out genIType lsb);
The functions umulExtended() and imulExtended() multiply 32-bit unsigned
or signed integers or vectors <x> and <y>, producing a 64-bit result. The
32 least significant bits are returned in <lsb>; the 32 most significant
bits are returned in <msb>.
GLX Protocol
None.
Dependencies on ARB_gpu_shader_fp64
This extension, ARB_gpu_shader_fp64, and NV_gpu_shader5 all modify the set
of implicit conversions supported in the OpenGL Shading Language. If more
than one of these extensions is supported, an expression of one type may
be converted to another type if that conversion is allowed by any of these
specifications.
If ARB_gpu_shader_fp64 or a similar extension introducing new data types
is not supported, the function overloading rule in the GLSL specification
preferring promotion an input parameters to smaller type to a larger type
is never applicable, as all data types are of the same size. That rule
and the example referring to "double" should be removed.
Dependencies on NV_gpu_shader5
This extension, ARB_gpu_shader_fp64, and NV_gpu_shader5 all modify the set
of implicit conversions supported in the OpenGL Shading Language. If more
than one of these extensions is supported, an expression of one type may
be converted to another type if that conversion is allowed by any of these
specifications.
If NV_gpu_shader5 is supported, integer data types are supported with four
different precisions (8-, 16, 32-, and 64-bit) and floating-point data
types are supported with three different precisions (16-, 32-, and
64-bit). The extension adds the following rule for output parameters,
which is similar to the one present in this extension for input
parameters:
5. If the formal parameters in both matches are output parameters, a
conversion from a type with a larger number of bits per component is
better than a conversion from a type with a smaller number of bits
per component. For example, a conversion from an "int16_t" formal
parameter type to "int" is better than one from an "int8_t" formal
parameter type to "int".
Such a rule is not provided in this extension because there is no
combination of types in this extension and ARB_gpu_shader_fp64 where this
rule has any effect.
Errors
None
New State
None
New Implementation Dependent State
None
Issues
(1) What should this extension be called?
UNRESOLVED. This extension borrows from GL_ARB_gpu_shader5, so creating
some sort of a play on that name would be viable. However, nothing in
this extension should require SM5 hardware, so such a name would be a
little misleading and weird.
Since the primary purpose is to add integer related functions from
GL_ARB_gpu_shader5, call this extension GL_MESA_shader_integer_functions
for now.
(2) Why is some of the formatting in this extension weird?
RESOLVED: This extension is formatted to minimize the differences (as
reported by 'diff --side-by-side -W180') with the GL_ARB_gpu_shader5
specification.
(3) Should ldexp and frexp be included?
RESOLVED: Yes. Few GPUs have native instructions to implement these
functions. These are generally implemented using existing GLSL built-in
functions and the other functions provided by this extension.
(4) Should umulExtended and imulExtended be included?
RESOLVED: Yes. These functions should be implementable on any GPU that
can support the rest of this extension, but the implementation may be
complex. The implementation on a GPU that only supports 32bit x 32bit =
32bit multiplication would be quite expensive. However, many GPUs
(including OpenGL 4.0 GPUs that already support this function) have a
32bit x 16bit = 48bit multiplier. The implementation there is only
trivially more expensive than regular 32bit multiplication.
(5) Should the pack and unpack functions be included?
RESOLVED: No. These functions are already available via
GL_ARB_shading_language_packing.
(6) Should the "BitsTo" functions be included?
RESOLVED: No. These functions are already available via
GL_ARB_shader_bit_encoding.
Revision History
Rev. Date Author Changes
---- ----------- -------- -----------------------------------------
3 31-Mar-2017 Jon Leech Add ES support (OpenGL-Registry/issues/3)
2 7-Jul-2016 idr Fix typo in #extension line
1 20-Jun-2016 idr Initial version based on GL_ARB_gpu_shader5.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_swap_control.spec
+129
View File
@@ -0,0 +1,129 @@
Name
MESA_swap_control
Name Strings
GLX_MESA_swap_control
Contact
Ian Romanick, IBM, idr at us.ibm.com
Status
Deployed in DRI drivers post-XFree86 4.3.
Version
Date: 5/1/2003 Revision: 1.1
Number
???
Dependencies
None
Based on GLX_SGI_swap_control version 1.9 and WGL_EXT_swap_control
version 1.5.
Overview
This extension allows an application to specify a minimum periodicity
of color buffer swaps, measured in video frame periods.
Issues
* Should implementations that export GLX_MESA_swap_control also export
GL_EXT_swap_control for compatibility with WGL_EXT_swap_control?
UNRESOLVED.
New Procedures and Functions
int glXSwapIntervalMESA(unsigned int interval)
int glXGetSwapIntervalMESA(void)
New Tokens
None
Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation)
None
Additions to Chapter 3 of the 1.4 GL Specification (Rasterization)
None
Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations
and the Framebuffer)
None
Additions to Chapter 5 of the 1.4 GL Specification (Special Functions)
None
Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests)
None
Additions to the GLX 1.3 Specification
[Add the following to Section 3.3.10 of the GLX Specification (Double
Buffering)]
glXSwapIntervalMESA specifies the minimum number of video frame periods
per buffer swap. (e.g. a value of two means that the color buffers
will be swapped at most every other video frame.) A return value
of zero indicates success; otherwise an error occurred. The interval
takes effect when glXSwapBuffers is first called subsequent to the
glXSwapIntervalMESA call.
A video frame period is the time required by the monitor to display a
full frame of video data. In the case of an interlaced monitor,
this is typically the time required to display both the even and odd
fields of a frame of video data.
If <interval> is set to a value of 0, buffer swaps are not synchro-
nized to a video frame. The <interval> value is silently clamped to
the maximum implementation-dependent value supported before being
stored.
The swap interval is not part of the render context state. It cannot
be pushed or popped. The current swap interval for the window
associated with the current context can be obtained by calling
glXGetSwapIntervalMESA. The default swap interval is 0.
On XFree86, setting the environment variable LIBGL_THROTTLE_REFRESH sets
the swap interval to 1.
Errors
glXSwapIntervalMESA returns GLX_BAD_CONTEXT if there is no current
GLXContext or if the current context is not a direct rendering context.
GLX Protocol
None. This extension only extends to direct rendering contexts.
New State
Get Value Get Command Type Initial Value
--------- ----------- ---- -------------
[swap interval] GetSwapInterval Z+ 0
New Implementation Dependent State
None
Revision History
1.1, 5/1/03 Added the issues section and contact information.
Changed the default swap interval to 0.
1.0, 3/17/03 Initial version based on GLX_SGI_swap_control and
WGL_EXT_swap_control.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_texture_const_bandwidth.spec
+83
View File
@@ -0,0 +1,83 @@
Name
MESA_texture_const_bandwidth
Name Strings
GL_MESA_texture_const_bandwidth
Contact
Rob Clark <robdclark@chromium.org>
Contributors
Rob Clark, Google
Lina Versace, Google
Tapani Pälli, Intel
Status
Proposal
Version
Version 1, September, 2023
Number
tbd
Dependencies
Requires EXT_memory_object.
Overview
The use of data dependent bandwidth compressed formats (UBWC, AFBC, etc)
can introduce a form of side-channel, in that the bandwidth used for
texture access is dependent on the texture's contents. In some cases
an application may want to disable the use of data dependent formats on
specific textures.
For that purpose, this extension extends EXT_memory_object to introduce
a new <param> CONST_BW_TILING_MESA.
IP Status
None
Issues
None
New Procedures and Functions
None
New Types
None
New Tokens
Returned in the <params> parameter of GetInternalFormativ or
GetInternalFormati64v when the <pname> parameter is TILING_TYPES_EXT,
returned in the <params> parameter of GetTexParameter{if}v,
GetTexParameterI{i ui}v, GetTextureParameter{if}v, and
GetTextureParameterI{i ui}v when the <pname> parameter is
TEXTURE_TILING_EXT, and accepted by the <params> parameter of
TexParameter{ifx}{v}, TexParameterI{i ui}v, TextureParameter{if}{v},
TextureParameterI{i ui}v when the <pname> parameter is
TEXTURE_TILING_EXT:
CONST_BW_TILING_MESA 0x8BBE
Errors
None
Revision History
Version 1, 2023-9-28 (Rob Clark)
Initial draft.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_texture_signed_rgba.spec
+214
View File
@@ -0,0 +1,214 @@
Name
MESA_texture_signed_rgba
Name Strings
GL_MESA_texture_signed_rgba
Contact
Notice
IP Status
No known IP issues
Status
Version
0.3, 2009-03-24
Number
Not assigned ?
Dependencies
Written based on the wording of the OpenGL 2.0 specification.
This extension trivially interacts with ARB_texture_float.
This extension shares some language with ARB_texture_compression_rgtc
but does not depend on it.
Overview
OpenGL prior to 3.1 does not support any signed texture formats.
ARB_texture_compression_rgtc introduces some compressed red and
red_green signed formats but no uncompressed ones, which might
still be useful. NV_texture_shader adds signed texture formats,
but also a lot of functionality which has been superseded by fragment
shaders.
It is usually possible to get the same functionality
using a unsigned format by doing scale and bias in a shader, but this
is undesirable since modern hardware has direct support for this.
This extension adds a signed 4-channel texture format by backporting
the relevant features from OpenGL 3.1, as a means to support this in
OpenGL implementations only supporting older versions.
Issues
1) What should this extension be called?
RESOLVED: MESA_texture_signed_rgba seems reasonable.
The rgba part is there because only 4 channel format is supported.
2) Should the full set of signed formats (alpha, luminance, rgb, etc.)
be supported?
RESOLVED: NO. To keep this extension simple, only add the most
universal format, rgba. alpha/luminance can't be trivially supported
since OpenGL 3.1 does not support them any longer, and there is some
implied dependency on ARB_texture_rg for red/red_green formats so
avoid all this. Likewise, only 8 bits per channel is supported.
3) Should this extension use new enums for the texture formats?
RESOLVED: NO. Same enums as those used in OpenGL 3.1.
4) How are signed integer values mapped to floating-point values?
RESOLVED: Same as described in issue 5) of
ARB_texture_compression_rgtc (quote):
A signed 8-bit two's complement value X is computed to
a floating-point value Xf with the formula:
{ X / 127.0, X > -128
Xf = {
{ -1.0, X == -128
This conversion means -1, 0, and +1 are all exactly representable,
however -128 and -127 both map to -1.0. Mapping -128 to -1.0
avoids the numerical awkwardness of have a representable value
slightly more negative than -1.0.
This conversion is intentionally NOT the "byte" conversion listed
in Table 2.9 for component conversions. That conversion says:
Xf = (2*X + 1) / 255.0
The Table 2.9 conversion is incapable of exactly representing
zero.
(Difference to ARB_texture_compression_rgtc):
This is the same mapping as OpenGL 3.1 uses.
This is also different to what NV_texture_shader used.
The above mapping should be considered the reference, but there
is some leeway so other mappings are allowed for implementations which
cannot do this. Particularly the mapping given in NV_texture_shader or
the standard OpenGL byte/float mapping is considered acceptable too, as
might be a mapping which represents -1.0 by -128, 0.0 by 0 and 1.0 by
127 (that is, uses different scale factors for negative and positive
numbers).
Also, it is ok to store incoming GL_BYTE user data as-is, without
converting to GL_FLOAT (using the standard OpenGL float/byte mapping)
and converting back (using the mapping described here).
Other than those subtle issues there are no other non-standard
conversions used, so when using for instance CopyTexImage2D with
a framebuffer clamped to [0,1] all converted numbers will be in the range
[0, 127] (and not scaled and biased).
5) How will signed components resulting from RGBA8_SNORM texture
fetches interact with fragment coloring?
RESOLVED: Same as described in issue 6) of
ARB_texture_compression_rgtc (quote):
The specification language for this extension is silent
about clamping behavior leaving this to the core specification
and other extensions. The clamping or lack of clamping is left
to the core specification and other extensions.
For assembly program extensions supporting texture fetches
(ARB_fragment_program, NV_fragment_program, NV_vertex_program3,
etc.) or the OpenGL Shading Language, these signed formats will
appear as expected with unclamped signed components as a result
of a texture fetch instruction.
If ARB_color_buffer_float is supported, its clamping controls
will apply.
NV_texture_shader extension, if supported, adds support for
fixed-point textures with signed components and relaxed the
fixed-function texture environment clamping appropriately. If the
NV_texture_shader extension is supported, its specified behavior
for the texture environment applies where intermediate values
are clamped to [-1,1] unless stated otherwise as in the case
of explicitly clamped to [0,1] for GL_COMBINE. or clamping the
linear interpolation weight to [0,1] for GL_DECAL and GL_BLEND.
Otherwise, the conventional core texture environment clamps
incoming, intermediate, and output color components to [0,1].
This implies that the conventional texture environment
functionality of unextended OpenGL 1.5 or OpenGL 2.0 without
using GLSL (and with none of the extensions referred to above)
is unable to make proper use of the signed texture formats added
by this extension because the conventional texture environment
requires texture source colors to be clamped to [0,1]. Texture
filtering of these signed formats would be still signed, but
negative values generated post-filtering would be clamped to
zero by the core texture environment functionality. The
expectation is clearly that this extension would be co-implemented
with one of the previously referred to extensions or used with
GLSL for the new signed formats to be useful.
6) Should the RGBA_SNORM tokens also be accepted by CopyTexImage
functions?
RESOLVED: YES.
7) What to do with GetTexParameter if ARB_texture_float is supported,
in particular what datatype should this return for TEXTURE_RED_TYPE_ARB,
TEXTURE_GREEN_TYPE_ARB, TEXTURE_BLUE_TYPE_ARB, TEXTURE_ALPHA_TYPE_ARB?
RESOLVED: ARB_texture_float states type is either NONE,
UNSIGNED_NORMALIZED_ARB, or FLOAT. This extension adds a new enum,
SIGNED_NORMALIZED, which will be returned accordingly. This is the
same behaviour as in OpenGL 3.1.
New Tokens
Accepted by the <internalformat> parameter of
TexImage1D, TexImage2D, TexImage3D, CopyTexImage1D, and CopyTexImage2D:
RGBA_SNORM 0x8F93
RGBA8_SNORM 0x8F97
Returned by the <params> parameter of GetTexLevelParameter:
SIGNED_NORMALIZED 0x8F9C
Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization):
-- Section 3.8.1, Texture Image Specification
Add to Table 3.16 (page 154): Sized internal formats
Sized Base R G B A L I D
Internal Format Internal Format bits bits bits bits bits bits bits
--------------- --------------- ---- ---- ---- ---- ---- ---- ----
RGBA8_SNORM RGBA 8 8 8 8 0 0 0
Dependencies on ARB_texture_float extension:
If ARB_texture_float is supported, GetTexParameter queries with <value>
of TEXTURE_RED_TYPE_ARB, TEXTURE_GREEN_TYPE_ARB, TEXTURE_BLUE_TYPE_ARB or
TEXTURE_ALPHA_TYPE_ARB return SIGNED_NORMALIZED if
the base internal format is RGBA_SNORM.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_window_pos.spec
+126
View File
@@ -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)
local/recipes/dev/mesa-clc/source/docs/_extra/specs/MESA_ycbcr_texture.spec
+204
View File
@@ -0,0 +1,204 @@
Name
MESA_ycbcr_texture
Name Strings
GL_MESA_ycbcr_texture
Contact
Brian Paul, Tungsten Graphics, Inc. (brian.paul 'at' tungstengraphics.com)
Keith Whitwell, Tungsten Graphics, Inc. (keith 'at' tungstengraphics.com)
Status
Shipping (Mesa 4.0.4 and later)
Version
1.0
Number
TBD
Dependencies
OpenGL 1.0 or later is required
This extension is written against the OpenGL 1.4 Specification.
NV_texture_rectangle effects the definition of this extension.
Overview
This extension supports texture images stored in the YCbCr format.
There is no support for converting YCbCr images to RGB or vice versa
during pixel transfer. The texture's YCbCr colors are converted to
RGB during texture sampling, after-which, all the usual per-fragment
operations take place. Only 2D texture images are supported (not
glDrawPixels, glReadPixels, etc).
A YCbCr pixel (texel) is a 16-bit unsigned short with two components.
The first component is luminance (Y). For pixels in even-numbered
image columns, the second component is Cb. For pixels in odd-numbered
image columns, the second component is Cr. If one were to convert the
data to RGB one would need to examine two pixels from columns N and N+1
(where N is even) to deduce the RGB color.
IP Status
None
Issues
None
New Procedures and Functions
None
New Tokens
Accepted by the <internalFormat> and <format> parameters of
TexImage2D and TexSubImage2D:
YCBCR_MESA 0x8757
Accepted by the <type> parameter of TexImage2D and TexSubImage2D:
UNSIGNED_SHORT_8_8_MESA 0x85BA /* same as Apple's */
UNSIGNED_SHORT_8_8_REV_MESA 0x85BB /* same as Apple's */
Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
In section 3.6.4, Rasterization of Pixel Rectangles, on page 101,
add the following to Table 3.8 (Packed pixel formats):
type Parameter GL Data Number of Matching
Token Name Type Components Pixel Formats
-------------- ------- ---------- -------------
UNSIGNED_SHORT_8_8_MESA ushort 2 YCBCR_MESA
UNSIGNED_SHORT_8_8_REV_MESA ushort 2 YCBCR_MESA
In section 3.6.4, Rasterization of Pixel Rectangles, on page 102,
add the following to Table 3.10 (UNSIGNED_SHORT formats):
UNSIGNED_SHORT_8_8_MESA:
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+-------------------------------+-------------------------------+
| 1st | 2nd |
+-------------------------------+-------------------------------+
UNSIGNED_SHORT_8_8_REV_MESA:
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+-------------------------------+-------------------------------+
| 2nd | 1st |
+-------------------------------+-------------------------------+
In section 3.6.4, Rasterization of Pixel Rectangles, on page 104,
add the following to Table 3.12 (Packed pixel field assignments):
First Second Third Fourth
Format Element Element Element Element
------ ------- ------- ------- -------
YCBCR_MESA luminance chroma
In section 3.8.1, Texture Image Specification, on page 125, add
another item to the list of TexImage2D and TexImage3D equivalence
exceptions:
* The value of internalformat and format may be YCBCR_MESA to
indicate that the image data is in YCbCr format. type must
be either UNSIGNED_SHORT_8_8_MESA or UNSIGNED_SHORT_8_8_REV_MESA
as seen in tables 3.8 and 3.10. Table 3.12 describes the mapping
between Y and Cb/Cr to the components.
If NV_texture_rectangle is supported target may also be
TEXTURE_RECTANGLE_NV or PROXY_TEXTURE_RECTANGLE_NV.
All pixel transfer operations are bypassed. The texture is stored as
YCbCr, not RGB. Queries of the texture's red, green and blue component
sizes will return zero. The YCbCr colors are converted to RGB during
texture sampling using an implementation dependent conversion.
In section 3.8.1, Texture Image Specification, on page 126, add
another item to the list of TexImage1D and TexImage2D equivalence
exceptions:
* The value of internalformat and format can not be YCBCR_MESA.
In section 3.8.2, Alternate Texture Image Specification Commands, on
page 129, insert this paragraph after the first full paragraph on the
page:
"If the internal storage format of the image being updated by
TexSubImage2D is YCBCR_MESA then format must be YCBCR_MESA.
The error INVALID_OPERATION will be generated otherwise."
Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
Operations and the Frame Buffer)
None
Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
None
Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
State Requests)
None
Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
None
Additions to the AGL/GLX/WGL Specifications
None
GLX Protocol
None
Errors
INVALID_ENUM is generated by TexImage2D if <internalFormat> is
MESA_YCBCR but <format> is not MESA_YCBCR.
INVALID_ENUM is generated by TexImage2D if <format> is MESA_YCBCR but
<internalFormat> is not MESA_YCBCR.
INVALID_VALUE is generated by TexImage2D if <format> is MESA_YCBCR and
<internalFormat> is MESA_YCBCR and <border> is not zero.
INVALID_OPERATION is generated by TexSubImage2D if the internal image
format is YCBCR_MESA and <format> is not YCBCR_MESA.
INVALID_OPERATION is generated by CopyTexSubImage2D if the internal
image is YCBCR_MESA.
New State
Edit table 6.16 on page 231: change the type of TEXTURE_INTERNAL_FORMAT
from n x Z42 to n x Z43 to indicate that internal format may also be
YCBCR_MESA.
Revision History
20 September 2002 - Initial draft
29 April 2003 - minor updates
3 September 2003 - further clarify when YCbCr->RGB conversion takes place
19 September 2003 - a few more updates prior to submitting to extension
registry.
3 April 2004 - fix assorted inaccuracies
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/EGL_MESA_screen_surface.txt
+564
View File
@@ -0,0 +1,564 @@
Name
MESA_screen_surface
Name Strings
EGL_MESA_screen_surface
Contact
Brian Paul
To discuss, join the dri-egl@lists.freedesktop.org list.
Status
Obsolete.
Version
11 (27 January 2006)
Number
TBD
Dependencies
EGL 1.0 or later.
Overview
EGL 1.1 supports three types of drawing surfaces:
* Window surfaces
* Pixmap surfaces
* Pbuffer surfaces
This extension defines a fourth type of drawing surface:
* Screen surface
A screen surface is a surface for which the (front) color buffer can
be directly displayed (i.e. scanned out) on a monitor (such as a flat
panel or CRT). In particular the color buffer memory will be allocated
at a location in VRAM (and in a suitable format) which can be displayed
by the graphics hardware.
Note that the width and height of the screen surface need not exactly
match the monitor's current resolution. For example, while the monitor
may be configured to to show 1024x768 pixels, the associated screen
surface may be larger, such as 1200x1000. The "screen origin" attribute
will specify which region of the screen surface which is visible on the
monitor. The screen surface can be scrolled by changing this origin.
This extension also defines functions for controlling the monitor's
display mode (width, height, refresh rate, etc), and specifying which
screen surface is to be displayed on a monitor.
The new EGLModeMESA type and related functions are very similar to the
EGLConfig type and related functions. The user may get a list of
supported modes for a screen and specify the mode to be used when
displaying a screen surface.
Issues
1. Should EGL_INTERLACE be a supported mode attribute?
Arguments against:
No, this should be provided by another extension which would
also provide the mechanisms needed to play back interlaced video
material correctly on hardware that supports it.
This extension should prefer non-interlaced modes. [M. Danzer]
Arguments for:
An interlaced display can be of use without considering video
material. Being able to query whether a screen is operating in
interlaced mode can be used by applications to control their
drawing. For example: avoid drawing 1-pixel-wide horizontal lines
if screen is interlaced. [B. Paul]
Resolution: Defer for future extension?
2. Should EGL_REFRESH_RATE be a supported mode attribute?
Arguments for:
Yes, it's been shown that applications and/or users need to select
modes by this. [M. Danzer]
Many examples have been given in which it's desirable to let the
user choose from a variety of refresh rates without having to
restart/reconfigure. [B. Paul]
Arguments against:
TBD.
Resolution: Yes.
3. Exactly how should the list of modes returned by eglChooseConfigMESA
be sorted?
Current method is described in the text below. Subject to change.
Alternately, leave the sorting order undefined so that each
implementation can return the modes in order of "most desirable"
to "least desirable" which may depend on the display technology
(CRT vs LCD, etc) or other factors.
4. How should screen blanking be supported? Note that a screen can be
disabled or turned off by calling eglShowSurface(dpy, scrn,
EGL_NO_SURFACE, EGL_NO_MODE_MESA). But what about power-save mode?
I would defer this to other extensions that depend on this one.
I can imagine people wanting different semantics not just in
relation to the power management API being exposed (DPMS or whatever)
but also relating to what events can trigger EGL_CONTEXT_LOST. Also
I'm not sure whether power management commands are properly operations
on the Display or on a screen surface. [A. Jackson]
5. Should the EGL_PHYSICAL_SIZE_EGL query be kept? The size information
isn't always reliable (consider video projectors) but can still be
used to determine the pixel aspect ratio.
Resolution: Omit. The EGL 1.2 specification includes queries for
the display resolution and pixel aspect ratio.
6. Should detailed mode timing information be exposed by this API?
Probably not. Instead, offer that information in a layered extension.
7. How should the notion of a screen's "native" mode be expressed?
For example, LCD panels have a native resolution and refresh rate
that looks best but other sub-optimal resolutions may be supported.
The mode attribute EGL_OPTIMAL_MESA will be set for modes which
best match the screen. [M. Danzer]
8. Should eglQueryModeStringMESA() be included? This function returns
a human-readable string which corresponds to an EGLMode.
Arguments for:
A mode name such as "HDTV-720P" might mean more to users than
"1280x720@60Hz" if the later were generated via code.
Arguments against:
There's no standard syntax for the strings. May cause more
trouble than it's worth.
Postpone for future extension. [A. Jackson]
Latest discussion leaning toward omitting this function.
9. Should we use "Get" or "Query" for functions which return state?
The EGL 1.x specification doesn't seem to be totally consistent
in this regard, but "Query" is used more often.
Use "Get" for mode-related queries (as for EGLConfigs) but "Query"
for everything else.
10. What should be the default size for screen surfaces?
For Pbuffer surfaces the default width and height are zero.
We'll do the same for screen surfaces. Since there's no function
to resize surfaces it's useless to have a 0x0 screen, but this isn't
a situation that'll normally be encountered.
11. Should there be a function for resizing a screen surface?
Suppose one wants to change the screen's size in the EGL application.
Also suppose there's a hardware restriction such that only one screen
surface can exist at a time (either for lack of memory or because of
memory layout restrictions).
The basic idea is that the currently displayed screen surface must
be deallocated before a new one can be created. Perhaps a resize
function would work better?
12. How should sub-pixel LCD color information be made available?
What about the display's gamma value?
Perhaps expose as additional read-only mode attributes.
Perhaps postpone for a layered extension.
13. What happens if the user attempts to delete a screen surface that
is currently being shown?
Spec currently says that's illegal and that an error (TBD) will be
generated.
14. What if the physical screen size can't be determined? Should
a query of EGL_PHYSICAL_SIZE_MESA return [0,0]?
Obsolete: EGL_PHYSICAL_SIZE_MESA not used.
15. Suppose the device's number of RAMDACs is different from the
number of output ports. For example, a graphics card with
two RAMDACs but three ports (VGA, DVI, TV).
Address this in a follow-on extension. [Matthias Hopf]
16. How should we deal with on-the-fly device changes? For example,
the monitor being unplugged and replaced by another with different
characteristics?
A HAL event could be received via DBUS in the application [J. Smirl,
A. Jackson].
Should there be an EGL mechanism for detecting this? Maybe an
EGL_SCREEN_LOST error (similar to EGL_CONTEXT_LOST) can be recorded
when there's a screen change. At least then the application can
poll to detect this situation.
Maybe leave that to a future extension.
See also the EGL_SCREEN_COUNT_MESA query.
17. What if pixel-accurate panning is not supported (see
eglScreenPositionMESA)? [M. Danzer]
Is this a common problem? Can we ignore it for now?
18. Should eglShowSurfaceMESA be renamed to eglShowScreenSurfaceMESA?
Probably.
New Procedures and Functions
EGLBoolean eglChooseModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
const EGLint *attrib_list,
EGLModeMESA *modes, EGLint modes_size,
EGLint *num_modes)
EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLModeMESA *modes, EGLint modes_size,
EGLint *num_modes)
EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
EGLint attrib, EGLint *value)
EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens,
EGLint screens_size, EGLint *num_screens)
EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
const EGLint *attrib_list)
EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLSurface surface, EGLModeMESA mode)
EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLint x, EGLint y)
EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLint attrib, EGLint *value);
EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLSurface *surface)
EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLModeMESA *mode)
const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLMode mode);
New Types
EGLModeMESA
EGLScreenMESA
New Tokens
New error codes:
EGL_BAD_SCREEN_MESA
EGL_BAD_MODE_MESA
Screen-related tokens:
EGL_SCREEN_COUNT_MESA
EGL_SCREEN_POSITION_MESA
EGL_SCREEN_BIT_MESA
EGL_SCREEN_POSITION_GRANULARITY_MESA
Mode-related tokens:
EGL_MODE_ID_MESA
EGL_REFRESH_RATE_MESA
EGL_INTERLACED_MESA
EGL_OPTIMAL_MESA
EGL_NO_MODE_MESA
Additions to Chapter X of the EGL 1.1 Specification
[XXX this all has to be rewritten to fit into the EGL specification
and match the conventions of an EGL extension. For now, just list
all the functions with brief descriptions.]
EGLBoolean eglChooseModeMESA(EGLDisplay dpy, const EGLScreenMESA screen,
EGLint *attrib_list, EGLModeMESA *modes,
EGLint modes_size, EGLint *num_modes)
Like eglChooseConfig, returns a list of EGLModes which match the given
attribute list. This does not set the screen's current display mode.
The attribute list is a list of token/value pairs terminated with
EGL_NONE. Supported attributes include:
Name Description
--------------------- ---------------------------------------------
EGL_WIDTH Mode width (resolution)
EGL_HEIGHT Mode height (resolution)
EGL_REFRESH_RATE_MESA The mode's refresh rate, multiplied by 1000
EGL_INTERLACED_MESA 1 indicates an interlaced mode, 0 otherwise
EGL_OPTIMAL_MESA Set if the most is especially optimal for the
screen (ex. for particular LCD resolutions)
Any other token will generate the error EGL_BAD_ATTRIBUTE.
The list of modes returned by eglChooseModeMESA will be sorted
according to the following criteria. See the discussion of table 3.3
in the EGL specification for more information.
Selection Sort Sort
Attribute Default Criteria Order Priority
-------------------- -------------- ----------- ------ --------
EGL_OPTIMAL_MESA EGL_DONT_CARE Exact 1,0 1
EGL_INTERLACED_MESA EGL_DONT_CARE Exact 0,1 2
EGL_REFRESH_RATE EGL_DONT_CARE AtLeast Larger 3
EGL_WIDTH EGL_DONT_CARE AtLeast Larger 4
EGL_HEIGHT EGL_DONT_CARE AtLeast Larger 5
EGL_MODE_ID_MESA EGL_DONT_CARE Exact Smaller 6
EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLModeMESA *modes, EGLint modes_size,
EGLint *num_modes)
Like eglGetConfigs, returns a list of all modes supported by the
given screen. The returned modes will be sorted in the same manner
as for eglChooseModeMESA().
EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
EGLint attrib, EGLint *value)
Used to query mode attributes. The following attributes are supported:
Name Return value description
--------------------- ----------------------------------------------
EGL_OPTIMAL_MESA 1 indicates an optimal mode, 0 otherwise
EGL_INTERLACED_MESA 1 indicates an interlaced mode, 0 otherwise
EGL_REFRESH_RATE_MESA The mode's refresh rate, multiplied by 1000
EGL_WIDTH Mode width (resolution)
EGL_HEIGHT Mode height (resolution)
EGL_MODE_ID_MESA A unique small integer identifier for the mode
Any other token will generate the error EGL_BAD_ATTRIBUTE.
EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens,
EGLint screens_size, EGLint *num_screens)
This function returns an array of all available screen handles.
<screens_size> is the maximum number of screens to return in the
<screens> array. <num_screens> will return the number of screen handles
placed in the array, even if <screens> is NULL.
The number of screens and the availability of each may change over
time (hot-plugging). Screen handles will not be reused. When a
screen handle becomes invalid, function calls which reference an
invalid handle will generate EGL_BAD_SCREEN_MESA.
The first screen handle returned will be considered to be the primary
one.
EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
const EGLint *attrib_list)
Create a surface that can be displayed on a screen. <attrib_list> is
an array of token/value pairs terminated with EGL_NONE. Valid tokens
include:
Name Description
---------------- --------------------------------
EGL_WIDTH desired surface width in pixels
EGL_HEIGHT desired surface height in pixels
Any other token will generate the error EGL_BAD_ATTRIBUTE.
The default width and height are zero.
EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLSurface surface, EGLModeMESA mode)
This function causes a screen to show the given surface (or more
precisely, the surface's front color buffer) with the given mode.
If the surface is in any way incompatible with the mode, the error
EGL_BAD_MATCH will be generated, EGL_FALSE will be returned, and the
previous screen state will remain in effect. This might occur when
the bandwidth of the video-out subsystem is exceeded, or if the mode
specifies a width or height that's greater than the width or height
of the surface.
To disable a screen, the values EGL_NO_SURFACE and EGL_NO_MODE_MESA
be passed as the <surface> and <mode> parameters.
The values of EGL_SCREEN_POSITION_MESA are clamped to the new valid
range computed from the screen size and surface size. If the new
surface is EGL_NO_SURFACE, EGL_SCREEN_POSITION_MESA is set to [0, 0].
Attempting to delete a screen surface which is currently being
displayed will result in the error EGL_BAD_ACCESS being generated.
EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLint x, EGLint y)
Specifies the origin of the screen's view into the surface, if the
surface is larger than the screen. Valid values for x and y are
[0, surfaceWidth - screenWidth] and [0, surfaceHeight - screenHeight],
respectively.
The x and y values are also constrained to be integer multiples of the
EGL_SCREEN_POSITION_GRANULARITY_MESA values.
EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLint attrib, EGLint *value);
Used to query screen attributes. <attrib> may be one of the following:
Name Return value description
------------------------ ---------------------------------------------
EGL_SCREEN_POSITION_MESA x, y position of the screen's origin with
respect to the surface. If no surface is
attached to the screen, [0, 0] is returned.
EGL_SCREEN_POSITION_GRANULARITY_MESA
Returns the granularity, in pixels, for
which the screen position is constrained.
Any other token will generate the error EGL_BAD_ATTRIBUTE.
EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLSurface *surface)
Returns the surface currently displayed on the given screen. <surface>
may be EGL_NO_SURFACE if the screen isn't currently showing any surface.
EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
EGLModeMESA *mode)
Returns the given screen's current display mode. The mode may be
EGL_NO_MODE_MESA if the screen is currently disabled.
const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLModeMESA mode);
Returns a human-readable string for the given mode. The string is a
zero-terminated C string which the user should not attempt to free.
There is no standard syntax for mode strings. Applications should
not directly rely on mode strings.
Version History
1. 15 March 2005 - BrianP
Initial version
2. 16 March 2005 - BrianP
Removed EGL_DEPTH_MESA
Added EGL_PHYSICAL_WIDTH_MESA, EGL_PHYSICAL_HEIGHT_MESA queries
Added EGL_OPTIMAL_MESA for width/height/refresh rate selection
Added possible eglQueryModeStringMESA() function
More details of the new functions explained.
3. 18 March 2005 - BrianP
Added screen_number to eglChooseModeMESA().
Fix off by one mistake in value range for ORIGIN attributes
Added Issues section
4. 21 March 2005 - BrianP
Removed eglScreenAttribsMESA().
Added eglScreenPositionMESA() to set screen origin.
Replaced EGL_SCREEN_X/Y_OFFSET_MESA with EGL_SCREEN_POSITION_MESA.
Replaced EGL_PHYSICAL_WIDTH/HEIGHT_MESA with EGL_PHYSICAL_SIZE_MESA.
Use EGL_OPTIMAL_MESA as a new mode attribute. (Michel Danzer)
Added a few more issues.
5. 6 April 2005 - BrianP
More language for eglGetModeStringMESA().
Added issues 10, 11, 12, 13, 14.
Updated issue 3 discussion about mode sorting.
6. 22 April 2005 - BrianP
Fixed "LDC" typo.
Added issues 15, 16.
Changed dependency on EGL 1.1 to EGL 1.0
s/EGL_NUM_SCREENS_MESA/EGL_SCREEN_COUNT_MESA/
Added eglQueryDisplayMESA() to New Functions section.
Clarified language for the EGL_SCREEN_COUNT_MESA query.
7. 29 April 2005 - BrianP
Added EGLScreenMESA type and eglGetScreensMESA() function. [J. Smirl].
Replaced EGLint screen_number parameters with EGLScreenMESA screen.
Added issue 17 (pixel-accurate panning)
8. 2 May 2005 - BrianP
Removed eglQueryDisplayMESA.
Fixed a few more EGLint -> EGLScreenMESA changes.
9. 20 May 2005 - BrianP
Fixed a few typos.
Updated some open issues text.
10. 10 August 2005 - BrianP
Added EGL_SCREEN_POSITION_GRANULARITY_MESA.
11. 27 January 2006 - BrianP
EGL_PHYSICAL_SIZE_MESA removed since EGL 1.2 has a similar feature.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_agp_offset.spec
+94
View File
@@ -0,0 +1,94 @@
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
Obsolete. Effectively superseded by ARB_vertex_buffer_object.
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
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_multithread_makecurrent.spec
+158
View File
@@ -0,0 +1,158 @@
Name
MESA_multithread_makecurrent
Name Strings
GLX_MESA_multithread_makecurrent
Contact
Eric Anholt (eric@anholt.net)
Status
Obsolete.
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 through 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.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_packed_depth_stencil.spec
+230
View File
@@ -0,0 +1,230 @@
Name
MESA_packed_depth_stencil
Name Strings
GL_MESA_packed_depth_stencil
Contact
Keith Whitwell, VA Linux Systems Inc. (keithw 'at' valinux.com)
Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com)
Status
Obsolete.
Version
Number
???
Dependencies
EXT_abgr affects the definition of this extension
SGIS_texture4D affects the definition of this extension
EXT_cmyka affects the definition of this extension
ARB_packed_pixels affects the definition of this extension
Overview
Provides a mechanism for DrawPixels and ReadPixels to efficiently
transfer depth and stencil image data. Specifically, we defined new
packed pixel formats and types which pack both stencil and depth
into one value.
Issues:
1. Is this the right way to distinguish between 24/8 and 8/24
pixel formats? Should we instead provide both:
GL_DEPTH_STENCIL_MESA
GL_STENCIL_DEPTH_MESA
And perhaps just use GL_UNSIGNED_INT, GL_UNSIGNED_SHORT ?
2. If not, is it correct to use _REV to indicate that stencil
preceeds depth in the 1_15 and 8_24 formats?
3. Do we really want the GL_UNSIGNED_SHORT formats?
New Procedures and Functions
None.
New Tokens
Accepted by the <format> parameter of ReadPixels and DrawPixels:
GL_DEPTH_STENCIL_MESA 0x8750
Accepted by the <type> parameter of ReadPixels and DrawPixels:
GL_UNSIGNED_INT_24_8_MESA 0x8751
GL_UNSIGNED_INT_8_24_REV_MESA 0x8752
GL_UNSIGNED_SHORT_15_1_MESA 0x8753
GL_UNSIGNED_SHORT_1_15_REV_MESA 0x8754
Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the 1.1 Specification (Rasterization)
One entry is added to table 3.5 (DrawPixels and ReadPixels formats).
The new table is:
Target
Format Name Buffer Element Meaning and Order
----------- ------ -------------------------
COLOR_INDEX Color Color index
STENCIL_INDEX Stencil Stencil index
DEPTH_COMPONENT Depth Depth component
RED Color R component
GREEN Color G component
BLUE Color B component
ALPHA Color A component
RGB Color R, G, B components
RGBA Color R, G, B, A components
BGRA Color B, G, R, A components
ABGR_EXT Color A, B, G, R components
CMYK_EXT Color Cyan, Magenta, Yellow, Black components
CMYKA_EXT Color Cyan, Magenta, Yellow, Black, A components
LUMINANCE Color Luminance component
LUMINANCE_ALPHA Color Luminance, A components
DEPTH_STENCIL Depth, Depth component, stencil index.
Stencil
Table 3.5: DrawPixels and ReadPixels formats. The third column
gives a description of and the number and order of elements in a
group.
Add to the description of packed pixel formats:
<type> Parameter Data of Matching
Token Name Type Elements Pixel Formats
---------------- ---- -------- -------------
UNSIGNED_BYTE_3_3_2 ubyte 3 RGB
UNSIGNED_BYTE_2_3_3_REV ubyte 3 RGB
UNSIGNED_SHORT_5_6_5 ushort 3 RGB
UNSIGNED_SHORT_5_6_5_REV ushort 3 RGB
UNSIGNED_SHORT_4_4_4_4 ushort 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT
UNSIGNED_SHORT_4_4_4_4_REV ushort 4 RGBA,BGRA
UNSIGNED_SHORT_5_5_5_1 ushort 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT
UNSIGNED_SHORT_1_5_5_5_REV ushort 4 RGBA,BGRA
UNSIGNED_INT_8_8_8_8 uint 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT
UNSIGNED_INT_8_8_8_8_REV uint 4 RGBA,BGRA
UNSIGNED_INT_10_10_10_2 uint 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT
UNSIGNED_INT_2_10_10_10_REV uint 4 RGBA,BGRA
UNSIGNED_SHORT_15_1_MESA ushort 2 DEPTH_STENCIL_MESA
UNSIGNED_SHORT_1_15_REV_MESA ushort 2 DEPTH_STENCIL_MESA
UNSIGNED_SHORT_24_8_MESA ushort 2 DEPTH_STENCIL_MESA
UNSIGNED_SHORT_8_24_REV_MESA ushort 2 DEPTH_STENCIL_MESA
UNSIGNED_INT_8_24:
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+-----------------------+-----------------------------------------------------------------------+
| | |
+-----------------------+-----------------------------------------------------------------------+
first second
element element
UNSIGNED_INT_24_8:
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+----------------------------------------------------------------------+------------------------+
| | |
+----------------------------------------------------------------------+------------------------+
first second
element element
UNSIGNED_SHORT_15_1:
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+-----------------------------------------------------------+---+
| | |
+-----------------------------------------------------------+---+
first second
element element
UNSIGNED_SHORT_1_15_REV:
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+---+-----------------------------------------------------------+
| | |
+---+-----------------------------------------------------------+
second first
element element
The assignment of elements to fields in the packed pixel is as
described in the table below:
First Second Third Fourth
Format Element Element Element Element
------ ------- ------- ------- -------
RGB red green blue
RGBA red green blue alpha
BGRA blue green red alpha
ABGR_EXT alpha blue green red
CMYK_EXT cyan magenta yellow black
DEPTH_STENCIL_MESA depth stencil
Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations
and the Frame Buffer)
The new format is added to the discussion of Obtaining Pixels from the
Framebuffer. It should read " If the <format> is one of RED, GREEN,
BLUE, ALPHA, RGB, RGBA, ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, and
the GL is in color index mode, then the color index is obtained."
The new format is added to the discussion of Index Lookup. It should
read "If <format> is one of RED, GREEN, BLUE, ALPHA, RGB, RGBA,
ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, then the index is used to
reference 4 tables of color components: PIXEL_MAP_I_TO_R,
PIXEL_MAP_I_TO_G, PIXEL_MAP_I_TO_B, and PIXEL_MAP_I_TO_A."
Additions to Chapter 5 of the 1.1 Specification (Special Functions)
None
Additions to Chapter 6 of the 1.1 Specification (State and State Requests)
None
Additions to the GLX Specification
None
GLX Protocol
TBD
Errors
None
New State
None
Revision History
Version 1.0 - 23 Sep 2000
Keith's original version.
Version 1.1 - 3 Nov 2000
Brian's edits, assigned values to new enums.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_program_debug.spec
+356
View File
@@ -0,0 +1,356 @@
Name
MESA_program_debug
Name Strings
GL_MESA_program_debug
Contact
Brian Paul (brian.paul 'at' tungstengraphics.com)
Status
Obsolete.
Version
Last Modified Date: July 20, 2003
Author Revision: 1.0
Number
TBD
Dependencies
OpenGL 1.4 is required
The extension is written against the OpenGL 1.4 specification.
ARB_vertex_program or ARB_fragment_program or NV_vertex_program
or NV_fragment_program is required.
Overview
The extension provides facilities for implementing debuggers for
vertex and fragment programs.
The concept is that vertex and fragment program debuggers will be
implemented outside of the GL as a utility package. This extension
only provides the minimal hooks required to implement a debugger.
There are facilities to do the following:
1. Have the GL call a user-specified function prior to executing
each vertex or fragment instruction.
2. Query the current program string's execution position.
3. Query the current values of intermediate program values.
The main feature is the ProgramCallbackMESA function. It allows the
user to register a callback function with the GL. The callback will
be called prior to executing each vertex or fragment program instruction.
From within the callback, the user may issue Get* commands to
query current GL state. The GetProgramRegisterfvMESA function allows
current program values to be queried (such as temporaries, input
attributes, and result registers).
There are flags for enabling/disabling the program callbacks.
The current execution position (as an offset from the start of the
program string) can be queried with
GetIntegerv(GL_FRAGMENT_PROGRAM_POSITION_MESA, &pos) or
GetIntegerv(GL_VERTEX_PROGRAM_POSITION_MESA, &pos).
IP Status
None
Issues
1. Is this the right model for a debugger?
It seems prudent to minimize the scope of this extension and leave
it up to the developer (or developer community) to write debuggers
that layer on top of this extension.
If the debugger were fully implemented within the GL it's not
clear how terminal and GUI-based interfaces would work, for
example.
2. There aren't any other extensions that register callbacks with
the GL. Isn't there another solution?
If we want to be able to single-step through vertex/fragment
programs I don't see another way to do it.
3. How do we prevent the user from doing something crazy in the
callback function, like trying to call glBegin (leading to
recursion)?
The rule is that the callback function can only issue glGet*()
functions and no other GL commands. It could be difficult to
enforce this, however. Therefore, calling any non-get GL
command from within the callback will result in undefined
results.
4. Is this extension amenable to hardware implementation?
Hopefully, but if not, the GL implementation will have to fall
back to a software path when debugging. This may be acceptable
for debugging.
5. What's the <data> parameter to ProgramCallbackMESA for?
It's a common programming practice to associate a user-supplied
value with callback functions.
6. Debuggers often allow one to modify intermediate program values,
then continue. Does this extension support that?
No.
New Procedures and Functions (and datatypes)
typedef void (*programcallbackMESA)(enum target, void *data)
void ProgramCallbackMESA(enum target, programcallbackMESA callback,
void *data)
void GetProgramRegisterfvMESA(enum target, sizei len,
const ubyte *registerName, float *v)
New Tokens
Accepted by the <cap> parameter of Enable, Disable, IsEnabled,
GetBooleanv, GetDoublev, GetFloatv and GetIntegerv:
FRAGMENT_PROGRAM_CALLBACK_MESA 0x8bb1
VERTEX_PROGRAM_CALLBACK_MESA 0x8bb4
Accepted by the <pname> parameter GetBooleanv, GetDoublev,
GetFloatv and GetIntegerv:
FRAGMENT_PROGRAM_POSITION_MESA 0x8bb0
VERTEX_PROGRAM_POSITION_MESA 0x8bb5
Accepted by the <pname> parameter of GetPointerv:
FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x8bb2
FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x8bb3
VERTEX_PROGRAM_CALLBACK_FUNC_MESA 0x8bb6
VERTEX_PROGRAM_CALLBACK_DATA_MESA 0x8bb7
Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
None.
Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
Operations and the Frame Buffer)
None.
Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
In section 5.4 "Display Lists", page 202, add the following command
to the list of those that are not compiled into display lists:
ProgramCallbackMESA.
Add a new section 5.7 "Callback Functions"
The function
void ProgramCallbackMESA(enum target, programcallbackMESA callback,
void *data)
registers a user-defined callback function with the GL. <target>
may be FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB. The enabled
callback functions registered with these targets will be called
prior to executing each instruction in the current fragment or
vertex program, respectively. The callbacks are enabled and
disabled by calling Enable or Disable with <cap>
FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB.
The callback function's signature must match the typedef
typedef void (*programcallbackMESA)(enum target, void *data)
When the callback function is called, <target> will either be
FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which
program is currently executing and <data> will be the value
specified when ProgramCallbackMESA was called.
From within the callback function, only the following GL commands
may be called:
GetBooleanv
GetDoublev
GetFloatv
GetIntegerv
GetProgramLocalParameter
GetProgramEnvParameter
GetProgramRegisterfvMESA
GetProgramivARB
GetProgramStringARB
GetError
Calling any other command from within the callback results in
undefined behaviour.
Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
State Requests)
Add a new section 6.1.3 "Program Value Queries":
The command
void GetProgramRegisterfvMESA(enum target, sizei len,
const ubyte *registerName,
float *v)
Is used to query the value of program variables and registers
during program execution. GetProgramRegisterfvMESA may only be
called from within a callback function registered with
ProgramCallbackMESA.
<registerName> and <len> specify the name a variable, input
attribute, temporary, or result register in the program string.
The current value of the named variable is returned as four
values in <v>. If <name> doesn't exist in the program string,
the error INVALID_OPERATION is generated.
Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
None.
Additions to the AGL/GLX/WGL Specifications
None.
GLX Protocol
XXX TBD
Dependencies on NV_vertex_program and NV_fragment_program
If NV_vertex_program and/or NV_fragment_program are supported,
vertex and/or fragment programs defined by those extensions may
be debugged as well. Register queries will use the syntax used
by those extensions (i.e. "v[X]" to query vertex attributes,
"o[X]" for vertex outputs, etc.)
Errors
INVALID_OPERATION is generated if ProgramCallbackMESA is called
between Begin and End.
INVALID_ENUM is generated by ProgramCallbackMESA if <target> is not
a supported vertex or fragment program type.
Note: INVALID_OPERAION IS NOT generated by GetProgramRegisterfvMESA,
GetBooleanv, GetDoublev, GetFloatv, or GetIntegerv if called between
Begin and End when a vertex or fragment program is currently executing.
INVALID_ENUM is generated by ProgramCallbackMESA,
GetProgramRegisterfvMESA if <target> is not a program target supported
by ARB_vertex_program, ARB_fragment_program (or NV_vertex_program or
NV_fragment_program).
INVALID_VALUE is generated by GetProgramRegisterfvMESA if <registerName>
does not name a known program register or variable.
INVALID_OPERATION is generated by GetProgramRegisterfvMESA when a
register query is attempted for a program target that's not currently
being executed.
New State
XXX finish
(table 6.N, p. ###)
Initial
Get Value Type Get Command Value Description Sec. Attribute
--------- ---- ----------- ----- ----------- ---- ---------
FRAGMENT_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable
VERTEX_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable
FRAGMENT_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX -
VERTEX_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX -
FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX -
VERTEX_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX -
FRAGMENT_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX -
VERTEX_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX -
XXX more?
New Implementation Dependent State
None.
Revision History
8 July 2003
Initial draft. (Brian Paul)
11 July 2003
Second draft. (Brian Paul)
20 July 2003
Third draft. Lots of fundamental changes. (Brian Paul)
23 July 2003
Added chapter 5 and 6 spec language. (Brian Paul)
Example Usage
The following is a very simple example of how this extension may
be used to print the values of R0, R1, R2 and R3 while executing
vertex programs.
/* This is called by the GL when the vertex program is executing.
* We can only make glGet* calls from within this function!
*/
void DebugCallback(GLenum target, GLvoid *data)
{
GLint pos;
GLuint i;
/* Get PC and current instruction string */
glGetIntegerv(GL_VERTEX_PROGRAM_POSITION_ARB, &pos);
printf("Current position: %d\n", pos);
printf("Current temporary registers:\n");
for (i = 0; i < 4; i++) {
GLfloat v[4];
char s[10];
sprintf(s, "R%d", i);
glGetProgramRegisterfvMESA(GL_VERTEX_PROGRAM_ARB, strlen(s), s, v);
printf("R%d = %g, %g, %g, %g\n", i, v[0], v[1], v[2], v[3]);
}
}
/*
* elsewhere...
*/
/* Register our debugger callback function */
glProgramCallbackMESA(GL_VERTEX_PROGRAM_ARB, DebugCallback, NULL);
glEnable(GL_VERTEX_PROGRAM_CALLBACK_MESA);
/* define/bind a vertex program */
glEnable(GL_VERTEX_PROGRAM);
/* render something */
glBegin(GL_POINTS);
glVertex2f(0, 0);
glEnd();
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_resize_buffers.spec
+81
View File
@@ -0,0 +1,81 @@
Name
MESA_resize_buffers
Name Strings
GL_MESA_resize_buffers
Contact
Brian Paul (brian.paul 'at' tungstengraphics.com)
Status
Obsolete.
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
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_set_3dfx_mode.spec
+85
View File
@@ -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
Obsolete.
Version
Last Modified Date: 8 June 2000
Number
218
Dependencies
OpenGL 1.0 or later is required.
GLX 1.0 or later is required.
Overview
The Mesa Glide driver allows full-screen rendering or rendering into
an X window. The glXSet3DfxModeMESA() function allows an application
to switch between full-screen and windowed rendering.
IP Status
Open-source; freely implementable.
Issues
None.
New Procedures and Functions
GLboolean glXSet3DfxModeMESA( GLint mode );
New Tokens
GLX_3DFX_WINDOW_MODE_MESA 0x1
GLX_3DFX_FULLSCREEN_MODE_MESA 0x2
Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors)
The Mesa Glide device driver allows either rendering in full-screen
mode or rendering into an X window. An application can switch between
full-screen and window rendering with the command:
GLboolean glXSet3DfxModeMESA( GLint mode );
<mode> may either be GLX_3DFX_WINDOW_MODE_MESA to indicate window
rendering or GLX_3DFX_FULLSCREEN_MODE_MESA to indicate full-screen mode.
GL_TRUE is returned if <mode> is valid and the operation completed
normally. GL_FALSE is returned if <mode> is invalid or if the Glide
driver is not being used.
Note that only one drawable and context can be created at any given
time with the Mesa Glide driver.
GLX Protocol
None since this is a client-side extension.
Errors
None.
New State
None.
Revision History
8 June 2000 - initial specification
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_shader_debug.spec
+264
View File
@@ -0,0 +1,264 @@
Name
MESA_shader_debug
Name Strings
GL_MESA_shader_debug
Contact
Brian Paul (brian.paul 'at' tungstengraphics.com)
Michal Krol (mjkrol 'at' gmail.com)
Status
Obsolete.
Version
Last Modified Date: July 30, 2006
Author Revision: 0.2
Number
TBD
Dependencies
OpenGL 1.0 is required.
The ARB_shader_objects extension is required.
The ARB_shading_language_100 extension is required.
The extension is written against the OpenGL 1.5 specification.
The extension is written against the OpenGL Shading Language 1.10
Specification.
Overview
This extension introduces a debug object that can be attached to
a program object to enable debugging. Vertex and/or fragment shader,
during execution, issue diagnostic function calls that are logged
to the debug object's log. A separate debug log for each shader type
is maintained. A debug object can be attached, detached and queried
at any time outside the Begin/End pair. Multiple debug objects can
be attached to a single program object.
IP Status
None
Issues
None
New Procedures and Functions
handleARB CreateDebugObjectMESA(void)
void ClearDebugLogMESA(handleARB obj, enum logType, enum shaderType)
void GetDebugLogMESA(handleARB obj, enum logType, enum shaderType,
sizei maxLength, sizei *length,
charARB *debugLog)
sizei GetDebugLogLengthMESA(handleARB obj, enum logType,
enum shaderType)
New Types
None
New Tokens
Returned by the <params> parameter of GetObjectParameter{fi}vARB:
DEBUG_OBJECT_MESA 0x8759
Accepted by the <logType> argument of ClearDebugLogMESA,
GetDebugLogLengthMESA and GetDebugLogMESA:
DEBUG_PRINT_MESA 0x875A
DEBUG_ASSERT_MESA 0x875B
Additions to Chapter 2 of the OpenGL 1.5 Specification
(OpenGL Operation)
None
Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization)
None
Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
Operations and the Frame Buffer)
None
Additions to Chapter 5 of the OpenGL 1.5 Specification
(Special Functions)
None
Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
Requests)
None
Additions to Appendix A of the OpenGL 1.5 Specification (Invariance)
None
Additions to Chapter 1 of the OpenGL Shading Language 1.10 Specification
(Introduction)
None
Additions to Chapter 2 of the OpenGL Shading Language 1.10 Specification
(Overview of OpenGL Shading)
None
Additions to Chapter 3 of the OpenGL Shading Language 1.10 Specification
(Basics)
None
Additions to Chapter 4 of the OpenGL Shading Language 1.10 Specification
(Variables and Types)
None
Additions to Chapter 5 of the OpenGL Shading Language 1.10 Specification
(Operators and Expressions)
None
Additions to Chapter 6 of the OpenGL Shading Language 1.10 Specification
(Statements and Structure)
None
Additions to Chapter 7 of the OpenGL Shading Language 1.10 Specification
(Built-in Variables)
None
Additions to Chapter 8 of the OpenGL Shading Language 1.10 Specification
(Built-in Functions)
Add a new section 8.10 "Debug Functions":
Debug functions are available to both fragment and vertex shaders.
They are used to track the execution of a shader by logging
passed-in arguments to the debug object's log. Those values can be
retrieved by the application for inspection after shader execution
is complete.
The text, if any, produced by any of these functions is appended
to each debug object that is attached to the program object.
There are different debug log types
Add a new section 8.10.1 "Print Function":
The following printMESA prototypes are available.
void printMESA(const float value)
void printMESA(const int value)
void printMESA(const bool value)
void printMESA(const vec2 value)
void printMESA(const vec3 value)
void printMESA(const vec4 value)
void printMESA(const ivec2 value)
void printMESA(const ivec3 value)
void printMESA(const ivec4 value)
void printMESA(const bvec2 value)
void printMESA(const bvec3 value)
void printMESA(const bvec4 value)
void printMESA(const mat2 value)
void printMESA(const mat3 value)
void printMESA(const mat4 value)
void printMESA(const sampler1D value)
void printMESA(const sampler2D value)
void printMESA(const sampler3D value)
void printMESA(const samplerCube value)
void printMESA(const sampler1DShadow value)
void printMESA(const sampler2DShadow value)
The printMESA function writes the argument <value> to the "debug
print log" (XXX DEBUG_PRINT_MESA?). Each component is written in
text format (XXX format!) and is delimited by a white space (XXX 1
or more?).
Add a new section 8.10.2 "Assert Function":
The following assertMESA prototypes are available.
void assertMESA(const bool condition)
void assertMESA(const bool condition, const int cookie)
void assertMESA(const bool condition, const int cookie,
const int file, const int line)
The assertMESA function checks if the argument <condition> is
true or false. If it is true, nothing happens. If it is false,
a diagnostic message is written to the "debug assert log".
The message contains the argument <file>, <line>, <cookie> and
implementation dependent double-quoted string, each of this
delimited by a white space. If the argument <cookie> is not present,
it is meant as if it was of value 0. If the arguments <file> and
<line> are not present, they are meant as if they were of values
__FILE__ and __LINE__, respectively. The following three calls
produce the same output, assuming they were issued from the same
file and line.
assertMESA (false);
assertMESA (false, 0);
assertMESA (false, 0, __FILE__, __LINE__);
The diagnostic message examples follow.
1 89 0 ""
1 45 333 "all (lessThanEqual (fragColor, vec4 (1.0)))"
1 66 1 "assertion failed in file 1, line 66, cookie 1"
Additions to Chapter 9 of the OpenGL Shading Language 1.10 Specification
(Shading Language Grammar)
None
Additions to Chapter 10 of the OpenGL Shading Language 1.10
Specification (Issues)
None
Additions to the AGL/EGL/GLX/WGL Specifications
None
GLX Protocol
None
Errors
TBD
New State
TBD
New Implementation Dependent State
TBD
Sample Code
TBD
Revision History
29 May 2006
Initial draft. (Michal Krol)
30 July 2006
Add Overview, New Procedures and Functions, New Tokens sections.
Add sections 8.10.1, 8.10.2 to GLSL spec.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_sprite_point.spec
+190
View File
@@ -0,0 +1,190 @@
Name
MESA_sprite_point
Name Strings
GL_MESA_sprite_point
Contact
Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com)
Status
Obsolete - see GL_ARB_point_sprite.
Version
Number
???
Dependencies
GL_EXT_point_parameters effects the definition of this extension
GL_ARB_multitexture effects the definition of this extension
Overview
This extension modifies the way in which points are rendered,
specifically when they're textured. When SPRITE_POINT_MESA is enabled
a point is rendered as if it were a quadrilateral with unique texture
coordinates at each vertex. This extension effectively turns points
into sprites which may be rendered more easily and quickly than using
conventional textured quadrilaterals.
When using point size > 1 or attenuated points this extension is an
effective way to render many small sprite images for particle systems
or other effects.
Issues:
1. How are the texture coordinates computed?
The lower-left corner has texture coordinate (0,0,r,q).
The lower-right, (1,0,r,q). The upper-right, (1,1,r,q).
The upper-left, (0,1,r,q).
2. What about texgen and texture matrices?
Texgen and the texture matrix have no effect on the point's s and t
texture coordinates. The r and q coordinates may have been computed
by texgen or the texture matrix. Note that with a 3D texture and/or
texgen that the r coordinate could be used to select a slice in the
3D texture.
3. What about point smoothing?
When point smoothing is enabled, a triangle fan could be rendered
to approximate a circular point. This could be problematic to
define and implement so POINT_SMOOTH is ignored when drawing sprite
points.
Smoothed points can be approximated by using an appropriate texture
images, alpha testing and blending.
POLYGON_SMOOTH does effect the rendering of the quadrilateral, however.
4. What about sprite rotation?
There is none. Sprite points are always rendered as window-aligned
squares. One could define rotated texture images if desired. A 3D
texture and appropriate texture r coordinates could be used to
effectively specify image rotation per point.
5. What about POLYGON_MODE?
POLYGON_MODE does not effect the rasterization of the quadrilateral.
6. What about POLYGON_CULL?
TBD. Polygon culling is normally specified and implemented in the
transformation stage of OpenGL. However, some rasterization hardware
implements it later during triangle setup.
Polygon culling wouldn't be useful for sprite points since the
quadrilaterals are always defined in counter-clockwise order in
window space. For that reason, polygon culling should probably be
ignored.
7. Should sprite points be alpha-attenuated if their size is below the
point parameter's threshold size?
8. Should there be an advertisized maximum sprite point size?
No. Since we're rendering the point as a quadrilateral there's no
need to limit the size.
New Procedures and Functions
None.
New Tokens
Accepted by the <pname> parameter of Enable, Disable, IsEnabled,
GetIntegerv, GetBooleanv, GetFloatv and GetDoublev:
SPRITE_POINT_MESA 0x????
MAX_SPRITE_POINT_SIZE_MESA 0x???? (need this?)
Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the 1.1 Specification (Rasterization)
Section ???.
When SPRITE_POINT_MESA is enabled points are rasterized as screen-
aligned quadrilaterals. If the four vertices of the quadrilateral
are labeled A, B, C, and D, starting at the lower-left corner and moving
counter-clockwise around the quadrilateral, then the vertex and
texture coordinates are computed as follows:
vertex window coordinate texture coordinate
A (x-r, y-r, z, w) (0, 0, r, q)
B (x+r, y-r, z, w) (1, 0, r, q)
C (x+r, y+r, z, w) (1, 1, r, q)
D (x-r, y+r, z, w) (0, 1, r, q)
where x, y, z, w are the point's window coordinates, r and q are the
point's 3rd and 4th texture coordinates and r is half the point's
size. The other vertex attributes (such as the color and fog coordinate)
are simply duplicated from the original point vertex.
Point size may either be specified with PointSize or computed
according to the EXT_point_parameters extension.
The new texture coordinates are not effected by texgen or the texture
matrix. Note, however, that the texture r and q coordinates are passed
unchanged and may have been computed with texgen and/or the texture
matrix.
If multiple texture units are present the same texture coordinate is
used for all texture units.
The point is then rendered as if it were a quadrilateral using the
normal point sampling rules. POLYGON_MODE does not effect the
rasterization of the quadrilateral but POLYGON_SMOOTH does.
POINT_SMOOTH has no effect when SPRITE_POINT_MESA is enabled.
Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations
and the Frame Buffer)
None.
Additions to Chapter 5 of the 1.1 Specification (Special Functions)
None
Additions to Chapter 6 of the 1.1 Specification (State and State Requests)
None
Additions to the GLX Specification
None
GLX Protocol
TBD
Errors
None
New State
Add boolean variable SPRITE_POINT_MESA to the point attribute group.
Revision History
Version 1.0 - 4 Dec 2000
Original draft.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_swap_frame_usage.spec
+201
View File
@@ -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
Obsolete.
Version
Date: 5/1/2003 Revision: 1.1
Number
???
Dependencies
GLX_SGI_swap_control affects the definition of this extension.
GLX_MESA_swap_control affects the definition of this extension.
GLX_OML_sync_control affects the definition of this extension.
Based on WGL_I3D_swap_frame_usage version 1.3.
Overview
This extension allows an application to determine what portion of the
swap period has elapsed since the last swap operation completed. The
"usage" value is a floating point value on the range [0,max] which is
calculated as follows:
td
percent = ----
tf
where td is the time measured from the last completed buffer swap (or
call to enable the statistic) to when the next buffer swap completes, tf
is the entire time for a frame which may be multiple screen refreshes
depending on the swap interval as set by the GLX_SGI_swap_control or
GLX_OML_sync_control extensions.
The value, percent, indicates the amount of time spent between the
completion of the two swaps. If the value is in the range [0,1], the
buffer swap occurred within the time period required to maintain a
constant frame rate. If the value is in the range (1,max], a constant
frame rate was not achieved. The value indicates the number of frames
required to draw.
This definition of "percent" differs slightly from
WGL_I3D_swap_frame_usage. In WGL_I3D_swap_frame_usage, the measurement
is taken from the completion of one swap to the issuance of the next.
This representation may not be as useful as measuring between
completions, as a significant amount of time may pass between the
issuance of a swap and the swap actually occurring.
There is also a mechanism to determine whether a frame swap was
missed.
New Procedures and Functions
int glXGetFrameUsageMESA(Display *dpy,
GLXDrawable drawable,
float *usage)
int glXBeginFrameTrackingMESA(Display *dpy,
GLXDrawable drawable)
int glXEndFrameTrackingMESA(Display *dpy,
GLXDrawable drawable)
int glXQueryFrameTrackingMESA(Display *dpy,
GLXDrawable drawable,
int64_t *swapCount,
int64_t *missedFrames,
float *lastMissedUsage)
New Tokens
None
Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation)
None
Additions to Chapter 3 of the 1.4 GL Specification (Rasterization)
None
Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations
and the Framebuffer)
None
Additions to Chapter 5 of the 1.4 GL Specification (Special Functions)
None
Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests)
None
Additions to the GLX 1.3 Specification
The frame usage is measured as the percentage of the swap period elapsed
between two buffer-swap operations being committed. In unextended GLX the
swap period is the vertical refresh time. If SGI_swap_control or
MESA_swap_control are supported, the swap period is the vertical refresh
time multiplied by the swap interval (or one if the swap interval is set
to zero).
If OML_sync_control is supported, the swap period is the vertical
refresh time multiplied by the divisor parameter to
glXSwapBuffersMscOML. The frame usage in this case is less than 1.0 if
the swap is committed before target_msc, and is greater than or equal to
1.0 otherwise. The actual usage value is based on the divisor and is
never less than 0.0.
int glXBeginFrameTrackingMESA(Display *dpy,
GLXDrawable drawable,
float *usage)
glXGetFrameUsageMESA returns a floating-point value in <usage>
that represents the current swap usage, as defined above.
Missed frame swaps can be tracked by calling the following function:
int glXBeginFrameTrackingMESA(Display *dpy,
GLXDrawable drawable)
glXBeginFrameTrackingMESA resets a "missed frame" count and
synchronizes with the next frame vertical sync before it returns.
If a swap is missed based in the rate control specified by the
<interval> set by glXSwapIntervalSGI or the default swap of once
per frame, the missed frame count is incremented.
The current missed frame count and total number of swaps since
the last call to glXBeginFrameTrackingMESA can be obtained by
calling the following function:
int glXQueryFrameTrackingMESA(Display *dpy,
GLXDrawable drawable,
int64_t *swapCount,
int64_t *missedFrames,
float *lastMissedUsage)
The location pointed to by <swapCount> will be updated with the
number of swaps that have been committed. This value may not match the
number of swaps that have been requested since swaps may be
queued by the implementation. This function can be called at any
time and does not synchronize to vertical blank.
The location pointed to by <missedFrames> will contain the number
swaps that missed the specified frame. The frame usage for the
last missed frame is returned in the location pointed to by
<lastMissedUsage>.
Frame tracking is disabled by calling the function
int glXEndFrameTrackingMESA(Display *dpy,
GLXDrawable drawable)
This function will not return until all swaps have occurred. The
application can call glXQueryFrameTrackingMESA for a final swap and
missed frame count.
If these functions are successful, zero is returned. If the context
associated with dpy and drawable is not a direct context,
GLX_BAD_CONTEXT is returned.
Errors
If the function succeeds, zero is returned. If the function
fails, one of the following error codes is returned:
GLX_BAD_CONTEXT The current rendering context is not a direct
context.
GLX Protocol
None. This extension only extends to direct rendering contexts.
New State
None
New Implementation Dependent State
None
Revision History
1.1, 5/1/03 Added contact information.
1.0, 3/17/03 Initial version based on WGL_I3D_swap_frame_usage.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_texture_array.spec
+804
View File
@@ -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
DEPRECATED - Support removed in Mesa 10.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:
https://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=011557
https://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=000516
https://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=011903
http://www.delphi3d.net/articles/viewarticle.php?article=terraintex.htm
New Procedures and Functions
All functions come directly from EXT_texture_array.
void FramebufferTextureLayerEXT(enum target, enum attachment,
uint texture, int level, int layer);
New Tokens
All token names and values come directly from EXT_texture_array.
Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, by
the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and
GetDoublev, and by the <target> parameter of TexImage3D, GetTexImage,
GetTexLevelParameteriv, GetTexLevelParameterfv, GetTexParameteriv, and
GetTexParameterfv:
TEXTURE_1D_ARRAY_EXT 0x8C18
TEXTURE_2D_ARRAY_EXT 0x8C1A
Accepted by the <target> parameter of TexImage2D, TexSubImage2D,
CopyTexImage2D, CopyTexSubImage2D, CompressedTexImage2D,
CompressedTexSubImage2D, GetTexLevelParameteriv, and
GetTexLevelParameterfv:
TEXTURE_1D_ARRAY_EXT
PROXY_TEXTURE_1D_ARRAY_EXT 0x8C19
Accepted by the <target> parameter of TexImage3D, TexSubImage3D,
CopyTexSubImage3D, CompressedTexImage3D, CompressedTexSubImage3D,
GetTexLevelParameteriv, and GetTexLevelParameterfv:
TEXTURE_2D_ARRAY_EXT
PROXY_TEXTURE_2D_ARRAY_EXT 0x8C1B
Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
GetFloatv, and GetDoublev
TEXTURE_BINDING_1D_ARRAY_EXT 0x8C1C
TEXTURE_BINDING_2D_ARRAY_EXT 0x8C1D
MAX_ARRAY_TEXTURE_LAYERS_EXT 0x88FF
Accepted by the <param> parameter of TexParameterf, TexParameteri,
TexParameterfv, and TexParameteriv when the <pname> parameter is
TEXTURE_COMPARE_MODE_ARB:
COMPARE_REF_DEPTH_TO_TEXTURE_EXT 0x884E
(Note: COMPARE_REF_DEPTH_TO_TEXTURE_EXT is simply an alias for the
existing COMPARE_R_TO_TEXTURE token in OpenGL 2.0; the alternate name
reflects the fact that the R coordinate is not always used.)
Accepted by the <internalformat> parameter of TexImage3D and
CompressedTexImage3D, and by the <format> parameter of
CompressedTexSubImage3D:
COMPRESSED_RGB_S3TC_DXT1_EXT
COMPRESSED_RGBA_S3TC_DXT1_EXT
COMPRESSED_RGBA_S3TC_DXT3_EXT
COMPRESSED_RGBA_S3TC_DXT5_EXT
Accepted by the <pname> parameter of
GetFramebufferAttachmentParameterivEXT:
FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT 0x8CD4
(Note: FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER is simply an alias for the
FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT token provided in
EXT_framebuffer_object. This extension generalizes the notion of
"<zoffset>" to include layers of an array texture.)
Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization)
-- Section 3.8.1 "Texture Image Specification"
Change the first paragraph (page 150) to say (spec changes identical to
EXT_texture_array):
"The command
void TexImage3D(enum target, int level, int internalformat,
sizei width, sizei height, sizei depth, int border,
enum format, enum type, void *data);
is used to specify a three-dimensional texture image. target must be one
one of TEXTURE_3D for a three-dimensional texture or
TEXTURE_2D_ARRAY_EXT for an two-dimensional array texture.
Additionally, target may be either PROXY_TEXTURE_3D for a
three-dimensional proxy texture, or PROXY_TEXTURE_2D_ARRAY_EXT for a
two-dimensional proxy array texture."
Change the fourth paragraph on page 151 to say (spec changes identical
to EXT_texture_array):
"Textures with a base internal format of DEPTH_COMPONENT are supported
by texture image specification commands only if target is TEXTURE_1D,
TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, TEXTURE_2D_ARRAY_EXT,
PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, PROXY_TEXTURE_1D_ARRAY_EXT, or
PROXY_TEXTURE_2D_ARRAY_EXT. Using this format in conjunction with any
other target will result in an INVALID_OPERATION error."
Change the fourth paragraph on page 156 to say (spec changes identical
to EXT_texture_array):
"The command
void TexImage2D(enum target, int level,
int internalformat, sizei width, sizei height,
int border, enum format, enum type, void *data);
is used to specify a two-dimensional texture image. target must be one
of TEXTURE_2D for a two-dimensional texture, TEXTURE_1D_ARRAY_EXT for a
one-dimensional array texture, or one of TEXTURE_CUBE_MAP_POSITIVE_X,
TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y,
TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, or
TEXTURE_CUBE_MAP_NEGATIVE_Z for a cube map texture. Additionally,
target may be either PROXY_TEXTURE_2D for a two-dimensional proxy
texture, PROXY_TEXTURE_1D_ARRAY_EXT for a one-dimensional proxy array
texture, or PROXY TEXTURE_CUBE_MAP for a cube map proxy texture in the
special case discussed in section 3.8.11. The other parameters match
the corresponding parameters of TexImage3D.
For the purposes of decoding the texture image, TexImage2D is
equivalent to calling TexImage3D with corresponding arguments and depth
of 1, except that
* The border depth, d_b, is zero, and the depth of the image is
always 1 regardless of the value of border.
* The border height, h_b, is zero if <target> is
TEXTURE_1D_ARRAY_EXT, and <border> otherwise.
* Convolution will be performed on the image (possibly changing its
width and height) if SEPARABLE 2D or CONVOLUTION 2D is enabled.
* UNPACK SKIP IMAGES is ignored."
-- Section 3.8.2 "Alternate Texture Image Specification Commands"
Change the second paragraph (page 159) (spec changes identical
to EXT_texture_array):
"The command
void CopyTexImage2D(enum target, int level,
enum internalformat, int x, int y, sizei width,
sizei height, int border);
defines a two-dimensional texture image in exactly the manner of
TexImage2D, except that the image data are taken from the framebuffer
rather than from client memory. Currently, target must be one of
TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, TEXTURE_CUBE_MAP_POSITIVE_X,
TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE MAP_POSITIVE_Y,
TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, or
TEXTURE_CUBE_MAP_NEGATIVE_Z.
Change the last paragraph on page 160 to say (spec changes identical
to EXT_texture_array):
"Currently the target arguments of TexSubImage1D and CopyTexSubImage1D
must be TEXTURE_1D, the target arguments of TexSubImage2D and
CopyTexSubImage2D must be one of TEXTURE_2D, TEXTURE_1D_ARRAY_EXT,
TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_NEGATIVE_X,
TEXTURE_CUBE_MAP_POSITIVE_Y, TEXTURE_CUBE_MAP_NEGATIVE_Y,
TEXTURE_CUBE_MAP_POSITIVE_Z, or TEXTURE_CUBE_MAP_NEGATIVE_Z, and the
target arguments of TexSubImage3D and CopyTexSubImage3D must be
TEXTURE_3D or TEXTURE_2D_ARRAY_EXT. ..."
-- Section 3.8.4 "Texture Parameters"
Change the first paragraph (page 166) to say:
"Various parameters control how the texel array is treated when
specified or changed, and when applied to a fragment. Each parameter is
set by calling
void TexParameter{if}(enum target, enum pname, T param);
void TexParameter{if}v(enum target, enum pname, T params);
target is the target, either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D,
TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT."
-- Section 3.8.8 "Texture Minification" in the section "Scale Factor and Level of Detail"
Change the first paragraph (page 172) to say:
"Let s(x,y) be the function that associates an s texture coordinate
with each set of window coordinates (x,y) that lie within a primitive;
define t(x,y) and r(x,y) analogously. Let u(x,y) = w_t * s(x,y),
v(x,y) = h_t * t(x,y), and w(x,y) = d_t * r(x,y), where w_t, h_t,
and d_t are as defined by equations 3.15, 3.16, and 3.17 with
w_s, h_s, and d_s equal to the width, height, and depth of the
image array whose level is level_base. For a one-dimensional
texture or a one-dimensional array texture, define v(x,y) = 0 and
w(x,y) = 0; for a two-dimensional texture or a two-dimensional array
texture, define w(x,y) = 0..."
-- Section 3.8.8 "Texture Minification" in the section "Mipmapping"
Change the third paragraph (page 174) to say:
"For a two-dimensional texture, two-dimensional array texture, or
cube map texture,"
Change the fourth paragraph (page 174) to say:
"And for a one-dimensional texture or a one-dimensional array texture,"
After the first paragraph (page 175) add:
"For one-dimensional array textures, h_b and d_b are treated as 1,
regardless of the actual values, when performing mipmap calculations.
For two-dimensional array textures, d_b is always treated as one,
regardless of the actual value, when performing mipmap calculations."
-- Section 3.8.8 "Automatic Mipmap Generation" in the section "Mipmapping"
Change the third paragraph (page 176) to say (spec changes identical
to EXT_texture_array):
"The contents of the derived arrays are computed by repeated, filtered
reduction of the level_base array. For one- and two-dimensional array
textures, each layer is filtered independently. ..."
-- Section 3.8.8 "Manual Mipmap Generation" in the section "Mipmapping"
Change first paragraph to say (spec changes identical to
EXT_texture_array):
"Mipmaps can be generated manually with the command
void GenerateMipmapEXT(enum target);
where <target> is one of TEXTURE_1D, TEXTURE_2D, TEXTURE_CUBE_MAP,
TEXTURE_3D, TEXTURE_1D_ARRAY, or TEXTURE_2D_ARRAY. Mipmap generation
affects the texture image attached to <target>. ..."
-- Section 3.8.10 "Texture Completeness"
Change the second paragraph (page 177) to say (spec changes identical
to EXT_texture_array):
"For one-, two-, or three-dimensional textures and one- or
two-dimensional array textures, a texture is complete if the following
conditions all hold true:"
-- Section 3.8.11 "Texture State and Proxy State"
Change the second and third paragraphs (page 179) to say (spec changes
identical to EXT_texture_array):
"In addition to image arrays for one-, two-, and three-dimensional
textures, one- and two-dimensional array textures, and the six image
arrays for the cube map texture, partially instantiated image arrays
are maintained for one-, two-, and three-dimensional textures and one-
and two-dimensional array textures. Additionally, a single proxy image
array is maintained for the cube map texture. Each proxy image array
includes width, height, depth, border width, and internal format state
values, as well as state for the red, green, blue, alpha, luminance,
and intensity component resolutions. Proxy image arrays do not include
image data, nor do they include texture properties. When TexImage3D is
executed with target specified as PROXY_TEXTURE_3D, the
three-dimensional proxy state values of the specified level-of-detail
are recomputed and updated. If the image array would not be supported
by TexImage3D called with target set to TEXTURE 3D, no error is
generated, but the proxy width, height, depth, border width, and
component resolutions are set to zero. If the image array would be
supported by such a call to TexImage3D, the proxy state values are set
exactly as though the actual image array were being specified. No pixel
data are transferred or processed in either case.
Proxy arrays for one- and two-dimensional textures and one- and
two-dimensional array textures are operated on in the same way when
TexImage1D is executed with target specified as PROXY_TEXTURE_1D,
TexImage2D is executed with target specified as PROXY_TEXTURE_2D or
PROXY_TEXTURE_1D_ARRAY_EXT, or TexImage3D is executed with target
specified as PROXY_TETXURE_2D_ARRAY_EXT."
-- Section 3.8.12 "Texture Objects"
Change section (page 180) to say (spec changes identical to
EXT_texture_array):
"In addition to the default textures TEXTURE_1D, TEXTURE_2D,
TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and TEXTURE_2D_EXT,
named one-, two-, and three-dimensional, cube map, and one- and
two-dimensional array texture objects can be created and operated upon.
The name space for texture objects is the unsigned integers, with zero
reserved by the GL.
A texture object is created by binding an unused name to TEXTURE_1D,
TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
TEXTURE_2D_ARRAY_EXT. The binding is effected by calling
void BindTexture(enum target, uint texture);
with <target> set to the desired texture target and <texture> set to
the unused name. The resulting texture object is a new state vector,
comprising all the state values listed in section 3.8.11, set to the
same initial values. If the new texture object is bound to TEXTURE_1D,
TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
TEXTURE_2D_ARRAY_EXT, it is and remains a one-, two-,
three-dimensional, cube map, one- or two-dimensional array texture
respectively until it is deleted.
BindTexture may also be used to bind an existing texture object to
either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP,
TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT. The error
INVALID_OPERATION is generated if an attempt is made to bind a texture
object of different dimensionality than the specified target. If the
bind is successful no change is made to the state of the bound texture
object, and any previous binding to target is broken.
While a texture object is bound, GL operations on the target to which
it is bound affect the bound object, and queries of the target to which
it is bound return state from the bound object. If texture mapping of
the dimensionality of the target to which a texture object is bound is
enabled, the state of the bound texture object directs the texturing
operation.
In the initial state, TEXTURE_1D, TEXTURE_2D, TEXTURE_3D,
TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and TEXTURE_2D_ARRAY_EXT have
one-, two-, three-dimensional, cube map, and one- and two-dimensional
array texture state vectors respectively associated with them. In order
that access to these initial textures not be lost, they are treated as
texture objects all of whose names are 0. The initial one-, two-,
three-dimensional, cube map, one- and two-dimensional array textures
are therefore operated upon, queried, and applied as TEXTURE_1D,
TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and
TEXTURE_2D_ARRAY_EXT respectively while 0 is bound to the corresponding
targets.
Change second paragraph on page 181 to say (spec changes identical to
EXT_texture_array):
"... If a texture that is currently bound to one of the targets
TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP,
TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT is deleted, it is as
though BindTexture had been executed with the same target and texture
zero. ..."
Change second paragraph on page 182 to say (spec changes identical to
EXT_texture_array):
"The texture object name space, including the initial one-, two-, and
three dimensional, cube map, and one- and two-dimensional array texture
objects, is shared among all texture units. ..."
-- Section 3.8.14 "Depth Texture Comparison Modes" in "Texture Comparison Modes"
Change second through fourth paragraphs (page 188) to say:
"Let D_t be the depth texture value, in the range [0, 1]. For
texture lookups from one- and two-dimensional, rectangle, and
one-dimensional array targets, let R be the interpolated <r>
texture coordinate, clamped to the range [0, 1]. For texture lookups
from two-dimensional array texture targets, let R be the interpolated
<q> texture coordinate, clamped to the range [0, 1]. Then the
effective texture value L_t, I_t, or A_t is computed as follows:
If the value of TEXTURE_COMPARE_MODE is NONE, then
r = Dt
If the value of TEXTURE_COMPARE_MODE is
COMPARE_REF_DEPTH_TO_TEXTURE_EXT), then r depends on the texture
comparison function as shown in table 3.27."
-- Section 3.8.15 "Texture Application"
Change the first paragraph (page 189) to say:
"Texturing is enabled or disabled using the generic Enable and Disable
commands, respectively, with the symbolic constants TEXTURE_1D,
TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
TEXTURE_2D_ARRAY_EXT to enable one-, two-, three-dimensional, cube
map, one-dimensional array, or two-dimensional array texture,
respectively. If both two- and one-dimensional textures are enabled,
the two-dimensional texture is used. If the three-dimensional and
either of the two- or one-dimensional textures is enabled, the
three-dimensional texture is used. If the cube map texture and any of
the three-, two-, or one-dimensional textures is enabled, then cube map
texturing is used. If one-dimensional array texture is enabled and any
of cube map, three-, two-, or one-dimensional textures is enabled,
one-dimensional array texturing is used. If two-dimensional array
texture is enabled and any of cube map, three-, two-, one-dimensional
textures or one-dimensional array texture is enabled, two-dimensional
array texturing is used..."
-- Section 3.11.2 of ARB_fragment_program (Fragment Program Grammar and Restrictions):
(mostly add to existing grammar rules)
<optionName> ::= "MESA_texture_array"
<texTarget> ::= "1D"
| "2D"
| "3D"
| "CUBE"
| "RECT"
| <arrayTarget> (if program option is present)
| <shadowTarget> (if program option is present)
<arrayTarget> ::= "ARRAY1D"
| "ARRAY2D"
<shadowTarget> ::= "SHADOW1D"
| "SHADOW2D"
| "SHADOWRECT"
| <shadowArrayTarget> (if program option is present)
<shadowArrayTarget> ::= "SHADOWARRAY1D"
| "SHADOWARRAY2D"
-- Add Section 3.11.4.5.4 "Texture Stack Option"
"If a fragment program specifies the "MESA_texture_array" program
option, the <texTarget> rule is modified to add the texture targets
ARRAY1D and ARRAY2D (See Section 3.11.2)."
-- Section 3.11.6 "Fragment Program Texture Instruction Set"
(replace 1st and 2nd paragraphs with the following paragraphs)
"The first three texture instructions described below specify the
mapping of 4-tuple input vectors to 4-tuple output vectors.
The sampling of the texture works as described in section 3.8,
except that texture environments and texture functions are not
applicable, and the texture enables hierarchy is replaced by explicit
references to the desired texture target (i.e., 1D, 2D, 3D, cube map,
rectangle, ARRAY1D, ARRAY2D). These texture instructions specify
how the 4-tuple is mapped into the coordinates used for sampling. The
following function is used to describe the texture sampling in the
descriptions below:
vec4 TextureSample(vec4 coord, float lodBias, int texImageUnit,
enum texTarget);
Note that not all four components of the texture coordinates <coord>
are used by all texture targets. Component usage for each <texTarget>
is defined in table X.
coordinates used
texTarget Texture Type s t r layer shadow
---------------- --------------------- ----- ----- ------
1D TEXTURE_1D x - - - -
2D TEXTURE_2D x y - - -
3D TEXTURE_3D x y z - -
CUBE TEXTURE_CUBE_MAP x y z - -
RECT TEXTURE_RECTANGLE_ARB x y - - -
ARRAY1D TEXTURE_1D_ARRAY_EXT x - - y -
ARRAY2D TEXTURE_2D_ARRAY_EXT x y - z -
SHADOW1D TEXTURE_1D x - - - z
SHADOW2D TEXTURE_2D x y - - z
SHADOWRECT TEXTURE_RECTANGLE_ARB x y - - z
SHADOWARRAY1D TEXTURE_1D_ARRAY_EXT x - - y z
SHADOWARRAY2D TEXTURE_2D_ARRAY_EXT x y - z w
Table X: Texture types accessed for each of the <texTarget>, and
coordinate mappings. The "coordinates used" column indicate the
input values used for each coordinate of the texture lookup, the
layer selector for array textures, and the reference value for
texture comparisons."
-- Section 3.11.6.2 "TXP: Project coordinate and map to color"
Add to the end of the section:
"A program will fail to load if the TXP instruction is used in
conjunction with the SHADOWARRAY2D target."
Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment Operations)
-- Section 4.4.2.3 "Attaching Texture Images to a Framebuffer"
Add to the end of the section (spec changes identical to
EXT_texture_array):
"The command
void FramebufferTextureLayerEXT(enum target, enum attachment,
uint texture, int level, int layer);
operates identically to FramebufferTexture3DEXT, except that it
attaches a single layer of a three-dimensional texture or a one- or
two-dimensional array texture. <layer> is an integer indicating the
layer number, and is treated identically to the <zoffset> parameter in
FramebufferTexture3DEXT. The error INVALID_VALUE is generated if
<layer> is negative. The error INVALID_OPERATION is generated if
<texture> is non-zero and is not the name of a three dimensional
texture or one- or two-dimensional array texture. Unlike
FramebufferTexture3D, no <textarget> parameter is accepted.
If <texture> is non-zero and the command does not result in an error,
the framebuffer attachment state corresponding to <attachment> is
updated as in the other FramebufferTexture commands, except that
FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT is set to <layer>."
-- Section 4.4.4.1 "Framebuffer Attachment Completeness"
Add to the end of the list of completeness rules (spec changes
identical to EXT_texture_array):
"* If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE and
FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT names a one- or
two-dimensional array texture, then
FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT must be smaller than the
number of layers in the texture."
Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions)
-- Section 5.4 "Display Lists"
Change the first paragraph on page 242 to say (spec changes
identical to EXT_texture_array):
"TexImage3D, TexImage2D, TexImage1D, Histogram, and ColorTable are
executed immediately when called with the corresponding proxy arguments
PROXY_TEXTURE_3D or PROXY_TEXTURE_2D_ARRAY_EXT; PROXY_TEXTURE_2D,
PROXY_TEXTURE_CUBE_MAP, or PROXY_TEXTURE_1D_ARRAY_EXT;
PROXY_TEXTURE_1D; PROXY_HISTOGRAM; and PROXY_COLOR_TABLE,
PROXY_POST_CONVOLUTION_COLOR_TABLE, or
PROXY_POST_COLOR_MATRIX_COLOR_TABLE."
Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State Requests)
-- Section 6.1.3 "Enumerated Queries"
Add after the line beginning "If the value of
FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE" (spec changes
identical to EXT_texture_array):
"If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT and the
texture object named FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is a
three-dimensional texture or a one- or two-dimensional array texture,
then <params> will contain the number of texture layer attached to the
attachment point. Otherwise, <params> will contain the value zero."
-- Section 6.1.4 "Texture Queries"
Change the first three paragraphs (page 248) to say (spec changes
identical to EXT_texture_array):
"The command
void GetTexImage(enum tex, int lod, enum format,
enum type, void *img);
is used to obtain texture images. It is somewhat different from the
other get commands; tex is a symbolic value indicating which texture
(or texture face in the case of a cube map texture target name) is to
be obtained. TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_1D_ARRAY_EXT,
and TEXTURE_2D_ARRAY_EXT indicate a one-, two-, or three-dimensional
texture, or one- or two-dimensional array texture, respectively.
TEXTURE_CUBE_MAP_POSITIVE_X, ...
GetTexImage obtains... from the first image to the last for
three-dimensional textures. One- and two-dimensional array textures
are treated as two- and three-dimensional images, respectively, where
the layers are treated as rows or images. These groups are then...
For three-dimensional and two-dimensional array textures, pixel storage
operations are applied as if the image were two-dimensional, except
that the additional pixel storage state values PACK_IMAGE_HEIGHT and
PACK_SKIP_IMAGES are applied. ..."
Additions to Appendix A of the OpenGL 2.0 Specification (Invariance)
None
Additions to the AGL/GLX/WGL Specifications
None
GLX Protocol
None
Dependencies on ARB_fragment_program
If ARB_fragment_program is not supported, the changes to section 3.11
should be ignored.
Dependencies on EXT_framebuffer_object
If EXT_framebuffer_object is not supported, the changes to section
3.8.8 ("Manual Mipmap Generation"), 4.4.2.3, and 6.1.3 should be ignored.
Dependencies on EXT_texture_compression_s3tc and NV_texture_compression_vtc
(Identical dependency as EXT_texture_array.)
S3TC texture compression is supported for two-dimensional array textures.
When <target> is TEXTURE_2D_ARRAY_EXT, each layer is stored independently
as a compressed two-dimensional textures. When specifying or querying
compressed images using one of the S3TC formats, the images are provided
and/or returned as a series of two-dimensional textures stored
consecutively in memory, with the layer closest to zero specified first.
For array textures, images are not arranged in 4x4x4 or 4x4x2 blocks as in
the three-dimensional compression format provided in the
EXT_texture_compression_vtc extension. Pixel store parameters, including
those specific to three-dimensional images, are ignored when compressed
image data are provided or returned, as in the
EXT_texture_compression_s3tc extension.
S3TC compression is not supported for one-dimensional texture targets in
EXT_texture_compression_s3tc, and is not supported for one-dimensional
array textures in this extension. If compressed one-dimensional arrays
are needed, use a two-dimensional texture with a height of one.
This extension allows the use of the four S3TC internal format types in
TexImage3D, CompressedTexImage3D, and CompressedTexSubImage3D calls.
Errors
None
New State
(add to table 6.15, p. 276)
Initial
Get Value Type Get Command Value Description Sec. Attribute
---------------------------- ----- ----------- ----- -------------------- ------ ---------
TEXTURE_BINDING_1D_ARRAY_EXT 2*xZ+ GetIntegerv 0 texture object bound 3.8.12 texture
to TEXTURE_1D_ARRAY
TEXTURE_BINDING_2D_ARRAY_EXT 2*xZ+ GetIntegerv 0 texture object bound 3.8.12 texture
to TEXTURE_2D_ARRAY
New Implementation Dependent State
(add to Table 6.32, p. 293)
Minimum
Get Value Type Get Command Value Description Sec. Attribute
---------------------------- ---- ----------- ------- ------------------ ----- ---------
MAX_TEXTURE_ARRAY_LAYERS_EXT Z+ GetIntegerv 64 maximum number of 3.8.1 -
layers for texture
arrays
Issues
(1) Is "texture stack" a good name for this functionality?
NO. The name is changed to "array texture" to match the
nomenclature used by GL_EXT_texture_array.
(2) Should the R texture coordinate be treated as normalized or
un-normalized? If it were un-normalized, floor(R) could be thought
of as a direct index into the array texture. This may be more
convenient for applications.
RESOLVED. All texture coordinates are normalized. The issue of
un-normalized texture coordinates has been discussed in the ARB
before and should be left for a layered extension.
RE-RESOLVED. The R coordinate is un-normalized. Accessing an array
using [0, layers-1] coordinates is much more natural.
(3) How does LOD selection work for stacked textures?
RESOLVED. For 2D array textures the R coordinate is ignored, and
the LOD selection equations for 2D textures are used. For 1D
array textures the T coordinate is ignored, and the LOD selection
equations for 1D textures are used. The expected usage is in a
fragment program with an explicit LOD selection.
(4) What is the maximum size of a 2D array texture? Is it the same
as for a 3D texture, or should a new query be added? How about for 1D
array textures?
RESOLVED. A new query is added.
(5) How are array textures exposed in GLSL?
RESOLVED. Use GL_EXT_texture_array.
(6) Should a 1D array texture also be exposed?
RESOLVED. For orthogonality, yes.
(7) How are stacked textures attached to framebuffer objects?
RESOLVED. Layers of both one- and two-dimensional array textures
are attached using FreambufferTextureLayerEXT. Once attached, the
array texture layer behaves exactly as either a one- or
two-dimensional texture.
(8) How is this extension related to GL_EXT_texture_array?
This extension adapats GL_MESAX_texture_stack to the notation,
indexing, and FBO access of GL_EXT_texture_array. This extension
replaces the GLSL support of GL_EXT_texture_array with
GL_ARB_fragment_program support.
Assembly program support is also provided by GL_NV_gpu_program4.
GL_NV_gpu_program4 also adds support for other features that are
specific to Nvidia hardware, while this extension adds only support
for array textures.
Much of text of this extension that has changed since
GL_MESAX_texture_stack comes directly from either
GL_EXT_texture_array or GL_NV_gpu_program4.
Revision History
||2005/11/15||0.1||idr||Initial draft MESAX version.||
||2005/12/07||0.2||idr||Added framebuffer object interactions.||
||2005/12/12||0.3||idr||Updated fragment program interactions.||
||2007/05/16||0.4||idr||Converted to MESA_texture_array. Brought in line with EXT_texture_array and NV_gpu_program4.||
local/recipes/dev/mesa-clc/source/docs/_extra/specs/OLD/MESA_trace.spec
+359
View File
@@ -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 explicitly 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 occurrences of name/pointer, and is free to consider it
transient state.
(5) Should comment commands be prohibited between Begin/End?
RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA
is transient, the other commands might cause storage of persistent
data in the context. There is no need to have the ability mark names
or pointers between Begin and End.
New Procedures and Functions
void NewTraceMESA( bitfield mask, const ubyte * traceName )
void EndTraceMESA( void )
void EnableTraceMESA( bitfield mask )
void DisableTraceMESA( bitfield mask )
void TraceAssertAttribMESA( bitfield attribMask )
void TraceCommentMESA( const ubyte* comment )
void TraceTextureMESA( uint name, const ubyte* comment )
void TraceListMESA( uint name, const ubyte* comment )
void TracePointerMESA( void* pointer, const ubyte* comment )
void TracePointerRangeMESA( const void* first,
const void* last,
const ubyte* comment )
New Tokens
Accepted by the <mask> parameter of EnableTrace and DisableTrace:
TRACE_ALL_BITS_MESA 0xFFFF
TRACE_OPERATIONS_BIT_MESA 0x0001
TRACE_PRIMITIVES_BIT_MESA 0x0002
TRACE_ARRAYS_BIT_MESA 0x0004
TRACE_TEXTURES_BIT_MESA 0x0008
TRACE_PIXELS_BIT_MESA 0x0010
TRACE_ERRORS_BIT_MESA 0x0020
Accepted by the <pname> parameter of GetIntegerv, GetBooleanv,
GetFloatv, and GetDoublev:
TRACE_MASK_MESA 0x8755
Accepted by the <pname> parameter to GetString:
TRACE_NAME_MESA 0x8756
Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
Add a new section:
5.7 Tracing
The tracing facility is used to record the execution of a GL program
to a human-readable log. The log appears as a sequence of GL commands
using C syntax. The primary intention of tracing is to aid in program
debugging.
A trace is started with the command
void NewTraceMESA( bitfield mask, const GLubyte * traceName )
<mask> may be any value accepted by PushAttrib and specifies a set of
attribute groups. The state values included in those attribute groups
is written to the trace as a sequence of GL commands.
<traceName> specifies a name or label for the trace. It is expected
that <traceName> will be interpreted as a filename in most implementations.
A trace is ended by calling the command
void EndTraceMESA( void )
It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End.
The commands
void EnableTraceMESA( bitfield mask )
void DisableTraceMESA( bitfield mask )
enable or disable tracing of different classes of GL commands.
<mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA,
TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA,
and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA
indicates all classes of commands are to be logged.
TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of
Begin/End, including Begin/End.
TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of
Begin/End, including Begin/End.
TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer,
ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands.
TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by
TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and
TexSubImage3D commands.
TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by
Bitmap and DrawPixels commands.
TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is
set, GetError will be executed wherever applicable, and the result will
be added to the trace as a comment. The error returns are cached and
returned to the application on its GetError calls. If the user does not
wish the additional GetError calls to be performed, this bit should not
be set.
The command
void TraceCommentMESA( const ubyte* comment )
immediately adds the <comment> string to the trace output, surrounded
by C-style comment delimiters.
The commands
void TraceTextureMESA( uint name, const ubyte* comment )
void TraceListMESA( uint name, const ubyte* comment )
associates <comment> with the texture object or display list specified
by <name>. Logged commands which reference the named texture object or
display list will be annotated with <comment>. If IsTexture(name) or
IsList(name) fail (respectively) the command is quietly ignored.
The commands
void TracePointerMESA( void* pointer, const ubyte* comment )
void TracePointerRangeMESA( const void* first,
const void* last,
const ubyte* comment )
associate <comment> with the address specified by <pointer> or with
a range of addresses specified by <first> through <last>.
Any logged commands which reference <pointer> or an address between
<first> and <last> will be annotated with <comment>.
The command
void TraceAssertAttribMESA( bitfield attribMask )
will add GL state queries and assertion statements to the log to
confirm that the current state at the time TraceAssertAttrib is
executed matches the current state when the trace log is executed
in the future.
<attribMask> is any value accepted by PushAttrib and specifies
the groups of state variables which are to be asserted.
The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA,
TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA,
TracePointerMESA and TracePointerRangeMESA are not compiled into display lists.
Examples:
The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state
variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
to get the values <test>, <func>, <mask>, and <clear> respectively.
Statements equivalent to the following will then be logged:
glEnable(GL_DEPTH_TEST); (if <test> is true)
glDisable(GL_DEPTH_TEST); (if <test> is false)
glDepthFunc(<func>);
glDepthMask(<mask>);
glClearDepth(<clear>);
The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state
variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
to get the values <test>, <func>, <mask>, and <clear> respectively.
The resulting trace might then look will like this:
{
GLboolean b;
GLint i;
GLfloat f;
b = glIsEnabled(GL_DEPTH_TEST);
assert(b == <test>);
glGetIntegerv(GL_DEPTH_FUNC, &i);
assert(i == <func>);
glGetIntegerv(GL_DEPTH_MASK, &i);
assert(i == <mask>);
glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f);
assert(f == <clear>);
}
Additions to Chapter 6 of the OpenGL 1.2.1 Specification
(State and State Requests)
Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or
GetDoublev returns the current command class trace mask.
Querying TRACE_NAME_MESA with GetString returns the current trace name.
Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
The MESA_trace extension can be used in a way that does not affect data
flow from application to OpenGL, as well as data flow from OpenGL to
application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA
will add additional GetError queries. Setting a trace mask with NewTraceMESA
as well as use of TraceAssertAttribMESA might cause additional state queries.
With the possible exception of performance, OpenGL rendering should not be
affected at all by a properly chosen logging operation.
Additions to the AGL/GLX/WGL Specifications
None.
GLX Protocol
None. The logging operation is carried out client-side, by exporting
entry points to the wrapper functions that execute the logging operation.
Errors
INVALID_OPERATION is generated if any trace command except TraceCommentMESA
is called between Begin and End.
New State
The current trace name and current command class mask are stored
per-context.
New Implementation Dependent State
None.
Revision History
* Revision 0.1 - Initial draft from template (bk000415)
* Revision 0.2 - Draft (bk000906)
* Revision 0.3 - Draft (bk000913)
* Revision 0.4 - Reworked text, fixed typos (bp000914)
* Revision 0.5 - Assigned final GLenum values (bp001103)
* Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916)
* Revision 0.7 - Added MESA postfix (bk010126)
local/recipes/dev/mesa-clc/source/docs/_extra/specs/WL_bind_wayland_display.spec
+202
View File
@@ -0,0 +1,202 @@
Name
WL_bind_wayland_display
Name Strings
EGL_WL_bind_wayland_display
Contact
Kristian Høgsberg <krh@bitplanet.net>
Benjamin Franzke <benjaminfranzke@googlemail.com>
Status
Proposal
Version
Version 5, July 16, 2013
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_resource *buffer,
EGLint attribute, EGLint *value);
New Tokens
Accepted as <target> in eglCreateImageKHR
EGL_WAYLAND_BUFFER_WL 0x31D5
Accepted in the <attrib_list> parameter of eglCreateImageKHR:
EGL_WAYLAND_PLANE_WL 0x31D6
Possible values for EGL_TEXTURE_FORMAT:
EGL_TEXTURE_Y_U_V_WL 0x31D7
EGL_TEXTURE_Y_UV_WL 0x31D8
EGL_TEXTURE_Y_XUXV_WL 0x31D9
EGL_TEXTURE_EXTERNAL_WL 0x31DA
Accepted in the <attribute> parameter of eglQueryWaylandBufferWL:
EGL_TEXTURE_FORMAT 0x3080
EGL_WAYLAND_Y_INVERTED_WL 0x31DB
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.
EGL_TEXTURE_EXTERNAL_WL
Treated as a single plane texture, but sampled with
samplerExternalOES according to OES_EGL_image_external
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.
Also, eglQueryWaylandBufferWL may accept
EGL_WAYLAND_Y_INVERTED_WL attribute to query orientation of
wl_buffer. If EGL_WAYLAND_Y_INVERTED_WL is supported
eglQueryWaylandBufferWL returns EGL_TRUE and value is a boolean
that tells if wl_buffer is y-inverted or not. If
EGL_WAYLAND_Y_INVERTED_WL is not supported
eglQueryWaylandBufferWL returns EGL_FALSE, in that case
wl_buffer should be treated as if value of
EGL_WAYLAND_Y_INVERTED_WL was EGL_TRUE.
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)
Version 5, July 16, 2013
Change eglQueryWaylandBufferWL to take a resource pointer to the
buffer instead of a pointer to a struct wl_buffer, as the latter has
been deprecated. (Ander Conselvan de Oliveira)
Version 6, September 16, 2013
Add EGL_WAYLAND_Y_INVERTED_WL attribute to allow specifying
wl_buffer's orientation.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/WL_create_wayland_buffer_from_image.spec
+101
View File
@@ -0,0 +1,101 @@
Name
WL_create_wayland_buffer_from_image
Name Strings
EGL_WL_create_wayland_buffer_from_image
Contributors
Neil Roberts
Axel Davy
Daniel Stone
Contact
Neil Roberts <neil.s.roberts@intel.com>
Status
Proposal
Version
Version 2, October 25, 2013
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 an entry point to create a wl_buffer which shares
its contents with a given EGLImage. The expected use case for this is in a
nested Wayland compositor which is using subsurfaces to present buffers
from its clients. Using this extension it can attach the client buffers
directly to the subsurface without having to blit the contents into an
intermediate buffer. The compositing can then be done in the parent
compositor.
The nested compositor can create an EGLImage from a client buffer resource
using the existing WL_bind_wayland_display extension. It should also be
possible to create buffers using other types of images although there is
no expected use case for that.
IP Status
Open-source; freely implementable.
New Procedures and Functions
struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy,
EGLImageKHR image);
New Tokens
None.
Additions to the EGL 1.4 Specification:
To create a client-side wl_buffer from an EGLImage call
struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy,
EGLImageKHR image);
The returned buffer will share the contents with the given EGLImage. Any
updates to the image will also be updated in the wl_buffer. Typically the
EGLImage will be generated in a nested Wayland compositor using a buffer
resource from a client via the EGL_WL_bind_wayland_display extension.
If there was an error then the function will return NULL. In particular it
will generate EGL_BAD_MATCH if the implementation is not able to represent
the image as a wl_buffer. The possible reasons for this error are
implementation-dependant but may include problems such as an unsupported
format or tiling mode or that the buffer is in memory that is inaccessible
to the GPU that the given EGLDisplay is using.
Issues
1) Under what circumstances can the EGL_BAD_MATCH error be generated? Does
this include for example unsupported tiling modes?
RESOLVED: Yes, the EGL_BAD_MATCH error can be generated for any reason
which prevents the implementation from representing the image as a
wl_buffer. For example, these problems can be but are not limited to
unsupported tiling modes, inaccessible memory or an unsupported pixel
format.
Revision History
Version 1, September 6, 2013
Initial draft (Neil Roberts)
Version 2, October 25, 2013
Added a note about more possible reasons for returning EGL_BAD_FORMAT.
local/recipes/dev/mesa-clc/source/docs/_extra/specs/enums.txt
+113
View File
@@ -0,0 +1,113 @@
The definitive source for enum values and reserved ranges are the XML files in
the Khronos registry:
https://github.com/KhronosGroup/EGL-Registry/blob/master/api/egl.xml
https://github.com/KhronosGroup/OpenGL-Registry/blob/master/xml/gl.xml
https://github.com/KhronosGroup/OpenGL-Registry/blob/master/xml/glx.xml
https://github.com/KhronosGroup/OpenGL-Registry/blob/master/xml/wgl.xml
GL blocks allocated to Mesa:
0x8750-0x875F
0x8BB0-0x8BBF
Unused EGL blocks allocated to Mesa:
0x3290-0x329F
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:
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
GL_MESA_ycbcr_texture:
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:
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: (obsolete)
GL_FRAGMENT_PROGRAM_POSITION_MESA 0x8BB0
GL_FRAGMENT_PROGRAM_CALLBACK_MESA 0x8BB1
GL_FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x8BB2
GL_FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x8BB3
GL_VERTEX_PROGRAM_POSITION_MESA 0x8BB4
GL_VERTEX_PROGRAM_CALLBACK_MESA 0x8BB5
GL_VERTEX_PROGRAM_CALLBACK_FUNC_MESA 0x8BB6
GL_VERTEX_PROGRAM_CALLBACK_DATA_MESA 0x8BB7
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
GL_MESA_program_binary_formats:
GL_PROGRAM_BINARY_FORMAT_MESA 0x875F
GL_MESA_tile_raster_order
GL_TILE_RASTER_ORDER_FIXED_MESA 0x8BB8
GL_TILE_RASTER_ORDER_INCREASING_X_MESA 0x8BB9
GL_TILE_RASTER_ORDER_INCREASING_Y_MESA 0x8BBA
GL_MESA_framebuffer_flip_y
GL_FRAMEBUFFER_FLIP_Y_MESA 0x8BBB
GL_MESA_texture_const_bandwidth
GL_CONST_BW_TILING_MESA 0x8BBE
EGL_MESA_drm_image
EGL_DRM_BUFFER_FORMAT_MESA 0x31D0
EGL_DRM_BUFFER_USE_MESA 0x31D1
EGL_DRM_BUFFER_FORMAT_ARGB32_MESA 0x31D2
EGL_DRM_BUFFER_MESA 0x31D3
EGL_DRM_BUFFER_STRIDE_MESA 0x31D4
EGL_MESA_platform_gbm
EGL_PLATFORM_GBM_MESA 0x31D7
EGL_MESA_platform_surfaceless
EGL_PLATFORM_SURFACELESS_MESA 0x31DD
EGL_MESA_drm_image
EGL_DRM_BUFFER_FORMAT_ARGB2101010_MESA 0x3290
EGL_DRM_BUFFER_FORMAT_ARGB1555_MESA 0x3291
EGL_DRM_BUFFER_FORMAT_RGB565_MESA 0x3292
EGL_WL_bind_wayland_display
EGL_TEXTURE_FORMAT 0x3080
EGL_WAYLAND_BUFFER_WL 0x31D5
EGL_WAYLAND_PLANE_WL 0x31D6
EGL_TEXTURE_Y_U_V_WL 0x31D7
EGL_TEXTURE_Y_UV_WL 0x31D8
EGL_TEXTURE_Y_XUXV_WL 0x31D9
EGL_WAYLAND_Y_INVERTED_WL 0x31DB
EGL_EXT_platform_xcb
EGL_PLATFORM_XCB_EXT 0x31DC
EGL_PLATFORM_XCB_SCREEN_EXT 0x31DE
EGL_EXT_present_opaque
EGL_PRESENT_OPAQUE_EXT 0x31DF
local/recipes/dev/mesa-clc/source/docs/_exts/bootstrap.py
+127
View File
@@ -0,0 +1,127 @@
# BSD 3-Clause License
#
# Copyright (c) 2018, pandas
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
# list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# * Neither the name of the copyright holder nor the names of its
# contributors may be used to endorse or promote products derived from
# this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
# Based on https://github.com/pydata/pydata-sphinx-theme
from sphinx.ext.autosummary import autosummary_table
from sphinx.locale import admonitionlabels
import types
class BootstrapHTML5TranslatorMixin:
def __init__(self, *args, **kwds):
super().__init__(*args, **kwds)
self.settings.table_style = "table"
def starttag(self, *args, **kwargs):
"""ensure an aria-level is set for any heading role"""
if kwargs.get("ROLE") == "heading" and "ARIA-LEVEL" not in kwargs:
kwargs["ARIA-LEVEL"] = "2"
return super().starttag(*args, **kwargs)
def visit_admonition(self, node, name: str = '') -> None:
admonitionclasses = {
'attention': 'alert-primary',
'caution': 'alert-secondary',
'danger': 'alert-danger',
'error': 'alert-danger',
'hint': 'alert-secondary',
'important': 'alert-primary',
'note': 'alert-info',
'seealso': 'alert-info',
'tip': 'alert-info',
'warning': 'alert-warning',
}
self.body.append(self.starttag(
node, 'div', CLASS=('alert ' + admonitionclasses[name])))
if name:
self.body.append(self.starttag(node, 'div', '', CLASS='h5'))
self.body.append(str(admonitionlabels[name]))
self.body.append('</div>')
def depart_admonition(self, node) -> None:
self.body.append('</div>\n')
def visit_table(self, node):
# init the attributes
atts = {}
self._table_row_indices.append(0)
# get the classes
classes = [cls.strip(" \t\n") for cls in self.settings.table_style.split(",")]
# we're looking at the 'real_table', which is wrapped by an autosummary
if isinstance(node.parent, autosummary_table):
classes += ["autosummary"]
# add the width if set in a style attribute
if "width" in node:
atts["style"] = f'width: {node["width"]}'
# add specific class if align is set
if "align" in node:
classes.append(f'table-{node["align"]}')
tag = self.starttag(node, "table", CLASS=" ".join(classes), **atts)
self.body.append(tag)
def setup_translators(app):
if app.builder.format != "html":
return
if not app.registry.translators.items():
translator = types.new_class(
"BootstrapHTML5Translator",
(
BootstrapHTML5TranslatorMixin,
app.builder.default_translator_class,
),
{},
)
app.set_translator(app.builder.name, translator, override=True)
else:
for name, klass in app.registry.translators.items():
translator = types.new_class(
"BootstrapHTML5Translator",
(
BootstrapHTML5TranslatorMixin,
klass,
),
{},
)
app.set_translator(name, translator, override=True)
def setup(app):
app.connect("builder-inited", setup_translators)
local/recipes/dev/mesa-clc/source/docs/_exts/depfile.py
+36
View File
@@ -0,0 +1,36 @@
# Copyright © 2021 Collabora Ltd
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sub license, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice (including the
# next paragraph) shall be included in all copies or substantial portions
# of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
# IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
# ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
def create_depfile(app, env):
if not app.config.depfile:
return
with open(app.config.depfile, 'w') as f:
for doc in env.found_docs:
path = env.doc2path(doc)
f.write('{0}: {1}\n'.format(app.outdir, path))
def setup(app):
app.add_config_value('depfile', None, 'env')
app.connect('env-updated', create_depfile)
local/recipes/dev/mesa-clc/source/docs/_exts/formatting.py
+50
View File
@@ -0,0 +1,50 @@
# formatting.py
# Sphinx extension providing formatting for Gallium-specific data
# (c) Corbin Simpson 2010
# Public domain to the extent permitted; contact author for special licensing
import sphinx.addnodes
from sphinx.util.nodes import split_explicit_title
from docutils import nodes, utils
def parse_opcode(env, sig, signode):
opcode, desc = sig.split("-", 1)
opcode = opcode.strip().upper()
desc = " (%s)" % desc.strip()
signode += sphinx.addnodes.desc_name(opcode, opcode)
signode += sphinx.addnodes.desc_annotation(desc, desc)
return opcode
def ext_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
has_explicit_title, title, ext = split_explicit_title(text)
parts = ext.split('_', 2)
if parts[0] == 'VK':
full_url = f'https://docs.vulkan.org/refpages/latest/refpages/source/{ext}.html'
elif parts[0] == 'GL':
full_url = f'https://registry.khronos.org/OpenGL/extensions/{parts[1]}/{parts[1]}_{parts[2]}.txt'
else:
raise Exception(f'Unexpected API: {parts[0]}')
pnode = nodes.reference(title, title, internal=False, refuri=full_url)
return [pnode], []
def vkfeat_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
has_explicit_title, title, ext = split_explicit_title(text)
full_url = f'https://docs.vulkan.org/spec/latest/chapters/features.html#features-{ext}'
pnode = nodes.reference(title, title, internal=False, refuri=full_url)
return [pnode], []
def setup(app):
app.add_object_type("opcode", "opcode", "%s (TGSI opcode)", parse_opcode)
app.add_role('ext', ext_role)
app.add_role('vk-feat', vkfeat_role)
local/recipes/dev/mesa-clc/source/docs/_exts/nir.py
+158
View File
@@ -0,0 +1,158 @@
# Copyright © 2021 Intel Corporation
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sub license, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice (including the
# next paragraph) shall be included in all copies or substantial portions
# of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
# IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
# ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
import docutils.nodes
import mako.template
import os
import sphinx
from sphinx.directives import SphinxDirective
from sphinx.domains import Domain
from sphinx.util.nodes import make_refnode
import sys
import textwrap
THIS_DIR = os.path.dirname(os.path.abspath(__file__))
MESA_DIR = os.path.join(THIS_DIR, '..', '..')
NIR_PATH = os.path.join(MESA_DIR, 'src', 'compiler', 'nir')
sys.path.append(NIR_PATH)
import nir_opcodes
OP_DESC_TEMPLATE = mako.template.Template("""
<%
def src_decl_list(num_srcs):
return ', '.join('nir_def *src' + str(i) for i in range(num_srcs))
def to_yn(b):
return 'Y' if b else 'N'
%>
**Properties:**
.. list-table::
:header-rows: 1
* - Per-component
- Associative
- 2-src commutative
* - ${to_yn(op.output_size == 0)}
- ${to_yn('associative' in op.algebraic_properties)}
- ${to_yn('2src_commutative' in op.algebraic_properties)}
${("**Description:** " + op.description) if op.description != "" else ""}
**Constant-folding:**
.. code-block:: c
${textwrap.indent(op.const_expr, ' ')}
**Builder function:**
.. c:function:: nir_def *nir_${op.name}(nir_builder *, ${src_decl_list(op.num_inputs)})
""")
def parse_rst(state, parent, rst):
vl = docutils.statemachine.ViewList(rst.splitlines())
state.nested_parse(vl, 0, parent)
def nir_alu_type_name(t, s):
if s:
return '{}[{}]'.format(t, s)
else:
return '{}[N]'.format(t)
def build_alu_op_desc(state, env, op):
desc = sphinx.addnodes.desc(domain='nir', objtype='aluop')
# Add the signature
sig = sphinx.addnodes.desc_signature()
desc.append(sig)
sig += sphinx.addnodes.desc_name(op.name, op.name)
params = sphinx.addnodes.desc_parameterlist()
for i, t, s in zip(range(100), op.input_types, op.input_sizes):
params += docutils.nodes.Text(nir_alu_type_name(t, s) + ' ')
params += sphinx.addnodes.desc_parameter('', 'src' + str(i))
sig += params
sig += sphinx.addnodes.desc_returns('', nir_alu_type_name(op.output_type, op.output_size))
nir_domain = env.get_domain('nir')
sig['ids'].append(nir_domain.add_alu_op_ref(op))
# Build the description
content = sphinx.addnodes.desc_content()
desc.append(content)
parse_rst(state, content, OP_DESC_TEMPLATE.render(op=op, textwrap=textwrap))
return desc
class NIRALUOpcodesDirective(SphinxDirective):
def run(self):
return [build_alu_op_desc(self.state, self.env, op)
for op in nir_opcodes.opcodes.values()]
class NIRDomain(Domain):
"""A new NIR directive
To list all NIR ALU opcodes with their descriptions:
```rst
.. nir:alu-opcodes::
```
To reference a NIR opcode, ``:nir:alu-op:`fadd```
"""
name = 'nir'
roles = {
'alu-op': sphinx.roles.XRefRole(),
}
directives = {
'alu-opcodes': NIRALUOpcodesDirective,
}
initial_data = {
'alu-op-refs': [],
}
def add_alu_op_ref(self, op):
"""Add reference to an ALU op."""
self.data['alu-op-refs'].append((op.name, self.env.docname))
return 'nir-alu-op-' + op.name
def resolve_xref(self, env, fromdocname, builder, typ, target, node,
contnode):
for opname, todocname in self.data['alu-op-refs']:
if target == opname:
targ = 'nir-alu-op-' + opname
return make_refnode(builder, fromdocname, todocname, targ,
contnode, targ)
return None
def setup(app):
app.add_domain(NIRDomain)
local/recipes/dev/mesa-clc/source/docs/amber.rst
+46
View File
@@ -0,0 +1,46 @@
Amber Branch
============
After Mesa 21.3, all non-Gallium DRI drivers were removed from the Mesa
source-tree. These drivers are still being maintained to some degree,
but only on the ``amber`` branch, and only for critical fixes.
These drivers include:
- Radeon
- r200
- i915
- i965
- Nouveau (the DRI driver for NV04-NV20)
At the same time, the OpenSWR Gallium driver was removed from the Mesa
source-tree, because it was already practically speaking unmaintained and
the actively maintained LLVMpipe offers much of the same functionality.
Users with Intel GPUs that were using i965 should migrate to either Iris
or Crocus, depending on their GPU. These drivers generally speaking both
perform better and have more features than i965 had, and due to sharing
more code with the rest of the Mesa infrastructure, gets more bug fixes
and features.
Similarly, users of i915 should migrate to i915g (the Gallium driver for
the same hardware), as it's still being maintained.
Users who depend on the removed drivers will have to use them built from
the Amber branch in order to get updates.
Building
--------
The Amber branch has some extra logic to be able to coexist with recent
Mesa releases without them stepping on each others toes. In order to
enable that logic, you need to pass the ``-Damber=true`` flag to Meson.
Documentation
-------------
On `docs.mesa3d.org <https://docs.mesa3d.org/>`__, we currently only
publish the documentation from our main branch. But you can view the
documentation for the Amber branch `here
<https://gitlab.freedesktop.org/mesa/mesa/-/tree/amber/docs>`__.
local/recipes/dev/mesa-clc/source/docs/android.rst
+544
View File
@@ -0,0 +1,544 @@
Android
=======
Mesa hardware drivers can be built for Android one of two ways: built
into the Android OS using the ndk-build build system on older versions
of Android, or out-of-tree using the Meson build system and the
Android NDK.
The ndk-build build system has proven to be hard to maintain, as one
needs a built Android tree to build against, and it has never been
tested in CI. The Meson build system flow is frequently used by
Chrome OS developers for building and testing Android drivers.
When building llvmpipe or lavapipe for Android the ndk-build workflow
is also used, but there are additional steps required to add the driver
to the Android OS image.
Preparing offline compilers
---------------------------
For cross-compiling the nvk driver, mesa_clc compiler binary needs to be
prepared first:
.. code-block:: sh
meson setup build-compiler \
-Dprefix=/tmp/mesa-compiler \
-Dbuildtype=release \
-Dstrip=true \
-Dplatforms= \
-Dgallium-drivers= \
-Dvulkan-drivers= \
-Dmesa-clc=enabled \
-Dinstall-mesa-clc=true
meson install -C build-compiler
export PATH=/tmp/mesa-compiler/bin:$PATH
For panvk, ``-Dtools=panfrost -Dinstall-precomp-compiler=true`` is
additionally needed.
Building using the Android NDK
------------------------------
Download and install the NDK using whatever method you normally would.
Then, create your Meson cross file to use it, something like this
``~/.local/share/meson/cross/android-aarch64`` file:
.. code-block:: ini
[constants]
ndk_path = <absolute path to NDK>
[binaries]
ar = ndk_path / 'toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android-ar'
c = ['ccache', ndk_path / 'toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android34-clang']
cpp = ['ccache', ndk_path / 'toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android34-clang++', '-fno-exceptions', '-fno-unwind-tables', '-fno-asynchronous-unwind-tables', '--start-no-unused-arguments', '-static-libstdc++', '--end-no-unused-arguments']
c_ld = 'lld'
cpp_ld = 'lld'
strip = ndk_path / 'toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android-strip'
[host_machine]
system = 'android'
cpu_family = 'aarch64'
cpu = 'armv8'
endian = 'little'
For nvk, below rust toolchain preparation and cross file additions are needed:
.. code-block:: sh
rustup target add aarch64-linux-android
.. code-block:: ini
[properties]
bindgen_clang_arguments = ['-target', 'aarch64-linux-android', '--sysroot', ndk_path / 'toolchains/llvm/prebuilt/linux-x86_64/sysroot']
[binaries]
rust = ['rustc', '--target', 'aarch64-linux-android']
Now, use that cross file for your Android build directory (as in this
one cross-compiling the turnip driver for a stock Pixel phone)
.. code-block:: sh
meson setup build-android-aarch64 \
--cross-file android-aarch64 \
-Dplatforms=android \
-Dplatform-sdk-version=34 \
-Dandroid-stub=true \
-Dandroid-libbacktrace=disabled \
-Degl=disabled \
-Dgallium-drivers= \
-Dvulkan-drivers=freedreno \
-Dfreedreno-kmds=kgsl
meson compile -C build-android-aarch64
For drm drivers, ``-Dallow-fallback-for=libdrm`` is needed. Besides,
``-Dallow-fallback-for=libdrm -Dmesa-clc=system`` is needed by nvk, and
``-Dprecomp-compiler=system`` is additionally needed by panvk.
Replacing Android drivers on stock Android
------------------------------------------
The vendor partition with the drivers is normally mounted from a
read-only disk image on ``/vendor``. To be able to replace them for
driver development, we need to unlock the device and remount
``/vendor`` read/write.
.. code-block:: sh
adb disable-verity
adb reboot
adb remount -R
adb remount
Now you can replace drivers as in:
.. code-block:: sh
adb push build-android-aarch64/src/freedreno/vulkan/libvulkan_freedreno.so /vendor/lib64/hw/vulkan.sdm710.so
Note this command doesn't quite work because libvulkan wants the
SONAME to match. You can use ``patchelf`` to fix this:
.. code-block:: sh
cp build-android-aarch64/src/freedreno/vulkan/libvulkan_freedreno.so /tmp/vulkan.sdm710.so
patchelf --set-soname vulkan.sdm710.so /tmp/vulkan.sdm710.so
adb push /tmp/vulkan.sdm710.so /vendor/lib64/hw/
Replacing Android drivers on Chrome OS
--------------------------------------
Chrome OS's ARC++ is an Android container with hardware drivers inside
of it. The vendor partition with the drivers is normally mounted from
a read-only squashfs image on disk. For doing rapid driver
development, you don't want to regenerate that image. So, we'll take
the existing squashfs image, copy it out on the host, and then use a
bind mount instead of a loopback mount so we can update our drivers
using scp from outside the container.
On your device, you'll want to make ``/`` read-write. ssh in as root
and run:
.. code-block:: sh
crossystem dev_boot_signed_only=0
/usr/share/vboot/bin/make_dev_ssd.sh --remove_rootfs_verification --partitions 4
reboot
Then, we'll switch Android from using an image for ``/vendor`` to using a
bind-mount from a directory we control.
.. code-block:: sh
cd /opt/google/containers/android/
mkdir vendor-ro
mount -o loop vendor.raw.img vendor-ro
cp -a vendor-ro vendor-rw
emacs config.json
In the ``config.json``, you want to find the block for ``/vendor`` and
change it to::
{
"destination": "/vendor",
"type": "bind",
"source": "/opt/google/containers/android/vendor-rw",
"options": [
"bind",
"rw"
]
},
Now, restart the UI to do a full reload:
.. code-block:: sh
restart ui
At this point, your android container is restarted with your new
bind-mount ``/vendor``, and if you use ``android-sh`` to shell into it
then the ``mount`` command should show::
/dev/root on /vendor type ext2 (rw,seclabel,relatime)
Now, replacing your DRI driver with a new one built for Android should
be a matter of:
.. code-block:: sh
scp msm_dri.so $HOST:/opt/google/containers/android/vendor-rw/lib64/dri/
You can do your build of your DRI driver using ``emerge-$BOARD
arc-mesa-freedreno`` (for example) if you have a source tree with
ARC++, but it should also be possible to build using the NDK as
described above. There are currently rough edges with this, for
example the build will require that you have your arc-libdrm build
available to the NDK, assuming you're building anything but the
Freedreno Vulkan driver for KGSL. You can mostly put things in place
with:
.. code-block:: sh
scp $HOST:/opt/google/containers/android/vendor-rw/lib64/libdrm.so \
NDKDIR/sysroot/usr/lib/aarch64-linux-android/lib/
ln -s \
/usr/include/xf86drm.h \
/usr/include/libsync.h \
/usr/include/libdrm \
NDKDIR/sysroot/usr/include/
It seems that new invocations of an application will often reload the
DRI driver, but depending on the component you're working on you may
find you need to reload the whole Android container. To do so without
having to log in to Chrome again every time, you can just kill the
container and let it restart:
.. code-block:: sh
kill $(cat /run/containers/android-run_oci/container.pid )
Adding out-of-tree drivers to Android OS image
----------------------------------------------
When building your own Android OS images it's possible to add
drivers built out of tree directly into the OS image. For
running llvmpipe and lavapipe on Android this step is required
to ensure Android is able to load the drivers correctly.
The following steps provide and example for building
the android cuttlefish image following the official Android
documentation from https://source.android.com/docs/setup
When building llvmpipe or lavapipe for Android, it is required
to do this so that the permissions for accessing the library
are set correctly.
Following the Android documentation, we can run the following
commands
.. code-block:: sh
repo init -b main -u https://android.googlesource.com/platform/manifest
repo sync -c -j8
source build/envsetup.sh
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
Be aware that the sync command can take a long time to run as
it will download all of the source code. This will set up
the ``aosp_cf_x86_64_phone-trunk_staging-userdebug`` build target
for Android. Please note that the x86_64 cuttlefish target will require
you to build mesa for 32bit and 64bit. Next we need to copy the build
driver libraries into the source tree of Android and patch the binary names.
.. code-block:: sh
mkdir prebuilts/mesa
mkdir prebuilts/mesa/x86_64
mkdir prebuilts/mesa/x86
cp ${INSTALL_PREFIX_64}/lib/libEGL.so prebuilts/mesa/x86_64/
cp ${INSTALL_PREFIX_64}/lib/libgallium_dri.so prebuilts/mesa/x86_64/
cp ${INSTALL_PREFIX_64}/lib/libGLESv1_CM.so prebuilts/mesa/x86_64/
cp ${INSTALL_PREFIX_64}/lib/libGLESv2.so prebuilts/mesa/x86_64/
cp ${INSTALL_PREFIX_64}/lib/libvulkan_lvp.so prebuilts/mesa/x86_64/
cp ${INSTALL_PREFIX_32}/lib/libEGL.so prebuilts/mesa/x86
cp ${INSTALL_PREFIX_32}/lib/libgallium_dri.so prebuilts/mesa/x86/
cp ${INSTALL_PREFIX_32}/lib/libGLESv1_CM.so prebuilts/mesa/x86
cp ${INSTALL_PREFIX_32}/lib/libGLESv2.so prebuilts/mesa/x86
cp ${INSTALL_PREFIX_32}/lib/libvulkan_lvp.so prebuilts/mesa/x86
patchelf --set-soname libEGL_lp.so prebuilts/mesa/x86_64/libEGL.so
patchelf --set-soname libGLESv1_CM_lp.so prebuilts/mesa/x86_64/libGLESv1_CM.so
patchelf --set-soname libGLESv2_lp.so prebuilts/mesa/x86_64/libGLESv2.so
patchelf --set-soname vulkan.lvp.so prebuilts/mesa/x86_64/libvulkan_lvp.so
patchelf --set-soname libEGL_lp.so prebuilts/mesa/x86/libEGL.so
patchelf --set-soname libGLESv1_CM_lp.so prebuilts/mesa/x86/libGLESv1_CM.so
patchelf --set-soname libGLESv2_lp.so prebuilts/mesa/x86/libGLESv2.so
patchelf --set-soname vulkan.lvp.so prebuilts/mesa/x86/libvulkan_lvp.so
We then need to create an ``prebuilts/mesa/Android.bp`` build file to include
the libraries in the build.
.. code-block::
cc_prebuilt_library_shared {
name: "libgallium_dri",
arch: {
x86_64: {
srcs: ["x86_64/libgallium_dri.so"],
},
x86: {
srcs: ["x86/libgallium_dri.so"],
},
},
strip: {
none: true,
},
relative_install_path: "egl",
shared_libs: ["libc", "libdl", "liblog", "libm"],
check_elf_files: false,
vendor: true
}
cc_prebuilt_library_shared {
name: "libEGL_lp",
arch: {
x86_64: {
srcs: ["x86_64/libEGL.so"],
},
x86: {
srcs: ["x86/libEGL.so"],
},
},
strip: {
none: true,
},
relative_install_path: "egl",
shared_libs: ["libc", "libdl", "liblog", "libm", "libcutils", "libdrm", "libhardware", "liblog", "libnativewindow", "libsync"],
check_elf_files: false,
vendor: true
}
cc_prebuilt_library_shared {
name: "libGLESv1_CM_lp",
arch: {
x86_64: {
srcs: ["x86_64/libGLESv1_CM.so"],
},
x86: {
srcs: ["x86/libGLESv1_CM.so"],
},
},
strip: {
none: true,
},
relative_install_path: "egl",
shared_libs: ["libc", "libdl", "liblog", "libm"],
check_elf_files: false,
vendor: true
}
cc_prebuilt_library_shared {
name: "libGLESv2_lp",
arch: {
x86_64: {
srcs: ["x86_64/libGLESv2.so"],
},
x86: {
srcs: ["x86_64/libGLESv2.so"],
},
},
strip: {
none: true,
},
relative_install_path: "egl",
shared_libs: ["libc", "libdl", "liblog", "libm"],
check_elf_files: false,
vendor: true
}
cc_prebuilt_library_shared {
name: "vulkan.lvp",
arch: {
x86_64: {
srcs: ["x86_64/libvulkan_lvp.so"],
},
x86: {
srcs: ["x86/libvulkan_lvp.so"],
},
},
strip: {
none: true,
},
relative_install_path: "hw",
shared_libs: ["libc", "libdl", "liblog", "libm", "libcutils", "libdrm", "liblog", "libnativewindow", "libsync", "libz"],
vendor: true
}
Next we need to update the device configuration to include the libraries
in the build, as well as set the appropriate system properties. We can
create the file
``device/google/cuttlefish/shared/mesa/device_vendor.mk``
.. code-block:: makefile
PRODUCT_SOONG_NAMESPACES += prebuilts/mesa
PRODUCT_PACKAGES += libglapi \
libGLESv1_CM_lp \
libGLESv2_lp \
libEGL_lp \
libgallium_dri.so \
vulkan.lvp
PRODUCT_VENDOR_PROPERTIES += \
ro.hardware.egl=lp \
ro.hardware.vulkan=lvp \
mesa.libgl.always.software=true \
mesa.android.no.kms.swrast=true \
debug.hwui.renderer=opengl \
ro.gfx.angle.supported=false \
debug.sf.disable_hwc_vds=1 \
ro.vendor.hwcomposer.mode=client
Also the file ``device/google/cuttlefish/shared/mesa/BoardConfig.mk``
.. code-block:: makefile
BOARD_VENDOR_SEPOLICY_DIRS += \
device/google/cuttlefish/shared/mesa/sepolicy
Next the file ``device/google/cuttlefish/shared/mesa/sepolicy/file_contexts``
.. code-block:: sh
/vendor/lib(64)?/egl/libEGL_lp\.so u:object_r:same_process_hal_file:s0
/vendor/lib(64)?/egl/libGLESv1_CM_lp\.so u:object_r:same_process_hal_file:s0
/vendor/lib(64)?/egl/libGLESv2_lp\.so u:object_r:same_process_hal_file:s0
/vendor/lib(64)?/libglapi\.so u:object_r:same_process_hal_file:s0
/vendor/lib(64)?/libgallium_dri\.so u:object_r:same_process_hal_file:s0
/vendor/lib(64)?/hw/vulkan\.lvp\.so u:object_r:same_process_hal_file:s0
After creating these files we need to modify the existing config files
to include these build files. First we modify
``device/google/cuttlefish/shared/phone/device_vendor.mk``
to add the below code in the spot where other device_vendor
files are included.
.. code-block:: sh
$(call inherit-product, device/google/cuttlefish/shared/mesa/device_vendor.mk)
Lastly we modify
``device/google/cuttlefish/vsoc_x86_64/BoardConfig.mk`` to include
the following line where the other BoardConfig files are included
.. code-block:: sh
-include device/google/cuttlefish/shared/mesa/BoardConfig.mk
Then we are set to continue following the official instructions to
build the cuttlefish target and run it in the cuttlefish emulator.
.. _android-android-system-properties:
Android System Properties
-------------------------
Android (generally) uses system properties rather than
:doc:`environment variables <envvars>` to control Mesa/Gallium behavior,
although there are some exceptions to this for
:ref:`Android app developers <envvars-android-app-developers>`.
With the ``os_get_option()`` helper, the environment variable names are
automatically translated to the corresponding system property name by:
- converting UPPER case to lower case
- replacing ``_`` with ``.``
- adding the ``mesa.`` prefix to ``<property_name>`` if it's not present already
- and then querying the system property name with the following prefixes, in
order:
#. ``debug.<property_name>``
#. ``vendor.<property_name>``
#. ``<property_name>``
For example, ``LIBGL_DEBUG`` will be queried as:
#. ``debug.mesa.libgl.debug``
#. ``vendor.mesa.libgl.debug``
#. ``mesa.libgl.debug``
This allows for default ``vendor.`` / ``mesa.`` properties to be overridden by
users at run-time with ``debug.`` values.
System properties can be queried with:
.. code-block:: sh
$ adb shell getprop <property_name>
System properties can be set with:
.. code-block:: sh
$ adb shell setprop <property_name> <value>
For example:
.. code-block:: sh
$ adb shell setprop debug.mesa.libgl.debug verbose
$ adb shell getprop debug.mesa.libgl.debug
verbose
NOTE: Any driver that wishes to support Android system properties should replace
any calls to ``getenv()`` with ``os_get_option()``, which automatically handles
both environment variables and Android system properties.
.. _envvars-android-app-developers:
Android App Developers
^^^^^^^^^^^^^^^^^^^^^^
Android app developers have two options to control Mesa behavior on un-rooted
devices:
- Environment variables, using the wrap shell script
- https://developer.android.com/ndk/guides/wrap-script.html
- ``debug.<property_name>`` system properties
App developers with access to rooted devices can also use ``vendor.`` and
``mesa.`` values, although ``debug.`` prefixes are recommended.
While the system properties values are used for each app invocation once set,
they do not persist across device reboots.
Android Driver Developers
^^^^^^^^^^^^^^^^^^^^^^^^^
Android driver developers have three options to control Mesa behavior on
devices with ``root`` access:
#. ``debug.<property_name>``
#. ``vendor.<property_name>``
#. ``<property_name>``
The ``debug.`` prefix can be used without ``root``, while ``vendor.`` and
``mesa.`` prefixes require ``root``.
Any of the values can be set in the device's makefile to control Mesa
behavior, although ``vendor.`` and ``mesa.`` are typically used for this
purpose.
While the system properties values are used for each app invocation once set
at runtime, they do not persist across device reboots if configured with
``setprop``.
local/recipes/dev/mesa-clc/source/docs/application-issues.rst
+48
View File
@@ -0,0 +1,48 @@
Application Issues
==================
This page documents known issues with some OpenGL applications.
Topogun
-------
`Topogun <https://www.topogun.com/>`__ for Linux (version 2, at least)
creates a GLX visual without requesting a depth buffer. This causes bad
rendering if the OpenGL driver happens to choose a visual without a
depth buffer.
Mesa 9.1.2 and later (will) support a DRI configuration option to work
around this issue. Using the
`driconf <https://dri.freedesktop.org/wiki/DriConf>`__ tool, set the
"Create all visuals with a depth buffer" option before running Topogun.
Then, all GLX visuals will be created with a depth buffer.
Old OpenGL games
----------------
Some old OpenGL games (approx. ten years or older) may crash during
start-up because of an extension string buffer-overflow problem.
The problem is a modern OpenGL driver will return a very long string for
the ``glGetString(GL_EXTENSIONS)`` query and if the application naively
copies the string into a fixed-size buffer it can overflow the buffer
and crash the application.
The work-around is to set the ``MESA_EXTENSION_MAX_YEAR`` environment
variable to the approximate release year of the game. This will cause
the ``glGetString(GL_EXTENSIONS)`` query to only report extensions older
than the given year.
For example, if the game was released in 2001, do
.. code-block:: sh
export MESA_EXTENSION_MAX_YEAR=2001
before running the game.
Viewperf
--------
See the :doc:`Viewperf issues <viewperf>` page for a detailed list of
Viewperf issues.
local/recipes/dev/mesa-clc/source/docs/bugs.rst
+26
View File
@@ -0,0 +1,26 @@
Report a Bug
============
To file a Mesa bug, go to `GitLab on
freedesktop.org <https://gitlab.freedesktop.org/mesa/mesa/-/issues>`__.
Please follow these bug reporting guidelines:
- Check if a new version of Mesa is available which might have fixed
the problem.
- Check if your bug is already reported in the database.
- Monitor your bug report for requests for additional information, etc.
- Attach the output of running glxinfo or wglinfo. This will tell us
the Mesa version, which device driver you're using, etc.
- If you're reporting a crash, try to use your debugger (gdb) to get a
stack trace. Also, recompile Mesa in debug mode to get more detailed
information.
- Describe in detail how to reproduce the bug, especially with games
and applications that the Mesa developers might not be familiar with.
- Provide an `apitrace <https://github.com/apitrace/apitrace>`__ or
simple GLUT-based test program if possible.
The easier a bug is to reproduce, the sooner it will be fixed. Please do
everything you can to facilitate quickly fixing bugs. If your bug report
is vague or your test program doesn't compile easily, the problem may
not be fixed very quickly.
local/recipes/dev/mesa-clc/source/docs/ci/LAVA.rst
+129
View File
@@ -0,0 +1,129 @@
LAVA CI
=======
`LAVA <https://www.lavasoftware.org/>`__ is a system for functional
testing of boards including deploying custom bootloaders and kernels.
This is particularly relevant to testing Mesa because we often need
to change kernels for UAPI changes (and this lets us do full testing
of a new kernel during development), and our workloads can easily
take down boards when mistakes are made (kernel oopses, OOMs that
take out critical system services).
Available LAVA labs
-------------------
- Collabora `[dashboard] <https://lava.collabora.dev/scheduler/device_types>`__ (without authentication only health check jobs are displayed)
- Lima [dashboard not available]
Mesa-LAVA software architecture
-------------------------------
The gitlab-runner will run on some host that has access to the LAVA
lab, with tags like "mesa-ci-x86-64-lava-$DEVICE_TYPE" to control only
taking in jobs for the hardware that the LAVA lab contains. The
gitlab-runner spawns a Docker container with lavacli in it, and
connects to the LAVA lab using a predefined token to submit jobs under
a specific device type.
The LAVA instance manages scheduling those jobs to the boards present.
For a job, it will deploy the kernel, device tree, and the ramdisk
containing the CTS.
Deploying a new Mesa-LAVA lab
-----------------------------
You'll want to start with setting up your LAVA instance and getting
some boards booting using test jobs. Start with the stock QEMU
examples to make sure your instance works at all. Then, you'll need
to define your actual boards.
The device type in lava-gitlab-ci.yml is the device type you create in
your LAVA instance, which doesn't have to match the board's name in
``/etc/lava-dispatcher/device-types``. You create your boards under
that device type and the Mesa jobs will be scheduled to any of them.
Instantiate your boards by creating them in the UI or at the command
line attached to that device type, then populate their dictionary
(using an "extends" line probably referencing the board's template in
``/etc/lava-dispatcher/device-types``). Now, go find a relevant
health check job for your board as a test job definition, or cobble
something together from a board that boots using the same boot_method
and some public images, and figure out how to get your boards booting.
Once you can boot your board using a custom job definition, it's time
to connect Mesa CI to it. Install gitlab-runner and register as a
shared runner (you'll need a GitLab admin for help with this). The
runner *must* have a tag (like "mesa-ci-x86-64-lava-rk3399-gru-kevin")
to restrict the jobs it takes or it will grab random jobs from tasks
across ``gitlab.freedesktop.org``, and your runner isn't ready for
that.
The Docker image will need access to the LAVA instance. If it's on a
public network it should be fine. If you're running the LAVA instance
on localhost, you'll need to set ``network_mode="host"`` in
``/etc/gitlab-runner/config.toml`` so it can access localhost. Create a
gitlab-runner user in your LAVA instance, log in under that user on
the web interface, and create an API token. Copy that into a
``lavacli.yaml``:
.. code-block:: yaml
default:
token: <token contents>
uri: <URL to the instance>
username: gitlab-runner
Add a volume mount of that ``lavacli.yaml`` to
``/etc/gitlab-runner/config.toml`` so that the Docker container can
access it. You probably have a ``volumes = ["/cache"]`` already, so now it would be::
volumes = ["/home/anholt/lava-config/lavacli.yaml:/root/.config/lavacli.yaml", "/cache"]
Note that this token is visible to anybody that can submit MRs to
Mesa! It is not an actual secret. We could just bake it into the
GitLab CI YAML, but this way the current method of connecting to the
LAVA instance is separated from the Mesa branches (particularly
relevant as we have many stable branches all using CI).
Now it's time to define your test jobs in the driver-specific
gitlab-ci.yml file, using the device-specific tags.
Caching downloads
-----------------
To improve the runtime for downloading traces during traces job runs, you will
want a pass-through HTTP cache. On your runner box, install nginx:
.. code-block:: sh
sudo apt install nginx libnginx-mod-http-lua
Add the server setup files:
.. literalinclude:: fdo-cache
:name: /etc/nginx/sites-available/fdo-cache
:caption: /etc/nginx/sites-available/fdo-cache
.. literalinclude:: uri-caching.conf
:name: /etc/nginx/snippets/uri-caching.conf
:caption: /etc/nginx/snippets/uri-caching.conf
Edit the listener addresses in fdo-cache to suit the ethernet interface that
your devices are on.
Enable the site and restart nginx:
.. code-block:: sh
sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/fdo-cache /etc/nginx/sites-enabled/fdo-cache
sudo systemctl restart nginx
# First download will hit the internet
wget http://localhost/cache/?uri=https://s3.freedesktop.org/mesa-tracie-public/itoral-gl-terrain-demo/demo-v2.trace
# Second download should be cached.
wget http://localhost/cache/?uri=https://s3.freedesktop.org/mesa-tracie-public/itoral-gl-terrain-demo/demo-v2.trace
The trace runner script automatically sets the caching proxy, so there's no
need to modify anything in the Mesa CI YAML files.
Add ``LAVA_HTTP_CACHE_URI=http://localhost/cache/?uri=`` to your ``config.toml``
runner environment lines and you can use it for cached artifact downloads
instead of going all the way to freedesktop.org on each job.
local/recipes/dev/mesa-clc/source/docs/ci/bare-metal.rst
+10
View File
@@ -0,0 +1,10 @@
Bare-metal CI
=============
Bare-metal support is being removed from Mesa, and adding new devices is
no longer supported.
Please consider using one of the following alternatives:
- `CI-tron <https://docs.ci-tron.dev>`__
- :doc:`LAVA`
local/recipes/dev/mesa-clc/source/docs/ci/docker.rst
+74
View File
@@ -0,0 +1,74 @@
Docker CI
=========
For LLVMpipe and Softpipe CI, we run tests in a container containing
VK-GL-CTS, on the shared GitLab runners provided by `freedesktop
<https://www.freedesktop.org>`__
Software architecture
---------------------
The Docker containers are rebuilt using the shell scripts under
.gitlab-ci/container/ when the FDO\_DISTRIBUTION\_TAG changes in
.gitlab-ci.yml. The resulting images are around 1 GB, and are
expected to change approximately weekly (though an individual
developer working on them may produce many more images while trying to
come up with a working MR!).
gitlab-runner is a client that polls gitlab.freedesktop.org for
available jobs, with no inbound networking requirements. Jobs can
have tags, so we can have DUT-specific jobs that only run on runners
with that tag marked in the GitLab UI.
Since dEQP takes a long time to run, we mark the job as "parallel" at
some level, which spawns multiple jobs from one definition, and then
deqp-runner.sh takes the corresponding fraction of the test list for
that job.
To reduce dEQP runtime (or avoid tests with unreliable results), a
deqp-runner.sh invocation can provide a list of tests to skip. If
your driver is not yet conformant, you can pass a list of expected
failures, and the job will only fail on tests that aren't listed (look
at the job's log for which specific tests failed).
DUT requirements
----------------
In addition to the general :ref:`CI-job-user-expectations`, using
Docker requires:
* DUTs must have a stable kernel and GPU reset (if applicable).
If the system goes down during a test run, that job will eventually
time out and fail (default 1 hour). However, if the kernel can't
reliably reset the GPU on failure, bugs in one MR may leak into
spurious failures in another MR. This would be an unacceptable impact
on Mesa developers working on other drivers.
* DUTs must be able to run Docker
The Mesa gitlab-runner based test architecture is built around Docker,
so that we can cache the Debian package installation and CTS build
step across multiple test runs. Since the images are large and change
approximately weekly, the DUTs also need to be running some script to
prune stale Docker images periodically in order to not run out of disk
space as we rev those containers (perhaps `this script
<https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2980#note_169233611>`__).
Note that Docker doesn't allow containers to be stored on NFS, and
doesn't allow multiple Docker daemons to interact with the same
network block device, so you will probably need some sort of physical
storage on your DUTs.
* DUTs must be public
By including your device in .gitlab-ci.yml, you're effectively letting
anyone on the internet run code on your device. Docker containers may
provide some limited protection, but how much you trust that and what
you do to mitigate hostile access is up to you.
* DUTs must expose the DRI device nodes to the containers.
Obviously, to get access to the HW, we need to pass the render node
through. This is done by adding ``devices = ["/dev/dri"]`` to the
``runners.docker`` section of /etc/gitlab-runner/config.toml.
local/recipes/dev/mesa-clc/source/docs/ci/fdo-cache
+92
View File
@@ -0,0 +1,92 @@
proxy_cache_path /var/cache/nginx/ levels=1:2 keys_zone=my_cache:10m max_size=50g inactive=2w use_temp_path=off;
server {
listen 10.42.0.1:80 default_server;
listen 127.0.0.1:80 default_server;
listen [::]:80 default_server;
resolver 8.8.8.8;
root /var/www/html;
# Add index.php to the list if you are using PHP
index index.html index.htm index.nginx-debian.html;
server_name _;
location / {
# First attempt to serve request as file, then
# as directory, then fall back to displaying a 404.
try_files $uri $uri/ =404;
}
location /tmp {
# Lava server http artifacts to the clients; e.g. for the deploy action
alias /var/lib/lava/dispatcher/tmp;
}
proxy_cache my_cache;
# Wait for the cache creation when multiple query are done for the same file
proxy_cache_lock on;
proxy_cache_lock_age 30m;
proxy_cache_lock_timeout 1h;
location /force_cache {
internal;
# On some setups the cache headers will indicate to nginx that the
# artifacts shouldn't be cached, however if we know that that is not valid
# for lava usage this endpoint allows caching to be forced instead
proxy_cache_valid 200 48h;
proxy_ignore_headers Cache-Control Set-Cookie expires;
include snippets/uri-caching.conf;
}
location /fdo_cache {
internal;
# As the auth information in the query is being dropped, use
# the minimal possible cache validity, such that in practise
# every requests gets revalidated. This avoids
# unauthenticated downloads from our cache as the cache key doesn't
# include auth info
proxy_cache_valid 200 1s;
proxy_cache_revalidate on;
proxy_ignore_headers Cache-Control Set-Cookie expires;
set_by_lua_block $cache_key {
-- Set the cache key to the uri with the query stripped
local unescaped = ngx.unescape_uri(ngx.var.arg_uri);
local it,err = ngx.re.match(unescaped, "([^?]*).*")
if not it then
-- Fallback on the full uri as key if the regexp fails
return ngx.var.arg_uri;
end
return it[1]
}
proxy_cache_key $cache_key;
include snippets/uri-caching.conf;
}
location /cache {
# Gitlabs http server puts everything as no-cache even though
# the artifacts URLS don't change.
if ($arg_uri ~* /.*gitlab.*artifacts(\/|%2F)raw/ ) {
rewrite ^ /force_cache;
}
# fd.o's object storage has an embedded signature for
# authentication as part of its query. So use an adjusted cache key
# without the query
if ($arg_uri ~* .*your-objectstorage.com(\/|%2F)fdo-opa(\/|%2F)) {
rewrite ^ /fdo_cache;
}
# Set a really low validity together with cache revalidation; Our goal
# for caching isn't to lower the number of http requests but to
# lower the amount of data transfer. Also for some test
# scenarios (typical manual tests) the file at a given url
# might get modified so avoid confusion by ensuring
# revalidations happens often.
proxy_cache_valid 200 10s;
proxy_cache_revalidate on;
include snippets/uri-caching.conf;
}
}
local/recipes/dev/mesa-clc/source/docs/ci/index.rst
+410
View File
@@ -0,0 +1,410 @@
Continuous Integration
======================
GitLab CI
---------
GitLab provides a convenient framework for running commands in response to Git pushes.
We use it to test merge requests (MRs) before merging them (pre-merge testing),
as well as post-merge testing, for everything that hits ``main``
(this is necessary because we still allow commits to be pushed outside of MRs,
and even then the MR CI runs in the forked repository, which might have been
modified and thus is unreliable).
The CI runs a number of tests, from trivial build-testing to complex GPU rendering:
- Build testing for a number of configurations and platforms
- Sanity checks (``meson test``)
- Most drivers are also tested using several test suites, such as the
`Vulkan/GL/GLES conformance test suite <https://github.com/KhronosGroup/VK-GL-CTS>`__,
`Piglit <https://gitlab.freedesktop.org/mesa/piglit>`__, and others.
- Replay of application traces
A typical run takes between 20 and 30 minutes, although it can go up very quickly
if the GitLab runners are overwhelmed, which happens sometimes. When it does happen,
not much can be done besides waiting it out, or cancel it.
It is a good practice to check the ``Marge``
`queue <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests?assignee_username=marge-bot>`__
to evaluate if it is the right moment to trigger some testing jobs. ``Marge``
is configured to pick the MRs by assignment time, and this sort option is not
available in the Web UI. The `marge_queue <#marge-queue>`__ CLI tool
provides the list sorted by assignment time. The recommended way to manage the
trigger of those jobs is using our :abbr:`crnm (bin/ci/ci_run_n_monitor.sh)`
`cli tool <#running-specific-ci-jobs>`__.
Due to limited resources, we currently do not run the CI automatically
on every push; instead, we only run it automatically once the MR has
been assigned to ``Marge``, our merge bot.
If you're interested in the details, the main configuration file is ``.gitlab-ci.yml``,
and it references a number of other files in ``.gitlab-ci/``.
If the GitLab CI doesn't seem to be running on your fork (or MRs, as they run
in the context of your fork), you should check the "Settings" of your fork.
Under "CI / CD" → "General pipelines", make sure "Custom CI config path" is
empty (or set to the default ``.gitlab-ci.yml``), and that the
"Project-based pipeline visibility" box is checked.
If a specific CI farm is failing for reasons unrelated to your changes, make an
MR to disable the farm following the `farm management <#farm-management>`__
instructions.
If you're having other issues with the GitLab CI, your best bet is to ask
about it on ``#freedesktop`` on OFTC and tag `Daniel Stone
<https://gitlab.freedesktop.org/daniels>`__ (``daniels`` on IRC) or
`Eric Engestrom <https://gitlab.freedesktop.org/eric>`__ (``eric_engestrom`` on
IRC).
The three GitLab CI systems currently integrated are:
.. toctree::
:maxdepth: 1
bare-metal
LAVA
docker
Farm management
---------------
.. note::
Never mix disabling/re-enabling a farm with any change that can affect a job
that runs in another farm!
When the farm starts failing for any reason (power, network, out-of-space), it needs to be disabled by pushing separate MR with
.. code-block:: sh
git mv .ci-farms{,-disabled}/$farm_name
Find the GitLab handle of the farm's admin in ``.gitlab-ci/farm-rules.yml`` and
ping them on the MR. MRs to disable farms do not need to go through review, and
can be assigned to ``Marge`` directly.
After farm restore functionality can be enabled by pushing a new merge request,
which contains
.. code-block:: sh
git mv .ci-farms{-disabled,}/$farm_name
.. warning::
Pushing (``git push``) directly to ``main`` is forbidden; this change must
be sent as a :ref:`Merge Request <merging>`.
Application traces replay
-------------------------
The CI replays application traces with various drivers in two different jobs. The first
job replays traces listed in ``src/<driver>/ci/traces-<driver>.yml`` files and if any
of those traces fail the pipeline fails as well. The second job replays traces listed in
``src/<driver>/ci/restricted-traces-<driver>.yml`` and it is allowed to fail. This second
job is only created when the pipeline is triggered by ``marge-bot`` or any other user that
has been granted access to these traces.
A traces YAML file also includes a ``download-url`` pointing to a MinIO
instance where to download the traces from. While the first job should always work with
publicly accessible traces, the second job could point to an URL with restricted access.
Restricted traces are those that have been made available to Mesa developers without a
license to redistribute at will, and thus should not be exposed to the public. Failing to
access that URL would not prevent the pipeline to pass, therefore forks made by
contributors without permissions to download non-redistributable traces can be merged
without friction.
As an aside, only maintainers of such non-redistributable traces are responsible for
ensuring that replays are successful, since other contributors would not be able to
download and test them by themselves.
Those Mesa contributors that believe they could have permission to access such
non-redistributable traces can request permission to Daniel Stone <daniels@collabora.com>.
gitlab.freedesktop.org accounts that are to be granted access to these traces will be
added to the OPA policy for the MinIO repository as per
https://gitlab.freedesktop.org/freedesktop/helm-gitlab-infra/-/commit/a3cd632743019f68ac8a829267deb262d9670958 .
So the jobs are created in personal repositories, the name of the user's account needs
to be added to the rules attribute of the GitLab CI job that accesses the restricted
accounts.
.. toctree::
:maxdepth: 1
local-traces
Intel CI
--------
The Intel CI is not yet integrated into the GitLab CI.
For now, special access must be manually given (file a issue in
`the Intel CI configuration repo <https://gitlab.freedesktop.org/Mesa_CI/mesa_jenkins>`__
if you think you or Mesa would benefit from you having access to the Intel CI).
Results can be seen on `mesa-ci.01.org <https://mesa-ci.01.org>`__
if you are *not* an Intel employee, but if you are you
can access a better interface on
`mesa-ci-results.jf.intel.com <http://mesa-ci-results.jf.intel.com>`__.
The Intel CI runs a much larger array of tests, on a number of generations
of Intel hardware and on multiple platforms (X11, Wayland, DRM & Android),
with the purpose of detecting regressions.
Tests include
`Crucible <https://gitlab.freedesktop.org/mesa/crucible>`__,
`VK-GL-CTS <https://github.com/KhronosGroup/VK-GL-CTS>`__,
`dEQP <https://android.googlesource.com/platform/external/deqp>`__,
`Piglit <https://gitlab.freedesktop.org/mesa/piglit>`__,
`Skia <https://skia.googlesource.com/skia>`__,
`VkRunner <https://github.com/Igalia/vkrunner>`__,
`WebGL <https://github.com/KhronosGroup/WebGL>`__,
and a few other tools.
A typical run takes between 30 minutes and an hour.
If you're having issues with the Intel CI, your best bet is to ask about
it on ``#dri-devel`` on OFTC and tag `Nico Cortes
<https://gitlab.freedesktop.org/ngcortes>`__ (``ngcortes`` on IRC).
.. _CI-job-user-expectations:
CI job user expectations
------------------------
To make sure that testing of one vendor's drivers doesn't block
unrelated work by other vendors, we require that a given driver's test
farm produces a spurious failure no more than once a week. If every
driver had CI and failed once a week, we would be seeing someone's
code getting blocked on a spurious failure daily, which is an
unacceptable cost to the project.
To ensure that, driver maintainers with CI enabled should watch the Flakes panel
of the `CI flakes dashboard
<https://ci-stats-grafana.freedesktop.org/d/Ae_TLIwVk/mesa-ci-quality-false-positives?orgId=1>`__,
particularly the "Flake jobs" pane, to inspect jobs in their driver where the
automatic retry of a failing job produced a success a second time.
Additionally, most CI reports test-level flakes to an IRC channel, and flakes
reported as NEW are not expected and could cause spurious failures in jobs.
Please track the NEW reports in jobs and add them as appropriate to the
``-flakes.txt`` file for your driver.
Additionally, the test farm needs to be able to provide a short enough
turnaround time that we can get our MRs through marge-bot without the pipeline
backing up. As a result, we require that the test farm be able to handle a
whole pipeline's worth of jobs in less than 15 minutes (to compare, the build
stage is about 10 minutes). Given boot times and intermittent network delays,
this generally means that the test runtime as reported by deqp-runner should be
kept to 10 minutes.
If a test farm is short the HW to provide these guarantees, consider dropping
tests to reduce runtime. dEQP job logs print the slowest tests at the end of
the run, and Piglit logs the runtime of tests in the results.json.bz2 in the
artifacts. Or, you can add the following to your job to only run some fraction
(in this case, 1/10th) of the dEQP tests.
.. code-block:: yaml
variables:
DEQP_FRACTION: 10
to just run 1/10th of the test list.
For Collabora's LAVA farm, the `device types
<https://lava.collabora.dev/scheduler/device_types>`__ page can tell you how
many boards of a specific tag are currently available by adding the "Idle" and
"Busy" columns. For bare-metal, a gitlab admin can look at the `runners
<https://gitlab.freedesktop.org/admin/runners>`__ page. A pipeline should
probably not create more jobs for a board type than there are boards, unless you
clearly have some short-runtime jobs.
If a HW CI farm goes offline (network dies and all CI pipelines end up
stalled) or its runners are consistently spuriously failing (disk
full?), and the maintainer is not immediately available to fix the
issue, please push through an MR disabling that farm's jobs according
to the `Farm Management <#farm-management>`__ instructions.
Personal runners
----------------
Mesa's CI is currently run primarily on packet.net's m1xlarge nodes
(2.2Ghz Sandy Bridge), with each job getting 8 cores allocated. You
can speed up your personal CI builds (and marge-bot merges) by using a
faster personal machine as a runner. You can find the gitlab-runner
package in Debian, or use GitLab's own builds.
To do so, follow `GitLab's instructions
<https://docs.gitlab.com/ci/runners/runners_scope/#create-a-project-runner-with-a-runner-authentication-token>`__
to register your personal GitLab runner in your Mesa fork. Then, tell
Mesa how many jobs it should serve (``concurrent=``) and how many
cores those jobs should use (``FDO_CI_CONCURRENT=``) by editing these
lines in ``/etc/gitlab-runner/config.toml``, for example:
.. code-block:: toml
concurrent = 2
[[runners]]
environment = ["FDO_CI_CONCURRENT=16"]
Docker caching
--------------
The CI system uses Docker images extensively to cache
infrequently-updated build content like the CTS. The `freedesktop.org
CI templates
<https://gitlab.freedesktop.org/freedesktop/ci-templates/>`__ help us
manage the building of the images to reduce how frequently rebuilds
happen, and trim down the images (stripping out manpages, cleaning the
apt cache, and other such common pitfalls of building Docker images).
When running a container job, the templates will look for an existing
build of that image in the container registry under
``MESA_IMAGE_TAG``. If it's found it will be reused, and if
not, the associated ``.gitlab-ci/containers/<jobname>.sh`` will be run
to build it. So, when developing any change to container build
scripts, you need to update the associated ``MESA_IMAGE_TAG`` to
a new unique string. We recommend using the current date plus some
string related to your branch (so that if you rebase on someone else's
container update from the same day, you will get a Git conflict
instead of silently reusing their container)
When developing a given change to your Docker image, you would have to
bump the tag on each ``git commit --amend`` to your development
branch, which can get tedious. Instead, you can navigate to the
`container registry
<https://gitlab.freedesktop.org/mesa/mesa/container_registry>`__ for
your repository and delete the tag to force a rebuild. When your code
is eventually merged to main, a full image rebuild will occur again
(forks inherit images from the main repo, but MRs don't propagate
images from the fork into the main repo's registry).
Building locally using CI docker images
---------------------------------------
It can be frustrating to debug build failures on an environment you
don't personally have. If you're experiencing this with the CI
builds, you can use Docker to use their build environment locally. Go
to your job log, and at the top you'll see a line like::
Pulling docker image registry.freedesktop.org/anholt/mesa/debian/android_build:2020-09-11
We'll use a volume mount to make our current Mesa tree be what the
Docker container uses, so they'll share everything (their build will
go in _build, according to ``meson-build.sh``). We're going to be
using the image non-interactively so we use ``run --rm $IMAGE
command`` instead of ``run -it $IMAGE bash`` (which you may also find
useful for debug). Extract your build setup variables from
.gitlab-ci.yml and run the CI meson build script:
.. code-block:: sh
IMAGE=registry.freedesktop.org/anholt/mesa/debian/android_build:2020-09-11
sudo docker pull $IMAGE
sudo docker run --rm -v `pwd`:/mesa -w /mesa $IMAGE env PKG_CONFIG_PATH=/usr/local/lib/aarch64-linux-android/pkgconfig/:/android-ndk-r21d/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/pkgconfig/ GALLIUM_DRIVERS=freedreno UNWIND=disabled EXTRA_OPTION="-D android-stub=true -D llvm=disabled" DRI_LOADERS="-D glx=disabled -D gbm=disabled -D egl=enabled -D platforms=android" CROSS=aarch64-linux-android ./.gitlab-ci/meson-build.sh
All you have left over from the build is its output, and a _build
directory. You can hack on mesa and iterate testing the build with:
.. code-block:: sh
sudo docker run --rm -v `pwd`:/mesa $IMAGE meson compile -C /mesa/_build
Running specific CI jobs
------------------------
You can use ``bin/ci/ci_run_n_monitor.py`` to run specific CI jobs. It
will automatically take care of running all the jobs yours depends on,
and cancel the rest to avoid wasting resources.
See ``bin/ci/ci_run_n_monitor.py --help`` for all the options.
**Target jobs**
The ``--target`` argument takes a regex that you can use to select the
jobs names you want to run, e.g. ``--target 'zink.*'`` will run all the
Zink jobs, leaving the other drivers' jobs free for others to use.
Note that in fork pipelines, GitLab only adds the jobs for the files that have
changed **since the last push**, so you might not get the jobs you expect.
You can work around that by adding a dummy change in a file core to what you're
working on and then making a new push with that change, and removing that change
before you create the MR.
**GitLab token**
The ``--token`` argument is used to provide a GitLab token with rights to
interact with the pipeline. Using the argument, one can provide the value or
the name of the file having the value. If the argument is not provided, then
it checks if the value of ``$XDG_CONFIG_HOME`` has a valid directory (if not,
then uses ``$HOME/.config``), and there is a file called ``gitlab-token`` that
contains a token. The token required to work with this tool needs ``api``
scope permissions.
.. note::
To create that token, refer to
`create-a-personal-access-token <https://docs.gitlab.com/user/profile/personal_access_tokens/#create-a-personal-access-token>`_
and select the ``api`` scope. The token will only be shown once after creation,
so make sure you store it securely.
Marge queue
-----------
You can use ``bin/ci/marge_queue.sh`` to check how long the Marge queue is. As
mentioned, the merge flow is to assign MR to the ``Marge`` bot, to serialize
the verification and merge. Looking at the
`merge requests assigned to Marge <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests?assignee_username=marge-bot>`__
you can evaluate the size of the queue, since the ``marge_queue`` tool provides
sorted and summarized information about those MR in queue.
The tool requires a GitLab token as described in the
`crnm <#running-specific-ci-jobs>`__ section. It outputs the current queue
sorted by the ``assigned at`` to ``Marge``. It can also be used as an active
wait for another action in a pipe, using the ``--wait`` until the queue is
empty. The return code corresponds to the number of MRs in the queue, so when
it returns ``0``, one can, for example, start the ``crnm`` tool on a certain
pipeline.
Conformance Tests
-----------------
Some conformance tests require a special treatment to be maintained on GitLab CI.
This section lists their documentation pages.
.. toctree::
:maxdepth: 1
skqp
Updating GitLab CI Linux Kernel
-------------------------------
GitLab CI usually runs a bleeding-edge kernel. The following documentation has
instructions on how to uprev Linux Kernel in the GitLab CI ecosystem.
.. toctree::
:maxdepth: 1
kernel
Structured tagging
------------------
Some build scripts can be tagged with a deterministic tag to allow for
testing and validation of the build output. This section lists the
documentation pages for the structured tagging feature.
.. toctree::
:maxdepth: 1
structured-tagging
Reusing CI scripts for other projects
--------------------------------------
The CI scripts in ``.gitlab-ci/`` can be reused for other projects, to
facilitate reuse of the infrastructure, our scripts can be used as tools
to create containers and run tests on the available farms.
.. envvar:: EXTRA_LOCAL_PACKAGES
Define extra Debian packages to be installed in the container.
local/recipes/dev/mesa-clc/source/docs/ci/kernel.rst
+115
View File
@@ -0,0 +1,115 @@
Upreving Linux Kernel
=====================
Occasionally, the GitLab CI needs a Linux Kernel update to enable new kernel
features, device drivers, bug fixes etc to CI jobs.
Kernel uprevs in GitLab CI are relatively simple, but prone to lots of
side-effects since many devices from different platforms are involved in the
pipeline.
Kernel repository
-----------------
The Linux Kernel used in the GitLab CI is stored at the following repository:
https://gitlab.freedesktop.org/gfx-ci/linux
It is common that Mesa kernel brings some patches that were not merged on the
Linux mainline, that is why Mesa has its own kernel version which should be used
as the base for newer kernels.
So, one should base the kernel uprev from the last tag used in the Mesa CI,
please refer to ``.gitlab-ci/image-tags.yml`` ``KERNEL_TAG`` variable.
Every tag has a standard naming: ``vX.YZ-for-mesa-ci-<commit_short_SHA>``, which
can be created via the command:
:code:`git tag vX.YZ-for-mesa-ci-$(git rev-parse --short HEAD)`
Building Kernel
---------------
The kernel files are loaded from the artifacts uploaded to S3 from gfx-ci/linux.
Updating Kconfigs
^^^^^^^^^^^^^^^^^
When a Kernel uprev happens, it is worth compiling and cross-compiling the
Kernel locally, in order to update the Kconfigs accordingly. Remember that the
resulting Kconfig is a merge between *Mesa CI Kconfig* and *Linux tree
defconfig* made via ``merge_config.sh`` script located at Linux Kernel tree.
Kconfigs location
"""""""""""""""""
+------------+------------------------------------------------------+-------------------------------------+
| Platform | Mesa CI Kconfig location | Linux tree defconfig |
+============+======================================================+=====================================+
| arm | kernel/configs/mesa3d-ci_arm.config\@gfx-ci/linux | arch/arm/configs/multi_v7_defconfig |
+------------+------------------------------------------------------+-------------------------------------+
| arm64 | kernel/configs/mesa3d-ci_arm64.config\@gfx-ci/linux | arch/arm64/configs/defconfig |
+------------+------------------------------------------------------+-------------------------------------+
| x86-64 | kernel/configs/mesa3d-ci_x86_64.config\@gfx-ci/linux | arch/x86/configs/x86_64_defconfig |
+------------+------------------------------------------------------+-------------------------------------+
Updating image tags
-------------------
Every kernel uprev should update the following tag:
:code:`.gitlab-ci/image-tags.yml` tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **KERNEL_TAG** to use the new kernel
Development routine
-------------------
1. Compile the newer kernel locally for each platform.
2. Compile device trees for ARM platforms
3. Update Kconfigs. Are new Kconfigs necessary? Is CONFIG_XYZ_BLA deprecated? Does the ``merge_config.sh`` override an important config?
4. Push a new development branch to `Kernel repository`_ based on the latest kernel tag used in GitLab CI
5. Hack ``build-kernel.sh`` script to clone kernel from your development branch
6. Update image tags. See `Updating image tags`_
7. Run the entire CI pipeline, all the automatic jobs should be green. If some job is red or taking too long, you will need to investigate it and probably ask for help.
When the Kernel uprev is stable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Push a new tag to Mesa CI `Kernel repository`_
2. Update KERNEL_URL ``debian/x86_test-gl`` job definition
3. Open a merge request, if it is not opened yet
Tips and Tricks
---------------
Compare pipelines
^^^^^^^^^^^^^^^^^
To have the most confidence that a kernel uprev does not break anything in Mesa,
it is suggested that one runs the entire CI pipeline to check if the update affected the manual CI jobs.
Step-by-step
""""""""""""
1. Create a local branch in the same git ref (should be the main branch) before branching to the kernel uprev kernel.
2. Push this test branch
3. Run the entire pipeline against the test branch, even the manual jobs
4. Now do the same for the kernel uprev branch
5. Compare the job results. If a CI job turned red on your uprev branch, it means that the kernel update broke the test. Otherwise, it should be fine.
Bare-metal custom kernels
^^^^^^^^^^^^^^^^^^^^^^^^^
Some CI jobs have support to plug in a custom kernel by simply changing a variable.
This is great, since rebuilding the kernel and rootfs may takes dozens of minutes.
For example, Freedreno jobs ``gitlab.yml`` manifest support a variable named
``BM_KERNEL``. If one puts a gz-compressed kernel URL there, the job will use that
kernel to boot the Freedreno bare-metal devices. The same works for ``BM_DTB`` in
the case of device tree binaries.
Careful reading of the job logs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sometimes a job may turn to red for reasons unrelated to the kernel update, e.g.
LAVA ``tftp`` timeout, problems with the freedesktop servers etc.
So it is important to see the reason why the job turned red, and retry it if an
infrastructure error has happened.
local/recipes/dev/mesa-clc/source/docs/ci/local-traces.rst
+45
View File
@@ -0,0 +1,45 @@
Running traces on a local machine
=================================
Prerequisites
-------------
- Install `Apitrace <https://apitrace.github.io/>`__
- Install `Renderdoc <https://renderdoc.org/>`__ (only needed for some traces)
- Download and compile `Piglit <https://gitlab.freedesktop.org/mesa/piglit>`__ and install his `dependencies <https://gitlab.freedesktop.org/mesa/piglit#2-setup>`__
- Download traces you want to replay from `traces-db <https://gitlab.freedesktop.org/gfx-ci/tracie/traces-db/>`__
Running single trace
--------------------
A simple run to see the output of the trace can be done with
.. code-block:: sh
apitrace replay -w name_of_trace.trace
For more information, look into the `Apitrace documentation <https://github.com/apitrace/apitrace/blob/master/docs/USAGE.markdown>`__.
For comparing checksums use:
.. code-block:: sh
cd piglit/replayer
export PIGLIT_SOURCE_DIR="../"
./replayer.py compare trace -d test path/name_of_trace.trace 0 # replace with expected checksum
Simulating CI trace job
-----------------------
Sometimes it's useful to be able to test traces on your local machine instead of the Mesa CI runner. To simulate the CI environment as closely as possible.
Download the YAML file from your driver's ``ci/`` directory and then change the path in the YAML file from local proxy or MinIO to the local directory (URL-like format ``file://``)
.. code-block:: sh
# The PIGLIT_REPLAY_DEVICE_NAME has to match name in the YAML file.
export PIGLIT_REPLAY_DEVICE_NAME='your_device_name'
export PIGLIT_REPLAY_DESCRIPTION_FILE='path_to_mesa_traces_file.yml'
./piglit run -l verbose --timeout 300 -j10 replay ~/results/
Note: For replaying traces, you may need to allow higher GL and GLSL versions. You can achieve that by setting  ``MESA_GLSL_VERSION_OVERRIDE`` and ``MESA_GL_VERSION_OVERRIDE``.
local/recipes/dev/mesa-clc/source/docs/ci/skqp.rst
+33
View File
@@ -0,0 +1,33 @@
SkQP
====
`SkQP <https://skia.org/docs/dev/testing/skqp/>`__ stands for SKIA Quality
Program conformance tests. Basically, it has sets of rendering tests and unit
tests to ensure that `SKIA <https://skia.org/>`__ is meeting its design specifications on a specific
device.
The rendering tests have support for GL, GLES and Vulkan backends and test some
rendering scenarios.
And the unit tests check the GPU behavior without rendering images, using any of the GL/GLES or Vulkan drivers.
SkQP reports
------------
SkQP generates reports after finishing its execution, and deqp-runner collects
them in the job artifacts results directory under the test name. Click the
'Browse' button from a failing job to get to them.
SkQP failing tests
------------------
SkQP rendering tests will have a range of pixel values allowed for the driver's
rendering for a given test. This can make the "expected" image in the result
output look rather strange, but you should be able to make sense of it knowing
that.
In SkQP itself, testcases can have increased failing pixel thresholds added to
them to keep CI green when the rendering is "correct" but out of normal range.
However, we don't support changing the thresholds in our testing. Because any
driver rendering not meeting the normal thresholds will trigger Android CTS
failures, we treat them as failures and track them as expected failures the
```*-fails.txt`` file.`
local/recipes/dev/mesa-clc/source/docs/ci/structured-tagging.rst
+359
View File
@@ -0,0 +1,359 @@
================================
Structured Tagging for CI Builds
================================
This document explains the new structural tagging system integrated into our CI pipeline. Structural
tagging ensures that every build and test job is tied to a unique, reproducible build state by
computing a deterministic tag from each component's build script (and its relevant inputs, such as
patches) and verifying that tag at both build and test time.
Overview
--------
Structural tagging enhances container and rootfs tag management with an automated, end-to-end
process. Key aspects include:
Deterministic Tag Generation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
During the build, the system calculates a tag (an MD5 hash) from the contents of the build script
plus any extra files that affect the build. This tag represents the "structure" of the build.
YAML-Declared Tags
~~~~~~~~~~~~~~~~~~
For each component, a tag is declared in the YAML configuration file (located at
``.gitlab-ci/conditional-build-image-tags.yml``). The declared value is used to verify that the
build script has not changed without an accompanying update to the tag.
Dual-Phase Verification
~~~~~~~~~~~~~~~~~~~~~~~
* **Build Time:** The build script calls the helper function ``ci_build_time_tag_check`` immediately after calculating the tag. This function compares the calculated tag against the declared tag and writes the computed tag to a file (located at ``/mesa-ci-build-tag/``), ensuring early detection of mismatches.
* **Test Time:** Later, test scripts invoke ``ci_tag_test_time_check`` to read the stored tag and confirm that the tests run against the expected build version. A mismatch here will cause the test job to fail immediately.
Automated Tag Updates
~~~~~~~~~~~~~~~~~~~~~
A helper script ``bin/ci/update_tag.py`` is provided to list, check, and update tags for all or
individual components. This tool is intended to simplify the process of keeping the declared tags
synchronized with the build scripts.
How it works
------------
The mechanism considers a "component" any build script that follows the
``.gitlab-ci/container/build-*.sh`` pattern and also uses the ``ci_tag_*`` prefixed functions provided by
``.gitlab-ci/setup_test_env.sh``.
Suppose that SkQP just received the structured tagging support.
Let's look how the build and test phases work.
.. graphviz::
:caption: Structured Tagging
digraph StructuredTagging {
rankdir=TD;
node [style=filled, fillcolor=lightgray];
// =========================
// Build Phase Subgraph
// =========================
subgraph cluster_build {
label="Build Phase";
style=dashed;
// Define nodes with descriptive IDs and labels.
tag_decl [
label="SKQP_TAG declared in\n.gitlab-ci/conditional-build-image-tags.yml",
shape=note, fillcolor=white
];
calc_tag [
label="build-skqp.sh:\nCalculate tag (build script content + patches)",
shape=box, style="rounded,filled", fillcolor=lightgray
];
early_check [
label="container_pre_build.sh:\nCheck all structured tags early",
shape=box, style="rounded,filled", fillcolor=lightgray
];
validate_tag [
label="Validate calculated tag\nagainst declared SKQP_TAG",
shape=box, style="rounded,filled", fillcolor=lightgray
];
build_decision [
label="Is calculated tag equal\nto declared SKQP_TAG?",
shape=diamond, fillcolor=lightyellow
];
fail_build [
label="Fail build",
shape=rounded, fillcolor=salmon
];
write_tag [
label="Write calculated tag to\n/var/tmp/mesa-ci-build-tag/SKQP_TAG",
shape=box, style="rounded,filled", fillcolor=lightblue
];
compile_skqp [
label="Compile SkQP",
shape=box, fillcolor=palegreen
];
// Define edges for the build phase.
tag_decl -> calc_tag;
calc_tag -> validate_tag;
early_check -> validate_tag;
validate_tag -> build_decision;
build_decision -> fail_build [label="No"];
build_decision -> write_tag [label="Yes"];
write_tag -> compile_skqp;
}
// =========================
// Test Phase Subgraph
// =========================
subgraph cluster_test {
label="Test Phase";
style=dashed;
// Define nodes with descriptive IDs and labels.
skqp_running [
label="Is SKQP running?",
shape=diamond, fillcolor=lightyellow
];
ci_var_include [
label="image-tags.yml:\nincludes\ncontainer-builds-image-tags.yml",
shape=note, fillcolor=white
];
ci_var [
label="CI Variable\n(CONDITIONAL_BUILD_SKQP_TAG)\nfrom container-builds-image-tags.yml",
shape=note, fillcolor=white
];
ci_var_extends [
label="This job extends\n.container-builds-skqp\nMaking SKQP_TAG=CONDITIONAL_BUILD_SKQP_TAG",
shape=note, fillcolor=white
];
check_tag [
label="deqp-runner.sh:\nPull tag in /var/tmp/mesa-ci-build-tag/SKQP_TAG",
shape=box, style="rounded,filled", fillcolor=lightblue
];
decision [
label="Is calculated tag equal\nto declared SKQP_TAG?",
shape=diamond, fillcolor=lightyellow
];
proceed_test [
label="Proceed the test job",
shape=box, fillcolor=palegreen
];
fail_test [
label="Fail test",
shape=box, fillcolor=salmon
];
// Define edges for the test phase.
skqp_running -> check_tag [label="Yes"];
skqp_running -> proceed_test [label="No"];
check_tag -> decision;
decision -> proceed_test [label="Yes"];
decision -> fail_test [label="Mismatch"];
ci_var_extends -> decision;
ci_var -> ci_var_extends;
ci_var_include -> ci_var;
}
}
Build-Time Checks
~~~~~~~~~~~~~~~~~
During the build phase:
* **Tag Calculation:**
In the component's build script (named following the convention ``build-<component>.sh``), the
function ``_ci_calculate_tag`` computes an MD5 hash based on:
- The build script's contents.
- Any additional files (e.g. patches) that affect the build.
* **Validation:**
The build script calls ``ci_tag_build_time_check`` to verify that the current value of the component's
tag (passed in as an environment variable) matches the tag calculated by the build script.
* **Failure on Mismatch:**
If the tags do not match, the build is aborted. This prevents any accidental use of stale or mismatched artifacts.
* **Early checks:**
Right now, the `container_pre_build.sh` script is responsible for checking the structured tagging
in all registered components. So, we can check quickly, before the component's build starts, if
the tag is correct.
* **Tag writing:**
The build script writes the computed tag into a new file the structured tagging directory, namely
``/mesa-ci-build-tag/<component>_TAG``.
Test-Time Checks
~~~~~~~~~~~~~~~~
In the test scripts (for example, in ``.gitlab-ci/deqp-runner.sh``):
* **Verification:**
The test job retrieves the tag written into the artifact (e.g. from ``/mesa-ci-build-tag/DEQP_RUNNER_TAG``) and then calls:
.. code-block:: bash
ci_tag_test_time_check "DEQP_RUNNER_TAG"
* **Purpose:**
This check ensures that the tests are run against the exact build that was produced. If a mismatch is found, the test job fails immediately.
.. note::
Even when the developer forgets to update the ``image-tags.yml`` file when needed, the test job
will fail if the tag is not correct, given that the ``conditional-build-image-tags.yml``
file is properly updated.
Adding a New Component Tag
--------------------------
To integrate structured tagging for a new component (for example, ``my_component``), follow these steps:
1. **Modify the Build Script:**
- In your build script (e.g. ``.gitlab-ci/container/build-my-component.sh``), map out the external files that can affect the build output.
*Tip:* You can mimic the approach in ``build-angle.sh`` early variable declaration to get the tag.
- Immediately after calculating the tag, add a validation step:
.. code-block:: bash
PATCH_FILES=("...")
ci_tag_build_time_check "MY_COMPONENT_TAG" "${PATCH_FILES[@]}"
2. **If the component is run in a DUT job, update the passthrough script:**
On ``.gitlab-ci/common/generate-env.sh``:
.. code-block:: bash
VARS=(
...
MY_COMPONENT_TAG
...
)
3. **Update the CI YAMLs:**
- In your conditional image tags file (e.g. ``.gitlab-ci/conditional-build-image-tags.yml``), add an entry for your component:
.. code-block:: yaml
variables:
CONDITIONAL_BUILD_MY_COMPONENT_TAG: <initial-tag-value>
- Now we need to update the build related YAMLs to include the new component tag. In ``.gitlab-ci/container/gitlab-ci.yml``, add a new hidden job:
.. code-block:: yaml
.container-builds-my-component:
variables:
MY_COMPONENT_TAG: "${CONDITIONAL_BUILD_MY_COMPONENT_TAG}"
- It is time to modify the job that builds the component image to include the new component tag. Let's suppose that only the ``debian/arm64_test-gl`` job builds the component image. We need to add the new component tag to the job as an extension:
.. code-block:: yaml
debian/arm64_test-gl:
extends:
- .container-builds-my-component
- .container-builds-my-component2
variables:
# CI_BUILD_COMPONENTS is a space-separated list of components used during early tag checks
CI_BUILD_COMPONENTS: "my_component my_component2"
- Now, ``MY_COMPONENT_TAG`` will be used by the ``ci_tag_build_time_check`` and ``ci_tag_test_time_check`` functions, only for jobs that extend the ``.container-builds-my-component`` job.
- And the ``CI_BUILD_COMPONENTS`` variable will be swept to perform the early checks.
.. warning::
Do not forget to update your main image tags file (e.g. ``.gitlab-ci/image-tags.yml``) if necessary, check the header comments of the modified files for more details.
.. note::
Also, note that the main image tags file (``.gitlab-ci/image-tags.yml``) does not define the
conditional build tags directly.
Instead, it **retrieves** values such as ``MY_COMPONENT_TAG`` from the `includes` directive of the
``.gitlab/container-builds-image-tags.yml`` file. This setup ensures centralized management of
tag values and maintains consistency across various components and jobs.
Updating Component Tags with the Helper Script
----------------------------------------------
The helper script ``bin/ci/update_tag.py`` assists with tag management. Its key functionalities include:
* **Listing Available Components:**
.. code-block:: bash
./bin/ci/update_tag.py --list
* **Updating All Component Tags:**
.. code-block:: bash
./bin/ci/update_tag.py --all
* **Updating a Specific Component Tag:**
.. code-block:: bash
./bin/ci/update_tag.py --include my_component
./bin/ci/update_tag.py --include 'my_component.*'
* **Running a Check:**
.. code-block:: bash
./bin/ci/update_tag.py --check my_component
./bin/ci/update_tag.py --check my_component1 --check my_component2
This script uses the same underlying functions as in the build scripts to generate the deterministic tag and then updates the YAML file accordingly.
Ensure that your python environment has the requirements installed, see ``bin/ci/requirements.txt`` for the list of dependencies.
Limitations
-----------
The current implementation has some known limitations:
* **Local Utility Script Constraints:**
When running the update/tagging utility locally, the build inputs used by the build script (such
as environment variables defined in the YAML) are not automatically applied. For example, if the
tag calculation relies on a variable like ``EXTRA_MESON_ARGS``, you must manually set or mock its
value locally to generate the correct tag. Otherwise, the computed tag may be incorrect, and you
might need to run the actual build job (and extract the expected tag from the error message) to
verify the value. Future improvements may leverage tools like gitlab-ci-local to better reproduce
the YAML environment locally.
* **Timing Sensitivity:**
If the build script is modified after the early check (performed by the utility script) but before the actual build job runs, the calculated tag will differ from the declared tag. This discrepancy will block the build consistently until the YAML declaration is updated.
* **Manual Update Requirement:**
In this initial version, updating the ``image-tags.yml`` must be done manually. If this file is
not updated, the build scripts will not be validated properly.
However, the test-time check will still catch mismatches and abort the job, ensuring that any
issues do not go unnoticed.
Troubleshooting and FAQ
-----------------------
* **Tag Mismatch Errors:**
If you encounter a tag mismatch error, verify that:
- The build script and its additional inputs (patches, environment variables, etc.) are current.
- The declared tag in ``.gitlab-ci/conditional-build-image-tags.yml`` has been updated accordingly. Use the update helper if necessary.
* **Local Testing Challenges:**
When running the update utility locally, ensure that you mock any YAML-dependent variables (e.g., EXTRA_MESON_ARGS) to simulate the CI environment.
Conclusion
----------
The new structural tagging system provides a robust, automated method to ensure that every CI build
is uniquely identified and that tests run against the correct build state. By integrating
deterministic tag calculation with dual-phase verification and a dedicated update helper script,
this system minimizes human error and streamlines the CI process.
.. note::
Be aware of the current limitations, especially around local testing and the manual update
requirement, as you integrate and use structural tagging. Future improvements are planned to
address these issues.
Happy tagging!
local/recipes/dev/mesa-clc/source/docs/ci/uri-caching.conf
+44
View File
@@ -0,0 +1,44 @@
set $proxy_authorization '';
set_by_lua $proxyuri '
local unescaped = ngx.unescape_uri(ngx.var.arg_uri);
local it, err = ngx.re.match(unescaped, "(https?://)(.*@)?([^/]*)(/.*)?");
if not it then
-- Hack to cause nginx to return 404
return "http://localhost/404"
end
local scheme = it[1];
local authstring = it[2];
local host = it[3];
local query = it[4];
if ngx.var.http_authorization and ngx.var.http_authorization ~= "" then
ngx.var.proxy_authorization = ngx.var.http_authorization;
elseif authstring then
auth = string.sub(authstring, 0, -2);
auth64 = ngx.encode_base64(auth);
ngx.var.proxy_authorization = "Basic " .. auth64;
end
-- Default to / if none is set to avoid using the request_uri query
if not query then
query = "/";
end
return scheme .. host .. query;
';
# Rewrite the location header to redirect back to this server. Do
# this using lua header filtering to allow for url encoding the original
# location header for use as a query parameter.
header_filter_by_lua_block {
if ngx.header.location then
ngx.header.location = "/cache?uri=" .. ngx.escape_uri(ngx.header.location);
end
}
add_header X-GG-Cache-Status $upstream_cache_status;
proxy_set_header Authorization $proxy_authorization;
proxy_pass $proxyuri;
local/recipes/dev/mesa-clc/source/docs/codingstyle.rst
+228
View File
@@ -0,0 +1,228 @@
Coding Style
============
Mesa is over 20 years old and the coding style has evolved over time.
Some old parts use a style that's a bit out of date. Different sections
of mesa can use different coding style as set in the local EditorConfig
(.editorconfig) and/or Emacs (.dir-locals.el) file. Alternatively the
following is applicable. If the guidelines below don't cover something,
try following the format of existing, neighboring code.
``clang-format``
----------------
A growing number of drivers and components are adopting ``clang-format``
to standardize the formatting and make it easy for everyone to apply it.
You can re-format the code for the components that have opted-in to the
formatting enforcement (listed in ``.clang-format-include``) by simply
running ``ninja -C build/ clang-format``.
Since mass-reformatting commits can be an annoying extra jump to go
through when looking at ``git blame``, you can configure it to ignore
them by running::
git config blame.ignoreRevsFile .git-blame-ignore-revs
Most code editors also support automatically formatting code as you
write it; check your editor or its plug-ins to see how to enable this.
Vim
***
Add this to your ``.vimrc`` to automatically format any C & C++ file
(that has a .clang-format config) when you save it:
.. code:: vim
augroup ClangFormatOnSave
au!
function! ClangFormatOnSave()
" Only format files that have a .clang-format in a parent folder
if !empty(findfile('.clang-format', '.;'))
let l:formatdiff = 1 " Only format lines that have changed
py3f /usr/share/clang/clang-format.py
endif
endfunction
autocmd BufWritePre *.h,*.c,*.cc,*.cpp call ClangFormatOnSave()
augroup END
If ``/usr/share/clang/clang-format.py`` doesn't exist, try
``/usr/share/clang/clang-format-$CLANG_VERSION/clang-format.py``
(replacing ``$CLANG_VERSION`` with your clang version). If your distribution
has put the file somewhere else, look through the files in the package
providing ``clang-format``.
Emacs
*****
Add this to your ``.emacs`` to automatically format any C & C++ file
(that has a .clang-format config) when you save it:
.. code:: emacs
(load "/usr/share/clang/clang-format.el")
(defun clang-format-save-hook-for-this-buffer ()
"Create a buffer local save hook."
(add-hook 'before-save-hook
(lambda ()
(when (locate-dominating-file "." ".clang-format")
(clang-format-buffer))
;; Continue to save.
nil)
nil
;; Buffer local hook.
t))
;; Run this for each mode you want to use the hook.
(add-hook 'c-mode-hook (lambda () (clang-format-save-hook-for-this-buffer)))
(add-hook 'c++-mode-hook (lambda () (clang-format-save-hook-for-this-buffer)))
If ``/usr/share/clang/clang-format.el`` doesn't exist, look through the
files in the package providing ``clang-format`` in your distribution.
If you can't find anything (e.g. on Debian/Ubuntu), refer to `this StackOverflow
answer <https://stackoverflow.com/questions/59690583/how-do-you-use-clang-format-on-emacs-ubuntu/59850773#59850773>`__
to install clang-format through Emacs instead.
git ``pre-commit`` hook
***********************
If your editor doesn't support this, or if you don't want to enable it, you
can always just run ``ninja clang-format`` to format everything, or add
a ``pre-commit`` hook that runs this automatically whenever you ``git
commit`` by adding the following in your ``.git/hooks/pre-commit``:
.. code:: sh
shopt -s globstar
git clang-format $upstream -- $(grep -E '^[^#]' .clang-format-include)
# replace $upstream with the name of the remote tracking upstream mesa
# if you don't know, it's probably `origin`
Basic formatting guidelines
---------------------------
- 3-space indentation, no tabs.
- Limit lines to 78 or fewer characters. The idea is to prevent line
wrapping in 80-column editors and terminals. There are exceptions,
such as if you're defining a large, static table of information.
- Opening braces go on the same line as the if/for/while statement. For
example:
.. code-block:: c
if (condition) {
foo;
} else {
bar;
}
- Put a space before/after operators. For example, ``a = b + c;`` and
not ``a=b+c;``
- This GNU indent command generally does the right thing for
formatting:
.. code-block:: sh
indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
- Use comments wherever you think it would be helpful for other
developers. Several specific cases and style examples follow. Note
that we roughly follow `Doxygen <https://www.doxygen.nl>`__
conventions.
Single-line comments:
.. code-block:: c
/* null-out pointer to prevent dangling reference below */
bufferObj = NULL;
Or,
.. code-block:: c
bufferObj = NULL; /* prevent dangling reference below */
Multi-line comment:
.. code-block:: c
/* If this is a new buffer object id, or one which was generated but
* never used before, allocate a buffer object now.
*/
We try to quote the OpenGL specification where prudent:
.. code-block:: c
/* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
*
* "An INVALID_OPERATION error is generated for any of the following
* conditions:
*
* * <length> is zero."
*
* Additionally, page 94 of the PDF of the OpenGL 4.5 core spec
* (30.10.2014) also says this, so it's no longer allowed for desktop GL,
* either.
*/
Function comment example:
.. code-block:: c
/**
* Create and initialize a new buffer object. Called via the
* ctx->Driver.CreateObject() driver callback function.
* \param name integer name of the object
* \param type one of GL_FOO, GL_BAR, etc.
* \return pointer to new object or NULL if error
*/
struct gl_object *
_mesa_create_object(GLuint name, GLenum type)
{
/* function body */
}
- Put the function return type and qualifiers on one line and the
function name and parameters on the next, as seen above. This makes
it easy to use ``grep ^function_name dir/*`` to find function
definitions. Also, the opening brace goes on the next line by itself
(see above.)
- Function names follow various conventions depending on the type of
function:
+---------------------+------------------------------------------+
| Convention | Explanation |
+=====================+==========================================+
| ``glFooBar()`` | a public GL entry point (in |
| | :file:`glapi_dispatch.c`) |
+---------------------+------------------------------------------+
| ``_mesa_FooBar()`` | the internal immediate mode function |
+---------------------+------------------------------------------+
| ``save_FooBar()`` | retained mode (display list) function in |
| | :file:`dlist.c` |
+---------------------+------------------------------------------+
| ``foo_bar()`` | a static (private) function |
+---------------------+------------------------------------------+
| ``_mesa_foo_bar()`` | an internal non-static Mesa function |
+---------------------+------------------------------------------+
- Constants, macros and enum names are ``ALL_UPPERCASE``, with \_
between words.
- Mesa usually uses camel case for local variables (Ex:
``localVarname``) while Gallium typically uses underscores (Ex:
``local_var_name``).
- Global variables are almost never used because Mesa should be
thread-safe.
- Booleans. Places that are not directly visible to the GL API should
prefer the use of ``bool``, ``true``, and ``false`` over
``GLboolean``, ``GL_TRUE``, and ``GL_FALSE``. In C code, this may
mean that ``#include <stdbool.h>`` needs to be added. The
``try_emit_*`` method ``src/mesa/state_tracker/st_glsl_to_tgsi.cpp``
can serve as an example.
local/recipes/dev/mesa-clc/source/docs/conf.py
+248
View File
@@ -0,0 +1,248 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# The Mesa 3D Graphics Library documentation build configuration file, created by
# sphinx-quickstart on Wed Mar 29 14:08:51 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
from hawkmoth.util import compiler
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.append(os.path.abspath('_exts'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'bootstrap',
'depfile',
'formatting',
'hawkmoth',
'nir',
'sphinx.ext.graphviz',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'The Mesa 3D Graphics Library'
copyright = '1995-2018, Brian Paul'
author = 'Brian Paul'
html_show_copyright = False
html_theme_path = ['.']
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'latest'
# The full version, including alpha/beta/rc tags.
release = 'latest'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['header-stubs']
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# Disable highlighting unless a language is specified, otherwise we'll get
# python keywords highlit in literal blocks.
highlight_language = 'none'
default_role = 'c:expr'
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'mesa3d_theme'
html_favicon = 'favicon.ico'
html_copy_source = False
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
html_extra_path = [
'_extra/',
'release-maintainers-keys.asc',
'features.txt',
'libGL.txt',
'README.UVD',
'README.VCE',
]
# -- Options for linkcheck ------------------------------------------------
linkcheck_ignore = [
r'specs/.*\.spec', # gets copied during the build process
r'news:.*', # seems linkcheck doesn't like the news: URI-scheme...
r'http://mesa-ci-results.jf.intel.com', # only available for Intel employees
r'https://gitlab.com/.*#.*', # needs JS eval
r'https://gitlab.freedesktop.org/.*#.*', # needs JS eval
r'https://github.com/.*#.*', # needs JS eval
r'https://www.intel.com/.*', # intel.com is blocking the linkcheck user-agent; maybe it can be customized to look like a browser?
r'https://sourceforge.net/.*', # blocking the linkcheck user-agent
r'https://.*\.sourceforge\.(net|io)/.*', # blocking the linkcheck user-agent
r'https://stackoverflow.com/.*', # blocking the linkcheck user-agent
r'https://(www|dev)\.vulkan\.org/.*', # blocking the linkcheck user-agent
r'https://crates.io/.*', # blocking the linkcheck user-agent
r'https://docs.vulkan.org/.*', # blocking the linkcheck user-agent
r'https://wikis.khronos.org/.*', # blocking the linkcheck user-agent
r'https://en.wikipedia.org/.*', # rate-limited, which linkcheck doesn't respect
r'https://www.freedesktop.org/.*', # protected by anubis
]
linkcheck_exclude_documents = [r'relnotes/.*']
linkcheck_allowed_redirects = {
# Pages that forward the front-page to a wiki or some explore-page
'https://www.freedesktop.org': 'https://www.freedesktop.org/wiki/',
'https://x.org': 'https://x.org/wiki/',
'https://dri.freedesktop.org/': 'https://dri.freedesktop.org/wiki/',
'https://gitlab.freedesktop.org/': 'https://gitlab.freedesktop.org/explore/groups',
'https://www.sphinx-doc.org/': 'https://www.sphinx-doc.org/en/master/',
# Pages that requires authentication
'https://gitlab.freedesktop.org/admin/runners': 'https://gitlab.freedesktop.org/users/sign_in',
'https://gitlab.freedesktop.org/profile/personal_access_tokens': 'https://gitlab.freedesktop.org/users/sign_in',
'https://support.broadcom.com/group/ecx/free-downloads': 'https://support.broadcom.com/c/portal/login',
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'TheMesa3DGraphicsLibrarydoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'TheMesa3DGraphicsLibrary.tex', 'The Mesa 3D Graphics Library Documentation',
'Brian Paul', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'themesa3dgraphicslibrary', 'The Mesa 3D Graphics Library Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'TheMesa3DGraphicsLibrary', 'The Mesa 3D Graphics Library Documentation',
author, 'TheMesa3DGraphicsLibrary', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Graphviz -------------------------------------------------
graphviz_output_format = 'svg'
# -- Options for hawkmoth -------------------------------------------------
hawkmoth_root = os.path.abspath(os.pardir)
mesa_root = os.path.join(os.path.dirname(__file__), os.pardir)
mesa_build_root = os.environ.get('MESA_BUILD_ROOT')
hawkmoth_clang = [
'-I{}/docs/header-stubs/'.format(mesa_root),
'-I{}/include/'.format(mesa_root),
'-I{}/src/'.format(mesa_root),
'-I{}/src/gallium/include/'.format(mesa_root),
'-I{}/src/intel/'.format(mesa_root),
'-I{}/src/mesa/'.format(mesa_root),
'-I{}/src/vulkan/util'.format(mesa_root),
'-I{}/src/'.format(mesa_build_root),
'-DHAVE_STRUCT_TIMESPEC',
'-DHAVE_PTHREAD',
'-DHAVE_ENDIAN_H',
]
hawkmoth_clang.extend(compiler.get_include_args())
# helpers for definining parameter direction
rst_prolog = '''
.. |in| replace:: **[in]**
.. |out| replace:: **[out]**
.. |inout| replace:: **[inout]**
'''
local/recipes/dev/mesa-clc/source/docs/conform.rst
+26
View File
@@ -0,0 +1,26 @@
Conformance Testing
===================
Mesa as a project does not get certified conformant by Khronos for the
APIs it implements. Rather, individual driver teams run the
conformance tests and submit their results on a set of hardware on a
particular operating system. The canonical list is at Khronos' list
of `conformant
products <https://www.khronos.org/conformance/adopters/conformant-products/>`_
and you can find some reports there by searching for "Mesa",
"Raspbian" and "RADV" for example.
Submitting conformance results to Khronos
-----------------------------------------
If your driver team is associated with an organization that is a
Khronos member and has submitted conformance for your API on another
software stack (likely you're a hardware company), it will probably be
easiest to submit your conformance through them.
If you are an individual developer or your organization hasn't
submitted results for the given API yet, X.Org is a member through
the Software Freedom Conservancy, and they can help submit your
conformance results to get added to the list of conformant products.
You should probably coordinate with board@foundation.x.org for your
first submission.
local/recipes/dev/mesa-clc/source/docs/devinfo.rst
+37
View File
@@ -0,0 +1,37 @@
Development Notes
=================
Adding Extensions
-----------------
To add a new GL extension to Mesa you have to do at least the following.
- If ``glext.h`` doesn't define the extension, edit ``include/GL/gl.h``
and add code like this:
.. code-block:: c
#ifndef GL_EXT_the_extension_name
#define GL_EXT_the_extension_name 1
/* declare the new enum tokens */
/* prototype the new functions */
/* TYPEDEFS for the new functions */
#endif
- In the ``src/mesa/glapi/glapi/gen/`` directory, add the new extension
functions and enums to the ``gl_API.xml`` file. Then, a bunch of
source files must be regenerated by executing the corresponding
Python scripts.
- Add a new entry to the ``gl_extensions`` struct in ``consts_exts.h`` if
the extension requires driver capabilities not already exposed by
another extension.
- Add a new entry to the ``src/mesa/main/extensions_table.h`` file.
- From this point, the best way to proceed is to find another
extension, similar to the new one, that's already implemented in Mesa
and use it as an example.
- If the new extension adds new GL state, the functions in ``get.c``,
``enable.c`` and ``attrib.c`` will most likely require new code.
- To determine if the new extension is active in the current context,
use the auto-generated ``_mesa_has_##name_str()`` function defined in
``src/mesa/main/extensions.h``.
local/recipes/dev/mesa-clc/source/docs/dispatch.rst
+209
View File
@@ -0,0 +1,209 @@
GL Dispatch
===========
Several factors combine to make efficient dispatch of OpenGL functions
fairly complicated. This document attempts to explain some of the issues
and introduce the reader to Mesa's implementation. Readers already
familiar with the issues around GL dispatch can safely skip ahead to the
:ref:`overview of Mesa's implementation <overview>`.
1. Complexity of GL Dispatch
----------------------------
Every GL application has at least one object called a GL *context*. This
object, which is an implicit parameter to every GL function, stores all
of the GL related state for the application. Every texture, every buffer
object, every enable, and much, much more is stored in the context.
Since an application can have more than one context, the context to be
used is selected by a window-system dependent function such as
``glXMakeContextCurrent``.
In environments that implement OpenGL with X-Windows using GLX, every GL
function, including the pointers returned by ``glXGetProcAddress``, are
*context independent*. This means that no matter what context is
currently active, the same ``glVertex3fv`` function is used.
This creates the first bit of dispatch complexity. An application can
have two GL contexts. One context is a direct rendering context where
function calls are routed directly to a driver loaded within the
application's address space. The other context is an indirect rendering
context where function calls are converted to GLX protocol and sent to a
server. The same ``glVertex3fv`` has to do the right thing depending on
which context is current.
Highly optimized drivers or GLX protocol implementations may want to
change the behavior of GL functions depending on current state. For
example, ``glFogCoordf`` may operate differently depending on whether or
not fog is enabled.
In multi-threaded environments, it is possible for each thread to have a
different GL context current. This means that poor old ``glVertex3fv``
has to know which GL context is current in the thread where it is being
called.
.. _overview:
2. Overview of Mesa's Implementation
------------------------------------
Mesa uses two per-thread pointers. The first pointer stores the address
of the context current in the thread, and the second pointer stores the
address of the *dispatch table* associated with that context. The
dispatch table stores pointers to functions that actually implement
specific GL functions. Each time a new context is made current in a
thread, these pointers are updated.
The implementation of functions such as ``glVertex3fv`` becomes
conceptually simple:
- Fetch the current dispatch table pointer.
- Fetch the pointer to the real ``glVertex3fv`` function from the
table.
- Call the real function.
This can be implemented in just a few lines of C code. The file
``src/mesa/glapi/glapitemp.h`` contains code very similar to this.
.. code-block:: c
:caption: Sample dispatch function
void glVertex3f(GLfloat x, GLfloat y, GLfloat z)
{
const struct _glapi_table * const dispatch = GET_DISPATCH();
dispatch->Vertex3f(x, y, z);
}
The problem with this simple implementation is the large amount of
overhead that it adds to every GL function call.
In a multithreaded environment, a naive implementation of
``GET_DISPATCH()`` involves a call to ``_mesa_glapi_get_dispatch()`` or
``_mesa_glapi_tls_Dispatch``.
3. Optimizations
----------------
A number of optimizations have been made over the years to diminish the
performance hit imposed by GL dispatch. This section describes these
optimizations. The benefits of each optimization and the situations
where each can or cannot be used are listed.
3.1. ELF TLS
~~~~~~~~~~~~
Starting with the 2.4.20 Linux kernel, each thread is allocated an area
of per-thread, global storage. Variables can be put in this area using
some extensions to GCC that called ``ELF TLS``. By storing the dispatch table
pointer in this area, the expensive call to ``pthread_getspecific`` and
the test of ``_mesa_glapi_Dispatch`` can be avoided. As we don't support for
Linux kernel earlier than 2.4.20, so we can always using ``ELF TLS``.
The dispatch table pointer is stored in a new variable called
``_mesa_glapi_tls_Dispatch``. A new variable name is used so that a single
libGL can implement both interfaces. This allows the libGL to operate
with direct rendering drivers that use either interface. Once the
pointer is properly declared, ``GET_DISPACH`` becomes a simple variable
reference.
.. code-block:: c
:caption: TLS ``GET_DISPATCH`` Implementation
extern __THREAD_INITIAL_EXEC struct _glapi_table *_mesa_glapi_tls_Dispatch;
#define GET_DISPATCH() _mesa_glapi_tls_Dispatch
3.2. Assembly Language Dispatch Stubs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many platforms have difficulty properly optimizing the tail-call in the
dispatch stubs. Platforms like x86 that pass parameters on the stack
seem to have even more difficulty optimizing these routines. All of the
dispatch routines are very short, and it is trivial to create optimal
assembly language versions. The amount of optimization provided by using
assembly stubs varies from platform to platform and application to
application. However, by using the assembly stubs, many platforms can
use an additional space optimization (see :ref:`below <fixedsize>`).
The biggest hurdle to creating assembly stubs is handling the various
ways that the dispatch table pointer can be accessed. There are four
different methods that can be used:
#. Using ``_mesa_glapi_Dispatch`` directly in builds for non-multithreaded
environments.
#. Using ``_mesa_glapi_Dispatch`` and ``_mesa_glapi_get_dispatch`` in
multithreaded environments.
#. Using ``_mesa_glapi_tls_Dispatch`` directly in TLS enabled multithreaded
environments.
People wishing to implement assembly stubs for new platforms should
focus on #3 if the new platform supports TLS. Otherwise implement #2.
Environments that do not support multithreading are
uncommon and not terribly relevant.
Selection of the dispatch table pointer access method is controlled by a
few preprocessor defines.
- If ``HAVE_PTHREAD`` is defined, method #2 is used.
- If none of the preceding are defined, method #1 is used.
Two different techniques are used to handle the various different cases.
On x86 and SPARC, a macro called ``GL_STUB`` is used. In the preamble of
the assembly source file different implementations of the macro are
selected based on the defined preprocessor variables. The assembly code
then consists of a series of invocations of the macros such as:
.. code-block:: c
:caption: SPARC Assembly Implementation of ``glColor3fv``
GL_STUB(Color3fv, _gloffset_Color3fv)
The benefit of this technique is that changes to the calling pattern
(i.e., addition of a new dispatch table pointer access method) require
fewer changed lines in the assembly code.
However, this technique can only be used on platforms where the function
implementation does not change based on the parameters passed to the
function. For example, since x86 passes all parameters on the stack, no
additional code is needed to save and restore function parameters around
a call to ``pthread_getspecific``. Since x86-64 passes parameters in
registers, varying amounts of code needs to be inserted around the call
to ``pthread_getspecific`` to save and restore the GL function's
parameters.
The other technique, used by platforms like x86-64 that cannot use the
first technique, is to insert ``#ifdef`` within the assembly
implementation of each function. This makes the assembly file
considerably larger (e.g., 29,332 lines for ``glapi_x86-64.S`` versus
1,155 lines for ``glapi_x86.S``) and causes simple changes to the
function implementation to generate many lines of diffs. Since the
assembly files are typically generated by scripts, this isn't a
significant problem.
Once a new assembly file is created, it must be inserted in the build
system. There are two steps to this. The file must first be added to
``src/mesa/sources``. That gets the file built and linked. The second
step is to add the correct ``#ifdef`` magic to
``src/mesa/glapi/glapi_dispatch.c`` to prevent the C version of the
dispatch functions from being built.
.. _fixedsize:
3.3. Fixed-Length Dispatch Stubs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To implement ``glXGetProcAddress``, Mesa stores a table that associates
function names with pointers to those functions. This table is stored in
``src/mesa/glapi/glprocs.h``. For different reasons on different
platforms, storing all of those pointers is inefficient. On most
platforms, including all known platforms that support TLS, we can avoid
this added overhead.
If the assembly stubs are all the same size, the pointer need not be
stored for every function. The location of the function can instead be
calculated by multiplying the size of the dispatch stub by the offset of
the function in the table. This value is then added to the address of
the first dispatch stub.
This path is activated by adding the correct ``#ifdef`` magic to
``src/mesa/glapi/glapi.c`` just before ``glprocs.h`` is included.
local/recipes/dev/mesa-clc/source/docs/download.rst
+64
View File
@@ -0,0 +1,64 @@
Downloading and Unpacking
=========================
Downloading
-----------
You can download the released versions of Mesa via
`HTTPS <https://archive.mesa3d.org/>`__ or
`FTP <ftp://ftp.freedesktop.org/pub/mesa/>`__.
Our release tarballs are GPG-signed, and the public keys are available
here: `release-maintainers-keys.asc <release-maintainers-keys.asc>`__.
Starting with the first release of 2017, Mesa's version scheme is
year-based. Filenames are in the form ``mesa-Y.N.P.tar.gz``, where ``Y``
is the year (two digits), ``N`` is an incremental number (starting at 0)
and ``P`` is the patch number (0 for the first release, 1 for the first
patch after that).
When a new release is coming, release candidates (betas) may be found in
the same directory, and are recognizable by the
``mesa-Y.N.P-rcX.tar.gz`` filename.
Unpacking
---------
Mesa releases are available in two formats: ``.tar.xz`` and ``.tar.gz``.
To unpack the tarball:
.. code-block:: sh
tar xf mesa-Y.N.P.tar.xz
or
.. code-block:: sh
tar xf mesa-Y.N.P.tar.gz
Contents
--------
Proceed to the :doc:`compilation and installation
instructions <install>`.
Demos, GLUT, and GLU
--------------------
A package of SGI's GLU library is available
`here <https://archive.mesa3d.org/glu/>`__
A package of Mark Kilgard's GLUT library is available
`here <https://archive.mesa3d.org/glut/>`__
The Mesa demos collection is available
`here <https://archive.mesa3d.org/demos/>`__
In the past, GLUT, GLU and the Mesa demos were released in conjunction
with Mesa releases. But since GLUT, GLU and the demos change
infrequently, they were split off into their own Git repositories:
`GLUT <https://gitlab.freedesktop.org/mesa/glut>`__,
`GLU <https://gitlab.freedesktop.org/mesa/glu>`__ and
`Demos <https://gitlab.freedesktop.org/mesa/demos>`__,
local/recipes/dev/mesa-clc/source/docs/drivers/amd/function-calls.rst
+173
View File
@@ -0,0 +1,173 @@
:orphan:
.. _aco-fn-calls:
Function call support in RADV/ACO
=================================
ACO supports function calls inside shaders - given a function signature and ABI, shaders can call
an arbitrary function, even via only a function pointer (i.e. with an unknown function definition).
This function call support is useful for implementing ray tracing pipelines (by representing individual RT shaders
as callable functions), but it also has potential use cases in GPGPU/Compute workloads.
This page serves to document the concepts involved in implementing function calls as well as an overview of the
implementation components.
Function call representation
----------------------------
In NIR, function calls are represented by a `nir_call_instr`. The instruction takes a `nir_function` representing
the function being called, as well as SSA defs for each call parameter.
NIR can also represent "indirect calls", i.e. calls where the function being called is
unknown - instead, the instruction takes an SSA def containing a function pointer to the callee. In this case, the
`nir_function` only serves to provide information about the function signature, i.e. how many and which parameters
the function takes.
Call instructions do not have return values - instead, return values are represented by so-called "return parameters".
Instead of an SSA value, these parameters are derefs, and the return value is written into the deref when the callee
returns. Return parameters can double as input parameters, too - the callee can read the previous value of the deref
before (potentially) overwriting it with a new value.
ACO's representation of function calls follows this very closely. Calls are described by the `p_call` pseudo-instruction.
The operands to this instruction are a function pointer (i.e. the address of the callee), followed by the call
parameters. Return parameters are handled differently, though: While the initial value of the return parameter is passed
as an operand, the call instruction produces new definitions that refer to the SSA values of the return parameters after
the function call returns. There is a special NIR intrinsic ``load_return_param_amd`` that can be used to access these
new definitions when lowering return parameter derefs to SSA form.
.. _div-calls:
Divergent calls
---------------
On CPUs, a call instruction will only ever jump to a single address. However, GPUs are SIMT, and the value of a function
pointer may be divergent, i.e. different threads try calling different functions within the same call instruction. AMD
hardware executes one instruction for all threads in lockstep, so the multiple callees have to be executed one after
the other.
This is handled by RADV in ``radv_nir_lower_call_abi``. In addition to the (non-divergent) function pointer to jump to,
``radv_nir_lower_call_abi`` prepends another parameter representing the (potentially divergent) function pointer for all
lanes. For callable functions, ``radv_nir_lower_call_abi`` wraps the function body in a condition that verifies that the
current thread's (divergent) pointer matches the (non-divergent) pointer that is currently being executed. This serves
to "mask off" all threads that wanted to jump to a different function than what is currently executing. At the very end,
``radv_nir_lower_call_abi`` inserts some code deciding whether to jump to the next callee or to return.
.. _stack:
Stack
-----
Supporting arbitrary function calls also means supporting recursion, and recursive functions need a stack.
AMD hardware provides instructions for accessing a per-thread scratch memory area in VRAM, and ACO uses this per-thread
scratch memory to set up its stack.
The stack frame for a function consists of all scratch memory allocated for this function in NIR, as well as space to
spill VGPRs if that is required. ACO adds a stack pointer as a parameter to every function - this stack pointer is added
to the offset inside the scratch space for all scratch loads/stores to make sure they don't overwrite stack frames of
caller functions.
ACO's call instructions take two stack-related operands: The current (caller) stack pointer and the caller's stack size.
When converting the call instruction to hardware instructions, ACO will add the caller stack size to the stack pointer
for the duration of the call (and subtract it again afterwards). This allows us to re-use the same stack pointer after
the call.
Implicit/System Parameters
--------------------------
In addition to parameters defined by the function signature, both RADV and ACO will insert additional parameters while
lowering calls. This is an overview of which lowering passes add which parameters.
Parameters added by ``radv_nir_lower_call_abi`` (see :ref:`Divergent calls <div-calls>`):
- "Uniform"/Non-divergent callee pointer
- Divergent function pointer
Parameters added by ACO: (see :ref:`Stack <stack>`)
- Stack pointer (uniform)
ABI Definition
--------------
The ABI (Application Binary Interface) defines specifics about the interaction between the function caller and the
callee (e.g. assignment of registers to parameters or register preservation). In ACO, the primary purpose of the ABI is
to define which register ranges are "preserved" (i.e. never overwritten by the callee) or "clobbered" (i.e. potentially
overwritten by the callee).
The caller can use preserved register ranges to store temporaries that are live across a call, and the callee can use
clobbered register ranges to store its own temporaries. If the callee wants to use registers from a preserved range,
then it needs to back up the value contained in the preserved register beforehand, and restore it when it's done using
the preserved register. Similarly, if there are not enough preserved registers for the caller to store all its
temporaries, the caller will need to spill excess temporaries to the stack.
ACO has to cater to different needs when defining ABIs: On one side, ray tracing traversal shaders demand to free up
the entire register file for the callee (Ray traversal is a really hot loop, so we don't want to spill anything at all).
Besides some parameters like the invocation ID, these shaders should be able to overwrite almost anything. On the other
side, RT traversal shaders should not be required to free up the register file when calling any-hit/intersection shaders
as this would also cause spilling during traversal. GPGPU compute workloads could fall anywhere between these extremes,
so a middle-ground solution is desirable for these.
ACO's way of defining an ABI divides the register file into "blocks" (``struct aco::ABI::RegisterBlock``). Each block
consists of a fixed number of preserved and clobbered registers, and a boolean determining whether the preserved or
clobbered registers come first in the block. Preserved and clobbered register ranges are defined by
repeating these blocks for as long as there are unassigned registers.
Some examples of preserved/clobbered register ranges using this approach::
For all examples, there are 108 SGPRs and 128 VGPRs to assign.
RegisterBlock:
clobbered_size: {16 sgpr, 16 vgpr}
preserved_size: {16 sgpr, 16 vgpr}
clobbered_first: false
results in:
v0-v15: preserved
v16-v31: clobbered
v32-v47: preserved
v48-v63: clobbered
v64-v79: preserved
v80-v95: clobbered
v96-v111: preserved
v112-v127: clobbered
s0-s15: preserved
s16-s31: clobbered
s32-s47: preserved
s48-s63: clobbered
s64-s79: preserved
s80-s95: clobbered
s96-s108: preserved
RegisterBlock:
clobbered_size: {128 sgpr, 256 vgpr}
preserved_size: {80 sgpr, 80 vgpr}
clobbered_first: false
results in:
v0-v79: preserved
v80-v127: clobbered
s0-s79: preserved
s80-s108: clobbered
An alternating preserved-clobbered-preserved pattern is useful for generic compute workloads, because the ratio of
preserved to clobbered registers is roughly the same, no matter how many registers are used by the shaders.
The latter example where the lower part of the register file is preserved and only some registers high up in the
register file are clobbered is suitable for any-hit/intersection shaders - traversal shader temporaries can live in the
preserved part low in the register file.
This block assignment is optional - if no ``RegisterBlock`` is given, the ABI defines the entire register range as
clobbered-by-default, although parameters that are not marked as clobbered via ``ACO_NIR_PARAM_ATTRIB_DISCARDABLE``
will continue being preserved.
Parameter Register Assignment
-----------------------------
If a ``RegisterBlock`` defines preserved and clobbered ranges, then parameters are assigned registers from either range
depending on ``ACO_NIR_PARAM_ATTRIB_DISCARDABLE`` - if parameters are marked as clobbered with this attribute, then they
are assigned a register in a clobbered range, otherwise they are assigned in a register in a preserved range. The order
of the parameters in the register file is not necessarily the same order as in the function signature - they may get
reordered if it's beneficial to fill gaps or for alignment.
If there is no ``RegisterBlock``, then registers will be assigned based on alignment only.
If there is no more space for a parameter in any of its corresponding register ranges, it will be moved to the stack.
local/recipes/dev/mesa-clc/source/docs/drivers/amd/hang-debugging.rst
+85
View File
@@ -0,0 +1,85 @@
:orphan:
.. _radv-debug-hang:
Debugging GPU hangs with RADV
=============================
UMR (optional)
--------------
UMR is needed for dumping a lot of useful information. Clone, build and install
`UMR <https://gitlab.freedesktop.org/tomstdenis/umr>`__. Do not forget to run
``chmod +s $(which umr)`` so RADV can actually access UMR.
UMR needs to access some kernel debug interfaces:
.. code-block:: sh
chmod 777 /sys/kernel/debug
chmod -R 777 /sys/kernel/debug/dri
Secure boot has to be disabled as well.
Generating and analyzing hang reports
-------------------------------------
With UMR installed, you can now set ``RADV_DEBUG=hang`` which makes RADV insert
trace markers and synchronization and check for hangs. The hang report will be
saved to ``~/radv_dumps_<pid>_<time>``. Inside the directory of the hang report,
there are a couple of files:
* ``*.spv``: SPIR-V binaries of the pipeline that was bound when the hang
occurred.
* ``addr_binding_report.log``: VK_EXT_address_binding_report logs.
* ``app_info.log``: ``VkApplicationInfo`` fields.
* ``bo_history.log``: A list of every GPU memory allocation and deallocation.
If the GPU hang was caused by a page fault, you can use
`radv_check_va.py <https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/src/amd/vulkan/radv_check_va.py>`__
to figure out if address is invalid or used after the memory was deallocated.
* ``bo_ranges.log``: Address ranges that were valid at the time of submission.
* ``dmesg.log``: Output of ``dmesg``, if available.
* ``gpu_info.log``: Fields of ``radeon_info``.
* ``pipeline.log``: IR of the shaders that were bound during the hang as well as
programm counters of waves executing said shaders and bound descriptors.
* ``registers.log``: Various GPU state registers.
* ``trace.log``: An annotated list of the command stream that caused the hang.
the commands that hung come after
``!!!!! This is the last trace point that was reached by the CP !!!!!``.
* ``umr_ring.log``: Similar to ``trace.log``.
* ``umr_waves.log``: A list of waves that were active at the time of the hang,
including register values.
* ``vm_fault.log``: The page fault address if a page fault occurred.
Note: By default, the backend IR (ACO or LLVM) and the disassembly should be
dumped to ``pipeline.log``. But due to shaders caching, you might need
``RADV_DEBUG=hang,nocache`` to get SPIR-V and NIR in the GPU hang report.
Debugging Steam games
---------------------
Steam games require a bit more work so RADV can access UMR: In your Steam library,
make sure **Tools** is checked and search for **Steam Linux Runtime**.
Under **Properties** -> **Installed Files**, click **Browse**, open
``_v2-entry-point`` and add
.. code-block:: sh
shift 2
exec "$@"
at the top of the file. Hang debugging can be enabled by selecting the faulting
game and adding ``RADV_DEBUG=hang %command%`` under **Properties** -> **General**
-> **LAUNCH OPTIONS**.
Debugging hangs without RADV_DEBUG=hang
---------------------------------------
In some situations, ``RADV_DEBUG=hang`` wouldn't be able to generate a GPU hang
report, like for synchronization issues (because it enables
``RADV_DEBUG=syncshaders`` behind the scene). An alternative solution is to
disable GPU recovery by adding ``amdgpu.gpu_recovery=0`` to your kernel command
line options. And then invoke UMR manually with
``umr --by-pci <pci_id> -O bits,halt_waves -go 0 -wa <ring> -go 1 2>&1`` for
dumping the waves and ``umr --by-pci <pci_id> -RS <ring> 2>&1`` for dumping the
rings once the GPU hang occurred.
local/recipes/dev/mesa-clc/source/docs/drivers/amd/hw/pops.rst
+477
View File
@@ -0,0 +1,477 @@
Primitive Ordered Pixel Shading
===============================
Primitive Ordered Pixel Shading (POPS) is the feature available starting from
GFX9 that provides the Fragment Shader Interlock or Fragment Shader Ordering
functionality.
It allows a part of a fragment shader — an ordered section (or a critical
section) — to be executed sequentially in rasterization order for different
invocations covering the same pixel position.
This article describes how POPS is set up in shader code and the registers. The
information here is currently provided for architecture generations up to GFX11.
Note that the information in this article is **not official** and may contain
inaccuracies, as well as incomplete or incorrect assumptions. It is based on the
shader code output of the Radeon GPU Analyzer for Rasterizer Ordered View usage
in Direct3D shaders, AMD's Platform Abstraction Library (PAL), ISA references,
and experimentation with the hardware.
Shader code
-----------
With POPS, a wave can dynamically execute up to one ordered section. It is fine
for a wave not to enter an ordered section at all if it doesn't need ordering on
its execution path, however.
The setup of the ordered section consists of three parts:
1. Entering the ordered section in the current wave — awaiting the completion of
ordered sections in overlapped waves.
2. Resolving overlap within the current wave — intrawave collisions (optional
and GFX9–10.3 only).
3. Exiting the ordered section — resuming overlapping waves trying to enter
their ordered sections.
GFX9–10.3: Entering the ordered section in the wave
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Awaiting the completion of ordered sections in overlapped waves is performed by
setting the POPS packer hardware register, and then polling the volatile
``pops_exiting_wave_id`` ALU operand source until its value exceeds the newest
overlapped wave ID for the current wave.
The information needed for the wave to perform the waiting is provided to it via
the SGPR argument ``COLLISION_WAVEID``. Its loading needs to be enabled in the
``SPI_SHADER_PGM_RSRC2_PS`` and ``PA_SC_SHADER_CONTROL`` registers (note that
the POPS arguments specifically need to be enabled not only in ``RSRC`` unlike
various other arguments, but in ``PA_SC_SHADER_CONTROL`` as well).
The collision wave ID argument contains the following unsigned values:
* [31]: Whether overlap has occurred.
* [29:28] (GFX10+) / [28] (GFX9): ID of the packer the wave should be associated
with.
* [25:16]: Newest overlapped wave ID.
* [9:0]: Current wave ID.
The 2020 RDNA and RDNA 2 ISA references contain incorrect offsets and widths of
the fields, possibly from an early development iteration, but the meanings of
them are accurate there.
The wait must not be performed if the "did overlap" bit 31 is set to 0,
otherwise it will result in a hang. Also, the bit being set to 0 indicates that
there are *both* no wave overlap *and no intrawave collisions* for the current
wave — so if the bit is 0, it's safe for the wave to skip all of the POPS logic
completely and execute the contents of the ordered section simply as usual with
unordered access as a potential additional optimization. The packer hardware
register, however, may be set even without overlap safely — it's the wait loop
itself that must not be executed if it was reported that there was no overlap.
The packer ID needs to be passed to the packer hardware register using
``s_setreg_b32`` so the wave can poll ``pops_exiting_wave_id`` on that packer.
On GFX9, the ``MODE`` (1) hardware register has two bits specifying which packer
the wave is associated with:
* [25]: The wave is associated with packer 1.
* [24]: The wave is associated with packer 0.
Initially, both of these bits are set 0, meaning that POPS is disabled for the
wave. If the wave needs to enter the ordered section, it must set bit 24 to 1 if
the packer ID in ``COLLISION_WAVEID`` is 0, or set bit 25 to 1 if the packer ID
is 1.
Starting from GFX10, the ``POPS_PACKER`` (25) hardware register is used instead,
containing the following fields:
* [2:1]: Packer ID.
* [0]: POPS enabled for the wave.
Initially, POPS is disabled for a wave. To start entering the ordered section,
bits 2:1 must be set to the packer ID from ``COLLISION_WAVEID``, and bit 0 needs
to be set to 1.
The wave IDs, both in ``COLLISION_WAVEID`` and ``pops_exiting_wave_id``, are
10-bit values wrapping around on overflow — consecutive waves are numbered 1022,
1023, 0, 1… This wraparound needs to be taken into account when comparing the
exiting wave ID and the newest overlapped wave ID.
Specifically, until the current wave exits the ordered section, its ID can't be
smaller than the newest overlapped wave ID or the exiting wave ID. So
``current_wave_id + 1`` can be subtracted from 10-bit wave IDs to remap them to
monotonically increasing unsigned values. In this case, the largest value,
0xFFFFFFFF, will correspond to the current wave, 10-bit values up to the current
wave ID will be in a range near 0xFFFFFFFF growing towards it, and wave IDs from
before the last wraparound will be near 0 increasing away from it. Subtracting
``current_wave_id + 1`` is equivalent to adding ``~current_wave_id``.
GFX9 has an off-by-one error in the newest overlapped wave ID: if the 10-bit
newest overlapped wave ID is greater than the 10-bit current wave ID (meaning
that it's behind the last wraparound point), 1 needs to be added to the newest
overlapped wave ID before using it in the comparison. This was corrected in
GFX10.
The exiting wave ID (not to be confused with "exited" — the exiting wave ID is
the wave that will exit the ordered section next) is queried via the
``pops_exiting_wave_id`` ALU operand source, numbered 239. Normally, it will be
one of the arguments of ``s_add_i32`` that remaps it from a wrapping 10-bit wave
ID to monotonically increasing one.
It's a volatile operand, and it needs to be read in a loop until its value
becomes greater than the newest overlapped wave ID (after remapping both to
monotonic). However, if it's too early for the current wave to enter the ordered
section, it needs to yield execution to other waves that may potentially be
overlapped — via ``s_sleep``. GFX9 requires a finite amount of delay to be
specified, AMD uses 3. Starting from GFX10, exiting the ordered section wakes up
the waiting waves, so the maximum delay of 0xFFFF can be used.
In pseudocode, the entering logic would look like this::
bool did_overlap = collision_wave_id[31];
if (did_overlap) {
if (gfx_level >= GFX10) {
uint packer_id = collision_wave_id[29:28];
s_setreg_b32(HW_REG_POPS_PACKER[2:0], 1 | (packer_id << 1));
} else {
uint packer_id = collision_wave_id[28];
s_setreg_b32(HW_REG_MODE[25:24], packer_id ? 0b10 : 0b01);
}
uint current_10bit_wave_id = collision_wave_id[9:0];
// Or -(current_10bit_wave_id + 1).
uint wave_id_remap_offset = ~current_10bit_wave_id;
uint newest_overlapped_10bit_wave_id = collision_wave_id[25:16];
if (gfx_level < GFX10 &&
newest_overlapped_10bit_wave_id > current_10bit_wave_id) {
++newest_overlapped_10bit_wave_id;
}
uint newest_overlapped_wave_id =
newest_overlapped_10bit_wave_id + wave_id_remap_offset;
while (!(src_pops_exiting_wave_id + wave_id_remap_offset >
newest_overlapped_wave_id)) {
s_sleep(gfx_level >= GFX10 ? 0xFFFF : 3);
}
}
The SPIR-V fragment shader interlock specification requires an invocation — an
individual invocation, not the whole subgroup — to execute
``OpBeginInvocationInterlockEXT`` exactly once. However, if there are multiple
begin instructions, or even multiple begin/end pairs, under divergent
conditions, a wave may end up waiting for the overlapped waves multiple times.
Thankfully, it's safe to set the POPS packer hardware register to the same
value, or to run the wait loop, multiple times during the wave's execution, as
long as the ordered section isn't exited in between by the wave.
GFX11: Entering the ordered section in the wave
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Instead of exposing wave IDs to shaders, GFX11 uses the "export ready" wave
status flag to report that the wave may enter the ordered section. It's awaited
by the ``s_wait_event`` instruction, with the bit 0 ("don't wait for
``export_ready``") of the immediate operand set to 0. On GFX11 specifically, AMD
passes 0 as the whole immediate operand.
The "export ready" wait can be done multiple times safely.
GFX9–10.3: Resolving intrawave collisions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On GFX9–10.3, it's possible for overlapping fragment shader invocations to be
placed not only in different waves, but also in the same wave, with the shader
code making sure that the ordered section is executed for overlapping
invocations in order.
This functionality is optional — it can be activated by enabling loading of the
``INTRAWAVE_COLLISION`` SGPR argument in ``SPI_SHADER_PGM_RSRC2_PS`` and
``PA_SC_SHADER_CONTROL``.
The lower 8 or 16 (depending on the wave size) bits of ``INTRAWAVE_COLLISION``
contain the mask of whether each quad in the wave starts a new layer of
overlapping invocations, and thus the ordered section code for them needs to be
executed after running it for all lanes with indices preceding that quad index
multiplied by 4. The rest of the bits in the argument need to be ignored — AMD
explicitly masks them out in shader code (although this is not necessary if the
shader uses "find first 1" to obtain the start of the next set of overlapping
quads or expands this quad mask into a lane mask).
For example, if the intrawave collision mask is 0b0000001110000100, or
``(1 << 2) | (1 << 7) | (1 << 8) | (1 << 9)``, the code of the ordered section
needs to be executed first only for quads 1:0 (lanes 7:0), then only for quads
6:2 (lanes 27:8), then for quad 7 (lanes 31:28), then for quad 8 (lanes 35:32),
and then for the remaining quads 15:9 (lanes 63:36).
This effectively causes the ordered section to be executed as smaller
"sub-subgroups" within the original subgroup.
However, this is not always compatible with the execution model of SPIR-V or
GLSL fragment shaders, so enabling intrawave collisions and wrapping a part of
the shader in a loop may be unsafe in some cases. One particular example is when
the shader uses subgroup operations influenced by lanes outside the current
quad. In this case, the code outside and inside the ordered section may be
executed with different sets of active invocations, affecting the results of
subgroup operations. But in SPIR-V and GLSL, fragment shader interlock is not
supposed to modify the set of active invocations in any way. So the intrawave
collision loop may break the results of subgroup operations in unpredictable
ways, even outside the driver's compiler infrastructure. Even if the driver
splits the subgroup exactly at ``OpBeginInvocationInterlockEXT`` and makes the
lane subsets rejoin exactly at ``OpEndInvocationInterlockEXT``, the application
and the compilers that created the source shader are still not aware of that
happening — the input SPIR-V or GLSL shader might have already gone through
various optimizations, such as common subexpression elimination which might
have considered a subgroup operation before ``OpBeginInvocationInterlockEXT``
and one after it equivalent.
The idea behind reporting intrawave collisions to shaders is to reduce the
impact on the parallelism of the part of the shader that doesn't depend on the
ordering, to avoid wasting lanes in the wave and to allow the code outside the
ordered section in different invocations to run in parallel lanes as usual. This
may be especially helpful if the ordered section is small compared to the rest
of the shader — for instance, a custom blending equation in the end of the usual
fragment shader for a surface in the world.
However, whether handling intrawave collisions is preferred is not a question
with one universal answer. Intrawave collisions are pretty uncommon without
multisampling, or when using sample interlock with multisampling, although
they're highly frequent with pixel interlock with multisampling, when adjacent
primitives cover the same pixels along the shared edge (though that's an
extremely expensive situation in general). But resolving intrawave collisions
adds some overhead costs to the shader. If intrawave overlap is unlikely to
happen often, or even more importantly, if the majority of the shader is inside
the ordered section, handling it in the shader may cause more harm than good.
GFX11 removes this concept entirely, instead overlapping invocations are always
placed in different waves.
GFX9–10.3: Exiting the ordered section in the wave
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To exit the ordered section and let overlapping waves resume execution and enter
their ordered sections, the wave needs to send the ``ORDERED_PS_DONE`` message
(7) using ``s_sendmsg``.
If the wave has enabled POPS by setting the packer hardware register, it *must
not* execute ``s_endpgm`` without having sent ``ORDERED_PS_DONE`` once, so the
message must be sent on all execution paths after the packer register setup.
However, if the wave exits before having configured the packer register, sending
the message is not required, though it's still fine to send it regardless of
that.
Note that if the shader has multiple ``OpEndInvocationInterlockEXT``
instructions executed in the same wave (depending on a divergent condition, for
example), it must still be ensured that ``ORDERED_PS_DONE`` is sent by the wave
only once, and especially not before any awaiting of overlapped waves.
Before the message is sent, all counters for memory accesses that need to be
primitive-ordered, both writes and (in case something after the ordered section
depends on the per-pixel data, for instance, the tail blending fallback in
order-independent transparency) reads, must be awaited. Those may include
``vm``, ``vs``, and in some cases ``lgkm`` (though normally primitive-ordered
memory accesses will be done through VMEM with divergent addresses, not SMEM, as
there's no synchronization between fragments at different pixel coordinates, but
it's still technically possible for a shader, even though pointless and
nonoptimal, to explicitly perform them in a waterfall loop, for instance, and
that must work correctly too). Without that, a race condition will occur when
the newly resumed waves start accessing the memory locations to which there
still are outstanding accesses in the current wave.
Another option for exiting is the ``s_endpgm_ordered_ps_done`` instruction,
which combines waiting for all the counters, sending the ``ORDERED_PS_DONE``
message, and ending the program. Generally, however, it's desirable to resume
overlapping waves as early as possible, including before the export, as it may
stall the wave for some time too.
GFX11: Exiting the ordered section in the wave
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The overlapping waves are resumed when the wave performs the last export (with
the ``done`` flag).
The same requirements for awaiting the memory access counters as on GFX9–10.3
still apply.
Memory access requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^
The compiler needs to ensure that entering the ordered section implements
acquire semantics, and exiting it implements release semantics, in the fragment
interlock memory scope for ``UniformMemory`` and ``ImageMemory`` SPIR-V storage
classes.
A fragment interlock memory scope instance includes overlapping fragment shader
invocations executed by commands inside a single subpass. It may be considered a
subset of a queue family memory scope instance from the perspective of memory
barriers.
Fragment shader interlock doesn't perform implicit memory availability or
visibility operations. Shaders must do them by themselves for accesses requiring
primitive ordering, such as via ``coherent`` (``queuefamilycoherent``) in GLSL
or ``MakeAvailable`` and ``MakeVisible`` in at least the ``QueueFamily`` scope
in SPIR-V.
On AMD hardware, this means that the accessed memory locations must be made
available or visible between waves that may be executed on any compute unit — so
accesses must go directly to the global L2 cache, bypassing L0$ via the GLC flag
and L1$ via DLC.
However, it should be noted that memory accesses in the ordered section may be
expected by the application to be done in primitive order even if they don't
have the GLC and DLC flags. Coherent access not only bypasses, but also
invalidates the lower-level caches for the accessed memory locations. Thus,
considering that normally per-pixel data is accessed exclusively by the
invocation executing the ordered section, it's not necessary to make all reads
or writes in the ordered section for one memory location to be GLC/DLC — just
the first read and the last write: it doesn't matter if per-pixel data is cached
in L0/L1 in the middle of a dependency chain in the ordered section, as long as
it's invalidated in them in the beginning and flushed to L2 in the end.
Therefore, optimizations in the compiler must not simply assume that only
coherent accesses need primitive ordering — and moreover, the compiler must also
take into account that the same data may be accessed through different bindings.
Export requirements
^^^^^^^^^^^^^^^^^^^
With POPS, on all hardware generations, the shader must have at least one
export, though it can be a null or an ``off, off, off, off`` one.
Also, even if the shader doesn't need to export any real data, the export
skipping that was added in GFX10 must not be used, and some space must be
allocated in the export buffer, such as by setting ``SPI_SHADER_COL_FORMAT`` for
some color output to ``SPI_SHADER_32_R``.
Without this, the shader will be executed without the needed synchronization on
GFX10, and will hang on GFX11.
Drawing context setup
---------------------
Configuring POPS
^^^^^^^^^^^^^^^^
Most of the configuration is performed via the ``DB_SHADER_CONTROL`` register.
To enable POPS for the draw,
``DB_SHADER_CONTROL.PRIMITIVE_ORDERED_PIXEL_SHADER`` should be set to 1.
On GFX9–10.3, ``DB_SHADER_CONTROL.POPS_OVERLAP_NUM_SAMPLES`` controls which
fragment shader invocations are considered overlapping:
* For pixel interlock, it must be set to 0 (1 sample).
* If sample interlock is sufficient (only synchronizing between invocations that
have any common sample mask bits), it may be set to
``PA_SC_AA_CONFIG.MSAA_EXPOSED_SAMPLES`` — the number of sample coverage mask
bits passed to the shader which is expected to use the sample mask to
determine whether it's allowed to access the data for each of the samples. As
of April 2023, PAL for some reason doesn't use non-1x
``POPS_OVERLAP_NUM_SAMPLES`` at all, even when using Direct3D Rasterizer
Ordered Views or ``GL_INTEL_fragment_shader_ordering`` with sample shading
(those APIs tie the interlock granularity to the shading frequency — Vulkan
and OpenGL fragment shader interlock, however, allows specifying the interlock
granularity independently of it, making it possible both to ask for finer
synchronization guarantees and to require stronger ones than Direct3D ROVs can
provide). However, with MSAA, on AMD hardware, pixel interlock generally
performs *massively*, sometimes prohibitively, slower than sample interlock,
because it causes fragment shader invocations along the common edge of
adjacent primitives to be ordered as they cover the same pixels (even though
they don't cover any common samples). So it's highly desirable for the driver
to provide sample interlock, and to set ``POPS_OVERLAP_NUM_SAMPLES``
accordingly, if the shader declares that it's enough for it via the execution
mode.
On GFX11, when POPS is enabled, ``DB_SHADER_CONTROL.OVERRIDE_INTRINSIC_RATE`` is
used in place of ``DB_SHADER_CONTROL.POPS_OVERLAP_NUM_SAMPLES`` from the earlier
architecture generations (and has a different bit offset in the register), and
``DB_SHADER_CONTROL.OVERRIDE_INTRINSIC_RATE_ENABLE`` must be set to 1. The GFX11
blending performance workaround overriding the intrinsic rate must not be
applied if POPS is used in the draw — the intrinsic rate override must be used
solely to control the interlock granularity in this case.
No explicit flushes/synchronization are needed when changing the pipeline state
variables that may be involved in POPS, such as the rasterization sample count.
POPS automatically keeps synchronizing invocations even between draws with
different sample counts (invocations with common coverage mask bits are
considered overlapping by the hardware, regardless of what those samples
actually are — only the indices are important).
Also, on GFX11, POPS uses ``DB_Z_INFO.NUM_SAMPLES`` to determine the coverage
sample count, and it must be equal to ``PA_SC_AA_CONFIG.MSAA_EXPOSED_SAMPLES``
even if there's no depth/stencil target.
Hardware bug workarounds
^^^^^^^^^^^^^^^^^^^^^^^^
Early revisions of GFX9 — ``CHIP_VEGA10`` and ``CHIP_RAVEN`` — contain a
hardware bug that may result in a hang, and need a workaround to be enabled.
Specifically, if POPS is used with 8 or more rasterization samples, or with 8 or
more depth/stencil target samples, ``DB_DFSM_CONTROL.POPS_DRAIN_PS_ON_OVERLAP``
must be set to 1 for draws that satisfy this condition. In PAL, this is the
``waMiscPopsMissedOverlap`` workaround. It results in slightly lower performance
in those cases, increasing the frame time by around 1.5 to 2 times in
`nvpro-samples/vk_order_independent_transparency <https://github.com/nvpro-samples/vk_order_independent_transparency>`_
on the RX Vega 10, but it's required in a pretty rare case (8x+ MSAA) and is
mandatory to ensure stability.
Also, even though ``DB_DFSM_CONTROL.POPS_DRAIN_PS_ON_OVERLAP`` is not required
on chips other than the ``CHIP_VEGA10`` and ``CHIP_RAVEN`` GFX9 revisions, if
it's enabled for some reason on GFX10.1 (``CHIP_NAVI10``, ``CHIP_NAVI12``,
``CHIP_NAVI14``), and the draw uses POPS,
``DB_RENDER_OVERRIDE2.PARTIAL_SQUAD_LAUNCH_CONTROL`` must be set to
``PSLC_ON_HANG_ONLY`` to avoid a hang (see ``waStalledPopsMode`` in PAL).
Out-of-order rasterization interaction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is a largely unresearched topic currently. However, considering that POPS
is primarily the functionality of the Depth Block, similarity to the behavior of
out-of-order rasterization in depth/stencil testing may possibly be expected.
If the shader specifies an ordered interlock execution mode, out-of-order
rasterization likely must not be enabled implicitly.
As of April 2023, PAL doesn't have any rules specifically for POPS in the logic
determining whether out-of-order rasterization can be enabled automatically.
Some of the POPS usage cases may possibly be covered by the rule that always
disables out-of-order rasterization if the shader writes to Unordered Access
Views (storage resources), though fragment shader interlock can be used for
read-only purposes too (for ordering between draws that only read per-pixel data
and draws that may write it), so that may be an oversight.
Explicitly enabled relaxed rasterization order modifies the concept of
rasterization order itself in Vulkan, so from the point of view of the
specification of fragment shader interlock, relaxed rasterization order should
still be applicable regardless of whether the shader requests ordered interlock.
PAL also doesn't make any POPS-specific exceptions here as of April 2023.
Variable-rate shading interaction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On GFX10.3, enabling ``DB_SHADER_CONTROL.PRIMITIVE_ORDERED_PIXEL_SHADER`` forces
the shading rate to be 1x1, thus the
``fragmentShadingRateWithFragmentShaderInterlock`` Vulkan device property must
be false.
On GFX11, by default, POPS itself can work with non-1x1 shading rates, and the
``fragmentShadingRateWithFragmentShaderInterlock`` property must be true.
However, if ``PA_SC_VRS_SURFACE_CNTL_1.FORCE_SC_VRS_RATE_FINE_POPS`` is set,
enabling POPS will force 1x1 shading rate.
The widest interlock granularity available on GFX11 — with the lowest possible
Depth Block intrinsic rate, 1x — is per-fine-pixel, however. There's no
synchronization between coarse fragment shader invocations if they don't cover
common fine pixels, so the ``fragmentShaderShadingRateInterlock`` Vulkan device
feature is not available.
Additional configuration
^^^^^^^^^^^^^^^^^^^^^^^^
These are some largely unresearched options found in the register declarations.
PAL doesn't use them, so it's unknown if they make any significant difference.
No effect was found in `nvpro-samples/vk_order_independent_transparency <https://github.com/nvpro-samples/vk_order_independent_transparency>`_
during testing on GFX9 ``CHIP_RAVEN`` and GFX11 ``CHIP_NAVI31``.
* ``DB_SHADER_CONTROL.EXEC_IF_OVERLAPPED`` on GFX9–10.3.
* ``PA_SC_BINNER_CNTL_0.BIN_MAPPING_MODE = BIN_MAP_MODE_POPS`` on GFX10-11.5.
This field is reserved on GFX12+ and should be set to 0.
local/recipes/dev/mesa-clc/source/docs/drivers/amd/live-var-analysis.rst
+164
View File
@@ -0,0 +1,164 @@
:orphan:
.. _aco-live-var-analysis:
Description of live variable analysis in ACO
============================================
Operand flags
-------------
Operands can have several different flags which are set by live variable analysis:
* ``isKill``: this operand is not live after the instruction
* ``isFirstKill``: this is the first instance of a temporary in the instruction with ``isKill=true``
* ``isLateKill``: this operand cannot use the same registers as any definition
* ``isClobbered``: this operand will use some of the same registers as a definition
* ``isCopyKill``: this operand must use a different register than earlier instances of the same temporary in the
instruction's operand list
Note that:
* ``isFirstKill=true`` requires that the operand is also ``isKill=true``.
* If ``isKill=true``, then ``isLateKill=true`` requires that the operand is also ``isFirstKill=true`` or
``isCopyKill=true``.
* ``isCopyKill=true`` is incompatible with ``isFirstKill=true`` in the same operand.
* ``isLateKill=true`` cannot be used with ``isClobbered=true`` for the same temporary in an instruction.
* If ``isCopyKill=true``, then the operand will also have ``isKill=true``, even if the temporary is live after the
instruction.
Operands and definitions can be "tied", indicated by ``get_tied_defs()``, meaning that the must use the same registers:
* Operands tied to definitions have ``isClobbered=true``.
* If a clobbered operand has ``isKill=false``, it will be moved to a different register.
* If two operands of the same temporary are tied to different definitions of the same instruction, the second of those
operands will have ``isCopyKill=true``.
There also exists the ``isVectorAligned`` flag. This can be used to define a vector of operands, starting with
``isVectorAligned=true`` and ending with ``isVectorAligned=false``, which must be placed in consecutive registers.
To prevent issues with register allocation, an operand being part of a vector means:
* Unless a vector is tied to a definition, it will also have ``isLateKill=true``, so that a partially killed vectors
are not required to share the same space with definitions.
* If two operands of the same temporary are both part of vectors in the same instruction, the second of those operands
will have ``isCopyKill=true``.
Register demand calculation
---------------------------
``live_in``
temporaries live before the instruction
``live_out``
temporaries live after the instruction
``live_through``
temporaries live both before and after the instruction
``live_definitions``
temporaries defined and used later (definitions where ``isKill=false``)
``dead_definitions``
temporaries defined and not used later (definitions where ``isKill=true``)
``early_kill_operands``
temporaries killed which are not marked late kill (operands where ``isFirstKill=true && isLateKill=false``)
``late_kill_operands``
temporaries killed which are marked late kill (operands where ``isFirstKill=true && isLateKill=true``)
``first_kill_operands``
temporaries killed by the instruction (operands where ``isFirstKill=true``)
``early_kill_operands + late_kill_operands``
``copied_operands``
operands which are either clobbered but not killed, or copy-kill (operands where
``isCopyKill=true || (isClobbered=true && isKill=false)``)
``early_kill_copies``
``copied_operands`` which are not marked late kill (operands where
``(isCopyKill=true && isLateKill=false) || (isClobbered=true && isKill=false)``)
``late_kill_copies``
``copied_operands`` which are marked late kill (operands where ``(isCopyKill=true && isLateKill=true)``)
``live_out``
``live_through + live_definitions``
``live_in - first_kill_operands + live_definitions``
``live_in``
``live_out - live_definitions + first_kill_operands``
``live_through + first_kill_operands``
``live_through``
``live_out - live_definitions``
``live_in - first_kill_operands``
Breakdown of register demand stages using ``live_in``:
* stage 0: before instruction: ``live_in``
* stage 1: setup operands: ``live_in + early_kill_copies + late_kill_copies``
* stage 2: during instruction: ``live_in - early_kill_operands + late_kill_copies``
* stage 3: write definitions: ``live_in - early_kill_operands + late_kill_copies + live_definitions + dead_definitions``
* stage 4: after instruction: ``live_in - early_kill_operands - late_kill_operands + live_definitions``
Breakdown of register demand stages using ``live_through``:
* stage 0: before instruction: ``live_through + late_kill_operands + early_kill_operands``
* stage 1: setup operands: ``live_through + late_kill_operands + early_kill_operands + early_kill_copies + late_kill_copies``
* stage 2: during instruction: ``live_through + late_kill_operands + late_kill_copies``
* stage 3: write definitions: ``live_through + late_kill_operands + late_kill_copies + live_definitions + dead_definitions``
* stage 4: after instruction: ``live_through + live_definitions``
Breakdown of register demand stages using ``live_out``:
* stage 0: before instruction: ``live_out - live_definitions + late_kill_operands + early_kill_operands``
* stage 1: setup operands: ``live_out - live_definitions + late_kill_operands + early_kill_operands + early_kill_copies + late_kill_copies``
* stage 2: during instruction: ``live_out - live_definitions + late_kill_operands + late_kill_copies``
* stage 3: write definitions: ``live_out + dead_definitions + late_kill_operands + late_kill_copies``
* stage 4: after instruction: ``live_out``
If instruction B immediately follows instruction A, then stage 0 of instruction B equals stage 4 of instruction A.
``Instruction::register_demand`` is ``max(stage1, stage3)``, which is equal to the maximum of all stages.
There are a few helper functions for examining how an instruction changes register demand:
``get_live_changes()``
This is the register demand change from killed temporaries and live definitions.
``live_definitions - first_kill_operands``
equal to ``live_out - live_in``
``get_temp_registers()``
This is the temporary increase in register demand needed for copy-kill operands, late-kill operands, clobbered
operands, and dead definitions.
``max(early_kill_operands + late_kill_operands + early_kill_copies + late_kill_copies - live_definitions, late_kill_operands + late_kill_copies + dead_definitions)``
equal to ``register_demand - live_out``
``get_temp_reg_changes()``
Since ``register_demand`` is ``max(stage1, stage3)``, this can be used to know what's the effect of marking an
operand killed will be.
``live_definitions + dead_definitions - early_kill_operands - early_kill_copies``
equal to ``stage3 - stage1``
They can be used as follows:
* ``register_demand(a) = live_in(a) + live_changes(a) + temp_registers(a)``
* ``register_demand(a) = live_out(a) + temp_registers(a)``
Assuming ``stage4(a)==stage0(b)``:
* ``register_demand(a) = register_demand(b) - temp_registers(b) - live_changes(b) + temp_registers(a)``
* ``register_demand(b) = register_demand(a) - temp_registers(a) + live_changes(b) + temp_registers(b)``
(note that ``max(a + b, a + c) - max(b, c) = a`` and ``a + max(b, c) = max(a + b, a + c)``)
local/recipes/dev/mesa-clc/source/docs/drivers/anv.rst
+401
View File
@@ -0,0 +1,401 @@
ANV
===
Experimental features
---------------------
.. _`Bindless model`:
Binding Model
-------------
Here is the ANV bindless binding model that was implemented for the
descriptor indexing feature of Vulkan 1.2 :
.. graphviz::
digraph G {
fontcolor="black";
compound=true;
subgraph cluster_1 {
label = "Binding Table (HW)";
bgcolor="cornflowerblue";
node [ style=filled,shape="record",fillcolor="white",
label="RT0" ] n0;
node [ label="RT1" ] n1;
node [ label="dynbuf0"] n2;
node [ label="set0" ] n3;
node [ label="set1" ] n4;
node [ label="set2" ] n5;
n0 -> n1 -> n2 -> n3 -> n4 -> n5 [style=invis];
}
subgraph cluster_2 {
label = "Descriptor Set 0";
bgcolor="burlywood3";
fixedsize = true;
node [ style=filled,shape="record",fillcolor="white", fixedsize = true, width=4,
label="binding 0 - STORAGE_IMAGE\n anv_storage_image_descriptor" ] n8;
node [ label="binding 1 - COMBINED_IMAGE_SAMPLER\n anv_sampled_image_descriptor" ] n9;
node [ label="binding 2 - UNIFORM_BUFFER\n anv_address_range_descriptor" ] n10;
node [ label="binding 3 - UNIFORM_TEXEL_BUFFER\n anv_storage_image_descriptor" ] n11;
n8 -> n9 -> n10 -> n11 [style=invis];
}
subgraph cluster_5 {
label = "Vulkan Objects"
fontcolor="black";
bgcolor="darkolivegreen4";
subgraph cluster_6 {
label = "VkImageView";
bgcolor=darkolivegreen3;
node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
label="surface_state" ] n12;
}
subgraph cluster_7 {
label = "VkSampler";
bgcolor=darkolivegreen3;
node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
label="sample_state" ] n13;
}
subgraph cluster_8 {
label = "VkImageView";
bgcolor="darkolivegreen3";
node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
label="surface_state" ] n14;
}
subgraph cluster_9 {
label = "VkBuffer";
bgcolor=darkolivegreen3;
node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
label="address" ] n15;
}
subgraph cluster_10 {
label = "VkBufferView";
bgcolor=darkolivegreen3;
node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
label="surface_state" ] n16;
}
n12 -> n13 -> n14 -> n15 -> n16 [style=invis];
}
subgraph cluster_11 {
subgraph cluster_12 {
label = "CommandBuffer state stream";
bgcolor="gold3";
node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
label="surface_state" ] n17;
node [ label="surface_state" ] n18;
node [ label="surface_state" ] n19;
n17 -> n18 -> n19 [style=invis];
}
}
n3 -> n8 [lhead=cluster_2];
n8 -> n12;
n9 -> n13;
n9 -> n14;
n10 -> n15;
n11 -> n16;
n0 -> n17;
n1 -> n18;
n2 -> n19;
}
The HW binding table is generated when the draw or dispatch commands
are emitted. Here are the types of entries one can find in the binding
table :
- The currently bound descriptor sets, one entry per descriptor set
(our limit is 8).
- For dynamic buffers, one entry per dynamic buffer.
- For draw commands, render target entries if needed.
The entries of the HW binding table for descriptor sets are
RENDER_SURFACE_STATE similar to what you would have for a normal
uniform buffer. The shader will emit reads this buffer first to get
the information it needs to access a surface/sampler/etc... and then
emits the appropriate message using the information gathered from the
descriptor set buffer.
Each binding type entry gets an associated structure in memory
(``anv_storage_image_descriptor``, ``anv_sampled_image_descriptor``,
``anv_address_range_descriptor``, ``anv_storage_image_descriptor``).
This is the information read by the shader.
.. _`Binding tables`:
Binding Tables
--------------
Binding tables are arrays of 32bit offset entries referencing surface
states. This is how shaders can refer to binding table entry to read
or write a surface. For example fragment shaders will often refer to
entry 0 as the first render target.
The way binding tables are managed is fairly awkward.
Each shader stage must have its binding table programmed through
a corresponding instruction
``3DSTATE_BINDING_TABLE_POINTERS_*`` (each stage has its own).
.. graphviz::
digraph structs {
node [shape=record];
struct3 [label="{ binding tables&#92;n area | { <bt4> BT4 | <bt3> BT3 | ... | <bt0> BT0 } }|{ surface state&#92;n area |{<ss0> ss0|<ss1> ss1|<ss2> ss2|...}}"];
struct3:bt0 -> struct3:ss0;
struct3:bt0 -> struct3:ss1;
}
The value programmed in the ``3DSTATE_BINDING_TABLE_POINTERS_*``
instructions is not a 64bit pointer but an offset from the address
programmed in ``STATE_BASE_ADDRESS::Surface State Base Address`` or
``3DSTATE_BINDING_TABLE_POOL_ALLOC::Binding Table Pool Base Address``
(available on Gfx11+). The offset value in
``3DSTATE_BINDING_TABLE_POINTERS_*`` is also limited to a few bits
(not a full 32bit value), meaning that as we use more and more binding
tables we need to reposition ``STATE_BASE_ADDRESS::Surface State Base
Address`` to make space for new binding table arrays.
To make things even more awkward, the binding table entries are also
relative to ``STATE_BASE_ADDRESS::Surface State Base Address`` so as
we change ``STATE_BASE_ADDRESS::Surface State Base Address`` we need
add that offsets to the binding table entries.
The way with deal with this is that we allocate 4Gb of address space
(since the binding table entries can address 4Gb of surface state
elements). We reserve the first gigabyte exclusively to binding
tables, so that anywhere we position our binding table in that first
gigabyte, it can always refer to the surface states in the next 3Gb.
.. _`Descriptor Set Memory Layout`:
Descriptor Set Memory Layout
----------------------------
Here is a representation of how the descriptor set bindings, with each
elements in each binding is mapped to a the descriptor set memory :
.. graphviz::
digraph structs {
node [shape=record];
rankdir=LR;
struct1 [label="Descriptor Set | \
<b0> binding 0\n STORAGE_IMAGE \n (array_length=3) | \
<b1> binding 1\n COMBINED_IMAGE_SAMPLER \n (array_length=2) | \
<b2> binding 2\n UNIFORM_BUFFER \n (array_length=1) | \
<b3> binding 3\n UNIFORM_TEXEL_BUFFER \n (array_length=1)"];
struct2 [label="Descriptor Set Memory | \
<b0e0> anv_storage_image_descriptor|\
<b0e1> anv_storage_image_descriptor|\
<b0e2> anv_storage_image_descriptor|\
<b1e0> anv_sampled_image_descriptor|\
<b1e1> anv_sampled_image_descriptor|\
<b2e0> anv_address_range_descriptor|\
<b3e0> anv_storage_image_descriptor"];
struct1:b0 -> struct2:b0e0;
struct1:b0 -> struct2:b0e1;
struct1:b0 -> struct2:b0e2;
struct1:b1 -> struct2:b1e0;
struct1:b1 -> struct2:b1e1;
struct1:b2 -> struct2:b2e0;
struct1:b3 -> struct2:b3e0;
}
Each Binding in the descriptor set is allocated an array of
``anv_*_descriptor`` data structure. The type of ``anv_*_descriptor``
used for a binding is selected based on the ``VkDescriptorType`` of
the bindings.
The value of ``anv_descriptor_set_binding_layout::descriptor_offset``
is a byte offset from the descriptor set memory to the associated
binding. ``anv_descriptor_set_binding_layout::array_size`` is the
number of ``anv_*_descriptor`` elements in the descriptor set memory
from that offset for the binding.
Pipeline state emission
-----------------------
Vulkan initially started by baking as much state as possible in
pipelines. But extension after extension, more and more state has
become potentially dynamic.
ANV tries to limit the amount of time an instruction has to be packed
to reprogram part of the 3D pipeline state. The packing is happening
in 2 places :
- ``genX_pipeline.c`` where the non dynamic state is emitted in the
pipeline batch. Chunks of the batches are copied into the command
buffer as a result of calling ``vkCmdBindPipeline()``, depending on
what changes from the previously bound graphics pipeline
- ``genX_gfx_state.c`` where the dynamic state is added to already
packed instructions from ``genX_pipeline.c``
The rule to know where to emit an instruction programming the 3D
pipeline is as follow :
- If any field of the instruction can be made dynamic, it should be
emitted in ``genX_gfx_state.c``
- Otherwise, the instruction can be emitted in ``genX_pipeline.c``
When a piece of state programming is dynamic, it should have a
corresponding field in ``anv_gfx_dynamic_state`` and the
``genX(cmd_buffer_flush_gfx_runtime_state)`` function should be
updated to ensure we minimize the amount of time an instruction should
be emitted. Each instruction should have a associated
``ANV_GFX_STATE_*`` mask so that the dynamic emission code can tell
when to re-emit an instruction.
Generated indirect draws optimization
-------------------------------------
Indirect draws have traditionally been implemented on Intel HW by
loading the indirect parameters from memory into HW registers using
the command streamer's ``MI_LOAD_REGISTER_MEM`` instruction before
dispatching a draw call to the 3D pipeline.
On recent products, it was found that the command streamer is showing
as performance bottleneck, because it cannot dispatch draw calls fast
enough to keep the 3D pipeline busy.
The solution to this problem is to change the way we deal with
indirect draws. Instead of loading HW registers with values using the
command streamer, we generate entire set of ``3DPRIMITIVE``
instructions using a shader. The generated instructions contain the
entire draw call parameters. This way the command streamer executes
only ``3DPRIMITIVE`` instructions and doesn't do any data loading from
memory or touch HW registers, feeding the 3D pipeline as fast as it
can.
In ANV this implemented in 2 different ways :
By generating instructions directly into the command stream using a
side batch buffer. When ANV encounters the first indirect draws, it
generates a jump into the side batch, the side batch contains a draw
call using a generation shader for each indirect draw. We keep adding
on more generation draws into the batch until we have to stop due to
command buffer end, secondary command buffer calls or a barrier
containing the access flag ``VK_ACCESS_INDIRECT_COMMAND_READ_BIT``.
The side batch buffer jump back right after the instruction where it
was called. Here is a high level diagram showing how the generation
batch buffer writes in the main command buffer :
.. graphviz::
digraph commands_mode {
rankdir = "LR"
"main-command-buffer" [
label = "main command buffer|...|draw indirect0 start|<f0>jump to\ngeneration batch|<f1>|<f2>empty instruction0|<f3>empty instruction1|...|draw indirect0 end|...|draw indirect1 start|<f4>empty instruction0|<f5>empty instruction1|...|<f6>draw indirect1 end|..."
shape = "record"
];
"generation-command-buffer" [
label = "generation command buffer|<f0>|<f1>write draw indirect0|<f2>write draw indirect1|...|<f3>exit jump"
shape = "record"
];
"main-command-buffer":f0 -> "generation-command-buffer":f0;
"generation-command-buffer":f1 -> "main-command-buffer":f2 [color="#0000ff"];
"generation-command-buffer":f1 -> "main-command-buffer":f3 [color="#0000ff"];
"generation-command-buffer":f2 -> "main-command-buffer":f4 [color="#0000ff"];
"generation-command-buffer":f2 -> "main-command-buffer":f5 [color="#0000ff"];
"generation-command-buffer":f3 -> "main-command-buffer":f1;
}
By generating instructions into a ring buffer of commands, when the
draw count number is high. This solution allows smaller batches to be
emitted. Here is a high level diagram showing how things are
executed :
.. graphviz::
digraph ring_mode {
rankdir=LR;
"main-command-buffer" [
label = "main command buffer|...| draw indirect |<f1>generation shader|<f2> jump to ring|<f3> increment\ndraw_base|<f4>..."
shape = "record"
];
"ring-buffer" [
label = "ring buffer|<f0>generated draw0|<f1>generated draw1|<f2>generated draw2|...|<f3>exit jump"
shape = "record"
];
"main-command-buffer":f2 -> "ring-buffer":f0;
"ring-buffer":f3 -> "main-command-buffer":f3;
"ring-buffer":f3 -> "main-command-buffer":f4;
"main-command-buffer":f3 -> "main-command-buffer":f1;
"main-command-buffer":f1 -> "ring-buffer":f1 [color="#0000ff"];
"main-command-buffer":f1 -> "ring-buffer":f2 [color="#0000ff"];
}
Runtime dependencies
--------------------
Starting with Intel 12th generation/Alder Lake-P and Intel Arc Alchemist, the Intel 3D driver stack requires GuC firmware for proper operation. You have two options to install the firmware:
- Distro package: Install the pre-packaged firmware included in your Linux distribution's repositories.
- Manual download: You can download the firmware from the official repository: https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/i915. Place the downloaded files in the /lib/firmware/i915 directory.
Important: For optimal performance, we recommend updating the GuC firmware to version 70.6.3 or later.
Debugging tips
--------------
When running into rendering/hang issues here are a few things that can
be experimented with to try to narrow down the issue :
- Run with ``INTEL_DEBUG=stall`` : stall execution, flush and
invalidate all caches between draw/dispatch/trace operations,
helpful to detect synchronization issues between draw/dispatch/trace
operations
- Run with ``INTEL_DEBUG=sync`` : wait for completion of previous
command buffers before submitting new ones, helpful to detect
synchronization between command buffers
- Run with ``INTEL_DEBUG=noccs`` : disable compression, helpful to
detect compressed data handling issues in the driver
- Run with ``ANV_QUEUE_OVERRIDE=c=0,b=0`` : disable the async compute
queue and transfer queue, helpful to identify synchronization issues
between queues
- Run with ``INTEL_DEBUG=noccs-modifier`` : disable compressed
modifiers, helpful to identify compression data handling issues
between applications (application and compositor)
- Run with ``INTEL_DEBUG=no-resource-barrier`` : disable use of the
new RESOURCE_BARRIER instruction on Xe2+, helpful to identify
synchronization issues associated to this instruction
A combinaison of those can also be tried if the issue has multiple
causes, for example : ``INTEL_DEBUG=stall,sync``
local/recipes/dev/mesa-clc/source/docs/drivers/asahi.rst
+427
View File
@@ -0,0 +1,427 @@
Asahi
=====
The Asahi driver aims to provide an OpenGL implementation for the Apple M1.
Wrap (macOS only)
-----------------
Mesa includes a library that wraps the key IOKit entrypoints used in the macOS
UABI for AGX. The wrapped routines print information about the kernel calls made
and dump work submitted to the GPU using agxdecode. This facilitates
reverse-engineering the hardware, as glue to get at the "interesting" GPU
memory.
The library is only built if ``-Dtools=asahi`` is passed. It builds a single
``wrap.dylib`` file, which should be inserted into a process with the
``DYLD_INSERT_LIBRARIES`` environment variable.
For example, to trace an app ``./app``, run:
DYLD_INSERT_LIBRARIES=~/mesa/build/src/asahi/lib/libwrap.dylib ./app
Hardware varyings
-----------------
At an API level, vertex shader outputs need to be interpolated to become
fragment shader inputs. This process is logically pipelined in AGX, with a value
traveling from a vertex shader to remapping hardware to coefficient register
setup to the fragment shader to the iterator hardware. Each stage is described
below.
Vertex shader
`````````````
A vertex shader (running on the :term:`Unified Shader Cores`) outputs varyings with the
``st_var`` instruction. ``st_var`` takes a *vertex output index* and a 32-bit
value. The maximum number of *vertex outputs* is specified as the "output count"
of the shader in the "VDM State Vertex Outputs" structure. The value may be interpreted
consist of a single 32-bit value or an aligned 16-bit register pair, depending
on whether interpolation should happen at 32-bit or 16-bit. Vertex outputs are
indexed starting from 0, with the *vertex position* always coming first, the
32-bit user varyings coming next with perspective, flat, and linear interpolated
varyings grouped in that order, then 16-bit user varyings with the same groupings,
and finally *point size*, *layer/viewport*, and *clip distances* at the end if present. Note that
*clip distances* are not accessible from the fragment shader; if the fragment
shader needs to read the interpolated clip distance, the vertex shader must
*also* write the clip distance values to a user varying for the fragment shader
to interpolate. Also note there is no clip plane enable mask anywhere; that must
lowered for APIs that require this (OpenGL but not Vulkan).
.. list-table:: Ordering of vertex outputs with all outputs used
:widths: 25 75
:header-rows: 1
* - Size (words)
- Value
* - 4
- Vertex position
* - 1
- 32-bit smooth varying 0
* -
- ...
* - 1
- 32-bit smooth varying m
* - 1
- 32-bit flat varying 0
* -
- ...
* - 1
- 32-bit flat varying n
* - 1
- 32-bit linear varying 0
* -
- ...
* - 1
- 32-bit linear varying o
* - 1
- Packed pair of 16-bit smooth varyings 0
* -
- ...
* - 1
- Packed pair of 16-bit smooth varyings p
* - 1
- Packed pair of 16-bit flat varyings 0
* -
- ...
* - 1
- Packed pair of 16-bit flat varyings q
* - 1
- Packed pair of 16-bit linear varyings 0
* -
- ...
* - 1
- Packed pair of 16-bit linear varyings r
* - 1
- Point size
* - 1
- Layer/viewport
* - 1
- Clip distance for plane 0
* -
- ...
* - 1
- Clip distance for plane 16
Remapping
`````````
Vertex outputs are remapped to varying slots to be interpolated.
The output of remapping consists of the following items: the *W* fragment
coordinate, the *Z* fragment coordinate, user varyings in the vertex
output order. *Z* may be omitted, but *W* may not be. This remapping is
configured by the "Output select" word.
.. list-table:: Ordering of remapped slots
:widths: 25 75
:header-rows: 1
* - Index
- Value
* - 0
- Fragment coord W
* - 1
- Fragment coord Z
* - 2
- 32-bit varying 0
* -
- ...
* - 2 + m
- 32-bit varying m
* - 2 + m + 1
- Packed pair of 16-bit varyings 0
* -
- ...
* - 2 + m + n + 1
- Packed pair of 16-bit varyings n
Coefficient registers
`````````````````````
The fragment shader does not see the physical slots.
Instead, it references varyings through *coefficient registers*. A coefficient
register is a register allocated constant for all fragment shader invocations in
a given polygon. Physically, it contains the values output by the vertex shader
for each vertex of the polygon. Coefficient registers are preloaded with values
from varying slots. This preloading appears to occur in fixed function hardware,
a simplification from PowerVR which requires a specialized program for the
programmable data sequencer to do the preload.
The "Fragment Shader" structure points to coefficient register bindings,
preceded by a header. The header contains the number of 32-bit varying slots. As
the *W* slot is always present, this field is always nonzero. Slots whose index
is below this count are treated as 32-bit. The remaining slots are treated as
16-bits.
The header also contains the total number of coefficient registers bound.
Each binding that follows maps a (vector of) varying slots to a (consecutive)
coefficient registers. Some details about the varying (perspective
interpolation, flat shading, point sprites) are configured here.
Coefficient registers may be ordered the same as the internal varying slots.
However, this may be inconvenient for some APIs that require a separable shader
model. For these APIs, the flexibility to mix-and-match slots and coefficient
registers allows mixing shaders without shader variants. In that case, the
bindings should be generated outside of the compiler. For simple APIs where the
bindings are fixed and known at compile-time, the bindings could be generated
within the compiler.
Mathematically, the value of the coefficient register is a vector in
:math:`\mathbb{R}^3`. The X and Y components are the screen-space partial
derivatives of the varying with respect to X and Y. The Z component is the
interpolated value of the varying at the upper-left pixel in the 32x32 tile that
the pixel belongs to.
Fragment shader
```````````````
In the fragment shader, coefficient registers, identified by the prefix ``cf``
followed by a decimal index, act as opaque handles to varyings. For flat
shading, coefficient registers may be loaded into general registers with the
``ldcf`` instruction. For smooth shading, the coefficient register corresponding
to the desired varying is passed as an argument to the "iterate" instruction
``iter`` in order to "iterate" (interpolate) a varying. As perspective correct
interpolation also requires the W component of the fragment coordinate, the
coefficient register for W is passed as a second argument. As an example, if
there's a single varying to interpolate, an instruction like ``iter r0, cf1, cf0``
is used.
It is occassionally useful to manipulate the raw coefficient registers, for
example to implement interpolation modes not natively supported by the hardware.
``ldcf`` is used for this purpose.
Iterator
````````
To actually interpolate varyings, AGX provides fixed-function iteration hardware
to multiply the specified coefficient registers with the required barycentrics,
producing an interpolated value, hence the name "coefficient register". This
operation is purely mathematical and does not require any memory access, as
the required coefficients are preloaded before the shader begins execution.
That means the iterate instruction executes in constant time, does not signal
a data fence, and does not require the shader to wait on a data fence before
using the value.
Image layouts
-------------
AGX supports several image layouts, described here. To work with image layouts
in the drivers, use the ail library, located in ``src/asahi/layout``.
Strided linear
``````````````
The simplest layout is **strided linear**. Pixels are stored in raster-order in
memory with a software-controlled stride. Strided linear images are useful for
working with modifier-unaware window systems, however performance will suffer.
Strided linear images have numerous limitations:
- Strides must be a multiple of 16 bytes.
- Strides must be nonzero. For 1D images where the stride is logically
irrelevant, ail will internally select the minimal stride.
- Only 1D, 2D, and 2D Array images may be linear. In particular, no 3D or cubemaps.
- 2D images must not be mipmapped.
- Block-compressed formats and multisampled images are unsupported. Elements of
a strided linear image are simply pixels.
With these limitations, addressing into a strided linear image is as simple as
.. math::
\text{address} = (y \cdot \text{stride}) + (x \cdot \text{bytes per pixel})
In practice, this suffices for window system integration and little else.
GPU-tiled
`````````
The most common uncompressed layout is **GPU-tiled**. The image is divided into
power-of-two sized tiles. The tiles themselves are stored in raster-order.
Within each tile, elements (pixels/blocks) are stored in Morton (Z) order.
The tile size used depends on both the image size and the block size of the
image format. For large images, :math:`n \times n` or :math:`2n \times n` tiles
are used (:math:`n` power-of-two). :math:`n` is such that each page contains
exactly one tile. Only power-of-two block sizes are supported in hardware,
ensuring such a tile size always exists. The hardware uses 16 KiB pages, so tile
sizes are as follows:
.. list-table:: Tile sizes for large images
:widths: 50 50
:header-rows: 1
* - Bytes per block
- Tile size
* - 1
- 128 x 128
* - 2
- 128 x 64
* - 4
- 64 x 64
* - 8
- 64 x 32
* - 16
- 32 x 32
The dimensions of large images are rounded up to be multiples of the tile size.
In addition, non-power-of-two large images have extra padding tiles when
mipmapping is used, see below.
That rounding would waste a great deal of memory for small images. If
an image is smaller than this tile size, a smaller tile size is used to reduce
the memory footprint. For small images, the tile size is :math:`m \times m`
where
.. math::
m = 2^{\lceil \log_2( \min \{ \text{width}, \text{ height} \}) \rceil}
In other words, small images use the smallest square power-of-two tile such that
the image's minor axis fits in one tile.
For mipmapped images, tile sizes are determined independently for each level.
Typically, the first levels of an image are "large" and the remaining levels are
"small". This scheme reduces the memory footprint of mipmapping, compared to a
fixed tile size for the whole image. Each mip level are padded to fill at least
one cache line (128 bytes), ensure no cache line contains multiple mip levels.
There is a wrinkle: the dimensions of large mip levels in tiles are determined
by the dimensions of level 0. For power-of-two images, the two calculations are
equivalent. However, they differ subtly for non-power-of-two images. To
determine the number of tiles to allocate for level :math:`l`, the number of
tiles for level 0 should be right-shifted by :math:`2l`. That appears to divide
by :math:`2^l` in both width and height, matching the definition of mipmapping,
however it rounds down incorrectly. To compensate, the level contains one extra
row, column, or both (with the corner) as required if any of the first :math:`l`
levels were rounded down. This hurt the memory footprint. However, it means
non-power-of-two integer multiplication is only required for level 0.
Calculating the sizes for subsequent levels requires only addition and bitwise
math. That simplifies the hardware (but complicates software).
A 2D image consists of a full miptree (constructed as above) rounded up to the
page size (16 KiB).
3D images consist simply of an array of 2D layers (constructed as above). That
means cube maps, 2D arrays, cube map arrays, and 3D images all use the same
layout. The only difference is the number of layers. Notably, 3D images (like
``GL_TEXTURE_3D``) reserve space even for mip levels that do not exist
logically. These extra levels pad out layers of 3D images to the size of the
first layer, simplifying layout calculations for both software and hardware.
Although the padding is logically unnecessary, it wastes little space compared
to the sizes of large mipmapped 3D textures.
Twiddled
````````
In addition to GPU-tiled images, AGX also has a fully **twiddled** layout. The
image is rounded up to power-of-two dimensions, then all elements are stored in
Morton (Z) order.
A twiddled image is equivalent to a GPU-tiled image with a single square
power-of-two tile spanning the entire image. That means GPU-tiled and twiddled
images may share address calculation code, as long as everything is parametrized
in terms of the tile size.
In general, twiddled images require more memory than GPU-tiled images due to the
extra padding required. Because GPU tiles are page-sized, twiddling beyond that
does not offer any cache locality benefit either. The twiddled layout is
mostly vestigial at this point, but the PBE requires it for sparse mapping.
Sparse page tables
``````````````````
The hardware has native support for sparse images. If an texture/PBE descriptor
is configured in sparse mode, the specified address does not point to the image
itself. Rather, it points to a **sparse page table**. The extra indirection
enables on-device sparse binding (e.g. by updating the page table from a compute
kernel).
At the top level, the sparse page table is an array of **folios**. Each folio
describes 256 pages. The folio itself has two halves. The first half is the page
table itself, containing 4-byte "Sparse Block" data structures mapping image
pages to GPU virtual addresses. The second half is probably sparse texture
counters, again 4-bytes per page. Each folio therefore consumes :math:`256 \cdot
4 \cdot 2 = 2 \mathrm{KiB}` in order to describe :math:`256 \cdot 16384 =
4 \mathrm{MiB}`.
In a layered (array or 3D) image, a given folio only describes a single layer.
That implies extra padding between layers.
Within a layer, the table works purely at an address level. It maps pages to
pages, rather than tiles to tiles. It is not a spatial data structure in itself.
Rather, it inherits the tiling of the image by virtue of the addresses mapped.
This presumably simplifies the hardware implementation.
drm-shim (Linux only)
---------------------
Mesa includes a library that mocks out the DRM UABI used by the Asahi driver
stack, allowing the Mesa driver to run on non-M1 Linux hardware. This can be
useful for exercising the compiler. To build, use options:
::
-Dgallium-drivers=asahi -Dtools=drm-shim
Then run an OpenGL workload with environment variable:
.. code-block:: sh
LD_PRELOAD=~/mesa/build/src/asahi/drm-shim/libasahi_noop_drm_shim.so
For example to compile a shader with shaderdb and print some statistics along
with the IR:
.. code-block:: sh
~/shader-db$ AGX_MESA_DEBUG=shaders,shaderdb ASAHI_MESA_DEBUG=precompile LD_PRELOAD=~/mesa/build/src/asahi/drm-shim/libasahi_noop_drm_shim.so ./run shaders/glmark/1-12.shader_test
The drm-shim implementation for Asahi is located in ``src/asahi/drm-shim``. The
drm-shim implementation there should be updated as new UABI is added.
Hardware glossary
-----------------
AGX is a tiled renderer descended from the PowerVR architecture. Some hardware
concepts used in PowerVR GPUs appear in AGX.
.. glossary:: :sorted:
VDM
Vertex Data Master
Dispatches vertex shaders.
PDM
Pixel Data Master
Dispatches pixel shaders.
CDM
Compute Data Master
Dispatches compute kernels.
USC
Unified Shader Cores
A unified shader core is a small CPU that runs shader code. The core is
unified because a single ISA is used for vertex, pixel and compute
shaders. This differs from older GPUs where the vertex, fragment and
compute have separate ISAs for shader stages.
PPP
Primitive Processing Pipeline
The Primitive Processing Pipeline is a hardware unit that does primitive
assembly. The PPP is between the :term:`VDM` and :term:`ISP`.
ISP
Image Synthesis Processor
The Image Synthesis Processor is responsible for the rasterization stage
of the rendering pipeline.
PBE
Pixel BackEnd
Hardware unit which writes to color attachments and images. Also the
name for a descriptor passed to :term:`PBE` instructions.
UVS
Unified Vertex Store
Hardware unit which buffers the outputs of the vertex shader (varyings).
local/recipes/dev/mesa-clc/source/docs/drivers/d3d12.rst
+65
View File
@@ -0,0 +1,65 @@
D3D12
=====
Overview
--------
The D3D12 driver is a Gallium driver that emits API calls for Microsoft's
:abbr:`D3D12 (Direct3D 12)` API instead of targeting a specific GPU
architecture. This can be used to get full desktop OpenGL 3.3 support on
devices that only support D3D12.
Debugging
---------
There's a few tools that are useful for debugging D3D12, such as these
environment variables:
.. envvar:: D3D12_DEBUG
Accepts the following comma-separated list of flags:
``verbose``
Enable verbose output to stdout
``blit``
Trace blit and copy resource calls
``experimental``
Enable experimental shader models feature
``dxil``
Dump DXIL during program compile
``disass``
Dump disassambly of created DXIL shader
``res``
Debug resources
``debuglayer``
Enable `debug layer`_
``gpuvalidator``
Enable `GPU validator`_
.. envvar:: DXIL_DEBUG
Accepts the following comma-separated list of flags:
``verbose``
Enable verbose output to stdout
``dump_blob``
Write shader blobs
``trace``
Trace instruction conversion
``dump_module``
dump module tree to stderr
.. _debug layer: https://learn.microsoft.com/en-us/windows/win32/direct3d12/understanding-the-d3d12-debug-layer
.. _GPU validator: https://learn.microsoft.com/en-us/windows/win32/direct3d12/using-d3d12-debug-layer-gpu-based-validation
Utilities
---------
Environment variables that control the behavior of the D3D12 driver.
.. envvar:: MESA_D3D12_DEFAULT_ADAPTER_NAME
Specifies a substring to search for when choosing a default adapter to
run on. The first adapter matching the substring is chosen. The substring
is not case sensitive.

Some files were not shown because too many files have changed in this diff Show More