source: downloads/openal-0.0.8/README @ 17

Contents
========

   * Building OpenAL with autotools
   * Building OpenAL with CMake
   * Notes about the Darwin backend
      + FAQ for the Darwin backend
      + Darwin backend mini-release-notes
      + Darwin backend ToDos
      + Darwin backend test results
   * Notes about the IRIX backend
   * Coding guidelines


Building OpenAL with autotools
==============================

For impatient people the story is:

   ./autogen.sh && ./configure && make install

For more details, have a look at INSTALL or simply read on a bit.

If this is your first time retrieving CVS, you will need to build the
configure script and a few more configuration-related files. To achieve
this, just run:

   ./autogen.sh

You might see quite a few warnings, but they are harmless and are caused
by minor bugs outside OpenAL. If you don't want to see them anymore,
contact your favourite distribution vendor. :-)

After that initial step, configuration and compilation work like this:

   ./configure && make

This assumes that you want to install OpenAL into /usr/local. If you
want something different, give configure a "--prefix=/wherever/you/want"
option.

If you are on x86(_64) if may be wise to send your CFLAGS along to
configure, as dependening on them, SIMD code will be activated, i.e.:

   CFLAGS="-march=athlon-xp" ./configure

configure will detect that "-march=athlon-xp" activates MMX, SSE,
3DNow!, SSE-MMX and 3DNow! extended. You can also explicitly enable a
specific SIMD instruction set via CFLAGS, i.e. "-mmmx" activates MMX on
the GCC compiler (see its manual). Currently OpenAL only features some
MMX code though, so other SIMD instruction set are ignored.  On x86 (32
bit) it is advised to have nasm installed. Then it is safe to activate
all SIMD instruction sets at compile time, as at runtime the detection
will only activate supported SIMD routines. (Above example shouldn't be
used as such though, as it doesn't do any optimization, so send more
flags and/or use the optimization configure option.)

Possible configure options (use --help to determine the rest):

   --enable-more-warnings  enable even more compiler warnings
   --enable-werror         enable failure on all warnings
   --enable-debug          enable debug code and assertions
   ...

Note that the "test" subdirectory has bitrotted, in the future you
should be able to test the build via:

   cd test && make
   [run some tests]

To install OpenAL, just issue:

   make install

If this is your first time installing openal, you'll need to run
ldconfig on some *nices.


Building OpenAL with CMake
==========================

The CMake build files are maintained by prakash@punnoor.de, so if you
have troubles building OpenAL using CMake, please contact me and not the
OpenAL developers, as the official build system is still the one using
autotools. The CMake build files are currenty meant as an additional
possibility to build OpenAL.

The aim of using CMake is making portable development easier, as CMake
containg generators for various build systems. On e.g. *nix Makefiles
will be built, and on Windows MS VC++ project files, if you wish. You
can get CMake at http://cmake.org/.

Current status: The build system is feature complete, so it (should)
build everything as the default one has done.

(+,o,- indicates feature more/same/less then default OpenAL build
system.)

   o builds shared OpenAL lib
   o builds static OpenAL lib; can be deactivated
   o builds the test-suite, if specified
   o all back-ends and vorbis/mp3 extensions should be handled by CMake
   o out of tree builds are supported
   o correct dependency tracking of source files
   + prepared for adding support for non GNU compiler
   (setting link libraries probably needs cleaning up)
   + support for IDE project files generation
   + less time overhead till compilation starts
   + less hassle for user (GUI) and developer (one syntax)

This document explains briefly how to build with CMake on Linux via an
out-of-tree build:

   - Change to the toplevel directory containing the OpenAL sources.
   - Create a directory, e.g. "default", and change into it.
   - Now run something like:

        cmake .. -DCMAKE_INSTALL_PREFIX:STRING="/usr" -DCMAKE_C_FLAGS:STRING="-march=athlon-xp -O2"
        make
        make install

     If you exported your CFLAGS, there is no need to specify them
     explicitly, as CMake will pick them up.

   - OpenAL should get installed as you got used to it.

I really would like to get CMake building OpenAL on every supported
platform. So please contact me if it doesn't build on yours. I'll try to
fix this with your help.

