                           Mesa as loadable library
                                 (LDG format)



1 Introduction
--------------

Mesa (http://www.mesa3d.org/) is a free software implementation of the OpenGL
API. It can renders using hardware, or pure software using the CPU. This version
is called OSMesa (offscreen rendering Mesa). It renders its pictures using the
CPU in a memory buffer, which can then be copied to the screen.
On the Atari ST and higher computers, binary programs must be statically
linked i.e. all the libraries needed to run a program must be contained in the
file you distribute (the prg or tos file). This is a problem when you update
or bugfix a small part of this library, because the program must be recompiled
(or just relinked if you have the object files), and this operation is not
user-friendly.

2 Shared and loadable libraries
-------------------------------

The shared library concept is to load those needed libraries when you run the
program, so the program does not contain the code that does not belong to him.
On Atari systems, no actual development tool can easily do it for you. You
have two ways to implement loadable object files: SLB and LDG.

I decided to made Mesa a loadable library, so when I bugfix Mesa, I just have to
copy mesa.ldg or mesa.slb over the previous one. And all programs that use it are
bugfixed. Nice, isn't it?

I chose to do it the LDG way (I don't know much about the SLB way, but anyone
could do it).

3 Compilation and installation
------------------------------

First you need to install the standard Mesa library for MiNT (archive on my web
site), because the LDG installation will need files installed by the standard
archive.
Just './configure ; make ; make install' would be sufficient.

Note: you need to go in ./src and make libOSMesa.a first

4 Which Mesa.ldg ?
-----------------

Once installed, you'll find the osmesa.ldg files in $(prefix)/ldg and subdirs
according to CPU. Default $(prefix) is /usr/local/lib. Put the osmesa.ldg
corresponding to your cpu in the global LDG directory (or in the directory
where is the program that need it).

5 Usage
-------

Use the script 'osmesa-config' to retrieve needed parameters to compile your
program (--cflags, --static-libs for classic static linking, --libs to link
against OSMesa.ldg).

libOSMesa.a, which is in ${prefix}/lib/ldg/OSMesa is just a loader for the big
OSMesa.ldg. Whenever you call one of the OSMesa*() functions, it loads the ldg
for you.

6 Compatibility with mesa_gl.ldg and tiny_gl.ldg
------------------------------------------------

The LDG version should be compatible with previous OpenGL implementations on
Atari. However bugs may remain.

6.1 glOrtho() implementation
----------------------------

mesa_gl.ldg and tiny_gl.ldg use glOrtho() with 6 'float' parameters. However,
the OpenGL standard use 6 'GLdouble' parameters. The static libOSMesa.a library
(not the one in this archive) provides this original prototype (and in its header
files). To be compatible with previous OpenGL implementations, the glOrtho()
provided by ldg_find() function will point you to a compatible call (using
float parameters). If you want to port software requiring double parameters,
link against the libOSMesa.a, which will load the OSMesa.ldg library for you,
and which will give you the original prototype of this function.

7 Licenses
----------

osmesa.ldg and glu.ldg are under LGPL license, see COPYING.lgpl.
libOSMesa.a and libGLU.a are under ZLIB license, see COPYING.zlib.

It simply means you can statically link against the lib*.a for your program,
even if it is closed-source software.

--
Patrice Mandin <pmandin@caramail.com>
Web: http://membres.lycos.fr/pmandin/
