Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/openal-0.0.8/README @ 17

Last change on this file since 17 was 17, checked in by landauf, 17 years ago

added openal

File size: 14.2 KB
Line 
1Contents
2========
3
4   * Building OpenAL with autotools
5   * Building OpenAL with CMake
6   * Notes about the Darwin backend
7      + FAQ for the Darwin backend
8      + Darwin backend mini-release-notes
9      + Darwin backend ToDos
10      + Darwin backend test results
11   * Notes about the IRIX backend
12   * Coding guidelines
13
14
15Building OpenAL with autotools
16==============================
17
18For impatient people the story is:
19
20   ./autogen.sh && ./configure && make install
21
22For more details, have a look at INSTALL or simply read on a bit.
23
24If this is your first time retrieving CVS, you will need to build the
25configure script and a few more configuration-related files. To achieve
26this, just run:
27
28   ./autogen.sh
29
30You might see quite a few warnings, but they are harmless and are caused
31by minor bugs outside OpenAL. If you don't want to see them anymore,
32contact your favourite distribution vendor. :-)
33
34After that initial step, configuration and compilation work like this:
35
36   ./configure && make
37
38This assumes that you want to install OpenAL into /usr/local. If you
39want something different, give configure a "--prefix=/wherever/you/want"
40option.
41
42If you are on x86(_64) if may be wise to send your CFLAGS along to
43configure, as dependening on them, SIMD code will be activated, i.e.:
44
45   CFLAGS="-march=athlon-xp" ./configure
46
47configure will detect that "-march=athlon-xp" activates MMX, SSE,
483DNow!, SSE-MMX and 3DNow! extended. You can also explicitly enable a
49specific SIMD instruction set via CFLAGS, i.e. "-mmmx" activates MMX on
50the GCC compiler (see its manual). Currently OpenAL only features some
51MMX code though, so other SIMD instruction set are ignored.  On x86 (32
52bit) it is advised to have nasm installed. Then it is safe to activate
53all SIMD instruction sets at compile time, as at runtime the detection
54will only activate supported SIMD routines. (Above example shouldn't be
55used as such though, as it doesn't do any optimization, so send more
56flags and/or use the optimization configure option.)
57
58Possible configure options (use --help to determine the rest):
59
60   --enable-more-warnings  enable even more compiler warnings
61   --enable-werror         enable failure on all warnings
62   --enable-debug          enable debug code and assertions
63   ...
64
65Note that the "test" subdirectory has bitrotted, in the future you
66should be able to test the build via:
67
68   cd test && make
69   [run some tests]
70
71To install OpenAL, just issue:
72
73   make install
74
75If this is your first time installing openal, you'll need to run
76ldconfig on some *nices.
77
78
79Building OpenAL with CMake
80==========================
81
82The CMake build files are maintained by prakash@punnoor.de, so if you
83have troubles building OpenAL using CMake, please contact me and not the
84OpenAL developers, as the official build system is still the one using
85autotools. The CMake build files are currenty meant as an additional
86possibility to build OpenAL.
87
88The aim of using CMake is making portable development easier, as CMake
89containg generators for various build systems. On e.g. *nix Makefiles
90will be built, and on Windows MS VC++ project files, if you wish. You
91can get CMake at http://cmake.org/.
92
93Current status: The build system is feature complete, so it (should)
94build everything as the default one has done.
95
96(+,o,- indicates feature more/same/less then default OpenAL build
97system.)
98
99   o builds shared OpenAL lib
100   o builds static OpenAL lib; can be deactivated
101   o builds the test-suite, if specified
102   o all back-ends and vorbis/mp3 extensions should be handled by CMake
103   o out of tree builds are supported
104   o correct dependency tracking of source files
105   + prepared for adding support for non GNU compiler
106   (setting link libraries probably needs cleaning up)
107   + support for IDE project files generation
108   + less time overhead till compilation starts
109   + less hassle for user (GUI) and developer (one syntax)
110
111This document explains briefly how to build with CMake on Linux via an
112out-of-tree build:
113
114   - Change to the toplevel directory containing the OpenAL sources.
115   - Create a directory, e.g. "default", and change into it.
116   - Now run something like:
117
118        cmake .. -DCMAKE_INSTALL_PREFIX:STRING="/usr" -DCMAKE_C_FLAGS:STRING="-march=athlon-xp -O2"
119        make
120        make install
121
122     If you exported your CFLAGS, there is no need to specify them
123     explicitly, as CMake will pick them up.
124
125   - OpenAL should get installed as you got used to it.
126
127I really would like to get CMake building OpenAL on every supported
128platform. So please contact me if it doesn't build on yours. I'll try to
129fix this with your help.
130
131Some tips:
132
133   - You can use a console GUI named ccmake for configuring cmake. This
134     also comes in handy, to find out about available options. You can
135     also set options via command-line:
136
137        ccmake .. -DCMAKE_INSTALL_PREFIX:STRING="/usr" -DCMAKE_C_FLAGS:STRING="-march=athlon-xp -O2"
138
139     sets the two variables defined on command line and then starts the
140     GUI. Press 'c' the first time and every time you want to commit
141     changes in the config. Finally press 'g' to run the generator. Btw,
142     to set boolean vars from the command line, use -DVAR:BOOL=X, where
143     X is eg. ON or OFF.
144
145   - If you want more output at compile time, use
146
147        make VERBOSE=1
148
149   - If you want to install to a different directory (using same
150     prefix), use
151
152        make install DESTDIR=/foo/bar
153
154   - CMake doesn't has a distclean target by default, so you better
155     really do an out-of-tree build, then you can simply delete its
156     content when you want a distclean... Furthermore it is easier to
157     have different builds using different parameters via out-of-tree
158     builds.
159
160   - If you are interested in variables to set, take a look into
161     CMakeCache.txt after having run the configuring stage.
162
163   - If you update your source tree via cvs and want to rebuild an
164     previously built lib without cleaning, you better at least clear
165     the CMake cache (remove CMakeCache.txt) otherwise a modified CMake
166     project file could result to unwanted behaviour.
167
168
169Notes about the Darwin backend
170==============================
171
172FAQ for the Darwin backend
173--------------------------
174
175Q : How can I choose the sound card I want for rendering?
176A : You can't. The first found is the first used.
177
178Q : MP3 support doesn't work.
179A : To enable MP3 exentensions, SDL must be installed. Maybe it works, maybe
180not. I don't have nor time neither SDL to test.
181
182Q : The compiler complains about lack of libdl.
183A : libdl.dylib is required. You must install it before compiling.
184
185Q : Moving windows or using a big amount of CPU power makes result sound choppy.
186A : Increase the number of buffers in "darwin_native.c" and recompile.
187
188Q : There's really too much latency.
189A : Decrease the number of buffers in "darwin_native.c" and recompile.
190
191Q : There's really too much latency and result sound choppy.
192A : Change your CPU or write a better MOSX implementation than mine !
193
194Q : Why my question is not listed here?
195A : Because I can't guess ALL questions ! Ask me directly : gborios@free.fr
196
197
198Darwin backend mini-release-notes
199---------------------------------
200
201Version : Alpha 6
202Better bridge between CoreAudio and OpenAL :
203=> No choppy sound anymore.
204=> Minimum latency.
205=> CPU load greatly lowered.
206Should work better with different contexts modes (Sample rates, Mono/stereo,
2078/16bits), to be tested...
208
209Version : Alpha 5
210Support for MOSX 10.1
211Better sound buffer copying stuff.
212Corrected a bug that caused regular bus errors.
213
214Version : Alpha 3 & 4
215Test versions for Garin and me under MOSX Public Beta and 10.0
216
217Version : Alpha 2
218Modified buffering system to use n buffers => sounds less choppy when CPU gets
219suddenly loaded.
220Implemented :
221    * void  release_native(),
222    * void pause_nativedevice(),
223    * void resume_nativedevice().
224
225Version : Alpha 1
226First version to play sound !
227Implemented :
228    * void *grab_write_native(),
229    * ALboolean set_write_native(),
230    * void  native_blitbuffer().
231
232
233Darwin backend ToDos
234--------------------
235
236   * Implements what's not !
237
238   * Add a preference file to determine which is the default Audio
239     Controller (by now, it is the first found).
240
241   * Optimize for Altivec.
242
243   * Clean up everything.
244
245   * Try to make all test programs work.
246
247
248Darwin backend test results
249---------------------------
250
251This is the results of the test programs compiled with alpha 5 version
252of the MOSX Backend and the default branch of the OpenAL CVS. I didn't
253have time to check deeply each example, but I did it for some.
254
255OK : 31
256OK but... : 5
257Can't test : 6
258FAIL : 11
259
260testalinitexit  OK
261testalut        OK
262testbufferuniq  OK
263testcallback    Can't test (Don't have the test file : "adpcm.adp")
264testcapture     Can't test (void *grab_read_native() is not implemented under MOSX).
265testchannel     FAIL : Start OK but sound stops quickly (at the 15th iteration actually)
266testchannel2    Can't test (int set_nativechannel() & float get_nativechannel() are not implemented under MOSX).
267testda  OK
268testdevice      OK
269testdoppler     OK but can't hear any doppler effect...
270testext OK
271testgain        OK
272testgainlinear  OK
273testgendelbuffer_error  OK
274testgendelsource_error  OK
275testleak        Can't test (Don't have the test file : "adpcm.adp")
276testleak2       Can't test (Don't have the test file : "adpcm.adp")
277testlistener    OK
278testlistener2   OK
279testlistener3   OK but can't hear angle modifications...
280testlistener4   OK but can't hear angle modifications...
281testloop        see problem #1
282testmath        OK, at least I think.
283testmp3 FAIL : Could not GetProc alutLoadMP3_LOKI
284testmp32        FAIL : Could not GetProc alutLoadMP3_LOKI
285testmulti       OK
286testmultialut   OK
287testmultichannel        OK
288testmulticontext        OK
289testmulticontext2       OK
290testmultimp3    FAIL : Could not GetProc alutLoadMP3_LOKI
291testmultinothread       OK, but sounds very bad at the beginning (expected behaviour under MOSX)
292testnothread    OK
293testorient      OK
294testpause       OK
295testpitch       OK
296testpitch2      FAIL : No sound
297testpitch3      OK -> with problem #2 and modif #1
298testpitch4      FAIL : No sound
299testpitchnothread       OK
300testpitchnothread2      OK
301testqueue       FAIL ? Over appears before end of source
302testqueue2      FAIL ? Over appears before end of source
303testqueue3      FAIL ? Over appears before end of source
304testrelative    OK, but sound doesn't seem to move
305testreverb      OK, but must make 10^5 more micro_sleep to hear sound. Makes me think micro_sleep is broken.
306testsingle      OK -> with problem #2 and modif #1
307testsourcestop  OK
308testsourceuniq  OK
309teststartstop   OK
310teststream      Can't test (Don't have the test file : "rawpcm.pcm")
311teststrings     OK
312testtime        FAIL ? Over appears before end of source
313testvorbis      FAIL : Could not GetProc alutLoadVorbis_LOKI
314
315
316Problems :
317
318#1 : It seems something goes wrong with AL_LOOPING. in testloop : after
319alSourceStop() AL_LOOPING is set to false even before we explicitely set
320it. then we set it to false in the test app, and asking for the loop
321state is OK (returns false). then we call alSourcePlay() and ask again
322for the looping state : it has been now strangely reseted to true. The
323solution is to change the looping value whiel the source is still
324playing, but is this a normal behaviour? I guess no.
325
326#2 : when a mixer source is destroyed, the bid_queue.read_index of the
327attached source is set to the size of the bid_queue. So when
328reallocating a new mix source for the same source, the bid is invalid
329because bid queue read index is out of range (1buffer too far). See
330modif #1 for a solution.
331
332Modifications :
333
334#1 : al_mixer.c, line 719 : mixer modif when reallocating for a stopped
335source -> I guess this is the modif Joe made Monday.
336
337
338Notes about the IRIX backend
339============================
340
341Only Indy, Indogo2 and Onyx Audio/Serial Option (ASO) can natively
342handle 4 channel (surround sound) audio.
343
344Adding 4 channel audio support is possible by adding the following
345definition to your ~/.openalrc file:
346
347   (define speaker-num 4)
348
349It is also possible to specify the default output port by adding the
350following definition:
351
352   (define native-out-device "Analog Out")
353
354When your system doesn't support four channel audio by default, but it
355does contain (at least) two different output ports you could enable four
356channel audio by defining two separate ports:
357
358   (define native-out-device "Analog Out")
359   (define native-rear-out-device "Analog Out 2")
360
361or alternatively by selecting two different interfaces:
362
363   (define native-out-device "A3.Speaker")
364   (define native-rear-out-device "A3.LineOut2")
365
366See "man 3dm alResources" for more information.
367
368
369Coding guidelines
370=================
371
372Coding guidelines are a very sensitive topic and can easily lead to
373almost religious discussions. Always remember that they are not invented
374to torment developers, but to ease collaboration by avoiding useless
375creativity. The following items are not a complete list, they are only a
376few things to bear in mind. Furthermore, note that most of the current
377code does not yet adhere to these rules, so at least try to follow these
378guidelines when writing new code.
379
380   * To avoid endless formatting discussions and guarantee consistency,
381     use GNU indent with the configuration file located at
382     admin/autotools/.indent.pro. There is even a make target "indent"
383     which does this automatically for the whole source tree.
384
385   * The code should be kept as warning-free as possible, but don't
386     simply silence the compiler by e.g. casting without thinking first.
387
388   * C has only very poor namespace support, so to avoid accidental
389     name clashes we need some naming conventions. Something to bear in
390     mind is that macros and symbols starting with an underscore are
391     reserved for the C compiler, so we should not use this. The
392     following is a list of conventions for the AL part only, the ALC
393     part should be handled accordingly:
394
395      + Quite obviously, globally visible functions from the OpenAL spec
396        have the form "alFooBar" and official macros have the form
397        "AL_FOO_BAR".
398
399      + Globally visible functions and variables not in the OpenAL spec
400        must have the form "alFooBar_" to keep the global namespace
401        clean.
402
403      + Internal types must have the form "AL_FooBar".
404
405      + Internal macros and enum values "AL_FOO_BAR_"
406
407      + C structs have their own namespaces, so we need no funny
408        prefixes or suffixes here and can simply use "fooBar".
409
410   * A header file named "foo/bar.h" should be protected against
411     multiple inclusion via an "AL_FOO_BAR_H_" macro.
412
413Please feel free to add some more items to the guidelines above...
Note: See TracBrowser for help on using the repository browser.