fdo-mirrors/mesa
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/mesa/mesa.git synced 2026-05-08 15:38:09 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Doxygen documentation additions and fixes

Browse source
This commit is contained in:
Jose Fonseca 2003-03-09 10:52:20 +00:00
parent 50d1c2c921
commit bafbdcb703
11 changed files with 432 additions and 120 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

283
src/mesa/main/context.c
View file

@ -28,7 +28,7 @@
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
/* $Id: context.c,v 1.188.2.1.2.6 2003/03/05 14:22:21 keithw Exp $ */
/* $Id: context.c,v 1.188.2.1.2.7 2003/03/09 10:52:20 jrfonseca Exp $ */
/**
* \mainpage Mesa Core Module
@ -134,8 +134,15 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss );
/*@{*/
/**
* Called by window system/device driver (via gc->exports.destroyCurrent())
* when the rendering context is to be destroyed.
* \brief Destroy context callback.
*
* \param gc context.
* \return GL_TRUE on success, or GL_FALSE on failure.
*
* Called by window system/device driver (via __GLexports::destroyCurrent) when
* the rendering context is to be destroyed.
*
* Frees the context data and the context structure.
*/
GLboolean
_mesa_destroyContext(__GLcontext *gc)
@ -148,8 +155,15 @@ _mesa_destroyContext(__GLcontext *gc)
}
/**
* Called by window system/device driver (via gc->exports.loseCurrent())
* \brief Unbind context callback.
*
* \param gc context.
* \return GL_TRUE on success, or GL_FALSE on failure.
*
* Called by window system/device driver (via __GLexports::loseCurrent)
* when the rendering context is made non-current.
*
* No-op.
*/
GLboolean
_mesa_loseCurrent(__GLcontext *gc)
@ -159,8 +173,15 @@ _mesa_loseCurrent(__GLcontext *gc)
}
/**
* Called by window system/device driver (via gc->exports.makeCurrent())
* \brief Bind context callback.
*
* \param gc context.
* \return GL_TRUE on success, or GL_FALSE on failure.
*
* Called by window system/device driver (via __GLexports::makeCurrent)
* when the rendering context is made current.
*
* No-op.
*/
GLboolean
_mesa_makeCurrent(__GLcontext *gc)
@ -170,8 +191,12 @@ _mesa_makeCurrent(__GLcontext *gc)
}
/**
* Called by window system/device driver - yadda, yadda, yadda.
* See above comments.
* \brief Share context callback.
*
* \param gc context.
* \return GL_TRUE on success, or GL_FALSE on failure.
*
* Called by window system/device driver (via __GLexports::shareContext)
*/
GLboolean
_mesa_shareContext(__GLcontext *gc, __GLcontext *gcShare)
@ -190,6 +215,9 @@ _mesa_shareContext(__GLcontext *gc, __GLcontext *gcShare)
}
}
/**
* \brief Copy context callback.
*/
GLboolean
_mesa_copyContext(__GLcontext *dst, const __GLcontext *src, GLuint mask)
{
@ -202,12 +230,19 @@ _mesa_copyContext(__GLcontext *dst, const __GLcontext *src, GLuint mask)
}
}
/** No-op. */
GLboolean
_mesa_forceCurrent(__GLcontext *gc)
{
return GL_TRUE;
}
/**
* \brief Windows/buffer resizing notification callback.
*
* \param gc GL context.
* \return GL_TRUE on success, or GL_FALSE on failure.
*/
GLboolean
_mesa_notifyResize(__GLcontext *gc)
{
@ -222,7 +257,13 @@ _mesa_notifyResize(__GLcontext *gc)
}
/**
* \brief Window/buffer destruction notification callback.
*
* \param gc GL context.
*
* Called when the context's window/buffer is going to be destroyed.
*
* No-op.
*/
void
_mesa_notifyDestroy(__GLcontext *gc)
@ -231,6 +272,10 @@ _mesa_notifyDestroy(__GLcontext *gc)
}
/**
* \brief Swap buffers notification callback.
*
* \param gc GL context.
*
* Called by window system just before swapping buffers.
* We have to finish any pending rendering.
*/
@ -240,17 +285,20 @@ _mesa_notifySwapBuffers(__GLcontext *gc)
FLUSH_VERTICES( gc, 0 );
}
/** \brief No-op. */
struct __GLdispatchStateRec *
_mesa_dispatchExec(__GLcontext *gc)
{
return NULL;
}
/** \brief No-op. */
void
_mesa_beginDispatchOverride(__GLcontext *gc)
{
}
/** \brief No-op. */
void
_mesa_endDispatchOverride(__GLcontext *gc)
{
@ -330,15 +378,15 @@ __glCoreNopDispatch(void)
/**
* \brief Allocate a new GLvisual object.
*
* \param rgbFlag GL_TRUE=RGB(A) mode, GL_FALSE=Color Index mode
* \param dbFlag double buffering?
* \param stereoFlag stereo buffer?
* \param rgbFlag GL_TRUE for RGB(A) mode, GL_FALSE for Color Index mode.
* \param dbFlag double buffering
* \param stereoFlag stereo buffer
* \param depthBits requested bits per depth buffer value. Any value in [0, 32]
* is acceptable but the actual depth type will be GLushort or GLuint as
* needed.
* \param stencilBits requested minimum bits per stencil buffer value
* \param accumBits requested minimum bits per accum buffer component
* \param indexBits number of bits per pixel if rgbFlag==GL_FALSE
* \param indexBits number of bits per pixel if \p rgbFlag is GL_FALSE
* \param red number of bits per color component in frame buffer for RGB(A)
* mode. We always use 8 in core Mesa though.
* \param green same as above.
@ -347,6 +395,9 @@ __glCoreNopDispatch(void)
*
* \return pointer to new GLvisual or NULL if requested parameters can't be
* met.
*
* Allocates a GLvisual structure and initializes it via
* _mesa_initialize_visual().
*/
GLvisual *
_mesa_create_visual( GLboolean rgbFlag,
@ -385,7 +436,10 @@ _mesa_create_visual( GLboolean rgbFlag,
*
* \return GL_TRUE on success, or GL_FALSE on failure.
*
* \sa see _mesa_create_visual() above.
* \sa _mesa_create_visual() above for the parameter description.
*
* Makes some sanity checks and fills in the fields of the
* GLvisual structure with the given parameters.
*/
GLboolean
_mesa_initialize_visual( GLvisual *vis,
@ -462,6 +516,13 @@ _mesa_initialize_visual( GLvisual *vis,
return GL_TRUE;
}
/**
* \brief Destroy a visual.
*
* \param vis visual.
*
* Frees the visual structure.
*/
void
_mesa_destroy_visual( GLvisual *vis )
{
@ -489,6 +550,9 @@ _mesa_destroy_visual( GLvisual *vis )
* \param softwareAlpha create/use a software alpha buffer?
*
* \return pointer to new GLframebuffer struct or NULL if error.
*
* Allocate a GLframebuffer structure and initializes it via
* _mesa_initialize_framebuffer().
*/
GLframebuffer *
_mesa_create_framebuffer( const GLvisual *visual,
@ -510,7 +574,10 @@ _mesa_create_framebuffer( const GLvisual *visual,
/**
* \brief Initialize a GLframebuffer object.
*
* \sa _mesa_create_framebuffer() above.
* \sa _mesa_create_framebuffer() above for the parameter description.
*
* Makes some sanity checks and fills in the fields of the
* GLframebuffer structure with the given parameters.
*/
void
_mesa_initialize_framebuffer( GLframebuffer *buffer,
@ -550,9 +617,10 @@ _mesa_initialize_framebuffer( GLframebuffer *buffer,
buffer->UseSoftwareAlphaBuffers = softwareAlpha;
}
/**
* \brief Free a framebuffer struct and its buffers.
*
* Calls _mesa_free_framebuffer_data() and frees the structure.
*/
void
_mesa_destroy_framebuffer( GLframebuffer *buffer )
@ -563,9 +631,12 @@ _mesa_destroy_framebuffer( GLframebuffer *buffer )
}
}
/**
* \brief Free the data hanging off of \p buffer, but not \p buffer itself.
*
* \param buffer framebuffer.
*
* Frees all the buffers associated with the structure.
*/
void
_mesa_free_framebuffer_data( GLframebuffer *buffer )
@ -607,14 +678,29 @@ _mesa_free_framebuffer_data( GLframebuffer *buffer )
/**********************************************************************/
/** \name Context allocation, initialization, destroying *****/
/** \name Context allocation, initialization, destroying */
/**********************************************************************/
/**
* The purpose of the most initalization functions here is to provide the
* default state values according to the OpenGL specification.
*/
/*@{*/
/**
* \brief One-time initalization mutex lock.
*
* \sa Used by one_time_init().
*/
_glthread_DECLARE_STATIC_MUTEX(OneTimeLock);
/**
* \brief This function just calls all the various one-time-init functions in Mesa.
* \brief Calls all the various one-time-init functions in Mesa.
*
* While holding the OneTimeLock lock, calls several initialization functions,
* and sets the glapi callbacks if the \c MESA_DEBUG environment variable is
* defined.
*
* \sa _mesa_init_lists(), _math_init() and _mesa_init_math().
*/
static void
one_time_init( GLcontext *ctx )
@ -663,6 +749,17 @@ one_time_init( GLcontext *ctx )
_glthread_UNLOCK_MUTEX(OneTimeLock);
}
/**
* \brief Initialize a matrix stack.
*
* \param stack matrix stack.
* \param maxDepth maximum stack depth.
* \param dirtyFlag dirty flag.
*
* Allocates an array of \p maxDepth elements for the matrix stack and calls
* _math_matrix_ctr() and _math_matrix_alloc_inv() for each element to
* initialize it.
*/
static void
init_matrix_stack( struct matrix_stack *stack,
GLuint maxDepth, GLuint dirtyFlag )
@ -681,6 +778,14 @@ init_matrix_stack( struct matrix_stack *stack,
stack->Top = stack->Stack;
}
/**
* \brief Free matrix stack.
*
* \param stack matrix stack.
*
* Calls _math_matrix_dtr() for each element of the matrix stack and
* frees the array.
*/
static void
free_matrix_stack( struct matrix_stack *stack )
{
@ -694,6 +799,13 @@ free_matrix_stack( struct matrix_stack *stack )
/**
* \brief Allocate and initialize a shared context state structure.
*
* \return pointer to a gl_shared_state structure on success, or NULL on
* failure.
*
* Initializes the display list, texture objects and vertex programs hash
* tables, allocates the texture objects. If it runs out of memory, frees
* everything already allocated before returing NULL.
*/
static struct gl_shared_state *
alloc_shared_state( void )
@ -775,6 +887,15 @@ alloc_shared_state( void )
/**
* \brief Deallocate a shared state context and all children structures.
*
* \param ctx GL context.
* \param ss shared state pointer.
*
* Frees the display lists, the texture objects (calling the driver texture
* deletion callback to free its private data) and the vertex programs, as well
* as their hash tables.
*
* \sa alloc_shared_state().
*/
static void
free_shared_state( GLcontext *ctx, struct gl_shared_state *ss )
@ -818,9 +939,11 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss )
}
/**
* \brief Initialize the n-th light.
* \brief Initialize the n-th light data structure.
*
* Note that the defaults for light 0 are different than the other lights.
* \param l pointer to the gl_light structure to be initialized.
* \param n number of the light.
* \note The defaults for light 0 are different than the other lights.
*/
static void
init_light( struct gl_light *l, GLuint n )
@ -848,6 +971,11 @@ init_light( struct gl_light *l, GLuint n )
l->Enabled = GL_FALSE;
}
/**
* \brief Initialize the light model data structure.
*
* \param lm pointer to the gl_lightmodel structure to be initialized.
*/
static void
init_lightmodel( struct gl_lightmodel *lm )
{
@ -857,6 +985,11 @@ init_lightmodel( struct gl_lightmodel *lm )
lm->ColorControl = GL_SINGLE_COLOR;
}
/**
* \brief Initalize the material data structure.
*
* \param m pointer to the gl_material structure to be initialized.
*/
static void
init_material( struct gl_material *m )
{
@ -870,6 +1003,12 @@ init_material( struct gl_material *m )
m->SpecularIndex = 1;
}
/**
* \brief Initalize a texture unit.
*
* \param ctx GL context.
* \param unit texture unit number to be initialized.
*/
static void
init_texture_unit( GLcontext *ctx, GLuint unit )
{
@ -961,7 +1100,12 @@ init_2d_map( struct gl_2d_map *map, int n, const float *initial )
}
/**
* \brief Initialize the attribute groups in a GLcontext.
* \brief Initialize the attribute groups in a GL context.
*
* \param ctx GL context.
*
* Initializes all the attributes, calling the respective <c>init*</c>
* functions for the more complex data structures.
*/
static void
init_attrib_groups( GLcontext *ctx )
@ -1563,10 +1707,10 @@ init_attrib_groups( GLcontext *ctx )
/**
* \brief Allocate the proxy textures.
*
* If we run out of memory part way through the allocations clean up and return
* GL_FALSE.
*
* \return GL_TRUE on success, or GL_FALSE on failure
*
* If run out of memory part way through the allocations, clean up and return
* GL_FALSE.
*/
static GLboolean
alloc_proxy_textures( GLcontext *ctx )
@ -1658,6 +1802,14 @@ alloc_proxy_textures( GLcontext *ctx )
}
}
/**
* \brief Set the debugging flags.
*
* \param debug debug string
*
* If compiled with debugging support then search for keywords in \p debug and
* enables the verbose debug output of the respective feature.
*/
static void add_debug_flags( const char *debug )
{
#ifdef MESA_DEBUG
@ -1700,6 +1852,17 @@ static void add_debug_flags( const char *debug )
*
* This includes allocating all the other structs and arrays which hang off of
* the context by pointers.
*
* \param ctx GL context.
*
* \sa _mesa_create_context() for the remaining parameter description.
*
* Performs the imports and exports callback tables initialzation, and
* miscellaenuos one-time initializations. If no shared context is supplied one
* is allocated, and increase its reference count. Setups the GL API dispatch
* tables. Initialize the TNL module. Sets the maximum Z buffer depth.
* Finally queries the \c MESA_DEBUG and \c MESA_VERBOSE environment variables
* for debug flags.
*/
GLboolean
_mesa_initialize_context( GLcontext *ctx,
@ -1973,7 +2136,9 @@ _mesa_create_context( const GLvisual *visual,
/**
* \brief Free the data associated with the given context.
*
* But don't free() the GLcontext struct itself!
* But doesn't free the GLcontext struct itself.
*
* \sa _mesa_initialize_context() and init_attrib_groups().
*/
void
_mesa_free_context_data( GLcontext *ctx )
@ -2089,6 +2254,10 @@ _mesa_free_context_data( GLcontext *ctx )
/**
* \brief Destroy a GLcontext structure.
*
* \param ctx GL context.
*
* Calls _mesa_free_context_data() and free the structure.
*/
void
_mesa_destroy_context( GLcontext *ctx )
@ -2105,6 +2274,11 @@ _mesa_destroy_context( GLcontext *ctx )
* \param src source context
* \param dst destination context
* \param mask bitwise OR of GL_*_BIT flags
*
* According to the bits specified in \p mask, copies the corresponding
* attributes from \p src into \dst. For many of the attributes a simple \c
* memcpy is not enough due to the existence of internal pointers in their data
* structures.
*/
void
_mesa_copy_context( const GLcontext *src, GLcontext *dst, GLuint mask )
@ -2213,6 +2387,9 @@ _mesa_copy_context( const GLcontext *src, GLcontext *dst, GLuint mask )
dst->NewState = _NEW_ALL;
}
/**
* \brief Print information about this Mesa version and build options.
*/
static void print_info( void )
{
_mesa_debug(NULL, "Mesa GL_VERSION = %s\n",
@ -2242,6 +2419,11 @@ static void print_info( void )
/**
* \brief Set the current context, binding the given frame buffer to the context.
*
* \param newCtx new GL context.
* \param buffer framebuffer.
*
* Calls _mesa_make_current2() with \p buffer as read and write framebuffer.
*/
void
_mesa_make_current( GLcontext *newCtx, GLframebuffer *buffer )
@ -2249,10 +2431,24 @@ _mesa_make_current( GLcontext *newCtx, GLframebuffer *buffer )
_mesa_make_current2( newCtx, buffer, buffer );
}
/**
* \brief Bind the given context to the given draw-buffer and read-buffer and
* make it the current context for this thread.
*
* \param newCtx new GL context. If NULL then there will be no current GL
* context.
* \param drawBuffer draw framebuffer.
* \param readBuffer read framebuffer.
*
* Check that the context's and framebuffer's visuals are compatible, returning
* imediatly otherwise. Sets the glapi current context via
* _glapi_set_context(). If \p newCtx is not NULL, associates \p drawBuffer and
* \p readBuffer with it and calls dd_function_table::ResizeBuffers if the buffers size has changed.
* Calls dd_function_table::MakeCurrent callback if defined.
*
* When a context is bound by the first time and the \c MESA_INFO environment
* variable is set it calls print_info() as an aid for remote user
* troubleshooting.
*/
void
_mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
@ -2354,10 +2550,12 @@ _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
}
/**
* \brief Return current context handle for the calling thread.
* \brief Get current context for the calling thread.
*
* This isn't the fastest way to get the current context.
* If you need speed, see the GET_CURRENT_CONTEXT() macro in context.h
* \return pointer to the current GL context.
*
* Calls _glapi_get_context(). This isn't the fastest way to get the current
* context. If you need speed, see the GET_CURRENT_CONTEXT macro in context.h.
*/
GLcontext *
_mesa_get_current_context( void )
@ -2366,10 +2564,16 @@ _mesa_get_current_context( void )
}
/**
* \brief Return pointer to this context's current API dispatch table.
* \brief Get context's current API dispatch table.
*
* It'll either be the immediate-mode execute dispatcher or the display list
* compile dispatcher.
*
* \param ctx GL context.
*
* \return pointer to dispatch_table.
*
* Simply returns __GLcontextRec::CurrentDispatch.
*/
struct _glapi_table *
_mesa_get_dispatch(GLcontext *ctx)
@ -2386,8 +2590,15 @@ _mesa_get_dispatch(GLcontext *ctx)
/*@{*/
/**
* Record the given error code and call the driver's Error function if defined.
* \brief Record an error.
*
* \param ctx GL context.
* \param error error code.
*
* Records the given error code and call the driver's dd_function_table::Error
* function if defined.
*
* \sa
* This is called via _mesa_error().
*/
void
@ -2406,6 +2617,12 @@ _mesa_record_error( GLcontext *ctx, GLenum error )
}
}
/**
* \brief Execute glFinish().
*
* Calls the ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the
* dd_function_table::Finish driver callback, if not NULL.
*/
void
_mesa_Finish( void )
{
@ -2416,6 +2633,12 @@ _mesa_Finish( void )
}
}
/**
* \brief Execute glFlush().
*
* Calls the ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the
* dd_function_table::Flush driver callback, if not NULL.
*/
void
_mesa_Flush( void )
{

11
src/mesa/main/dd.h
View file

@ -27,7 +27,7 @@
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
/* $Id: dd.h,v 1.74.6.1 2003/03/02 00:27:33 jrfonseca Exp $ */
/* $Id: dd.h,v 1.74.6.2 2003/03/09 10:52:20 jrfonseca Exp $ */
#ifndef DD_INCLUDED
@ -74,10 +74,11 @@ struct dd_function_table {
/**
* \brief Clear the color/depth/stencil/accum buffer(s).
*
* \p mask is a bitmask of the DD_*_BIT values defined above that indicates
* \param mask a bitmask of the DD_*_BIT values defined above that indicates
* which buffers need to be cleared.
* If \p all is true then clear the whole buffer, else clear only the
* region defined by \c (x, y, width, height).
* \param all if true then clear the whole buffer, else clear only the
* region defined by <c>(x, y, width, height)</c>.
*
* This function must obey the glColorMask(), glIndexMask() and glStencilMask()
* settings!
* Software Mesa can do masked clears if the device driver can't.
@ -580,7 +581,7 @@ struct dd_function_table {
void (*DepthFunc)(GLcontext *ctx, GLenum func);
void (*DepthMask)(GLcontext *ctx, GLboolean flag);
void (*DepthRange)(GLcontext *ctx, GLclampd nearval, GLclampd farval);
void (*Enable)(GLcontext* ctx, GLenum cap, GLboolean state);
void (*Enable)(GLcontext *ctx, GLenum cap, GLboolean state);
void (*Fogfv)(GLcontext *ctx, GLenum pname, const GLfloat *params);
void (*Hint)(GLcontext *ctx, GLenum target, GLenum mode);
void (*IndexMask)(GLcontext *ctx, GLuint mask);

10
src/mesa/main/dlist.c
View file

@ -27,7 +27,7 @@
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
/* $Id: dlist.c,v 1.100.4.1 2003/03/02 00:27:34 jrfonseca Exp $ */
/* $Id: dlist.c,v 1.100.4.2 2003/03/09 10:52:20 jrfonseca Exp $ */
#include "glheader.h"
#include "imports.h"
@ -315,7 +315,7 @@ static Node *make_empty_list( void )
/*
* Destroy all nodes in a display list.
* Input: list - display list number
* \param list - display list number
*/
void _mesa_destroy_list( GLcontext *ctx, GLuint list )
{
@ -657,9 +657,9 @@ void _mesa_init_lists( void )
/*
* Allocate space for a display list instruction.
* Input: opcode - type of instruction
* \param opcode - type of instruction
* argcount - size in bytes of data required.
* Return: pointer to the usable data area (not including the internal
* \return pointer to the usable data area (not including the internal
* opcode).
*/
void *
@ -4193,7 +4193,7 @@ islist(GLcontext *ctx, GLuint list)
* Execute a display list. Note that the ListBase offset must have already
* been added before calling this function. I.e. the list argument is
* the absolute list number, not relative to ListBase.
* Input: list - display list number
* \param list - display list number
*/
static void
execute_list( GLcontext *ctx, GLuint list )

10
src/mesa/main/eval.c
View file

@ -1,4 +1,4 @@
/* $Id: eval.c,v 1.24 2002/10/24 23:57:20 brianp Exp $ */
/* $Id: eval.c,v 1.24.4.1 2003/03/09 10:52:20 jrfonseca Exp $ */
/*
* Mesa 3-D graphics library
@ -202,8 +202,8 @@ get_2d_map( GLcontext *ctx, GLenum target )
/*
* Copy 1-parametric evaluator control points from user-specified
* memory space to a buffer of contiguous control points.
* Input: see glMap1f for details
* Return: pointer to buffer of contiguous control points or NULL if out
* \param see glMap1f for details
* \return pointer to buffer of contiguous control points or NULL if out
* of memory.
*/
GLfloat *_mesa_copy_map_points1f( GLenum target, GLint ustride, GLint uorder,
@ -257,8 +257,8 @@ GLfloat *_mesa_copy_map_points1d( GLenum target, GLint ustride, GLint uorder,
* Additional memory is allocated to be used by the horner and
* de Casteljau evaluation schemes.
*
* Input: see glMap2f for details
* Return: pointer to buffer of contiguous control points or NULL if out
* \param see glMap2f for details
* \return pointer to buffer of contiguous control points or NULL if out
* of memory.
*/
GLfloat *_mesa_copy_map_points2f( GLenum target,

10
src/mesa/main/image.c
View file

@ -1,4 +1,4 @@
/* $Id: image.c,v 1.69.4.1 2002/12/30 15:20:35 keithw Exp $ */
/* $Id: image.c,v 1.69.4.2 2003/03/09 10:52:20 jrfonseca Exp $ */
/*
* Mesa 3-D graphics library
@ -417,14 +417,14 @@ _mesa_is_legal_format_and_type( GLenum format, GLenum type )
/*
* Return the address of a pixel in an image (actually a volume).
* Pixel unpacking/packing parameters are observed according to 'packing'.
* Input: image - start of image data
* \param image - start of image data
* width, height - size of image
* format - image format
* type - pixel component type
* packing - the pixelstore attributes
* img - which image in the volume (0 for 1D or 2D images)
* row, column - location of pixel in the image
* Return: address of pixel at (image,row,column) in image or NULL if error.
* \return address of pixel at (image,row,column) in image or NULL if error.
*/
GLvoid *
_mesa_image_address( const struct gl_pixelstore_attrib *packing,
@ -1782,7 +1782,7 @@ _mesa_pack_float_rgba_span( GLcontext *ctx,
* Optionally apply the enabled pixel transfer ops.
* Pack into memory using the given packing params struct.
* This is used by glReadPixels and glGetTexImage?D()
* Input: ctx - the context
* \param ctx - the context
* n - number of pixels in the span
* rgba - the pixels
* format - dest packing format
@ -2539,7 +2539,7 @@ extract_float_rgba(GLuint n, GLfloat rgba[][4],
* the pixel unpacking parameters.
* Return GLubyte values in the specified dest image format.
* This is (or will be) used by glDrawPixels and glTexImage?D().
* Input: ctx - the context
* \param ctx - the context
* n - number of pixels in the span
* dstFormat - format of destination color array
* dest - the destination color array

6
src/mesa/main/imports.c
View file

@ -1,4 +1,4 @@
/* $Id: imports.c,v 1.25 2002/10/30 20:40:46 brianp Exp $ */
/* $Id: imports.c,v 1.25.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
/*
* Mesa 3-D graphics library
@ -443,7 +443,7 @@ _mesa_problem( const GLcontext *ctx, const char *s )
/*
* If in debug mode, print error message to stdout.
* Also, record the error code by calling _mesa_record_error().
* Input: ctx - the GL context
* \param ctx - the GL context
* error - the error value
* fmtString - printf-style format string, followed by optional args
*/
@ -642,7 +642,7 @@ default_GetDrawablePrivate(__GLcontext *gc)
/*
* Initialize a __GLimports object to point to the functions in
* this file. This is to be called from device drivers.
* Input: imports - the object to init
* \param imports - the object to init
* driverCtx - pointer to device driver-specific data
*/
void

12
src/mesa/main/rastpos.c
View file

@ -1,4 +1,4 @@
/* $Id: rastpos.c,v 1.39 2002/10/24 23:57:21 brianp Exp $ */
/* $Id: rastpos.c,v 1.39.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
/*
* Mesa 3-D graphics library
@ -44,8 +44,8 @@
/*
* Clip a point against the view volume.
* Input: v - vertex-vector describing the point to clip
* Return: 0 = outside view volume
* \param v - vertex-vector describing the point to clip
* \return 0 = outside view volume
* 1 = inside view volume
*/
static GLuint
@ -78,8 +78,8 @@ viewclip_point_z( const GLfloat v[] )
/*
* Clip a point against the user clipping planes.
* Input: v - vertex-vector describing the point to clip.
* Return: 0 = point was clipped
* \param v - vertex-vector describing the point to clip.
* \return 0 = point was clipped
* 1 = point not clipped
*/
static GLuint
@ -106,7 +106,7 @@ userclip_point( GLcontext* ctx, const GLfloat v[] )
/* This has been split off to allow the normal shade routines to
* get a little closer to the vertex buffer, and to use the
* GLvector objects directly.
* Input: ctx - the context
* \param ctx - the context
* vertex - vertex location
* normal - normal vector
* Output: Rcolor - returned color

14
src/mesa/main/teximage.c
View file

@ -1,4 +1,4 @@
/* $Id: teximage.c,v 1.124 2002/10/30 19:58:58 brianp Exp $ */
/* $Id: teximage.c,v 1.124.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
/*
* Mesa 3-D graphics library
@ -757,9 +757,9 @@ _mesa_init_teximage_fields(GLcontext *ctx, GLenum target,
/*
* Test glTexImage[123]D() parameters for errors.
* Input:
* \param
* dimensions - must be 1 or 2 or 3
* Return: GL_TRUE = an error was detected, GL_FALSE = no errors
* \return GL_TRUE = an error was detected, GL_FALSE = no errors
*/
static GLboolean
texture_error_check( GLcontext *ctx, GLenum target,
@ -1046,9 +1046,9 @@ texture_error_check( GLcontext *ctx, GLenum target,
/*
* Test glTexSubImage[123]D() parameters for errors.
* Input:
* \param
* dimensions - must be 1 or 2 or 3
* Return: GL_TRUE = an error was detected, GL_FALSE = no errors
* \return GL_TRUE = an error was detected, GL_FALSE = no errors
*/
static GLboolean
subtexture_error_check( GLcontext *ctx, GLuint dimensions,
@ -1213,8 +1213,8 @@ 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 dimensions - must be 1 or 2 or 3
* \return GL_TRUE = an error was detected, GL_FALSE = no errors
*/
static GLboolean
copytexture_error_check( GLcontext *ctx, GLuint dimensions,

186
src/mesa/main/texobj.c
View file

@ -1,4 +1,7 @@
/* $Id: texobj.c,v 1.62 2002/10/24 23:57:21 brianp Exp $ */
/**
* \file texobj.c
* \brief Texture object functions.
*/
/*
* Mesa 3-D graphics library
@ -24,6 +27,8 @@
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
/* $Id: texobj.c,v 1.62.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
#include "glheader.h"
#include "colortab.h"
#include "context.h"
@ -37,16 +42,23 @@
#include "mtypes.h"
/*
* Allocate a new texture object and add it to the linked list of texture
* objects. If name>0 then also insert the new texture object into the hash
/**
* \brief Allocate a new texture object and add it to the linked list of
* texture objects.
*
* \param shared the shared GL state structure to contain the texture object
* \param name integer name for the texture object
* \param target either GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D,
* GL_TEXTURE_CUBE_MAP_ARB or GL_TEXTURE_RECTANGLE_NV. zero is ok for the sake
* of GenTextures()
*
* \return pointer to new texture object.
*
* Allocate and initalize a gl_texture_object structure, and insert in the
* shared state texture list while holding its mutex.
* If <c>name > 0</c> then also insert the new texture object into the hash
* table.
* Input: shared - the shared GL state structure to contain the texture object
* name - integer name for the texture object
* target - either GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D,
* GL_TEXTURE_CUBE_MAP_ARB or GL_TEXTURE_RECTANGLE_NV
* zero is ok for the sake of GenTextures()
* Return: pointer to new texture object
*
*/
struct gl_texture_object *
_mesa_alloc_texture_object( struct gl_shared_state *shared,
@ -112,12 +124,16 @@ _mesa_alloc_texture_object( struct gl_shared_state *shared,
return obj;
}
/*
* Deallocate a texture object struct and remove it from the given
/**
* \brief Deallocate a texture object struct and remove it from the given
* shared GL state.
* Input: shared - the shared GL state to which the object belongs
* t - the texture object to delete
*
* \param shared the shared GL state to which the object belongs.
* \param t the texture object to delete.
*
* Unlink the texture object from the shared state texture linked list while
* holding its lock. If the texture is a name number it's also removed from the
* hash table. Finally rees the texture images and the object itself.
*/
void _mesa_free_texture_object( struct gl_shared_state *shared,
struct gl_texture_object *t )
@ -168,9 +184,11 @@ void _mesa_free_texture_object( struct gl_shared_state *shared,
FREE( t );
}
/*
* Copy texture object state from one texture object to another.
/**
* \brief Copy texture object state from one texture object to another.
*
* \param dest destination texture object.
* \param src source texture object.
*/
void
_mesa_copy_texture_object( struct gl_texture_object *dest,
@ -206,8 +224,13 @@ _mesa_copy_texture_object( struct gl_texture_object *dest,
}
/*
* Report why a texture object is incomplete. (for debug only)
/**
* \brief Report why a texture object is incomplete.
*
* \param t texture object.
* \param why string describing why it's incomplete.
*
* \note For debug purposes only.
*/
#if 0
static void
@ -216,13 +239,21 @@ incomplete(const struct gl_texture_object *t, const char *why)
_mesa_printf("Texture Obj %d incomplete because: %s\n", t->Name, why);
}
#else
#define incomplete(a, b)
#define incomplete(t, why)
#endif
/*
* Examine a texture object to determine if it is complete.
* The t->Complete flag will be set to GL_TRUE or GL_FALSE accordingly.
/**
* \brief Examine a texture object to determine if it is complete.
*
* The gl_texture_object::Complete flag will be set to GL_TRUE or GL_FALSE
* accordingly.
*
* \param ctx GL context.
* \param t texture object.
*
* According to the texture target, verifies that each of the mipmaps is
* present and has the expected size.
*/
void
_mesa_test_texobj_completeness( const GLcontext *ctx,
@ -492,13 +523,26 @@ _mesa_test_texobj_completeness( const GLcontext *ctx,
}
}
/**
* \brief Texture name generation lock.
*
* Used by _mesa_GenTextures() to guarantee that the generation and allocation
* of texture IDs is atomic.
*/
_glthread_DECLARE_STATIC_MUTEX(GenTexturesLock);
/*
* Execute glGenTextures
*/
/**
* \brief Generate texture names.
*
* \param n number of texture names to be generated.
* \param texName an array in which will hold the generated texture names.
*
* \sa glGenTextures().
*
* While holdind the GenTexturesLock lock, calls _mesa_HashFindFreeKeyBlock()
* to find a block of free texture IDs which are stored in \p texName.
* Corresponding empty texture objects are also generated.
*/
void
_mesa_GenTextures( GLsizei n, GLuint *texName )
{
@ -537,10 +581,17 @@ _mesa_GenTextures( GLsizei n, GLuint *texName )
_glthread_UNLOCK_MUTEX(GenTexturesLock);
}
/*
* Execute glDeleteTextures
/**
* \brief Delete named textures.
*
* \param n number of textures to be deleted.
* \param texName array of textures names to be deleted.
*
* \sa glDeleteTextures().
*
* For each texture checks if its bound to any of the texture units, unbind it
* and decrementing the reference count if so. If the texture reference count
* is zero, delete its object.
*/
void
_mesa_DeleteTextures( GLsizei n, const GLuint *texName)
@ -616,10 +667,20 @@ _mesa_DeleteTextures( GLsizei n, const GLuint *texName)
}
}
/*
* Execute glBindTexture
/**
* \brief Bind a named texture to a texturing target.
*
* \param target texture target.
* \param texName texture name.
*
* \sa glBindTexture().
*
* Determines the old texture object bound and returns immediatly if rebinding
* the same texture. Get the current texture which is either a default texture
* if name is null, a named texture from the hash, or a new texture if the
* given texture name is new. Increments its reference count, binds it, and
* calls dd_driver_table::BindTexture. Decrements the old texture reference
* count and deletes it if it reaches zero.
*/
void
_mesa_BindTexture( GLenum target, GLuint texName )
@ -766,10 +827,17 @@ _mesa_BindTexture( GLenum target, GLuint texName )
}
}
/*
* Execute glPrioritizeTextures
/**
* \brief Set texture priorities.
*
* \param n number of textures.
* \param texName texture names.
* \param priorities corresponding texture priorities.
*
* \sa glPrioritizeTextures().
*
* Looksup each texture in the hash, clamps the corresponding priority between
* 0.0 and 1.0, and calls dd_driver_table::PrioritizeTexture.
*/
void
_mesa_PrioritizeTextures( GLsizei n, const GLuint *texName,
@ -802,10 +870,23 @@ _mesa_PrioritizeTextures( GLsizei n, const GLuint *texName,
ctx->NewState |= _NEW_TEXTURE;
}
/*
* Execute glAreTexturesResident
/**
* \brief See if textures are loaded in texture memory.
*
* \param n number of textures to query.
* \param texName array with the texture names.
* \param residences array which will hold the residence status.
*
* \return GL_TRUE if all textures are resident and \p residences is left unchanged,
*
* \sa glAreTexturesResident().
*
* Looksup each texture in the hash and calls
* dd_driver_table::IsTextureResident.
*
* \todo According to the OpenGL specification the \p residences contents
* should be left unchanged when all textures are resident, which is not done in
* this implementation.
*/
GLboolean
_mesa_AreTexturesResident(GLsizei n, const GLuint *texName,
@ -850,10 +931,17 @@ _mesa_AreTexturesResident(GLsizei n, const GLuint *texName,
return allResident;
}
/*
* Execute glIsTexture
/**
* \brief See if a name corresponds to a texture.
*
* \param texture texture name.
*
* \return GL_TRUE if texture name corresponds to a texture, or GL_FALSE
* otherwise.
*
* \sa glIsTexture().
*
* Calls _mesa_HashLookup().
*/
GLboolean
_mesa_IsTexture( GLuint texture )

6
src/mesa/main/texstore.c
View file

@ -1,4 +1,4 @@
/* $Id: texstore.c,v 1.47.4.1 2002/11/20 21:40:02 brianp Exp $ */
/* $Id: texstore.c,v 1.47.4.2 2003/03/09 10:52:21 jrfonseca Exp $ */
/*
* Mesa 3-D graphics library
@ -159,7 +159,7 @@ components_in_intformat( GLint format )
* apply pixel transfer ops into a temporary image buffer. Then,
* convert the temporary image into the special hardware format.
*
* Input:
* \param
* dimensions - 1, 2, or 3
* texDestFormat - GL_LUMINANCE, GL_INTENSITY, GL_LUMINANCE_ALPHA, GL_ALPHA,
* GL_RGB or GL_RGBA (the destination format)
@ -435,7 +435,7 @@ transfer_teximage(GLcontext *ctx, GLuint dimensions,
* Transfer a texture image from user space to <destAddr> applying all
* needed image transfer operations and storing the result in the format
* specified by <dstFormat>. <dstFormat> may be any format from texformat.h.
* Input:
* \param
* dimensions - 1, 2 or 3
* baseInternalFormat - base format of the internal texture format
* specified by the user. This is very important, see below.

4
src/mesa/main/texutil.c
View file

@ -1,4 +1,4 @@
/* $Id: texutil.c,v 1.34 2002/10/29 20:28:53 brianp Exp $ */
/* $Id: texutil.c,v 1.34.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
/*
* Mesa 3-D graphics library
@ -868,7 +868,7 @@ _mesa_convert_texsubimage1d( GLint mesaFormat,
* with the _mesa_transfer_teximage() function. That function will also
* do image transfer operations such as scale/bias and convolution.
*
* Input:
* \param
* mesaFormat - one of the MESA_FORMAT_* values from texformat.h
* xoffset, yoffset - position in dest image to put data
* width, height - incoming image size, also size of dest region.