SecBSD/xenocara
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

sync code with last improvements from OpenBSD

Browse source
This commit is contained in:
purplerain 2023-08-28 05:57:34 +00:00
commit 88965415ff
Signed by: purplerain
GPG key ID: F42C07F07E2E35B7
26235 changed files with 29195616 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

564
lib/mesa/docs/_extra/specs/OLD/EGL_MESA_screen_surface.txt Normal file
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 specifing 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.

94
lib/mesa/docs/_extra/specs/OLD/MESA_agp_offset.spec Normal file
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

230
lib/mesa/docs/_extra/specs/OLD/MESA_packed_depth_stencil.spec Normal file
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.

356
lib/mesa/docs/_extra/specs/OLD/MESA_program_debug.spec Normal file
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();

81
lib/mesa/docs/_extra/specs/OLD/MESA_resize_buffers.spec Normal file
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

85
lib/mesa/docs/_extra/specs/OLD/MESA_set_3dfx_mode.spec Normal file
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

190
lib/mesa/docs/_extra/specs/OLD/MESA_sprite_point.spec Normal file
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.

359
lib/mesa/docs/_extra/specs/OLD/MESA_trace.spec Normal file
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 explicitely support the notion of "frames?
This would require hooking into glXSwapBuffers calls as well.
RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA
and TraceComment along with external parsing tools to split the
trace into frames, in whatever way considered adequate.
(2a) Should GLX calls be traced?
PBuffers and other render-to-texture solutions demonstrate that
context level commands beyond SwapBuffers might have to be
traced. The GL DLL exports the entry points, so this would not
be out of the question.
(3) Should the specification mandate the actual output format?
RESOLVED: No. It is sufficient to guarantee that all data and commands
will be traced as requested by Enable/DisableTraceMESA, in the order
encountered. Whether the resulting trace is available as a readable
text file, binary metafile, compilable source code, much less which
indentation and formatting has been used, is up to the implementation.
For the same reason this specification does not enforce or prohibit
additional information added to the trace (statistics, profiling/timing,
warnings on possible error conditions).
(4) Should the comment strings associated with names and pointer (ranges)
be considered persistent state?
RESOLVED: No. The implementation is not forced to use this information
on subsequent occurences of name/pointer, and is free to consider it
transient state.
(5) Should comment commands be prohibited between Begin/End?
RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA
is transient, the other commands might cause storage of persistent
data in the context. There is no need to have the ability mark names
or pointers between Begin and End.
New Procedures and Functions
void NewTraceMESA( bitfield mask, const ubyte * traceName )
void EndTraceMESA( void )
void EnableTraceMESA( bitfield mask )
void DisableTraceMESA( bitfield mask )
void TraceAssertAttribMESA( bitfield attribMask )
void TraceCommentMESA( const ubyte* comment )
void TraceTextureMESA( uint name, const ubyte* comment )
void TraceListMESA( uint name, const ubyte* comment )
void TracePointerMESA( void* pointer, const ubyte* comment )
void TracePointerRangeMESA( const void* first,
const void* last,
const ubyte* comment )
New Tokens
Accepted by the <mask> parameter of EnableTrace and DisableTrace:
TRACE_ALL_BITS_MESA 0xFFFF
TRACE_OPERATIONS_BIT_MESA 0x0001
TRACE_PRIMITIVES_BIT_MESA 0x0002
TRACE_ARRAYS_BIT_MESA 0x0004
TRACE_TEXTURES_BIT_MESA 0x0008
TRACE_PIXELS_BIT_MESA 0x0010
TRACE_ERRORS_BIT_MESA 0x0020
Accepted by the <pname> parameter of GetIntegerv, GetBooleanv,
GetFloatv, and GetDoublev:
TRACE_MASK_MESA 0x8755
Accepted by the <pname> parameter to GetString:
TRACE_NAME_MESA 0x8756
Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
Add a new section:
5.7 Tracing
The tracing facility is used to record the execution of a GL program
to a human-readable log. The log appears as a sequence of GL commands
using C syntax. The primary intention of tracing is to aid in program
debugging.
A trace is started with the command
void NewTraceMESA( bitfield mask, const GLubyte * traceName )
<mask> may be any value accepted by PushAttrib and specifies a set of
attribute groups. The state values included in those attribute groups
is written to the trace as a sequence of GL commands.
<traceName> specifies a name or label for the trace. It is expected
that <traceName> will be interpreted as a filename in most implementations.
A trace is ended by calling the command
void EndTraceMESA( void )
It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End.
The commands
void EnableTraceMESA( bitfield mask )
void DisableTraceMESA( bitfield mask )
enable or disable tracing of different classes of GL commands.
<mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA,
TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA,
and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA
indicates all classes of commands are to be logged.
TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of
Begin/End, including Begin/End.
TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of
Begin/End, including Begin/End.
TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer,
ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands.
TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by
TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and
TexSubImage3D commands.
TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by
Bitmap and DrawPixels commands.
TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is
set, GetError will be executed whereever applicable, and the result will
be added to the trace as a comment. The error returns are cached and
returned to the application on its GetError calls. If the user does not
wish the additional GetError calls to be performed, this bit should not
be set.
The command
void TraceCommentMESA( const ubyte* comment )
immediately adds the <comment> string to the trace output, surrounded
by C-style comment delimiters.
The commands
void TraceTextureMESA( uint name, const ubyte* comment )
void TraceListMESA( uint name, const ubyte* comment )
associates <comment> with the texture object or display list specified
by <name>. Logged commands which reference the named texture object or
display list will be annotated with <comment>. If IsTexture(name) or
IsList(name) fail (respectively) the command is quietly ignored.
The commands
void TracePointerMESA( void* pointer, const ubyte* comment )
void TracePointerRangeMESA( const void* first,
const void* last,
const ubyte* comment )
associate <comment> with the address specified by <pointer> or with
a range of addresses specified by <first> through <last>.
Any logged commands which reference <pointer> or an address between
<first> and <last> will be annotated with <comment>.
The command
void TraceAssertAttribMESA( bitfield attribMask )
will add GL state queries and assertion statements to the log to
confirm that the current state at the time TraceAssertAttrib is
executed matches the current state when the trace log is executed
in the future.
<attribMask> is any value accepted by PushAttrib and specifies
the groups of state variables which are to be asserted.
The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA,
TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA,
TracePointerMESA and TracePointerRangeMESA are not compiled into display lists.
Examples:
The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state
variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
to get the values <test>, <func>, <mask>, and <clear> respectively.
Statements equivalent to the following will then be logged:
glEnable(GL_DEPTH_TEST); (if <test> is true)
glDisable(GL_DEPTH_TEST); (if <test> is false)
glDepthFunc(<func>);
glDepthMask(<mask>);
glClearDepth(<clear>);
The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state
variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
to get the values <test>, <func>, <mask>, and <clear> respectively.
The resulting trace might then look will like this:
{
GLboolean b;
GLint i;
GLfloat f;
b = glIsEnabled(GL_DEPTH_TEST);
assert(b == <test>);
glGetIntegerv(GL_DEPTH_FUNC, &i);
assert(i == <func>);
glGetIntegerv(GL_DEPTH_MASK, &i);
assert(i == <mask>);
glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f);
assert(f == <clear>);
}
Additions to Chapter 6 of the OpenGL 1.2.1 Specification
(State and State Requests)
Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or
GetDoublev returns the current command class trace mask.
Querying TRACE_NAME_MESA with GetString returns the current trace name.
Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
The MESA_trace extension can be used in a way that does not affect data
flow from application to OpenGL, as well as data flow from OpenGL to
application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA
will add additional GetError queries. Setting a trace mask with NewTraceMESA
as well as use of TraceAssertAttribMESA might cause additional state queries.
With the possible exception of performance, OpenGL rendering should not be
affected at all by a properly chosen logging operation.
Additions to the AGL/GLX/WGL Specifications
None.
GLX Protocol
None. The logging operation is carried out client-side, by exporting
entry points to the wrapper functions that execute the logging operation.
Errors
INVALID_OPERATION is generated if any trace command except TraceCommentMESA
is called between Begin and End.
New State
The current trace name and current command class mask are stored
per-context.
New Implementation Dependent State
None.
Revision History
* Revision 0.1 - Initial draft from template (bk000415)
* Revision 0.2 - Draft (bk000906)
* Revision 0.3 - Draft (bk000913)
* Revision 0.4 - Reworked text, fixed typos (bp000914)
* Revision 0.5 - Assigned final GLenum values (bp001103)
* Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916)
* Revision 0.7 - Added MESA postfix (bk010126)