Crate rfmod

Source

Expand description

§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.

§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)

Crate rfmodCopy item path