docs/drivers.html - third_party/mesa - Git at Google

 <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>
	<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>