diff options
Diffstat (limited to 'src/mesa/main/teximage.c')
| -rw-r--r-- | src/mesa/main/teximage.c | 243 |
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 ) |