Mesa Source Code Documentation

There are three large Mesa data types/classes which are meant to be used by device drivers:

These types should be encapsulated by corresponding device driver data types. See xmesa.h and xmesaP.h for an example.

In OOP terms, GLcontext, GLvisual, and GLframebuffer are base classes which the device driver must derive from.

#include "imports.h"
#include "mtypes.h"


Defines
#define	NEED_SECONDARY_COLOR(CTX)
	Is the secondary color needed?
#define	RGBA_LOGICOP_ENABLED(CTX)
	Is RGBA LogicOp enabled?
Macros for flushing buffered rendering commands before state changes,
checking if inside glBegin/glEnd, etc.
#define	FLUSH_VERTICES(ctx, newstate)
	Flush vertices.
#define	FLUSH_CURRENT(ctx, newstate)
	Flush current state.
#define	ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, retval)
	Macro to assert that the API call was made outside the glBegin()/glEnd() pair, with return value.
#define	ASSERT_OUTSIDE_BEGIN_END(ctx)
	Macro to assert that the API call was made outside the glBegin()/glEnd() pair.
#define	ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx)
	Macro to assert that the API call was made outside the glBegin()/glEnd() pair and flush the vertices.
#define	ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH_WITH_RETVAL(ctx, retval)
	Macro to assert that the API call was made outside the glBegin()/glEnd() pair and flush the vertices, with return value.
Functions
void	_mesa_notifySwapBuffers (__GLcontext *gc)
	Swap buffers notification callback.
struct _glapi_table *	_mesa_get_dispatch (GLcontext *ctx)
	Get context's current API dispatch table.
void	_mesa_set_mvp_with_dp4 (GLcontext *ctx, GLboolean flag)
	Set mvp_with_dp4 flag.
GLboolean	_mesa_valid_to_render (GLcontext ctx, const char where)
	Prior to drawing anything with glBegin, glDrawArrays, etc.
Visual-related functions
GLvisual *	_mesa_create_visual (GLboolean rgbFlag, GLboolean dbFlag, GLboolean stereoFlag, GLint redBits, GLint greenBits, GLint blueBits, GLint alphaBits, GLint indexBits, GLint depthBits, GLint stencilBits, GLint accumRedBits, GLint accumGreenBits, GLint accumBlueBits, GLint accumAlphaBits, GLint numSamples)
	Allocates a GLvisual structure and initializes it via _mesa_initialize_visual().
GLboolean	_mesa_initialize_visual (GLvisual *v, GLboolean rgbFlag, GLboolean dbFlag, GLboolean stereoFlag, GLint redBits, GLint greenBits, GLint blueBits, GLint alphaBits, GLint indexBits, GLint depthBits, GLint stencilBits, GLint accumRedBits, GLint accumGreenBits, GLint accumBlueBits, GLint accumAlphaBits, GLint numSamples)
	Makes some sanity checks and fills in the fields of the GLvisual object with the given parameters.
void	_mesa_destroy_visual (GLvisual *vis)
	Destroy a visual and free its memory.
Context-related functions
GLcontext *	_mesa_create_context (const GLvisual visual, GLcontext share_list, const struct dd_function_table driverFunctions, void driverContext)
	Allocate and initialize a GLcontext structure.
GLboolean	_mesa_initialize_context (GLcontext ctx, const GLvisual visual, GLcontext share_list, const struct dd_function_table driverFunctions, void *driverContext)
	Initialize a GLcontext struct (rendering context).
void	_mesa_initialize_context_extra (GLcontext *ctx)
void	_mesa_free_context_data (GLcontext *ctx)
	Free the data associated with the given context.
void	_mesa_destroy_context (GLcontext *ctx)
	Destroy a GLcontext structure.
void	_mesa_copy_context (const GLcontext src, GLcontext dst, GLuint mask)
	Copy attribute groups from one context to another.
void	_mesa_check_init_viewport (GLcontext *ctx, GLuint width, GLuint height)
	Check if the viewport/scissor size has not yet been initialized.
GLboolean	_mesa_make_current (GLcontext ctx, GLframebuffer drawBuffer, GLframebuffer *readBuffer)
	Bind the given context to the given drawBuffer and readBuffer and make it the current context for the calling thread.
GLboolean	_mesa_share_state (GLcontext ctx, GLcontext ctxToShare)
	Make context 'ctx' share the display lists, textures and programs that are associated with 'ctxToShare'.
