Merge Jose's documentation and core Mesa changes from embedded branch

1 files changed, 189 insertions, 54 deletions

diff --git a/src/mesa/main/teximage.c b/src/mesa/main/teximage.c
index de28839463a..90f03322373 100644
--- a/src/mesa/main/teximage.c
+++ b/src/mesa/main/teximage.c
@@ -1,3 +1,14 @@
+/**
+ * \file teximage.c
+ * Texture images manipulation functions.
+ *
+ * \note Mesa's native texture data type is GLchan.  Native formats are
+ * GL_ALPHA, GL_LUMINANCE, GL_LUMANCE_ALPHA, GL_INTENSITY, GL_RGB, GL_RGBA, and
+ * GL_COLOR_INDEX.
+ *
+ * \note Device drivers are free to implement any internal format they want.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -22,6 +33,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #include "glheader.h"
 #include "context.h"
 #include "convolve.h"
@@ -37,16 +49,6 @@
 #include "mtypes.h"
 
 
-/*
- * NOTES:
- *
- * Mesa's native texture datatype is GLchan.  Native formats are
- * GL_ALPHA, GL_LUMINANCE, GL_LUMANCE_ALPHA, GL_INTENSITY, GL_RGB, GL_RGBA,
- * and GL_COLOR_INDEX.
- * Device drivers are free to implement any internal format they want.
- */
-
-
 #if 0
 static void PrintTexture(GLcontext *ctx, const struct gl_texture_image *img)
 {
@@ -101,7 +103,6 @@ static void PrintTexture(GLcontext *ctx, const struct gl_texture_image *img)
 #endif
 
 
-
 /*
  * Compute floor(log_base_2(n)).
  * If n <= 0 return -1.
@@ -130,15 +131,17 @@ logbase2( int n )
 
 
 
-/*
- * Given an internal texture format enum or 1, 2, 3, 4 return the
- * corresponding _base_ internal format:  GL_ALPHA, GL_LUMINANCE,
- * GL_LUMANCE_ALPHA, GL_INTENSITY, GL_RGB, or GL_RGBA.
+/**
+ * Get base internal format.
+ *
+ * \param ctx GL context.
+ * \param format internal texture format enum or 1, 2, 3, 4.
+ *
+ * \return the corresponding \u base internal format (GL_ALPHA, GL_LUMINANCE,
+ * GL_LUMANCE_ALPHA, GL_INTENSITY, GL_RGB, or GL_RGBA), or -1 if invalid enum.
  *
  * This is the format which is used during texture application (i.e. the
  * texture format and env mode determine the arithmetic used.
- *
- * Return -1 if invalid enum.
  */
 GLint
 _mesa_base_tex_format( GLcontext *ctx, GLint format )
@@ -270,9 +273,9 @@ _mesa_base_tex_format( GLcontext *ctx, GLint format )
 }
 
 
-/*
- * Test if the given image format is a color/rgba format.  That is,
- * not color index, depth, stencil, etc.
+/**
+ * Test if the given image format is a color/RGBA format, i.e., not
+ * color index, depth, stencil, etc.
  */
 static GLboolean
 is_color_format(GLenum format)
@@ -328,6 +331,9 @@ is_color_format(GLenum format)
 }
 
 
+/**
+ * Test if the given image format is a color index format.
+ */
 static GLboolean
 is_index_format(GLenum format)
 {
@@ -347,9 +353,15 @@ is_index_format(GLenum format)
 
 
 /**
- * Return GL_TRUE if internalFormat is a supported compressed format,
- * return GL_FALSE otherwise.
- * \param - internalFormat - the internal format token provided by the user
+ * Test if it is a supported compressed format.
+ * 
+ * \param internalFormat the internal format token provided by the user.
+ * 
+ * \ret GL_TRUE if \p internalFormat is a supported compressed format, or
+ * GL_FALSE otherwise.
+ *
+ * Currently only GL_COMPRESSED_RGB_FXT1_3DFX and GL_COMPRESSED_RGBA_FXT1_3DFX
+ * are supported.
  */
 static GLboolean
 is_compressed_format(GLenum internalFormat)
@@ -364,9 +376,15 @@ is_compressed_format(GLenum internalFormat)
 }
 
 
-/*
+/**
  * Store a gl_texture_image pointer in a gl_texture_object structure
  * according to the target and level parameters.
+ * 
+ * \param tObj texture object.
+ * \param target texture target.
+ * \param level image level.
+ * \param texImage texture image.
+ * 
  * This was basically prompted by the introduction of cube maps.
  */
 void
@@ -411,11 +429,14 @@ _mesa_set_tex_image(struct gl_texture_object *tObj,
 }
 
 
