PonyTracker
Un projet de tracker de musique
 Tout Structures de données Espaces de nommage Fichiers Fonctions Variables Définitions de type Énumérations Valeurs énumérées Macros Pages
fmod_codec.h
Aller à la documentation de ce fichier.
1 /* ==================================================================================================== */
2 /* FMOD Ex - codec development header file. Copyright (c), Firelight Technologies Pty, Ltd. 2004-2014. */
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 
15 
16 /*
17  Codec callbacks
18 */
19 typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_OPENCALLBACK) (FMOD_CODEC_STATE *codec_state, FMOD_MODE usermode, FMOD_CREATESOUNDEXINFO *userexinfo);
20 typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_CLOSECALLBACK) (FMOD_CODEC_STATE *codec_state);
21 typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_READCALLBACK) (FMOD_CODEC_STATE *codec_state, void *buffer, unsigned int sizebytes, unsigned int *bytesread);
22 typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_GETLENGTHCALLBACK) (FMOD_CODEC_STATE *codec_state, unsigned int *length, FMOD_TIMEUNIT lengthtype);
23 typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_SETPOSITIONCALLBACK) (FMOD_CODEC_STATE *codec_state, int subsound, unsigned int position, FMOD_TIMEUNIT postype);
24 typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_GETPOSITIONCALLBACK) (FMOD_CODEC_STATE *codec_state, unsigned int *position, FMOD_TIMEUNIT postype);
25 typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_SOUNDCREATECALLBACK) (FMOD_CODEC_STATE *codec_state, int subsound, FMOD_SOUND *sound);
26 typedef FMOD_RESULT (F_CALLBACK *FMOD_CODEC_METADATACALLBACK) (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) (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 [in] mean the variable can be written to. The user can set the value.<br>
38  Members marked with [out] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.<br>
39 
40  [PLATFORMS]
41  Win32, Win64, Linux, Linux64, Macintosh, Xbox360, PlayStation Portable, PlayStation 3, Wii, iPhone, 3GS, NGP, Android
42 
43  [SEE_ALSO]
44  FMOD_CODEC_STATE
45 ]
46 */
47 typedef struct FMOD_CODEC_DESCRIPTION
48 {
49  const char *name; /* [in] Name of the codec. */
50  unsigned int version; /* [in] Plugin writer's version number. */
51  int defaultasstream; /* [in] 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. */
52  FMOD_TIMEUNIT timeunits; /* [in] When setposition codec is called, only these time formats will be passed to the codec. Use bitwise OR to accumulate different types. */
53  FMOD_CODEC_OPENCALLBACK open; /* [in] Open callback for the codec for when FMOD tries to open a sound using this codec. */
54  FMOD_CODEC_CLOSECALLBACK close; /* [in] Close callback for the codec for when FMOD tries to close a sound using this codec. */
55  FMOD_CODEC_READCALLBACK read; /* [in] 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). */
56  FMOD_CODEC_GETLENGTHCALLBACK getlength; /* [in] Callback to return the length of the song in whatever format required when Sound::getLength is called. */
57  FMOD_CODEC_SETPOSITIONCALLBACK setposition; /* [in] Seek callback for the codec for when FMOD tries to seek within the file with Channel::setPosition. */
58  FMOD_CODEC_GETPOSITIONCALLBACK getposition; /* [in] Tell callback for the codec for when FMOD tries to get the current position within the with Channel::getPosition. */
59  FMOD_CODEC_SOUNDCREATECALLBACK soundcreate; /* [in] 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). */
60  FMOD_CODEC_GETWAVEFORMAT getwaveformat; /* [in] 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. */
62 
63 
64 /*
65 [STRUCTURE]
66 [
67  [DESCRIPTION]
68  Set these values marked 'in' to tell fmod what sort of sound to create.<br>
69  The format, channels and frequency tell FMOD what sort of hardware buffer to create when you initialize your code. So if you wrote an MP3 codec that decoded to stereo 16bit integer PCM, you would specify FMOD_SOUND_FORMAT_PCM16, and channels would be equal to 2.<br>
70  Members marked as 'out' are set by fmod. Do not modify these. Simply specify 0 for these values when declaring the structure, FMOD will fill in the values for you after creation with the correct function pointers.<br>
71 
72  [REMARKS]
73  Members marked with [in] mean the variable can be written to. The user can set the value.<br>
74  Members marked with [out] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.<br>
75  <br>
76  An FMOD file might be from disk, memory or network, however the file may be opened by the user.<br>
77  <br>
78  '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>
79  'numsubsounds' should be 1+ if the file is a container format, and does not contain wav data itself. Examples of these types would be CDDA (multiple CD tracks), FSB (contains multiple sounds), MIDI/MOD/S3M/XM/IT (contain instruments).<br>
80  The arrays of format, channel, frequency, length and blockalign should point to 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 of each attribute, the same as if the number of subsounds was 1. If subsounds was 100 for example, each pointer should point to an array of 100 of each attribute.<br>
81  When a sound has 1 or more subsounds, you must play the individual sounds specified by first obtaining the subsound with Sound::getSubSound.
82 
83  [PLATFORMS]
84  Win32, Win64, Linux, Linux64, Macintosh, Xbox360, PlayStation Portable, PlayStation 3, Wii, iPhone, 3GS, NGP, Android
85 
86  [SEE_ALSO]
87  FMOD_SOUND_FORMAT
88  FMOD_FILE_READCALLBACK
89  FMOD_FILE_SEEKCALLBACK
90  FMOD_CODEC_METADATACALLBACK
91  Sound::getSubSound
92  Sound::getNumSubSounds
93 ]
94 */
96 {
97  char name[256]; /* [in] Name of sound.*/
98  FMOD_SOUND_FORMAT format; /* [in] Format for (decompressed) codec output, ie FMOD_SOUND_FORMAT_PCM8, FMOD_SOUND_FORMAT_PCM16.*/
99  int channels; /* [in] Number of channels used by codec, ie mono = 1, stereo = 2. */
100  int frequency; /* [in] Default frequency in hz of the codec, ie 44100. */
101  unsigned int lengthbytes; /* [in] Length in bytes of the source data. */
102  unsigned int lengthpcm; /* [in] 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. */
103  int blockalign; /* [in] Blockalign in decompressed, PCM samples of the optimal decode chunk size for this format. The codec read callback will be called in multiples of this value. */
104  int loopstart; /* [in] Loopstart in decompressed, PCM samples of file. */
105  int loopend; /* [in] Loopend in decompressed, PCM samples of file. */
106  FMOD_MODE mode; /* [in] Mode to determine whether the sound should by default load as looping, non looping, 2d or 3d. */
107  unsigned int channelmask; /* [in] Microsoft speaker channel mask, as defined for WAVEFORMATEXTENSIBLE and is found in ksmedia.h. Leave at 0 to play in natural speaker order. */
108 };
109 
110 
111 /*
112 [STRUCTURE]
113 [
114  [DESCRIPTION]
115  Codec plugin structure that is passed into each callback.<br>
116  <br>
117  Set these numsubsounds and waveformat members when called in FMOD_CODEC_OPENCALLBACK to tell fmod what sort of sound to create.<br>
118  <br>
119  The format, channels and frequency tell FMOD what sort of hardware buffer to create when you initialize your code. So if you wrote an MP3 codec that decoded to stereo 16bit integer PCM, you would specify FMOD_SOUND_FORMAT_PCM16, and channels would be equal to 2.<br>
120 
121  [REMARKS]
122  Members marked with [in] mean the variable can be written to. The user can set the value.<br>
123  Members marked with [out] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.<br>
124  <br>
125  An FMOD file might be from disk, memory or internet, however the file may be opened by the user.<br>
126  <br>
127  '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>
128  'numsubsounds' should be 1+ if the file is a container format, and does not contain wav data itself. Examples of these types would be CDDA (multiple CD tracks), FSB (contains multiple sounds), DLS (contain instruments).<br>
129  The arrays of format, channel, frequency, length and blockalign should point to 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 of each attribute, the same as if the number of subsounds was 1. If subsounds was 100 for example, each pointer should point to an array of 100 of each attribute.<br>
130  When a sound has 1 or more subsounds, you must play the individual sounds specified by first obtaining the subsound with Sound::getSubSound.
131 
132  [PLATFORMS]
133  Win32, Win64, Linux, Linux64, Macintosh, Xbox360, PlayStation Portable, PlayStation 3, Wii, iPhone, 3GS, NGP, Android
134 
135  [SEE_ALSO]
136  FMOD_SOUND_FORMAT
137  FMOD_FILE_READCALLBACK
138  FMOD_FILE_SEEKCALLBACK
139  FMOD_CODEC_METADATACALLBACK
140  Sound::getSubSound
141  Sound::getNumSubSounds
142 ]
143 */
145 {
146  int numsubsounds; /* [in] Number of 'subsounds' in this sound. Anything other than 0 makes it a 'container' format (ie CDDA/DLS/FSB etc which contain 1 or more su bsounds). 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. */
147  FMOD_CODEC_WAVEFORMAT *waveformat; /* [in] Pointer to an array of format structures containing information about each sample. Can be 0 or NULL if FMOD_CODEC_GETWAVEFORMAT 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. */
148  void *plugindata; /* [in] Plugin writer created data the codec author wants to attach to this object. */
149 
150  void *filehandle; /* [out] This will return an internal FMOD file handle to use with the callbacks provided. */
151  unsigned int filesize; /* [out] This will contain the size of the file in bytes. */
152  FMOD_FILE_READCALLBACK fileread; /* [out] This will return a callable FMOD file function to use from codec. */
153  FMOD_FILE_SEEKCALLBACK fileseek; /* [out] This will return a callable FMOD file function to use from codec. */
154  FMOD_CODEC_METADATACALLBACK metadata; /* [out] This will return a callable FMOD metadata function to use from codec. */
155 };
156 
157 #endif
158 
159 
FMOD_SOUND_FORMAT
Definition: fmod.h:826
FMOD_TIMEUNIT timeunits
Definition: fmod_codec.h:52
FMOD_CODEC_METADATACALLBACK metadata
Definition: fmod_codec.h:154
FMOD_TAGTYPE tagtype
Definition: fmod_codec.h:26
struct FMOD_SOUND FMOD_SOUND
Definition: fmod.h:65
FMOD_TAGTYPE char * name
Definition: fmod_codec.h:26
FMOD_TAGTYPE char void unsigned int FMOD_TAGDATATYPE datatype
Definition: fmod_codec.h:26
int FMOD_SOUND * sound
Definition: fmod_codec.h:25
FMOD_CODEC_GETWAVEFORMAT getwaveformat
Definition: fmod_codec.h:60
unsigned int version
Definition: fmod_codec.h:50
FMOD_CODEC_OPENCALLBACK open
Definition: fmod_codec.h:53
FMOD_SOUND_FORMAT format
Definition: fmod_codec.h:98
void unsigned int sizebytes
Definition: fmod_codec.h:21
FMOD_CODEC_GETPOSITIONCALLBACK getposition
Definition: fmod_codec.h:58
FMOD_CODEC_WAVEFORMAT * waveformat
Definition: fmod_codec.h:147
FMOD_TAGDATATYPE
Definition: fmod.h:1229
FMOD_TAGTYPE char void unsigned int datalen
Definition: fmod_codec.h:26
unsigned int channelmask
Definition: fmod_codec.h:107
void unsigned int unsigned int * bytesread
Definition: fmod_codec.h:21
FMOD_CODEC_SOUNDCREATECALLBACK soundcreate
Definition: fmod_codec.h:59
FMOD_CODEC_READCALLBACK read
Definition: fmod_codec.h:55
FMOD_TAGTYPE char void unsigned int FMOD_TAGDATATYPE int unique
Definition: fmod_codec.h:26
FMOD_FILE_READCALLBACK fileread
Definition: fmod_codec.h:152
unsigned int lengthbytes
Definition: fmod_codec.h:101
int unsigned int position
Definition: fmod_codec.h:23
typedef FMOD_RESULT(F_CALLBACK *FMOD_CODEC_OPENCALLBACK)(FMOD_CODEC_STATE *codec_state
FMOD_CODEC_SETPOSITIONCALLBACK setposition
Definition: fmod_codec.h:57
int unsigned int FMOD_TIMEUNIT postype
Definition: fmod_codec.h:23
FMOD_CODEC_GETLENGTHCALLBACK getlength
Definition: fmod_codec.h:56
unsigned int lengthpcm
Definition: fmod_codec.h:102
unsigned int filesize
Definition: fmod_codec.h:151
int subsound
Definition: fmod_codec.h:23
int FMOD_CODEC_WAVEFORMAT * waveformat
Definition: fmod_codec.h:27
struct FMOD_CODEC_DESCRIPTION FMOD_CODEC_DESCRIPTION
FMOD_CODEC_CLOSECALLBACK close
Definition: fmod_codec.h:54
unsigned int FMOD_MODE
Definition: fmod.h:75
void * buffer
Definition: fmod_codec.h:21
int index
Definition: fmod_codec.h:27
unsigned int FMOD_TIMEUNIT
Definition: fmod.h:76
unsigned int FMOD_TIMEUNIT lengthtype
Definition: fmod_codec.h:22
FMOD_FILE_SEEKCALLBACK fileseek
Definition: fmod_codec.h:153
FMOD_TAGTYPE char void * data
Definition: fmod_codec.h:26
FMOD_TAGTYPE
Definition: fmod.h:1195
const char * name
Definition: fmod_codec.h:49
FMOD_MODE FMOD_CREATESOUNDEXINFO * userexinfo
Definition: fmod_codec.h:19
unsigned int * length
Definition: fmod_codec.h:22
#define F_CALLBACK
Definition: fmod.h:57
FMOD_MODE usermode
Definition: fmod_codec.h:19