Some tips:

   - You can use a console GUI named ccmake for configuring cmake. This
     also comes in handy, to find out about available options. You can
     also set options via command-line:

        ccmake .. -DCMAKE_INSTALL_PREFIX:STRING="/usr" -DCMAKE_C_FLAGS:STRING="-march=athlon-xp -O2"

     sets the two variables defined on command line and then starts the
     GUI. Press 'c' the first time and every time you want to commit
     changes in the config. Finally press 'g' to run the generator. Btw,
     to set boolean vars from the command line, use -DVAR:BOOL=X, where
     X is eg. ON or OFF.

   - If you want more output at compile time, use

        make VERBOSE=1

   - If you want to install to a different directory (using same
     prefix), use

        make install DESTDIR=/foo/bar

   - CMake doesn't has a distclean target by default, so you better
     really do an out-of-tree build, then you can simply delete its
     content when you want a distclean... Furthermore it is easier to
     have different builds using different parameters via out-of-tree
     builds.

   - If you are interested in variables to set, take a look into
     CMakeCache.txt after having run the configuring stage.

   - If you update your source tree via cvs and want to rebuild an
     previously built lib without cleaning, you better at least clear
     the CMake cache (remove CMakeCache.txt) otherwise a modified CMake
     project file could result to unwanted behaviour.


Notes about the Darwin backend
==============================

FAQ for the Darwin backend
--------------------------

Q : How can I choose the sound card I want for rendering?
A : You can't. The first found is the first used.

Q : MP3 support doesn't work.
A : To enable MP3 exentensions, SDL must be installed. Maybe it works, maybe
not. I don't have nor time neither SDL to test.

Q : The compiler complains about lack of libdl.
A : libdl.dylib is required. You must install it before compiling.

Q : Moving windows or using a big amount of CPU power makes result sound choppy.
A : Increase the number of buffers in "darwin_native.c" and recompile.

Q : There's really too much latency.
A : Decrease the number of buffers in "darwin_native.c" and recompile.

Q : There's really too much latency and result sound choppy.
A : Change your CPU or write a better MOSX implementation than mine !

Q : Why my question is not listed here?
A : Because I can't guess ALL questions ! Ask me directly : gborios@free.fr


Darwin backend mini-release-notes
---------------------------------

Version : Alpha 6
Better bridge between CoreAudio and OpenAL :
=> No choppy sound anymore.
=> Minimum latency.
=> CPU load greatly lowered.
Should work better with different contexts modes (Sample rates, Mono/stereo,
8/16bits), to be tested...

Version : Alpha 5
Support for MOSX 10.1
Better sound buffer copying stuff.
Corrected a bug that caused regular bus errors.

Version : Alpha 3 & 4
Test versions for Garin and me under MOSX Public Beta and 10.0

Version : Alpha 2
Modified buffering system to use n buffers => sounds less choppy when CPU gets
suddenly loaded.
Implemented :
    * void  release_native(),
    * void pause_nativedevice(),
    * void resume_nativedevice().

Version : Alpha 1
First version to play sound !
Implemented :
    * void *grab_write_native(),
    * ALboolean set_write_native(),
    * void  native_blitbuffer().


Darwin backend ToDos
--------------------

   * Implements what's not !

   * Add a preference file to determine which is the default Audio
     Controller (by now, it is the first found).

   * Optimize for Altivec.

   * Clean up everything.

   * Try to make all test programs work.


Darwin backend test results
---------------------------

This is the results of the test programs compiled with alpha 5 version
of the MOSX Backend and the default branch of the OpenAL CVS. I didn't
have time to check deeply each example, but I did it for some.

OK : 31
OK but... : 5
Can't test : 6
FAIL : 11