GLcontext *	_mesa_get_current_context (void)
	Returns: pointer to the current GL context for this thread.
Miscellaneous
void	_mesa_record_error (GLcontext *ctx, GLenum error)
	Record an error.
void GLAPIENTRY	_mesa_Finish (void)
	Execute glFinish().
void GLAPIENTRY	_mesa_Flush (void)
	Execute glFlush().

Define Documentation

#define ASSERT_OUTSIDE_BEGIN_END ( ctx )

Value:

do {                                                                    \
   if (ctx->Driver.CurrentExecPrimitive != PRIM_OUTSIDE_BEGIN_END) {    \
      _mesa_error(ctx, GL_INVALID_OPERATION, "Inside glBegin/glEnd");   \
      return;                                                           \
   }                                                                    \
} while (0)

Macro to assert that the API call was made outside the glBegin()/glEnd() pair.

Parameters:

ctx

GL context.

#define ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH ( ctx )

Value:

do {                                                                    \
   ASSERT_OUTSIDE_BEGIN_END(ctx);                                       \
   FLUSH_VERTICES(ctx, 0);                                              \
} while (0)

Macro to assert that the API call was made outside the glBegin()/glEnd() pair and flush the vertices.

Parameters:

ctx

GL context.

#define ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH_WITH_RETVAL	(	ctx,
		retval		)

Value:

do {                                                                    \
   ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, retval);                   \
   FLUSH_VERTICES(ctx, 0);                                              \
} while (0)

Macro to assert that the API call was made outside the glBegin()/glEnd() pair and flush the vertices, with return value.

Parameters:

	ctx	GL context.
	retval	value to return value in case the assertion fails.

#define ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL	(	ctx,
		retval		)

Value:

do {                                                                    \
   if (ctx->Driver.CurrentExecPrimitive != PRIM_OUTSIDE_BEGIN_END) {    \
      _mesa_error(ctx, GL_INVALID_OPERATION, "Inside glBegin/glEnd");   \
      return retval;                                                    \
   }                                                                    \
} while (0)

Macro to assert that the API call was made outside the glBegin()/glEnd() pair, with return value.

Parameters:

	ctx	GL context.
	retval	value to return value in case the assertion fails.

#define FLUSH_CURRENT	(	ctx,
		newstate		)

Value:

do {                                                            \
   if (MESA_VERBOSE & VERBOSE_STATE)                            \
      _mesa_debug(ctx, "FLUSH_CURRENT in %s\n", MESA_FUNCTION); \
   if (ctx->Driver.NeedFlush & FLUSH_UPDATE_CURRENT)            \
      ctx->Driver.FlushVertices(ctx, FLUSH_UPDATE_CURRENT);     \
   ctx->NewState |= newstate;                                   \
} while (0)

Flush current state.

Parameters:

	ctx	GL context.
	newstate	new state.

Checks if dd_function_table::NeedFlush is marked to flush current state, and calls dd_function_table::FlushVertices if so. Marks __GLcontextRec::NewState with newstate.

#define FLUSH_VERTICES	(	ctx,
		newstate		)

Value:

do {                                                            \
   if (MESA_VERBOSE & VERBOSE_STATE)                            \
      _mesa_debug(ctx, "FLUSH_VERTICES in %s\n", MESA_FUNCTION);\
   if (ctx->Driver.NeedFlush & FLUSH_STORED_VERTICES)           \
      ctx->Driver.FlushVertices(ctx, FLUSH_STORED_VERTICES);    \
   ctx->NewState |= newstate;                                   \
} while (0)

Flush vertices.

Parameters:

	ctx	GL context.
	newstate	new state.

Checks if dd_function_table::NeedFlush is marked to flush stored vertices, and calls dd_function_table::FlushVertices if so. Marks __GLcontextRec::NewState with newstate.

#define NEED_SECONDARY_COLOR ( CTX )

Value:

(((CTX)->Light.Enabled &&                                               \
     (CTX)->Light.Model.ColorControl == GL_SEPARATE_SPECULAR_COLOR)     \
    || (CTX)->Fog.ColorSumEnabled                                       \
    || ((CTX)->VertexProgram._Current &&                                \
        ((CTX)->VertexProgram._Current != (CTX)->VertexProgram._TnlProgram) &&    \
        ((CTX)->VertexProgram._Current->Base.InputsRead & VERT_BIT_COLOR1)) \
    || ((CTX)->FragmentProgram._Current &&                              \
        ((CTX)->FragmentProgram._Current != (CTX)->FragmentProgram._TexEnvProgram) &&  \
        ((CTX)->FragmentProgram._Current->Base.InputsRead & FRAG_BIT_COL1)) \
   )

