-<HTML>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8">
+ <title>Off-screen Rendering</title>
+ <link rel="stylesheet" type="text/css" href="mesa.css">
+</head>
+<body>
-<TITLE>Off-screen Rendering</TITLE>
+<div class="header">
+ <h1>The Mesa 3D Graphics Library</h1>
+</div>
-<BODY text="#000000" bgcolor="#55bbff" link="#111188">
+<iframe src="contents.html"></iframe>
+<div class="content">
-<H1>Off-screen Rendering</H1>
+<h1>Off-screen Rendering</h1>
<p>
-Mesa 1.2.4 introduced off-screen rendering, a facility for generating
-3-D imagery without having to open a window on your display. Mesa's
-simple off-screen rendering interface is completely operating system
-and window system independent so programs which use off-screen
-rendering should be very portable. This feature effectively
-enables you to use Mesa as an off-line, batch-oriented renderer.
+Mesa's off-screen interface is used for rendering into user-allocated memory
+without any sort of window system or operating system dependencies.
+That is, the GL_FRONT colorbuffer is actually a buffer in main memory,
+rather than a window on your display.
</p>
+
<p>
-The "OSMesa" API provides 3 functions for making off-screen
+The OSMesa API provides three basic functions for making off-screen
renderings: OSMesaCreateContext(), OSMesaMakeCurrent(), and
OSMesaDestroyContext(). See the Mesa/include/GL/osmesa.h header for
-more information. See the demos/osdemo.c file for an example program.
-There is no facility for writing images to files. That's up to you.
+more information about the API functions.
</p>
+
<p>
-If you want to generate large images (larger than 1280x1024) you'll
-have to edit the src/config.h file to change MAX_WIDTH and MAX_HEIGHT
-then recompile Mesa. Image size should only be limited by available
-memory.
+The OSMesa interface may be used with any of three software renderers:
</p>
+<ol>
+<li>llvmpipe - this is the high-performance Gallium LLVM driver
+<li>softpipe - this it the reference Gallium software driver
+<li>swrast - this is the legacy Mesa software rasterizer
+</ol>
-<H2>Deep color channels</H2>
-
<p>
- For some applications 8-bit color channels don't have sufficient
- accuracy (film and IBR, for example). If you're in this situation
- you'll be happy to know that Mesa supports 16-bit and 32-bit color
- channels through the OSMesa interface. When using 16-bit channels,
- channels are GLushorts and RGBA pixels occupy 8 bytes. When using 32-bit
- channels, channels are GLfloats and RGBA pixels occupy 16 bytes.
+There are several examples of OSMesa in the mesa/demos repository.
</p>
+
+<h1>Building OSMesa</h1>
+
<p>
- To build Mesa/OSMesa with 16-bit color channels:
-<pre>
- cd Mesa-5.x/src
- make -f Makefile.X11 clean
- make -f Makefile.OSMesa16 linux-osmesa16
-</pre>
+Configure and build Mesa with something like:
- For 32-bit channels:
<pre>
- cd Mesa-5.x/src
- make -f Makefile.X11 clean
- make -f Makefile.OSMesa16 linux-osmesa32
+configure --enable-osmesa --disable-driglx-direct --disable-dri --with-gallium-drivers=swrast
+make
</pre>
<p>
-You'll wind up with a library named libOSMesa16.so or libOSMesa32.so.
+Make sure you have LLVM installed first if you want to use the llvmpipe driver.
</p>
<p>
-If you're not using Linux, you can easily edit Make-config and add
-an appropriate configuration.
+When the build is complete you should find:
</p>
+<pre>
+lib/libOSMesa.so (swrast-based OSMesa)
+lib/gallium/libOSMsea.so (gallium-based OSMesa)
+</pre>
+
<p>
-The Mesa/tests/osdemo16.c file (available via CVS) demonstrates how
-to use this feature.
+Set your LD_LIBRARY_PATH to point to one directory or the other to select
+the library you want to use.
</p>
+
<p>
-BE WARNED: 16 and 32-bit channel support has not been exhaustively
-tested and there may be some bugs. However, a number of people have
-been using this feature successfully so it can't be too broken.
+When you link your application, link with -lOSMesa
</p>
-
-</BODY>
-</HTML>
+</div>
+</body>
+</html>