libopenmpt C

Modules
	Render param indices
	Parameter index to use with openmpt_module_get_render_param() and openmpt_module_set_render_param()
	Pattern cell indices
	Parameter index to use with openmpt_module_get_pattern_row_channel_command(), openmpt_module_format_pattern_row_channel_command() and openmpt_module_highlight_pattern_row_channel_command()

Classes
struct	openmpt_stream_callbacks
	Stream callbacks. More...
struct	openmpt_module_initial_ctl
struct	openmpt_stream_buffer
struct	openmpt_stream_buffer2

Macros
#define	OPENMPT_STRING_LIBRARY_VERSION   LIBOPENMPT_DEPRECATED_STRING( "library_version" )
#define	OPENMPT_STRING_LIBRARY_FEATURES   LIBOPENMPT_DEPRECATED_STRING( "library_features" )
#define	OPENMPT_STRING_CORE_VERSION   LIBOPENMPT_DEPRECATED_STRING( "core_version" )
#define	OPENMPT_STRING_BUILD   LIBOPENMPT_DEPRECATED_STRING( "build" )
#define	OPENMPT_STRING_CREDITS   LIBOPENMPT_DEPRECATED_STRING( "credits" )
#define	OPENMPT_STRING_CONTACT   LIBOPENMPT_DEPRECATED_STRING( "contact" )
#define	OPENMPT_STRING_LICENSE   LIBOPENMPT_DEPRECATED_STRING( "license" )
#define	OPENMPT_STREAM_SEEK_SET   0
#define	OPENMPT_STREAM_SEEK_CUR   1
#define	OPENMPT_STREAM_SEEK_END   2
#define	OPENMPT_ERROR_OK   0
#define	OPENMPT_ERROR_BASE   256
#define	OPENMPT_ERROR_UNKNOWN   ( OPENMPT_ERROR_BASE + 1 )
#define	OPENMPT_ERROR_EXCEPTION   ( OPENMPT_ERROR_BASE + 11 )
#define	OPENMPT_ERROR_OUT_OF_MEMORY   ( OPENMPT_ERROR_BASE + 21 )
#define	OPENMPT_ERROR_RUNTIME   ( OPENMPT_ERROR_BASE + 30 )
#define	OPENMPT_ERROR_RANGE   ( OPENMPT_ERROR_BASE + 31 )
#define	OPENMPT_ERROR_OVERFLOW   ( OPENMPT_ERROR_BASE + 32 )
#define	OPENMPT_ERROR_UNDERFLOW   ( OPENMPT_ERROR_BASE + 33 )
#define	OPENMPT_ERROR_LOGIC   ( OPENMPT_ERROR_BASE + 40 )
#define	OPENMPT_ERROR_DOMAIN   ( OPENMPT_ERROR_BASE + 41 )
#define	OPENMPT_ERROR_LENGTH   ( OPENMPT_ERROR_BASE + 42 )
#define	OPENMPT_ERROR_OUT_OF_RANGE   ( OPENMPT_ERROR_BASE + 43 )
#define	OPENMPT_ERROR_INVALID_ARGUMENT   ( OPENMPT_ERROR_BASE + 44 )
#define	OPENMPT_ERROR_GENERAL   ( OPENMPT_ERROR_BASE + 101 )
#define	OPENMPT_ERROR_INVALID_MODULE_POINTER   ( OPENMPT_ERROR_BASE + 102 )
#define	OPENMPT_ERROR_ARGUMENT_NULL_POINTER   ( OPENMPT_ERROR_BASE + 103 )
#define	OPENMPT_ERROR_FUNC_RESULT_NONE   0
#define	OPENMPT_ERROR_FUNC_RESULT_LOG   ( 1 << 0 )
#define	OPENMPT_ERROR_FUNC_RESULT_STORE   ( 1 << 1 )
#define	OPENMPT_ERROR_FUNC_RESULT_DEFAULT   ( OPENMPT_ERROR_FUNC_RESULT_LOG | OPENMPT_ERROR_FUNC_RESULT_STORE )
#define	OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES   0x1ull
#define	OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS   0x2ull
#define	OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT   ( OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES | OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS )
#define	OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE   0x0ull
#define	OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS   1
#define	OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE   0
#define	OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA   (-1)
#define	OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR   (-255)
#define	openmpt_stream_buffer_init_prefix_only(buffer_, prefix_data_, prefix_size_, file_size_)
#define	openmpt_stream_buffer_overflowed(buffer_)   ( (buffer_)->overflow )
#define	LIBOPENMPT_STREAM_CALLBACKS_BUFFER
	Defined if libopenmpt/libopenmpt_stream_callbacks_buffer.h exists. More...
#define	LIBOPENMPT_STREAM_CALLBACKS_FD
	Defined if libopenmpt/libopenmpt_stream_callbacks_fd.h exists. More...
#define	LIBOPENMPT_STREAM_CALLBACKS_FILE
	Defined if libopenmpt/libopenmpt_stream_callbacks_file.h exists. More...
#define	LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW
	Defined if libopenmpt/libopenmpt_stream_callbacks_file_mingw.h exists. More...
#define	LIBOPENMPT_STREAM_CALLBACKS_FILE_MSVCRT
	Defined if libopenmpt/libopenmpt_stream_callbacks_file_msvcrt.h exists. More...
#define	LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX
	Defined if libopenmpt/libopenmpt_stream_callbacks_file_posix.h exists. More...
#define	LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX_LFS64
	Defined if libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h exists. More...

Typedefs
typedef size_t(*	openmpt_stream_read_func) (void *stream, void *dst, size_t bytes)
	Read bytes from stream. More...
typedef int(*	openmpt_stream_seek_func) (void *stream, int64_t offset, int whence)
	Seek stream position. More...
typedef int64_t(*	openmpt_stream_tell_func) (void *stream)
	Tell stream position. More...
typedef struct openmpt_stream_callbacks	openmpt_stream_callbacks
	Stream callbacks. More...
typedef void(*	openmpt_log_func) (const char *message, void *user)
	Logging function. More...
typedef int(*	openmpt_error_func) (int error, void *user)
	Error function. More...
typedef struct openmpt_module	openmpt_module
	Opaque type representing a libopenmpt module. More...
typedef struct openmpt_module_initial_ctl	openmpt_module_initial_ctl
typedef struct openmpt_stream_buffer	openmpt_stream_buffer
typedef struct openmpt_stream_buffer2	openmpt_stream_buffer2

Functions
uint32_t	openmpt_get_library_version (void)
	Get the libopenmpt version number. More...
uint32_t	openmpt_get_core_version (void)
	Get the core version number. More...
void	openmpt_free_string (const char *str)
	Free a string returned by libopenmpt. More...
const char *	openmpt_get_string (const char *key)
	Get library related metadata. More...
const char *	openmpt_get_supported_extensions (void)
	Get a list of supported file extensions. More...
int	openmpt_is_extension_supported (const char *extension)
	Query whether a file extension is supported. More...
void	openmpt_log_func_default (const char *message, void *user)
	Default logging function. More...
void	openmpt_log_func_silent (const char *message, void *user)
	Silent logging function. More...
int	openmpt_error_is_transient (int error)
	Check whether the error is transient. More...
const char *	openmpt_error_string (int error)
	Convert error code to text. More...
int	openmpt_error_func_default (int error, void *user)
	Default error function. More...
int	openmpt_error_func_log (int error, void *user)
	Log error function. More...
int	openmpt_error_func_store (int error, void *user)
	Store error function. More...
int	openmpt_error_func_ignore (int error, void *user)
	Ignore error function. More...
int	openmpt_error_func_errno (int error, void *user)
	Errno error function. More...
void *	openmpt_error_func_errno_userdata (int *error)
	User pointer for openmpt_error_func_errno. More...
