Wrapper Library for IrrKlang

Introduction

Overview

Important: Please note that although the IrrKlang wrapper is free for both commercial and non comercial use IrrKlang is licensed free for non commercial use only, please visit http://www.ambiera.com/irrklang for further details.

MP3 Licensing Issues: This package does not include the MP3 plugin module required to play MP3 sound files (although you can download IrrKlang and copy the ikpMP3.dll into your IrrKlangWrapper directory for full MP3 support). A large number of companies have claimed ownership of patents nessecary to implement MP3 and Thompson Consumer Electronics in particular has been activlty enforcing those patents (although they themselves have also been subject to lawsuites alledging IP infringment)  These patents do not expire until 2012 at the earliest and possibly 2017 if some questionable claims can be enforced. To avoid problems my personal recommendation is to use the Open Source Patent free OGG Vorbis format that delievers comparable or superior quality and performance http://www.vorbis.com/.
The first thing I must do is acknowledge the fantastic work that has been carried out by the many different authors whos amazing work makes it possible for this package to enable BASIC programmers to easily incorporate audio and manage the sound system for a complete multi-media application.

This wrapper library provides a simple and partial gateway from non object-oriented languages like FreeBasic into the object oriented audio engine IrrKlang. Although the wrapper only exposes part of the functionality of IrrKlang it endevours to expose the most important parts to give you access to IrrKlangs powerful features. It does not directly expose the IrrKlang commands but provides a seperate syntax to encapsulate the engine.

In total it provides over 20 commands that cover streaming and memory playback of 2D and 3D sounds.

This document serves as an introduction into the wrapper, from here I suggest you follow the installation instructions below and then try out the examples, these practical demonstrations provide an excellent way to learn how the wrapper functions. If you need specific information your first port of call will be the reference manual and your last port of call the IrrKlangWrapper.bi which hopefully you will not need.

Installation

The installation of the IrrKklangWrapper for FreeBasic package is very simple, just extract the zip file to a folder of your choice and your ready to go. You may prefer to move the IrrKlangWrapper.bi file to your FreeBasic\inc directory however I leave it where it is and create my project files within the same directory. The wrapper uses a standard IrrKlang DLL and as such you can import any IrrKlang DLL you wish to use however this library was built with a specific version of IrrKlang and newer versions may not operate as expected.


Note: You will need FreeBasic verion 0.20 or better to use the wrapper

The Audio Engine

When you start Irrlicht with the IrrKlangStart command you create an object that manages your loaded library of sounds, it provides commands that allow you to control the playback of those sounds and to free them up to release memory for other things you may wish to load.



The Sound Object

A sound object is an audio file that may be a WAV sample. MP3 Music and even some tracker modules.

The sound object is stored in main memory and can be used to create a momentary sound effect such as walking feet or the roar of a beast, or it can be used in a looped mannar to create ambient background sound or to play a musical track.

When you load a new sound the wrapper will return the object to you as an irr_sound type only if you set the track parameter to true, otherwise it will return an empty object to you that you cannot use later. If you have a large number of sounds you should store the sound objects and remove them from memory when they are no longer needed.

License

The IrrKlang library and its associated modules are licensed seperately under the terms described within the readme.txt file supplied with this package.

The IrrKlang Wrapper is provided 'as-is', without any express or implied warranty. In no event will the author be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

Contact

If you have any problems or suggestions I would be happy to receive them. Although I can not promise any action or an individual response I do try to help where possible and to look after my babies even when I release them into the wild. Mail::frankdodd@ukonline.co.uk

Acknowledgements

I wish to express my gratitude  to the following people that have helped with contributions to the wrapper or with technical assistance for various features and problems.

IrrKlang Nikolaus Gebhardt: http://www.ambiera.com/irrklang
FreeBasic http://www.freebasic.net/index.php/about?section=credits
Many thanks for the development tools Code::Blocks (www.codeblocks.org); GCC Compiler (gcc.gnu.org); FBIde (www.freebasic.net); FBEdit (fbedit.freebasic.net); NVu
Lots of thanks for help in the Forums Eponasoft; Daiwa; Crocodudule, John K, AlecZ, Alvaro Victor; thebignic and everyone that has offered their support. Thanks.