406 lines
20 KiB
C
406 lines
20 KiB
C
/*
|
|
* libopenmpt_ext.h
|
|
* ----------------
|
|
* Purpose: libopenmpt public c interface for libopenmpt extensions
|
|
* Notes :
|
|
* Authors: OpenMPT Devs
|
|
* The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
|
|
*/
|
|
|
|
#ifndef LIBOPENMPT_EXT_H
|
|
#define LIBOPENMPT_EXT_H
|
|
|
|
#include "libopenmpt_config.h"
|
|
#include "libopenmpt.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*!
|
|
* \page libopenmpt_ext_c_overview libopenmpt_ext C API
|
|
*
|
|
* libopenmpt_ext is included in all builds by default.
|
|
*
|
|
* \section libopenmpt-ext-c-detailed Detailed documentation
|
|
*
|
|
* \ref libopenmpt_ext_c
|
|
*
|
|
*/
|
|
|
|
/*! \defgroup libopenmpt_ext_c libopenmpt_ext C */
|
|
|
|
/*! \addtogroup libopenmpt_ext_c
|
|
* @{
|
|
*/
|
|
|
|
/*! \brief Opaque type representing a libopenmpt extension module
|
|
*/
|
|
typedef struct openmpt_module_ext openmpt_module_ext;
|
|
|
|
/*! \brief Construct an openmpt_module_ext
|
|
*
|
|
* \param stream_callbacks Input stream callback operations.
|
|
* \param stream Input stream to load the module from.
|
|
* \param logfunc Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module_ext. May be NULL.
|
|
* \param loguser User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
|
|
* \param errfunc Error function to define error behaviour. May be NULL.
|
|
* \param erruser Error function user context. Used to pass any user-defined data associated with this module to the logging function.
|
|
* \param error Pointer to an integer where an error may get stored. May be NULL.
|
|
* \param error_message Pointer to a string pointer where an error message may get stored. May be NULL.
|
|
* \param ctls A map of initial ctl values, see openmpt_module_get_ctls.
|
|
* \return A pointer to the constructed openmpt_module_ext, or NULL on failure.
|
|
* \remarks The input data can be discarded after an openmpt_module_ext has been constructed successfully.
|
|
* \sa openmpt_stream_callbacks
|
|
* \sa \ref libopenmpt_c_fileio
|
|
* \since 0.3.0
|
|
*/
|
|
LIBOPENMPT_API openmpt_module_ext * openmpt_module_ext_create( 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 );
|
|
|
|
/*! \brief Construct an openmpt_module_ext
|
|
*
|
|
* \param filedata Data to load the module from.
|
|
* \param filesize Amount of data available.
|
|
* \param logfunc Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module_ext.
|
|
* \param loguser User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
|
|
* \param errfunc Error function to define error behaviour. May be NULL.
|
|
* \param erruser Error function user context. Used to pass any user-defined data associated with this module to the logging function.
|
|
* \param error Pointer to an integer where an error may get stored. May be NULL.
|
|
* \param error_message Pointer to a string pointer where an error message may get stored. May be NULL.
|
|
* \param ctls A map of initial ctl values, see openmpt_module_get_ctls.
|
|
* \return A pointer to the constructed openmpt_module_ext, or NULL on failure.
|
|
* \remarks The input data can be discarded after an openmpt_module_ext has been constructed successfully.
|
|
* \sa \ref libopenmpt_c_fileio
|
|
* \since 0.3.0
|
|
*/
|
|
LIBOPENMPT_API openmpt_module_ext * openmpt_module_ext_create_from_memory( 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 );
|
|
|
|
/*! \brief Unload a previously created openmpt_module_ext from memory.
|
|
*
|
|
* \param mod_ext The module to unload.
|
|
*/
|
|
LIBOPENMPT_API void openmpt_module_ext_destroy( openmpt_module_ext * mod_ext );
|
|
|
|
/*! \brief Retrieve the openmpt_module handle from an openmpt_module_ext handle.
|
|
*
|
|
* \param mod_ext The extension module handle to convert
|
|
* \return An equivalent openmpt_module handle to pass to standard libopenmpt functions
|
|
* \since 0.3.0
|
|
*/
|
|
LIBOPENMPT_API openmpt_module * openmpt_module_ext_get_module( openmpt_module_ext * mod_ext );
|
|
|
|
/*! Retrieve a libopenmpt extension.
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param interface_id The name of the extension interface to retrieve (e.g. LIBOPENMPT_EXT_C_INTERFACE_PATTERN_VIS).
|
|
* \param interface Appropriate structure of interface function pointers which is to be filled by this function (e.g. a pointer to a openmpt_module_ext_interface_pattern_vis structure).
|
|
* \param interface_size Size of the interface's structure of function pointers (e.g. sizeof(openmpt_module_ext_interface_pattern_vis)).
|
|
* \return 1 on success, 0 if the interface was not found.
|
|
* \since 0.3.0
|
|
*/
|
|
LIBOPENMPT_API int openmpt_module_ext_get_interface( openmpt_module_ext * mod_ext, const char * interface_id, void * interface, size_t interface_size );
|
|
|
|
|
|
|
|
#ifndef LIBOPENMPT_EXT_C_INTERFACE_PATTERN_VIS
|
|
#define LIBOPENMPT_EXT_C_INTERFACE_PATTERN_VIS "pattern_vis"
|
|
#endif
|
|
|
|
/*! Pattern command type */
|
|
#define OPENMPT_MODULE_EXT_INTERFACE_PATTERN_VIS_EFFECT_TYPE_UNKNOWN 0
|
|
#define OPENMPT_MODULE_EXT_INTERFACE_PATTERN_VIS_EFFECT_TYPE_GENERAL 1
|
|
#define OPENMPT_MODULE_EXT_INTERFACE_PATTERN_VIS_EFFECT_TYPE_GLOBAL 2
|
|
#define OPENMPT_MODULE_EXT_INTERFACE_PATTERN_VIS_EFFECT_TYPE_VOLUME 3
|
|
#define OPENMPT_MODULE_EXT_INTERFACE_PATTERN_VIS_EFFECT_TYPE_PANNING 4
|
|
#define OPENMPT_MODULE_EXT_INTERFACE_PATTERN_VIS_EFFECT_TYPE_PITCH 5
|
|
|
|
typedef struct openmpt_module_ext_interface_pattern_vis {
|
|
/*! Get pattern command type for pattern highlighting
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param pattern The pattern whose data should be retrieved.
|
|
* \param row The row from which the data should be retrieved.
|
|
* \param channel The channel from which the data should be retrieved.
|
|
* \return The command type in the effect column at the given pattern position (see OPENMPT_MODULE_EXT_INTERFACE_PATTERN_VIS_EFFECT_TYPE_*)
|
|
* \sa openmpt_module_ext_interface_pattern_vis::get_pattern_row_channel_volume_effect_type
|
|
*/
|
|
int ( * get_pattern_row_channel_volume_effect_type ) ( openmpt_module_ext * mod_ext, int32_t pattern, int32_t row, int32_t channel );
|
|
|
|
/*! Get pattern command type for pattern highlighting
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param pattern The pattern whose data should be retrieved.
|
|
* \param row The row from which the data should be retrieved.
|
|
* \param channel The channel from which the data should be retrieved.
|
|
* \return The command type in the effect column at the given pattern position (see OPENMPT_MODULE_EXT_INTERFACE_PATTERN_VIS_EFFECT_TYPE_*)
|
|
* \sa openmpt_module_ext_interface_pattern_vis::get_pattern_row_channel_volume_effect_type
|
|
*/
|
|
int ( * get_pattern_row_channel_effect_type ) ( openmpt_module_ext * mod_ext, int32_t pattern, int32_t row, int32_t channel );
|
|
} openmpt_module_ext_interface_pattern_vis;
|
|
|
|
|
|
|
|
#ifndef LIBOPENMPT_EXT_C_INTERFACE_INTERACTIVE
|
|
#define LIBOPENMPT_EXT_C_INTERFACE_INTERACTIVE "interactive"
|
|
#endif
|
|
|
|
typedef struct openmpt_module_ext_interface_interactive {
|
|
/*! Set the current ticks per row (speed)
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param speed The new tick count in range [1, 65535].
|
|
* \return 1 on success, 0 on failure.
|
|
* \remarks The tick count may be reset by pattern commands at any time.
|
|
* \sa openmpt_module_get_current_speed
|
|
*/
|
|
int ( * set_current_speed ) ( openmpt_module_ext * mod_ext, int32_t speed );
|
|
|
|
/*! Set the current module tempo
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param tempo The new tempo in range [32, 512]. The exact meaning of the value depends on the tempo mode used by the module.
|
|
* \return 1 on success, 0 on failure.
|
|
* \remarks The tempo may be reset by pattern commands at any time. Use openmpt_module_ext_interface_interactive::set_tempo_factor to apply a tempo factor that is independent of pattern commands.
|
|
* \sa openmpt_module_get_current_tempo
|
|
*/
|
|
int ( * set_current_tempo ) ( openmpt_module_ext * mod_ext, int32_t tempo );
|
|
|
|
/*! Set the current module tempo factor without affecting playback pitch
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param factor The new tempo factor in range ]0.0, 4.0] - 1.0 means unmodified tempo.
|
|
* \return 1 on success, 0 on failure.
|
|
* \remarks Modifying the tempo without applying the same pitch factor using openmpt_module_ext_interface_interactive::set_pitch_factor may cause rhythmic samples (e.g. drum loops) to go out of sync.
|
|
* \sa openmpt_module_ext_interface_interactive::get_tempo_factor
|
|
*/
|
|
int ( * set_tempo_factor ) ( openmpt_module_ext * mod_ext, double factor );
|
|
|
|
/*! Gets the current module tempo factor
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \return The current tempo factor.
|
|
* \sa openmpt_module_ext_interface_interactive::set_tempo_factor
|
|
*/
|
|
double ( * get_tempo_factor ) ( openmpt_module_ext * mod_ext );
|
|
|
|
/*! Set the current module pitch factor without affecting playback speed
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param factor The new pitch factor in range ]0.0, 4.0] - 1.0 means unmodified pitch.
|
|
* \return 1 on success, 0 on failure.
|
|
* \remarks Modifying the pitch without applying the the same tempo factor using openmpt_module_ext_interface_interactive::set_tempo_factor may cause rhythmic samples (e.g. drum loops) to go out of sync.
|
|
* \remarks To shift the pich by `n` semitones, the parameter can be calculated as follows: `pow( 2.0, n / 12.0 )`
|
|
* \sa openmpt_module_ext_interface_interactive::get_pitch_factor
|
|
*/
|
|
int ( * set_pitch_factor ) ( openmpt_module_ext * mod_ext, double factor );
|
|
|
|
/*! Gets the current module pitch factor
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \return The current pitch factor.
|
|
* \sa openmpt_module_ext_interface_interactive::set_pitch_factor
|
|
*/
|
|
double ( * get_pitch_factor ) ( openmpt_module_ext * mod_ext );
|
|
|
|
/*! Set the current global volume
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param volume The new global volume in range [0.0, 1.0]
|
|
* \return 1 on success, 0 on failure.
|
|
* \remarks The global volume may be reset by pattern commands at any time. Use openmpt_module_set_render_param to apply a global overall volume factor that is independent of pattern commands.
|
|
* \sa openmpt_module_ext_interface_interactive::get_global_volume
|
|
*/
|
|
int ( * set_global_volume ) ( openmpt_module_ext * mod_ext, double volume );
|
|
|
|
/*! Get the current global volume
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \return The current global volume in range [0.0, 1.0]
|
|
* \sa openmpt_module_ext_interface_interactive::set_global_volume
|
|
*/
|
|
double ( * get_global_volume ) ( openmpt_module_ext * mod_ext );
|
|
|
|
/*! Set the current channel volume for a channel
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel whose volume should be set, in range [0, openmpt_module_get_num_channels()[
|
|
* \param volume The new channel volume in range [0.0, 1.0]
|
|
* \return 1 on success, 0 on failure (channel out of range).
|
|
* \remarks The channel volume may be reset by pattern commands at any time.
|
|
* \sa openmpt_module_ext_interface_interactive::get_channel_volume
|
|
*/
|
|
int ( * set_channel_volume ) ( openmpt_module_ext * mod_ext, int32_t channel, double volume );
|
|
|
|
/*! Get the current channel volume for a channel
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel whose volume should be retrieved, in range [0, openmpt_module_get_num_channels()[
|
|
* \return The current channel volume in range [0.0, 1.0]
|
|
* \sa openmpt_module_ext_interface_interactive::set_channel_volume
|
|
*/
|
|
double ( * get_channel_volume ) ( openmpt_module_ext * mod_ext, int32_t channel );
|
|
|
|
/*! Set the current mute status for a channel
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel whose mute status should be set, in range [0, openmpt_module_get_num_channels()[
|
|
* \param mute The new mute status. true is muted, false is unmuted.
|
|
* \return 1 on success, 0 on failure (channel out of range).
|
|
* \sa openmpt_module_ext_interface_interactive::get_channel_mute_status
|
|
*/
|
|
int ( * set_channel_mute_status ) ( openmpt_module_ext * mod_ext, int32_t channel, int mute );
|
|
|
|
/*! Get the current mute status for a channel
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel whose mute status should be retrieved, in range [0, openmpt_module_get_num_channels()[
|
|
* \return The current channel mute status. 1 is muted, 0 is unmuted, -1 means the instrument was out of range
|
|
* \sa openmpt_module_ext_interface_interactive::set_channel_mute_status
|
|
*/
|
|
int ( * get_channel_mute_status ) ( openmpt_module_ext * mod_ext, int32_t channel );
|
|
|
|
/*! Set the current mute status for an instrument
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param instrument The instrument whose mute status should be set, in range [0, openmpt_module_get_num_instruments()[ if openmpt_module_get_num_instruments is not 0, otherwise in [0, openmpt_module_get_num_samples()[
|
|
* \param mute The new mute status. true is muted, false is unmuted.
|
|
* \return 1 on success, 0 on failure (instrument out of range).
|
|
* \sa openmpt_module_ext_interface_interactive::get_instrument_mute_status
|
|
*/
|
|
int ( * set_instrument_mute_status ) ( openmpt_module_ext * mod_ext, int32_t instrument, int mute );
|
|
|
|
/*! Get the current mute status for an instrument
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param instrument The instrument whose mute status should be retrieved, in range [0, openmpt_module_get_num_instruments()[ if openmpt_module_get_num_instruments is not 0, otherwise in [0, openmpt_module_get_num_samples()[
|
|
* \return The current instrument mute status. 1 is muted, 0 is unmuted, -1 means the instrument was out of range
|
|
* \sa openmpt_module_ext_interface_interactive::set_instrument_mute_status
|
|
*/
|
|
int ( * get_instrument_mute_status ) ( openmpt_module_ext * mod_ext, int32_t instrument );
|
|
|
|
/*! Play a note using the specified instrument
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param instrument The instrument that should be played, in range [0, openmpt_module_get_num_instruments()[ if openmpt_module_get_num_instruments is not 0, otherwise in [0, openmpt_module_get_num_samples()[
|
|
* \param note The note to play, in rage [0, 119]. 60 is the middle C.
|
|
* \param volume The volume at which the note should be triggered, in range [0.0, 1.0]
|
|
* \param panning The panning position at which the note should be triggered, in range [-1.0, 1.0], 0.0 is center.
|
|
* \return The channel on which the note is played. This can pe be passed to openmpt_module_ext_interface_interactive::stop_note to stop the note. -1 means that no channel could be allocated and the note is not played.
|
|
* \sa openmpt_module_ext_interface_interactive::stop_note
|
|
* \sa openmpt_module_ext_interface_interactive2::note_off
|
|
* \sa openmpt_module_ext_interface_interactive2::note_fade
|
|
*/
|
|
int32_t ( * play_note ) ( openmpt_module_ext * mod_ext, int32_t instrument, int32_t note, double volume, double panning );
|
|
|
|
/*! Stop the note playing on the specified channel
|
|
*
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel on which the note should be stopped. This is the value returned by a previous play_note call.
|
|
* \return 1 on success, 0 on failure (channel out of range).
|
|
* \sa openmpt_module_ext_interface_interactive::play_note
|
|
* \sa openmpt_module_ext_interface_interactive2::note_off
|
|
* \sa openmpt_module_ext_interface_interactive2::note_fade
|
|
*/
|
|
int ( * stop_note ) ( openmpt_module_ext * mod_ext, int32_t channel );
|
|
|
|
} openmpt_module_ext_interface_interactive;
|
|
|
|
|
|
|
|
#ifndef LIBOPENMPT_EXT_C_INTERFACE_INTERACTIVE2
|
|
#define LIBOPENMPT_EXT_C_INTERFACE_INTERACTIVE2 "interactive2"
|
|
#endif
|
|
|
|
typedef struct openmpt_module_ext_interface_interactive2 {
|
|
//! Sends a key-off command for the note playing on the specified channel
|
|
/*!
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel on which the key-off event should be triggered. This is the value returned by a previous play_note call.
|
|
* \return 1 on success, 0 on failure (channel out of range).
|
|
* \remarks This method releases envelopes and sample sustain loops. If the sample has no sustain loop, or if the module does not use instruments, it does nothing.
|
|
* \sa openmpt_module_ext_interface_interactive::play_note
|
|
* \sa openmpt_module_ext_interface_interactive::stop_note
|
|
* \sa openmpt_module_ext_interface_interactive2::note_fade
|
|
* \since 0.6.0
|
|
*/
|
|
int ( *note_off ) ( openmpt_module_ext * mod_ext, int32_t channel );
|
|
|
|
//! Sends a note fade command for the note playing on the specified channel
|
|
/*!
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel on which the note should be faded. This is the value returned by a previous play_note call.
|
|
* \return 1 on success, 0 on failure (channel out of range).
|
|
* \remarks This method uses the instrument's fade-out value. If the module does not use instruments, or the instrument's fade-out value is 0, it does nothing.
|
|
* \sa openmpt_module_ext_interface_interactive::play_note
|
|
* \sa openmpt_module_ext_interface_interactive::stop_note
|
|
* \sa openmpt_module_ext_interface_interactive2::note_fade
|
|
* \since 0.6.0
|
|
*/
|
|
int ( *note_fade ) ( openmpt_module_ext * mod_ext, int32_t channel );
|
|
|
|
//! Set the current panning for a channel
|
|
/*!
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel that should be panned. This is the value returned by a previous play_note call.
|
|
* \param panning The panning position to set on the channel, in range [-1.0, 1.0], 0.0 is center.
|
|
* \return 1 on success, 0 on failure (channel out of range).
|
|
* \remarks This command affects subsequent notes played on the same channel, and may itself be overridden by subsequent panning commands encountered in the module itself.
|
|
* \sa openmpt_module_ext_interface_interactive2::get_channel_panning
|
|
* \since 0.6.0
|
|
*/
|
|
int ( *set_channel_panning) ( openmpt_module_ext * mod_ext, int32_t channel, double panning );
|
|
|
|
//! Get the current panning position for a channel
|
|
/*!
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel whose panning should be retrieved. This is the value returned by a previous play_note call.
|
|
* \return The current channel panning, in range [-1.0, 1.0], 0.0 is center.
|
|
* \sa openmpt_module_ext_interface_interactive2::set_channel_panning
|
|
* \since 0.6.0
|
|
*/
|
|
double (*get_channel_panning) ( openmpt_module_ext * mod_ext, int32_t channel );
|
|
|
|
//! Set the finetune for the currently playing note on a channel
|
|
/*!
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel whose finetune will be changed, in range [0, openmpt::module::get_num_channels()[
|
|
* \param finetune The finetune to set on the channel, in range [-1.0, 1.0], 0.0 is center.
|
|
* \throws openmpt::exception Throws an exception derived from openmpt::exception if the channel index is invalid.
|
|
* \remarks The finetune range depends on the pitch wheel depth of the instrument playing on the current channel; for sample-based modules, the depth of this command is fixed to +/-1 semitone.
|
|
* \remarks This command does not affect subsequent notes played on the same channel, but may itself be overridden by subsequent finetune commands encountered in the module itself.
|
|
* \sa openmpt_module_ext_interface_interactive2::get_note_finetune
|
|
* \since 0.6.0
|
|
*/
|
|
int ( *set_note_finetune) ( openmpt_module_ext * mod_ext, int32_t channel, double finetune );
|
|
|
|
//! Get the finetune for the currently playing note on a channel
|
|
/*!
|
|
* \param mod_ext The module handle to work on.
|
|
* \param channel The channel whose finetune should be retrieved, in range [0, openmpt::module::get_num_channels()[
|
|
* \return The current channel finetune, in range [-1.0, 1.0], 0.0 is center.
|
|
* \remarks The finetune range depends on the pitch wheel depth of the instrument playing on the current channel; for sample-based modules, the depth of this command is fixed to +/-1 semitone.
|
|
* \throws openmpt::exception Throws an exception derived from openmpt::exception if the channel is outside the specified range.
|
|
* \sa openmpt_module_ext_interface_interactive2::set_note_finetune
|
|
* \since 0.6.0
|
|
*/
|
|
double (*get_note_finetune) ( openmpt_module_ext * mod_ext, int32_t channel );
|
|
|
|
} openmpt_module_ext_interface_interactive2;
|
|
|
|
|
|
|
|
/* add stuff here */
|
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
/*!
|
|
* @}
|
|
*/
|
|
|
|
#endif /* LIBOPENMPT_EXT_H */
|
|
|