windows audio README.md file

audio/windows/README.md

@@ -0,0 +1,88 @@
+# Audio libraries for Windows
+
+The G3N engine audio support currently depends on the following external libraries:
+
+- `OpenAL`        - for spatial audio
+- `libogg`        - for Ogg container format
+- `libvorbis`     - for vorbis decoder support
+- `libvorbisfile` - for reading/decoding ogg vorbis files
+
+These libraries are easily installed in Linux systems using the distribution package manager.
+
+For compiling `G3N` for windows, the directory `<GOPATH>/src/github.com/g3n/engine/audio/windows`
+contains the sources of these libraries, and the subdirectory `bin` contains compiled `dlls`,
+used during the link process. For running an application which uses `G3N`, you will need
+to copy these dlls to the directory from which will run your application.
+It is recommended to avoid copying them to the Windows system directory.
+
+The library sources were obtained from:
+```
+http://kcat.strangesoft.net/openal-releases/openal-soft-1.18.2.tar.bz2
+http://downloads.xiph.org/releases/ogg/libogg-1.3.3.zip
+http://downloads.xiph.org/releases/vorbis/libvorbis-1.3.5.zip
+```
+
+The original file `libvorbis-1.3.3/win32/VS2010/libogg.props` was changed to setup
+`libogg` version and location.
+
+If you want to build the `dlls` from source instead of using the supplied `dlls` you
+can use the following procedure:
+
+1. Download and install *Microsoft Studio Community* from https://www.visualstudio.com/downloads/.
+   Under the *Workloads* tab, select ***Desktop development with C++***.
+   We are assuming here that *Microsoft Studio 2017* will be used. If you are using the previous
+   version of *Microsoft Studio* replace *Microsoft Studio 15 2017* by *Microsoft Studio 14 2015*
+   in the *CMake* command line in item 4.
+
+2. Download and install *CMake* from https://cmake.org/download/.
+
+3. Execute the *Developer Command Prompt for VS 2017* (or the equivalent for the 2015 version)
+   installed by *Microsoft Visual Studio*.
+   It is a command prompt window with environment variables correctly initialized to use
+   the MS compiler and tools.
+
+4. In the command prompt navigate to the *build* directory inside the *openal-soft-1.18.2* directory, and then execute:
+   ```
+   >mkdir build
+   >cd build
+   >cmake -G "Visual Studio 15 2017 Win64" ..
+   ``` 
+  
+   It is important to check in the messages generated by *CMake* that *OpenAL* will be built
+   with support for *DirectSound*.
+   If everything is OK, a file named `OpenAL.sln` should have been generated in this
+   directory (along with many others).
+
+5. Execute *Visual Studio* and from its menu select *Open -> Project/Solution...*.
+   Select the file `OpenAL.sln` generated previously by *CMake*.
+   In the *Visual Studio* toolbar, below the menu, select the build mode *Release*
+   and *x64* architecture.
+   Then select *Build -> Build Solution* in the menu to start the build.
+   Once the build is complete the file `OpenAL.dll` should have been generated in the directory `build/Release`.
+    
+6. Execute *Visual Studio* and from its menu select *Open -> Project/Solution...*.
+   Select the file `libogg-1.3.3\win32\VS2015\libogg_dynamic.sln`.
+   In the *Visual Studio* toolbar, below the menu, select the build mode *Release*
+   and *x64* architecture.
+   Then select the menu *Build -> Build Solution* to start the build.
+   If during the build *Visual Studio* indicates an error related to
+   the installed platform toolset you may need to retarget the solution,
+   selecting the menu *Project -> Retarget solution"* and then try to build again.
+   If everything goes OK then `libogg.dll` should be in the directory:
+   `libogg-1.3.3\win32\VS2015\x64\Release`.
+
+7. Execute *Visual Studio* and from its menu select *Open -> Project/Solution...*.
+   Select the file `libvorbis-1.3.5\win32\VS2010\vorbis_dynamic.sln`.
+   In the *Visual Studio* toolbar, below the menu, select the build mode *Release*
+   and *x64* architecture.
+   Then select the menu *Build -> Build Solution* to start the build.
+   If during the build *Visual Studio* indicates an error related to
+   the installed platform toolset you may need to retarget the solution,
+   selecting the menu *Project -> Retarget solution"* and then try the build again.
+   If everything goes OK, then `libvorbis.dll` and `libvorbisfile.dll` should be in the directory:
+   `libvorbis-1.3.5\win32\VS2010\x64\Release`.
+
+8. Copy the dlls: `OpenAL32.dll, libogg.dll, libvorbis.dll` and `libvorbisfile.dll`
+   to the directory from which you will execute a G3N application.
+
+