Re: [Mesa3d-dev] Mesa Implementation Notes update

[Brian P. <br...@tu...>]

See my edits below.

-Brian


Jos=E9 Fonseca wrote:
>=20
> Hi,
>=20
> I've included an (hopefully) updated version the Mesa Implementation No=
tes
> in the DRI-Devel-FAQ.
>=20
> I would appreciate corrections additions to this.
>=20
> Although a hypertext version (whith direct links to the DRI CVS) is at
> http://mefriss1.swan.ac.uk/~jfonseca/dri/faq/html/architecture.html#MES=
A-INTERNALS
> I've pasted a ascii-only version here for your convenience.
>=20
> -----------------------------------------------------------------------=
----------------
>=20
> 3.3.5. Mesa Implementation Notes
>=20
> This document is an overview of the internal structure of Mesa and is
> meant for those who are interested in modifying or enhancing Mesa, or j=
ust
> curious.
>=20
> [Note]
>=20
> Based on the original Mesa Implementation Notes by Brian Paul.
> 3.3.5.1. Library State and Contexts
>=20
> OpenGL uses the notion of a state machine. Mesa encapsulates the state =
in
> one large struct: gl_context, as seen in types.h

It's called __GLcontextRec now (typedef'd to GLcontext)


> The gl_context struct actually contains a number of sub structs which
> exactly correspond to OpenGL's attribute groups. This organization made
> glPushAttrib and glPopAttrib trivial to implement and proved to be a go=
od
> way of organizing the state variables.
> 3.3.5.2. Vertex buffer
>=20
> The vertices between glBegin and glEnd are accumulated in the vertex
> buffer (see vb.h and vb.c ).

See the 'struct immediate' in tnl/t_context.h and the tnl/t_imm_api.c
file.


> When either the vertex buffer becomes filled
> or a state change outside the glBegin/glEnd is made, we must flush the
> buffer. That is, we apply the vertex transformations, compute lighting,
> fog, texture coordinates etc. Then, we can render the vertices as point=
s,
> lines or polygons by calling the gl_render_vb() function in render.c .

Replace last sentence with: "The various vertex transformations are
implemented as software pipeline stages by the t_pipeline.c and
t_vb_*.c files.


> When we're outside of a glBegin/glEnd pair the information in this
> structure is retained pending either of the flushing events described
> above.
>=20
> [Note]
>=20
> Originally, Mesa didn't accumulate vertices in this way. Instead, glVer=
tex
> transformed and lit then buffered each vertex as it was received. When
> enough vertices to draw the primitive (1 for points, 2 for lines, >2 fo=
r
> polygons) were accumulated the primitive was drawn and the buffer clear=
ed.
>=20
> The new approach of buffering many vertices and then transforming,
> lighting and clip testing is faster because it's done in a "vectorized"
> manner. See gl_transform_points in xform.c for an example. Also, vertic=
es
> shared between primitives (i.e. GL_LINE_STRIP) are only transformed onc=
e.

Remove the last sentence.


> The only complication is clipping. If no vertices in the vertex buffer
> have their clip flag set, the rasterization functions can be applied
> directly to the vertex buffer. Otherwise, a clipping function is called
> before rasterizing each primitive. If clipping introduces new vertices
> they will be stored at the end of the vertex buffer.

Remove that paragraph.


> For best performance Mesa clients should try to maximize the number of
> vertices between glBegin/glEnd pairs and used connected primitives when
> possible.
> 3.3.5.3. Rasterization
>=20
> The point, line and polygon rasterizers are called via the PointsFunc,
> LineFunc, and TriangleFunc function pointers in the dd_function_table
> driver function pointer table.

Those functions are now in swrast/s_context.h in the SWcontext struct.


> Whenever the library state is changed in a
> significant way, the NewState context flag is raised. When glBegin is
> called NewState is checked. If the flag is set we re-evaluate the state=
 to
> determine what rasterizers to use. Special purpose rasterizers are
> selected according to the status of certain state variables such as fla=
t
> vs smooth shading, depth-buffered vs. non-depth- buffered, etc. The
> gl_set_point|line|polygon_function functions do this analysis.

The _swrast_choose_*() functions do this analysis.


> They in
> turn query the device driver for "accelerated" rasterizers. More on tha=
t
> later.

Remove that sentence.  It's up to the device driver to choose optimized
or accelerated rasterization functions to replace those in the general
software rasterizer.

> In general, typical states (depth-buffered & smooth-shading) result in
> optimized rasterizers being selected. Non-typical states (stenciling,
> blending, stippling) result in slower, general purpose rasterizers bein=
g
> selected.
>=20
> For best performance, Mesa clients should group state changes (glEnable=
,
> glDisable, glShadeModel, glLight*, glMaterial) together to minimize the
> number of times the rasterizer selectors are called.

Remove that paragraph.


> 3.3.5.4. Pixel (fragment) buffer
>=20
> The general purpose point, line and bitmap rasterizers accumulate
> fragments (pixels plus color, depth, texture coords) in the PB (Pixel
> Buffer) struct seen in . pb.h and pb.c . When the pixel buffer is full =
or
> glEnd is called the pixel buffer is flushed. This includes clipping the
> fragments against the window, depth testing, stenciling, blending,
> stippling, etc. Finally, the pixel buffer's pixels are drawn to the
> display buffer by calling one of device driver functions. The goal is t=
o
> maximize the number of pixels processed inside loops and to minimize th=
e
> number of function calls.