testalinitexit  OK
testalut        OK
testbufferuniq  OK
testcallback    Can't test (Don't have the test file : "adpcm.adp")
testcapture     Can't test (void *grab_read_native() is not implemented under MOSX).
testchannel     FAIL : Start OK but sound stops quickly (at the 15th iteration actually)
testchannel2    Can't test (int set_nativechannel() & float get_nativechannel() are not implemented under MOSX).
testda  OK
testdevice      OK
testdoppler     OK but can't hear any doppler effect...
testext OK
testgain        OK
testgainlinear  OK
testgendelbuffer_error  OK
testgendelsource_error  OK
testleak        Can't test (Don't have the test file : "adpcm.adp")
testleak2       Can't test (Don't have the test file : "adpcm.adp")
testlistener    OK
testlistener2   OK
testlistener3   OK but can't hear angle modifications...
testlistener4   OK but can't hear angle modifications...
testloop        see problem #1 
testmath        OK, at least I think.
testmp3 FAIL : Could not GetProc alutLoadMP3_LOKI
testmp32        FAIL : Could not GetProc alutLoadMP3_LOKI
testmulti       OK
testmultialut   OK
testmultichannel        OK
testmulticontext        OK
testmulticontext2       OK
testmultimp3    FAIL : Could not GetProc alutLoadMP3_LOKI
testmultinothread       OK, but sounds very bad at the beginning (expected behaviour under MOSX)
testnothread    OK
testorient      OK
testpause       OK
testpitch       OK
testpitch2      FAIL : No sound
testpitch3      OK -> with problem #2 and modif #1
testpitch4      FAIL : No sound
testpitchnothread       OK
testpitchnothread2      OK
testqueue       FAIL ? Over appears before end of source
testqueue2      FAIL ? Over appears before end of source
testqueue3      FAIL ? Over appears before end of source
testrelative    OK, but sound doesn't seem to move
testreverb      OK, but must make 10^5 more micro_sleep to hear sound. Makes me think micro_sleep is broken.
testsingle      OK -> with problem #2 and modif #1
testsourcestop  OK
testsourceuniq  OK
teststartstop   OK
teststream      Can't test (Don't have the test file : "rawpcm.pcm")
teststrings     OK
testtime        FAIL ? Over appears before end of source
testvorbis      FAIL : Could not GetProc alutLoadVorbis_LOKI


Problems :

#1 : It seems something goes wrong with AL_LOOPING. in testloop : after
alSourceStop() AL_LOOPING is set to false even before we explicitely set
it. then we set it to false in the test app, and asking for the loop
state is OK (returns false). then we call alSourcePlay() and ask again
for the looping state : it has been now strangely reseted to true. The
solution is to change the looping value whiel the source is still
playing, but is this a normal behaviour? I guess no.

#2 : when a mixer source is destroyed, the bid_queue.read_index of the
attached source is set to the size of the bid_queue. So when
reallocating a new mix source for the same source, the bid is invalid
because bid queue read index is out of range (1buffer too far). See
modif #1 for a solution.

Modifications :

#1 : al_mixer.c, line 719 : mixer modif when reallocating for a stopped
source -> I guess this is the modif Joe made Monday.


Notes about the IRIX backend
============================

Only Indy, Indogo2 and Onyx Audio/Serial Option (ASO) can natively
handle 4 channel (surround sound) audio.

Adding 4 channel audio support is possible by adding the following
definition to your ~/.openalrc file:

   (define speaker-num 4) 

It is also possible to specify the default output port by adding the
following definition:

   (define native-out-device "Analog Out")

When your system doesn't support four channel audio by default, but it
does contain (at least) two different output ports you could enable four
channel audio by defining two separate ports:

   (define native-out-device "Analog Out")
   (define native-rear-out-device "Analog Out 2")

or alternatively by selecting two different interfaces:

   (define native-out-device "A3.Speaker")
   (define native-rear-out-device "A3.LineOut2")

See "man 3dm alResources" for more information.


Coding guidelines
=================

Coding guidelines are a very sensitive topic and can easily lead to
almost religious discussions. Always remember that they are not invented
to torment developers, but to ease collaboration by avoiding useless
creativity. The following items are not a complete list, they are only a
few things to bear in mind. Furthermore, note that most of the current
code does not yet adhere to these rules, so at least try to follow these
guidelines when writing new code.

   * To avoid endless formatting discussions and guarantee consistency,
     use GNU indent with the configuration file located at
     admin/autotools/.indent.pro. There is even a make target "indent"
     which does this automatically for the whole source tree.

   * The code should be kept as warning-free as possible, but don't
     simply silence the compiler by e.g. casting without thinking first.

   * C has only very poor namespace support, so to avoid accidental
     name clashes we need some naming conventions. Something to bear in
     mind is that macros and symbols starting with an underscore are
     reserved for the C compiler, so we should not use this. The
     following is a list of conventions for the AL part only, the ALC
     part should be handled accordingly:

      + Quite obviously, globally visible functions from the OpenAL spec
        have the form "alFooBar" and official macros have the form
        "AL_FOO_BAR".

      + Globally visible functions and variables not in the OpenAL spec
        must have the form "alFooBar_" to keep the global namespace
        clean.

      + Internal types must have the form "AL_FooBar".

      + Internal macros and enum values "AL_FOO_BAR_"

      + C structs have their own namespaces, so we need no funny
        prefixes or suffixes here and can simply use "fooBar".

   * A header file named "foo/bar.h" should be protected against
     multiple inclusion via an "AL_FOO_BAR_H_" macro.

Please feel free to add some more items to the guidelines above...