System::setFileSystem

FMOD Studio API

previous page next page

Firelight Technologies FMOD Studio API

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

C# Syntax

RESULT System.setFileSystem(
  FILE_OPENCALLBACK useropen,
  FILE_CLOSECALLBACK userclose,
  FILE_READCALLBACK userread,
  FILE_SEEKCALLBACK userseek,
  FILE_ASYNCREADCALLBACK userasyncread,
  FILE_ASYNCCANCELCALLBACK userasynccancel,
  int blockalign
);

JavaScript Syntax

System.setFileSystem(
  useropen,                        
  userclose,                       
  userread,                        
  userseek,                        
  userasyncread,                   
  userasynccancel,                 
  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).

  • For 'userasyncread' and 'userasynccancel' usage, see the 'asyncio' example in the FMOD examples folder. There is also a tutorial in the documentation.
  • If userasyncread callback is specified - userread and userseek will not be called at all, so they can be set to 0 / null.
  • userasyncread allows the user to return immediately before the data is ready. FMOD will either wait internally (see note below about thread safety), or poll in the streamer until data arrives. It is the user's responsibility to provide data in time in the stream case, or the stream may stutter. Data starvation can be detected with Sound::getOpenState.
  • NOTE: If userasyncread is processed in the main thread, then it will hang the application, because FMOD will wait internally until data is ready, and the main thread process will not be able to supply the data. For this reason the user's file access should normally be from a separate thread.

See Also




Version 1.10.03 Built on Feb 1, 2018


previous page start next page