From b77ca3d2b767b36e341300dfdce7aa2a6f50246b Mon Sep 17 00:00:00 2001 From: Jose Fonseca Date: Sat, 22 Feb 2003 21:27:17 +0000 Subject: [PATCH] More documentation - now almost complete. --- doxygen/radeon_subset.doxy | 2 + src/mesa/drivers/common/mm.c | 99 ++++++- src/mesa/drivers/common/mm.h | 69 ++--- src/mesa/drivers/dri/common/mm.c | 99 ++++++- src/mesa/drivers/dri/common/mm.h | 69 ++--- src/mesa/drivers/dri/radeon/radeon_context.h | 6 +- .../drivers/dri/radeon/radeon_subset_vtx.c | 242 ++++++++++++++++-- 7 files changed, 492 insertions(+), 94 deletions(-) diff --git a/doxygen/radeon_subset.doxy b/doxygen/radeon_subset.doxy index 4b46999282f..60103cb9b4f 100644 --- a/doxygen/radeon_subset.doxy +++ b/doxygen/radeon_subset.doxy @@ -53,6 +53,7 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- INPUT = \ ../src/drv/common/mm.c \ + ../src/drv/common/mm.h \ ../src/drv/radeon/radeon_context.c \ ../src/drv/radeon/radeon_context.h \ ../src/drv/radeon/radeon_ioctl.c \ @@ -64,6 +65,7 @@ INPUT = \ ../src/drv/radeon/radeon_state.c \ ../src/drv/radeon/radeon_state.h \ ../src/drv/radeon/radeon_state_init.c \ + ../src/drv/radeon/radeon_subset.h \ ../src/drv/radeon/radeon_subset_bitmap.c \ ../src/drv/radeon/radeon_subset_readpix.c \ ../src/drv/radeon/radeon_subset_select.c \ diff --git a/src/mesa/drivers/common/mm.c b/src/mesa/drivers/common/mm.c index 602f6d5be0a..a2b8e4fc868 100644 --- a/src/mesa/drivers/common/mm.c +++ b/src/mesa/drivers/common/mm.c @@ -1,5 +1,9 @@ +/** + * \file mm.c + * \brief Memory management. + */ + /* - * GLX Hardware Device Driver common code * Copyright (C) 1999 Keith Whitwell * * Permission is hereby granted, free of charge, to any person obtaining a @@ -19,20 +23,29 @@ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * */ + /* $XFree86: xc/lib/GL/mesa/src/drv/common/mm.c,v 1.3 2001/08/18 02:51:03 dawes Exp $ */ #include #include #include "mm.h" -#include "hwlog.h" /* KW: I don't know who the author of this code is, but it wasn't me * despite what the copyright says... */ +/** + * \brief Dump memmory information about the heap. + * + * \param heap memmory heap. + * + * \note For debugging purposes. + * + * \internal + * Prints the offset, size and flags for each block. + */ void mmDumpMemInfo( memHeap_t *heap ) { TMemBlock *p; @@ -52,6 +65,19 @@ void mmDumpMemInfo( memHeap_t *heap ) fprintf(stderr, "End of memory blocks\n"); } + +/** + * \brief Memmory heap initialization. + * + * \param offset offset in bytes. + * \param size total size in bytes + * + * \return a heap pointer on success, or NULL on failure. + * + * \internal + * Allocate a mem_block_t structure and initialize it with the heap + * information. + */ memHeap_t *mmInit(int ofs, int size) { @@ -71,6 +97,22 @@ memHeap_t *mmInit(int ofs, } +/** + * \brief Slice a free memmory block. + * + * \param p memmory block. + * \param startofs start offset to slice. + * \param size of the slice. + * \param reserved flag. + * \param alignment block alignment. + * + * \return pointer to the slice block on success, or NULL on failure. + * + * \internal + * Creates a new block to the left with the remaining memory before the slice + * start (if any), a block to the right with the remaing memmory after the + * slice (if any), and the reduced memmory block itself as the slice. + */ static TMemBlock* SliceBlock(TMemBlock *p, int startofs, int size, int reserved, int alignment) @@ -111,6 +153,26 @@ static TMemBlock* SliceBlock(TMemBlock *p, return p; } + +/** + * \brief Allocate a memmory block. + * + * Allocate \p size bytes with \p 2^align2 bytes alignment, + * restrict the search to free memory after \p startSearch. + * Depth and back buffers should be in different 4MB banks + * to get better page hits if possible. + * + * \param heap memmory heap. + * \param size size to allocate in bytes. + * \param align2 base 2 log of the alignment in bytes. + * \param startSearch linear offset from start of the heap to begin the search. + * + * \return pointer to the allocated block on success, or NULL on failure. + * + * \internal + * Walks through the free blocks on the heap and if it finds one above + * startSearch and large enough slices it via SliceBlock() and returns the result. + */ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch) { int mask,startofs,endofs; @@ -140,6 +202,17 @@ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch) return p; } + +/** + * \brief Join two successive free memmory blocks. + * + * \param p pointer to first memmory block. + * + * \return 1 on success, or 0 on failure. + * + * \internal + * Adds the size of the second block to the first and frees its data structure. + */ static __inline__ int Join2Blocks(TMemBlock *p) { if (p->free && p->next && p->next->free) { @@ -152,6 +225,18 @@ static __inline__ int Join2Blocks(TMemBlock *p) return 0; } + +/** + * \brief Free a memmory block. + * + * \param pointer to a block. + * + * \return 0 on success, or -1 on failure. + * + * \internal + * Search the given block on the heap, mark it as free and attempt to join it + * with the next one via Join2Blocks(). + */ int mmFreeMem(PMemBlock b) { TMemBlock *p,*prev; @@ -185,6 +270,14 @@ int mmFreeMem(PMemBlock b) } +/** + * \brief Destroy the memmory heap. + * + * \param heap memmory heap. + * + * \internal + * Frees each block in the heap. + */ void mmDestroy(memHeap_t *heap) { TMemBlock *p,*q; diff --git a/src/mesa/drivers/common/mm.h b/src/mesa/drivers/common/mm.h index d52871d39f3..8d558d55b63 100644 --- a/src/mesa/drivers/common/mm.h +++ b/src/mesa/drivers/common/mm.h @@ -1,5 +1,9 @@ +/** + * \file mm.h + * \brief Memory management. + */ + /* - * GLX Hardware Device Driver common code * Copyright (C) 1999 Keith Whitwell * * Permission is hereby granted, free of charge, to any person obtaining a @@ -25,58 +29,57 @@ #ifndef MM_INC #define MM_INC +/** + * \brief Memmory block/heap. + */ struct mem_block_t { - struct mem_block_t *next; - struct mem_block_t *heap; - int ofs,size; - int align; - int free:1; - int reserved:1; + struct mem_block_t *next; /**< \brief pointer to next block in the heap */ + struct mem_block_t *heap; /**< \brief pointer to the heap (first block) */ + int ofs; /**< \brief offset */ + int size; /**< \brief size */ + int align; /**< \brief alignment */ + int free:1; /**< \brief free flag */ + int reserved:1; /**< \brief reserved flag */ }; + +/** + * \brief Memmory block. + */ typedef struct mem_block_t TMemBlock; + +/** + * \brief Memmory block pointer. + */ typedef struct mem_block_t *PMemBlock; -/* a heap is just the first block in a chain */ +/** + * \brief Memmory heap. + * + * \note A heap is just the first block in a chain + */ typedef struct mem_block_t memHeap_t; +/** + * \brief Get Memmory block size. + */ static __inline__ int mmBlockSize(PMemBlock b) { return b->size; } +/** + * \brief Get Memmory block offset. + */ static __inline__ int mmOffset(PMemBlock b) { return b->ofs; } -/* - * input: total size in bytes - * return: a heap pointer if OK, NULL if error - */ memHeap_t *mmInit( int ofs, int size ); -/* - * Allocate 'size' bytes with 2^align2 bytes alignment, - * restrict the search to free memory after 'startSearch' - * depth and back buffers should be in different 4mb banks - * to get better page hits if possible - * input: size = size of block - * align2 = 2^align2 bytes alignment - * startSearch = linear offset from start of heap to begin search - * return: pointer to the allocated block, 0 if error - */ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch ); -/* - * Free block starts at offset - * input: pointer to a block - * return: 0 if OK, -1 if error - */ int mmFreeMem( PMemBlock b ); -/* - * destroy MM - */ -void mmDestroy( memHeap_t *mmInit ); +void mmDestroy( memHeap_t *heap ); -/* For debuging purpose. */ -void mmDumpMemInfo( memHeap_t *mmInit ); +void mmDumpMemInfo( memHeap_t *heap ); #endif diff --git a/src/mesa/drivers/dri/common/mm.c b/src/mesa/drivers/dri/common/mm.c index 602f6d5be0a..a2b8e4fc868 100644 --- a/src/mesa/drivers/dri/common/mm.c +++ b/src/mesa/drivers/dri/common/mm.c @@ -1,5 +1,9 @@ +/** + * \file mm.c + * \brief Memory management. + */ + /* - * GLX Hardware Device Driver common code * Copyright (C) 1999 Keith Whitwell * * Permission is hereby granted, free of charge, to any person obtaining a @@ -19,20 +23,29 @@ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * */ + /* $XFree86: xc/lib/GL/mesa/src/drv/common/mm.c,v 1.3 2001/08/18 02:51:03 dawes Exp $ */ #include #include #include "mm.h" -#include "hwlog.h" /* KW: I don't know who the author of this code is, but it wasn't me * despite what the copyright says... */ +/** + * \brief Dump memmory information about the heap. + * + * \param heap memmory heap. + * + * \note For debugging purposes. + * + * \internal + * Prints the offset, size and flags for each block. + */ void mmDumpMemInfo( memHeap_t *heap ) { TMemBlock *p; @@ -52,6 +65,19 @@ void mmDumpMemInfo( memHeap_t *heap ) fprintf(stderr, "End of memory blocks\n"); } + +/** + * \brief Memmory heap initialization. + * + * \param offset offset in bytes. + * \param size total size in bytes + * + * \return a heap pointer on success, or NULL on failure. + * + * \internal + * Allocate a mem_block_t structure and initialize it with the heap + * information. + */ memHeap_t *mmInit(int ofs, int size) { @@ -71,6 +97,22 @@ memHeap_t *mmInit(int ofs, } +/** + * \brief Slice a free memmory block. + * + * \param p memmory block. + * \param startofs start offset to slice. + * \param size of the slice. + * \param reserved flag. + * \param alignment block alignment. + * + * \return pointer to the slice block on success, or NULL on failure. + * + * \internal + * Creates a new block to the left with the remaining memory before the slice + * start (if any), a block to the right with the remaing memmory after the + * slice (if any), and the reduced memmory block itself as the slice. + */ static TMemBlock* SliceBlock(TMemBlock *p, int startofs, int size, int reserved, int alignment) @@ -111,6 +153,26 @@ static TMemBlock* SliceBlock(TMemBlock *p, return p; } + +/** + * \brief Allocate a memmory block. + * + * Allocate \p size bytes with \p 2^align2 bytes alignment, + * restrict the search to free memory after \p startSearch. + * Depth and back buffers should be in different 4MB banks + * to get better page hits if possible. + * + * \param heap memmory heap. + * \param size size to allocate in bytes. + * \param align2 base 2 log of the alignment in bytes. + * \param startSearch linear offset from start of the heap to begin the search. + * + * \return pointer to the allocated block on success, or NULL on failure. + * + * \internal + * Walks through the free blocks on the heap and if it finds one above + * startSearch and large enough slices it via SliceBlock() and returns the result. + */ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch) { int mask,startofs,endofs; @@ -140,6 +202,17 @@ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch) return p; } + +/** + * \brief Join two successive free memmory blocks. + * + * \param p pointer to first memmory block. + * + * \return 1 on success, or 0 on failure. + * + * \internal + * Adds the size of the second block to the first and frees its data structure. + */ static __inline__ int Join2Blocks(TMemBlock *p) { if (p->free && p->next && p->next->free) { @@ -152,6 +225,18 @@ static __inline__ int Join2Blocks(TMemBlock *p) return 0; } + +/** + * \brief Free a memmory block. + * + * \param pointer to a block. + * + * \return 0 on success, or -1 on failure. + * + * \internal + * Search the given block on the heap, mark it as free and attempt to join it + * with the next one via Join2Blocks(). + */ int mmFreeMem(PMemBlock b) { TMemBlock *p,*prev; @@ -185,6 +270,14 @@ int mmFreeMem(PMemBlock b) } +/** + * \brief Destroy the memmory heap. + * + * \param heap memmory heap. + * + * \internal + * Frees each block in the heap. + */ void mmDestroy(memHeap_t *heap) { TMemBlock *p,*q; diff --git a/src/mesa/drivers/dri/common/mm.h b/src/mesa/drivers/dri/common/mm.h index d52871d39f3..8d558d55b63 100644 --- a/src/mesa/drivers/dri/common/mm.h +++ b/src/mesa/drivers/dri/common/mm.h @@ -1,5 +1,9 @@ +/** + * \file mm.h + * \brief Memory management. + */ + /* - * GLX Hardware Device Driver common code * Copyright (C) 1999 Keith Whitwell * * Permission is hereby granted, free of charge, to any person obtaining a @@ -25,58 +29,57 @@ #ifndef MM_INC #define MM_INC +/** + * \brief Memmory block/heap. + */ struct mem_block_t { - struct mem_block_t *next; - struct mem_block_t *heap; - int ofs,size; - int align; - int free:1; - int reserved:1; + struct mem_block_t *next; /**< \brief pointer to next block in the heap */ + struct mem_block_t *heap; /**< \brief pointer to the heap (first block) */ + int ofs; /**< \brief offset */ + int size; /**< \brief size */ + int align; /**< \brief alignment */ + int free:1; /**< \brief free flag */ + int reserved:1; /**< \brief reserved flag */ }; + +/** + * \brief Memmory block. + */ typedef struct mem_block_t TMemBlock; + +/** + * \brief Memmory block pointer. + */ typedef struct mem_block_t *PMemBlock; -/* a heap is just the first block in a chain */ +/** + * \brief Memmory heap. + * + * \note A heap is just the first block in a chain + */ typedef struct mem_block_t memHeap_t; +/** + * \brief Get Memmory block size. + */ static __inline__ int mmBlockSize(PMemBlock b) { return b->size; } +/** + * \brief Get Memmory block offset. + */ static __inline__ int mmOffset(PMemBlock b) { return b->ofs; } -/* - * input: total size in bytes - * return: a heap pointer if OK, NULL if error - */ memHeap_t *mmInit( int ofs, int size ); -/* - * Allocate 'size' bytes with 2^align2 bytes alignment, - * restrict the search to free memory after 'startSearch' - * depth and back buffers should be in different 4mb banks - * to get better page hits if possible - * input: size = size of block - * align2 = 2^align2 bytes alignment - * startSearch = linear offset from start of heap to begin search - * return: pointer to the allocated block, 0 if error - */ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch ); -/* - * Free block starts at offset - * input: pointer to a block - * return: 0 if OK, -1 if error - */ int mmFreeMem( PMemBlock b ); -/* - * destroy MM - */ -void mmDestroy( memHeap_t *mmInit ); +void mmDestroy( memHeap_t *heap ); -/* For debuging purpose. */ -void mmDumpMemInfo( memHeap_t *mmInit ); +void mmDumpMemInfo( memHeap_t *heap ); #endif diff --git a/src/mesa/drivers/dri/radeon/radeon_context.h b/src/mesa/drivers/dri/radeon/radeon_context.h index 550e91d3bdf..b1dcf8b321e 100644 --- a/src/mesa/drivers/dri/radeon/radeon_context.h +++ b/src/mesa/drivers/dri/radeon/radeon_context.h @@ -608,9 +608,9 @@ struct radeon_context { * \name Vertex buffers */ /*@{*/ - struct radeon_ioctl ioctl; - struct radeon_dma dma; - struct radeon_store store; /**< \ brief Command buffer */ + struct radeon_ioctl ioctl; + struct radeon_dma dma; /**< \brief DMA information */ + struct radeon_store store; /**< \brief Command buffer */ /*@}*/ /** diff --git a/src/mesa/drivers/dri/radeon/radeon_subset_vtx.c b/src/mesa/drivers/dri/radeon/radeon_subset_vtx.c index 0cbf8dab416..bfb17377123 100644 --- a/src/mesa/drivers/dri/radeon/radeon_subset_vtx.c +++ b/src/mesa/drivers/dri/radeon/radeon_subset_vtx.c @@ -117,7 +117,7 @@ static struct vb_t { GLenum prim; /**< \brief primitive */ GLuint vertex_format; /**< \brief vertex format */ GLint vertex_size; /**< \brief vertex size */ - GLboolean recheck; + GLboolean recheck; /**< \brief set if it's needed to validate this information */ /*@}*/ } vb; @@ -151,7 +151,8 @@ static struct prims_t { * * \param rmesa Radeon context. * - * Truncates any redundant vertices off the end of the buffer and + * Truncates any redundant vertices off the end of the buffer, emit the + * remainging vertices and advances the current DMA region. */ static void finish_prim( radeonContextPtr rmesa ) { @@ -178,6 +179,15 @@ static void finish_prim( radeonContextPtr rmesa ) } +/** + * \brief Copy a vertex from the current DMA region + * + * \param rmesa Radeon context. + * \param n vertice index relative to the current DMA region. + * \param dst destination pointer. + * + * Used internally by copy_dma_verts(). + */ static void copy_vertex( radeonContextPtr rmesa, GLuint n, GLfloat *dst ) { GLuint i; @@ -190,6 +200,17 @@ static void copy_vertex( radeonContextPtr rmesa, GLuint n, GLfloat *dst ) } +/** + * \brief Copy last vertices from the current DMA buffer to resume in a new buffer. + * + * \param rmesa Radeon context. + * \param tmp destination buffer. + * + * Takes from the current DMA buffer the last vertices necessary to resume in a + * new buffer, according to the current primitive. Uses internally + * copy_vertex() for the vertex copying. + * + */ static GLuint copy_dma_verts( radeonContextPtr rmesa, GLfloat (*tmp)[MAX_VERTEX_DWORDS] ) { @@ -242,6 +263,13 @@ static GLuint copy_dma_verts( radeonContextPtr rmesa, static void notify_wrap_buffer( void ); +/** + * \brief Resets the vertex buffer notifycation mechanism. + * + * Fills in vb_t::stack with the values from the current DMA region in + * radeon_dma::current and sets points the notification callback to + * notify_wrap_buffer(). + */ static void reset_notify( void ) { radeonContextPtr rmesa = RADEON_CONTEXT( vb.context ); @@ -255,6 +283,13 @@ static void reset_notify( void ) vb.stack[0].notify = notify_wrap_buffer; } +/** + * \brief Full buffer notification callback. + * + * Makes a copy of the necessary vertices of the current buffer via + * copy_dma_verts(), gets and resets new buffer via radeon and reemits the + * saved vertices. + */ static void notify_wrap_buffer( void ) { GLcontext *ctx = vb.context; @@ -286,6 +321,7 @@ static void notify_wrap_buffer( void ) } } + static void notify_noop( void ) { vb.stack[0].dmaptr = (int *)vb.vertex; @@ -293,11 +329,30 @@ static void notify_noop( void ) vb.stack[0].vertspace = 1; } +/** + * \brief Pop the notification mechanism stack. + * + * Simply copy the second stack array element into the first. + * + * \sa vb_t::stack and push_notify(). + */ static void pop_notify( void ) { vb.stack[0] = vb.stack[1]; } +/** + * \brief Push the notification mechanism stack. + * + * \param notify new notify callback for the stack head. + * \param space space available for vertices in \p store. + * \param store buffer where to store the vertices. + * + * Copy the second stack array element into the first and makes the stack head + * use the given resources. + * + * \sa vb_t::stack and pop_notify(). + */ static void push_notify( void (*notify)( void ), int space, union vertex_dword *store ) { @@ -310,7 +365,12 @@ static void push_notify( void (*notify)( void ), int space, /** - * \brief Emit a stored vertex (in vb.vertex_store) to DMA. + * \brief Emit a stored vertex (in vb_t::vertex_store) to DMA. + * + * \param v vertex index. + * + * Adds the vertex into the current vertex buffer and calls the notification + * callback vb_t::notify(). */ static void emit_vertex( int v ) { @@ -325,7 +385,14 @@ static void emit_vertex( int v ) /** - * \brief Emit a quad (in vb.vertex_store) to dma as two triangles. + * \brief Emit a quad (in vb_t::vertex_store) to DMA as two triangles. + * + * \param v0 first vertex index. + * \param v1 second vertex index. + * \param v2 third vertex index. + * \param v3 fourth vertex index. + * + * Calls emit_vertex() to emit the triangles' vertices. */ static void emit_quad( int v0, int v1, int v2, int v3 ) { @@ -334,7 +401,11 @@ static void emit_quad( int v0, int v1, int v2, int v3 ) } /** - * \brief Every fourth vertex in a quad primitive, this is called to emit. + * \brief Every fourth vertex in a quad primitive, this is called to emit it. + * + * Pops the notification stack, calls emit_quad() and pushes the notification + * stack again, with itself and the vb_t::vertex_store to process another four + * vertices. */ static void notify_quad( void ) { @@ -343,11 +414,18 @@ static void notify_quad( void ) push_notify( notify_quad, 4, vb.vertex_store ); } -/* - * After the 4th vertex, emit either a quad or a flipped quad each two - * vertices. - */ static void notify_qstrip1( void ); + +/** + * \brief After the 4th vertex, emit either a quad or a flipped quad each two + * vertices. + * + * Pops the notification stack, calls emit_quad() with the flipped vertices and + * pushes the notification stack again, with notify_qstrip1() and the + * vb_t::vertex_store to process another two vertices. + * + * \sa notify_qstrip1(). + */ static void notify_qstrip0( void ) { pop_notify(); @@ -355,6 +433,16 @@ static void notify_qstrip0( void ) push_notify( notify_qstrip1, 2, vb.vertex_store ); } +/** + * \brief After the 4th vertex, emit either a quad or a flipped quad each two + * vertices. + * + * Pops the notification stack, calls emit_quad() with the straight vertices + * and pushes the notification stack again, with notify_qstrip0() and the + * vb_t::vertex_store to process another two vertices. + * + * \sa notify_qstrip0(). + */ static void notify_qstrip1( void ) { pop_notify(); @@ -366,6 +454,8 @@ static void notify_qstrip1( void ) * \brief Emit the saved vertex (but hang on to it for later). * * Continue processing this primitive as a linestrip. + * + * Pops the notification stack and calls emit_quad with the first vertex. */ static void notify_lineloop0( void ) { @@ -373,15 +463,30 @@ static void notify_lineloop0( void ) emit_vertex(0); } - - - +/** + * \brief Invalidate the current vertex format. + * + * \param ctx GL context. + * + * Sets the vb_t::recheck flag. + */ void radeonVtxfmtInvalidate( GLcontext *ctx ) { vb.recheck = GL_TRUE; } +/** + * \brief Validate the vertex format from the context. + * + * \param ctx GL context. + * + * Signals a new primitive and determines the appropriate vertex format and + * size. Points vb_t::floatcolorptr and vb_t::texcoordptr to the curent vertex + * and sets them to the current color and texture attributes. + * + * Clears the vb_t::recheck flag on exit. + */ static void radeonVtxfmtValidate( GLcontext *ctx ) { radeonContextPtr rmesa = RADEON_CONTEXT( ctx ); @@ -440,7 +545,10 @@ static void radeonVtxfmtValidate( GLcontext *ctx ) -/* Begin/End +/** + * \brief Process glBegin/glEnd. + * + * \param mode primitive. */ static void radeon_Begin( GLenum mode ) { @@ -467,7 +575,7 @@ static void radeon_Begin( GLenum mode ) if (vb.recheck) radeonVtxfmtValidate( ctx ); - /* Do we need to grab a new dma region for the vertices? + /* Do we need to grab a new DMA region for the vertices? */ if (rmesa->dma.current.ptr + 12*vb.vertex_size*4 > rmesa->dma.current.end) { RADEON_NEWPRIM( rmesa ); @@ -549,6 +657,15 @@ static void radeon_End( void ) } +/** + * \brief Flush vertices. + * + * \param ctx GL context. + * \param flags flags. + * + * If FLUSH_UPDATE_CURRENT is et in \p flags then the current vertex attributes + * in the GL context is updated from vb_t::floatcolorptr and vb_t::texcoordptr. + */ static void radeonFlushVertices( GLcontext *ctx, GLuint flags ) { if (flags & FLUSH_UPDATE_CURRENT) { @@ -569,8 +686,14 @@ static void radeonFlushVertices( GLcontext *ctx, GLuint flags ) } -/* Code each function once, let the compiler optimize away the inline - * calls: +/** + * \brief Set current vertex coordinates. + * + * \param x x vertex coordinate. + * \param y y vertex coordinate. + * \param z z vertex coordinate. + * + * Set the current vertex coordinates. If run out of space in this buffer call the notification callback. */ static __inline__ void radeon_Vertex3f( GLfloat x, GLfloat y, GLfloat z ) { @@ -587,6 +710,16 @@ static __inline__ void radeon_Vertex3f( GLfloat x, GLfloat y, GLfloat z ) vb.stack[0].notify(); } +/** + * \brief Set current vertex color. + * + * \param r red color component. + * \param g gree color component. + * \param b blue color component. + * \param a alpha color component. + * + * Sets the current vertex color via vb_t::floatcolorptr. + */ static __inline__ void radeon_Color4f( GLfloat r, GLfloat g, GLfloat b, GLfloat a ) { @@ -597,6 +730,16 @@ static __inline__ void radeon_Color4f( GLfloat r, GLfloat g, dest[3] = a; } +/** + * \brief Set current vertex color. + * + * \param r red color component. + * \param g gree color component. + * \param b blue color component. + * \param a alpha color component. + * + * Sets the current vertex color via vb_t::floatcolorptr. + */ static __inline__ void radeon_TexCoord2f( GLfloat s, GLfloat t ) { GLfloat *dest = vb.texcoordptr; @@ -604,44 +747,79 @@ static __inline__ void radeon_TexCoord2f( GLfloat s, GLfloat t ) dest[1] = t; } -/* Rely on __inline__ to make these efficient: +/** + * Calls radeon_Vertex3f(), which is expanded inline by the compiler to be + * efficient. */ static void radeon_Vertex3fv( const GLfloat *v ) { radeon_Vertex3f( v[0], v[1], v[2] ); } +/** + * Calls radeon_Vertex3f(), which is expanded inline by the compiler to be + * efficient. + */ static void radeon_Vertex2f( GLfloat x, GLfloat y ) { radeon_Vertex3f( x, y, 0 ); } +/** + * Calls radeon_Vertex3f(), which is expanded inline by the compiler to be + * efficient. + */ static void radeon_Vertex2fv( const GLfloat *v ) { radeon_Vertex3f( v[0], v[1], 0 ); } +/** + * Calls radeon_Vertex3f(), which is expanded inline by the compiler to be + * efficient. + */ static void radeon_Color4fv( const GLfloat *v ) { radeon_Color4f( v[0], v[1], v[2], v[3] ); } +/** + * Calls radeon_Color4f(), which is expanded inline by the compiler to be + * efficient. + */ static void radeon_Color3f( GLfloat r, GLfloat g, GLfloat b ) { radeon_Color4f( r, g, b, 1.0 ); } +/** + * Calls radeon_Color4f(), which is expanded inline by the compiler to be + * efficient. + */ static void radeon_Color3fv( const GLfloat *v ) { radeon_Color4f( v[0], v[1], v[2], 1.0 ); } +/** + * Calls radeon_TexCoord2f(), which is expanded inline by the compiler to be + * efficient. + */ static void radeon_TexCoord2fv( const GLfloat *v ) { radeon_TexCoord2f( v[0], v[1] ); } - +/** + * \brief Setup the GL context callbacks. + * + * \param ctx GL context. + * + * Setups the GL context callbacks and links _glapi_table entries related to + * the glBegin()/glEnd() pairs to the functions in this module. + * + * Called by radeonCreateContext(). + */ void radeonVtxfmtInit( GLcontext *ctx ) { struct _glapi_table *exec = ctx->Exec; @@ -667,25 +845,51 @@ void radeonVtxfmtInit( GLcontext *ctx ) notify_noop(); } - +/** + * No-op. + */ void radeonVtxfmtUnbindContext( GLcontext *ctx ) { } +/** + * No-op. + */ void radeonVtxfmtMakeCurrent( GLcontext *ctx ) { } +/** + * No-op. + */ void radeonVtxfmtDestroy( GLcontext *ctx ) { } +/** + * \brief Software rendering fallback. + * + * \param ctx GL context. + * \param bit fallback bitmask. + * \param mode enable or disable. + * + * Does nothing except display a warning message if \p mode is set. + */ void radeonFallback( GLcontext *ctx, GLuint bit, GLboolean mode ) { if (mode) fprintf(stderr, "Warning: hit nonexistant fallback path!\n"); } +/** + * \brief Software TCL fallback. + * + * \param ctx GL context. + * \param bit fallback bitmask. + * \param mode enable or disable. + * + * Does nothing except display a warning message if \p mode is set. + */ void radeonTclFallback( GLcontext *ctx, GLuint bit, GLboolean mode ) { if (mode)