Crate rfmod [−] [src]

rust-fmod

This is a rust binding for FMOD, the library developped by FIRELIGHT TECHNOLOGIES.

FMOD website : www.fmod.org

##Installation

You must install on your computer the FMOD library which is used for the binding.

To build it, please use :

> make

This command build rfmod, the examples, and the documentation.

You can build them separatly too.

> make rfmod
> make examples
> make doc

##Short example

Here is a short example on how to create a file and to play it :

extern crate libc;
extern crate rfmod;

use std::os;

fn main() {
    let fmod = match rfmod::Sys::new() {
        Ok(f) => f,
        Err(e) => {
            panic!("Error code : {}", e);
        }
    };

    match fmod.init() {
        rfmod::Status::Ok => {}
        e => {
            panic!("Sys.init failed : {}", e);
        }
    };

    let mut sound = match fmod.create_sound(StrBuf::from_str("music.mp3"), None, None) {
        Ok(s) => s,
        Err(err) => {
            panic!("Error code : {}", err);
        }
    };

    match sound.play_to_the_end() {
        rfmod::Status::Ok => {
            println!("Ok !");
        }
        err => {
            panic!("Error code : {}", err);
        }
    };
}

For a more complete example : https://github.com/GuillaumeGomez/rust-music-player

##License

Copyright (c) 2014 Guillaume Gomez

The license of this project is available in the LICENSE.TXT file. Please refer to it.
If you want more information, here is the website for FMOD : http://www.fmod.org/

#Notes

Members marked with [r] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.
Members marked with [w] mean the variable can be written to. The user can set the value.

Here is the list of all modules :

Re-exports

pub use self::types::Mode;

pub use self::types::TimeUnit;

pub use self::types::FmodCaps;

pub use self::types::PluginHandle;

pub use self::types::InitFlag;

pub use self::types::MemoryBits;

pub use self::types::EventMemoryBits;

Modules

callbacks
error
types

Macros

from_utf8

Structs

AdvancedSettings	Settings for advanced features like configuring memory and cpu usage for the FMOD_CREATECOMPRESSEDSAMPLE feature.
Channel	Channel Object
ChannelGroup	ChannelGroup object
CreateSoundexInfo	Use this structure with `Sys::create_sound` when more control is needed over loading. The possible reasons to use this with `Sys::create_sound` are:
Dsp	Dsp object
DspConnection	DspConnection object
DspDescription	When creating a DSP unit, declare one of these and provide the relevant callbacks and name for FMOD to use when it creates and uses a DSP unit of this type.
DspParameterDesc	Structure to define a parameter for a DSP unit.
DspState	DSP plugin structure that is passed into each callback.
FmodFile	A little struct to wrap C files.
FmodSyncPoint	Wrapper for SyncPoint object
FmodTag	Structure describing a piece of tag data.
Geometry	Geometry object
Guid	Structure describing a globally unique identifier.
MemoryUsageDetails	Structure to be filled with detailed memory usage information of a FMOD object
OutputHandle	Wrapper for OutputHandle
Reverb	Reverb object
ReverbChannelProperties	Structure defining the properties for a reverb source, related to a FMOD channel.
ReverbProperties	Structure defining a reverb environment.
SoftwareFormat	Wrapper for arguments of `Sys::set_software_format` and `Sys::get_software_format`.
Sound	Sound object
SoundGroup	SoundGroup object
SpeakerMixOptions	Structure which contains data for `Channel::set_speaker_mix` and `Channel::get_speaker_mix`
Sys	FMOD System Object
UserData	Structure used to store user data for file callback
Vector	Structure describing a point in 3D space.

Enums

