libopenmpt  0.2.5787-autotools
cross-platform C++ and C library to decode tracked music files
libopenmpt.h
Go to the documentation of this file.
1 /*
2  * libopenmpt.h
3  * ------------
4  * Purpose: libopenmpt public c interface
5  * Notes : (currently none)
6  * Authors: OpenMPT Devs
7  * The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
8  */
9 
10 #ifndef LIBOPENMPT_H
11 #define LIBOPENMPT_H
12 
13 #include "libopenmpt_config.h"
14 #include <stddef.h>
15 #include <stdint.h>
16 
72 #ifdef __cplusplus
73 extern "C" {
74 #endif
75 
81 LIBOPENMPT_API uint32_t openmpt_get_library_version(void);
82 
88 LIBOPENMPT_API uint32_t openmpt_get_core_version(void);
89 
91 #define OPENMPT_STRING_LIBRARY_VERSION "library_version"
92 
93 #define OPENMPT_STRING_LIBRARY_FEATURES "library_features"
94 
95 #define OPENMPT_STRING_CORE_VERSION "core_version"
96 
97 #define OPENMPT_STRING_BUILD "build"
98 
99 #define OPENMPT_STRING_CREDITS "credits"
100 
101 #define OPENMPT_STRING_CONTACT "contact"
102 
103 #define OPENMPT_STRING_LICENSE "license"
104 
109 LIBOPENMPT_API void openmpt_free_string( const char * str );
110 
122 LIBOPENMPT_API const char * openmpt_get_string( const char * key );
123 
128 LIBOPENMPT_API const char * openmpt_get_supported_extensions(void);
129 
135 LIBOPENMPT_API int openmpt_is_extension_supported( const char * extension );
136 
137 #define OPENMPT_STREAM_SEEK_SET 0
138 #define OPENMPT_STREAM_SEEK_CUR 1
139 #define OPENMPT_STREAM_SEEK_END 2
140 
150 typedef size_t (*openmpt_stream_read_func)( void * stream, void * dst, size_t bytes );
151 
162 typedef int (*openmpt_stream_seek_func)( void * stream, int64_t offset, int whence );
163 
171 typedef int64_t (*openmpt_stream_tell_func)( void * stream );
172 
177 typedef struct openmpt_stream_callbacks {
178 
184 
191 
198 
200 
206 typedef void (*openmpt_log_func)( const char * message, void * user );
207 
212 LIBOPENMPT_API void openmpt_log_func_default( const char * message, void * user );
213 
218 LIBOPENMPT_API void openmpt_log_func_silent( const char * message, void * user );
219 
230 LIBOPENMPT_API double openmpt_could_open_propability( openmpt_stream_callbacks stream_callbacks, void * stream, double effort, openmpt_log_func logfunc, void * user );
231 
235 
237  const char * ctl;
238  const char * value;
240 
252 LIBOPENMPT_API openmpt_module * openmpt_module_create( openmpt_stream_callbacks stream_callbacks, void * stream, openmpt_log_func logfunc, void * user, const openmpt_module_initial_ctl * ctls );
253 
264 LIBOPENMPT_API openmpt_module * openmpt_module_create_from_memory( const void * filedata, size_t filesize, openmpt_log_func logfunc, void * user, const openmpt_module_initial_ctl * ctls );
265 
270 LIBOPENMPT_API void openmpt_module_destroy( openmpt_module * mod );
271 
278 #define OPENMPT_MODULE_RENDER_MASTERGAIN_MILLIBEL 1
279 
285 #define OPENMPT_MODULE_RENDER_STEREOSEPARATION_PERCENT 2
286 
298 #define OPENMPT_MODULE_RENDER_INTERPOLATIONFILTER_LENGTH 3
299 
307 #define OPENMPT_MODULE_RENDER_VOLUMERAMPING_STRENGTH 4
308 
311 #define OPENMPT_MODULE_COMMAND_NOTE 0
312 #define OPENMPT_MODULE_COMMAND_INSTRUMENT 1
313 #define OPENMPT_MODULE_COMMAND_VOLUMEEFFECT 2
314 #define OPENMPT_MODULE_COMMAND_EFFECT 3
315 #define OPENMPT_MODULE_COMMAND_VOLUME 4
316 #define OPENMPT_MODULE_COMMAND_PARAMETER 5
317 
325 LIBOPENMPT_API int openmpt_module_select_subsong( openmpt_module * mod, int32_t subsong );
336 LIBOPENMPT_API int openmpt_module_set_repeat_count( openmpt_module * mod, int32_t repeat_count );
346 LIBOPENMPT_API int32_t openmpt_module_get_repeat_count( openmpt_module * mod );
347 
353 LIBOPENMPT_API double openmpt_module_get_duration_seconds( openmpt_module * mod );
354 
362 LIBOPENMPT_API double openmpt_module_set_position_seconds( openmpt_module * mod, double seconds );
369 LIBOPENMPT_API double openmpt_module_get_position_seconds( openmpt_module * mod );
370 
381 LIBOPENMPT_API double openmpt_module_set_position_order_row( openmpt_module * mod, int32_t order, int32_t row );
382 
395 LIBOPENMPT_API int openmpt_module_get_render_param( openmpt_module * mod, int param, int32_t * value );
408 LIBOPENMPT_API int openmpt_module_set_render_param( openmpt_module * mod, int param, int32_t value );
409 
423 LIBOPENMPT_API size_t openmpt_module_read_mono( openmpt_module * mod, int32_t samplerate, size_t count, int16_t * mono );
437 LIBOPENMPT_API size_t openmpt_module_read_stereo( openmpt_module * mod, int32_t samplerate, size_t count, int16_t * left, int16_t * right );
453 LIBOPENMPT_API size_t openmpt_module_read_quad( openmpt_module * mod, int32_t samplerate, size_t count, int16_t * left, int16_t * right, int16_t * rear_left, int16_t * rear_right );
466 LIBOPENMPT_API size_t openmpt_module_read_float_mono( openmpt_module * mod, int32_t samplerate, size_t count, float * mono );
480 LIBOPENMPT_API size_t openmpt_module_read_float_stereo( openmpt_module * mod, int32_t samplerate, size_t count, float * left, float * right );
496 LIBOPENMPT_API size_t openmpt_module_read_float_quad( openmpt_module * mod, int32_t samplerate, size_t count, float * left, float * right, float * rear_left, float * rear_right );
509 LIBOPENMPT_API size_t openmpt_module_read_interleaved_stereo( openmpt_module * mod, int32_t samplerate, size_t count, int16_t * interleaved_stereo );
522 LIBOPENMPT_API size_t openmpt_module_read_interleaved_quad( openmpt_module * mod, int32_t samplerate, size_t count, int16_t * interleaved_quad );
535 LIBOPENMPT_API size_t openmpt_module_read_interleaved_float_stereo( openmpt_module * mod, int32_t samplerate, size_t count, float * interleaved_stereo );
548 LIBOPENMPT_API size_t openmpt_module_read_interleaved_float_quad( openmpt_module * mod, int32_t samplerate, size_t count, float * interleaved_quad );
557 LIBOPENMPT_API const char * openmpt_module_get_metadata_keys( openmpt_module * mod );
577 LIBOPENMPT_API const char * openmpt_module_get_metadata( openmpt_module * mod, const char * key );
578 
584 LIBOPENMPT_API int32_t openmpt_module_get_current_speed( openmpt_module * mod );
590 LIBOPENMPT_API int32_t openmpt_module_get_current_tempo( openmpt_module * mod );
596 LIBOPENMPT_API int32_t openmpt_module_get_current_order( openmpt_module * mod );
602 LIBOPENMPT_API int32_t openmpt_module_get_current_pattern( openmpt_module * mod );
608 LIBOPENMPT_API int32_t openmpt_module_get_current_row( openmpt_module * mod );
614 LIBOPENMPT_API int32_t openmpt_module_get_current_playing_channels( openmpt_module * mod );
615 
623 LIBOPENMPT_API float openmpt_module_get_current_channel_vu_mono( openmpt_module * mod, int32_t channel );
631 LIBOPENMPT_API float openmpt_module_get_current_channel_vu_left( openmpt_module * mod, int32_t channel );
639 LIBOPENMPT_API float openmpt_module_get_current_channel_vu_right( openmpt_module * mod, int32_t channel );
647 LIBOPENMPT_API float openmpt_module_get_current_channel_vu_rear_left( openmpt_module * mod, int32_t channel );
655 LIBOPENMPT_API float openmpt_module_get_current_channel_vu_rear_right( openmpt_module * mod, int32_t channel );
656 
663 LIBOPENMPT_API int32_t openmpt_module_get_num_subsongs( openmpt_module * mod );
669 LIBOPENMPT_API int32_t openmpt_module_get_num_channels( openmpt_module * mod );
675 LIBOPENMPT_API int32_t openmpt_module_get_num_orders( openmpt_module * mod );
681 LIBOPENMPT_API int32_t openmpt_module_get_num_patterns( openmpt_module * mod );
687 LIBOPENMPT_API int32_t openmpt_module_get_num_instruments( openmpt_module * mod );
693 LIBOPENMPT_API int32_t openmpt_module_get_num_samples( openmpt_module * mod );
694 
702 LIBOPENMPT_API const char * openmpt_module_get_subsong_name( openmpt_module * mod, int32_t index );
710 LIBOPENMPT_API const char * openmpt_module_get_channel_name( openmpt_module * mod, int32_t index );
718 LIBOPENMPT_API const char * openmpt_module_get_order_name( openmpt_module * mod, int32_t index );
726 LIBOPENMPT_API const char * openmpt_module_get_pattern_name( openmpt_module * mod, int32_t index );
734 LIBOPENMPT_API const char * openmpt_module_get_instrument_name( openmpt_module * mod, int32_t index );
742 LIBOPENMPT_API const char * openmpt_module_get_sample_name( openmpt_module * mod, int32_t index );
743 
750 LIBOPENMPT_API int32_t openmpt_module_get_order_pattern( openmpt_module * mod, int32_t order );
757 LIBOPENMPT_API int32_t openmpt_module_get_pattern_num_rows( openmpt_module * mod, int32_t pattern );
758 
768 LIBOPENMPT_API uint8_t openmpt_module_get_pattern_row_channel_command( openmpt_module * mod, int32_t pattern, int32_t row, int32_t channel, int command );
769 
780 LIBOPENMPT_API const char * openmpt_module_format_pattern_row_channel_command( openmpt_module * mod, int32_t pattern, int32_t row, int32_t channel, int command );
802 LIBOPENMPT_API const char * openmpt_module_highlight_pattern_row_channel_command( openmpt_module * mod, int32_t pattern, int32_t row, int32_t channel, int command );
803 
815 LIBOPENMPT_API const char * openmpt_module_format_pattern_row_channel( openmpt_module * mod, int32_t pattern, int32_t row, int32_t channel, size_t width, int pad );
827 LIBOPENMPT_API const char * openmpt_module_highlight_pattern_row_channel( openmpt_module * mod, int32_t pattern, int32_t row, int32_t channel, size_t width, int pad );
828 
846 LIBOPENMPT_API const char * openmpt_module_get_ctls( openmpt_module * mod );
854 LIBOPENMPT_API const char * openmpt_module_ctl_get( openmpt_module * mod, const char * ctl );
862 LIBOPENMPT_API int openmpt_module_ctl_set( openmpt_module * mod, const char * ctl, const char * value );
863 
864 /* remember to add new functions to both C and C++ interfaces and to increase OPENMPT_API_VERSION_MINOR */
865 
866 #ifdef __cplusplus
867 }
868 #endif
869 
874 #endif /* LIBOPENMPT_H */
int32_t openmpt_module_get_current_tempo(openmpt_module *mod)
Get the current tempo.
uint32_t openmpt_get_core_version(void)
Get the core version number.
size_t openmpt_module_read_stereo(openmpt_module *mod, int32_t samplerate, size_t count, int16_t *left, int16_t *right)
Render audio data.
const char * openmpt_get_string(const char *key)
Get library related metadata.
void openmpt_log_func_silent(const char *message, void *user)
Silent logging function.
int32_t openmpt_module_get_pattern_num_rows(openmpt_module *mod, int32_t pattern)
Get the number of rows in a pattern.
int openmpt_module_select_subsong(openmpt_module *mod, int32_t subsong)
Select a subsong from a multi-song module.
size_t openmpt_module_read_float_stereo(openmpt_module *mod, int32_t samplerate, size_t count, float *left, float *right)
Render audio data.
struct openmpt_stream_callbacks openmpt_stream_callbacks
Stream callbacks.
int openmpt_module_get_render_param(openmpt_module *mod, int param, int32_t *value)
Get render parameter.
size_t openmpt_module_read_interleaved_float_stereo(openmpt_module *mod, int32_t samplerate, size_t count, float *interleaved_stereo)
Render audio data.
const char * ctl
Definition: libopenmpt.h:237
const char * openmpt_module_get_instrument_name(openmpt_module *mod, int32_t index)
Get an instrument name.
int openmpt_module_set_repeat_count(openmpt_module *mod, int32_t repeat_count)
Set Repeat Count.
void openmpt_free_string(const char *str)
Free a string returned by libopenmpt.
double openmpt_module_set_position_seconds(openmpt_module *mod, double seconds)
Set approximate current song position.
int32_t openmpt_module_get_current_pattern(openmpt_module *mod)
Get the current pattern.
openmpt_stream_tell_func tell
Tell callback.
Definition: libopenmpt.h:197
void(* openmpt_log_func)(const char *message, void *user)
Logging function.
Definition: libopenmpt.h:206
size_t openmpt_module_read_float_quad(openmpt_module *mod, int32_t samplerate, size_t count, float *left, float *right, float *rear_left, float *rear_right)
Render audio data.
openmpt_module * openmpt_module_create(openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *user, const openmpt_module_initial_ctl *ctls)
Construct an openmpt_module.
float openmpt_module_get_current_channel_vu_right(openmpt_module *mod, int32_t channel)
Get an approximate indication of the channel volume on the front-right speaker.
const char * openmpt_module_format_pattern_row_channel_command(openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
Get formatted (human-readable) pattern content.
size_t openmpt_module_read_mono(openmpt_module *mod, int32_t samplerate, size_t count, int16_t *mono)
Render audio data.
double openmpt_could_open_propability(openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *user)
Roughly scan the input stream to find out whether libopenmpt might be able to open it...
const char * openmpt_module_get_metadata(openmpt_module *mod, const char *key)
Get a metadata item value.
size_t openmpt_module_read_interleaved_quad(openmpt_module *mod, int32_t samplerate, size_t count, int16_t *interleaved_quad)
Render audio data.
const char * value
Definition: libopenmpt.h:238
int32_t openmpt_module_get_num_patterns(openmpt_module *mod)
Get the number of patterns.
float openmpt_module_get_current_channel_vu_rear_right(openmpt_module *mod, int32_t channel)
Get an approximate indication of the channel volume on the rear-right speaker.
int32_t openmpt_module_get_repeat_count(openmpt_module *mod)
Get Repeat Count.
size_t openmpt_module_read_interleaved_stereo(openmpt_module *mod, int32_t samplerate, size_t count, int16_t *interleaved_stereo)
Render audio data.
const char * openmpt_module_highlight_pattern_row_channel(openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, size_t width, int pad)
Get highlighting information for formatted pattern content.
int(* openmpt_stream_seek_func)(void *stream, int64_t offset, int whence)
Seek stream position.
Definition: libopenmpt.h:162
struct openmpt_module openmpt_module
Opaque type representing a libopenmpt module.
Definition: libopenmpt.h:234
const char * openmpt_module_get_order_name(openmpt_module *mod, int32_t index)
Get an order name.
int openmpt_module_ctl_set(openmpt_module *mod, const char *ctl, const char *value)
Set ctl value.
struct openmpt_module_initial_ctl openmpt_module_initial_ctl
double openmpt_module_set_position_order_row(openmpt_module *mod, int32_t order, int32_t row)
Set approximate current song position.
const char * openmpt_module_get_metadata_keys(openmpt_module *mod)
Get the list of supported metadata item keys.
uint32_t openmpt_get_library_version(void)
Get the libopenmpt version number.
int openmpt_is_extension_supported(const char *extension)
Query whether a file extension is supported.
const char * openmpt_module_get_sample_name(openmpt_module *mod, int32_t index)
Get a sample name.
const char * openmpt_module_format_pattern_row_channel(openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, size_t width, int pad)
Get formatted (human-readable) pattern content.
Stream callbacks.
Definition: libopenmpt.h:177
int32_t openmpt_module_get_num_samples(openmpt_module *mod)
Get the number of samples.
double openmpt_module_get_position_seconds(openmpt_module *mod)
Get current song position.
int openmpt_module_set_render_param(openmpt_module *mod, int param, int32_t value)
Set render parameter.
int32_t openmpt_module_get_current_playing_channels(openmpt_module *mod)
Get the current amount of playing channels.
size_t openmpt_module_read_float_mono(openmpt_module *mod, int32_t samplerate, size_t count, float *mono)
Render audio data.
int32_t openmpt_module_get_current_order(openmpt_module *mod)
Get the current order.
size_t openmpt_module_read_interleaved_float_quad(openmpt_module *mod, int32_t samplerate, size_t count, float *interleaved_quad)
Render audio data.
const char * openmpt_module_ctl_get(openmpt_module *mod, const char *ctl)
Get current ctl value.
size_t(* openmpt_stream_read_func)(void *stream, void *dst, size_t bytes)
Read bytes from stream.
Definition: libopenmpt.h:150
const char * openmpt_module_get_channel_name(openmpt_module *mod, int32_t index)
Get a channel name.
int64_t(* openmpt_stream_tell_func)(void *stream)
Tell stream position.
Definition: libopenmpt.h:171
const char * openmpt_module_get_pattern_name(openmpt_module *mod, int32_t index)
Get a pattern name.
openmpt_stream_read_func read
Read callback.
Definition: libopenmpt.h:183
double openmpt_module_get_duration_seconds(openmpt_module *mod)
approximate song duration
const char * openmpt_module_get_subsong_name(openmpt_module *mod, int32_t index)
Get a subsong name.
void openmpt_module_destroy(openmpt_module *mod)
Unload a previously created openmpt_module from memory.
int32_t openmpt_module_get_num_channels(openmpt_module *mod)
Get the number of pattern channels.
const char * openmpt_get_supported_extensions(void)
Get a list of supported file extensions.
int32_t openmpt_module_get_current_row(openmpt_module *mod)
Get the current row.
const char * openmpt_module_get_ctls(openmpt_module *mod)
Retrieve supported ctl keys.
float openmpt_module_get_current_channel_vu_left(openmpt_module *mod, int32_t channel)
Get an approximate indication of the channel volume on the front-left speaker.
const char * openmpt_module_highlight_pattern_row_channel_command(openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
Get highlighting information for formatted pattern content.
int32_t openmpt_module_get_order_pattern(openmpt_module *mod, int32_t order)
Get pattern at order position.
float openmpt_module_get_current_channel_vu_mono(openmpt_module *mod, int32_t channel)
Get an approximate indication of the channel volume.
int32_t openmpt_module_get_num_orders(openmpt_module *mod)
Get the number of orders.
uint8_t openmpt_module_get_pattern_row_channel_command(openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
Get raw pattern content.
openmpt_stream_seek_func seek
Seek callback.
Definition: libopenmpt.h:190
int32_t openmpt_module_get_num_instruments(openmpt_module *mod)
Get the number of instruments.
int32_t openmpt_module_get_num_subsongs(openmpt_module *mod)
Get the number of subsongs.
Definition: libopenmpt.h:236
openmpt_module * openmpt_module_create_from_memory(const void *filedata, size_t filesize, openmpt_log_func logfunc, void *user, const openmpt_module_initial_ctl *ctls)
Construct an openmpt_module.
size_t openmpt_module_read_quad(openmpt_module *mod, int32_t samplerate, size_t count, int16_t *left, int16_t *right, int16_t *rear_left, int16_t *rear_right)
Render audio data.
float openmpt_module_get_current_channel_vu_rear_left(openmpt_module *mod, int32_t channel)
Get an approximate indication of the channel volume on the rear-left speaker.
void openmpt_log_func_default(const char *message, void *user)
Default logging function.
int32_t openmpt_module_get_current_speed(openmpt_module *mod)
Get the current speed.