double	openmpt_could_open_probability (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. More...
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. More...
double	openmpt_could_open_probability2 (openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
	Roughly scan the input stream to find out whether libopenmpt might be able to open it. More...
size_t	openmpt_probe_file_header_get_recommended_size (void)
	Get recommended header size for successfull format probing. More...
int	openmpt_probe_file_header (uint64_t flags, const void *data, size_t size, uint64_t filesize, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
	Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it. More...
int	openmpt_probe_file_header_without_filesize (uint64_t flags, const void *data, size_t size, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
	Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it. More...
int	openmpt_probe_file_header_from_stream (uint64_t flags, openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
	Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it. More...
openmpt_module *	openmpt_module_create (openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, const openmpt_module_initial_ctl *ctls)
	Construct an openmpt_module. More...
openmpt_module *	openmpt_module_create2 (openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message, const openmpt_module_initial_ctl *ctls)
	Construct an openmpt_module. More...
openmpt_module *	openmpt_module_create_from_memory (const void *filedata, size_t filesize, openmpt_log_func logfunc, void *loguser, const openmpt_module_initial_ctl *ctls)
	Construct an openmpt_module. More...
openmpt_module *	openmpt_module_create_from_memory2 (const void *filedata, size_t filesize, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message, const openmpt_module_initial_ctl *ctls)
	Construct an openmpt_module. More...
void	openmpt_module_destroy (openmpt_module *mod)
	Unload a previously created openmpt_module from memory. More...
void	openmpt_module_set_log_func (openmpt_module *mod, openmpt_log_func logfunc, void *loguser)
	Set logging function. More...
void	openmpt_module_set_error_func (openmpt_module *mod, openmpt_error_func errfunc, void *erruser)
	Set error function. More...
int	openmpt_module_error_get_last (openmpt_module *mod)
	Get last error. More...
const char *	openmpt_module_error_get_last_message (openmpt_module *mod)
	Get last error message. More...
void	openmpt_module_error_set_last (openmpt_module *mod, int error)
	Set last error. More...
void	openmpt_module_error_clear (openmpt_module *mod)
	Clear last error. More...
int	openmpt_module_select_subsong (openmpt_module *mod, int32_t subsong)
	Select a sub-song from a multi-song module. More...
int32_t	openmpt_module_get_selected_subsong (openmpt_module *mod)
	Get currently selected sub-song from a multi-song module. More...
int	openmpt_module_set_repeat_count (openmpt_module *mod, int32_t repeat_count)
	Set Repeat Count. More...
int32_t	openmpt_module_get_repeat_count (openmpt_module *mod)
	Get Repeat Count. More...
double	openmpt_module_get_duration_seconds (openmpt_module *mod)
	approximate song duration More...
double	openmpt_module_set_position_seconds (openmpt_module *mod, double seconds)
	Set approximate current song position. More...
double	openmpt_module_get_position_seconds (openmpt_module *mod)
	Get current song position. More...
double	openmpt_module_set_position_order_row (openmpt_module *mod, int32_t order, int32_t row)
	Set approximate current song position. More...
int	openmpt_module_get_render_param (openmpt_module *mod, int param, int32_t *value)
	Get render parameter. More...
int	openmpt_module_set_render_param (openmpt_module *mod, int param, int32_t value)
	Set render parameter. More...
size_t	openmpt_module_read_mono (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *mono)
	Render audio data. More...
size_t	openmpt_module_read_stereo (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *left, int16_t *right)
	Render audio data. More...
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. More...
size_t	openmpt_module_read_float_mono (openmpt_module *mod, int32_t samplerate, size_t count, float *mono)
	Render audio data. More...
size_t	openmpt_module_read_float_stereo (openmpt_module *mod, int32_t samplerate, size_t count, float *left, float *right)
	Render audio data. More...
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. More...
size_t	openmpt_module_read_interleaved_stereo (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *interleaved_stereo)
	Render audio data. More...
size_t	openmpt_module_read_interleaved_quad (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *interleaved_quad)
	Render audio data. More...
size_t	openmpt_module_read_interleaved_float_stereo (openmpt_module *mod, int32_t samplerate, size_t count, float *interleaved_stereo)
	Render audio data. More...
size_t	openmpt_module_read_interleaved_float_quad (openmpt_module *mod, int32_t samplerate, size_t count, float *interleaved_quad)
	Render audio data. More...
const char *	openmpt_module_get_metadata_keys (openmpt_module *mod)
	Get the list of supported metadata item keys. More...
const char *	openmpt_module_get_metadata (openmpt_module *mod, const char *key)
	Get a metadata item value. More...
double	openmpt_module_get_current_estimated_bpm (openmpt_module *mod)
int32_t	openmpt_module_get_current_speed (openmpt_module *mod)
	Get the current speed. More...
int32_t	openmpt_module_get_current_tempo (openmpt_module *mod)
	Get the current tempo. More...
double	openmpt_module_get_current_tempo2 (openmpt_module *mod)
	Get the current tempo. More...
int32_t	openmpt_module_get_current_order (openmpt_module *mod)
	Get the current order. More...
int32_t	openmpt_module_get_current_pattern (openmpt_module *mod)
	Get the current pattern. More...
int32_t	openmpt_module_get_current_row (openmpt_module *mod)
	Get the current row. More...
int32_t	openmpt_module_get_current_playing_channels (openmpt_module *mod)
	Get the current amount of playing channels. More...
float	openmpt_module_get_current_channel_vu_mono (openmpt_module *mod, int32_t channel)
	Get an approximate indication of the channel volume. More...
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. More...
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. More...
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. More...
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. More...
int32_t	openmpt_module_get_num_subsongs (openmpt_module *mod)
	Get the number of sub-songs. More...
int32_t	openmpt_module_get_num_channels (openmpt_module *mod)
	Get the number of pattern channels. More...
int32_t	openmpt_module_get_num_orders (openmpt_module *mod)
	Get the number of orders. More...
int32_t	openmpt_module_get_num_patterns (openmpt_module *mod)
	Get the number of patterns. More...
int32_t	openmpt_module_get_num_instruments (openmpt_module *mod)
	Get the number of instruments. More...
int32_t	openmpt_module_get_num_samples (openmpt_module *mod)
	Get the number of samples. More...
const char *	openmpt_module_get_subsong_name (openmpt_module *mod, int32_t index)
	Get a sub-song name. More...
const char *	openmpt_module_get_channel_name (openmpt_module *mod, int32_t index)
	Get a channel name. More...
const char *	openmpt_module_get_order_name (openmpt_module *mod, int32_t index)
	Get an order name. More...
const char *	openmpt_module_get_pattern_name (openmpt_module *mod, int32_t index)
	Get a pattern name. More...
const char *	openmpt_module_get_instrument_name (openmpt_module *mod, int32_t index)
	Get an instrument name. More...
const char *	openmpt_module_get_sample_name (openmpt_module *mod, int32_t index)
	Get a sample name. More...
int32_t	openmpt_module_get_order_pattern (openmpt_module *mod, int32_t order)
	Get pattern at order position. More...
int32_t	openmpt_module_get_pattern_num_rows (openmpt_module *mod, int32_t pattern)
	Get the number of rows in a pattern. More...
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. More...
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. More...
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. More...
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. More...
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. More...
const char *	openmpt_module_get_ctls (openmpt_module *mod)
	Retrieve supported ctl keys. More...
const char *	openmpt_module_ctl_get (openmpt_module *mod, const char *ctl)
	Get current ctl value. More...
int	openmpt_module_ctl_get_boolean (openmpt_module *mod, const char *ctl)
	Get current ctl boolean value. More...
int64_t	openmpt_module_ctl_get_integer (openmpt_module *mod, const char *ctl)
	Get current ctl integer value. More...
double	openmpt_module_ctl_get_floatingpoint (openmpt_module *mod, const char *ctl)
	Get current ctl floatingpoint value. More...
const char *	openmpt_module_ctl_get_text (openmpt_module *mod, const char *ctl)
	Get current ctl string value. More...
int	openmpt_module_ctl_set (openmpt_module *mod, const char *ctl, const char *value)
	Set ctl value. More...
int	openmpt_module_ctl_set_boolean (openmpt_module *mod, const char *ctl, int value)
	Set ctl boolean value. More...
int	openmpt_module_ctl_set_integer (openmpt_module *mod, const char *ctl, int64_t value)
	Set ctl integer value. More...
int	openmpt_module_ctl_set_floatingpoint (openmpt_module *mod, const char *ctl, double value)
	Set ctl floatingpoint value. More...
int	openmpt_module_ctl_set_text (openmpt_module *mod, const char *ctl, const char *value)
	Set ctl string value. More...
static size_t	openmpt_stream_buffer_read_func (void *stream, void *dst, size_t bytes)
static int	openmpt_stream_buffer_seek_func (void *stream, int64_t offset, int whence)
static int64_t	openmpt_stream_buffer_tell_func (void *stream)
static void	openmpt_stream_buffer_init (openmpt_stream_buffer *buffer, const void *file_data, int64_t file_size)
static openmpt_stream_callbacks	openmpt_stream_get_buffer_callbacks (void)
	Provide openmpt_stream_callbacks for in-memoy buffers. More...
static size_t	openmpt_stream_buffer_read_func2 (void *stream, void *dst, size_t bytes)
static int	openmpt_stream_buffer_seek_func2 (void *stream, int64_t offset, int whence)
static int64_t	openmpt_stream_buffer_tell_func2 (void *stream)
static void	openmpt_stream_buffer_init2 (openmpt_stream_buffer2 *buffer, const void *file_data, int64_t file_size)
static openmpt_stream_callbacks	openmpt_stream_get_buffer_callbacks2 (void)
	Provide openmpt_stream_callbacks for in-memoy buffers. More...
static size_t	openmpt_stream_fd_read_func (void *stream, void *dst, size_t bytes)
static openmpt_stream_callbacks	openmpt_stream_get_fd_callbacks (void)
	Provide openmpt_stream_callbacks for standard POSIX file descriptors. More...
static size_t	openmpt_stream_file_read_func (void *stream, void *dst, size_t bytes)
static int	openmpt_stream_file_seek_func (void *stream, int64_t offset, int whence)
static int64_t	openmpt_stream_file_tell_func (void *stream)
static openmpt_stream_callbacks	openmpt_stream_get_file_callbacks (void)
	Provide openmpt_stream_callbacks for standard C FILE objects. More...
static openmpt_stream_callbacks	openmpt_stream_get_file_callbacks2 (void)
	Provide openmpt_stream_callbacks for standard C FILE objects. More...
static size_t	openmpt_stream_file_mingw_read_func (void *stream, void *dst, size_t bytes)
static int	openmpt_stream_file_mingw_seek_func (void *stream, int64_t offset, int whence)
static int64_t	openmpt_stream_file_mingw_tell_func (void *stream)
static openmpt_stream_callbacks	openmpt_stream_get_file_mingw_callbacks (void)
	Provide openmpt_stream_callbacks for standard C FILE objects. More...
static size_t	openmpt_stream_file_msvcrt_read_func (void *stream, void *dst, size_t bytes)
static int	openmpt_stream_file_msvcrt_seek_func (void *stream, int64_t offset, int whence)
static int64_t	openmpt_stream_file_msvcrt_tell_func (void *stream)
static openmpt_stream_callbacks	openmpt_stream_get_file_msvcrt_callbacks (void)
	Provide openmpt_stream_callbacks for standard C FILE objects. More...
static size_t	openmpt_stream_file_posix_read_func (void *stream, void *dst, size_t bytes)
static int	openmpt_stream_file_posix_seek_func (void *stream, int64_t offset, int whence)
static int64_t	openmpt_stream_file_posix_tell_func (void *stream)
static openmpt_stream_callbacks	openmpt_stream_get_file_posix_callbacks (void)
	Provide openmpt_stream_callbacks for standard C FILE objects. More...
static size_t	openmpt_stream_file_posix_lfs64_read_func (void *stream, void *dst, size_t bytes)
static int	openmpt_stream_file_posix_lfs64_seek_func (void *stream, int64_t offset, int whence)
static int64_t	openmpt_stream_file_posix_lfs64_tell_func (void *stream)
static openmpt_stream_callbacks	openmpt_stream_get_file_posix_lfs64_callbacks (void)
	Provide openmpt_stream_callbacks for standard C FILE objects. More...

Detailed Description

Macro Definition Documentation

LIBOPENMPT_STREAM_CALLBACKS_BUFFER

#define LIBOPENMPT_STREAM_CALLBACKS_BUFFER

Defined if libopenmpt/libopenmpt_stream_callbacks_buffer.h exists.

Remarks

Use the following to check for availability:

#include <libopenmpt/libopenmpt.h>
#if defined(LIBOPENMPT_STREAM_CALLBACKS_BUFFER)
#include <libopenmpt/libopenmpt_stream_callbacks_buffer.h>
#endif

LIBOPENMPT_STREAM_CALLBACKS_FD

#define LIBOPENMPT_STREAM_CALLBACKS_FD

Defined if libopenmpt/libopenmpt_stream_callbacks_fd.h exists.

Since

0.3.0

Remarks

Use the following to check for availability:

#include <libopenmpt/libopenmpt.h>
#if defined(LIBOPENMPT_STREAM_CALLBACKS_FD) || ((OPENMPT_API_VERSION_MAJOR == 0) && ((OPENMPT_API_VERSION_MINOR == 2) || (OPENMPT_API_VERSION_MINOR == 1)))
#include <libopenmpt/libopenmpt_stream_callbacks_fd.h>
#endif

LIBOPENMPT_STREAM_CALLBACKS_FILE

#define LIBOPENMPT_STREAM_CALLBACKS_FILE

Defined if libopenmpt/libopenmpt_stream_callbacks_file.h exists.

Since

0.3.0

Remarks

Use the following to check for availability:

#include <libopenmpt/libopenmpt.h>
#if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE) || ((OPENMPT_API_VERSION_MAJOR == 0) && ((OPENMPT_API_VERSION_MINOR == 2) || (OPENMPT_API_VERSION_MINOR == 1)))
#include <libopenmpt/libopenmpt_stream_callbacks_file.h>
#endif

LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW

#define LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW

Defined if libopenmpt/libopenmpt_stream_callbacks_file_mingw.h exists.

Since

0.7.0

Remarks

This macro does not determine if the interfaces required to use libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h are available. It is the libopenmpt user's responsibility to check for availability of the _off64_t, _ftelli64(), and _fseeki64(). Use the following to check for availability:

#include <libopenmpt/libopenmpt.h>
#if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW)
#include <libopenmpt/libopenmpt_stream_callbacks_file_mingw.h>
#endif

LIBOPENMPT_STREAM_CALLBACKS_FILE_MSVCRT

#define LIBOPENMPT_STREAM_CALLBACKS_FILE_MSVCRT

Defined if libopenmpt/libopenmpt_stream_callbacks_file_msvcrt.h exists.

Since

0.7.0

Remarks

This macro does not determine if the interfaces required to use libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h are available. It is the libopenmpt user's responsibility to check for availability of the __int64, _ftelli64(), and _fseeki64(). Use the following to check for availability:

#include <libopenmpt/libopenmpt.h>
#if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE_MSVCRT)
#include <libopenmpt/libopenmpt_stream_callbacks_file_msvcrt.h>
#endif

LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX

#define LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX

Defined if libopenmpt/libopenmpt_stream_callbacks_file_posix.h exists.

Since

0.7.0

Remarks

This macro does not determine if the interfaces required to use libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h are available. It is the libopenmpt user's responsibility to check for availability of the _off_t, ftello(), and fseeko(). Use the following to check for availability:

#include <libopenmpt/libopenmpt.h>
#if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW)
#include <libopenmpt/libopenmpt_stream_callbacks_file_mingw.h>
#endif

LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX_LFS64

#define LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX_LFS64

Defined if libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h exists.

Since

0.7.0

Remarks

This macro does not determine if the interfaces required to use libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h are available. It is the libopenmpt user's responsibility to check for availability of the off64_t, ftello64(), and fseeko64(). Use the following to check for availability:

#include <libopenmpt/libopenmpt.h>
#if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX_LFS64)
#include <libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h>
#endif

OPENMPT_ERROR_ARGUMENT_NULL_POINTER

#define OPENMPT_ERROR_ARGUMENT_NULL_POINTER   ( OPENMPT_ERROR_BASE + 103 )

NULL pointer argument.

Since

0.3.0

OPENMPT_ERROR_BASE

#define OPENMPT_ERROR_BASE   256

Lowest value libopenmpt will use for any of its own error codes.

Since

0.3.0

OPENMPT_ERROR_DOMAIN

#define OPENMPT_ERROR_DOMAIN   ( OPENMPT_ERROR_BASE + 41 )

Value domain error.

Since

0.3.0

OPENMPT_ERROR_EXCEPTION

#define OPENMPT_ERROR_EXCEPTION   ( OPENMPT_ERROR_BASE + 11 )

Unknown internal C++ exception.

Since

0.3.0

OPENMPT_ERROR_FUNC_RESULT_DEFAULT

#define OPENMPT_ERROR_FUNC_RESULT_DEFAULT   ( OPENMPT_ERROR_FUNC_RESULT_LOG | OPENMPT_ERROR_FUNC_RESULT_STORE )

Log and store the error.

Since

0.3.0

OPENMPT_ERROR_FUNC_RESULT_LOG

#define OPENMPT_ERROR_FUNC_RESULT_LOG   ( 1 << 0 )

Log the error.

Since

0.3.0

OPENMPT_ERROR_FUNC_RESULT_NONE

#define OPENMPT_ERROR_FUNC_RESULT_NONE   0

Do not log or store the error.

Since

0.3.0

OPENMPT_ERROR_FUNC_RESULT_STORE

#define OPENMPT_ERROR_FUNC_RESULT_STORE   ( 1 << 1 )

Store the error.

Since

0.3.0

OPENMPT_ERROR_GENERAL

#define OPENMPT_ERROR_GENERAL   ( OPENMPT_ERROR_BASE + 101 )

General libopenmpt error.

Since

0.3.0

OPENMPT_ERROR_INVALID_ARGUMENT

#define OPENMPT_ERROR_INVALID_ARGUMENT   ( OPENMPT_ERROR_BASE + 44 )

Invalid argument.

Since

0.3.0

OPENMPT_ERROR_INVALID_MODULE_POINTER

#define OPENMPT_ERROR_INVALID_MODULE_POINTER   ( OPENMPT_ERROR_BASE + 102 )

openmpt_module * is invalid.

Since

0.3.0

OPENMPT_ERROR_LENGTH

#define OPENMPT_ERROR_LENGTH   ( OPENMPT_ERROR_BASE + 42 )

Maximum supported size exceeded.

Since

0.3.0

OPENMPT_ERROR_LOGIC

#define OPENMPT_ERROR_LOGIC   ( OPENMPT_ERROR_BASE + 40 )

Logic error.

Since

0.3.0

OPENMPT_ERROR_OK

#define OPENMPT_ERROR_OK   0

No error.

Since

0.3.0

OPENMPT_ERROR_OUT_OF_MEMORY

#define OPENMPT_ERROR_OUT_OF_MEMORY   ( OPENMPT_ERROR_BASE + 21 )

Out of memory.

Since

0.3.0

OPENMPT_ERROR_OUT_OF_RANGE

#define OPENMPT_ERROR_OUT_OF_RANGE   ( OPENMPT_ERROR_BASE + 43 )

Argument out of range.

Since

0.3.0

OPENMPT_ERROR_OVERFLOW

#define OPENMPT_ERROR_OVERFLOW   ( OPENMPT_ERROR_BASE + 32 )

Arithmetic overflow.

Since

0.3.0

OPENMPT_ERROR_RANGE

#define OPENMPT_ERROR_RANGE   ( OPENMPT_ERROR_BASE + 31 )

Range error.

Since

0.3.0

OPENMPT_ERROR_RUNTIME

#define OPENMPT_ERROR_RUNTIME   ( OPENMPT_ERROR_BASE + 30 )

Runtime error.

Since

0.3.0

OPENMPT_ERROR_UNDERFLOW

#define OPENMPT_ERROR_UNDERFLOW   ( OPENMPT_ERROR_BASE + 33 )

Arithmetic underflow.

Since

0.3.0

OPENMPT_ERROR_UNKNOWN

#define OPENMPT_ERROR_UNKNOWN   ( OPENMPT_ERROR_BASE + 1 )

Unknown internal error.

Since

0.3.0

OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS   0x2ull

Probe for module-specific container formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since

0.3.0

OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT   ( OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES | OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS )

Probe for the default set of formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since

0.3.0

OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES   0x1ull

Probe for module formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since

0.3.0

OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE   0x0ull

Probe for no formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since

0.3.0

OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR

#define OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR   (-255)

Possible return values for openmpt_probe_file_header() and openmpt_probe_file_header_without_filesize(): An internal error occurred.

Since

0.3.0

OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE

#define OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE   0

Possible return values for openmpt_probe_file_header() and openmpt_probe_file_header_without_filesize(): The file is not supported by libopenmpt.

Since

0.3.0

OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS

#define OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS   1

Possible return values for openmpt_probe_file_header() and openmpt_probe_file_header_without_filesize(): The file will most likely be supported by libopenmpt.

Since

0.3.0

OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA

#define OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA   (-1)

Possible return values for openmpt_probe_file_header() and openmpt_probe_file_header_without_filesize(): An answer could not be determined with the amount of data provided.

Since

0.3.0

openmpt_stream_buffer_init_prefix_only

#define openmpt_stream_buffer_init_prefix_only	(		buffer_,
			prefix_data_,
			prefix_size_,
			file_size_
	)

Value:

  do { \
  openmpt_stream_buffer_init( (buffer_), (prefix_data_), (file_size_) ); \
  (buffer_)->prefix_size = (prefix_size_); \
} while(0)

openmpt_stream_buffer_overflowed

#define openmpt_stream_buffer_overflowed

(

buffer_

)

( (buffer_)->overflow )

OPENMPT_STREAM_SEEK_CUR

#define OPENMPT_STREAM_SEEK_CUR   1

Seek to the given offset relative to the current position in the file.

OPENMPT_STREAM_SEEK_END

#define OPENMPT_STREAM_SEEK_END   2

Seek to the given offset relative to the end of the file.

OPENMPT_STREAM_SEEK_SET

#define OPENMPT_STREAM_SEEK_SET   0

Seek to the given offset relative to the beginning of the file.

OPENMPT_STRING_BUILD

#define OPENMPT_STRING_BUILD   LIBOPENMPT_DEPRECATED_STRING( "build" )

Return information about the current build (e.g. the build date or compiler used) from openmpt_get_string().

Deprecated:

Please use "build" directly.

OPENMPT_STRING_CONTACT

#define OPENMPT_STRING_CONTACT   LIBOPENMPT_DEPRECATED_STRING( "contact" )

Return contact information about libopenmpt from openmpt_get_string().

Deprecated:

Please use "contact" directly.

OPENMPT_STRING_CORE_VERSION

#define OPENMPT_STRING_CORE_VERSION   LIBOPENMPT_DEPRECATED_STRING( "core_version" )

Return a verbose OpenMPT core version string from openmpt_get_string().

Deprecated:

Please use "core_version" directly.

OPENMPT_STRING_CREDITS

#define OPENMPT_STRING_CREDITS   LIBOPENMPT_DEPRECATED_STRING( "credits" )

Return all contributors from openmpt_get_string().

Deprecated:

Please use "credits" directly.

OPENMPT_STRING_LIBRARY_FEATURES

#define OPENMPT_STRING_LIBRARY_FEATURES   LIBOPENMPT_DEPRECATED_STRING( "library_features" )

Return a verbose library features string from openmpt_get_string().

Deprecated:

Please use "library_features" directly.

OPENMPT_STRING_LIBRARY_VERSION

#define OPENMPT_STRING_LIBRARY_VERSION   LIBOPENMPT_DEPRECATED_STRING( "library_version" )

Return a verbose library version string from openmpt_get_string().

Deprecated:

Please use "library_version" directly.

OPENMPT_STRING_LICENSE

#define OPENMPT_STRING_LICENSE   LIBOPENMPT_DEPRECATED_STRING( "license" )

Return the libopenmpt license from openmpt_get_string().

Deprecated:

Please use "license" directly.

Typedef Documentation

openmpt_error_func

typedef int(* openmpt_error_func) (int error, void *user)

Error function.

Parameters

error	Error code.
user	User context that was passed to openmpt_module_create2(), openmpt_module_create_from_memory2() or openmpt_could_open_probability2().

Returns

Mask of OPENMPT_ERROR_FUNC_RESULT_LOG and OPENMPT_ERROR_FUNC_RESULT_STORE.

Return values

OPENMPT_ERROR_FUNC_RESULT_NONE	Do not log or store the error.
OPENMPT_ERROR_FUNC_RESULT_LOG	Log the error.
OPENMPT_ERROR_FUNC_RESULT_STORE	Store the error.
OPENMPT_ERROR_FUNC_RESULT_DEFAULT	Log and store the error.

See also

OPENMPT_ERROR_FUNC_RESULT_NONE

OPENMPT_ERROR_FUNC_RESULT_LOG

OPENMPT_ERROR_FUNC_RESULT_STORE

OPENMPT_ERROR_FUNC_RESULT_DEFAULT

openmpt_error_func_default

openmpt_error_func_log

openmpt_error_func_store

openmpt_error_func_ignore

openmpt_error_func_errno

Since

0.3.0

openmpt_log_func

typedef void(* openmpt_log_func) (const char *message, void *user)

Logging function.

Parameters

message	UTF-8 encoded log message.
user	User context that was passed to openmpt_module_create2(), openmpt_module_create_from_memory2() or openmpt_could_open_probability2().

openmpt_module

typedef struct openmpt_module openmpt_module

Opaque type representing a libopenmpt module.

openmpt_module_initial_ctl

typedef struct openmpt_module_initial_ctl openmpt_module_initial_ctl

openmpt_stream_buffer

typedef struct openmpt_stream_buffer openmpt_stream_buffer

openmpt_stream_buffer2

typedef struct openmpt_stream_buffer2 openmpt_stream_buffer2

openmpt_stream_callbacks

typedef struct openmpt_stream_callbacks openmpt_stream_callbacks

Stream callbacks.

Stream callbacks used by libopenmpt for stream operations.

See also

openmpt_stream_get_file_callbacks

openmpt_stream_get_fd_callbacks

openmpt_stream_get_buffer_callbacks

openmpt_stream_read_func

typedef size_t(* openmpt_stream_read_func) (void *stream, void *dst, size_t bytes)

Read bytes from stream.

Read bytes data from stream to dst.

Parameters

stream	Stream to read data from
dst	Target where to copy data.
bytes	Number of bytes to read.

Returns

Number of bytes actually read and written to dst.

Return values

0	End of stream or error.

Remarks

Short reads are allowed as long as they return at least 1 byte if EOF is not reached.

openmpt_stream_seek_func

typedef int(* openmpt_stream_seek_func) (void *stream, int64_t offset, int whence)

Seek stream position.

Seek to stream position offset at whence.

Parameters

stream	Stream to operate on.
offset	Offset to seek to.
whence	OPENMPT_STREAM_SEEK_SET, OPENMPT_STREAM_SEEK_CUR, OPENMPT_STREAM_SEEK_END. See C89 documentation.

Returns

Returns 0 on success.

Return values

0	Success.
-1	Failure. Position does not get updated.

Remarks

libopenmpt will not try to seek beyond the file size, thus it is not important whether you allow for virtual positioning after the file end, or return an error in that case. The position equal to the file size needs to be seekable to.

openmpt_stream_tell_func

typedef int64_t(* openmpt_stream_tell_func) (void *stream)

Tell stream position.

Tell position of stream.

Parameters

stream

Stream to operate on.

Returns

Current position in stream.

Return values

-1

Failure.

Function Documentation

openmpt_could_open_probability()

double openmpt_could_open_probability	(	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.

Parameters

stream_callbacks	Input stream callback operations.
stream	Input stream to scan.
effort	Effort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
logfunc	Logging function where warning and errors are written. May be NULL.
user	Logging function user context. Used to pass any user-defined data associated with this module to the logging function.

Returns

Probability between 0.0 and 1.0.

Remarks

openmpt_could_open_probability() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).

openmpt_could_open_probability() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability() returned 0.5.

See also

File I/O

openmpt_stream_callbacks

Deprecated:

Please use openmpt_could_open_probability2().

Since

0.3.0

openmpt_could_open_probability2()

double openmpt_could_open_probability2	(	openmpt_stream_callbacks	stream_callbacks,
		void *	stream,
		double	effort,
		openmpt_log_func	logfunc,
		void *	loguser,
		openmpt_error_func	errfunc,
		void *	erruser,
		int *	error,
		const char **	error_message
	)

Roughly scan the input stream to find out whether libopenmpt might be able to open it.

Parameters

stream_callbacks	Input stream callback operations.
stream	Input stream to scan.
effort	Effort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
logfunc	Logging function where warning and errors are written. May be NULL.
loguser	Logging function user context. Used to pass any user-defined data associated with this module to the logging function.
errfunc	Error function to define error behaviour. May be NULL.
erruser	Error function user context. Used to pass any user-defined data associated with this module to the logging function.
error	Pointer to an integer where an error may get stored. May be NULL.
error_message	Pointer to a string pointer where an error message may get stored. May be NULL.

Returns

Probability between 0.0 and 1.0.

Remarks

openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize() provide a simpler and faster interface that fits almost all use cases better. It is recommended to use openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize() instead of openmpt_could_open_probability().

openmpt_could_open_probability2() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).

openmpt_could_open_probability2() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability2() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability2() returned 0.5.

/*
 * libopenmpt_example_c_probe.c
 * ----------------------------
 * Purpose: libopenmpt C API probing example
 * Notes  : (currently none)
 * Authors: OpenMPT Devs
 * The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
 */
 
/*
 * Usage: libopenmpt_example_c_probe SOMEMODULE ...
 * Returns 0 on successful probing for all files.
 * Returns 1 on failed probing for 1 or more files.
 * Returns 2 on error.
 */
 
#define LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY 1
#define LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT  2
 
#define LIBOPENMPT_EXAMPLE_PROBE_RESULT LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY
 
#if defined( __MINGW32__ ) && !defined( __MINGW64__ )
#include <sys/types.h>
#endif
 
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
#include <libopenmpt/libopenmpt.h>
#include <libopenmpt/libopenmpt_stream_callbacks_file.h>
 
#if defined( __DJGPP__ )
#include <crt0.h>
#endif /* __DJGPP__ */
 
static void libopenmpt_example_logfunc( const char * message, void * userdata ) {
  (void)userdata;
 
  if ( message ) {
    fprintf( stderr, "%s\n", message );
  }
}
 
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
static int probe_file( const wchar_t * filename ) {
#else
static int probe_file( const char * filename ) {
#endif
 
  int result = 0;
  int mod_err = OPENMPT_ERROR_OK;
  FILE * file = NULL;
 
#if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY )
  int result_binary = 0;
  int probe_file_header_result = OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE;
  const char * probe_file_header_result_str = NULL;
#endif
#if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT )
  double probability = 0.0;
#endif
 
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  if ( wcslen( filename ) == 0 ) {
    fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE'." );
    goto fail;
  }
#else
  if ( strlen( filename ) == 0 ) {
    fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE'." );
    goto fail;
  }
#endif
 
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  file = _wfopen( filename, L"rb" );
#else
  file = fopen( filename, "rb" );
#endif
  if ( !file ) {
    fprintf( stderr, "Error: %s\n", "fopen() failed." );
    goto fail;
  }
 
#if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY )
  probe_file_header_result = openmpt_probe_file_header_from_stream( OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT, openmpt_stream_get_file_callbacks2(), file, &libopenmpt_example_logfunc, NULL, &openmpt_error_func_default, NULL, &mod_err, NULL );
  probe_file_header_result_str = NULL;
  switch ( probe_file_header_result ) {
    case OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS:
      probe_file_header_result_str = "Success     ";
      result_binary = 1;
      break;
    case OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE:
      probe_file_header_result_str = "Failure     ";
      result_binary = 0;
      break;
    case OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA:
      probe_file_header_result_str = "WantMoreData";
      result_binary = 0;
      break;
    case OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR:
      result_binary = 0;
      (void)result_binary;
      fprintf( stderr, "Error: %s\n", "openmpt_probe_file_header() failed." );
      goto fail;
      break;
    default:
      result_binary = 0;
      (void)result_binary;
      fprintf( stderr, "Error: %s\n", "openmpt_probe_file_header() failed." );
      goto fail;
      break;
  }
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  fprintf( stdout, "%s - %ls\n", probe_file_header_result_str, filename );
#else
  fprintf( stdout, "%s - %s\n", probe_file_header_result_str, filename );
#endif
  if ( result_binary ) {
    result = 0;
  } else {
    result = 1;
  }
#elif ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT )
  probability = openmpt_could_open_probability2( openmpt_stream_get_file_callbacks2(), file, 0.25, &libopenmpt_example_logfunc, NULL, &openmpt_error_func_default, NULL, &mod_err, NULL );
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  fprintf( stdout, "%s: %f - %ls\n", "Result", probability, filename );
#else
  fprintf( stdout, "%s: %f - %s\n", "Result", probability, filename );
#endif
  if ( probability >= 0.5 ) {
    result = 0;
  } else {
    result = 1;
  }
#else
#error "LIBOPENMPT_EXAMPLE_PROBE_RESULT is wrong"
#endif
 
  goto cleanup;
 
fail:
 
  result = 2;
 
cleanup:
 
  if ( file ) {
    fclose( file );
    file = 0;
  }
 
  return result;
}
 
#if defined( __DJGPP__ )
/* clang-format off */
int _crt0_startup_flags = 0
  | _CRT0_FLAG_NONMOVE_SBRK          /* force interrupt compatible allocation */
  | _CRT0_DISABLE_SBRK_ADDRESS_WRAP  /* force NT compatible allocation */
  | _CRT0_FLAG_LOCK_MEMORY           /* lock all code and data at program startup */
  | 0;
/* clang-format on */
#endif /* __DJGPP__ */
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
#if defined( __clang__ ) && !defined( _MSC_VER )
int wmain( int argc, wchar_t * argv[] );
#endif
int wmain( int argc, wchar_t * argv[] ) {
#else
int main( int argc, char * argv[] ) {
#endif
#if defined( __DJGPP__ )
  /* clang-format off */
  _crt0_startup_flags &= ~_CRT0_FLAG_LOCK_MEMORY;  /* disable automatic locking for all further memory allocations */
  /* clang-format on */
#endif /* __DJGPP__ */
 
  int global_result = 0;
 
  if ( argc <= 1 ) {
    fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE ...'." );
    goto fail;
  }
 
  for ( int i = 1; i < argc; ++i ) {
    int result = probe_file( argv[i] );
    if ( result > global_result ) {
      global_result = result;
    }
  }
 
  goto cleanup;
 
fail:
 
  global_result = 2;
 
cleanup:
 
  return global_result;
}

See also

File I/O

openmpt_stream_callbacks

openmpt_probe_file_header

openmpt_probe_file_header_without_filesize

Since

0.3.0

openmpt_could_open_propability()

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.

Parameters

stream_callbacks	Input stream callback operations.
stream	Input stream to scan.
effort	Effort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
logfunc	Logging function where warning and errors are written. May be NULL.
user	Logging function user context. Used to pass any user-defined data associated with this module to the logging function.

Returns

Probability between 0.0 and 1.0.

Remarks

openmpt_could_open_probability() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).

openmpt_could_open_probability() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability() returned 0.5.

See also

File I/O

openmpt_stream_callbacks

Deprecated:

Please use openmpt_could_open_probability2().

openmpt_error_func_default()

int openmpt_error_func_default	(	int	error,
		void *	user
	)

Default error function.

Causes all errors to be logged and stored.

Parameters

error	Error code.
user	Ignored.

Return values

OPENMPT_ERROR_FUNC_RESULT_DEFAULT

Always.

Since

0.3.0

openmpt_error_func_errno()

int openmpt_error_func_errno	(	int	error,
		void *	user
	)

Errno error function.

Causes all errors to be stored in the pointer passed in as user.

Parameters

error	Error code.
user	Pointer to an int as generated by openmpt_error_func_errno_userdata.

Return values

OPENMPT_ERROR_FUNC_RESULT_NONE	user is not NULL.
OPENMPT_ERROR_FUNC_RESULT_DEFAULT	user is NULL.

Since

0.3.0

openmpt_error_func_errno_userdata()

void * openmpt_error_func_errno_userdata

(

int *

error

)

User pointer for openmpt_error_func_errno.

Provides a suitable user pointer argument for openmpt_error_func_errno.

Parameters

error

Pointer to an integer value to be used as output by openmpt_error_func_errno.

Return values

(void*)error.

Since

0.3.0

openmpt_error_func_ignore()

int openmpt_error_func_ignore	(	int	error,
		void *	user
	)

Ignore error function.

Causes all errors to be neither logged nor stored.

Parameters

error	Error code.
user	Ignored.

Return values

OPENMPT_ERROR_FUNC_RESULT_NONE

Always.

Since

0.3.0

openmpt_error_func_log()

int openmpt_error_func_log	(	int	error,
		void *	user
	)

Log error function.

Causes all errors to be logged.

Parameters

error	Error code.
user	Ignored.

Return values

OPENMPT_ERROR_FUNC_RESULT_LOG

Always.

Since

0.3.0

openmpt_error_func_store()

int openmpt_error_func_store	(	int	error,
		void *	user
	)

Store error function.

Causes all errors to be stored.

Parameters

error	Error code.
user	Ignored.

Return values

OPENMPT_ERROR_FUNC_RESULT_STORE

Always.

Since

0.3.0

openmpt_error_is_transient()

int openmpt_error_is_transient

(

int

error

)

Check whether the error is transient.

Checks whether an error code represents a transient error which may not occur again in a later try if for example memory has been freed up after an out-of-memory error.

Parameters

error

Error code.

Return values

0	Error is not transient.
1	Error is transient.

See also

OPENMPT_ERROR_OUT_OF_MEMORY

Since

0.3.0

openmpt_error_string()

const char * openmpt_error_string

(

int

error

)

Convert error code to text.

Converts an error code into a text string describing the error.

Parameters

error

Error code.

Returns

Allocated string describing the error.

Return values

NULL	Not enough memory to allocate the string.

Since

0.3.0

openmpt_free_string()

void openmpt_free_string

(

const char *

str

)

Free a string returned by libopenmpt.

Frees any string that got returned by libopenmpt.

openmpt_get_core_version()

uint32_t openmpt_get_core_version

(

void

)

Get the core version number.

Return the OpenMPT core version number.

Returns

The value represents (majormajor << 24 + major << 16 + minor << 8 + minorminor).

openmpt_get_library_version()

uint32_t openmpt_get_library_version

(

void

)

Get the libopenmpt version number.

Returns the libopenmpt version number.

Returns

The value represents (major << 24 + minor << 16 + patch << 0).

Remarks

libopenmpt < 0.3.0-pre used the following scheme: (major << 24 + minor << 16 + revision).

openmpt_get_string()

const char * openmpt_get_string

(

const char *

key

)

Get library related metadata.

Parameters

key

Key to query. Possible keys are: "library_version": verbose library version string "library_version_is_release": "1" if the version is an officially released version "library_features": verbose library features string "core_version": verbose OpenMPT core version string "source_url": original source code URL "source_date": original source code date "source_revision": original source code revision "source_is_modified": "1" if the original source has been modified "source_has_mixed_revisions": "1" if the original source has been compiled from different various revision "source_is_package": "1" if the original source has been obtained from a source pacakge instead of source code version control "build": information about the current build (e.g. the build date or compiler used) "build_compiler": information about the compiler used to build libopenmpt "credits": all contributors "contact": contact information about libopenmpt "license": the libopenmpt license "url": libopenmpt website URL "support_forum_url": libopenmpt support and discussions forum URL "bugtracker_url": libopenmpt bug and issue tracker URL

Returns

A (possibly multi-line) string containing the queried information. If no information is available, the string is empty.

openmpt_get_supported_extensions()

const char * openmpt_get_supported_extensions

(

void

)

Get a list of supported file extensions.

Returns

The semicolon-separated list of extensions supported by this libopenmpt build. The extensions are returned lower-case without a leading dot.

openmpt_is_extension_supported()

int openmpt_is_extension_supported

(

const char *

extension

)

Query whether a file extension is supported.

Parameters

extension

file extension to query without a leading dot. The case is ignored.

Returns

1 if the extension is supported by libopenmpt, 0 otherwise.

openmpt_log_func_default()

void openmpt_log_func_default	(	const char *	message,
		void *	user
	)

Default logging function.

Default logging function that logs anything to stderr.

openmpt_log_func_silent()

void openmpt_log_func_silent	(	const char *	message,
		void *	user
	)

Silent logging function.

Silent logging function that throws any log message away.

openmpt_module_create()

openmpt_module * openmpt_module_create	(	openmpt_stream_callbacks	stream_callbacks,
		void *	stream,
		openmpt_log_func	logfunc,
		void *	loguser,
		const openmpt_module_initial_ctl *	ctls
	)

Construct an openmpt_module.

Parameters

stream_callbacks	Input stream callback operations.
stream	Input stream to load the module from.
logfunc	Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module. May be NULL.
loguser	User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
ctls	An array of initial ctl and value pairs stored in openmpt_module_initial_ctl, terminated by a pair of NULL and NULL. See openmpt_module_get_ctls and openmpt_module_ctl_set.

Returns

A pointer to the constructed openmpt_module, or NULL on failure.

Remarks

The input data can be discarded after an openmpt_module has been constructed successfully.

See also

openmpt_stream_callbacks

File I/O

Deprecated:

Please use openmpt_module_create2().

openmpt_module_create2()

openmpt_module * openmpt_module_create2	(	openmpt_stream_callbacks	stream_callbacks,
		void *	stream,
		openmpt_log_func	logfunc,
		void *	loguser,
		openmpt_error_func	errfunc,
		void *	erruser,
		int *	error,
		const char **	error_message,
		const openmpt_module_initial_ctl *	ctls
	)

Construct an openmpt_module.

Parameters

stream_callbacks	Input stream callback operations.
stream	Input stream to load the module from.
logfunc	Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module. May be NULL.
loguser	User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
errfunc	Error function to define error behaviour. May be NULL.
erruser	Error function user context. Used to pass any user-defined data associated with this module to the logging function.
error	Pointer to an integer where an error may get stored. May be NULL.
error_message	Pointer to a string pointer where an error message may get stored. May be NULL.
ctls	An array of initial ctl and value pairs stored in openmpt_module_initial_ctl, terminated by a pair of NULL and NULL. See openmpt_module_get_ctls and openmpt_module_ctl_set.

Returns

A pointer to the constructed openmpt_module, or NULL on failure.

Remarks

The input data can be discarded after an openmpt_module has been constructed successfully.

See also

openmpt_stream_callbacks

File I/O

Since

0.3.0

openmpt_module_create_from_memory()

openmpt_module * openmpt_module_create_from_memory	(	const void *	filedata,
		size_t	filesize,
		openmpt_log_func	logfunc,
		void *	loguser,
		const openmpt_module_initial_ctl *	ctls
	)

Construct an openmpt_module.

Parameters

filedata	Data to load the module from.
filesize	Amount of data available.
logfunc	Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
loguser	User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
ctls	An array of initial ctl and value pairs stored in openmpt_module_initial_ctl, terminated by a pair of NULL and NULL. See openmpt_module_get_ctls and openmpt_module_ctl_set.

Returns

A pointer to the constructed openmpt_module, or NULL on failure.

Remarks

The input data can be discarded after an openmpt_module has been constructed successfully.

See also

File I/O

Deprecated:

Please use openmpt_module_create_from_memory2().

openmpt_module_create_from_memory2()

openmpt_module * openmpt_module_create_from_memory2	(	const void *	filedata,
		size_t	filesize,
		openmpt_log_func	logfunc,
		void *	loguser,
		openmpt_error_func	errfunc,
		void *	erruser,
		int *	error,
		const char **	error_message,
		const openmpt_module_initial_ctl *	ctls
	)

Construct an openmpt_module.

Parameters

filedata	Data to load the module from.
filesize	Amount of data available.
logfunc	Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
loguser	User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
errfunc	Error function to define error behaviour. May be NULL.
erruser	Error function user context. Used to pass any user-defined data associated with this module to the logging function.
error	Pointer to an integer where an error may get stored. May be NULL.
error_message	Pointer to a string pointer where an error message may get stored. May be NULL.
ctls	An array of initial ctl and value pairs stored in openmpt_module_initial_ctl, terminated by a pair of NULL and NULL. See openmpt_module_get_ctls and openmpt_module_ctl_set.

Returns

A pointer to the constructed openmpt_module, or NULL on failure.

Remarks

The input data can be discarded after an openmpt_module has been constructed successfully.

See also

File I/O

Since

0.3.0

openmpt_module_ctl_get()

const char * openmpt_module_ctl_get	(	openmpt_module *	mod,
		const char *	ctl
	)

Get current ctl value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be retrieved.

Returns

The associated ctl value, or NULL on failure.

See also

openmpt_module_get_ctls

Deprecated:

Please use openmpt_module_ctl_get_boolean(), openmpt_module_ctl_get_integer(), openmpt_module_ctl_get_floatingpoint(), or openmpt_module_ctl_get_text().

openmpt_module_ctl_get_boolean()

int openmpt_module_ctl_get_boolean	(	openmpt_module *	mod,
		const char *	ctl
	)

Get current ctl boolean value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be retrieved.

Returns

The associated ctl value, or NULL on failure.

See also

openmpt_module_get_ctls

Since

0.5.0

openmpt_module_ctl_get_floatingpoint()

double openmpt_module_ctl_get_floatingpoint	(	openmpt_module *	mod,
		const char *	ctl
	)

Get current ctl floatingpoint value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be retrieved.

Returns

The associated ctl value, or NULL on failure.

See also

openmpt_module_get_ctls

Since

0.5.0

openmpt_module_ctl_get_integer()

int64_t openmpt_module_ctl_get_integer	(	openmpt_module *	mod,
		const char *	ctl
	)

Get current ctl integer value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be retrieved.

Returns

The associated ctl value, or NULL on failure.

See also

openmpt_module_get_ctls

Since

0.5.0

openmpt_module_ctl_get_text()

const char * openmpt_module_ctl_get_text	(	openmpt_module *	mod,
		const char *	ctl
	)

Get current ctl string value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be retrieved.

Returns

The associated ctl value, or NULL on failure.

See also

openmpt_module_get_ctls

Since

0.5.0

openmpt_module_ctl_set()

int openmpt_module_ctl_set	(	openmpt_module *	mod,
		const char *	ctl,
		const char *	value
	)

Set ctl value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be set.
value	The value that should be set.

Returns

1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also

openmpt_module_get_ctls

Deprecated:

Please use openmpt_module_ctl_set_boolean(), openmpt_module_ctl_set_integer(), openmpt_module_ctl_set_floatingpoint(), or openmpt_module_ctl_set_text().

openmpt_module_ctl_set_boolean()

int openmpt_module_ctl_set_boolean	(	openmpt_module *	mod,
		const char *	ctl,
		int	value
	)

Set ctl boolean value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be set.
value	The value that should be set.

Returns

1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also

openmpt_module_get_ctls

Since

0.5.0

openmpt_module_ctl_set_floatingpoint()

int openmpt_module_ctl_set_floatingpoint	(	openmpt_module *	mod,
		const char *	ctl,
		double	value
	)

Set ctl floatingpoint value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be set.
value	The value that should be set.

Returns

1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also

openmpt_module_get_ctls

Since

0.5.0

openmpt_module_ctl_set_integer()

int openmpt_module_ctl_set_integer	(	openmpt_module *	mod,
		const char *	ctl,
		int64_t	value
	)

Set ctl integer value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be set.
value	The value that should be set.

Returns

1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also

openmpt_module_get_ctls

Since

0.5.0

openmpt_module_ctl_set_text()

int openmpt_module_ctl_set_text	(	openmpt_module *	mod,
		const char *	ctl,
		const char *	value
	)

Set ctl string value.

Parameters

mod	The module handle to work on.
ctl	The ctl key whose value should be set.
value	The value that should be set.

Returns

1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also

openmpt_module_get_ctls

Since

0.5.0

openmpt_module_destroy()

void openmpt_module_destroy

(

openmpt_module *

mod

)

Unload a previously created openmpt_module from memory.

Parameters

mod	The module to unload.

openmpt_module_error_clear()

void openmpt_module_error_clear

(

openmpt_module *

mod

)

Clear last error.

Set the error currently stored in an openmpt_module to OPPENMPT_ERROR_OK.

Parameters

mod	The module handle to work on.

See also

openmpt_module_error_get_last

openmpt_module_error_set_last

Since

0.3.0

openmpt_module_error_get_last()

int openmpt_module_error_get_last

(

openmpt_module *

mod

)

Get last error.

Return the error currently stored in an openmpt_module. The stored error is not cleared.

Parameters

mod	The module handle to work on.

Returns

The error currently stored.

See also

openmpt_module_error_get_last_message

openmpt_module_error_set_last

openmpt_module_error_clear

Since

0.3.0

openmpt_module_error_get_last_message()

const char * openmpt_module_error_get_last_message

(

openmpt_module *

mod

)

Get last error message.

Return the error message currently stored in an openmpt_module. The stored error is not cleared.

Parameters

mod	The module handle to work on.

Returns

The error message currently stored.

See also

openmpt_module_error_set_last

openmpt_module_error_clear

Since

0.3.0

openmpt_module_error_set_last()

void openmpt_module_error_set_last	(	openmpt_module *	mod,
		int	error
	)

Set last error.

Set the error currently stored in an openmpt_module.

Parameters

mod	The module handle to work on.
error	Error to be stored.

See also

openmpt_module_error_get_last

openmpt_module_error_clear

Since

0.3.0

openmpt_module_format_pattern_row_channel()

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.

Parameters

mod	The module handle to work on.
pattern	The pattern whose data should be retrieved.
row	The row from which the data should be retrieved.
channel	The channel from which the data should be retrieved.
width	The maximum number of characters the string should contain. 0 means no limit.
pad	If true, the string will be resized to the exact length provided in the width parameter.

Returns

The formatted pattern data at the given pattern position.

See also

openmpt_module_highlight_pattern_row_channel

openmpt_module_format_pattern_row_channel_command()

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.

Parameters

mod	The module handle to work on.
pattern	The pattern whose data should be retrieved.
row	The row from which the data should be retrieved.
channel	The channel from which the data should be retrieved.
command	The cell index at which the data should be retrieved.

Returns

The formatted pattern data at the given pattern position. See Pattern cell indices

See also

openmpt_module_highlight_pattern_row_channel_command

openmpt_module_get_channel_name()

const char * openmpt_module_get_channel_name	(	openmpt_module *	mod,
		int32_t	index
	)

Get a channel name.

Parameters

mod	The module handle to work on.
index	The channel whose name should be retrieved

Returns

The channel name.

See also

openmpt_module_get_num_channels

openmpt_module_get_ctls()

const char * openmpt_module_get_ctls

(

openmpt_module *

mod

)

Retrieve supported ctl keys.

Parameters

mod	The module handle to work on.

Returns

A semicolon-separated list containing all supported ctl keys.

Remarks

Currently supported ctl values are:

• load.skip_samples (boolean): Set to "1" to avoid loading samples into memory
• load.skip_patterns (boolean): Set to "1" to avoid loading patterns into memory
• load.skip_plugins (boolean): Set to "1" to avoid loading plugins
• load.skip_subsongs_init (boolean): Set to "1" to avoid pre-initializing sub-songs. Skipping results in faster module loading but slower seeking.
• seek.sync_samples (boolean): Set to "0" to not sync sample playback when using openmpt_module_set_position_seconds or openmpt_module_set_position_order_row.
• subsong (integer): The current subsong. Setting it has identical semantics as openmpt_module_select_subsong(), getting it returns the currently selected subsong.
• play.at_end (text): Chooses the behaviour when the end of song is reached. The song end is considered to be reached after the number of reptitions set by openmpt_module_set_repeat_count was played, so if the song is set to repeat infinitely, its end is never considered to be reached.
  • "fadeout": Fades the module out for a short while. Subsequent reads after the fadeout will return 0 rendered frames.
  • "continue": Returns 0 rendered frames when the song end is reached. Subsequent reads will continue playing from the loop start (if the song is not programmed to loop, playback resumed from the song start).
  • "stop": Returns 0 rendered frames when the song end is reached. Subsequent reads will return 0 rendered frames.
• play.tempo_factor (floatingpoint): Set a floating point tempo factor. "1.0" is the default tempo.
• play.pitch_factor (floatingpoint): Set a floating point pitch factor. "1.0" is the default pitch.
• render.resampler.emulate_amiga (boolean): Set to "1" to enable the Amiga resampler for Amiga modules. This emulates the sound characteristics of the Paula chip and overrides the selected interpolation filter. Non-Amiga module formats are not affected by this setting.
• render.resampler.emulate_amiga_type (string): Configures the filter type to use for the Amiga resampler. Supported values are:
  • "auto": Filter type is chosen by the library and might change. This is the default.
  • "a500": Amiga A500 filter.
  • "a1200": Amiga A1200 filter.
  • "unfiltered": BLEP synthesis without model-specific filters. The LED filter is ignored by this setting. This filter mode is considered to be experimental and might change in the future.
• render.opl.volume_factor (floatingpoint): Set volume factor applied to synthesized OPL sounds, relative to the default OPL volume.
• dither (integer): Set the dither algorithm that is used for the 16 bit versions of openmpt_module_read. Supported values are:
  • 0: No dithering.
  • 1: Default mode. Chosen by OpenMPT code, might change.
  • 2: Rectangular, 0.5 bit depth, no noise shaping (original ModPlug Tracker).
  • 3: Rectangular, 1 bit depth, simple 1st order noise shaping

openmpt_module_get_current_channel_vu_left()

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.

Parameters

mod	The module handle to work on.
channel	The channel whose volume should be retrieved.

Returns

The approximate channel volume.

Remarks

The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

openmpt_module_get_current_channel_vu_mono()

float openmpt_module_get_current_channel_vu_mono	(	openmpt_module *	mod,
		int32_t	channel
	)

Get an approximate indication of the channel volume.

Parameters

mod	The module handle to work on.
channel	The channel whose volume should be retrieved.

Returns

The approximate channel volume.

Remarks

The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

openmpt_module_get_current_channel_vu_rear_left()

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.

Parameters

mod	The module handle to work on.
channel	The channel whose volume should be retrieved.

Returns

The approximate channel volume.

Remarks

The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

openmpt_module_get_current_channel_vu_rear_right()

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.

Parameters

mod	The module handle to work on.
channel	The channel whose volume should be retrieved.

Returns

The approximate channel volume.

Remarks

The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

openmpt_module_get_current_channel_vu_right()

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.

Parameters

mod	The module handle to work on.
channel	The channel whose volume should be retrieved.

Returns

The approximate channel volume.

Remarks

The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

openmpt_module_get_current_estimated_bpm()

double openmpt_module_get_current_estimated_bpm

(

openmpt_module *

mod

)

Get the current estimated beats per minute (BPM).

Parameters

mod	The module handle to work on.

Remarks

Many module formats lack time signature metadata. It is common that this estimate is off by a factor of two, but other multipliers are also possible.

Due to the nature of how module tempo works, the estimate may change slightly after switching libopenmpt's output to a different sample rate.

Returns

The current estimated BPM.

openmpt_module_get_current_order()

int32_t openmpt_module_get_current_order

(

openmpt_module *

mod

)

Get the current order.

Parameters

mod	The module handle to work on.

Returns

The current order at which the module is being played back.

openmpt_module_get_current_pattern()

int32_t openmpt_module_get_current_pattern

(

openmpt_module *

mod

)

Get the current pattern.

Parameters

mod	The module handle to work on.

Returns

The current pattern that is being played.

openmpt_module_get_current_playing_channels()

int32_t openmpt_module_get_current_playing_channels

(

openmpt_module *

mod

)

Get the current amount of playing channels.

Parameters

mod	The module handle to work on.

Returns

The amount of sample channels that are currently being rendered.

openmpt_module_get_current_row()

int32_t openmpt_module_get_current_row

(

openmpt_module *

mod

)

Get the current row.

Parameters

mod	The module handle to work on.

Returns

The current row at which the current pattern is being played.

openmpt_module_get_current_speed()

int32_t openmpt_module_get_current_speed

(

openmpt_module *

mod

)

Get the current speed.

Parameters

mod	The module handle to work on.

Returns

The current speed in ticks per row.

openmpt_module_get_current_tempo()

int32_t openmpt_module_get_current_tempo

(

openmpt_module *

mod

)

Get the current tempo.

Parameters

mod	The module handle to work on.

Returns

The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used.

Deprecated:

Please use openmpt_module_get_current_tempo2().

openmpt_module_get_current_tempo2()

double openmpt_module_get_current_tempo2

(

openmpt_module *

mod

)

Get the current tempo.

Parameters

mod	The module handle to work on.

Returns

The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used.

Since

0.7.0

openmpt_module_get_duration_seconds()

double openmpt_module_get_duration_seconds

(

openmpt_module *

mod

)

approximate song duration

Parameters

mod	The module handle to work on.

Returns

Approximate duration of current sub-song in seconds.

Remarks

The function may return infinity if the pattern data is too complex to evaluate.

openmpt_module_get_instrument_name()

const char * openmpt_module_get_instrument_name	(	openmpt_module *	mod,
		int32_t	index
	)

Get an instrument name.

Parameters

mod	The module handle to work on.
index	The instrument whose name should be retrieved

Returns

The instrument name.

See also

openmpt_module_get_num_instruments

openmpt_module_get_metadata()

const char * openmpt_module_get_metadata	(	openmpt_module *	mod,
		const char *	key
	)

Get a metadata item value.

Parameters

mod

The module handle to work on.

key

Metadata item key to query. Use openmpt_module_get_metadata_keys to check for available keys. Possible keys are: type: Module format extension (e.g. it) or another similar identifier for modules formats that typically do not use a file extension type_long: Format name associated with the module format (e.g. Impulse Tracker) originaltype: Module format extension (e.g. it) of the original module in case the actual type is a converted format (e.g. mo3 or gdm) originaltype_long: Format name associated with the module format (e.g. Impulse Tracker) of the original module in case the actual type is a converted format (e.g. mo3 or gdm) container: Container format the module file is embedded in, if any (e.g. umx) container_long: Full container name if the module is embedded in a container (e.g. Unreal Music) tracker: Tracker that was (most likely) used to save the module file, if known artist: Author of the module title: Module title date: Date the module was last saved, in ISO-8601 format. message: Song message. If the song message is empty or the module format does not support song messages, a list of instrument and sample names is returned instead. message_raw: Song message. If the song message is empty or the module format does not support song messages, an empty string is returned. warnings: A list of warnings that were generated while loading the module.

Returns

The associated value for key.

See also

openmpt_module_get_metadata_keys

openmpt_module_get_metadata_keys()

const char * openmpt_module_get_metadata_keys

(

openmpt_module *

mod

)

Get the list of supported metadata item keys.

Parameters

mod	The module handle to work on.

Returns

Metadata item keys supported by openmpt_module_get_metadata, as a semicolon-separated list.

See also

openmpt_module_get_metadata

openmpt_module_get_num_channels()

int32_t openmpt_module_get_num_channels

(

openmpt_module *

mod

)

Get the number of pattern channels.

Parameters

mod	The module handle to work on.

Returns

The number of pattern channels in the module. Not all channels do necessarily contain data.

Remarks

The number of pattern channels is completely independent of the number of output channels. libopenmpt can render modules in mono, stereo or quad surround, but the choice of which of the three modes to use must not be made based on the return value of this function, which may be any positive integer amount. Only use this function for informational purposes.

openmpt_module_get_num_instruments()

int32_t openmpt_module_get_num_instruments

(

openmpt_module *

mod

)

Get the number of instruments.

Parameters

mod	The module handle to work on.

Returns

The number of instrument slots in the module. Instruments are a layer on top of samples, and are not supported by all module formats.

openmpt_module_get_num_orders()

int32_t openmpt_module_get_num_orders

(

openmpt_module *

mod

)

Get the number of orders.

Parameters

mod	The module handle to work on.

Returns

The number of orders in the current sequence of the module.

openmpt_module_get_num_patterns()

int32_t openmpt_module_get_num_patterns

(

openmpt_module *

mod

)

Get the number of patterns.

Parameters

mod	The module handle to work on.

Returns

The number of distinct patterns in the module.

openmpt_module_get_num_samples()

int32_t openmpt_module_get_num_samples

(

openmpt_module *

mod

)

Get the number of samples.

Parameters

mod	The module handle to work on.

Returns

The number of sample slots in the module.

openmpt_module_get_num_subsongs()

int32_t openmpt_module_get_num_subsongs

(

openmpt_module *

mod

)

Get the number of sub-songs.

Parameters

mod	The module handle to work on.

Returns

The number of sub-songs in the module. This includes any "hidden" songs (songs that share the same sequence, but start at different order indices) and "normal" sub-songs or "sequences" (if the format supports them).

See also

openmpt_module_get_subsong_name, openmpt_module_select_subsong, openmpt_module_get_selected_subsong

openmpt_module_get_order_name()

const char * openmpt_module_get_order_name	(	openmpt_module *	mod,
		int32_t	index
	)

Get an order name.

Parameters

mod	The module handle to work on.
index	The order whose name should be retrieved

Returns

The order name.

See also

openmpt_module_get_num_orders

openmpt_module_get_order_pattern()

int32_t openmpt_module_get_order_pattern	(	openmpt_module *	mod,
		int32_t	order
	)

Get pattern at order position.

Parameters

mod	The module handle to work on.
order	The order item whose pattern index should be retrieved.

Returns

The pattern index found at the given order position of the current sequence.

openmpt_module_get_pattern_name()

const char * openmpt_module_get_pattern_name	(	openmpt_module *	mod,
		int32_t	index
	)

Get a pattern name.

Parameters

mod	The module handle to work on.
index	The pattern whose name should be retrieved

Returns

The pattern name.

See also

openmpt_module_get_num_patterns

openmpt_module_get_pattern_num_rows()

int32_t openmpt_module_get_pattern_num_rows	(	openmpt_module *	mod,
		int32_t	pattern
	)

Get the number of rows in a pattern.

Parameters

mod	The module handle to work on.
pattern	The pattern whose row count should be retrieved.

Returns

The number of rows in the given pattern. If the pattern does not exist, 0 is returned.

openmpt_module_get_pattern_row_channel_command()

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.

Parameters

mod	The module handle to work on.
pattern	The pattern whose data should be retrieved.
row	The row from which the data should be retrieved.
channel	The channel from which the data should be retrieved.
command	The cell index at which the data should be retrieved. See Pattern cell indices

Returns

The internal, raw pattern data at the given pattern position.

openmpt_module_get_position_seconds()

double openmpt_module_get_position_seconds

(

openmpt_module *

mod

)

Get current song position.

Parameters

mod	The module handle to work on.

Returns

Current song position in seconds.

See also

openmpt_module_set_position_seconds

openmpt_module_get_render_param()

int openmpt_module_get_render_param	(	openmpt_module *	mod,
		int	param,
		int32_t *	value
	)

Get render parameter.

Parameters

mod	The module handle to work on.
param	Parameter to query. See Render param indices
value	Pointer to the variable that receives the current value of the parameter.

Returns

1 on success, 0 on failure (invalid param or value is NULL).

See also

OPENMPT_MODULE_RENDER_MASTERGAIN_MILLIBEL

OPENMPT_MODULE_RENDER_STEREOSEPARATION_PERCENT

OPENMPT_MODULE_RENDER_INTERPOLATIONFILTER_LENGTH

OPENMPT_MODULE_RENDER_VOLUMERAMPING_STRENGTH

openmpt_module_set_render_param

openmpt_module_get_repeat_count()

int32_t openmpt_module_get_repeat_count

(

openmpt_module *

mod

)

Get Repeat Count.

Parameters

mod	The module handle to work on.

Returns

Repeat Count

• -1: repeat forever
• 0: play once, repeat zero times (the default)
• n>0: play once and repeat n times after that

See also

openmpt_module_set_repeat_count

openmpt_module_get_sample_name()

const char * openmpt_module_get_sample_name	(	openmpt_module *	mod,
		int32_t	index
	)

Get a sample name.

Parameters

mod	The module handle to work on.
index	The sample whose name should be retrieved

Returns

The sample name.

See also

openmpt_module_get_num_samples

openmpt_module_get_selected_subsong()

int32_t openmpt_module_get_selected_subsong

(

openmpt_module *

mod

)

Get currently selected sub-song from a multi-song module.

Parameters

mod	The module handle to work on.

Returns

Currently selected sub-song. -1 for all subsongs consecutively, 0 or greater for the current sub-song index.

See also

openmpt_module_get_num_subsongs, openmpt_module_select_subsong, openmpt_module_get_subsong_name

Since

0.3.0

openmpt_module_get_subsong_name()

const char * openmpt_module_get_subsong_name	(	openmpt_module *	mod,
		int32_t	index
	)

Get a sub-song name.

Parameters

mod	The module handle to work on.
index	The sub-song whose name should be retrieved

Returns

The sub-song name.

See also

openmpt_module_get_num_subsongs, openmpt_module_select_subsong, openmpt_module_get_selected_subsong

openmpt_module_highlight_pattern_row_channel()

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.

Parameters

mod	The module handle to work on.
pattern	The pattern whose data should be retrieved.
row	The row from which the data should be retrieved.
channel	The channel from which the data should be retrieved.
width	The maximum number of characters the string should contain. 0 means no limit.
pad	If true, the string will be resized to the exact length provided in the width parameter.

Returns

The highlighting string for the formatted pattern data as retrieved by openmpt_module_format_pattern_row_channel at the given pattern position.

See also

openmpt_module_format_pattern_row_channel

openmpt_module_highlight_pattern_row_channel_command()

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.

Parameters

mod	The module handle to work on.
pattern	The pattern whose data should be retrieved.
row	The row from which the data should be retrieved.
channel	The channel from which the data should be retrieved.
command	The cell index at which the data should be retrieved. See Pattern cell indices

Returns

The highlighting string for the formatted pattern data as retrieved by openmpt_module_get_pattern_row_channel_command at the given pattern position.

Remarks

The returned string will map each character position of the string returned by openmpt_module_get_pattern_row_channel_command to a highlighting instruction. Possible highlighting characters are:

• " " : empty/space
• "." : empty/dot
• "n" : generic note
• "m" : special note
• "i" : generic instrument
• "u" : generic volume column effect
• "v" : generic volume column parameter
• "e" : generic effect column effect
• "f" : generic effect column parameter

See also

openmpt_module_get_pattern_row_channel_command

openmpt_module_read_float_mono()

size_t openmpt_module_read_float_mono	(	openmpt_module *	mod,
		int32_t	samplerate,
		size_t	count,
		float *	mono
	)

Render audio data.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
mono	Pointer to a buffer of at least count elements that receives the mono/center output.

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also

Output Format

openmpt_module_read_float_quad()

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.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
left	Pointer to a buffer of at least count elements that receives the left output.
right	Pointer to a buffer of at least count elements that receives the right output.
rear_left	Pointer to a buffer of at least count elements that receives the rear left output.
rear_right	Pointer to a buffer of at least count elements that receives the rear right output.

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also

Output Format

openmpt_module_read_float_stereo()

size_t openmpt_module_read_float_stereo	(	openmpt_module *	mod,
		int32_t	samplerate,
		size_t	count,
		float *	left,
		float *	right
	)

Render audio data.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
left	Pointer to a buffer of at least count elements that receives the left output.
right	Pointer to a buffer of at least count elements that receives the right output.

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also

Output Format

openmpt_module_read_interleaved_float_quad()

size_t openmpt_module_read_interleaved_float_quad	(	openmpt_module *	mod,
		int32_t	samplerate,
		size_t	count,
		float *	interleaved_quad
	)

Render audio data.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
interleaved_quad	Pointer to a buffer of at least count*4 elements that receives the interleaved quad surround output in the order (L,R,RL,RR).

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also

Output Format

openmpt_module_read_interleaved_float_stereo()

size_t openmpt_module_read_interleaved_float_stereo	(	openmpt_module *	mod,
		int32_t	samplerate,
		size_t	count,
		float *	interleaved_stereo
	)

Render audio data.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
interleaved_stereo	Pointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R).

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also

Output Format

openmpt_module_read_interleaved_quad()

size_t openmpt_module_read_interleaved_quad	(	openmpt_module *	mod,
		int32_t	samplerate,
		size_t	count,
		int16_t *	interleaved_quad
	)

Render audio data.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
interleaved_quad	Pointer to a buffer of at least count*4 elements that receives the interleaved quad surround output in the order (L,R,RL,RR).

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also

Output Format

openmpt_module_read_interleaved_stereo()

size_t openmpt_module_read_interleaved_stereo	(	openmpt_module *	mod,
		int32_t	samplerate,
		size_t	count,
		int16_t *	interleaved_stereo
	)

Render audio data.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
interleaved_stereo	Pointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R).

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also

Output Format

openmpt_module_read_mono()

size_t openmpt_module_read_mono	(	openmpt_module *	mod,
		int32_t	samplerate,
		size_t	count,
		int16_t *	mono
	)

Render audio data.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
mono	Pointer to a buffer of at least count elements that receives the mono/center output.

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also

Output Format

openmpt_module_read_quad()

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.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
left	Pointer to a buffer of at least count elements that receives the left output.
right	Pointer to a buffer of at least count elements that receives the right output.
rear_left	Pointer to a buffer of at least count elements that receives the rear left output.
rear_right	Pointer to a buffer of at least count elements that receives the rear right output.

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also

Output Format

openmpt_module_read_stereo()

size_t openmpt_module_read_stereo	(	openmpt_module *	mod,
		int32_t	samplerate,
		size_t	count,
		int16_t *	left,
		int16_t *	right
	)

Render audio data.

Parameters

mod	The module handle to work on.
samplerate	Sample rate to render output. Should be in [8000,192000], but this is not enforced.
count	Number of audio frames to render per channel.
left	Pointer to a buffer of at least count elements that receives the left output.
right	Pointer to a buffer of at least count elements that receives the right output.

Returns

The number of frames actually rendered.

Return values

0	The end of song has been reached.

Remarks

The output buffers are only written to up to the returned number of elements.

You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.

It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also

Output Format

openmpt_module_select_subsong()

int openmpt_module_select_subsong	(	openmpt_module *	mod,
		int32_t	subsong
	)

Select a sub-song from a multi-song module.

Parameters

mod	The module handle to work on.
subsong	Index of the sub-song. -1 plays all sub-songs consecutively.

Returns

1 on success, 0 on failure.

See also

openmpt_module_get_num_subsongs, openmpt_module_get_selected_subsong, openmpt_module_get_subsong_name

Remarks

Whether subsong -1 (all subsongs consecutively), subsong 0 or some other subsong is selected by default, is an implementation detail and subject to change. If you do not want to care about subsongs, it is recommended to just not call openmpt_module_select_subsong() at all.

openmpt_module_set_error_func()

void openmpt_module_set_error_func	(	openmpt_module *	mod,
		openmpt_error_func	errfunc,
		void *	erruser
	)

Set error function.

Set the error function of an already constructed openmpt_module.

Parameters

mod	The module handle to work on.
errfunc	Error function to define error behaviour. May be NULL.
erruser	Error function user context.

Since

0.3.0

openmpt_module_set_log_func()

void openmpt_module_set_log_func	(	openmpt_module *	mod,
		openmpt_log_func	logfunc,
		void *	loguser
	)

Set logging function.

Set the logging function of an already constructed openmpt_module.

Parameters

mod	The module handle to work on.
logfunc	Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
loguser	User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)

Since

0.3.0

openmpt_module_set_position_order_row()

double openmpt_module_set_position_order_row	(	openmpt_module *	mod,
		int32_t	order,
		int32_t	row
	)

Set approximate current song position.

If order or row are out of range, to position is not modified and the current position is returned.

Parameters

mod	The module handle to work on.
order	Pattern order number to seek to.
row	Pattern row number to seek to.

Returns

Approximate new song position in seconds.

See also

openmpt_module_set_position_seconds

openmpt_module_get_position_seconds

openmpt_module_set_position_seconds()

double openmpt_module_set_position_seconds	(	openmpt_module *	mod,
		double	seconds
	)

Set approximate current song position.

Parameters

mod	The module handle to work on.
seconds	Seconds to seek to. If seconds is out of range, the position gets set to song start or end respectively.

Returns

Approximate new song position in seconds.

See also

openmpt_module_get_position_seconds

openmpt_module_set_render_param()

int openmpt_module_set_render_param	(	openmpt_module *	mod,
		int	param,
		int32_t	value
	)

Set render parameter.

Parameters

mod	The module handle to work on.
param	Parameter to set. See Render param indices
value	The value to set param to.

Returns

1 on success, 0 on failure (invalid param).

See also

OPENMPT_MODULE_RENDER_MASTERGAIN_MILLIBEL

OPENMPT_MODULE_RENDER_STEREOSEPARATION_PERCENT

OPENMPT_MODULE_RENDER_INTERPOLATIONFILTER_LENGTH

OPENMPT_MODULE_RENDER_VOLUMERAMPING_STRENGTH

openmpt_module_get_render_param

openmpt_module_set_repeat_count()

int openmpt_module_set_repeat_count	(	openmpt_module *	mod,
		int32_t	repeat_count
	)

Set Repeat Count.

Parameters

mod	The module handle to work on.
repeat_count	Repeat Count -1: repeat forever 0: play once, repeat zero times (the default) n>0: play once and repeat n times after that

Returns

1 on success, 0 on failure.

See also

openmpt_module_get_repeat_count

openmpt_probe_file_header()

int openmpt_probe_file_header	(	uint64_t	flags,
		const void *	data,
		size_t	size,
		uint64_t	filesize,
		openmpt_log_func	logfunc,
		void *	loguser,
		openmpt_error_func	errfunc,
		void *	erruser,
		int *	error,
		const char **	error_message
	)

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters

flags	Bit mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
data	Beginning of the file data.
size	Size of the beginning of the file data.
filesize	Full size of the file data on disk.
logfunc	Logging function where warning and errors are written. May be NULL.
loguser	Logging function user context. Used to pass any user-defined data associated with this module to the logging function.
errfunc	Error function to define error behaviour. May be NULL.
erruser	Error function user context. Used to pass any user-defined data associated with this module to the logging function.
error	Pointer to an integer where an error may get stored. May be NULL.
error_message	Pointer to a string pointer where an error message may get stored. May be NULL.

Remarks

It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size and filesize to the file's size.

openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.

Return values

OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS	The file will most likely be supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE	The file is not supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA	An answer could not be determined with the amount of data provided.
OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR	An internal error occurred.

See also

openmpt_probe_file_header_get_recommended_size()

openmpt_probe_file_header_without_filesize()

openmpt_probe_file_header_from_stream()

openmpt_could_open_probability2()

Since

0.3.0

openmpt_probe_file_header_from_stream()

int openmpt_probe_file_header_from_stream	(	uint64_t	flags,
		openmpt_stream_callbacks	stream_callbacks,
		void *	stream,
		openmpt_log_func	logfunc,
		void *	loguser,
		openmpt_error_func	errfunc,
		void *	erruser,
		int *	error,
		const char **	error_message
	)

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters

flags	Bit mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
stream_callbacks	Input stream callback operations.
stream	Input stream to scan.
logfunc	Logging function where warning and errors are written. May be NULL.
loguser	Logging function user context. Used to pass any user-defined data associated with this module to the logging function.
errfunc	Error function to define error behaviour. May be NULL.
erruser	Error function user context. Used to pass any user-defined data associated with this module to the logging function.
error	Pointer to an integer where an error may get stored. May be NULL.
error_message	Pointer to a string pointer where an error message may get stored. May be NULL.

Remarks

The stream is left in an unspecified state when this function returns.

It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size and filesize to the file's size.

openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.

Return values

OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS	The file will most likely be supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE	The file is not supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA	An answer could not be determined with the amount of data provided.
OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR	An internal error occurred.

See also

openmpt_probe_file_header_get_recommended_size()

openmpt_probe_file_header()

openmpt_probe_file_header_without_filesize()

openmpt_could_open_probability2()

Since

0.3.0

openmpt_probe_file_header_get_recommended_size()

size_t openmpt_probe_file_header_get_recommended_size

(

void

)

Get recommended header size for successfull format probing.

See also

openmpt_probe_file_header()

openmpt_probe_file_header_without_filesize()

Since

0.3.0

openmpt_probe_file_header_without_filesize()

int openmpt_probe_file_header_without_filesize	(	uint64_t	flags,
		const void *	data,
		size_t	size,
		openmpt_log_func	logfunc,
		void *	loguser,
		openmpt_error_func	errfunc,
		void *	erruser,
		int *	error,
		const char **	error_message
	)

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters

flags	Bit mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
data	Beginning of the file data.
size	Size of the beginning of the file data.
logfunc	Logging function where warning and errors are written. May be NULL.
loguser	Logging function user context. Used to pass any user-defined data associated with this module to the logging function.
errfunc	Error function to define error behaviour. May be NULL.
erruser	Error function user context. Used to pass any user-defined data associated with this module to the logging function.
error	Pointer to an integer where an error may get stored. May be NULL.
error_message	Pointer to a string pointer where an error message may get stored. May be NULL.

Remarks

It is recommended to use openmpt_probe_file_header() and provide the acutal file's size as a parameter if at all possible. libopenmpt can provide more accurate answers if the filesize is known.

It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size to the file's size.

openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.

Return values

OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS	The file will most likely be supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE	The file is not supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA	An answer could not be determined with the amount of data provided.
OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR	An internal error occurred.

See also

openmpt_probe_file_header_get_recommended_size()

openmpt_probe_file_header()

openmpt_probe_file_header_from_stream()

openmpt_could_open_probability2()

Since

0.3.0

openmpt_stream_buffer_init()

static void openmpt_stream_buffer_init ( openmpt_stream_buffer *  buffer, const void *  file_data, int64_t  file_size  )

static

openmpt_stream_buffer_init2()

static void openmpt_stream_buffer_init2 ( openmpt_stream_buffer2 *  buffer, const void *  file_data, int64_t  file_size  )

static

openmpt_stream_buffer_read_func()

static size_t openmpt_stream_buffer_read_func ( void *  stream, void *  dst, size_t  bytes  )

static

openmpt_stream_buffer_read_func2()

static size_t openmpt_stream_buffer_read_func2 ( void *  stream, void *  dst, size_t  bytes  )

static

openmpt_stream_buffer_seek_func()

static int openmpt_stream_buffer_seek_func ( void *  stream, int64_t  offset, int  whence  )

static

openmpt_stream_buffer_seek_func2()

static int openmpt_stream_buffer_seek_func2 ( void *  stream, int64_t  offset, int  whence  )

static

openmpt_stream_buffer_tell_func()

static int64_t openmpt_stream_buffer_tell_func ( void *  stream )

static

openmpt_stream_buffer_tell_func2()

static int64_t openmpt_stream_buffer_tell_func2 ( void *  stream )

static

openmpt_stream_fd_read_func()

static size_t openmpt_stream_fd_read_func ( void *  stream, void *  dst, size_t  bytes  )

static

openmpt_stream_file_mingw_read_func()

static size_t openmpt_stream_file_mingw_read_func ( void *  stream, void *  dst, size_t  bytes  )

static

openmpt_stream_file_mingw_seek_func()

static int openmpt_stream_file_mingw_seek_func ( void *  stream, int64_t  offset, int  whence  )

static

openmpt_stream_file_mingw_tell_func()

static int64_t openmpt_stream_file_mingw_tell_func ( void *  stream )

static

openmpt_stream_file_msvcrt_read_func()

static size_t openmpt_stream_file_msvcrt_read_func ( void *  stream, void *  dst, size_t  bytes  )

static

openmpt_stream_file_msvcrt_seek_func()

static int openmpt_stream_file_msvcrt_seek_func ( void *  stream, int64_t  offset, int  whence  )

static

openmpt_stream_file_msvcrt_tell_func()

static int64_t openmpt_stream_file_msvcrt_tell_func ( void *  stream )

static

openmpt_stream_file_posix_lfs64_read_func()

static size_t openmpt_stream_file_posix_lfs64_read_func ( void *  stream, void *  dst, size_t  bytes  )

static

openmpt_stream_file_posix_lfs64_seek_func()

static int openmpt_stream_file_posix_lfs64_seek_func ( void *  stream, int64_t  offset, int  whence  )

static

openmpt_stream_file_posix_lfs64_tell_func()

static int64_t openmpt_stream_file_posix_lfs64_tell_func ( void *  stream )

static

openmpt_stream_file_posix_read_func()

static size_t openmpt_stream_file_posix_read_func ( void *  stream, void *  dst, size_t  bytes  )

static

openmpt_stream_file_posix_seek_func()

static int openmpt_stream_file_posix_seek_func ( void *  stream, int64_t  offset, int  whence  )

static

openmpt_stream_file_posix_tell_func()

static int64_t openmpt_stream_file_posix_tell_func ( void *  stream )

static

openmpt_stream_file_read_func()

static size_t openmpt_stream_file_read_func ( void *  stream, void *  dst, size_t  bytes  )

static

openmpt_stream_file_seek_func()

static int openmpt_stream_file_seek_func ( void *  stream, int64_t  offset, int  whence  )

static

openmpt_stream_file_tell_func()

static int64_t openmpt_stream_file_tell_func ( void *  stream )

static

openmpt_stream_get_buffer_callbacks()

static openmpt_stream_callbacks openmpt_stream_get_buffer_callbacks ( void  )

static

Provide openmpt_stream_callbacks for in-memoy buffers.

Fills openmpt_stream_callbacks suitable for passing an in-memory buffer as a stream parameter to functions doing file input/output. A suitable openmpt_stream_buffer object may be initialized with openmpt_stream_buffer_init().

Remarks

The stream argument must be passed as (void*)(openmpt_stream_buffer*)stream_buffer.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2

openmpt_stream_buffer_init

Deprecated:

Please use openmpt_stream_get_buffer_callbacks2().

openmpt_stream_get_buffer_callbacks2()

static openmpt_stream_callbacks openmpt_stream_get_buffer_callbacks2 ( void  )

static

Provide openmpt_stream_callbacks for in-memoy buffers.

Fills openmpt_stream_callbacks suitable for passing an in-memory buffer as a stream parameter to functions doing file input/output. A suitable openmpt_stream_buffer2 object can be initialized with openmpt_stream_buffer_init2().

Remarks

The stream argument must be passed as (void*)(openmpt_stream_buffer2*)stream_buffer.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2

openmpt_stream_buffer_init2

Since

0.7.0

openmpt_stream_get_fd_callbacks()

static openmpt_stream_callbacks openmpt_stream_get_fd_callbacks ( void  )

static

Provide openmpt_stream_callbacks for standard POSIX file descriptors.

Fills openmpt_stream_callbacks suitable for passing a POSIX filer descriptor as a stream parameter to functions doing file input/output.

Remarks

The stream argument must be passed as (void*)(uintptr_t)(int)fd.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2

openmpt_stream_get_file_callbacks()

static openmpt_stream_callbacks openmpt_stream_get_file_callbacks ( void  )

static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output. Since 0.7.0, it does not try to use platform-specific file seeking any more, but sticks to standard C fseek/ftell only, which means on platforms where long is 32bit, there is no 64bit file access possible any more.

Remarks

The stream argument must be passed as (void*)(FILE*)file.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2

openmpt_stream_get_file_callbacks2()

openmpt_stream_get_file_mingw_callbacks()

openmpt_stream_get_file_msvcrt_callbacks()

openmpt_stream_get_file_posix_callbacks()

openmpt_stream_get_file_posix_lfs64_callbacks()

Deprecated:

Please use openmpt_stream_get_file_callbacks2().

openmpt_stream_get_file_callbacks2()

static openmpt_stream_callbacks openmpt_stream_get_file_callbacks2 ( void  )

static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output. This function uses the standard C fseek and ftell, thus platform-specific file size limits apply accordingly.

Remarks

The stream argument must be passed as (void*)(FILE*)file.

The provided callbacks are limited to handling files up to the size representable in the platform's long type.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2

Since

0.7.0

openmpt_stream_get_file_mingw_callbacks()

static openmpt_stream_callbacks openmpt_stream_get_file_mingw_callbacks ( void  )

static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output.

Remarks

The stream argument must be passed as (void*)(FILE*)file.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2

openmpt_stream_get_file_msvcrt_callbacks()

static openmpt_stream_callbacks openmpt_stream_get_file_msvcrt_callbacks ( void  )

static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output.

Remarks

The stream argument must be passed as (void*)(FILE*)file.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2

openmpt_stream_get_file_posix_callbacks()

static openmpt_stream_callbacks openmpt_stream_get_file_posix_callbacks ( void  )

static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output.

Remarks

The stream argument must be passed as (void*)(FILE*)file.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2

openmpt_stream_get_file_posix_lfs64_callbacks()

static openmpt_stream_callbacks openmpt_stream_get_file_posix_lfs64_callbacks ( void  )

static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output.

Remarks

The stream argument must be passed as (void*)(FILE*)file.

See also

File I/O

openmpt_stream_callbacks

openmpt_could_open_probability2

openmpt_probe_file_header_from_stream

openmpt_module_create2