Pixel buffers are no longer present in the latest Mesa code (4.1).
All fragment processing is done via the span functions in swrast/s_span.c



> 3.3.5.5. Pixel spans
>=20
> The polygon, glDrawPixels, and glCopyPixels functions generate horizont=
al
> runs of pixels called spans. Spans are processed in span.c . Processing
> includes window clipping, depth testing, stenciling, texturing, etc. Af=
ter
> processing the span is written to the frame buffer by calling a device
> driver function.

Points, lines, triangles, glDrawPixel, glCopyPixels and glBitmap all
use the sw_span struct and functions in swrast/s_span.c to perform
fragment operations and rendering.



> 3.3.5.6. Device Driver
>=20
> There are three Mesa datatypes which are meant to be used by device
> drivers:
>=20
> GLcontext
>=20
>      this contains the Mesa rendering state
> GLvisual
>=20
>      this describes the color buffer (rgb vs. ci), whether or not there=
's
> a depth buffer, stencil buffer, etc.
> GLframebuffer
>=20
>      contains pointers to the depth buffer, stencil buffer, accum buffe=
r
> and alpha buffers.
>=20
> These types should be encapsulated by corresponding device driver
> datatypes. See xmesa.h and xmesaP.h for an example.
>=20
> In OOP terms, GLcontext, GLvisual, and GLframebuffer are base classes
> which the device driver must derive from.
>=20
> The struct dd_function_table seen in dd.h , defines the device driver
> functions. By using a table of pointers, the device driver can be chang=
ed
> dynamically at runtime. For example, the X/Mesa and OS/Mesa (Off-Screen
> rendering) device drivers can co-exist in one library and be selected a=
t
> runtime.

Many of the functions which used to be in the dd_function_table are
now moved into the tnl or swrast modules.


> In addition to the device driver table functions, each Mesa driver has =
its
> own set of unique interface functions. For example, the X/Mesa driver h=
as
> the XMesaCreateContext, XMesaBindWindow, and XMesaSwapBuffers functions
> while the Windows/Mesa interface has WMesaCreateContext,
> WMesaPaletteChange and WMesaSwapBuffers. New Mesa drivers need to both
> implement the dd_function_table functions and define a set of unique
> window system or operating system-specific interface functions.
>=20
> The device driver functions can roughly be divided into four groups:
>=20
>     1.
>=20
>        pixel span functions which read or write horizontal runs of RGB =
or
> color-index pixels. Each function takes an array of mask flags which
> indicate whether or not to plot each pixel in the span.
>     2.
>=20
>        pixel array functions which are very similar to the pixel span
> functions except that they're used to read or write arrays of pixels at
> random locations rather than horizontal runs.
>     3.
>=20
>        miscellaneous functions for window clearing, setting the current
> drawing color, enabling/disabling dithering, returning the current fram=
e
> buffer size, specifying the window clear color, synchronization, etc. M=
ost
> of these functions directly correspond to higher level OpenGL functions.
>     4.
>=20
>        if your graphics hardware or operating system provides accelerat=
ed
> point, line and polygon rendering operations, they can be utilized thro=
ugh
> the PointsFunc, LineFunc, and TriangleFunc functions. Mesa will call th=
ese
> functions to "ask" the device driver for accelerated functions trhough =
the
> UpdateState . If the device driver can provide an appropriate renderer,
> given the current Mesa state, then a pointer to that function can be
> returned. Otherwise the PointsFunc, LineFunc, and TriangleFunc function=
s
> pointers can just be set to NULL.
>=20
> Even if hardware accelerated renderers aren't available, the device dri=
ver
> may implement tuned, special purpose code for common kinds of points,
> lines or polygons. The X/Mesa device driver does this for a number of
> lines and polygons. See the xmesa3.c file.

See the src/X/xm_tri.c and src/X/xm_line.c files.


> 3.3.5.7. Overall Organization
>=20
> The overall relation of the core Mesa library, X device driver/interfac=
e,
> toolkits and application programs is shown in this diagram:
>=20
> +-----------------------------------------------------------+
> |                                                           |
> |                   Application Programs                    |
> |                                                           |
> |          +- glu.h -+- aux.h tk.h glut.h -+                |
> |          |         |                     |                |
> |          |   GLU   |   aux, tk or GLUT   |                |
> |          |         |      toolkits       |                |
> |          |         |                     |                |
> +---------- gl.h ------------+-------- glx.h ----+          |
> |                            |                   |          |
> |         Mesa core          |   GLX functions   |          |
> |                            |                   |          |
> +---------- dd.h ------------+------------- xmesa.h --------+
> |                                                           |
> |              XMesa* and device driver functions           |
> |                                                           |
> +-----------------------------------------------------------+
> |                 Hardware/OS/Window System                 |
> +-----------------------------------------------------------+

Remove all references to "tk" and "aux".  They're long gone.