diff options
Diffstat (limited to 'docs/drivers.html')
| -rw-r--r-- | docs/drivers.html | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/docs/drivers.html b/docs/drivers.html new file mode 100644 index 00000000000..47a059a57ae --- /dev/null +++ b/docs/drivers.html @@ -0,0 +1,221 @@ +<HTML> + +<TITLE>Writing Mesa Device Drivers</TITLE> + +<BODY text="#000000" bgcolor="#55bbff" link="#111188"> + +<center><h1>Writing Mesa Device Drivers</h1></center> + +<h2>Introduction</h2> + +<p> +Several different classes of drivers can be identified: +</p> +<ul> +<li><b>100% Software Driver</b> - + a software driver that does not utilize accelerated graphics hardware. + Such a driver will basically just write (and read) pixel values to the + computer's frame buffer or a malloc'd color buffer. + Examples include the X11/XMesa driver, the Windows driver and OSMesa. +</li> +<br> +<li><b>Hardware Rasterization Driver</b> - + for graphics hardware that implements accelerated point/line/triangle + rasterization, but relies on core Mesa for vertex transformation. + Examples include the DRI 3Dfx, Matrox, and Rage 128 drivers. +</li> +<br> +<li><b>Hardware Transformation and Rasterization Driver</b> - + for graphics hardware that implements accelerated rasterization and vertex + transformation. + Examples include the DRI Radeon and R200 drivers. +</li> +</ul> + +<p> +Each class of driver builds on the functionality of the preceeding one. +For example, a hardware rasterization driver may need to fall back to +software rasterization when a particular OpenGL state combination is set +but not supported by the hardware (perhaps smooth, stippled, textured +triangles). +</p> + +<p> +Likewise, a hardware transformation driver might need to fall back to +software-based transformation when a particular, seldom-used lighting +mode is enabled. +</p> + + +<h2>Getting Started</h2> + +<p> +The best way to get started writing a new driver is to find an existing +driver similar to what you plan to implement, and then study it. +</p> +<p> +It's not feasible for this document to explain every detail of writing +a driver. +The minute details can be gleaned by looking at existing drivers. +This document focuses on the high-level concepts and will perhaps expand +on the details in the future. +</p> +<p> +For examples of 100% software drivers, the OSMesa and XMesa (fake/stand-alone +GLX) drivers are the best examples. +</p> +<p> +For examples of hardware drivers, the DRI Radeon and R200 drivers are good +examples. +</p> + + + +<h2>Programming API vs. Drivers</h2> + +<p> +There are two aspects to a Mesa device driver: +</p> + +<ul> +<li><b>Public programming API</b> - + this is the interface which application programmers use. + Examples are the GLX, WGL and OSMesa interfaces. + If you're developing a device driver for a new operating system or + window system you'll have to design and implement an <em>OpenGL glue</em> + interface similar to these. + This interface will, in turn, communicate with the internal driver code. +</li> +<br> +<li><b>Private/internal driver code</b> - + this is the code which (effectively) translates OpenGL API calls into + rendering operations. + The device driver must manage hardware resources, track OpenGL state + and implement or dispatch the fundamental rendering operations such as + point, line, triangle and image rendering. +</li> +</ul> + +<p> +The remainder of this document will focus on the later part. +Furthermore, we'll use the GLX interface for examples. +</p> + +<p> +In the case of the DRI drivers, the public GLX interface is contained in +the <b>libGL.so</b> library. +libGL.so, in turn, dynamically loads one of the DRI drivers (such as +radeon_dri.so). +Both libGL.so and the driver modules talk to the X window system via the +DRI extension. +Furthermore, the driver modules interface to the graphics hardware with +the help of a kernel module and the conventional 2D X server driver. +</p> + + + + +<h2>Software Driver Overview</h2> + +<p> +A software driver is primarily concerned with writing pixel values to the +system's color buffer (and reading them back). +The color buffers might be window canvases (typically the front +color buffer) and/or off-screen image buffers (typically the back color +buffer). +The depth, stencil and accumulation buffers will be implemented within +core Mesa. +</p> +<p> +The software driver must also be concerned with allocation and deallocation +of rendering contexts, frame buffers and pixel formats (visuals). +</p> + + +<h3>Rendering Contexts</h3> + +<p> +The glue interface will always have a function for creating new rendering +contexts (such as glXCreateContext). +The device driver must have a function which allocates and initializes +a device-specific rendering context. +</p> + + +<h3>Frame Buffers</h3> + +<p> +The <em>frame buffer</em> can either be a screen region defined by a window +or the entire screen. +</p> +<p> +In either case, the device driver must implement functions for allocating, +initializing and managing frame buffers. +<p> + + +<h3>Spans</h3> + +<p> +The fundamental rendering operation is to write (and read) +<em>spans</em> of pixels to the front / back color buffers. +A span is a horizontal array of pixel colors with an array of mask +flags. The span begins at a particular (x,y) screen coordinate, +extends for N pixels, describes N RGBA colors (or color indexes) and +has an array of N boolean flags indicating which pixels to write and skip. +<p> + +<h3>Miscellaneous functions</h3> + +<p> +Additionally, a software driver will typically have functions for +binding rendering contexts to frame buffers (via glXMakeCurrent), +swapping color buffers (via glXSwapBuffers), synchronization +(via glFlush/glFinish) and queries (via glGetString). +</p> + +<h3>Optimizations</h3> + +<p> +A software driver might implement optimized routines for drawing lines +and triangles for common cases (such as smooth shading with depth-testing). +Then, the span functions can be bypassed for a little extra speed. +The OSMesa and XMesa drivers have examples of this. +</p> + + + + + + + +<h2>Hardware Driver Overview</h2> + +<p> +To do... +</p> + + + +<h2>OOP-Style Inheritance and Specialization</h2> + +<p> +Even though Mesa and most device drivers are written in C, object oriented +programming principles are used in several places. +</p> + +<h3>Rendering Contexts</h3> + +<p> +Every Mesa device driver will need to define a device-specific rendering +context structure. +</p> + + +<h2>State Tracking</h2> + + + + +</BODY> +</HTML> |