-
 /**
- * Return new gl_texture_image struct with all fields initialized to zero.
+ * Allocate a texture image structure.
+ * 
  * Called via ctx->Driver.NewTextureImage() unless overriden by a device
  * driver.
+ *
+ * \return a pointer to gl_texture_image struct with all fields initialized to
+ * zero.
  */
 struct gl_texture_image *
 _mesa_new_texture_image( GLcontext *ctx )
@@ -425,9 +446,12 @@ _mesa_new_texture_image( GLcontext *ctx )
 }
 
 
-
 /**
- * Delete/free the given texture image and associated image data if it's not
+ * Free texture image.
+ *
+ * \param teximage texture image.
+ *
+ * Free the texture image structure and the associated image data if it's not
  * marked as client data.
  */
 void
@@ -441,8 +465,12 @@ _mesa_delete_texture_image( struct gl_texture_image *teximage )
 }
 
 
-/*
- * Return GL_TRUE if the target is a proxy target.
+/**
+ * Test if a target is a proxy target.
+ *
+ * \param target texture target.
+ *
+ * \return GL_TRUE if the target is a proxy target, GL_FALSE otherwise.
  */
 static GLboolean
 is_proxy_target(GLenum target)
@@ -455,9 +483,16 @@ is_proxy_target(GLenum target)
 }
 
 
