tiny_gl.ldg
===========

This is the replacement of tiny_gl, using the NFOSMesa native
feature of ARAnyM for offscreen rendering.


osmesa.ldg
==========

This is the replacement of mesa_gl, using the NFOSMesa native
feature of ARAnyM for offscreen rendering. It implements all
functions of tiny_gl, and most of the other functions up to
OpenGL standard 4.5 (about 2800 functions).


nfosmesa.xdd
============

This was the MiNT driver used in previous versions. It is no
longer needed.


Installation
============

LDG must be installed for the library to be loaded/usable by
applications. OSMesa is an OpenGL offscreen renderer, i.e. it renders
images using host CPU in RAM. The result is then passed to the Atari
application for final display.

You can then substitute tiny_gl.ldg (or osmesa.ldg, but see BUGS below)
by the version contained in the archive. It is usually located in
c:\gemsys\ldg or the applications directory.

ARAnyM should have been compiled with OpenGL support (which is done by
default if it can be autodetected), and of course also with NFOSMesa
support (which is currently not done by default and has to be enabled
with --enable-nfosmesa).

For OSMesa to operate properly, you must have OSMesa host's libraries
compiled and installed, see the Mesa project page for more
informations. Then, fill the [NFOSMESA] section of the ARAnyM
configuration file: 

[NFOSMESA]
LibGL = /path/to/libGL.so
LibOSMesa = /path/to/libOSMesa.so

LibGL may not be needed on all systems. 
On some systems, the OSMesa interface is already part of the GL library,
this case is auto-detected (and LibOSMesa is not needed)

In previous versions of ARAnyM, there was also a ChannelSize option
to select a different OSMesa version. This is no longer recommended,
and might not be supported in future versions.


NEWS
====

- Both the cygwin and the MacOSX version of ARAnyM support this feature
  now, provided that the hosts native OpenGL library supports render buffers.
  For this to work, you should set the entry 'LibOSMesa' in the 'NFOSMESA'
  section of the config file to an empty string (do not remove it completely,
  that would just use the default value again). If Mesa is not found this way,
  offscreen render buffers will be used instead. Do not use this feature
  with an OpenGL screen window though (set [OPENGL] Enabled = No). Although
  it should work, due to the permanent context switches performance will suffer
  a lot.


BUGS
====

- the exception_error() function of tiny_gl.ldg is exported, but it will
  only be called for certain operations (compatible to the native tiny_gl).
  When using osmesa.ldg, it is a no-op, and you should use glGetError()
  instead to check for errors.

- Due to the design, usually all parameters that are supported by the
  hosts OSMesa library can be set with glEnable() etc. Remember however,
  that a native tiny_gl.ldg will only support a limited set of those.

- Only framebuffers of type OSMESA_RGB (GL_RGB, 24bit RGB) should be
  used currently. This is the format that screen.ldg expects to display
  on the screen, and the only format that the native tiny_gl.ldg supports.
  If you need some other format, you
  a) have to use the full-featured osmesa.ldg
  b) have to make sure that you call glFinish() or glFlush() when done drawing.
     This is the function that converts the host buffer to the
     format you requested. This may or may not also slow down the
     framerate due to the additional conversion step.
  c) are on your own on displaying the result.

- some GLU functions that are exported in the native mesa_gl.ldg are
  not yet implemented.

- Functions that take doubles as arguments might be difficult to call
  from languages other than GNU-C. The library (and also the hosts
  OSMesa library) will expect them to be in 64bit IEEE-754 format.

- If you need OSMesaPostprocess() (a function introduced in Mesa 10.x),
  you cannot use OSMesaCreateLDG(), because that conveniently makes
  the just created context current, and OSMesaPostprocess() must be
  called before that. You should look at lib-oldmesa.c to see what that
  function does and implement your own version in this case.

- TinyGL exports some functions which take float arguments, but the
  original OpenGL functions take doubles as arguments. For compatibility,
  the tiny_gl.ldg exports only the float version, while osmesa.ldg
  exports both. The header files define the OpenGL version to
  the float versions. Functions that are affected by this are
  - gluLookAt
  - glFrustum
  - glOrtho
  - glClearDepth

- Some functions that would return the address of some host buffer
  are currently not implemented at all. These include:
  - OSMesaGetDepthBuffer
  - OSMesaGetColorBuffer
  - glCreateSyncFromCLeventARB
  - glDebugMessageCallback
  - glDebugMessageCallbackAMD
  - glDebugMessageCallbackARB
  - glFenceSync
  - glMapBuffer
  - glMapBufferARB
  - glMapBufferRange
  - glMapObjectBufferATI
  - glMapNamedBuffer{EXT}
  - glMapNamedBufferRange{EXT}
  - glMapTexture2DINTEL
  - glImportSyncEXT
  - glProgramCallbackMESA
  - glTextureRangeAPPLE
  - glGetTexParameterPointervAPPLE
  - glInstrumentsBufferSGIX
  - glVDPAU*

- Parameter checking is not as thorough as in the native implementation.
  If you do something weird, you might crash the emulator.

- Sharing contexts is not supported yet.

- The interface in the tiny_gl.ldg library is not thread-safe; consequently only
  one context can be created at any time (only tiny_gl.ldg is affected by this,
  osmesa.ldg, tiny_gl.slb and osmesa.slb are thread-safe).
  To use more than one context in your application, you have to use osmesa.ldg
  and create the context using OSMesaCreateContextExt.
  Note that the automatically generated loader code still uses some static
  variables to call the actual functions.
  Note also that screen.ldg currently seems to have a problem when called
  from more than 1 process; the examples work around this by using a copy
  of ldg_open() that loads a copy of the shared library instead.

- OSMesaGetProcAddress can now be used as expected (ie. you can use the
  return value as a function pointer), provided that you use the generated
  loader code, but there may be several reasons for the function to fail:
  - You can only lookup functions that are known to the interface code.
    Functions that are defined by a later standard will not be found,
    even if they exist on the host, because the library does not know
    how to call them.
  - The functions must also be known to the shared library that was
    actually loaded, in case the version differs.
  - The function must also be known to ARAnyM. Again, this only matters
    if the interface version differs.
  - And finally, it must be found on the host.

- The loader code is almost as large as the shared library.


ERROR CODES
===========

These codes are passed to the callback function installed with
exception_error (taken from TinyGL):

1L = out of memory (need exit)
2L = list not defined (not need exit)
3L = glGet: option not implemented (not need exit)
4L = glViewport: error while resizing display (need exit)
5L = glViewport: size too small (need exit)
6L = Error allocating specular buffer (need exit)
7L = glTexImage2D: combination of parameters not handled (need exit)
8L = glTexParameter: unsupported option (not need exit)
9L = glPixelStore: unsupported option (need exit)
10L = glBegin: unsupported option (need exit)
11L = No sharing available in TinyGL (not need exit)
12L = zdither: not enough colors (not need exit)
13L = Insufficient memory Perhaps not need to exit
14L = can't save picture (not need exit)

100L = Warning low memory level (<32KB) (not need exit)
101L = Warning internal clipping error (not need exit)
102L = Warning: unknown pname in glGetFloatv()
103L = Warning: glEnableDisable: Option not supported (not need exit)