Tutorial 01 :
FMOD Ex/NativeFmodEx Introduction

•  Introduction

This tutorial an introduction to FMOD Ex audio system in Java using NativeFmodEx, and how to install and use them.

NativeFmodEx now includes an installer, which imports all necessary file from FMOD Ex installation (FMOD Ex also includes an installer).
This will certainly help you make NativeFmodEx works on your computer.
 

•  NativeFmodEx

•  What is FMOD Ex ?

'The FMOD Ex sound system is a revolutionary new audio engine for game developers, multimedia developers, sound designers, musicians and audio engineers, based on the years of experienced of Firelight Technologies previous product FMOD.'

FMOD Ex
Firelight Technologies

http://www.fmod.org/

Firelight Technologies also introduce a new tool based on FMOD Ex API : FMOD Designer.

'FMOD Designer is a tool for creating complex audio events for playback with the FMOD Ex Music and Sound Effects System. It allows the sound designer to model real-world sounds using layering, cross-fading, DSP effects and randomized behaviour. It also allows the programmer to dynamically control these events at runtime in order to realize a rich, interactive soundscape.'

FMOD Designer
Firelight Technologies
 

•  What is NativeFmodEx ?

Like for FMOD, FMOD Ex API does not have a support for the java programming language.
Like for NativeFmod project, NativeFmodEx is here to made the bridge between Java and FMOD (C/C++ library).

I've starten this project at the end of February 2005, when FMOD Ex was in alpha development stage (4.00.16). Someone ask me if I plan to make a Java support for FMOD Ex, like for FMOD. That's when this project was created.


Like NativeFmod, NativeFmodEx is based on JNI Java Native Interface API. I've completely write NativeFmodEx by my own (no SWIG). This project benefit of the experience acquired with NativeFmod. I've created a cleaner and more professional project (I know this was not the case for NativeFmod project at start and during lot of versions).
The first public version of NativeFmodEx was available next month of its creation. The first stable version was available in August, after 5 months of active development !

Now, NativeFmodEx is updated when major changes/bug fix are performed on FMOD Ex API.
 

•  Installation

First download the last NativeFmodEx API and FMOD Ex API. If it is the first time you use NativeFmodEx, I advice you to download NativeFmodEx Sdk (Runtime + examples).
Extract NativeFmodEx and install FMOD Ex in any folder you want.

An installer is provided with the Sdk distribution, with many examples ready-to-run (about 30 examples). Those examples are the example distributed with FMOD Ex and ported by me to Java.

See the file NATIVEFMODEX_FOLDER/Examples/Examples_Readme.txt for informations on particular examples. Read this for some help to run examples externaly to the installer or in your own platform (installer supports only windows, linux/mac platforms will be added when I will have free time).


Here are the files needed for using NativeFmodEx in your application :
   NATIVEFMODEX_FOLDER/lib/NativeFmodEx.jar
   NATIVEFMODEX_FOLDER/lib/NativeFmodEx.dll             [Windows only]
   NATIVEFMODEX_FOLDER/lib/libNativeFmodEx.so           [Linux only]
   NATIVEFMODEX_FOLDER/lib/libNativeFmodEx.jnilib       [Mac only]
   FMODEX_FOLDER/api/fmodex.dll                         [Windows only]
   FMODEX_FOLDER/api/libfmodex.so                       [Linux only]
   FMODEX_FOLDER/api/libfmodex.jnilib                   [Mac only]   //jnilib is the universal library distributed here without any warranty !

If you also want to use FMOD Designer (org.jouvieje.FmodDesigner), you will need to use those files :
   NATIVEFMODEX_FOLDER/lib/NativeFmodDesigner.jar
   NATIVEFMODEX_FOLDER/lib/NativeFmodDesigner.dll       [Windows only]
   NATIVEFMODEX_FOLDER/lib/libNativeFmodDesigner.so     [Linux only]
   NATIVEFMODEX_FOLDER/lib/libNativeFmodDesigner.jnilib [Mac only]
   FMODEX_FOLDER/api/fmod_event_net.dll                 [Windows only]
   FMODEX_FOLDER/api/libfmodevent.so                    [Linux only]
   FMODEX_FOLDER/api/libfmodevent.jnilib                [Mac only]   //jnilib is the universal library distributed here without any warranty !

