Firelight Technologies FMOD Studio API
System::createSound
Loads a sound into memory, or opens it for streaming.
C++ Syntax
FMOD_RESULT System::createSound(
const char *name_or_data,
FMOD_MODE mode,
FMOD_CREATESOUNDEXINFO *exinfo,
FMOD::Sound **sound
);
C Syntax
FMOD_RESULT FMOD_System_CreateSound(
FMOD_SYSTEM *system,
const char *name_or_data,
FMOD_MODE mode,
FMOD_CREATESOUNDEXINFO *exinfo,
FMOD_SOUND **sound
);
C# Syntax
RESULT System.createSound(
string name,
MODE mode,
out Sound sound
);
JavaScript Syntax
System.createSound(
name_or_data,
mode,
exinfo,
sound // writes value to sound.val
);
Parameters
- name_or_data
- Name of the file or URL to open encoded in a UTF-8 string, or a pointer to a preloaded sound memory block if FMOD_OPENMEMORY/FMOD_OPENMEMORY_POINT is used. For CD playback the name should be a drive letter with a colon, example "D:" (windows only).
- mode
- Behaviour modifier for opening the sound. See FMOD_MODE. Also see remarks for more.
- exinfo
- Pointer to a FMOD_CREATESOUNDEXINFO which lets the user provide extended information while playing the sound. Optional. Specify 0 or NULL to ignore.
- sound
- Address of a variable to receive a newly created FMOD::Sound object.
Return Values
If the function succeeds then the return value is FMOD_OK.
If the function fails then the return value will be one of the values defined in the FMOD_RESULT enumeration.
Remarks
Important! By default (FMOD_CREATESAMPLE) FMOD will try to load and decompress the whole sound into memory! Use FMOD_CREATESTREAM to open it as a stream and have it play back in realtime! FMOD_CREATECOMPRESSEDSAMPLE can also be used for certain formats.
- To open a file or URL as a stream, so that it decompresses / reads at runtime, instead of loading / decompressing into memory all at the time of this call, use the FMOD_CREATESTREAM flag. This is like a 'stream' in FMOD 3.
- To open a file or URL as a compressed sound effect that is not streamed and is not decompressed into memory at load time, use FMOD_CREATECOMPRESSEDSAMPLE. This is supported with MPEG (mp2/mp3), ADPCM/FADPCM, XMA, AT9 and FSB Vorbis files only. This is useful for those who want realtime compressed soundeffects, but not the overhead of disk access.
- To open a sound as 2D, so that it is not affected by 3D processing, use the FMOD_2D flag. 3D sound commands will be ignored on these types of sounds.
- To open a sound as 3D, so that it is treated as a 3D sound, use the FMOD_3D flag. Calls to Channel::setPan will be ignored on these types of sounds.
Note that FMOD_OPENRAW, FMOD_OPENMEMORY, FMOD_OPENMEMORY_POINT and FMOD_OPENUSER will not work here without the exinfo structure present, as more information is needed.
Use FMOD_NONBLOCKING to have the sound open or load in the background. You can use Sound::getOpenState to determine if it has finished loading / opening or not. While it is loading (not ready), sound functions are not accessable for that sound.
To account for slow devices or computers that might cause buffer underrun (skipping/stuttering/repeating blocks of audio), use System::setStreamBufferSize.
To play WMA files on Windows, the user must have the latest Windows media player codecs installed (Windows Media Player 9). The user can download this as an installer (wmfdist.exe) from www.fmod.org download page if they desire or you may wish to redistribute it with your application (this is allowed). This installer does NOT install windows media player, just the necessary WMA codecs needed.
Specifying FMOD_OPENMEMORY_POINT will POINT to your memory rather allocating its own sound buffers and duplicating it internally
This means you cannot free the memory while FMOD is using it, until after Sound::release is called.
With FMOD_OPENMEMORY_POINT, for PCM formats, only WAV, FSB and RAW are supported. For compressed formats, only
those formats supported by FMOD_CREATECOMPRESSEDSAMPLE are supported.
JavaScript only :
If FMOD.NON_BLOCKING is passed into mode, FMOD.ERR_UNSUPPORTED will be returned
See Also
Version 1.10.03 Built on Feb 1, 2018