|
| 1 | +/* ======================================================================================================== */ |
| 2 | +/* FMOD Studio - codec development header file. Copyright (c), Firelight Technologies Pty, Ltd. 2004-2019. */ |
| 3 | +/* */ |
| 4 | +/* Use this header if you are wanting to develop your own file format plugin to use with */ |
| 5 | +/* FMOD's codec system. With this header you can make your own fileformat plugin that FMOD */ |
| 6 | +/* can register and use. See the documentation and examples on how to make a working plugin. */ |
| 7 | +/* */ |
| 8 | +/* ======================================================================================================== */ |
| 9 | + |
| 10 | +#ifndef _FMOD_CODEC_H |
| 11 | +#define _FMOD_CODEC_H |
| 12 | + |
| 13 | +typedef struct FMOD_CODEC_STATE FMOD_CODEC_STATE; |
| 14 | +typedef struct FMOD_CODEC_WAVEFORMAT FMOD_CODEC_WAVEFORMAT; |
| 15 | + |
| 16 | +/* |
| 17 | + Codec callbacks |
| 18 | +*/ |
| 19 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_OPEN_CALLBACK) (FMOD_CODEC_STATE *codec_state, FMOD_MODE usermode, FMOD_CREATESOUNDEXINFO *userexinfo); |
| 20 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_CLOSE_CALLBACK) (FMOD_CODEC_STATE *codec_state); |
| 21 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_READ_CALLBACK) (FMOD_CODEC_STATE *codec_state, void *buffer, unsigned int samples_in, unsigned int *samples_out); |
| 22 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_GETLENGTH_CALLBACK) (FMOD_CODEC_STATE *codec_state, unsigned int *length, FMOD_TIMEUNIT lengthtype); |
| 23 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_SETPOSITION_CALLBACK) (FMOD_CODEC_STATE *codec_state, int subsound, unsigned int position, FMOD_TIMEUNIT postype); |
| 24 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_GETPOSITION_CALLBACK) (FMOD_CODEC_STATE *codec_state, unsigned int *position, FMOD_TIMEUNIT postype); |
| 25 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_SOUNDCREATE_CALLBACK) (FMOD_CODEC_STATE *codec_state, int subsound, FMOD_SOUND *sound); |
| 26 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_METADATA_CALLBACK) (FMOD_CODEC_STATE *codec_state, FMOD_TAGTYPE tagtype, char *name, void *data, unsigned int datalen, FMOD_TAGDATATYPE datatype, int unique); |
| 27 | +typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_GETWAVEFORMAT_CALLBACK)(FMOD_CODEC_STATE *codec_state, int index, FMOD_CODEC_WAVEFORMAT *waveformat); |
| 28 | + |
| 29 | + |
| 30 | +/* |
| 31 | +[STRUCTURE] |
| 32 | +[ |
| 33 | + [DESCRIPTION] |
| 34 | + When creating a codec, declare one of these and provide the relevant callbacks and name for FMOD to use when it opens and reads a file. |
| 35 | +
|
| 36 | + [REMARKS] |
| 37 | + Members marked with [r] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.<br> |
| 38 | + Members marked with [w] mean the variable can be written to. The user can set the value.<br> |
| 39 | +
|
| 40 | + [SEE_ALSO] |
| 41 | + FMOD_CODEC_STATE |
| 42 | + FMOD_CODEC_WAVEFORMAT |
| 43 | +] |
| 44 | +*/ |
| 45 | +typedef struct FMOD_CODEC_DESCRIPTION |
| 46 | +{ |
| 47 | + const char *name; /* [w] Name of the codec. */ |
| 48 | + unsigned int version; /* [w] Plugin writer's version number. */ |
| 49 | + int defaultasstream; /* [w] Tells FMOD to open the file as a stream when calling System::createSound, and not a static sample. Should normally be 0 (FALSE), because generally the user wants to decode the file into memory when using System::createSound. Mainly used for formats that decode for a very long time, or could use large amounts of memory when decoded. Usually sequenced formats such as mod/s3m/xm/it/midi fall into this category. It is mainly to stop users that don't know what they're doing from getting FMOD_ERR_MEMORY returned from createSound when they should have in fact called System::createStream or used FMOD_CREATESTREAM in System::createSound. */ |
| 50 | + FMOD_TIMEUNIT timeunits; /* [w] When setposition codec is called, only these time formats will be passed to the codec. Use bitwise OR to accumulate different types. */ |
| 51 | + FMOD_CODEC_OPEN_CALLBACK open; /* [w] Open callback for the codec for when FMOD tries to open a sound using this codec. */ |
| 52 | + FMOD_CODEC_CLOSE_CALLBACK close; /* [w] Close callback for the codec for when FMOD tries to close a sound using this codec. */ |
| 53 | + FMOD_CODEC_READ_CALLBACK read; /* [w] Read callback for the codec for when FMOD tries to read some data from the file to the destination format (specified in the open callback). */ |
| 54 | + FMOD_CODEC_GETLENGTH_CALLBACK getlength; /* [w] Callback to return the length of the song in whatever format required when Sound::getLength is called. */ |
| 55 | + FMOD_CODEC_SETPOSITION_CALLBACK setposition; /* [w] Seek callback for the codec for when FMOD tries to seek within the file with Channel::setPosition. */ |
| 56 | + FMOD_CODEC_GETPOSITION_CALLBACK getposition; /* [w] Tell callback for the codec for when FMOD tries to get the current position within the with Channel::getPosition. */ |
| 57 | + FMOD_CODEC_SOUNDCREATE_CALLBACK soundcreate; /* [w] Sound creation callback for the codec when FMOD finishes creating the sound. (So the codec can set more parameters for the related created sound, ie loop points/mode or 3D attributes etc). */ |
| 58 | + FMOD_CODEC_GETWAVEFORMAT_CALLBACK getwaveformat; /* [w] Callback to tell FMOD about the waveformat of a particular subsound. This is to save memory, rather than saving 1000 FMOD_CODEC_WAVEFORMAT structures in the codec, the codec might have a more optimal way of storing this information. */ |
| 59 | +} FMOD_CODEC_DESCRIPTION; |
| 60 | + |
| 61 | + |
| 62 | +/* |
| 63 | +[STRUCTURE] |
| 64 | +[ |
| 65 | + [DESCRIPTION] |
| 66 | + Set these values marked to tell fmod what sort of sound to create when the codec open callback is called.<br> |
| 67 | + The format, channels, frequency and lengthpcm tell FMOD what sort of sound buffer to create when you initialize your code. <br> |
| 68 | + If you wrote an MP3 codec that decoded to stereo 16bit integer PCM for a 44khz sound, you would specify FMOD_SOUND_FORMAT_PCM16, and channels would be equal to 2, and frequency would be 44100.<br> |
| 69 | +
|
| 70 | + [REMARKS] |
| 71 | + Members marked with [r] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.<br> |
| 72 | + Members marked with [w] mean the variable can be written to. The user can set the value.<br> |
| 73 | + <br> |
| 74 | + 1.07 Note. 'blockalign' member which was in bytes has been removed. 'pcmblocksize' is now the replacement, and is measured in PCM samples only, not bytes. This is purely to support buffering |
| 75 | + internal to FMOD for codecs that are not sample accurate. |
| 76 | + <br> |
| 77 | + Note: When registering a codec, format, channels, frequency and lengthpcm must be supplied, otherwise there will be an error.<br> |
| 78 | + This structure is optional if FMOD_CODEC_GETWAVEFORMAT_CALLBACK is specified.<br> |
| 79 | + An array of these structures may be needed if FMOD_CODEC_STATE::numsubsounds is larger than 1. |
| 80 | + |
| 81 | + |
| 82 | + [SEE_ALSO] |
| 83 | + FMOD_CODEC_STATE |
| 84 | + FMOD_SOUND_FORMAT |
| 85 | + FMOD_MODE |
| 86 | + FMOD_CHANNELMASK |
| 87 | + FMOD_CHANNELORDER |
| 88 | + FMOD_CODEC_WAVEFORMAT_VERSION |
| 89 | +] |
| 90 | +*/ |
| 91 | +struct FMOD_CODEC_WAVEFORMAT |
| 92 | +{ |
| 93 | + const char* name; /* [w] Name of sound. Optional. If used, the codec must own the lifetime of the string memory until the codec is destroyed. */ |
| 94 | + FMOD_SOUND_FORMAT format; /* [w] Format for (decompressed) codec output, ie FMOD_SOUND_FORMAT_PCM8, FMOD_SOUND_FORMAT_PCM16. Mandantory - Must be supplied. */ |
| 95 | + int channels; /* [w] Number of channels used by codec, ie mono = 1, stereo = 2. Mandantory - Must be supplied. */ |
| 96 | + int frequency; /* [w] Default frequency in hz of the codec, ie 44100. Mandantory - Must be supplied. */ |
| 97 | + unsigned int lengthbytes; /* [w] Length in bytes of the source data. Used for FMOD_TIMEUNIT_RAWBYTES. Optional. Default = 0. */ |
| 98 | + unsigned int lengthpcm; /* [w] Length in decompressed, PCM samples of the file, ie length in seconds * frequency. Used for Sound::getLength and for memory allocation of static decompressed sample data. Mandantory - Must be supplied. */ |
| 99 | + unsigned int pcmblocksize; /* [w] Minimum, optimal number of decompressed PCM samples codec can handle. 0 or 1 = no buffering. Anything higher means FMOD will allocate a PCM buffer of this size to read in chunks. The codec read callback will be called in multiples of this value. Optional. */ |
| 100 | + int loopstart; /* [w] Loopstart in decompressed, PCM samples of file. Optional. Default = 0. */ |
| 101 | + int loopend; /* [w] Loopend in decompressed, PCM samples of file. Optional. Default = 0. */ |
| 102 | + FMOD_MODE mode; /* [w] Mode to determine whether the sound should by default load as looping, non looping, 2d or 3d. Optional. Default = FMOD_DEFAULT. */ |
| 103 | + FMOD_CHANNELMASK channelmask; /* [w] Defined channel bitmask to describe which speakers the channels in the codec map to, in order of channel count. See fmod_common.h. Optional. Leave at 0 to map to the speaker layout defined in FMOD_SPEAKER. */ |
| 104 | + FMOD_CHANNELORDER channelorder; /* [w] Defined channel order type, to describe where each sound channel should pan for the number of channels specified. See fmod_common.h. Optional. Leave at 0 to play in default speaker order. */ |
| 105 | + float peakvolume; /* [w] Peak volume of sound. Optional. Default = 0 if not used. */ |
| 106 | +}; |
| 107 | + |
| 108 | + |
| 109 | +/* |
| 110 | +[DEFINE] |
| 111 | +[ |
| 112 | + [NAME] |
| 113 | + FMOD_CODEC_WAVEFORMAT_VERSION |
| 114 | +
|
| 115 | + [DESCRIPTION] |
| 116 | + Version number of FMOD_CODEC_WAVEFORMAT structure. Should be set into FMOD_CODEC_STATE in the FMOD_CODEC_OPEN_CALLBACK. |
| 117 | +
|
| 118 | + [REMARKS] |
| 119 | + Use this for binary compatibility and for future expansion. |
| 120 | +
|
| 121 | + [SEE_ALSO] |
| 122 | + FMOD_CODEC_STATE |
| 123 | + FMOD_CODEC_DESCRIPTION |
| 124 | + FMOD_CODEC_OPEN_CALLBACK |
| 125 | +] |
| 126 | +*/ |
| 127 | +#define FMOD_CODEC_WAVEFORMAT_VERSION 3 |
| 128 | +/* [DEFINE_END] */ |
| 129 | + |
| 130 | + |
| 131 | +/* |
| 132 | +[STRUCTURE] |
| 133 | +[ |
| 134 | + [DESCRIPTION] |
| 135 | + Codec plugin structure that is passed into each callback.<br> |
| 136 | + <br> |
| 137 | + Optionally set the numsubsounds and waveformat members when called in FMOD_CODEC_OPEN_CALLBACK to tell fmod what sort of sound to create.<br> |
| 138 | +
|
| 139 | + [REMARKS] |
| 140 | + Members marked with [r] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.<br> |
| 141 | + Members marked with [w] mean the variable can be written to. The user can set the value.<br> |
| 142 | + <br> |
| 143 | + 'numsubsounds' should be 0 if the file is a normal single sound stream or sound. Examples of this would be .WAV, .WMA, .MP3, .AIFF.<br> |
| 144 | + 'numsubsounds' should be 1+ if the file is a container format, and does not contain wav data itself. Examples of these types would be FSB (contains multiple sounds), DLS (contain instruments).<br> |
| 145 | + The waveformat value should point to an arrays of information based on how many subsounds are in the format. If the number of subsounds is 0 then it should point to 1 waveformat, the same as if the number of subsounds was 1. If subsounds was 100 for example, there should be a pointer to an array of 100 waveformat structures.<br> |
| 146 | + <br> |
| 147 | + The waveformat pointer is optional and could be 0, if using FMOD_CODEC_GETWAVEFORMAT_CALLBACK is preferred.<br> |
| 148 | + <br> |
| 149 | + When a sound has 1 or more subsounds, the caller must play the individual sounds specified by first obtaining the subsound with Sound::getSubSound. |
| 150 | + |
| 151 | + [SEE_ALSO] |
| 152 | + FMOD_CODEC_WAVEFORMAT |
| 153 | + FMOD_FILE_READ_CALLBACK |
| 154 | + FMOD_FILE_SEEK_CALLBACK |
| 155 | + FMOD_CODEC_METADATA_CALLBACK |
| 156 | + Sound::getSubSound |
| 157 | + Sound::getNumSubSounds |
| 158 | + FMOD_CODEC_WAVEFORMAT_VERSION |
| 159 | +] |
| 160 | +*/ |
| 161 | +struct FMOD_CODEC_STATE |
| 162 | +{ |
| 163 | + int numsubsounds; /* [w] Number of 'subsounds' in this sound. Anything other than 0 makes it a 'container' format (ie DLS/FSB etc which contain 1 or more subsounds). For most normal, single sound codec such as WAV/AIFF/MP3, this should be 0 as they are not a container for subsounds, they are the sound by itself. */ |
| 164 | + FMOD_CODEC_WAVEFORMAT *waveformat; /* [w] Pointer to an array of format structures containing information about each sample. Can be 0 or NULL if FMOD_CODEC_GETWAVEFORMAT_CALLBACK callback is preferred. The number of entries here must equal the number of subsounds defined in the subsound parameter. If numsubsounds = 0 then there should be 1 instance of this structure. */ |
| 165 | + void *plugindata; /* [w] Plugin writer created data the codec author wants to attach to this object. */ |
| 166 | + |
| 167 | + void *filehandle; /* [r] This will return an internal FMOD file handle to use with the callbacks provided. */ |
| 168 | + unsigned int filesize; /* [r] This will contain the size of the file in bytes. */ |
| 169 | + FMOD_FILE_READ_CALLBACK fileread; /* [r] This will return a callable FMOD file function to use from codec. */ |
| 170 | + FMOD_FILE_SEEK_CALLBACK fileseek; /* [r] This will return a callable FMOD file function to use from codec. */ |
| 171 | + FMOD_CODEC_METADATA_CALLBACK metadata; /* [r] This will return a callable FMOD metadata function to use from codec. */ |
| 172 | + |
| 173 | + int waveformatversion; /* [w] Must be set to FMOD_CODEC_WAVEFORMAT_VERSION in the FMOD_CODEC_OPEN_CALLBACK. */ |
| 174 | +}; |
| 175 | + |
| 176 | +#endif |
| 177 | + |
| 178 | + |
0 commit comments