1
2                            Mesa 4.1 release notes
3
4                               October 29, 2002
5
6                                PLEASE READ!!!!
7
8
9
10Introduction
11------------
12
13Mesa uses an even/odd version number scheme like the Linux kernel.
14Even numbered versions (such as 4.0) designate stable releases.
15Odd numbered versions (such as 4.1) designate new developmental releases.
16
17
18New Features in Mesa 4.1
19------------------------
20
21New extensions.  Docs at http://oss.sgi.com/projects/ogl-sample/registry/
22
23GL_NV_vertex_program
24
25    NVIDIA's vertex programming extension
26
27GL_NV_vertex_program1_1
28
29    A few features built on top of GL_NV_vertex_program
30
31GL_ARB_window_pos
32
33    This is the ARB-approved version of GL_MESA_window_pos
34
35GL_ARB_depth_texture
36
37    This is the ARB-approved version of GL_SGIX_depth_texture.
38    It allows depth (Z buffer) data to be stored in textures.
39    This is used by GL_ARB_shadow
40
41GL_ARB_shadow
42
43    Shadow mapping with depth textures.
44    This is the ARB-approved version of GL_SGIX_shadow.
45
46GL_ARB_shadow_ambient
47
48    Allows one to specify the luminance of shadowed pixels.
49    This is the ARB-approved version of GL_SGIX_shadow_ambient.
50
51GL_EXT_shadow_funcs
52
53    Extends the set of GL_ARB_shadow texture comparision functions to
54    include all eight of standard OpenGL dept-test functions.
55
56GL_ARB_point_parameters
57
58    This is basically the same as GL_EXT_point_parameters.
59
60GL_ARB_texture_env_crossbar
61
62    Allows any texture combine stage to reference any texture source unit.
63
64GL_NV_point_sprite
65
66    For rendering points as textured quads.  Useful for particle effects.
67
68GL_NV_texture_rectangle  (new in 4.0.4 actually)
69
70    Allows one to use textures with sizes that are not powers of two.
71    Note that mipmapping and several texture wrap modes are not allowed.
72
73GL_EXT_multi_draw_arrays
74
75    Allows arrays of vertex arrays to be rendered with one call.
76
77GL_EXT_stencil_two_side
78
79   Separate stencil modes for front and back-facing polygons.
80
81GLX_SGIX_fbconfig & GLX_SGIX_pbuffer
82
83   Off-screen rendering support.
84
85GL_ATI_texture_mirror_once
86
87   Adds two new texture wrap modes: GL_MIRROR_CLAMP_ATI and
88   GL_MIRROR_CLAMP_TO_EDGE_ATI.
89
90
91
92Device Driver Status
93--------------------
94
95A number of Mesa's software drivers haven't been actively maintained for
96some time.  We rely on volunteers to maintain many of these drivers.
97Here's the current status of all included drivers:
98
99
100Driver			Status
101----------------------	---------------------
102XMesa (Xlib)		implements OpenGL 1.3
103OSMesa (off-screen)	implements OpenGL 1.3
104FX (3dfx Voodoo1/2)	implements OpenGL 1.3
105SVGA			implements OpenGL 1.3
106Wind River UGL		implements OpenGL 1.3
107Windows/Win32		implements OpenGL 1.3
108DOS/DJGPP		implements OpenGL 1.3
109GGI			implements OpenGL 1.3
110BeOS			needs updating (underway)
111Allegro			needs updating
112D3D			needs updating
113DOS			needs updating
114
115
116
117New features in GLUT
118--------------------
119
1201. Frames per second printing
121
122   GLUT now looks for an environment variable called "GLUT_FPS".  If it's
123   set, GLUT will print out a frames/second statistic to stderr when
124   glutSwapBuffers() is called.  By default, frames/second is computed
125   and displayed once every 5 seconds.  You can specify a different
126   interval (in milliseconds) when you set the env var.  For example
127   'export GLUT_FPS=1000' or 'setenv GLUT_FPS 1000' will set the interval
128   to one second.
129
130   NOTE: the demo or application must call the glutInit() function for
131   this to work.  Otherwise, the env var will be ignored.
132
133   Finally, this feature may not be reliable in multi-window programs.
134
135
1362. glutGetProcAddress() function
137
138   The new function:
139
140        void *glutGetProcAddress(const char *procName)
141
142   is a wrapper for glXGetProcAddressARB() and wglGetProcAddress().  It
143   lets you dynamically get the address of an OpenGL function at runtime.
144   The GLUT_API_VERSION has been bumped to 5, but I haven't bumped the
145   GLUT version number from 3.7 since that's probably Mark Kilgard's role.
146
147   This function should probably also be able to return the address of
148   GLUT functions themselves, but it doesn't do that yet.
149
150
151
152XXX Things To Do Yet XXXX
153-------------------------
154
155isosurf with vertex program exhibits some missing triangles (probably
156when recycling the vertex buffer for long prims).
157
158
159
160Porting Info
161------------
162
163If you're porting a DRI or other driver from Mesa 4.0.x to Mesa 4.1 here
164are some things to change:
165
1661. ctx->Texture._ReallyEnabled is obsolete.
167
168   Since there are now 5 texture targets (1D, 2D, 3D, cube and rect) that
169   left room for only 6 units (6*5 < 32) in this field.
170   This field is being replaced by ctx->Texture._EnabledUnits which has one
171   bit per texture unit.  If the bit k of _EnabledUnits is set, that means
172   ctx->Texture.Unit[k]._ReallyEnabled is non-zero.  You'll have to look at
173   ctx->Texture.Unit[k]._ReallyEnabled to learn if the 1D, 2D, 3D, cube or
174   rect texture is enabled for unit k.
175
176   This also means that the constants TEXTURE1_*, TEXTURE2_*, etc are
177   obsolete.
178
179   The tokens TEXTURE0_* have been replaced as well (since there's no
180   significance to the "0" part:
181
182   old token           new token
183   TEXTURE0_1D         TEXTURE_1D_BIT
184   TEXTURE0_2D         TEXTURE_2D_BIT
185   TEXTURE0_3D         TEXTURE_3D_BIT
186   TEXTURE0_CUBE       TEXTURE_CUBE_BIT
187   <none>              TEXTURE_RECT_BIT
188
189   These tokens are only used for the ctx->Texture.Unit[i].Enabled and
190   ctx->Texture.Unit[i]._ReallyEnabled fields.  Exactly 0 or 1 bits will
191   be set in _ReallyEnabled at any time!
192
193   Q: "What's the purpose of Unit[i].Enabled vs Unit[i]._ReallyEnabled?"
194   A: The user can enable GL_TEXTURE_1D, GL_TEXTURE_2D, etc for any
195      texure unit all at once (an unusual thing to do).
196      OpenGL defines priorities that basically say GL_TEXTURE_2D has
197      higher priority than GL_TEXTURE_1D, etc.  Also, just because a
198      texture target is enabled by the user doesn't mean we'll actually
199      use that texture!  If a texture object is incomplete (missing mip-
200      map levels, etc) it's as if texturing is disabled for that target.
201      The _ReallyEnabled field will have a bit set ONLY if the texture
202      target is enabled and complete.  This spares the driver writer from
203      examining a _lot_ of GL state to determine which texture target is
204      to be used.
205
206
2072. Tnl tokens changes
208
209   During the implementation of GL_NV_vertex_program some of the vertex
210   buffer code was changed.  Specifically, the VERT_* bits defined in
211   tnl/t_context.h have been renamed to better match the conventions of
212   GL_NV_vertex_program.  The old names are still present but obsolete.
213   Drivers should use the newer names.
214
215   For example:  VERT_RGBA is now VERT_BIT_COLOR0 and
216   VERT_SPEC_RGB is now VERT_BIT_COLOR1.
217
218
219
2203. Read/Draw Buffer changes
221
222   The business of setting the current read/draw buffers in Mesa 4.0.x
223   was complicated.  It's much simpler now in Mesa 4.1.
224
225   Here are the changes:
226
227   - Renamed ctx->Color.DrawDestMask to ctx->Color._DrawDestMask
228   - Removed ctx->Color.DriverDrawBuffer
229   - Removed ctx->Pixel.DriverReadBuffer
230   - Removed ctx->Color.MultiDrawBuffer
231   - Removed ctx->Driver.SetDrawBuffer()
232   - Removed swrast->Driver.SetReadBuffer().
233   - Added ctx->Color._DrawDestMask - a bitmask of FRONT/BACK_LEFT/RIGHT_BIT
234     values to indicate the current draw buffers.
235   - Added ctx->Pixel._ReadSrcMask to indicate the source for pixel reading.
236     The value is _one_ of the FRONT/BACK_LEFT/RIGHT_BIT values.
237   - Added ctx->Driver.DrawBuffer() and ctx->Driver.ReadBuffer().
238     These functions exactly correspond to glDrawBuffer and glReadBuffer calls.
239     Many drivers will set ctx->Driver.DrawBuffer = _swrast_DrawBuffer and
240     leave ctx->Draw.ReadBuffer NULL.
241     DRI drivers should implement their own function for ctx->Driver.DrawBuffer
242     and use it to set the current hardware drawing buffer.  You'll probably
243     also want to check for GL_FRONT_AND_BACK mode and fall back to software.
244     Call _swrast_DrawBuffer() too, to update the swrast state.
245   - Added swrast->Driver.SetBuffer().
246     This function should be implemented by all device drivers that use swrast.
247     Mesa will call it to specify the buffer to use for span reading AND
248     writing and point/line/triangle rendering.
249     There should be no confusion between current read or draw buffer anymore.
250   - Added swrast->CurrentBuffer to indicate which color buffer to read/draw.
251     Will be FRONT_LEFT_BIT, BACK_LEFT_BIT, FRONT_RIGHT_BIT or BACK_RIGHT_BIT.
252     This value is usually passed to swrast->Driver.SetBuffer().
253
254
2554. _mesa_create_context() changes.  This function now takes a pointer to
256   a __GLimports object.  The __GLimports structure contains function
257   pointers to system functions like fprintf(), malloc(), etc.
258   The _mesa_init_default_imports() function can be used to initialize
259   a __GLimports object.  Most device drivers (like the DRI drivers)
260   should use this.
261
262
2635. In tnl's struct vertex_buffer, the field "ProjectedClipCoords"
264   has been replaced by "NdcPtr" to better match the OpenGL spec's
265   terminology.
266
267
2686. Since GL_EXT_stencil_two_side has been implemented, many of the
269   ctx->Stencil fields are now 2-element arrays.  For example,
270   "GLenum Ref" is now "GLenum Ref[2]"  The [0] elements are the front-face
271   values and the [1] elements are the back-face values.
272   ctx->Stencil.ActiveFace is 0 or 1 to indicate the current face for
273   the glStencilOp/Func/Mask() functions.
274   ctx->Stencil.TestTwoSide controls whether or not 1 or 2-sided stenciling
275   is enabled.
276
277
2787. Removed ctx->Polygon._OffsetAny.  Removed ctx->Polygon.OffsetMRD.
279
280
2818. GLfloat / GLchan changes:
282
283   - Changed ctx->Driver.ClearColor() to take GLfloat[4] instead of GLchan[4].
284     ctx->Color.ClearColor is now GLfloat[4] too.
285   - Changed ctx->Driver.AlphaRef() to take GLfloat instead of GLchan.
286   - ctx->Color.AlphaRef is now GLfloat.
287   - texObj->BorderColor is now GLfloat[4].  texObj->_BorderChan is GLchan[4].
288
289   This is part of an effort to remove all GLchan types from core Mesa so
290   that someday we can support 8, 16 and 32-bit color channels dynamically
291   at runtime, instead of at compile-time.
292
293
2949. GLboolean ctx->Tranform.ClipEnabled[MAX_CLIP_PLANES] has been replaced
295   by GLuint ctx->Transform.ClipPlanesEnabled.  The later is a bitfield.
296
297
29810. There's a new matrix_stack type in mtypes.h used for the Modelview,
299   Projection, Color and Texcoord matrix stacks.
300
301
30211. The ctx->Current.* fields have changed a lot.  Now, there's a
303   ctx->Current.Attrib[] array for all vertex attributes which matches
304   the NV vertex program conventions.
305
306
307----------------------------------------------------------------------
308