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