diff options
Diffstat (limited to 'libs/joal.README.md')
| -rw-r--r-- | libs/joal.README.md | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/libs/joal.README.md b/libs/joal.README.md new file mode 100644 index 0000000..d566099 --- /dev/null +++ b/libs/joal.README.md @@ -0,0 +1,180 @@ +# JOAL, OpenAL API Binding for Java™ + +[Original document location](https://jogamp.org/cgit/joal.git/about/) + +## Git Repository +This project's canonical repositories is hosted on [JogAmp](https://jogamp.org/cgit/joal.git/). + +## Overview +The [*JOAL Project*](https://jogamp.org/joal/www/) hosts a reference implementation of the +Java bindings for [OpenAL API](http://www.openal.org/), and is designed to provide +hardware-supported 3D spatialized audio for applications written in Java. + +This project also hosts the Sound3D Toolkit, a high level +API for spatialized audio built on top of the OpenAL bindings. +This toolkit is designed to provide access to all the features +of OpenAL through an intuitive, easy to use, object-oriented interface. + +JOAL is part of [the JogAmp project](https://jogamp.org). + +**The JogAmp project needs funding and we offer [commercial support](https://jogamp.org/wiki/index.php?title=Maintainer_and_Contacts#Commercial_Support)!**<br/> +Please contact [Göthel Software (Jausoft)](https://jausoft.com/). + +### License +See [LICENSE.txt](LICENSE.txt). + +## Platform Support +JOAL is tested against [OpenAL-Soft](https://openal-soft.org/) ([github repo](https://github.com/kcat/openal-soft/)), +the cross-platform, software implementation of the OpenAL 3D audio API. + +See OpenAL-Soft [environment variables](https://github.com/kcat/openal-soft/blob/master/docs/env-vars.txt) +and [configuration example](https://github.com/kcat/openal-soft/blob/master/alsoftrc.sample). + +All JOAL platform builds contain a self-build native library of [OpenAL-Soft](https://openal-soft.org/), +version [**v1.23.1** *from our fork*](https://jogamp.org/cgit/openal-soft.git/). + +Our builds expose the following audio backends: + +### GNU/Linux +- PipeWire +- PulseAudio +- ALSA +- OSS +- SndIO (linked) +- WaveFile +- Null + +### Android/Linux +- PipeWire +- OpenSL +- WaveFile +- Null + +### Windows +- WinMM +- DirectSound +- WASAPI +- WaveFile +- Null + +### MacOS +- CoreAudio +- WaveFile +- Null + +## Build Requirements +This project has been built under Win32, GNU/Linux, Android/Linux and MacOS. + +Check [GlueGen's HowToBuild](https://jogamp.org/gluegen/doc/HowToBuild.html) +for basic prerequisites. + +Additionally the following packages and tools have been used: + +* All Systems: + - See [GlueGen's HowToBuild](https://jogamp.org/gluegen/doc/HowToBuild.html) + - [OpenAL-Soft](https://openal-soft.org/) ([github repo](https://github.com/kcat/openal-soft/)) + +* Windows: + - [CMake 3.15.2](https://cmake.org/download/) + - OpenAL Soft: Audio-Backends: WinMM, DirectSound, WASAPI, WaveFile, Null + +* GNU/Linux: + - cmake + - OpenAL Soft: OpenAL: PipeWire, PulseAudio, ALSA, OSS, SndIO (linked), WaveFile, Null +``` + apt-get install cmake autoconf \ + libpipewire-0.3-dev \ + libpulse-dev libpulse0:amd64 libpulse0:i386 pulseaudio \ + libsndio-dev \ + libasound2-dev libasound2:amd64 libasound2:i386 +``` + On Debian 11 Bullseye, use bullseye-backports `apt -t bullseye-backports install libpipewire-0.3-dev` + to have libpipewire-0.3>=0.3.23, i.e. version 0.3.65. + +* Android/Linux: + - cmake + - OpenAL Soft: Audio-Backends: PipeWire, OpenSL, WaveFile, Null + +* OSX + - OSX 10.2 or later + - OSX Developer Tools Xcode + - CMake 3.15.2 <https://cmake.org/download/> + and install the commandline tools <https://stackoverflow.com/questions/30668601/installing-cmake-command-line-tools-on-a-mac> + - OpenAL Soft: Audio-Backends: CoreAudio, WaveFile, Null + +JOAL requires the GlueGen workspace to be checked out as a sibling +directory to the joal directory. +See GlueGen's HowToBuild <https://jogamp.org/gluegen/doc/HowToBuild.html> + +## Directory Organization: +``` +make/ Build-related files and the main build.xml +src/ The actual source for the JOAL APIs. +src/test/ A couple of small tests +build/ (generated directory) Where the Jar and DLL files get built to +www/ JOAL project webpage files +``` + +## GIT +JOAL can be build w/ openal-soft, which is a git submodule of JOAL. +This is the default for our JogAmp build on all platforms. + +Cloning [and pulling] JOAL incl. openal-soft +can be performed w/ the option '--recurse-submodules'. +``` + > cd /home/dude/projects/jogamp/ + > git clone --recurse-submodules git://jogamp.org/srv/scm/joal.git + > cd joal ; git pull --recurse-submodules +``` + +## JOAL Build Instructions: +Change into the joal/make directory +``` + > cd /home/dude/projects/jogamp/make/ +``` + +To clean: +``` + > ant clean +``` + +To build: +``` + > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar +``` + +To build docs: +``` + > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar javadoc +``` + +To test: +``` + > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar runtests +``` + +Instead of properties, you may also use environment variables, +see GlueGen's HowToBuild <https://jogamp.org/gluegen/doc/HowToBuild.html>. + +## Contact Us +- JogAmp [http://jogamp.org/](http://jogamp.org/) +- JOAL Web [http://jogamp.org/](http://jogamp.org/joal/) +- Forum/Mailinglist [http://forum.jogamp.org/](http://forum.jogamp.org/) +- Repository [http://jogamp.org/git/](http://jogamp.org/git/) +- Wiki [https://jogamp.org/wiki/](https://jogamp.org/wiki/) +- Maintainer [https://jogamp.org/wiki/index.php/Maintainer_and_Contacts](https://jogamp.org/wiki/index.php/Maintainer_and_Contacts) +- Sven's Blog [https://jausoft.com/blog/tag/jogamp/](https://jausoft.com/blog/tag/jogamp/) +- Email sgothel _at_ jausoft _dot_ com + +## Acknowledgments +Original JOAL and Sound3D authors + +- Athomas Goldberg +- Wildcard +- Java Games Initiative +- Software Advanced Technologies Group +- Sun Microsystems + +Since roughly 2010, JOAL development has been continued +by individuals of the JogAmp community, see git log for details. + |