-/*
- * Given a texture unit and a texture target, return the corresponding
- * texture object.
+/**
+ * Get the texture object that corresponds to the target of the given texture unit.
+ *
+ * \param ctx GL context.
+ * \param texUnit texture unit.
+ * \param target texture target.
+ *
+ * \return pointer to the texture object on success, or NULL on failure.
+ * 
+ * \sa gl_texture_unit.
  */
 struct gl_texture_object *
 _mesa_select_tex_object(GLcontext *ctx, const struct gl_texture_unit *texUnit,
@@ -501,9 +536,18 @@ _mesa_select_tex_object(GLcontext *ctx, const struct gl_texture_unit *texUnit,
 }
 
 
-/*
- * Return the texture image struct which corresponds to target and level
- * for the given texture unit.
+/**
+ * Get the texture image struct which corresponds to target and level
+ * of the given texture unit.
+ *
+ * \param ctx GL context.
+ * \param texUnit texture unit.
+ * \param target texture target.
+ * \param level image level.
+ *
+ * \return pointer to the texture image structure on success, or NULL on failure.
+ *
+ * \sa gl_texture_unit.
  */
 struct gl_texture_image *
 _mesa_select_tex_image(GLcontext *ctx, const struct gl_texture_unit *texUnit,
@@ -694,9 +738,16 @@ _mesa_get_proxy_tex_image(GLcontext *ctx, GLenum target, GLint level)
 }
 
 
-/*
- * Return the maximum number of allows mipmap levels for the given
- * texture target.
+/**
+ * Get the maximum number of allowed mipmap levels.
+ *
+ * \param ctx GL context.
+ * \param target texture target.
+ * 
+ * \return the maximum number of allowed mipmap levels for the given
+ * texture target, or zero if passed a bad target.
+ *
+ * \sa gl_constants.
  */
 GLint
 _mesa_max_texture_levels(GLcontext *ctx, GLenum target)
@@ -786,6 +837,9 @@ make_null_texture(GLint width, GLint height, GLint depth, GLenum format)
 
 /**
  * Reset the fields of a gl_texture_image struct to zero.
+ * 
+ * \param img texture image structure.
+ *
  * This is called when a proxy texture test fails, we set all the
  * image members (except DriverData) to zero.
  * It's also used in glTexImage[123]D as a safeguard to be sure all
@@ -817,8 +871,19 @@ clear_teximage_fields(struct gl_texture_image *img)
 }
 
 
-/*
+/**
  * Initialize basic fields of the gl_texture_image struct.
+ *
+ * \param ctx GL context.
+ * \param target texture target.
+ * \param img texture image structure to be initialized.
+ * \param width image width.
+ * \param height image height.
+ * \param depth image depth.
+ * \param border image border.
+ * \param internalFormat internal format.
+ *
+ * Fills in the fields of \p img with the given information.
  * Note: width, height and depth include the border.
  */
 void
@@ -978,11 +1043,25 @@ _mesa_test_proxy_teximage(GLcontext *ctx, GLenum target, GLint level,
 
 
 /**
- * Test glTexImage[123]D() parameters for errors.
- * This function calls the ctx->Driver.TestProxyTexImage() function to
- * check the level and size.
- * \param dimensions  must be 1 or 2 or 3
- * \return  GL_TRUE if an error was detected or GL_FALSE if no errors
+ * Test the glTexImage[123]D() parameters for errors.
+ * 
+ * \param ctx GL context.
+ * \param target texture target given by the user.
+ * \param level image level given by the user.
+ * \param internalFormat internal format given by the user.
+ * \param format pixel data format given by the user.
+ * \param type pixel data type given by the user.
+ * \param dimensions texture image dimensions (must be 1, 2 or 3).
+ * \param width image width given by the user.
+ * \param height image height given by the user.
+ * \param depth image depth given by the user.
+ * \param border image border given by the user.
+ * 
+ * \return GL_TRUE if an error was detected, or GL_FALSE if no errors.
+ *
+ * Verifies each of the parameters against the constants specified in
+ * __GLcontextRec::Const and the supported extensions, and according to the
+ * OpenGL specification.
  */
 static GLboolean
 texture_error_check( GLcontext *ctx, GLenum target,
@@ -1186,12 +1265,27 @@ texture_error_check( GLcontext *ctx, GLenum target,
 }
 
 
-
-/*
+/**
  * Test glTexSubImage[123]D() parameters for errors.
- * Input:
- *         dimensions - must be 1 or 2 or 3
- * Return:  GL_TRUE = an error was detected, GL_FALSE = no errors
+ * 
+ * \param ctx GL context.
+ * \param dimensions texture image dimensions (must be 1, 2 or 3).
+ * \param target texture target given by the user.
+ * \param level image level given by the user.
+ * \param xoffset sub-image x offset given by the user.
+ * \param yoffset sub-image y offset given by the user.
+ * \param zoffset sub-image z offset given by the user.
+ * \param format pixel data format given by the user.
+ * \param type pixel data type given by the user.
+ * \param width image width given by the user.
+ * \param height image height given by the user.
+ * \param depth image depth given by the user.
+ * 
+ * \return GL_TRUE if an error was detected, or GL_FALSE if no errors.
+ *
+ * Verifies each of the parameters against the constants specified in
+ * __GLcontextRec::Const and the supported extensions, and according to the
+ * OpenGL specification.
  */
 static GLboolean
 subtexture_error_check( GLcontext *ctx, GLuint dimensions,
@@ -1353,10 +1447,24 @@ subtexture_error_check( GLcontext *ctx, GLuint dimensions,
 }
 
 
-/*
+/**
  * Test glCopyTexImage[12]D() parameters for errors.
- * Input:  dimensions - must be 1 or 2 or 3
- * Return:  GL_TRUE = an error was detected, GL_FALSE = no errors
+ * 
+ * \param ctx GL context.
+ * \param dimensions texture image dimensions (must be 1, 2 or 3).
+ * \param target texture target given by the user.
+ * \param level image level given by the user.
+ * \param internalFormat internal format given by the user.
+ * \param width image width given by the user.
+ * \param height image height given by the user.
+ * \param depth image depth given by the user.
+ * \param border texture border.
+ * 
+ * \return GL_TRUE if an error was detected, or GL_FALSE if no errors.
+ * 
+ * Verifies each of the parameters against the constants specified in
+ * __GLcontextRec::Const and the supported extensions, and according to the
+ * OpenGL specification.
  */
 static GLboolean
 copytexture_error_check( GLcontext *ctx, GLuint dimensions,
@@ -1477,6 +1585,25 @@ copytexture_error_check( GLcontext *ctx, GLuint dimensions,
 }
 
 
+/**
+ * Test glCopyTexImage[12]D() parameters for errors.
+ * 
+ * \param ctx GL context.
+ * \param dimensions texture image dimensions (must be 1, 2 or 3).
+ * \param target texture target given by the user.
+ * \param level image level given by the user.
+ * \param xoffset sub-image x offset given by the user.
+ * \param yoffset sub-image y offset given by the user.
+ * \param zoffset sub-image z offset given by the user.
+ * \param width image width given by the user.
+ * \param height image height given by the user.
+ * 
+ * \return GL_TRUE if an error was detected, or GL_FALSE if no errors.
+ * 
+ * Verifies each of the parameters against the constants specified in
+ * __GLcontextRec::Const and the supported extensions, and according to the
+ * OpenGL specification.
+ */
 static GLboolean
 copytexsubimage_error_check( GLcontext *ctx, GLuint dimensions,
                              GLenum target, GLint level,
@@ -1618,7 +1745,15 @@ copytexsubimage_error_check( GLcontext *ctx, GLuint dimensions,
 }
 
 
-
+/**
+ * Get texture image.
+ *
+ * \param target texture target.
+ * \param level image level.
+ * \param format pixel data format.
+ * \param type pixel data type.
+ * \param pixels pixel data.
+ */
 void
 _mesa_GetTexImage( GLenum target, GLint level, GLenum format,
                    GLenum type, GLvoid *pixels )