System::setFileSystem

Specify user callbacks for FMOD's internal file manipulation functions. This function is useful for replacing FMOD's file system with a game system's own file reading API.

C++ Syntax

FMOD_RESULT System::setFileSystem(
  FMOD_FILE_OPEN_CALLBACK useropen,
  FMOD_FILE_CLOSE_CALLBACK userclose,
  FMOD_FILE_READ_CALLBACK userread,
  FMOD_FILE_SEEK_CALLBACK userseek,
  FMOD_FILE_ASYNCREAD_CALLBACK userasyncread,
  FMOD_FILE_ASYNCCANCEL_CALLBACK userasynccancel,
  int blockalign
);

C Syntax

FMOD_RESULT FMOD_System_SetFileSystem(
  FMOD_SYSTEM *system,
  FMOD_FILE_OPEN_CALLBACK useropen,
  FMOD_FILE_CLOSE_CALLBACK userclose,
  FMOD_FILE_READ_CALLBACK userread,
  FMOD_FILE_SEEK_CALLBACK userseek,
  FMOD_FILE_ASYNCREAD_CALLBACK userasyncread,
  FMOD_FILE_ASYNCCANCEL_CALLBACK userasynccancel,
  int blockalign
);

Parameters

useropen: Callback for opening a file. Specifying 0 / null will disable file callbacks.
userclose: Callback for closing a file. Specifying 0 / null will disable file callbacks.
userread: Callback for reading from a file. Specifying 0 / null will disable file callbacks if userasyncread is also 0 / null. User could use userasyncread instead of userread.
userseek: Callback for seeking within a file. Specifying 0 / null will disable file callbacks. User could use userasyncread instead of userseek.
userasyncread: OPTIONAL - Callback to replace 'userread' and 'userseek' that allows the user to defer file access to a later time and return immediately. FMOD will internally wait for data to appear, or in a file streaming case - stutter/starve if data is not fed to fmod in time. Set to 0 / null to get normal file callback operation.
userasynccancel: OPTIONAL - Callback for cancelling pending user file accesses. This will be called if a sound is released, so the user can cancel any pending file accesses. If the sound is released and a deferred read happens into a released buffer, the application will crash. This callback must be used to make sure this doesn't happen. Set to 0 / null to get normal file callback operation.
blockalign: Internal minimum file block alignment. FMOD will read data in at least chunks of this size if you ask it to. Specifying 0 means there is no file buffering at all (this could adversely affect streaming). Do NOT make this a large value, it is purely a setting for minimum sector size alignment to aid seeking and reading on certain media. It is not for stream buffer sizes, that is what System::setStreamBufferSize is for. It is recommened just to pass -1. Large values just mean large memory usage with no benefit. Specify -1 to not set this value. Default = 2048.

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

This has no effect on sounds loaded with FMOD_OPENMEMORY or FMOD_CREATEUSER.

This function can be used to set user file callbacks, or if required, they can be turned off by specifying 0 for all callbacks.
This function can be used purely to set the 'buffersize' parameter, and ignore the callback aspect of the function.

Warning : This function can cause unpredictable behaviour if not used properly. You must return the right values, and each command must work properly, or FMOD will not function, or it may even crash if you give it invalid data. You must also return FMOD_ERR_FILE_EOF from a read callback if the number of bytes read is smaller than the number of bytes requested.

FMOD's default filsystem buffers reads every 2048 bytes by default. This means every time fmod reads one byte from the API (say if it was parsing a file format), it simply mem copies the byte from the 2k memory buffer, and every time it needs to, refreshes the 2k buffer resulting in a drastic reduction in file I/O. Large reads go straight to the pointer instead of the 2k buffer if it is buffer aligned. This value can be increased or decreased by the user. A buffer of 0 means all reads go directly to the pointer specified. 2048 bytes is the size of a CD sector on most CD ISO formats so it is chosen as the default, for optimal reading speed from CD media.

NOTE! Do not force a cast from your function pointer to the FMOD_FILE_xxxCALLBACK type! Never try to 'force' fmod to accept your function. If there is an error then find out what it is. Remember to include F_CALLBACK between the return type and the function name, this equates to stdcall which you must include otherwise (besides not compiling) it will cause problems such as crashing and callbacks not being called.

NOTE! Your file callbacks must be thread safe. If not unexpected behaviour may occur. FMOD calls file functions from asynchronous threads, such as the streaming thread, and thread related to FMOD_NONBLOCKING flag.

Asynchronous file access (userasyncread/userasynccanel).