Is the secondary color needed?

#define RGBA_LOGICOP_ENABLED ( CTX )

Value:

((CTX)->Color.ColorLogicOpEnabled || \
   ((CTX)->Color.BlendEnabled && (CTX)->Color.BlendEquationRGB == GL_LOGIC_OP))

Is RGBA LogicOp enabled?

Function Documentation

void _mesa_check_init_viewport	(	GLcontext *	ctx,
		GLuint	width,
		GLuint	height
	)

Check if the viewport/scissor size has not yet been initialized.

Initialize the size if the given width and height are non-zero.

void _mesa_copy_context	(	const GLcontext *	src,
		GLcontext *	dst,
		GLuint	mask
	)

Copy attribute groups from one context to another.

Parameters:

	src	source context
	dst	destination context
	mask	bitwise OR of GL_*_BIT flags

According to the bits specified in mask, copies the corresponding attributes from src into dst. For many of the attributes a simple memcpy is not enough due to the existence of internal pointers in their data structures.

GLcontext* _mesa_create_context	(	const GLvisual *	visual,
		GLcontext *	share_list,
		const struct dd_function_table *	driverFunctions,
		void *	driverContext
	)

Allocate and initialize a GLcontext structure.

Note that the driver needs to pass in its dd_function_table here since we need to at least call driverFunctions->NewTextureObject to initialize the rendering context.

Parameters:

	visual	a GLvisual pointer (we copy the struct contents)
	share_list	another context to share display lists with or NULL
	driverFunctions	points to the dd_function_table into which the driver has plugged in all its special functions.
	driverContext	points to the device driver's private context state

Returns:: pointer to a new __GLcontextRec or NULL if error.

GLvisual* _mesa_create_visual	(	GLboolean	rgbFlag,
		GLboolean	dbFlag,
		GLboolean	stereoFlag,
		GLint	redBits,
		GLint	greenBits,
		GLint	blueBits,
		GLint	alphaBits,
		GLint	indexBits,
		GLint	depthBits,
		GLint	stencilBits,
		GLint	accumRedBits,
		GLint	accumGreenBits,
		GLint	accumBlueBits,
		GLint	accumAlphaBits,
		GLint	numSamples
	)

Allocates a GLvisual structure and initializes it via _mesa_initialize_visual().

Parameters:

	rgbFlag	GL_TRUE for RGB(A) mode, GL_FALSE for Color Index mode.
	dbFlag	double buffering
	stereoFlag	stereo buffer
	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.
	stencilBits	requested minimum bits per stencil buffer value
	accumRedBits,accumGreenBits,accumBlueBits,accumAlphaBits	number of bits per color component in accum buffer.
	indexBits	number of bits per pixel if `rgbFlag` is GL_FALSE
	redBits	number of bits per color component in frame buffer for RGB(A) mode. We always use 8 in core Mesa though.
	greenBits	same as above.
	blueBits	same as above.
	alphaBits	same as above.
	numSamples	not really used.

Returns:: pointer to new GLvisual or NULL if requested parameters can't be met.

Note:: Need to add params for level and numAuxBuffers (at least)

void _mesa_destroy_context ( GLcontext * ctx )

Destroy a GLcontext structure.

Parameters:

ctx

GL context.

Calls _mesa_free_context_data() and frees the GLcontext structure itself.

void _mesa_destroy_visual ( GLvisual * vis )

Destroy a visual and free its memory.

Parameters:

vis

visual.

Frees the visual structure.

void GLAPIENTRY _mesa_Finish ( void )

Execute glFinish().

Calls the ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the dd_function_table::Finish driver callback, if not NULL.

void GLAPIENTRY _mesa_Flush ( void )

Execute glFlush().

Calls the ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the dd_function_table::Flush driver callback, if not NULL.

void _mesa_free_context_data ( GLcontext * ctx )

Free the data associated with the given context.

But doesn't free the GLcontext struct itself.

See also:: _mesa_initialize_context() and init_attrib_groups().

GLcontext* _mesa_get_current_context ( void )