There is two ways for installing NativeFmodEx : in your JDK/JRE or directly with your application.
The advantage of the second way is that we don't need to have access to JDK/JRE (ie don't need administrator rights), so this will works everywhere (ie every computer and platforms supported).

Note : libfmodex.jnilib & libfmodevent.jnilib are universal libraries build (by me)
 

•  First way : Installation in the JDK/JRE [DISENCOURAGED]

JRE_FOLDER point towards jre folder of JDK (Java Development Kit) or JRE (Java Runtime Environment).
For example, on Windows platform, it can be :
  C:\Java\jdk1.4.2_09\jre\    [JDK]
or :
  C:\Java\jdk1.4.2_09\        [JRE]

Copy all jars into the folder :
  JRE_FOLDER/lib/ext
Copy the libraries (dll/so/jnilib) for your platform here :
  JRE_FOLDER/bin/             [Windows - dll]
  JRE_FOLDER/lib/i386/        [Linux   - so]
  JRE_FOLDER/***/             [Mac     - dylib/jnilib]

Now, you're ready to use FMOD Ex with Java !
 

•  Second way : Installation in your application [PREFERED WAY]

You can also install NativeFmodEx outside Java SDK/JRE.
This is usefull if you don't have access to the JDK/JRE, for deploying your application on another station, for including NativeFmodEx directly with your application ...

For this put all jars and libraries in a folder (refered by LIB_FOLDER).
At runtime, you will have to indicates where NativeFmodEx is. This can be done using java.library.path and classpath like this :

This way is also easier for multi-platform deployment. Simply put all files mentionned above and NativeFmodEx will choose the right file.
At start, NativeFmodEx will search the library in java.library.path folder and system dependant library folder.

If you use a development environment like Eclipse or NetBeans, NativeFmodEx jars and libraries can be linked directly to your project.
 

•  Using NativeFmodEx

Now, you have install NativeFmodEx and you probably want to use/try it.

To begin we will see how to run examples included in NativeFmodEx SDK. Then, we will see how to creates project under Eclipse et NetBean IDE.
 

•  Running examples

Examples are written with Java 1.5 (also called Java 5). Due to they use the new java syntax, you will need Java 1.5 for executing them.
If you have older versions of Java, don't be worry, NativeFmodEx is written and compatible with Java 1.4.

[Read Linux version]

To run an examples, just double click on one Batch file from SDK distribution (*.bat). To know what is the java command used to run the example, just open the file with a text editor.

If the example don't run and you have a similar error (I don't know exactly the error displayed under an english system) :

Read Installation of Java.

You can also execute them using a DOS terminal ("Invite de commande" in french) with Start/Execute/cmd.exe.
Go to the NativeFmodEx examples folder using the 'cd' commande.
Then execute an example using this script :

Replace <example_name> by the name of the examples ie ChannelGroups, Effects, PlaySound, PlayStream, ...

Here is a capture for PlaySound example :

Run PlaySound

Warning :
Some examples like CDPlayer and NetStream needs extras parameter :
   java ... .Examples.CDPlayer f
   java ... .Examples.NetStream http://jerome.jouvie.free.fr/downloads/NativeFmod/jules.mp3

For FMOD Designer examples, use this script :

  

[Read Linux version]

•  Eclipse - Create a Project that use NativeFmodEx

This part is dedicated to the wonderfull Java development environment : Eclipse.

Extract the examples and create a new project named "First NativeFmodEx Project" from the folder :
   NATIVEFMODEX_FOLDER/Src/Examples
(Copy the folder Media and SimpleEventMedia from NATIVEFMODEX_FOLDER/Examples to get the musics needed by the examples. You should have imported them from FMOD Ex distribution with Installer.jar )

