docs/relnotes/3.3

                         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.


----------------------------------------------------------------------