FMOD_CREATESOUNDEXINFO

FMOD Ex

 
Firelight Technologies FMOD Ex

FMOD_CREATESOUNDEXINFO

Use this structure with System::createSound when more control is needed over loading.
  The possible reasons to use this with System::createSound are:
 

  • Loading a file from memory. 
  • Loading a file from within another larger (possibly wad/pak) file, by giving the loader an offset and length. 
  • To create a user created / non file based sound. 
  • To specify a starting subsound to seek to within a multi-sample sounds (ie FSB/DLS/SF2) when created as a stream. 
  • To specify which subsounds to load for multi-sample sounds (ie FSB/DLS/SF2) so that memory is saved and only a subset is actually loaded/read from disk. 
  • To specify 'piggyback' read and seek callbacks for capture of sound data as fmod reads and decodes it. Useful for ripping decoded PCM data from sounds as they are loaded / played. 
  • To specify a MIDI DLS/SF2 sample set file to load when opening a MIDI file.  See below on what members to fill for each of the above types of sound you want to create. 

    Structure

    typedef struct {
      int  cbsize;
      unsigned int  length;
      unsigned int  fileoffset;
      int  numchannels;
      int  defaultfrequency;
      FMOD_SOUND_FORMAT  format;
      unsigned int  decodebuffersize;
      int  initialsubsound;
      int  numsubsounds;
      int *  inclusionlist;
      int  inclusionlistnum;
      FMOD_SOUND_PCMREADCALLBACK  pcmreadcallback;
      FMOD_SOUND_PCMSETPOSCALLBACK  pcmsetposcallback;
      FMOD_SOUND_NONBLOCKCALLBACK  nonblockcallback;
      const char *  dlsname;
      const char *  encryptionkey;
      int  maxpolyphony;
      void *  userdata;
      FMOD_SOUND_TYPE  suggestedsoundtype;
      FMOD_FILE_OPENCALLBACK  useropen;
      FMOD_FILE_CLOSECALLBACK  userclose;
      FMOD_FILE_READCALLBACK  userread;
      FMOD_FILE_SEEKCALLBACK  userseek;
      FMOD_FILE_ASYNCREADCALLBACK  userasyncread;
      FMOD_FILE_ASYNCCANCELCALLBACK  userasynccancel;
      FMOD_SPEAKERMAPTYPE  speakermap;
      FMOD_SOUNDGROUP *  initialsoundgroup;
      unsigned int  initialseekposition;
      FMOD_TIMEUNIT  initialseekpostype;
      int  ignoresetfilesystem;
      int  cddaforceaspi;
      unsigned int  audioqueuepolicy;
      unsigned int  minmidigranularity;
      int  nonblockthreadid;
    } FMOD_CREATESOUNDEXINFO;
    

    Members

    cbsize

    [w] Size of this structure. This is used so the structure can be expanded in the future and still work on older versions of FMOD Ex.

    length

    [w] Optional. Specify 0 to ignore. Size in bytes of file to load, or sound to create (in this case only if FMOD_OPENUSER is used). Required if loading from memory. If 0 is specified, then it will use the size of the file (unless loading from memory then an error will be returned).

    fileoffset

    [w] Optional. Specify 0 to ignore. Offset from start of the file to start loading from. This is useful for loading files from inside big data files.

    numchannels

    [w] Optional. Specify 0 to ignore. Number of channels in a sound mandatory if FMOD_OPENUSER or FMOD_OPENRAW is used.

    defaultfrequency

    [w] Optional. Specify 0 to ignore. Default frequency of sound in a sound mandatory if FMOD_OPENUSER or FMOD_OPENRAW is used. Other formats use the frequency determined by the file format.

    format

    [w] Optional. Specify 0 or FMOD_SOUND_FORMAT_NONE to ignore. Format of the sound mandatory if FMOD_OPENUSER or FMOD_OPENRAW is used. Other formats use the format determined by the file format.

    decodebuffersize

    [w] Optional. Specify 0 to ignore. For streams. This determines the size of the double buffer (in PCM samples) that a stream uses. Use this for user created streams if you want to determine the size of the callback buffer passed to you. Specify 0 to use FMOD's default size which is currently equivalent to 400ms of the sound format created/loaded.

    initialsubsound

    [w] Optional. Specify 0 to ignore. In a multi-sample file format such as .FSB/.DLS/.SF2, specify the initial subsound to seek to, only if FMOD_CREATESTREAM is used.

    numsubsounds

    [w] Optional. Specify 0 to ignore or have no subsounds. In a sound created with FMOD_OPENUSER, specify the number of subsounds that are accessable with Sound::getSubSound. If not created with FMOD_OPENUSER, this will limit the number of subsounds loaded within a multi-subsound file. If using FSB, then if FMOD_CREATESOUNDEXINFO::inclusionlist is used, this will shuffle subsounds down so that there are not any gaps. It will mean that the indices of the sounds will be different.

    inclusionlist

    [w] Optional. Specify 0 to ignore. In a multi-sample format such as .FSB/.DLS/.SF2 it may be desirable to specify only a subset of sounds to be loaded out of the whole file. This is an array of subsound indices to load into memory when created.

    inclusionlistnum

    [w] Optional. Specify 0 to ignore. This is the number of integers contained within the inclusionlist array.

    pcmreadcallback

    [w] Optional. Specify 0 to ignore. Callback to 'piggyback' on FMOD's read functions and accept or even write PCM data while FMOD is opening the sound. Used for user sounds created with FMOD_OPENUSER or for capturing decoded data as FMOD reads it.

    pcmsetposcallback

    [w] Optional. Specify 0 to ignore. Callback for when the user calls a seeking function such as Channel::setTime or Channel::setPosition within a multi-sample sound, and for when it is opened.

    nonblockcallback

    [w] Optional. Specify 0 to ignore. Callback for successful completion, or error while loading a sound that used the FMOD_NONBLOCKING flag.

    dlsname

    [w] Optional. Specify 0 to ignore. Filename for a DLS or SF2 sample set when loading a MIDI file. If not specified, on Windows it will attempt to open /windows/system32/drivers/gm.dls or /windows/system32/drivers/etc/gm.dls, on Mac it will attempt to load /System/Library/Components/CoreAudio.component/Contents/Resources/gs_instruments.dls, otherwise the MIDI will fail to open. Current DLS support is for level 1 of the specification.

    encryptionkey

    [w] Optional. Specify 0 to ignore. Key for encrypted FSB file. Without this key an encrypted FSB file will not load.

    maxpolyphony

    [w] Optional. Specify 0 to ignore. For sequenced formats with dynamic channel allocation such as .MID and .IT, this specifies the maximum voice count allowed while playing. .IT defaults to 64. .MID defaults to 32.

    userdata

    [w] Optional. Specify 0 to ignore. This is user data to be attached to the sound during creation. Access via Sound::getUserData. Note: This is not passed to FMOD_FILE_OPENCALLBACK, that is a different userdata that is file specific.

    suggestedsoundtype

    [w] Optional. Specify 0 or FMOD_SOUND_TYPE_UNKNOWN to ignore. Instead of scanning all codec types, use this to speed up loading by making it jump straight to this codec.

    useropen

    [w] Optional. Specify 0 to ignore. Callback for opening this file.

    userclose

    [w] Optional. Specify 0 to ignore. Callback for closing this file.

    userread

    [w] Optional. Specify 0 to ignore. Callback for reading from this file.

    userseek

    [w] Optional. Specify 0 to ignore. Callback for seeking within this file.

    userasyncread

    [w] Optional. Specify 0 to ignore. Callback for seeking within this file.

    userasynccancel

    [w] Optional. Specify 0 to ignore. Callback for seeking within this file.

    speakermap

    [w] Optional. Specify 0 to ignore. Use this to differ the way fmod maps multichannel sounds to speakers. See FMOD_SPEAKERMAPTYPE for more.

    initialsoundgroup

    [w] Optional. Specify 0 to ignore. Specify a sound group if required, to put sound in as it is created.

    initialseekposition

    [w] Optional. Specify 0 to ignore. For streams. Specify an initial position to seek the stream to.

    initialseekpostype

    [w] Optional. Specify 0 to ignore. For streams. Specify the time unit for the position set in initialseekposition.

    ignoresetfilesystem

    [w] Optional. Specify 0 to ignore. Set to 1 to use fmod's built in file system. Ignores setFileSystem callbacks and also FMOD_CREATESOUNEXINFO file callbacks. Useful for specific cases where you don't want to use your own file system but want to use fmod's file system (ie net streaming).

    cddaforceaspi

    [w] Optional. Specify 0 to ignore. For CDDA sounds only - if non-zero use ASPI instead of NTSCSI to access the specified CD/DVD device.

    audioqueuepolicy

    [w] Optional. Specify 0 or FMOD_AUDIOQUEUE_CODECPOLICY_DEFAULT to ignore. Policy used to determine whether hardware or software is used for decoding, see FMOD_AUDIOQUEUE_CODECPOLICY for options (iOS >= 3.0 required, otherwise only hardware is available)

    minmidigranularity

    [w] Optional. Specify 0 to ignore. Allows you to set a minimum desired MIDI mixer granularity. Values smaller than 512 give greater than default accuracy at the cost of more CPU and vice versa. Specify 0 for default (512 samples).

    nonblockthreadid

    [w] Optional. Specify 0 to ignore. Specifies a thread index to execute non blocking load on. Allows for up to 5 threads to be used for loading at once. This is to avoid one load blocking another. Maximum value = 4.

     

    Remarks

    This structure is optional! Specify 0 or NULL in System::createSound if you don't need it!

    Loading a file from memory.

  • Create the sound using the FMOD_OPENMEMORY flag.
  • Mandatory. Specify 'length' for the size of the memory block in bytes.
  • Other flags are optional.

    Loading a file from within another larger (possibly wad/pak) file, by giving the loader an offset and length.
  • Mandatory. Specify 'fileoffset' and 'length'.
  • Other flags are optional.

    To create a user created / non file based sound.
  • Create the sound using the FMOD_OPENUSER flag.
  • Mandatory. Specify 'defaultfrequency, 'numchannels' and 'format'.
  • Other flags are optional.

    To specify a starting subsound to seek to and flush with, within a multi-sample stream (ie FSB/DLS/SF2).

  • Mandatory. Specify 'initialsubsound'.

    To specify which subsounds to load for multi-sample sounds (ie FSB/DLS/SF2) so that memory is saved and only a subset is actually loaded/read from disk.

  • Mandatory. Specify 'inclusionlist' and 'inclusionlistnum'.

    To specify 'piggyback' read and seek callbacks for capture of sound data as fmod reads and decodes it. Useful for ripping decoded PCM data from sounds as they are loaded / played.

  • Mandatory. Specify 'pcmreadcallback' and 'pcmseekcallback'.

    To specify a MIDI DLS/SF2 sample set file to load when opening a MIDI file.

  • Mandatory. Specify 'dlsname'.

    Setting the 'decodebuffersize' is for cpu intensive codecs that may be causing stuttering, not file intensive codecs (ie those from CD or netstreams) which are normally altered with System::setStreamBufferSize. As an example of cpu intensive codecs, an mp3 file will take more cpu to decode than a PCM wav file.
    If you have a stuttering effect, then it is using more cpu than the decode buffer playback rate can keep up with. Increasing the decode buffersize will most likely solve this problem.


    FSB codec. If inclusionlist and numsubsounds are used together, this will trigger a special mode where subsounds are shuffled down to save memory. (useful for large FSB files where you only want to load 1 sound). There will be no gaps, ie no null subsounds. As an example, if there are 10,000 subsounds and there is an inclusionlist with only 1 entry, and numsubsounds = 1, then subsound 0 will be that entry, and there will only be the memory allocated for 1 subsound. Previously there would still be 10,000 subsound pointers and other associated codec entries allocated along with it multiplied by 10,000.

    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.

     

    See Also

     

     

    Version 4.44.07 Built on Feb 11, 2013