If you don't have installed NativeFmodEx in JDK/JRE, a lot of errors should be printed (org.jouvieje.FmodEx.* cannot be resolved ...). But no worry, we will see how to fix all these errors.

Your workspace should looks like this :

Eclipse workspace (1)

Now, you have to points NativeFmodEx to your project.
There is a cool way for this under Eclipse. Use 'User Library' feature :
    Windows->Preferences->Java->Build Path->User Libraries

Create a new user library named "NativeFmodEx" :

Create NativeFmodEx library

Then, click on "Add JARs" button and select NativeFmodEx.jar and NativeFmodDesigner.jar from NATIVEFMODEX_FOLDER/lib/ folder.
You will get this screen :

Add JARs

Note :
Just for informations, *.dll files are libraries for Windows, *.so for Linux and *.jnilib for Mac. FMOD Designer jar & libraries are only necessary in case of use of the package org.jouvieje.FmodDesigner.
You DON'T need to include all libraries, just use those needed (ie don't include FMOD Designer jar/libraries if you don't have any use of them).

You've just linked NativeFmodEx jars, now you have to link libraries.
Double clic on "Native library location: (None)" under the two enties entry and select the folder (with "External Folder ...") in which there is NativeFmodEx libraries (NATIVEFMODEX_FOLDER/lib/ folder).

Select libraries location

Optional :
You can attach NativeFmodEx/NativeFmodDesigner sources by selecting NativeFmodEx-src.jar & NativeFmodEx-src.jar from their respective folders ie NATIVEFMODEX_FOLDER/src/NativeFmodEx/Java/ & NATIVEFMODEX_FOLDER/src/NativeFmodDesigner/Java/.
Similarly, you can attach NativeFmodEx javadoc by selecting NativeFmodEx javadoc folder (in NativeFmodEx Javadoc.rar).

Finally, you will have something like this :

User Library settings

Note :
I've included NativeFmodDesigner in NativeFmodEx user library, you can create a second user library for NativeFmodDesigner.


NativeFmodEx user library is now created. You will see how it is easy to use it.

Go to Properties of the project. Choose the tab 'Libraries' and select 'Add Library'.
On 'Add Library' window, select NativeFmodEx user library.

Attach NativeFmodEx user library

Now, all the above errors should disappear (except may be for Geometry_ and Demo3D example which uses JOGL-JSR231, look at OpenGl section for some hints to installing/using JOGL.

The examples requieres Java 1.5 (also known as 5.0) or greater.
Check the JRE selected in Window/Preferences/Java/Installed JREs is at least Java 1.5 (ie use Java 5) and in Window/Preferences/Java/Compiler that Compiler compliance level is a least 5.0.

Remark : NativeFmodEx is written with Java 1.4. Only example needs Java 1.5 or later.

To run an example, such as DspPluginViewer, right click on it and select Run as -> Java Application.

Note 1 :
Don't be surprised if a lot of informations are printed in the Eclipse's console. Eclipse console consider \r as \n. When an information is updated, changes are displayed in a new line instead of the current one.

Note 2 :
An alternative and NOT-RECOMMENDED way is presented here.
 

•  NetBeans - Create a Project that use NativeFmodEx

I assume that you've already read Eclipse part.

I don't have used NetBeans a lot, but I will show a possible way to use NativeFmodEx under Eclipse.
This involve :
 - Indicating where are NativeFmodEx jars.
 - Indicating where are FMOD Ex & NativeFmodEx libraries.

First, create a project in any folder you want (PROJECT_FOLDER) and put all files from :
   NATIVEFMODEX_FOLDER/Src/Examples
Also copy Media and SimpleEventMedia folders from :
   NATIVEFMODEX_FOLDER/Examples.

Go to project's properties window and select NativeFmodEx jars in Libraries/Compile/Add JAR/Folder :

Selecting Jars in NetBeans

Select Run tree's item and add java.library.path in VM Options :

Selecting libraries in NetBeans

Finally, run the project !

For more details informations, please refer to Eclise install process.