docs/RELNOTES-4.1

   1
   2                             Mesa 4.1 release notes
   3
   4                                October 29, 2002
   5
   6                                 PLEASE READ!!!!
   7
   8
   9
  10 Introduction
  11 ------------
  12
  13 Mesa uses an even/odd version number scheme like the Linux kernel.
  14 Even numbered versions (such as 4.0) designate stable releases.
  15 Odd numbered versions (such as 4.1) designate new developmental releases.
  16
  17
  18 New Features in Mesa 4.1
  19 ------------------------
  20
  21 New extensions.  Docs at http://oss.sgi.com/projects/ogl-sample/registry/
  22
  23 GL_NV_vertex_program
  24
  25     NVIDIA's vertex programming extension
  26
  27 GL_NV_vertex_program1_1
  28
  29     A few features built on top of GL_NV_vertex_program
  30
  31 GL_ARB_window_pos
  32
  33     This is the ARB-approved version of GL_MESA_window_pos
  34
  35 GL_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
  41 GL_ARB_shadow
  42
  43     Shadow mapping with depth textures.
  44     This is the ARB-approved version of GL_SGIX_shadow.
  45
  46 GL_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
  51 GL_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
  56 GL_ARB_point_parameters
  57
  58     This is basically the same as GL_EXT_point_parameters.
  59
  60 GL_ARB_texture_env_crossbar
  61
  62     Allows any texture combine stage to reference any texture source unit.
  63
  64 GL_NV_point_sprite
  65
  66     For rendering points as textured quads.  Useful for particle effects.
  67
  68 GL_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
  73 GL_EXT_multi_draw_arrays
  74
  75     Allows arrays of vertex arrays to be rendered with one call.
  76
  77 GL_EXT_stencil_two_side
  78
  79    Separate stencil modes for front and back-facing polygons.
  80
  81 GLX_SGIX_fbconfig & GLX_SGIX_pbuffer
  82
  83    Off-screen rendering support.
  84
  85 GL_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
  92 Device Driver Status
  93 --------------------
  94
  95 A number of Mesa's software drivers haven't been actively maintained for
  96 some time.  We rely on volunteers to maintain many of these drivers.
  97 Here's the current status of all included drivers:
  98
  99
 100 Driver                  Status
 101 ----------------------  ---------------------
 102 XMesa (Xlib)            implements OpenGL 1.3
 103 OSMesa (off-screen)     implements OpenGL 1.3
 104 FX (3dfx Voodoo1/2)     implements OpenGL 1.3
 105 SVGA                    implements OpenGL 1.3
 106 Wind River UGL          implements OpenGL 1.3
 107 Windows/Win32           implements OpenGL 1.3
 108 DOS/DJGPP               implements OpenGL 1.3
 109 GGI                     implements OpenGL 1.3
 110 BeOS                    needs updating (underway)
 111 Allegro                 needs updating
 112 D3D                     needs updating
 113 DOS                     needs updating
 114
 115
 116
 117 New features in GLUT
 118 --------------------
 119
 120 1. 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
 136 2. 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
 152 XXX Things To Do Yet XXXX
 153 -------------------------
 154
 155 isosurf with vertex program exhibits some missing triangles (probably
 156 when recycling the vertex buffer for long prims).
 157
 158
 159
 160 Porting Info
 161 ------------
 162
 163 If you're porting a DRI or other driver from Mesa 4.0.x to Mesa 4.1 here
 164 are some things to change:
 165
 166 1. 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
 207 2. 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
 220 3. 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
 255 4. _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
 263 5. 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
 268 6. 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
 278 7. Removed ctx->Polygon._OffsetAny.  Removed ctx->Polygon.OffsetMRD.
 279
 280
 281 8. 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
 294 9. GLboolean ctx->Tranform.ClipEnabled[MAX_CLIP_PLANES] has been replaced
 295    by GLuint ctx->Transform.ClipPlanesEnabled.  The later is a bitfield.
 296
 297
 298 10. There's a new matrix_stack type in mtypes.h used for the Modelview,
 299    Projection, Color and Texcoord matrix stacks.
 300
 301
 302 11. 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 ----------------------------------------------------------------------