FMOD_CODEC_OPEN_CALLBACK

FMOD Studio API

previous page next page

Firelight Technologies FMOD Studio API

FMOD_CODEC_OPEN_CALLBACK

Open callback for the codec for when FMOD tries to open a sound using this codec. This is the callback the file format check is done in, codec related memory is allocated, and things are generally initialized / set up for the codec.

C/C++ Syntax

FMOD_RESULT F_CALLBACK FMOD_CODEC_OPEN_CALLBACK(
  FMOD_CODEC_STATE *codec_state,
  FMOD_MODE usermode,
  FMOD_CREATESOUNDEXINFO *userexinfo
);

Parameters

codec_state

Pointer to the codec state. The user can use this variable to access runtime plugin specific variables and plugin writer user data.

usermode

Mode that the user supplied via System::createSound. This is informational and can be ignored, or used if it has relevance to your codec.

userexinfo

Extra info structure that the user supplied via System::createSound. This is informational and can be ignored, or used if it has relevance to your codec.

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

The usermode and userexinfo parameters tell the codec what was passed in by the user.
Generally these can be ignored, as the file format usually determines the format and frequency of the sound.

If you have a flexible format codec (ie you don't mind what output format your codec writes to), you might want to use the parameter that was passed in by the user to specify the output sound format / frequency.

For example if you normally create a codec that is always 32bit floating point, the user might supply 16bit integer to save memory, so you could use this information to decode your data to this format instead of the original default format.

Read and seek within the file using the 'fileread' and 'fileseek' members of the FMOD_CODEC codec that is passed in.
Note: DO NOT USE YOUR OWN FILESYSTEM.
The reasons for this are:

  • The user may have set their own file system via user filesystem callbacks.
  • FMOD allows file reading via disk, memory and TCP/IP. If you use your own file routines you will lose this ability.

Important! FMOD will ping all codecs trying to find the right one for the file the user has passed in. Make sure the first line of your codec open is a FAST format check. Ie it reads an identifying string, checks it and returns an error FMOD_ERR_FORMAT if it is not found.

There may be a lot of codecs loaded into FMOD, so you don't want yours slowing down the System::createSound call because it is inneficient in determining if it is the right format or not.

Remember to return FMOD_OK at the bottom of the function, or an appropriate error code from FMOD_RESULT.

See Also




Version 1.10.03 Built on Feb 1, 2018


previous page start next page