ChannelIndex	Special channel index values for FMOD functions.
DelayType	Types of delay that can be used with `Channel::set_delay` / `Channel::get_delay`.
DspChorus	Parameter types for the FMOD_DSP_TYPE_CHORUS filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspCompressor	Parameter types for the FMOD_DSP_TYPE_COMPRESSOR unit. This is a simple linked multichannel software limiter that is uniform across the whole spectrum. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspDelay	Parameter types for the FMOD_DSP_TYPE_DELAY filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspDistortion	Parameter types for the FMOD_DSP_TYPE_DISTORTION filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspFftWindow	List of windowing methods used in spectrum analysis to reduce leakage / transient signals intefering with the analysis. This is a problem with analysis of continuous signals that only have a small portion of the signal sample (the fft window size). Windowing the signal with a curve or triangle tapers the sides of the fft window to help alleviate this problem.
DspFlange	Parameter types for the FMOD_DSP_TYPE_FLANGE filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspHighPass	Parameter types for the FMOD_DSP_TYPE_HIGHPASS filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`.
DspHighPassSimple	Parameter types for the FMOD_DSP_TYPE_HIGHPASS_SIMPLE filter. This is a very simple single-order high pass filter. The emphasis is on speed rather than accuracy, so this should not be used for task requiring critical filtering. Used with `Dsp::set_parameter` and `Dsp::get_parameter`.
DspITEcho	Parameter types for the FMOD_DSP_TYPE_ITECHO filter. This is effectively a software based echo filter that emulates the DirectX DMO echo effect. Impulse tracker files can support this, and FMOD will produce the effect on ANY platform, not just those that support DirectX effects! Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspITLowPass	Parameter types for the FMOD_DSP_TYPE_ITLOWPASS filter. This is different to the default FMOD_DSP_TYPE_ITLOWPASS filter in that it uses a different quality algorithm and is the filter used to produce the correct sounding playback in .IT files. FMOD Ex's .IT playback uses this filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspLowPass	Parameter types for the FMOD_DSP_TYPE_LOWPASS filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspLowPassSimple	Parameter types for the FMOD_DSP_TYPE_LOWPASS_SIMPLE filter. This is a very simple low pass filter, based on two single-pole RC time-constant modules. The emphasis is on speed rather than accuracy, so this should not be used for task requiring critical filtering. Used with `Dsp::set_parameter` and `Dsp::get_parameter`.
DspNormalize	Parameter types for the FMOD_DSP_TYPE_NORMALIZE filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspOscillator	Parameter types for the FMOD_DSP_TYPE_OSCILLATOR filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspPitchShift	Parameter types for the FMOD_DSP_TYPE_PITCHSHIFT filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspResampler	List of interpolation types that the FMOD Ex software mixer supports.
DspSfxReverb	Parameter types for the FMOD_DSP_TYPE_SFXREVERB unit. Used with `Dsp::set_parameter` and `Dsp::get_parameter`.
DspTremolo	Parameter types for the FMOD_DSP_TYPE_TREMOLO filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
DspType	These definitions can be used for creating FMOD defined special effects or DSP units. Used with `Dsp::set_parameter` and `Dsp::get_parameter`.
DspTypeEcho	Parameter types for the DspTypeEcho filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`.
DspTypeParameq	Parameter types for the DspTypeParameq filter. Used with `Dsp::set_parameter` and `Dsp::get_parameter`
OpenState	These values describe what state a sound is in after FMOD_NONBLOCKING has been used to open it.
OutputType	These output types are used with `Sys::set_output` / `Sys::get_output`, to choose which output method to use.
PluginType	These are plugin types defined for use with the `Sys::get_num_plugins`, `Sys::get_plugin_info` and `Sys::unload_plugin` functions.
RStatus
SeekStyle
SoundFormat	These definitions describe the native format of the hardware or software buffer that will be used.
SoundGroupBehavior	These flags are used with `SoundGroup::set_max_audible_behavior` to determine what happens when more sounds are played than are specified with `SoundGroup::set_max_audible`.
SoundType	These definitions describe the type of song being played.
Speaker	These are speaker types defined for use with the `Channel::set_speaker_level` command. It can also be used for speaker placement in the `Sys::set_3D_speaker_position` command.
SpeakerMapType	When creating a multichannel sound, FMOD will pan them to their default speaker locations:
SpeakerMode	These are speaker types defined for use with the `Sys::set_speaker_mode` or `Sys::get_speaker_mode` command.
Status	Error codes. Returned from every function.
SystemCallbackType	These callback types are used with `Channel::set_callback`.
TagDataType	List of data types that can be returned by `Sound::get_tag`
TagType	List of tag types that could be stored within a sound. These include id3 tags, metadata from netstreams and vorbis/asf data.

