3
<TITLE>Writing Mesa Device Drivers</TITLE>
5
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
7
<center><h1>Writing Mesa Device Drivers</h1></center>
12
Several different classes of drivers can be identified:
15
<li><b>100% Software Driver</b> -
16
a software driver that does not utilize accelerated graphics hardware.
17
Such a driver will basically just write (and read) pixel values to the
18
computer's frame buffer or a malloc'd color buffer.
19
Examples include the X11/XMesa driver, the Windows driver and OSMesa.
22
<li><b>Hardware Rasterization Driver</b> -
23
for graphics hardware that implements accelerated point/line/triangle
24
rasterization, but relies on core Mesa for vertex transformation.
25
Examples include the DRI 3Dfx, Matrox, and Rage 128 drivers.
28
<li><b>Hardware Transformation and Rasterization Driver</b> -
29
for graphics hardware that implements accelerated rasterization and vertex
31
Examples include the DRI Radeon and R200 drivers.
36
Each class of driver builds on the functionality of the preceeding one.
37
For example, a hardware rasterization driver may need to fall back to
38
software rasterization when a particular OpenGL state combination is set
39
but not supported by the hardware (perhaps smooth, stippled, textured
44
Likewise, a hardware transformation driver might need to fall back to
45
software-based transformation when a particular, seldom-used lighting
50
<h2>Getting Started</h2>
53
The best way to get started writing a new driver is to find an existing
54
driver similar to what you plan to implement, and then study it.
57
It's not feasible for this document to explain every detail of writing
59
The minute details can be gleaned by looking at existing drivers.
60
This document focuses on the high-level concepts and will perhaps expand
61
on the details in the future.
64
For examples of 100% software drivers, the OSMesa and XMesa (fake/stand-alone
65
GLX) drivers are the best examples.
68
For examples of hardware drivers, the DRI Radeon and R200 drivers are good
74
<h2>Programming API vs. Drivers</h2>
77
There are two aspects to a Mesa device driver:
81
<li><b>Public programming API</b> -
82
this is the interface which application programmers use.
83
Examples are the GLX, WGL and OSMesa interfaces.
84
If you're developing a device driver for a new operating system or
85
window system you'll have to design and implement an <em>OpenGL glue</em>
86
interface similar to these.
87
This interface will, in turn, communicate with the internal driver code.
90
<li><b>Private/internal driver code</b> -
91
this is the code which (effectively) translates OpenGL API calls into
93
The device driver must manage hardware resources, track OpenGL state
94
and implement or dispatch the fundamental rendering operations such as
95
point, line, triangle and image rendering.
100
The remainder of this document will focus on the later part.
101
Furthermore, we'll use the GLX interface for examples.
105
In the case of the DRI drivers, the public GLX interface is contained in
106
the <b>libGL.so</b> library.
107
libGL.so, in turn, dynamically loads one of the DRI drivers (such as
109
Both libGL.so and the driver modules talk to the X window system via the
111
Furthermore, the driver modules interface to the graphics hardware with
112
the help of a kernel module and the conventional 2D X server driver.
118
<h2>Software Driver Overview</h2>
121
A software driver is primarily concerned with writing pixel values to the
122
system's color buffer (and reading them back).
123
The color buffers might be window canvases (typically the front
124
color buffer) and/or off-screen image buffers (typically the back color
126
The depth, stencil and accumulation buffers will be implemented within
130
The software driver must also be concerned with allocation and deallocation
131
of rendering contexts, frame buffers and pixel formats (visuals).
135
<h3>Rendering Contexts</h3>
138
The glue interface will always have a function for creating new rendering
139
contexts (such as glXCreateContext).
140
The device driver must have a function which allocates and initializes
141
a device-specific rendering context.
145
<h3>Frame Buffers</h3>
148
The <em>frame buffer</em> can either be a screen region defined by a window
149
or the entire screen.
152
In either case, the device driver must implement functions for allocating,
153
initializing and managing frame buffers.
160
The fundamental rendering operation is to write (and read)
161
<em>spans</em> of pixels to the front / back color buffers.
162
A span is a horizontal array of pixel colors with an array of mask
163
flags. The span begins at a particular (x,y) screen coordinate,
164
extends for N pixels, describes N RGBA colors (or color indexes) and
165
has an array of N boolean flags indicating which pixels to write and skip.
168
<h3>Miscellaneous functions</h3>
171
Additionally, a software driver will typically have functions for
172
binding rendering contexts to frame buffers (via glXMakeCurrent),
173
swapping color buffers (via glXSwapBuffers), synchronization
174
(via glFlush/glFinish) and queries (via glGetString).
177
<h3>Optimizations</h3>
180
A software driver might implement optimized routines for drawing lines
181
and triangles for common cases (such as smooth shading with depth-testing).
182
Then, the span functions can be bypassed for a little extra speed.
183
The OSMesa and XMesa drivers have examples of this.
192
<h2>Hardware Driver Overview</h2>
200
<h2>OOP-Style Inheritance and Specialization</h2>
203
Even though Mesa and most device drivers are written in C, object oriented
204
programming principles are used in several places.
207
<h3>Rendering Contexts</h3>
210
Every Mesa device driver will need to define a device-specific rendering
215
<h2>State Tracking</h2>
added
removed
docs/drivers.html
