libopenmpt  0.2.3773
cross-platform C++ and C library to decode tracked music files
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
C API

Error Handling

  • Functions with no return value in the corresponding C++ API return 0 on failure and 1 on success.
  • Functions that return a string in the corresponding C++ API return a dynamically allocated const char *. I case of failure or memory allocation failure, a NULL pointer is returned.
  • Functions that return integer values signal error condition by returning an invalid value (-1 in most cases, 0 in some cases).

Strings

  • All strings returned from libopenmpt are encoded in UTF-8.
  • All strings passed to libopenmpt should also be encoded in UTF-8. Behaviour in case of invalid UTF-8 is unspecified.
  • All strings returned from libopenmpt are dynamically allocated and must be freed with openmpt_free_string(). Do NOT used C standard library free() for libopenmpt strings as that would make your code invalid on windows when dynamically linking against libopenmpt which itself statically links to the C runtime.
  • All strings passed to libopenmpt are copied. No ownership is assumed or transferred.

Detailed documentation

libopenmpt C

The C API documentaion currently lacks behind the C++ API documentation. In case a function is not documented here, you might want to look at the libopenmpt C++ documentation. The C and C++ APIs are kept semantically as close as possible.

Examples

FILE*

/*
* libopenmpt_example_c.c
* ----------------------
* Purpose: libopenmpt C API simple example
* Notes : (currently none)
* Authors: OpenMPT Devs
* The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
*/
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <portaudio.h>
#define BUFFERSIZE 480
#define SAMPLERATE 48000
static int16_t left[BUFFERSIZE];
static int16_t right[BUFFERSIZE];
static int16_t* const buffers[2] = {left,right};
int main(int argc,char* argv[]){
FILE* file = 0;
openmpt_module* mod = 0;
size_t count = 0;
PaStream* stream = 0;
PaStreamParameters streamparameters;
memset(&streamparameters,0,sizeof(PaStreamParameters));
(void)argc;
file = fopen(argv[1],"rb");
fclose(file);
Pa_Initialize();
streamparameters.device = Pa_GetDefaultOutputDevice();
streamparameters.channelCount = 2;
streamparameters.sampleFormat = paInt16|paNonInterleaved;
streamparameters.suggestedLatency = Pa_GetDeviceInfo(streamparameters.device)->defaultHighOutputLatency;
Pa_OpenStream(&stream,NULL,&streamparameters,SAMPLERATE,paFramesPerBufferUnspecified,0,NULL,NULL);
Pa_StartStream(stream);
while(1){
count = openmpt_module_read_stereo(mod,SAMPLERATE,BUFFERSIZE,left,right);
if(count==0){
break;
}
Pa_WriteStream(stream,buffers,count);
}
Pa_StopStream(stream);
Pa_CloseStream(stream);
Pa_Terminate();
return 0;
}

in memory

/*
* libopenmpt_example_c_mem.c
* --------------------------
* Purpose: libopenmpt C API simple example
* Notes : (currently none)
* Authors: OpenMPT Devs
* The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
*/
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <portaudio.h>
#define BUFFERSIZE 480
#define SAMPLERATE 48000
static int16_t left[BUFFERSIZE];
static int16_t right[BUFFERSIZE];
static int16_t* const buffers[2] = {left,right};
int main(int argc,char* argv[]){
FILE* file = 0;
size_t size = 0;
void* data = 0;
openmpt_module* mod = 0;
size_t count = 0;
PaStream* stream = 0;
PaStreamParameters streamparameters;
memset(&streamparameters,0,sizeof(PaStreamParameters));
(void)argc;
file = fopen(argv[1],"rb");
fseek(file,0,SEEK_END);
size = ftell(file);
fseek(file,0,SEEK_SET);
data = malloc(size);
size = fread(data,1,size,file);
fclose(file);
mod = openmpt_module_create_from_memory(data,size,NULL,NULL,NULL);
free(data);
Pa_Initialize();
streamparameters.device = Pa_GetDefaultOutputDevice();
streamparameters.channelCount = 2;
streamparameters.sampleFormat = paInt16|paNonInterleaved;
streamparameters.suggestedLatency = Pa_GetDeviceInfo(streamparameters.device)->defaultHighOutputLatency;
Pa_OpenStream(&stream,NULL,&streamparameters,SAMPLERATE,paFramesPerBufferUnspecified,0,NULL,NULL);
Pa_StartStream(stream);
while(1){
count = openmpt_module_read_stereo(mod,SAMPLERATE,BUFFERSIZE,left,right);
if(count==0){
break;
}
Pa_WriteStream(stream,buffers,count);
}
Pa_StopStream(stream);
Pa_CloseStream(stream);
Pa_Terminate();
return 0;
}