Returns:: pointer to the current GL context for this thread.

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.

struct _glapi_table* _mesa_get_dispatch ( GLcontext * ctx ) [read]

Get context's current API dispatch table.

It'll either be the immediate-mode execute dispatcher or the display list compile dispatcher.

Parameters:

ctx

GL context.

Returns:: pointer to dispatch_table.

Simply returns __GLcontextRec::CurrentDispatch.

GLboolean _mesa_initialize_context	(	GLcontext *	ctx,
		const GLvisual *	visual,
		GLcontext *	share_list,
		const struct dd_function_table *	driverFunctions,
		void *	driverContext
	)

Initialize a GLcontext struct (rendering context).

This includes allocating all the other structs and arrays which hang off of the context by pointers. Note that the driver needs to pass in its dd_function_table here since we need to at least call driverFunctions->NewTextureObject to create the default texture objects.

Called by _mesa_create_context().

Performs the imports and exports callback tables initialization, and miscellaneous 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 MESA_DEBUG and MESA_VERBOSE environment variables for debug flags.

Parameters:

	ctx	the context to initialize
	visual	describes the visual attributes for this context
	share_list	points to context to share textures, display lists, etc with, or NULL
	driverFunctions	table of device driver functions for this context to use
	driverContext	pointer to driver-specific context data

void _mesa_initialize_context_extra ( GLcontext * ctx )

GLboolean _mesa_initialize_visual	(	GLvisual *	vis,
		GLboolean	rgbFlag,
		GLboolean	dbFlag,
		GLboolean	stereoFlag,
		GLint	redBits,
		GLint	greenBits,
		GLint	blueBits,
		GLint	alphaBits,
		GLint	indexBits,
		GLint	depthBits,
		GLint	stencilBits,
		GLint	accumRedBits,
		GLint	accumGreenBits,
		GLint	accumBlueBits,
		GLint	accumAlphaBits,
		GLint	numSamples
	)

Makes some sanity checks and fills in the fields of the GLvisual object with the given parameters.

If the caller needs to set additional fields, he should just probably init the whole GLvisual object himself.

Returns:: GL_TRUE on success, or GL_FALSE on failure.

See also:: _mesa_create_visual() above for the parameter description.

GLboolean _mesa_make_current	(	GLcontext *	newCtx,
		GLframebuffer *	drawBuffer,
		GLframebuffer *	readBuffer
	)

Bind the given context to the given drawBuffer and readBuffer and make it the current context for the calling thread.

We'll render into the drawBuffer and read pixels from the readBuffer (i.e. glRead/CopyPixels, glCopyTexImage, etc).

We check that the context's and framebuffer's visuals are compatible and return immediately if they're not.

Parameters:

	newCtx	the new GL context. If NULL then there will be no current GL context.
	drawBuffer	the drawing framebuffer
	readBuffer	the reading framebuffer

void _mesa_notifySwapBuffers ( __GLcontext * ctx )

Swap buffers notification callback.

Parameters:

ctx

GL context.

Called by window system just before swapping buffers. We have to finish any pending rendering.

void _mesa_record_error	(	GLcontext *	ctx,
		GLenum	error
	)

Record an error.

Parameters:

	ctx	GL context.
	error	error code.

Records the given error code and call the driver's dd_function_table::Error function if defined.

See also:: This is called via _mesa_error().

void _mesa_set_mvp_with_dp4	(	GLcontext *	ctx,
		GLboolean	flag
	)

Set mvp_with_dp4 flag.

If a driver has a preference for DP4 over MUL/MAD, or vice versa, call this function to register that. Otherwise we default to MUL/MAD.

GLboolean _mesa_share_state	(	GLcontext *	ctx,
		GLcontext *	ctxToShare
	)

Make context 'ctx' share the display lists, textures and programs that are associated with 'ctxToShare'.

Any display lists, textures or programs associated with 'ctx' will be deleted if nobody else is sharing them.

GLboolean _mesa_valid_to_render	(	GLcontext *	ctx,
		const char *	where
	)

Prior to drawing anything with glBegin, glDrawArrays, etc.

this function is called to see if it's valid to render. This involves checking that the current shader is valid and the framebuffer is complete. If an error is detected it'll be recorded here.

Returns:: GL_TRUE if OK to render, GL_FALSE if not

context.h File Reference

Detailed Description

Defines

Functions

Define Documentation

Function Documentation