Constants

ACCURATETIME	For `Sys::create_sound` - for accurate `Sound::get_length` / `Channel::set_position` on VBR MP3, and MOD/S3M/XM/IT/MIDI files. Scans file first, so takes longer to open. OPENONLY does not affect this.
CREATECOMPRESSEDSAMPLE	Load MP2/MP3/IMAADPCM/CELT/Vorbis/AT9 or XMA into memory and leave it compressed. CELT/Vorbis/AT9 encoding only supported in the FSB file format. During playback the FMOD software mixer will decode it in realtime as a 'compressed sample'. Can only be used in combination with SOFTWARE. Overrides CREATESAMPLE. If the sound data is not one of the supported formats, it will behave as if it was created with CREATESAMPLE and decode the sound into PCM.
CREATESAMPLE	Decompress at loadtime, decompressing or decoding whole file into memory as the target sample format (ie PCM). Fastest for SOFTWARE based playback and most flexible.
CREATESTREAM	Decompress at runtime, streaming from the source provided (ie from disk). Overrides CREATESAMPLE and CREATECOMPRESSEDSAMPLE. Note a stream can only be played once at a time due to a stream only having 1 stream buffer and file handle. Open multiple streams to have them play concurrently.
DEFAULT	Default for all modes listed below. LOOP_OFF, 2D, HARDWARE
EVENT_MEMBITS_ALL	All memory used by FMOD Event System
EVENT_MEMBITS_EVENTCATEGORY	Event category objects
EVENT_MEMBITS_EVENTENVELOPE	Event envelope objects
EVENT_MEMBITS_EVENTENVELOPEDEF	Event envelope definition objects
EVENT_MEMBITS_EVENTENVELOPEPOINT	Event envelope point objects
EVENT_MEMBITS_EVENTGROUPI	EventGroup objects and internals
EVENT_MEMBITS_EVENTINSTANCE	Event instance base objects
EVENT_MEMBITS_EVENTINSTANCEPOOL	Event instance pool data
EVENT_MEMBITS_EVENTINSTANCE_COMPLEX	Complex event instance objects
EVENT_MEMBITS_EVENTINSTANCE_GROUP	All event instance memory
EVENT_MEMBITS_EVENTINSTANCE_LAYER	Event layer instance objects
EVENT_MEMBITS_EVENTINSTANCE_SIMPLE	Simple event instance objects
EVENT_MEMBITS_EVENTINSTANCE_SOUND	Event sound instance objects
EVENT_MEMBITS_EVENTPARAMETER	Event parameter objects
EVENT_MEMBITS_EVENTPROJECT	EventProject objects and internals
EVENT_MEMBITS_EVENTREVERB	Reverb objects
EVENT_MEMBITS_EVENTSYSTEM	EventSystem and various internals
EVENT_MEMBITS_FEV	Definition of objects contained in all loaded projects e.g. events, groups, categories
EVENT_MEMBITS_MEMORYFSB	Data loaded with preloadFSB
EVENT_MEMBITS_MUSICSYSTEM	MusicSystem and various internals
EVENT_MEMBITS_REVERBDEF	Reverb definition objects
EVENT_MEMBITS_SOUNDBANKCLASS	Objects used to manage wave banks
EVENT_MEMBITS_SOUNDBANKLIST	Data used to manage lists of wave bank usage
EVENT_MEMBITS_SOUNDDEFCLASS	Sound definition objects
EVENT_MEMBITS_SOUNDDEFDEFCLASS	Sound definition static data objects
EVENT_MEMBITS_SOUNDDEFPOOL	Sound definition pool data
EVENT_MEMBITS_SOUNDDEF_GROUP	All sound definition memory
EVENT_MEMBITS_STREAMINSTANCE	Stream objects and internals
EVENT_MEMBITS_USERPROPERTY	User property objects
HARDWARE	Attempts to make sounds use hardware acceleration. (DEFAULT). Note on platforms that don't support HARDWARE (only 3DS, PS Vita, PSP, Wii and Wii U support HARDWARE), this will be internally treated as SOFTWARE.
IGNORETAGS	Skips id3v2/asf/etc tag checks when opening a sound, to reduce seek/read overhead when opening files (helps with CD performance).
INIT_3D_RIGHTHANDED	All platforms - FMOD will treat +X as right, +Y as up and +Z as backwards (towards you).
INIT_7POINT1_DOLBYMAPPING	PS3/PS4 only - FMOD uses the WAVEFORMATEX Microsoft 7.1 speaker mapping where the last 2 pairs of speakers are 'rears' then 'sides', but on PS3/PS4 these are mapped to 'surrounds' and 'backs'. Use this flag to swap fmod's last 2 pair of speakers on PS3/PS4 to avoid needing to do a special case for these platforms.
INIT_DISABLEDOLBY	Wii / 3DS - Disable Dolby Pro Logic surround. will be set to STEREO even if user has selected surround in the system settings.
INIT_DISABLE_MYEARS_AUTODETECT	Win32 - Disables automatic setting of of _STEREO to _MYEARS if the MyEars profile exists on the PC. MyEars is HRTF 7.1 downmixing through headphones.
INIT_DISTANCE_FILTERING	All platforms - All SOFTWARE with 3D based voices will add a software lowpass and highpass filter effect into the DSP chain which will act as a distance-automated bandpass filter. Use `Sys::set_advanced_settings` to adjust the center frequency.
INIT_ENABLE_PROFILE	All platforms - Enable TCP/IP based host which allows FMOD Designer or FMOD Profiler to connect to it, and view memory, CPU and the DSP network graph in real-time.
INIT_GEOMETRY_USECLOSEST	All platforms - With the geometry engine, only process the closest polygon rather than accumulating all polygons the sound to listener line intersects.
INIT_HRTF_LOWPASS	All platforms - All SOFTWARE (and HARDWARE on 3DS and NGP) with 3D based voices will add a software lowpass filter effect into the DSP chain which causes sounds to sound duller when the sound goes behind the listener. Use `Sys::set_advanced_settings` to adjust Cutoff frequency.
INIT_NORMAL	All platforms - Initialize normally
INIT_OCCLUSION_LOWPASS	All platforms - All SOFTWARE (and HARDWARE on 3DS and NGP) with 3D based voices will add a software lowpass filter effect into the DSP chain which is automatically used when `Channel::set_3D_occlusion` is used or the geometry API.
INIT_PS3_DISABLEDOLBYDIGITAL	PS3 only - Disable Dolby Digital output mode selection
INIT_PS3_DISABLEDTS	PS3 only - Disable DTS output mode selection
INIT_PS3_FORCE2CHLPCM	PS3 only - Force PS3 system output mode to 2 channel LPCM.
INIT_PS3_PREFERDTS	PS3 only - Prefer DTS over Dolby Digital if both are supported. Note: 8 and 6 channel LPCM is always preferred over both DTS and Dolby Digital.
INIT_REVERB_PREALLOCBUFFERS	All platforms - FMOD Software reverb will preallocate enough buffers for reverb per channel, rather than allocating them and freeing them at runtime.
INIT_SOFTWARE_DISABLE	All platforms - Disable software mixer to save memory. Anything created with SOFTWARE will fail and DSP will not work.
INIT_STREAM_FROM_UPDATE	All platforms - No stream thread is created internally. Streams are driven from `Sys::update`. Mainly used with non-realtime outputs.
INIT_SYNCMIXERWITHUPDATE	Win32/Wii/PS3/Xbox/Xbox 360 - FMOD Mixer thread is woken up to do a mix when `Sys::update` is called rather than waking periodically on its own timer.
INIT_SYSTEM_MUSICMUTENOTPAUSE	Xbox 360 / PS3 - The "music" channelgroup which by default pauses when custom 360 dashboard / PS3 BGM music is played, can be changed to mute (therefore continues playing) instead of pausing, by using this flag.
INIT_VOL0_BECOMES_VIRTUAL	All platforms - Any sounds that are 0 volume will go virtual and not be processed except for having their positions updated virtually. Use `Sys::set_advanced_settings` to adjust what volume besides zero to switch to virtual at.
INIT_WASAPI_EXCLUSIVE	Win32 Vista only - for WASAPI output - Enable exclusive access to hardware, lower latency at the expense of excluding other applications from accessing the audio hardware.
LOADSECONDARYRAM	Load sound into the secondary RAM of supported platform. On PS3, sounds will be loaded into RSX/VRAM.
LOOP_BIDI	For bidirectional looping sounds. (only works on software mixed static sounds).
LOOP_NORMAL	For forward looping sounds.
LOOP_OFF	For non looping sounds. (DEFAULT). Overrides LOOP_NORMAL / LOOP_BIDI.
LOWMEM	Removes some features from samples to give a lower memory overhead, like `Sound::get_name`. See remarks.
MEMBITS_ALL	All memory used by FMOD Ex
MEMBITS_CHANNEL	`Channel` related memory
MEMBITS_CHANNELGROUP	`ChannelGroup` objects and internals
MEMBITS_CODEC	Codecs allocated for streaming
MEMBITS_DSP	`Dsp` implementation objects
MEMBITS_DSPCODEC	Realtime file format decoding `Dsp` objects
MEMBITS_DSPCONNECTION	`DspConnection` objects and internals
MEMBITS_FILE	Codecs allocated for streaming
MEMBITS_GEOMETRY	`Geometry` objects and internals
MEMBITS_OTHER	Memory not accounted for by other types
MEMBITS_OUTPUT	Output module object and internals
MEMBITS_PLUGINS	Plugin objects and internals
MEMBITS_PROFILE	Profiler memory footprint.
MEMBITS_RECORDBUFFER	Buffer used to store recorded data from microphone
MEMBITS_REVERB	`Reverb` implementation objects
MEMBITS_REVERBCHANNELPROPS	Reverb channel properties structs
MEMBITS_SOUND	`Sound` objects and internals
MEMBITS_SOUNDGROUP	`SoundGroup` objects and internals
MEMBITS_SOUND_SECONDARYRAM	Sound data stored in secondary RAM
MEMBITS_STREAMBUFFER	Stream buffer memory
MEMBITS_STRING	String data
MEMBITS_SYNCPOINT	Sync point memory.
MEMBITS_SYSTEM	`Sys` object and various internals
MPEGSEARCH	For corrupted / bad MP3 files. This will search all the way through the file until it hits a valid MPEG header. Normally only searches for 4k.
NONBLOCKING	For opening sounds and getting streamed subsounds (seeking) asyncronously. Use `Sound::get_open_state` to poll the state of the sound as it opens or retrieves the subsound in the background.
OPENMEMORY	"name_or_data" will be interpreted as a pointer to memory instead of filename for creating sounds. Use CREATESOUNDEXINFO to specify length. If used with CREATESAMPLE or CREATECOMPRESSEDSAMPLE, FMOD duplicates the memory into its own buffers. Your own buffer can be freed after open. If used with CREATESTREAM, FMOD will stream out of the buffer whose pointer you passed in. In this case, your own buffer should not be freed until you have finished with and released the stream.
OPENMEMORY_POINT	"name_or_data" will be interpreted as a pointer to memory instead of filename for creating sounds. Use CREATESOUNDEXINFO to specify length. This differs to OPENMEMORY in that it uses the memory as is, without duplicating the memory into its own buffers. For Wii/PSP HARDWARE supports this flag for the GCADPCM/VAG formats. On other platforms SOFTWARE must be used, as sound hardware on the other platforms (ie PC) cannot access main ram. Cannot be freed after open, only after `Sound::release`. Will not work if the data is compressed and CREATECOMPRESSEDSAMPLE is not used.
OPENONLY	Just open the file, dont prebuffer or read. Good for fast opens for info, or when sound::readData is to be used.
OPENRAW	Will ignore file format and treat as raw pcm. Use CREATESOUNDEXINFO to specify format. Requires at least defaultfrequency, numchannels and format to be specified before it will open. Must be little endian data.
OPENUSER	Opens a user created static sample or stream. Use CREATESOUNDEXINFO to specify format and/or read callbacks. If a user created 'sample' is created with no read callback, the sample will be empty. Use `Sound::lock` and `Sound::unlock` to place sound data into the sound if this is the case.
SOFTWARE	Makes the sound be mixed by the FMOD CPU based software mixer. Overrides HARDWARE. Use this for FFT, DSP, compressed sample support, 2D multi-speaker support and other software related features.
TIMEUNIT_BUFFERED	Time value as seen by buffered stream. This is always ahead of audible time, and is only used for processing.
TIMEUNIT_MODORDER	MOD/S3M/XM/IT. Order in a sequenced module format. Use `Sound::get_format` to determine the PCM format being decoded to.
TIMEUNIT_MODPATTERN	MOD/S3M/XM/IT. Current pattern in a sequenced module format. `Sound::get_length` will return the number of patterns in the song and `Channel::get_position` will return the currently playing pattern.
TIMEUNIT_MODROW	MOD/S3M/XM/IT. Current row in a sequenced module format. `Sound::get_length` will return the number of rows in the currently playing or seeked to pattern.
TIMEUNIT_MS	Milliseconds.
TIMEUNIT_PCM	PCM samples, related to milliseconds * samplerate / 1000.
TIMEUNIT_PCMBYTES	Bytes, related to PCM samples * channels * datawidth (ie 16bit = 2 bytes).
TIMEUNIT_PCMFRACTION	Fractions of 1 PCM sample. Unsigned int range 0 to 0xFFFFFFFF. Used for sub-sample granularity for DSP purposes.
TIMEUNIT_RAWBYTES	Raw file bytes of (compressed) sound data (does not include headers). Only used by `Sound::get_length` and `Channel::get_position`.
TIMEUNIT_SENTENCE	Currently playing sentence index according to the channel.
TIMEUNIT_SENTENCE_MS	Currently playing subsound in a sentence time in milliseconds.
TIMEUNIT_SENTENCE_PCM	Currently playing subsound in a sentence time in PCM Samples, related to milliseconds * samplerate / 1000.
TIMEUNIT_SENTENCE_PCMBYTES	Currently playing subsound in a sentence time in bytes, related to PCM samples * channels * datawidth (ie 16bit = 2 bytes).
TIMEUNIT_SENTENCE_SUBSOUND	Currently playing subsound index in a sentence.
UNICODE	Filename is double-byte unicode.
UNIQUE	Unique sound, can only be played one at a time
VIRTUAL_PLAYFROMSTART	For sounds that start virtual (due to being quiet or low importance), instead of swapping back to audible, and playing at the correct offset according to time, this flag makes the sound play from the start.
_2D	Ignores any 3d processing. (DEFAULT).
_3D	Makes the sound positionable in 3D. Overrides 2D
_3D_CUSTOMROLLOFF	This sound will follow a rolloff model defined by `Sound::set_3D_custom_rolloff` / `Channel::set_3D_custom_rolloff`.
_3D_HEADRELATIVE	Make the sound's position, velocity and orientation relative to the listener.
_3D_IGNOREGEOMETRY	Is not affect by geometry occlusion. If not specified in `Sound::set_mode`, or `Channel::set_mode`, the flag is cleared and it is affected by geometry again.
_3D_INVERSEROLLOFF	This sound will follow the inverse rolloff model where mindistance = full volume, maxdistance = where sound stops attenuating, and rolloff is fixed according to the global rolloff factor. (DEFAULT)
_3D_LINEARROLLOFF	This sound will follow a linear rolloff model where mindistance = full volume, maxdistance = silence. Rolloffscale is ignored.
_3D_LINEARSQUAREROLLOFF	This sound will follow a linear-square rolloff model where mindistance = full volume, maxdistance = silence. Rolloffscale is ignored.
_3D_WORLDRELATIVE	Make the sound's position, velocity and orientation absolute (relative to the world). (DEFAULT)