Firelight Technologies FMOD Studio API

Sound::readData

Reads data from an opened sound to a specified pointer, using the FMOD codec created internally.
This can be used for decoding data offline in small pieces (or big pieces), rather than playing and capturing it, or loading the whole file at once and having to lock / unlock the data.

C++ Syntax

FMOD_RESULT Sound::readData(
  void *buffer,
  unsigned int lenbytes,
  unsigned int *read
);

C Syntax

FMOD_RESULT FMOD_Sound_ReadData(
  FMOD_SOUND *sound,
  void *buffer,
  unsigned int lenbytes,
  unsigned int *read
);

C# Syntax

RESULT Sound.readData(
  IntPtr buffer,
  uint length,
  out uint read
);

JavaScript Syntax

Sound.readData(
  buffer,                          // writes value to buffer.val
  length,                          
  read                             // writes value to read.val
);

Parameters

buffer

Address of a buffer that receives the decoded data from the sound.

lenbytes

Number of bytes to read into the buffer.

read

Number of bytes actually read.

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

If too much data is read, it is possible FMOD_ERR_FILE_EOF will be returned, meaning it is out of data. The 'read' parameter will reflect this by returning a smaller number of bytes read than was requested.
As a sound already reads the whole file then closes it upon calling System::createSound (unless System::createStream or FMOD_CREATESTREAM is used), this function will not work because the file is no longer open.
Note that opening a stream makes it read a chunk of data and this will advance the read cursor. You need to either use FMOD_OPENONLY to stop the stream pre-buffering or call Sound::seekData to reset the read cursor.
If FMOD_OPENONLY flag is used when opening a sound, it will leave the file handle open, and FMOD will not read any data internally, so the read cursor will be at position 0. This will allow the user to read the data from the start.
As noted previously, if a sound is opened as a stream and this function is called to read some data, then you will 'miss the start' of the sound.
Channel::setPosition will have the same result. These function will flush the stream buffer and read in a chunk of audio internally. This is why if you want to read from an absolute position you should use Sound::seekData and not the previously mentioned functions.
Remember if you are calling readData and seekData on a stream it is up to you to cope with the side effects that may occur. Information functions such as Channel::getPosition may give misleading results. Calling Channel::setPosition will reset and flush the stream, leading to the time values returning to their correct position.

NOTE! Thread safety. If you call this from another stream callback, or any other thread besides the main thread, make sure to put a criticalsection around the call, and another around Sound::release in case the sound is still being read from while releasing.
This function is thread safe to call from a stream callback or different thread as long as it doesnt conflict with a call to Sound::release.

See Also

• Sound::seekData
• FMOD_MODE
• Channel::setPosition
• System::createSound
• System::createStream
• Sound::release

Version 1.10.03 Built on Feb 1, 2018