From 7181959675c1658cff313a161f3a96f88a118baa Mon Sep 17 00:00:00 2001 From: JP Cimalando Date: Thu, 28 Jun 2018 01:10:37 +0200 Subject: basic channel description API --- include/adlmidi.h | 3 +++ 1 file changed, 3 insertions(+) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index a1289a0..00f478b 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -270,6 +270,9 @@ extern void adl_positionRewind(struct ADL_MIDIPlayer *device); /*Set tempo multiplier: 1.0 - original tempo, >1 - play faster, <1 - play slower */ extern void adl_setTempo(struct ADL_MIDIPlayer *device, double tempo); +/*Get a textual description of the channel state. For display only.*/ +extern int adl_describeChannels(struct ADL_MIDIPlayer *device, char *text, char *attr, size_t size); + /*Close and delete ADLMIDI device*/ extern void adl_close(struct ADL_MIDIPlayer *device); -- cgit v1.2.3 From eecf8221aeac7097b971d585140850d45271e7a0 Mon Sep 17 00:00:00 2001 From: JP Cimalando Date: Tue, 3 Jul 2018 18:50:49 +0200 Subject: embedded bank loading API into multi-bank --- include/adlmidi.h | 2 ++ 1 file changed, 2 insertions(+) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index a1289a0..348b15c 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -149,6 +149,8 @@ extern int adl_getNextBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); extern int adl_getInstrument(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, unsigned index, ADL_Instrument *ins); /* Sets the nth intrument in the bank [0..127]. */ extern int adl_setInstrument(struct ADL_MIDIPlayer *device, ADL_Bank *bank, unsigned index, const ADL_Instrument *ins); +/* Loads the melodic or percussive part of the nth embedded bank. */ +extern int adl_loadEmbeddedBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank, int num); #endif /* defined(ADLMIDI_UNSTABLE_API) */ /*Sets number of 4-operator channels between all chips. -- cgit v1.2.3 From 3d60c15ae32219a7b29ccfa8221279f52a55858e Mon Sep 17 00:00:00 2001 From: Vitaly Novichkov Date: Wed, 4 Jul 2018 00:06:25 +0300 Subject: Remove "ADLMIDI_UNSTABLE_API" macro. As it's dev version, and lets polish this API to release it in next time --- include/adlmidi.h | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index 153cc5d..bf146db 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -132,7 +132,6 @@ enum ADL_BankAccessFlags typedef struct ADL_Instrument ADL_Instrument; -#if defined(ADLMIDI_UNSTABLE_API) /* Preallocates a minimum number of bank slots. Returns the actual capacity. */ extern int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks); /* Gets the bank designated by the identifier, optionally creating if it does not exist. */ @@ -151,7 +150,7 @@ extern int adl_getInstrument(struct ADL_MIDIPlayer *device, const ADL_Bank *bank extern int adl_setInstrument(struct ADL_MIDIPlayer *device, ADL_Bank *bank, unsigned index, const ADL_Instrument *ins); /* Loads the melodic or percussive part of the nth embedded bank. */ extern int adl_loadEmbeddedBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank, int num); -#endif /* defined(ADLMIDI_UNSTABLE_API) */ + /*Sets number of 4-operator channels between all chips. By default, it is automatically re-calculating every bank change. -- cgit v1.2.3 From 90f8b60438d59a1871a5ebf80a279c0eeea7a1a7 Mon Sep 17 00:00:00 2001 From: Vitaly Novichkov Date: Wed, 4 Jul 2018 00:25:35 +0300 Subject: Added instrument rhythm-mode related enums into the public header --- include/adlmidi.h | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index bf146db..3345fe6 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -408,10 +408,28 @@ typedef enum ADL_InstrumentFlags ADLMIDI_Ins_Pseudo4op = 0x02, /* Is a blank instrument entry */ ADLMIDI_Ins_IsBlank = 0x04, + + /* RythmMode flags mask */ + ADLMIDI_Ins_RhythmModeMask = 0x38, + /* Mask of the flags range */ ADLMIDI_Ins_ALL_MASK = 0x07, } ADL_InstrumentFlags; +typedef enum ADL_RhythmMode +{ + /* RythmMode: BassDrum */ + WOPL_RM_BassDrum = 0x08, + /* RythmMode: Snare */ + WOPL_RM_Snare = 0x10, + /* RythmMode: TomTom */ + WOPL_RM_TomTom = 0x18, + /* RythmMode: Cymbell */ + WOPL_RM_Cymball = 0x20, + /* RythmMode: HiHat */ + WOPL_RM_HiHat = 0x28 +} ADL_RhythmMode; + typedef struct ADL_Operator { /* AM/Vib/Env/Ksr/FMult characteristics */ -- cgit v1.2.3 From e6d67761951b7d0c61adba0a3420379c04864ff3 Mon Sep 17 00:00:00 2001 From: Vitaly Novichkov Date: Wed, 4 Jul 2018 00:48:23 +0300 Subject: Another typo fixes, begin to document all public functions --- include/adlmidi.h | 229 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 167 insertions(+), 62 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index 3345fe6..f644e3e 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -55,90 +55,182 @@ typedef char ADL_SInt8; typedef short ADL_SInt16; #endif +/** + * @brief Volume scaling models + */ enum ADLMIDI_VolumeModels { + /*! Automatical choice by the specific bank */ ADLMIDI_VolumeModel_AUTO = 0, + /*! Linearized scaling model, most standard */ ADLMIDI_VolumeModel_Generic = 1, + /*! Native OPL3's logarithmic volume scale */ ADLMIDI_VolumeModel_NativeOPL3 = 2, + /*! Native OPL3's logarithmic volume scale. Alias. */ ADLMIDI_VolumeModel_CMF = ADLMIDI_VolumeModel_NativeOPL3, + /*! Logarithmic volume scale, using volume map table. Used in DMX. */ ADLMIDI_VolumeModel_DMX = 3, + /*! Logarithmic volume scale, used in Apogee Sound System. */ ADLMIDI_VolumeModel_APOGEE = 4, + /*! Aproximated and shorted volume map table. Similar to general, but has less granularity. */ ADLMIDI_VolumeModel_9X = 5 }; +/** + * @brief Sound output format + */ enum ADLMIDI_SampleType { - ADLMIDI_SampleType_S16 = 0, /* signed PCM 16-bit */ - ADLMIDI_SampleType_S8, /* signed PCM 8-bit */ - ADLMIDI_SampleType_F32, /* float 32-bit */ - ADLMIDI_SampleType_F64, /* float 64-bit */ - ADLMIDI_SampleType_S24, /* signed PCM 24-bit */ - ADLMIDI_SampleType_S32, /* signed PCM 32-bit */ - ADLMIDI_SampleType_U8, /* unsigned PCM 8-bit */ - ADLMIDI_SampleType_U16, /* unsigned PCM 16-bit */ - ADLMIDI_SampleType_U24, /* unsigned PCM 24-bit */ - ADLMIDI_SampleType_U32, /* unsigned PCM 32-bit */ + /*! signed PCM 16-bit */ + ADLMIDI_SampleType_S16 = 0, + /*! signed PCM 8-bit */ + ADLMIDI_SampleType_S8, + /*! float 32-bit */ + ADLMIDI_SampleType_F32, + /*! float 64-bit */ + ADLMIDI_SampleType_F64, + /*! signed PCM 24-bit */ + ADLMIDI_SampleType_S24, + /*! signed PCM 32-bit */ + ADLMIDI_SampleType_S32, + /*! unsigned PCM 8-bit */ + ADLMIDI_SampleType_U8, + /*! unsigned PCM 16-bit */ + ADLMIDI_SampleType_U16, + /*! unsigned PCM 24-bit */ + ADLMIDI_SampleType_U24, + /*! unsigned PCM 32-bit */ + ADLMIDI_SampleType_U32, + /*! Count of available sample format types */ ADLMIDI_SampleType_Count, }; +/** + * @brief Sound output format context + */ struct ADLMIDI_AudioFormat { - enum ADLMIDI_SampleType type; /* type of sample */ - unsigned containerSize; /* size in bytes of the storage type */ - unsigned sampleOffset; /* distance in bytes between consecutive samples */ + /*! type of sample */ + enum ADLMIDI_SampleType type; + /*! size in bytes of the storage type */ + unsigned containerSize; + /*! distance in bytes between consecutive samples */ + unsigned sampleOffset; }; +/** + * @brief Instance of the library + */ struct ADL_MIDIPlayer { + /*! Private context descriptor */ void *adl_midiPlayer; }; /* DEPRECATED */ #define adl_setNumCards adl_setNumChips -/* Sets number of emulated chips (from 1 to 100). Emulation of multiple chips exchanges polyphony limits*/ +/** + * @brief Sets number of emulated chips (from 1 to 100). Emulation of multiple chips exchanges polyphony limits + * @param device Instance of the library + * @param numChips Count of virtual chips to emulate + * @return 0 on success, <0 when any error has occurred + */ extern int adl_setNumChips(struct ADL_MIDIPlayer *device, int numChips); -/* Get current number of emulated chips */ +/** + * @brief Get current number of emulated chips + * @param device Instance of the library + * @return Count of working chip emulators + */ extern int adl_getNumChips(struct ADL_MIDIPlayer *device); -/* Sets a number of the patches bank from 0 to N banks. Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. */ +/** + * @brief Sets a number of the patches bank from 0 to N banks. + * @param device Instance of the library + * @param bank Number of embedded bank + * @return 0 on success, <0 when any error has occurred + * + * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. + */ extern int adl_setBank(struct ADL_MIDIPlayer *device, int bank); -/* Returns total number of available banks */ +/** + * @brief Returns total number of available banks + * @return Total number of available embedded banks + */ extern int adl_getBanksCount(); -/* Returns pointer to array of names of every bank */ +/** + * @brief Returns pointer to array of names of every bank + * @return Array of strings are containing names of every embedded bank + */ extern const char *const *adl_getBankNames(); -/* Reference to dynamic bank */ +/** + * @brief Reference to dynamic bank + */ typedef struct ADL_Bank { void *pointer[3]; } ADL_Bank; -/* Identifier of dynamic bank */ +/** + * @brief Identifier of dynamic bank + */ typedef struct ADL_BankId { - ADL_UInt8 percussive, msb, lsb; + /*! 0 if bank is melodic set, or 1 if bank is a percussion set */ + ADL_UInt8 percussive; + /*! Assign to MSB bank number */ + ADL_UInt8 msb; + /*! Assign to LSB bank number */ + ADL_UInt8 lsb; } ADL_BankId; -/* Flags for dynamic bank access */ +/** + * @brief Flags for dynamic bank access + */ enum ADL_BankAccessFlags { - ADLMIDI_Bank_Create = 1, /* create bank, allocating memory as needed */ - ADLMIDI_Bank_CreateRt = 1|2, /* create bank, never allocating memory */ + /*! create bank, allocating memory as needed */ + ADLMIDI_Bank_Create = 1, + /*! create bank, never allocating memory */ + ADLMIDI_Bank_CreateRt = 1|2, }; typedef struct ADL_Instrument ADL_Instrument; -/* Preallocates a minimum number of bank slots. Returns the actual capacity. */ +/** + * @brief Preallocates a minimum number of bank slots. Returns the actual capacity. + * @param device Instance of the library + * @param banks Count of bank slots to pre-allocate. + * @return actual capacity of reserved bank slots. + */ extern int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks); -/* Gets the bank designated by the identifier, optionally creating if it does not exist. */ +/** + * @brief Gets the bank designated by the identifier, optionally creating if it does not exist. + * @param device Instance of the library + * @param id Identifier of dynamic bank + * @param flags Flags for dynamic bank access (ADL_BankAccessFlags) + * @param bank Reference to dynamic bank + * @return 0 on success, <0 when any error has occurred + */ extern int adl_getBank(struct ADL_MIDIPlayer *device, const ADL_BankId *id, int flags, ADL_Bank *bank); -/* Gets the identifier of a bank. */ +/** + * @brief Gets the identifier of a bank. + * @param device Instance of the library + * @param bank Reference to dynamic bank. + * @param id Identifier of dynamic bank + * @return 0 on success, <0 when any error has occurred + */ extern int adl_getBankId(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, ADL_BankId *id); -/* Removes a bank. */ +/** + * @brief Removes a bank + * @param device Instance of the library + * @param bank Reference to dynamic bank. + * @return 0 on success, <0 when any error has occurred + */ extern int adl_removeBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); /* Gets the first bank. */ extern int adl_getFirstBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); @@ -391,84 +483,97 @@ extern void adl_setNoteHook(struct ADL_MIDIPlayer *device, ADL_NoteHook noteHook extern void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMessageHook debugMessageHook, void *userData); -/**Instrument structures**/ +/** Instrument structures **/ enum { ADLMIDI_InstrumentVersion = 0, }; +/** + * @brief Instrument flags + */ typedef enum ADL_InstrumentFlags { - /* Is two-operator single-voice instrument (no flags) */ + /*! Is two-operator single-voice instrument (no flags) */ ADLMIDI_Ins_2op = 0x00, - /* Is true four-operator instrument */ + /*! Is true four-operator instrument */ ADLMIDI_Ins_4op = 0x01, - /* Is pseudo four-operator (two 2-operator voices) instrument */ + /*! Is pseudo four-operator (two 2-operator voices) instrument */ ADLMIDI_Ins_Pseudo4op = 0x02, - /* Is a blank instrument entry */ + /*! Is a blank instrument entry */ ADLMIDI_Ins_IsBlank = 0x04, - /* RythmMode flags mask */ + /*! RythmMode flags mask */ ADLMIDI_Ins_RhythmModeMask = 0x38, - /* Mask of the flags range */ + /*! Mask of the flags range */ ADLMIDI_Ins_ALL_MASK = 0x07, } ADL_InstrumentFlags; +/** + * @brief Rhythm-mode drum type + */ typedef enum ADL_RhythmMode { - /* RythmMode: BassDrum */ - WOPL_RM_BassDrum = 0x08, - /* RythmMode: Snare */ - WOPL_RM_Snare = 0x10, - /* RythmMode: TomTom */ - WOPL_RM_TomTom = 0x18, - /* RythmMode: Cymbell */ - WOPL_RM_Cymball = 0x20, - /* RythmMode: HiHat */ - WOPL_RM_HiHat = 0x28 + /*! RythmMode: BassDrum */ + ADLMIDI_RM_BassDrum = 0x08, + /*! RythmMode: Snare */ + ADLMIDI_RM_Snare = 0x10, + /*! RythmMode: TomTom */ + ADLMIDI_RM_TomTom = 0x18, + /*! RythmMode: Cymbal */ + ADLMIDI_RM_Cymbal = 0x20, + /*! RythmMode: HiHat */ + ADLMIDI_RM_HiHat = 0x28 } ADL_RhythmMode; + +/** + * @brief Operator structure, part of Instrument structure + */ typedef struct ADL_Operator { - /* AM/Vib/Env/Ksr/FMult characteristics */ + /*! AM/Vib/Env/Ksr/FMult characteristics */ ADL_UInt8 avekf_20; - /* Key Scale Level / Total level register data */ + /*! Key Scale Level / Total level register data */ ADL_UInt8 ksl_l_40; - /* Attack / Decay */ + /*! Attack / Decay */ ADL_UInt8 atdec_60; - /* Systain and Release register data */ + /*! Systain and Release register data */ ADL_UInt8 susrel_80; - /* Wave form */ + /*! Wave form */ ADL_UInt8 waveform_E0; } ADL_Operator; +/** + * @brief Instrument structure + */ typedef struct ADL_Instrument { - /* Version of the instrument object */ + /*! Version of the instrument object */ int version; - /* MIDI note key (half-tone) offset for an instrument (or a first voice in pseudo-4-op mode) */ + /*! MIDI note key (half-tone) offset for an instrument (or a first voice in pseudo-4-op mode) */ ADL_SInt16 note_offset1; - /* MIDI note key (half-tone) offset for a second voice in pseudo-4-op mode */ + /*! MIDI note key (half-tone) offset for a second voice in pseudo-4-op mode */ ADL_SInt16 note_offset2; - /* MIDI note velocity offset (taken from Apogee TMB format) */ + /*! MIDI note velocity offset (taken from Apogee TMB format) */ ADL_SInt8 midi_velocity_offset; - /* Second voice detune level (taken from DMX OP2) */ + /*! Second voice detune level (taken from DMX OP2) */ ADL_SInt8 second_voice_detune; - /* Percussion MIDI base tone number at which this drum will be played */ + /*! Percussion MIDI base tone number at which this drum will be played */ ADL_UInt8 percussion_key_number; - /* Enum ADL_InstrumentFlags */ + /*! Enum ADL_InstrumentFlags */ ADL_UInt8 inst_flags; - /* Feedback&Connection register for first and second operators */ + /*! Feedback&Connection register for first and second operators */ ADL_UInt8 fb_conn1_C0; - /* Feedback&Connection register for third and fourth operators */ + /*! Feedback&Connection register for third and fourth operators */ ADL_UInt8 fb_conn2_C0; - /* Operators register data */ + /*! Operators register data */ ADL_Operator operators[4]; - /* Millisecond delay of sounding while key is on */ + /*! Millisecond delay of sounding while key is on */ ADL_UInt16 delay_on_ms; - /* Millisecond delay of sounding after key off */ + /*! Millisecond delay of sounding after key off */ ADL_UInt16 delay_off_ms; } ADL_Instrument; -- cgit v1.2.3 From 35ed7d8b215fee6d08d8d411bd2d1ce2a3c68f71 Mon Sep 17 00:00:00 2001 From: Vitaly Novichkov Date: Wed, 4 Jul 2018 01:02:38 +0300 Subject: Continue documenting the library public functions --- include/adlmidi.h | 142 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 115 insertions(+), 27 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index f644e3e..e81894e 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -202,14 +202,14 @@ enum ADL_BankAccessFlags typedef struct ADL_Instrument ADL_Instrument; /** - * @brief Preallocates a minimum number of bank slots. Returns the actual capacity. + * @brief Preallocates a minimum number of bank slots. Returns the actual capacity * @param device Instance of the library * @param banks Count of bank slots to pre-allocate. * @return actual capacity of reserved bank slots. */ extern int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks); /** - * @brief Gets the bank designated by the identifier, optionally creating if it does not exist. + * @brief Gets the bank designated by the identifier, optionally creating if it does not exist * @param device Instance of the library * @param id Identifier of dynamic bank * @param flags Flags for dynamic bank access (ADL_BankAccessFlags) @@ -218,7 +218,7 @@ extern int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks); */ extern int adl_getBank(struct ADL_MIDIPlayer *device, const ADL_BankId *id, int flags, ADL_Bank *bank); /** - * @brief Gets the identifier of a bank. + * @brief Gets the identifier of a bank * @param device Instance of the library * @param bank Reference to dynamic bank. * @param id Identifier of dynamic bank @@ -228,48 +228,113 @@ extern int adl_getBankId(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, AD /** * @brief Removes a bank * @param device Instance of the library - * @param bank Reference to dynamic bank. + * @param bank Reference to dynamic bank * @return 0 on success, <0 when any error has occurred */ extern int adl_removeBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); -/* Gets the first bank. */ +/** + * @brief Gets the first bank + * @param device Instance of the library + * @param bank Reference to dynamic bank + * @return 0 on success, <0 when any error has occurred + */ extern int adl_getFirstBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); -/* Iterates to the next bank. */ +/** + * @brief Iterates to the next bank + * @param device Instance of the library + * @param bank Reference to dynamic bank + * @return 0 on success, <0 when any error has occurred or end has been reached. + */ extern int adl_getNextBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); -/* Gets the nth intrument in the bank [0..127]. */ +/** + * @brief Gets the nth intrument in the bank [0..127] + * @param device Instance of the library + * @param bank Reference to dynamic bank + * @param index Index of the instrument + * @param ins Instrument entry + * @return 0 on success, <0 when any error has occurred + */ extern int adl_getInstrument(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, unsigned index, ADL_Instrument *ins); -/* Sets the nth intrument in the bank [0..127]. */ +/** + * @brief Sets the nth intrument in the bank [0..127] + * @param device Instance of the library + * @param bank Reference to dynamic bank + * @param index Index of the instrument + * @param ins Instrument structure pointer + * @return 0 on success, <0 when any error has occurred + * + * This function allows to override an instrument on the fly + */ extern int adl_setInstrument(struct ADL_MIDIPlayer *device, ADL_Bank *bank, unsigned index, const ADL_Instrument *ins); -/* Loads the melodic or percussive part of the nth embedded bank. */ +/** + * @brief Loads the melodic or percussive part of the nth embedded bank + * @param device Instance of the library + * @param bank Reference to dynamic bank + * @param num Number of embedded bank to load into the current bank array + * @return 0 on success, <0 when any error has occurred + */ extern int adl_loadEmbeddedBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank, int num); -/*Sets number of 4-operator channels between all chips. - By default, it is automatically re-calculating every bank change. - If you want to specify custom number of four operator channels, - please call this function after bank change (adl_setBank() or adl_openBank()), - otherwise, value will be overwritten by auto-calculated.*/ + +/** + * @brief Sets number of 4-operator channels between all chips + * @param device Instance of the library + * @param ops4 Count of four-op channels to allocate between all emulating chips + * @return 0 on success, <0 when any error has occurred + * + * By default, it is automatically re-calculating every bank change. + * If you want to specify custom number of four operator channels, + * please call this function after bank change (adl_setBank() or adl_openBank()), + * otherwise, value will be overwritten by auto-calculated. + */ extern int adl_setNumFourOpsChn(struct ADL_MIDIPlayer *device, int ops4); -/*Get current total count of 4-operator channels between all chips*/ +/** + * @brief Get current total count of 4-operator channels between all chips + * @param device Instance of the library + * @return 0 on success, <0 when any error has occurred + */ extern int adl_getNumFourOpsChn(struct ADL_MIDIPlayer *device); -/*Override Enable(1) or Disable(0) AdLib percussion mode. -1 - use bank default AdLib percussion mode*/ +/** + * @brief Override Enable(1) or Disable(0) AdLib percussion mode. -1 - use bank default AdLib percussion mode + * @param device Instance of the library + * @param percmod 0 - disabled, 1 - enabled + * + * This function forces rhythm-mode on any bank. The result will wrork glitchy. + */ extern void adl_setPercMode(struct ADL_MIDIPlayer *device, int percmod); -/*Override Enable(1) or Disable(0) deep vibrato state. -1 - use bank default vibrato state*/ +/** + * @brief Override Enable(1) or Disable(0) deep vibrato state. -1 - use bank default vibrato state + * @param device Instance of the library + * @param hvibro 0 - disabled, 1 - enabled + */ extern void adl_setHVibrato(struct ADL_MIDIPlayer *device, int hvibro); -/*Override Enable(1) or Disable(0) deep tremolo state. -1 - use bank default tremolo state*/ +/** + * @brief Override Enable(1) or Disable(0) deep tremolo state. -1 - use bank default tremolo state + * @param device Instance of the library + * @param hvibro 0 - disabled, 1 - enabled + */ extern void adl_setHTremolo(struct ADL_MIDIPlayer *device, int htremo); -/*Override Enable(1) or Disable(0) scaling of modulator volumes. -1 - use bank default scaling of modulator volumes*/ +/** + * @brief Override Enable(1) or Disable(0) scaling of modulator volumes. -1 - use bank default scaling of modulator volumes + * @param device Instance of the library + * @param hvibro 0 - disabled, 1 - enabled + */ extern void adl_setScaleModulators(struct ADL_MIDIPlayer *device, int smod); -/*Enable(1) or Disable(0) full-range brightness (MIDI CC74 used in XG music to filter result sounding) scaling. - By default, brightness affects sound between 0 and 64. - When this option is enabled, the range will use a full range from 0 up to 127. -*/ +/** + * @brief Enable(1) or Disable(0) full-range brightness (MIDI CC74 used in XG music to filter result sounding) scaling + * @param device Instance of the library + * @param fr_brightness 0 - disabled, 1 - enabled + * + * By default, brightness affects sound between 0 and 64. + * When this option is enabled, the range will use a full range from 0 up to 127. + */ extern void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_brightness); /*Enable or disable built-in loop (built-in loop supports 'loopStart' and 'loopEnd' tags to loop specific part)*/ @@ -291,28 +356,51 @@ extern int adl_openBankData(struct ADL_MIDIPlayer *device, const void *mem, unsi /* DEPRECATED */ extern const char *adl_emulatorName(); -/*Returns chip emulator name string*/ +/** + * @brief Returns chip emulator name string + * @param device Instance of the library + * @return Understandible name of current OPL3 emulator + */ extern const char *adl_chipEmulatorName(struct ADL_MIDIPlayer *device); +/** + * @brief List of available OPL3 emulators + */ enum ADL_Emulator { + /*! Nuked OPL3 v. 1.8 */ ADLMIDI_EMU_NUKED = 0, + /*! Nuked OPL3 v. 1.7.4 */ ADLMIDI_EMU_NUKED_174, + /*! DosBox */ ADLMIDI_EMU_DOSBOX, + /*! Count instrument on the level */ ADLMIDI_EMU_end }; -/* Switch the emulation core */ +/** + * @brief Switch the emulation core + * @param device Instance of the library + * @param emulator Type of emulator (ADL_Emulator) + * @return 0 on success, <0 when any error has occurred + */ extern int adl_switchEmulator(struct ADL_MIDIPlayer *device, int emulator); - +/** + * @brief Library version context + */ typedef struct { ADL_UInt16 major; ADL_UInt16 minor; ADL_UInt16 patch; } ADL_Version; -/*Run emulator with PCM rate to reduce CPU usage on slow devices. May decrease sounding accuracy.*/ +/** + * @brief Run emulator with PCM rate to reduce CPU usage on slow devices. May decrease sounding accuracy. + * @param device Instance of the library + * @param enabled 0 - disabled, 1 - enabled + * @return 0 on success, <0 when any error has occurred + */ extern int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled); /*Returns string which contains a version number*/ -- cgit v1.2.3 From 9c8d04d885946342d0ffd233418e7862b6ca990c Mon Sep 17 00:00:00 2001 From: Vitaly Novichkov Date: Wed, 4 Jul 2018 02:06:28 +0300 Subject: Continue public API documenting. Almost complete. --- include/adlmidi.h | 488 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 419 insertions(+), 69 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index e81894e..9c00ed6 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -24,6 +24,10 @@ #ifndef ADLMIDI_H #define ADLMIDI_H +/** + * @section Public API + */ + #ifdef __cplusplus extern "C" { #endif @@ -201,6 +205,10 @@ enum ADL_BankAccessFlags typedef struct ADL_Instrument ADL_Instrument; +/** + * @subsection Setup + */ + /** * @brief Preallocates a minimum number of bank slots. Returns the actual capacity * @param device Instance of the library @@ -337,23 +345,57 @@ extern void adl_setScaleModulators(struct ADL_MIDIPlayer *device, int smod); */ extern void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_brightness); -/*Enable or disable built-in loop (built-in loop supports 'loopStart' and 'loopEnd' tags to loop specific part)*/ +/** + * @brief Enable or disable built-in loop (built-in loop supports 'loopStart' and 'loopEnd' tags to loop specific part) + * @param device Instance of the library + * @param loopEn 0 - disabled, 1 - enabled + */ extern void adl_setLoopEnabled(struct ADL_MIDIPlayer *device, int loopEn); -/* !!!DEPRECATED!!! Enable or disable Logariphmic volume changer */ +/** + * @brief [DEPRECATED] Enable or disable Logariphmic volume changer + * @param device Instance of the library + * @param logvol 0 - disabled, 1 - enabled + * + * This function is deprecated. Suggested replacement: `adl_setVolumeRangeModel` with `ADLMIDI_VolumeModel_NativeOPL3` volume model value; + */ extern void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol); -/*Set different volume range model */ +/** + * @brief Set different volume range model + * @param device Instance of the library + * @param volumeModel Volume model type (ADLMIDI_VolumeModels) + */ extern void adl_setVolumeRangeModel(struct ADL_MIDIPlayer *device, int volumeModel); -/*Load WOPL bank file from File System. Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time.*/ +/** + * @brief Load WOPL bank file from File System + * @param device Instance of the library + * @param filePath Absolute or relative path to the WOPL bank file. UTF8 encoding is required, even on Windows. + * @return 0 on success, <0 when any error has occurred + * + * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. + */ extern int adl_openBankFile(struct ADL_MIDIPlayer *device, const char *filePath); -/*Load WOPL bank file from memory data*/ +/** + * @brief Load WOPL bank file from memory data + * @param device Instance of the library + * @param mem Pointer to memory block where is raw data of WOPL bank file is stored + * @param size Size of given memory block + * @return 0 on success, <0 when any error has occurred + * + * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. + */ extern int adl_openBankData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size); -/* DEPRECATED */ +/** + * @brief [DEPRECATED] Dummy function + * @return A string that contains a notice to use `adl_chipEmulatorName` instead of this function. + * + * This function is deprecated. Suggested replacement: `adl_chipEmulatorName` + */ extern const char *adl_emulatorName(); /** @@ -396,183 +438,491 @@ typedef struct { } ADL_Version; /** - * @brief Run emulator with PCM rate to reduce CPU usage on slow devices. May decrease sounding accuracy. + * @brief Run emulator with PCM rate to reduce CPU usage on slow devices. * @param device Instance of the library * @param enabled 0 - disabled, 1 - enabled * @return 0 on success, <0 when any error has occurred + * + * May decrease sounding accuracy on some chip emulators. */ extern int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled); -/*Returns string which contains a version number*/ +/** + * @brief Set 4-bit device identifier. Used by the SysEx processor. + * @param device Instance of the library + * @param id 4-bit device identifier + * @return 0 on success, <0 when any error has occurred + */ +extern int adl_setDeviceIdentifier(struct ADL_MIDIPlayer *device, unsigned id); + +/** + * @subsection Library information + */ + +/** + * @brief Returns string which contains a version number + * @return String which contains a version of the library + */ extern const char *adl_linkedLibraryVersion(); -/*Returns structure which contains a version number of library */ +/** + * @brief Returns structure which contains a version number of library + * @return Library version context structure which contains version number of the library + */ extern const ADL_Version *adl_linkedVersion(); -/*Returns string which contains last error message of initialization*/ + +/** + * @subsection Error info + */ + +/** + * @brief Returns string which contains last error message of initialization + * @return String with error message related to library initialization + * + * Don't use this function to get info on any function except of `adl_init`! + */ extern const char *adl_errorString(); -/*Returns string which contains last error message on specific device*/ +/** + * @brief Returns string which contains last error message on specific device + * @param device Instance of the library + * @return String with error message related to last function call returned non-zero value. + */ extern const char *adl_errorInfo(struct ADL_MIDIPlayer *device); -/*Initialize ADLMIDI Player device*/ +/** + * @subsection Library initialization + */ + +/** + * @brief Initialize ADLMIDI Player device + * @param Output sample rate + * @return Instance of the library. If NULL was returned, check the `adl_errorString` message for more info. + * + * Tip 1: You can initialize multiple instances and run them in parallel + * Tip 2: Library is NOT thread-save, therefore don't use same instance in different threads or use mutexes + * Tip 3: Changing of sample rate on the fly is not supported. Re-create the instance again. + */ extern struct ADL_MIDIPlayer *adl_init(long sample_rate); -/*Set 4-bit device identifier*/ -extern int adl_setDeviceIdentifier(struct ADL_MIDIPlayer *device, unsigned id); +/** + * @brief Close and delete ADLMIDI device + * @param device Instance of the library + */ +extern void adl_close(struct ADL_MIDIPlayer *device); -/*Load MIDI file from File System*/ + +/** + * @subsection MIDI Sequencer + */ + +/** + * @brief Load MIDI (or any other supported format) file from File System + * @param device Instance of the library + * @param filePath Absolute or relative path to the music file. UTF8 encoding is required, even on Windows. + * @return 0 on success, <0 when any error has occurred + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern int adl_openFile(struct ADL_MIDIPlayer *device, const char *filePath); -/*Load MIDI file from memory data*/ +/** + * @brief Load MIDI (or any other supported format) file from memory data + * @param device Instance of the library + * @param mem Pointer to memory block where is raw data of music file is stored + * @param size Size of given memory block + * @return 0 on success, <0 when any error has occurred + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern int adl_openData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size); -/*Resets MIDI player*/ +/** + * @brief Resets MIDI player + * @param device Instance of the library + */ extern void adl_reset(struct ADL_MIDIPlayer *device); -/*Get total time length of current song*/ +/** + * @brief Get total time length of current song + * @param device Instance of the library + * @return Total song length in seconds + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern double adl_totalTimeLength(struct ADL_MIDIPlayer *device); -/*Get loop start time if presented. -1 means MIDI file has no loop points */ +/** + * @brief Get loop start time if presented. + * @param device Instance of the library + * @return Time position in seconds of loop start point, or -1 when file has no loop points + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern double adl_loopStartTime(struct ADL_MIDIPlayer *device); -/*Get loop end time if presented. -1 means MIDI file has no loop points */ +/** + * @brief Get loop endtime if presented. + * @param device Instance of the library + * @return Time position in seconds of loop end point, or -1 when file has no loop points + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern double adl_loopEndTime(struct ADL_MIDIPlayer *device); -/*Get current time position in seconds*/ +/** + * @brief Get current time position in seconds + * @param device Instance of the library + * @return Current time position in seconds + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern double adl_positionTell(struct ADL_MIDIPlayer *device); -/*Jump to absolute time position in seconds*/ +/** + * @brief Jump to absolute time position in seconds + * @param device Instance of the library + * @param seconds Destination time position in seconds to seek + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern void adl_positionSeek(struct ADL_MIDIPlayer *device, double seconds); -/*Reset MIDI track position to begin */ +/** + * @brief Reset MIDI track position to begin + * @param device Instance of the library + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern void adl_positionRewind(struct ADL_MIDIPlayer *device); -/*Set tempo multiplier: 1.0 - original tempo, >1 - play faster, <1 - play slower */ +/** + * @brief Set tempo multiplier + * @param device Instance of the library + * @param tempo Tempo multiplier value: 1.0 - original tempo, >1 - play faster, <1 - play slower + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern void adl_setTempo(struct ADL_MIDIPlayer *device, double tempo); -/*Get a textual description of the channel state. For display only.*/ -extern int adl_describeChannels(struct ADL_MIDIPlayer *device, char *text, char *attr, size_t size); - -/*Close and delete ADLMIDI device*/ -extern void adl_close(struct ADL_MIDIPlayer *device); +/** + * @brief Returns 1 if music position has reached end + * @param device Instance of the library + * @return 1 when end of sing has been reached, otherwise, 0 will be returned. <0 is returned on any error + */ +extern int adl_atEnd(struct ADL_MIDIPlayer *device); -/**META**/ +/** + * @subsection Meta-Tags + */ -/*Returns string which contains a music title*/ +/** + * @brief Returns string which contains a music title + * @param device Instance of the library + * @return A string that contains music title + */ extern const char *adl_metaMusicTitle(struct ADL_MIDIPlayer *device); -/*Returns string which contains a copyright string*/ +/** + * @brief Returns string which contains a copyright string* + * @param device Instance of the library + * @return A string that contains copyright notice, otherwise NULL + */ extern const char *adl_metaMusicCopyright(struct ADL_MIDIPlayer *device); -/*Returns count of available track titles: NOTE: there are CAN'T be associated with channel in any of event or note hooks */ +/** + * @brief Returns count of available track titles + * @param device Instance of the library + * @return Count of available MIDI tracks, otherwise NULL + * + * NOTE: There are CAN'T be associated with channel in any of event or note hooks + */ extern size_t adl_metaTrackTitleCount(struct ADL_MIDIPlayer *device); -/*Get track title by index*/ +/** + * @brief Get track title by index + * @param device Instance of the library + * @param index Index of the track to retreive the title + * @return A string that contains track title, otherwise NULL. + */ extern const char *adl_metaTrackTitle(struct ADL_MIDIPlayer *device, size_t index); +/** + * @brief MIDI Marker structure + */ struct Adl_MarkerEntry { + /*! MIDI Marker title */ const char *label; + /*! Absolute time position of the marker in seconds */ double pos_time; + /*! Absolute time position of the marker in MIDI ticks */ unsigned long pos_ticks; }; -/*Returns count of available markers*/ +/** + * @brief Returns count of available markers + * @param device Instance of the library + * @return Count of available MIDI markers + */ extern size_t adl_metaMarkerCount(struct ADL_MIDIPlayer *device); -/*Returns the marker entry*/ +/** + * @brief Returns the marker entry + * @param device Instance of the library + * @param index Index of the marker to retreive it. + * @return MIDI Marker description structure. + */ extern struct Adl_MarkerEntry adl_metaMarker(struct ADL_MIDIPlayer *device, size_t index); -/*Take a sample buffer and iterate MIDI timers */ +/** + * @subsection Output generation + */ + +/** + * @brief Take a sample buffer and iterate MIDI timers + * @param device Instance of the library + * @param sampleCount Count of samples (not frames!) + * @param out Pointer to output with 16-bit stereo PCM output + * @return Count of given samples, otherwise, 0 or when catching an error while playing + * + * Don't use count of frames, use instead count of samples. One frame is two samples. + */ extern int adl_play(struct ADL_MIDIPlayer *device, int sampleCount, short *out); -/*Take a sample buffer and iterate MIDI timers */ +/** + * @brief Take a sample buffer and iterate MIDI timers + * @param device Instance of the library + * @param sampleCount + * @param left + * @param right + * @param format + * @return + * + * Available when library is built with built-in MIDI Sequencer support. + */ extern int adl_playFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format); -/*Generate audio output from chip emulators without iteration of MIDI timers.*/ +/** + * @brief Generate audio output from chip emulators without iteration of MIDI timers + * @param device Instance of the library + * @param sampleCount + * @param out + * @return + */ extern int adl_generate(struct ADL_MIDIPlayer *device, int sampleCount, short *out); -/*Generate audio output from chip emulators without iteration of MIDI timers.*/ +/** + * @brief Generate audio output from chip emulators without iteration of MIDI timers + * @param device Instance of the library + * @param sampleCount + * @param left + * @param right + * @param format + * @return + */ extern int adl_generateFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format); /** * @brief Periodic tick handler. - * @param device - * @param seconds seconds since last call - * @param granularity don't expect intervals smaller than this, in seconds - * @return desired number of seconds until next call + * @param device Instance of the library + * @param seconds Previous delay. On a first moment, pass the `0.0` + * @param granularity Minimal size of one MIDI tick in seconds. + * @return desired number of seconds until next call. Pass this value into `seconds` field in next time * - * Use it for Hardware OPL3 mode or when you want to process events differently from adl_play() function. - * DON'T USE IT TOGETHER WITH adl_play()!!! + * Notice: The function is provided to use it with Hardware OPL3 mode or for the purpose to iterate + * MIDI playback without of sound generation. + * + * DON'T USE IT TOGETHER WITH adl_play() and adl_playFormat() calls + * as there are all using this function internally!!! */ extern double adl_tickEvents(struct ADL_MIDIPlayer *device, double seconds, double granuality); -/*Returns 1 if music position has reached end*/ -extern int adl_atEnd(struct ADL_MIDIPlayer *device); -/**RealTime**/ +/** + * @subsection RealTime MIDI + */ -/*Force Off all notes on all channels*/ +/** + * @brief Force Off all notes on all channels + * @param device Instance of the library + */ extern void adl_panic(struct ADL_MIDIPlayer *device); -/*Reset states of all controllers on all MIDI channels*/ +/** + * @brief Reset states of all controllers on all MIDI channels + * @param device Instance of the library + */ extern void adl_rt_resetState(struct ADL_MIDIPlayer *device); -/*Turn specific MIDI note ON*/ +/** + * @brief Turn specific MIDI note ON + * @param device Instance of the library + * @param channel + * @param note + * @param velocity + * @return + */ extern int adl_rt_noteOn(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 velocity); -/*Turn specific MIDI note OFF*/ +/** + * @brief Turn specific MIDI note OFF + * @param device Instance of the library + * @param channel + * @param note + */ extern void adl_rt_noteOff(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note); -/*Set note after-touch*/ +/** + * @brief Set note after-touch + * @param device Instance of the library + * @param channel + * @param note + * @param atVal + */ extern void adl_rt_noteAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 atVal); -/*Set channel after-touch*/ + +/** + * @brief Set channel after-touch + * @param device Instance of the library + * @param channel + * @param atVal + */ extern void adl_rt_channelAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 atVal); -/*Apply controller change*/ +/** + * @brief Apply controller change + * @param device Instance of the library + * @param channel + * @param type + * @param value + */ extern void adl_rt_controllerChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 type, ADL_UInt8 value); -/*Apply patch change*/ +/** + * @brief Apply patch change + * @param device Instance of the library + * @param channel + * @param patch + */ extern void adl_rt_patchChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 patch); -/*Apply pitch bend change*/ +/** + * @brief Apply pitch bend change + * @param device Instance of the library + * @param channel + * @param pitch + */ extern void adl_rt_pitchBend(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt16 pitch); -/*Apply pitch bend change*/ + +/** + * @brief Apply pitch bend change + * @param device Instance of the library + * @param channel + * @param msb + * @param lsb + */ extern void adl_rt_pitchBendML(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb, ADL_UInt8 lsb); -/*Change LSB of the bank*/ +/** + * @brief Change LSB of the bank number + * @param device Instance of the library + * @param channel + * @param lsb + */ extern void adl_rt_bankChangeLSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 lsb); -/*Change MSB of the bank*/ + +/** + * @brief Change MSB of the bank + * @param device Instance of the library + * @param channel + * @param msb + */ extern void adl_rt_bankChangeMSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb); -/*Change bank by absolute signed value*/ + +/** + * @brief Change bank by absolute signed value + * @param device Instance of the library + * @param channel + * @param bank + */ + extern void adl_rt_bankChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_SInt16 bank); -/*Perform a system exclusive message*/ +/** + * @brief Perform a system exclusive message + * @param device Instance of the library + * @param msg + * @param size + * @return + */ extern int adl_rt_systemExclusive(struct ADL_MIDIPlayer *device, const ADL_UInt8 *msg, size_t size); - -/**Hooks**/ +/** + * @subsection Hooks and debugging + */ typedef void (*ADL_RawEventHook)(void *userdata, ADL_UInt8 type, ADL_UInt8 subtype, ADL_UInt8 channel, const ADL_UInt8 *data, size_t len); typedef void (*ADL_NoteHook)(void *userdata, int adlchn, int note, int ins, int pressure, double bend); typedef void (*ADL_DebugMessageHook)(void *userdata, const char *fmt, ...); -/* Set raw MIDI event hook */ +/** + * @brief Set raw MIDI event hook + * @param device Instance of the library + * @param rawEventHook + * @param userData + */ extern void adl_setRawEventHook(struct ADL_MIDIPlayer *device, ADL_RawEventHook rawEventHook, void *userData); -/* Set note hook */ +/** + * @brief Set note hook + * @param device Instance of the library + * @param noteHook + * @param userData + */ extern void adl_setNoteHook(struct ADL_MIDIPlayer *device, ADL_NoteHook noteHook, void *userData); -/* Set debug message hook */ +/** + * @brief Set debug message hook + * @param device Instance of the library + * @param debugMessageHook + * @param userData + */ extern void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMessageHook debugMessageHook, void *userData); +/** + * @brief Get a textual description of the channel state. For display only. + * @param device Instance of the library + * @param text Destination char buffer for channel usage state. Every entry is assigned to the chip channel. + * @param attr Destination char buffer for additional attributes like MIDI channel number that uses this chip channel. + * @param size Size of given buffers (both text and attr are must have same size!) + * @return 0 on success, <0 when any error has occurred + * + * Every character in the `text` buffer means the type of usage: + * `-` - channel is unused (free) + * `+` - channel is used by two-operator voice + * `#` - channel is used by four-operator voice + * `@` - channel is used to play automatical arpeggio on chip channels overflow + * `r` - rhythm-mode channel note + * + * The `attr` field receives the MIDI channel from which the chip channel is used. + * To get the valid MIDI channel you will need to apply the & 0x0F mask to every value. + */ +extern int adl_describeChannels(struct ADL_MIDIPlayer *device, char *text, char *attr, size_t size); + -/** Instrument structures **/ +/** + * @subsection Instrument structures + */ + +/** + * @brief Version of the instrument data format + */ enum { ADLMIDI_InstrumentVersion = 0, -- cgit v1.2.3 From efe169c36a145696e64892d53d8c90556a9e7b91 Mon Sep 17 00:00:00 2001 From: Vitaly Novichkov Date: Wed, 4 Jul 2018 03:42:23 +0300 Subject: Continue documenting, and apply some minor fixes on other files --- include/adlmidi.h | 398 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 252 insertions(+), 146 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index 9c00ed6..960ba54 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -24,10 +24,6 @@ #ifndef ADLMIDI_H #define ADLMIDI_H -/** - * @section Public API - */ - #ifdef __cplusplus extern "C" { #endif @@ -59,6 +55,17 @@ typedef char ADL_SInt8; typedef short ADL_SInt16; #endif +/* == Deprecated function markers == */ + +#ifdef __GNUC__ +#define DEPRECATED(func) func __attribute__ ((deprecated)) +#elif defined(_MSC_VER) +#define DEPRECATED(func) __declspec(deprecated) func +#else +#define DEPRECATED(func) func +#endif + + /** * @brief Volume scaling models */ @@ -135,7 +142,7 @@ struct ADL_MIDIPlayer #define adl_setNumCards adl_setNumChips /** - * @brief Sets number of emulated chips (from 1 to 100). Emulation of multiple chips exchanges polyphony limits + * @brief Sets number of emulated chips (from 1 to 100). Emulation of multiple chips extends polyphony limits * @param device Instance of the library * @param numChips Count of virtual chips to emulate * @return 0 on success, <0 when any error has occurred @@ -151,11 +158,12 @@ extern int adl_getNumChips(struct ADL_MIDIPlayer *device); /** * @brief Sets a number of the patches bank from 0 to N banks. + * + * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. + * * @param device Instance of the library * @param bank Number of embedded bank * @return 0 on success, <0 when any error has occurred - * - * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. */ extern int adl_setBank(struct ADL_MIDIPlayer *device, int bank); @@ -205,9 +213,10 @@ enum ADL_BankAccessFlags typedef struct ADL_Instrument ADL_Instrument; -/** - * @subsection Setup - */ + + + +/* ======== Setup ======== */ /** * @brief Preallocates a minimum number of bank slots. Returns the actual capacity @@ -287,14 +296,15 @@ extern int adl_loadEmbeddedBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank, i /** * @brief Sets number of 4-operator channels between all chips - * @param device Instance of the library - * @param ops4 Count of four-op channels to allocate between all emulating chips - * @return 0 on success, <0 when any error has occurred * * By default, it is automatically re-calculating every bank change. * If you want to specify custom number of four operator channels, * please call this function after bank change (adl_setBank() or adl_openBank()), * otherwise, value will be overwritten by auto-calculated. + * + * @param device Instance of the library + * @param ops4 Count of four-op channels to allocate between all emulating chips + * @return 0 on success, <0 when any error has occurred */ extern int adl_setNumFourOpsChn(struct ADL_MIDIPlayer *device, int ops4); @@ -307,10 +317,11 @@ extern int adl_getNumFourOpsChn(struct ADL_MIDIPlayer *device); /** * @brief Override Enable(1) or Disable(0) AdLib percussion mode. -1 - use bank default AdLib percussion mode + * + * This function forces rhythm-mode on any bank. The result will work glitchy. + * * @param device Instance of the library * @param percmod 0 - disabled, 1 - enabled - * - * This function forces rhythm-mode on any bank. The result will wrork glitchy. */ extern void adl_setPercMode(struct ADL_MIDIPlayer *device, int percmod); @@ -324,24 +335,25 @@ extern void adl_setHVibrato(struct ADL_MIDIPlayer *device, int hvibro); /** * @brief Override Enable(1) or Disable(0) deep tremolo state. -1 - use bank default tremolo state * @param device Instance of the library - * @param hvibro 0 - disabled, 1 - enabled + * @param htremo 0 - disabled, 1 - enabled */ extern void adl_setHTremolo(struct ADL_MIDIPlayer *device, int htremo); /** * @brief Override Enable(1) or Disable(0) scaling of modulator volumes. -1 - use bank default scaling of modulator volumes * @param device Instance of the library - * @param hvibro 0 - disabled, 1 - enabled + * @param smod 0 - disabled, 1 - enabled */ extern void adl_setScaleModulators(struct ADL_MIDIPlayer *device, int smod); /** * @brief Enable(1) or Disable(0) full-range brightness (MIDI CC74 used in XG music to filter result sounding) scaling - * @param device Instance of the library - * @param fr_brightness 0 - disabled, 1 - enabled * * By default, brightness affects sound between 0 and 64. - * When this option is enabled, the range will use a full range from 0 up to 127. + * When this option is enabled, the brightness will use full range from 0 up to 127. + * + * @param device Instance of the library + * @param fr_brightness 0 - disabled, 1 - enabled */ extern void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_brightness); @@ -353,55 +365,56 @@ extern void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_bri extern void adl_setLoopEnabled(struct ADL_MIDIPlayer *device, int loopEn); /** - * @brief [DEPRECATED] Enable or disable Logariphmic volume changer - * @param device Instance of the library - * @param logvol 0 - disabled, 1 - enabled + * @brief [DEPRECATED] Enable or disable Logarithmic volume changer * * This function is deprecated. Suggested replacement: `adl_setVolumeRangeModel` with `ADLMIDI_VolumeModel_NativeOPL3` volume model value; */ -extern void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol); +DEPRECATED(extern void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol)); /** * @brief Set different volume range model * @param device Instance of the library - * @param volumeModel Volume model type (ADLMIDI_VolumeModels) + * @param volumeModel Volume model type (#ADLMIDI_VolumeModels) */ extern void adl_setVolumeRangeModel(struct ADL_MIDIPlayer *device, int volumeModel); /** * @brief Load WOPL bank file from File System + * + * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. + * * @param device Instance of the library * @param filePath Absolute or relative path to the WOPL bank file. UTF8 encoding is required, even on Windows. * @return 0 on success, <0 when any error has occurred - * - * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. */ extern int adl_openBankFile(struct ADL_MIDIPlayer *device, const char *filePath); /** * @brief Load WOPL bank file from memory data + * + * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. + * * @param device Instance of the library * @param mem Pointer to memory block where is raw data of WOPL bank file is stored * @param size Size of given memory block * @return 0 on success, <0 when any error has occurred - * - * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. */ extern int adl_openBankData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size); /** * @brief [DEPRECATED] Dummy function - * @return A string that contains a notice to use `adl_chipEmulatorName` instead of this function. * * This function is deprecated. Suggested replacement: `adl_chipEmulatorName` + * + * @return A string that contains a notice to use `adl_chipEmulatorName` instead of this function. */ -extern const char *adl_emulatorName(); +DEPRECATED(extern const char *adl_emulatorName()); /** * @brief Returns chip emulator name string * @param device Instance of the library - * @return Understandible name of current OPL3 emulator + * @return Understandable name of current OPL3 emulator */ extern const char *adl_chipEmulatorName(struct ADL_MIDIPlayer *device); @@ -423,7 +436,7 @@ enum ADL_Emulator /** * @brief Switch the emulation core * @param device Instance of the library - * @param emulator Type of emulator (ADL_Emulator) + * @param emulator Type of emulator (#ADL_Emulator) * @return 0 on success, <0 when any error has occurred */ extern int adl_switchEmulator(struct ADL_MIDIPlayer *device, int emulator); @@ -439,11 +452,12 @@ typedef struct { /** * @brief Run emulator with PCM rate to reduce CPU usage on slow devices. + * + * May decrease sounding accuracy on some chip emulators. + * * @param device Instance of the library * @param enabled 0 - disabled, 1 - enabled * @return 0 on success, <0 when any error has occurred - * - * May decrease sounding accuracy on some chip emulators. */ extern int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled); @@ -456,7 +470,7 @@ extern int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled); extern int adl_setDeviceIdentifier(struct ADL_MIDIPlayer *device, unsigned id); /** - * @subsection Library information + * @section Information */ /** @@ -472,15 +486,15 @@ extern const char *adl_linkedLibraryVersion(); extern const ADL_Version *adl_linkedVersion(); -/** - * @subsection Error info - */ +/* ======== Error Info ======== */ /** * @brief Returns string which contains last error message of initialization - * @return String with error message related to library initialization * * Don't use this function to get info on any function except of `adl_init`! + * Use `adl_errorInfo()` to get error information while workflow + * + * @return String with error message related to library initialization */ extern const char *adl_errorString(); @@ -491,18 +505,19 @@ extern const char *adl_errorString(); */ extern const char *adl_errorInfo(struct ADL_MIDIPlayer *device); -/** - * @subsection Library initialization - */ + + +/* ======== Initialization ======== */ /** * @brief Initialize ADLMIDI Player device - * @param Output sample rate - * @return Instance of the library. If NULL was returned, check the `adl_errorString` message for more info. * * Tip 1: You can initialize multiple instances and run them in parallel - * Tip 2: Library is NOT thread-save, therefore don't use same instance in different threads or use mutexes + * Tip 2: Library is NOT thread-safe, therefore don't use same instance in different threads or use mutexes * Tip 3: Changing of sample rate on the fly is not supported. Re-create the instance again. + * + * @param sample_rate Output sample rate + * @return Instance of the library. If NULL was returned, check the `adl_errorString` message for more info. */ extern struct ADL_MIDIPlayer *adl_init(long sample_rate); @@ -513,96 +528,104 @@ extern struct ADL_MIDIPlayer *adl_init(long sample_rate); extern void adl_close(struct ADL_MIDIPlayer *device); -/** - * @subsection MIDI Sequencer - */ + +/* ======== MIDI Sequencer ======== */ /** * @brief Load MIDI (or any other supported format) file from File System + * + * Available when library is built with built-in MIDI Sequencer support. + * * @param device Instance of the library * @param filePath Absolute or relative path to the music file. UTF8 encoding is required, even on Windows. * @return 0 on success, <0 when any error has occurred - * - * Available when library is built with built-in MIDI Sequencer support. */ extern int adl_openFile(struct ADL_MIDIPlayer *device, const char *filePath); /** * @brief Load MIDI (or any other supported format) file from memory data + * + * Available when library is built with built-in MIDI Sequencer support. + * * @param device Instance of the library * @param mem Pointer to memory block where is raw data of music file is stored * @param size Size of given memory block * @return 0 on success, <0 when any error has occurred - * - * Available when library is built with built-in MIDI Sequencer support. */ extern int adl_openData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size); /** - * @brief Resets MIDI player + * @brief Resets MIDI player (per-channel setup) into initial state * @param device Instance of the library */ extern void adl_reset(struct ADL_MIDIPlayer *device); /** * @brief Get total time length of current song - * @param device Instance of the library - * @return Total song length in seconds * * Available when library is built with built-in MIDI Sequencer support. + * + * @param device Instance of the library + * @return Total song length in seconds */ extern double adl_totalTimeLength(struct ADL_MIDIPlayer *device); /** * @brief Get loop start time if presented. - * @param device Instance of the library - * @return Time position in seconds of loop start point, or -1 when file has no loop points * * Available when library is built with built-in MIDI Sequencer support. + * + * @param device Instance of the library + * @return Time position in seconds of loop start point, or -1 when file has no loop points */ extern double adl_loopStartTime(struct ADL_MIDIPlayer *device); /** * @brief Get loop endtime if presented. - * @param device Instance of the library - * @return Time position in seconds of loop end point, or -1 when file has no loop points * * Available when library is built with built-in MIDI Sequencer support. + * + * @param device Instance of the library + * @return Time position in seconds of loop end point, or -1 when file has no loop points */ extern double adl_loopEndTime(struct ADL_MIDIPlayer *device); /** * @brief Get current time position in seconds - * @param device Instance of the library - * @return Current time position in seconds * * Available when library is built with built-in MIDI Sequencer support. + * + * @param device Instance of the library + * @return Current time position in seconds */ extern double adl_positionTell(struct ADL_MIDIPlayer *device); /** * @brief Jump to absolute time position in seconds - * @param device Instance of the library - * @param seconds Destination time position in seconds to seek * * Available when library is built with built-in MIDI Sequencer support. + * + * @param device Instance of the library + * @param seconds Destination time position in seconds to seek */ extern void adl_positionSeek(struct ADL_MIDIPlayer *device, double seconds); /** * @brief Reset MIDI track position to begin - * @param device Instance of the library * * Available when library is built with built-in MIDI Sequencer support. + * + * @param device Instance of the library */ extern void adl_positionRewind(struct ADL_MIDIPlayer *device); /** * @brief Set tempo multiplier - * @param device Instance of the library - * @param tempo Tempo multiplier value: 1.0 - original tempo, >1 - play faster, <1 - play slower * * Available when library is built with built-in MIDI Sequencer support. + * + * @param device Instance of the library + * @param tempo Tempo multiplier value: 1.0 - original tempo, >1 - play faster, <1 - play slower */ extern void adl_setTempo(struct ADL_MIDIPlayer *device, double tempo); @@ -615,9 +638,8 @@ extern int adl_atEnd(struct ADL_MIDIPlayer *device); -/** - * @subsection Meta-Tags - */ + +/* ======== Meta-Tags ======== */ /** * @brief Returns string which contains a music title @@ -635,10 +657,11 @@ extern const char *adl_metaMusicCopyright(struct ADL_MIDIPlayer *device); /** * @brief Returns count of available track titles - * @param device Instance of the library - * @return Count of available MIDI tracks, otherwise NULL * * NOTE: There are CAN'T be associated with channel in any of event or note hooks + * + * @param device Instance of the library + * @return Count of available MIDI tracks, otherwise NULL */ extern size_t adl_metaTrackTitleCount(struct ADL_MIDIPlayer *device); @@ -679,73 +702,108 @@ extern size_t adl_metaMarkerCount(struct ADL_MIDIPlayer *device); extern struct Adl_MarkerEntry adl_metaMarker(struct ADL_MIDIPlayer *device, size_t index); -/** - * @subsection Output generation - */ + + +/* ======== Audio output Generation ======== */ /** - * @brief Take a sample buffer and iterate MIDI timers + * @brief Generate PCM signed 16-bit stereo audio output and iterate MIDI timers + * + * Use this function when you are playing MIDI file loaded by `adl_openFile` or by `adl_openData` + * with using of built-in MIDI sequencer. + * + * Don't use count of frames, use instead count of samples. One frame is two samples. + * So, for example, if you want to take 10 frames, you must to request amount of 20 samples! + * + * Available when library is built with built-in MIDI Sequencer support. + * * @param device Instance of the library * @param sampleCount Count of samples (not frames!) * @param out Pointer to output with 16-bit stereo PCM output * @return Count of given samples, otherwise, 0 or when catching an error while playing - * - * Don't use count of frames, use instead count of samples. One frame is two samples. */ extern int adl_play(struct ADL_MIDIPlayer *device, int sampleCount, short *out); /** - * @brief Take a sample buffer and iterate MIDI timers - * @param device Instance of the library - * @param sampleCount - * @param left - * @param right - * @param format - * @return + * @brief Generate PCM stereo audio output in sample format declared by given context and iterate MIDI timers + * + * Use this function when you are playing MIDI file loaded by `adl_openFile` or by `adl_openData` + * with using of built-in MIDI sequencer. + * + * Don't use count of frames, use instead count of samples. One frame is two samples. + * So, for example, if you want to take 10 frames, you must to request amount of 20 samples! * * Available when library is built with built-in MIDI Sequencer support. + * + * @param device Instance of the library + * @param sampleCount Count of samples (not frames!) + * @param left Left channel buffer output (Must be casted into bytes array) + * @param right Right channel buffer output (Must be casted into bytes array) + * @param format Destination PCM format format context + * @return Count of given samples, otherwise, 0 or when catching an error while playing */ extern int adl_playFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format); /** - * @brief Generate audio output from chip emulators without iteration of MIDI timers + * @brief Generate PCM signed 16-bit stereo audio output without iteration of MIDI timers + * + * Use this function when you are using library as Real-Time MIDI synthesizer or with + * an external MIDI sequencer. You must to request the amount of samples which is equal + * to the delta between of MIDI event rows. One MIDI row is a group of MIDI events + * are having zero delta/delay between each other. When you are receiving events in + * real time, request the minimal possible delay value. + * + * Don't use count of frames, use instead count of samples. One frame is two samples. + * So, for example, if you want to take 10 frames, you must to request amount of 20 samples! + * * @param device Instance of the library * @param sampleCount - * @param out - * @return + * @param out Pointer to output with 16-bit stereo PCM output + * @return Count of given samples, otherwise, 0 or when catching an error while playing */ extern int adl_generate(struct ADL_MIDIPlayer *device, int sampleCount, short *out); /** - * @brief Generate audio output from chip emulators without iteration of MIDI timers + * @brief Generate PCM stereo audio output in sample format declared by given context without iteration of MIDI timers + * + * Use this function when you are using library as Real-Time MIDI synthesizer or with + * an external MIDI sequencer. You must to request the amount of samples which is equal + * to the delta between of MIDI event rows. One MIDI row is a group of MIDI events + * are having zero delta/delay between each other. When you are receiving events in + * real time, request the minimal possible delay value. + * + * Don't use count of frames, use instead count of samples. One frame is two samples. + * So, for example, if you want to take 10 frames, you must to request amount of 20 samples! + * * @param device Instance of the library * @param sampleCount - * @param left - * @param right - * @param format - * @return + * @param left Left channel buffer output (Must be casted into bytes array) + * @param right Right channel buffer output (Must be casted into bytes array) + * @param format Destination PCM format format context + * @return Count of given samples, otherwise, 0 or when catching an error while playing */ extern int adl_generateFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format); /** * @brief Periodic tick handler. - * @param device Instance of the library - * @param seconds Previous delay. On a first moment, pass the `0.0` - * @param granularity Minimal size of one MIDI tick in seconds. - * @return desired number of seconds until next call. Pass this value into `seconds` field in next time * * Notice: The function is provided to use it with Hardware OPL3 mode or for the purpose to iterate * MIDI playback without of sound generation. * * DON'T USE IT TOGETHER WITH adl_play() and adl_playFormat() calls * as there are all using this function internally!!! + * + * @param device Instance of the library + * @param seconds Previous delay. On a first moment, pass the `0.0` + * @param granulality Minimal size of one MIDI tick in seconds. + * @return desired number of seconds until next call. Pass this value into `seconds` field in next time */ -extern double adl_tickEvents(struct ADL_MIDIPlayer *device, double seconds, double granuality); +extern double adl_tickEvents(struct ADL_MIDIPlayer *device, double seconds, double granulality); -/** - * @subsection RealTime MIDI - */ + + +/* ======== Real-Time MIDI ======== */ /** * @brief Force Off all notes on all channels @@ -762,93 +820,93 @@ extern void adl_rt_resetState(struct ADL_MIDIPlayer *device); /** * @brief Turn specific MIDI note ON * @param device Instance of the library - * @param channel - * @param note - * @param velocity - * @return + * @param channel Target MIDI channel [Between 0 and 16] + * @param note Note number to on [Between 0 and 127] + * @param velocity Velocity level [Between 0 and 127] + * @return 1 when note was successfully started, 0 when note was rejected by any reason. */ extern int adl_rt_noteOn(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 velocity); /** * @brief Turn specific MIDI note OFF * @param device Instance of the library - * @param channel - * @param note + * @param channel Target MIDI channel [Between 0 and 16] + * @param note Note number to off [Between 0 and 127] */ extern void adl_rt_noteOff(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note); /** * @brief Set note after-touch * @param device Instance of the library - * @param channel - * @param note - * @param atVal + * @param channel Target MIDI channel [Between 0 and 16] + * @param note Note number to affect by aftertouch event [Between 0 and 127] + * @param atVal After-Touch value [Between 0 and 127] */ extern void adl_rt_noteAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 atVal); /** * @brief Set channel after-touch * @param device Instance of the library - * @param channel - * @param atVal + * @param channel Target MIDI channel [Between 0 and 16] + * @param atVal After-Touch level [Between 0 and 127] */ extern void adl_rt_channelAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 atVal); /** * @brief Apply controller change * @param device Instance of the library - * @param channel - * @param type - * @param value + * @param channel Target MIDI channel [Between 0 and 16] + * @param type Type of the controller [Between 0 and 255] + * @param value Value of the controller event [Between 0 and 127] */ extern void adl_rt_controllerChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 type, ADL_UInt8 value); /** * @brief Apply patch change * @param device Instance of the library - * @param channel - * @param patch + * @param channel Target MIDI channel [Between 0 and 16] + * @param patch Patch number [Between 0 and 127] */ extern void adl_rt_patchChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 patch); /** * @brief Apply pitch bend change * @param device Instance of the library - * @param channel - * @param pitch + * @param channel Target MIDI channel [Between 0 and 16] + * @param pitch 24-bit pitch bend value */ extern void adl_rt_pitchBend(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt16 pitch); /** * @brief Apply pitch bend change * @param device Instance of the library - * @param channel - * @param msb - * @param lsb + * @param channel Target MIDI channel [Between 0 and 16] + * @param msb MSB part of 24-bit pitch bend value + * @param lsb LSB part of 24-bit pitch bend value */ extern void adl_rt_pitchBendML(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb, ADL_UInt8 lsb); /** - * @brief Change LSB of the bank number + * @brief Change LSB of the bank number (Alias to CC-32 event) * @param device Instance of the library - * @param channel - * @param lsb + * @param channel Target MIDI channel [Between 0 and 16] + * @param lsb LSB value of the MIDI bank number */ extern void adl_rt_bankChangeLSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 lsb); /** - * @brief Change MSB of the bank + * @brief Change MSB of the bank (Alias to CC-0 event) * @param device Instance of the library - * @param channel - * @param msb + * @param channel Target MIDI channel [Between 0 and 16] + * @param msb MSB value of the MIDI bank number */ extern void adl_rt_bankChangeMSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb); /** * @brief Change bank by absolute signed value * @param device Instance of the library - * @param channel - * @param bank + * @param channel Target MIDI channel [Between 0 and 16] + * @param bank Bank number as concoctated signed 16-bit value of MSB and LSB parts. */ extern void adl_rt_bankChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_SInt16 bank); @@ -856,41 +914,66 @@ extern void adl_rt_bankChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, /** * @brief Perform a system exclusive message * @param device Instance of the library - * @param msg - * @param size - * @return + * @param msg Raw SysEx message buffer (must begin with 0xF0 and end with 0xF7) + * @param size Size of given SysEx message buffer + * @return 1 when SysEx message was successfully processed, 0 when SysEx message was rejected by any reason */ extern int adl_rt_systemExclusive(struct ADL_MIDIPlayer *device, const ADL_UInt8 *msg, size_t size); + + + +/* ======== Hooks and debugging ======== */ + /** - * @subsection Hooks and debugging + * @brief Raw event callback + * @param userdata Pointer to user data (usually, context of someting) + * @param type MIDI event type + * @param subtype MIDI event sub-type (special events only) + * @param channel MIDI channel + * @param data Raw event data + * @param len Length of event data */ - typedef void (*ADL_RawEventHook)(void *userdata, ADL_UInt8 type, ADL_UInt8 subtype, ADL_UInt8 channel, const ADL_UInt8 *data, size_t len); + +/** + * @brief Note on/off callback + * @param userdata Pointer to user data (usually, context of someting) + * @param adlchn Chip channel where note was played + * @param note Note number [between 0 and 127] + * @param pressure Velocity level, or -1 when it's note off event + * @param bend Pitch bend offset value + */ typedef void (*ADL_NoteHook)(void *userdata, int adlchn, int note, int ins, int pressure, double bend); + +/** + * @brief Debug messages callback + * @param userdata Pointer to user data (usually, context of someting) + * @param fmt Format strign output (in context of `printf()` standard function) + */ typedef void (*ADL_DebugMessageHook)(void *userdata, const char *fmt, ...); /** * @brief Set raw MIDI event hook * @param device Instance of the library - * @param rawEventHook - * @param userData + * @param rawEventHook Pointer to the callback function which will be called on every MIDI event + * @param userData Pointer to user data which will be passed through the callback. */ extern void adl_setRawEventHook(struct ADL_MIDIPlayer *device, ADL_RawEventHook rawEventHook, void *userData); /** * @brief Set note hook * @param device Instance of the library - * @param noteHook - * @param userData + * @param noteHook Pointer to the callback function which will be called on every noteOn MIDI event + * @param userData Pointer to user data which will be passed through the callback. */ extern void adl_setNoteHook(struct ADL_MIDIPlayer *device, ADL_NoteHook noteHook, void *userData); /** * @brief Set debug message hook * @param device Instance of the library - * @param debugMessageHook - * @param userData + * @param debugMessageHook Pointer to the callback function which will be called on every debug message + * @param userData Pointer to user data which will be passed through the callback. */ extern void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMessageHook debugMessageHook, void *userData); @@ -903,11 +986,13 @@ extern void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMess * @return 0 on success, <0 when any error has occurred * * Every character in the `text` buffer means the type of usage: + * ``` * `-` - channel is unused (free) * `+` - channel is used by two-operator voice * `#` - channel is used by four-operator voice - * `@` - channel is used to play automatical arpeggio on chip channels overflow + * `@` - channel is used to play automatic arpeggio on chip channels overflow * `r` - rhythm-mode channel note + * ``` * * The `attr` field receives the MIDI channel from which the chip channel is used. * To get the valid MIDI channel you will need to apply the & 0x0F mask to every value. @@ -916,9 +1001,8 @@ extern int adl_describeChannels(struct ADL_MIDIPlayer *device, char *text, char -/** - * @subsection Instrument structures - */ + +/* ======== Instrument structures ======== */ /** * @brief Version of the instrument data format @@ -1001,7 +1085,29 @@ typedef struct ADL_Instrument ADL_SInt8 second_voice_detune; /*! Percussion MIDI base tone number at which this drum will be played */ ADL_UInt8 percussion_key_number; - /*! Enum ADL_InstrumentFlags */ + /** + * @var inst_flags + * @brief Instrument flags + * + * Enums: #ADL_InstrumentFlags and #ADL_RhythmMode + * + * Bitwise flags bit map: + * ``` + * [0EEEDCBA] + * A) 0x00 - 2-operator mode + * B) 0x01 - 4-operator mode + * C) 0x02 - pseudo-4-operator (two 2-operator voices) mode + * D) 0x04 - is 'blank' instrument (instrument which has no sound) + * E) 0x38 - Reserved for rhythm-mode percussion type number (three bits number) + * -> 0x00 - Melodic or Generic drum (rhythm-mode is disabled) + * -> 0x08 - is Bass drum + * -> 0x10 - is Snare + * -> 0x18 - is Tom-tom + * -> 0x20 - is Cymbal + * -> 0x28 - is Hi-hat + * 0) Reserved / Unused + * ``` + */ ADL_UInt8 inst_flags; /*! Feedback&Connection register for first and second operators */ ADL_UInt8 fb_conn1_C0; -- cgit v1.2.3 From c6b16ecfb07897ed15fc37464b14e523627d82ea Mon Sep 17 00:00:00 2001 From: Vitaly Novichkov Date: Wed, 4 Jul 2018 03:45:05 +0300 Subject: Apply one minor fix on `adl_getBankNames()` call documentation --- include/adlmidi.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index 960ba54..387a30a 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -175,7 +175,7 @@ extern int adl_getBanksCount(); /** * @brief Returns pointer to array of names of every bank - * @return Array of strings are containing names of every embedded bank + * @return Array of strings containing the name of every embedded bank */ extern const char *const *adl_getBankNames(); -- cgit v1.2.3 From 7cb0fe9dad9f7ef24d1142d866450305102bf3a9 Mon Sep 17 00:00:00 2001 From: JP Cimalando Date: Sat, 7 Jul 2018 02:03:01 +0200 Subject: sequencer API to turn tracks on/off/solo --- include/adlmidi.h | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index 387a30a..dc6fd8c 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -636,6 +636,33 @@ extern void adl_setTempo(struct ADL_MIDIPlayer *device, double tempo); */ extern int adl_atEnd(struct ADL_MIDIPlayer *device); +/** + * @brief Returns the number of tracks of the current sequence + * @param device Instance of the library + * @return Count of tracks in the current sequence + */ +extern size_t adl_trackCount(struct ADL_MIDIPlayer *device); + +/** + * @brief Track options + */ +enum ADLMIDI_TrackOptions +{ + /*! Enabled track */ + ADL_TrackOption_On = 1, + /*! Disabled track */ + ADL_TrackOption_Off = 2, + /*! Solo track */ + ADL_TrackOption_Solo = 3, +}; + +/** + * @brief Sets options on a track of the current sequence + * @param device Instance of the library + * @param trackNumber Identifier of the designated track. + * @return 0 on success, <0 when any error has occurred + */ +extern int adl_setTrackOptions(struct ADL_MIDIPlayer *device, size_t trackNumber, unsigned trackOptions); -- cgit v1.2.3 From b82e6572f86105d237b031624e28666f13c3ceb9 Mon Sep 17 00:00:00 2001 From: JP Cimalando Date: Sat, 7 Jul 2018 19:32:55 +0200 Subject: rename enum members for consistency --- include/adlmidi.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index dc6fd8c..f19bca0 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -649,11 +649,11 @@ extern size_t adl_trackCount(struct ADL_MIDIPlayer *device); enum ADLMIDI_TrackOptions { /*! Enabled track */ - ADL_TrackOption_On = 1, + ADLMIDI_TrackOption_On = 1, /*! Disabled track */ - ADL_TrackOption_Off = 2, + ADLMIDI_TrackOption_Off = 2, /*! Solo track */ - ADL_TrackOption_Solo = 3, + ADLMIDI_TrackOption_Solo = 3, }; /** -- cgit v1.2.3 From 9fdaf5361c57438bf7f5bafaf6bb9a79b6bb7493 Mon Sep 17 00:00:00 2001 From: JP Cimalando Date: Mon, 9 Jul 2018 20:20:55 +0200 Subject: xmi: handle AIL callback trigger --- include/adlmidi.h | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index f19bca0..77fbe74 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -664,6 +664,24 @@ enum ADLMIDI_TrackOptions */ extern int adl_setTrackOptions(struct ADL_MIDIPlayer *device, size_t trackNumber, unsigned trackOptions); +/** + * @brief Handler of callback trigger events + * @param userData Pointer to user data (usually, context of something) + * @param trigger Value of the event which triggered this callback. + * @param track Identifier of the track which triggered this callback. + */ +typedef void (*ADL_TriggerHandler)(void *userData, unsigned trigger, size_t track); + +/** + * @brief Defines a handler for callback trigger events + * @param device Instance of the library + * @param handler Handler to invoke from the sequencer when triggered, or NULL. + * @param userData Instance of the library + * @return 0 on success, <0 when any error has occurred + */ +extern int adl_setTriggerHandler(struct ADL_MIDIPlayer *device, ADL_TriggerHandler handler, void *userData); + + /* ======== Meta-Tags ======== */ -- cgit v1.2.3 From 0f69d504792776967b61f8987ad458c48b4a322f Mon Sep 17 00:00:00 2001 From: Christopher Snowhill Date: Sun, 29 Jul 2018 20:52:26 -0700 Subject: Implemented optional soft panning support for the included chip emulators, disabled by default. --- include/adlmidi.h | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index 77fbe74..aa6aa52 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -364,6 +364,13 @@ extern void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_bri */ extern void adl_setLoopEnabled(struct ADL_MIDIPlayer *device, int loopEn); +/** + * @brief Enable or disable soft panning with chip emulators + * @param device Instance of the library + * @param softPanEn 0 - disabled, 1 - enabled + */ +extern void adl_setSoftPanEnabled(struct ADL_MIDIPlayer *device, int softPanEn); + /** * @brief [DEPRECATED] Enable or disable Logarithmic volume changer * -- cgit v1.2.3 From 626354e6d686d20c43b4d9aa929b85840e6e1015 Mon Sep 17 00:00:00 2001 From: Wohlstand Date: Tue, 31 Jul 2018 02:26:06 +0300 Subject: Fixed MSVC Build of shared library --- include/adlmidi.h | 176 ++++++++++++++++++++++++++++------------------------ include/adlmidi.hpp | 4 +- 2 files changed, 97 insertions(+), 83 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index aa6aa52..f687757 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -65,6 +65,18 @@ typedef short ADL_SInt16; #define DEPRECATED(func) func #endif +#ifdef ADLMIDI_BUILD +# ifndef ADLMIDI_DECLSPEC +# if defined (_WIN32) && defined(ADLMIDI_BUILD_DLL) +# define ADLMIDI_DECLSPEC __declspec(dllexport) +# else +# define ADLMIDI_DECLSPEC +# endif +# endif +#else +# define ADLMIDI_DECLSPEC +#endif + /** * @brief Volume scaling models @@ -147,14 +159,14 @@ struct ADL_MIDIPlayer * @param numChips Count of virtual chips to emulate * @return 0 on success, <0 when any error has occurred */ -extern int adl_setNumChips(struct ADL_MIDIPlayer *device, int numChips); +extern ADLMIDI_DECLSPEC int adl_setNumChips(struct ADL_MIDIPlayer *device, int numChips); /** * @brief Get current number of emulated chips * @param device Instance of the library * @return Count of working chip emulators */ -extern int adl_getNumChips(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC int adl_getNumChips(struct ADL_MIDIPlayer *device); /** * @brief Sets a number of the patches bank from 0 to N banks. @@ -165,19 +177,19 @@ extern int adl_getNumChips(struct ADL_MIDIPlayer *device); * @param bank Number of embedded bank * @return 0 on success, <0 when any error has occurred */ -extern int adl_setBank(struct ADL_MIDIPlayer *device, int bank); +extern ADLMIDI_DECLSPEC int adl_setBank(struct ADL_MIDIPlayer *device, int bank); /** * @brief Returns total number of available banks * @return Total number of available embedded banks */ -extern int adl_getBanksCount(); +extern ADLMIDI_DECLSPEC int adl_getBanksCount(); /** * @brief Returns pointer to array of names of every bank * @return Array of strings containing the name of every embedded bank */ -extern const char *const *adl_getBankNames(); +extern ADLMIDI_DECLSPEC const char *const *adl_getBankNames(); /** * @brief Reference to dynamic bank @@ -224,7 +236,7 @@ typedef struct ADL_Instrument ADL_Instrument; * @param banks Count of bank slots to pre-allocate. * @return actual capacity of reserved bank slots. */ -extern int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks); +extern ADLMIDI_DECLSPEC int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks); /** * @brief Gets the bank designated by the identifier, optionally creating if it does not exist * @param device Instance of the library @@ -233,7 +245,7 @@ extern int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks); * @param bank Reference to dynamic bank * @return 0 on success, <0 when any error has occurred */ -extern int adl_getBank(struct ADL_MIDIPlayer *device, const ADL_BankId *id, int flags, ADL_Bank *bank); +extern ADLMIDI_DECLSPEC int adl_getBank(struct ADL_MIDIPlayer *device, const ADL_BankId *id, int flags, ADL_Bank *bank); /** * @brief Gets the identifier of a bank * @param device Instance of the library @@ -241,28 +253,28 @@ extern int adl_getBank(struct ADL_MIDIPlayer *device, const ADL_BankId *id, int * @param id Identifier of dynamic bank * @return 0 on success, <0 when any error has occurred */ -extern int adl_getBankId(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, ADL_BankId *id); +extern ADLMIDI_DECLSPEC int adl_getBankId(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, ADL_BankId *id); /** * @brief Removes a bank * @param device Instance of the library * @param bank Reference to dynamic bank * @return 0 on success, <0 when any error has occurred */ -extern int adl_removeBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); +extern ADLMIDI_DECLSPEC int adl_removeBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); /** * @brief Gets the first bank * @param device Instance of the library * @param bank Reference to dynamic bank * @return 0 on success, <0 when any error has occurred */ -extern int adl_getFirstBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); +extern ADLMIDI_DECLSPEC int adl_getFirstBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); /** * @brief Iterates to the next bank * @param device Instance of the library * @param bank Reference to dynamic bank * @return 0 on success, <0 when any error has occurred or end has been reached. */ -extern int adl_getNextBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); +extern ADLMIDI_DECLSPEC int adl_getNextBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); /** * @brief Gets the nth intrument in the bank [0..127] * @param device Instance of the library @@ -271,7 +283,7 @@ extern int adl_getNextBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank); * @param ins Instrument entry * @return 0 on success, <0 when any error has occurred */ -extern int adl_getInstrument(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, unsigned index, ADL_Instrument *ins); +extern ADLMIDI_DECLSPEC int adl_getInstrument(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, unsigned index, ADL_Instrument *ins); /** * @brief Sets the nth intrument in the bank [0..127] * @param device Instance of the library @@ -282,7 +294,7 @@ extern int adl_getInstrument(struct ADL_MIDIPlayer *device, const ADL_Bank *bank * * This function allows to override an instrument on the fly */ -extern int adl_setInstrument(struct ADL_MIDIPlayer *device, ADL_Bank *bank, unsigned index, const ADL_Instrument *ins); +extern ADLMIDI_DECLSPEC int adl_setInstrument(struct ADL_MIDIPlayer *device, ADL_Bank *bank, unsigned index, const ADL_Instrument *ins); /** * @brief Loads the melodic or percussive part of the nth embedded bank * @param device Instance of the library @@ -290,7 +302,7 @@ extern int adl_setInstrument(struct ADL_MIDIPlayer *device, ADL_Bank *bank, unsi * @param num Number of embedded bank to load into the current bank array * @return 0 on success, <0 when any error has occurred */ -extern int adl_loadEmbeddedBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank, int num); +extern ADLMIDI_DECLSPEC int adl_loadEmbeddedBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank, int num); @@ -306,14 +318,14 @@ extern int adl_loadEmbeddedBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank, i * @param ops4 Count of four-op channels to allocate between all emulating chips * @return 0 on success, <0 when any error has occurred */ -extern int adl_setNumFourOpsChn(struct ADL_MIDIPlayer *device, int ops4); +extern ADLMIDI_DECLSPEC int adl_setNumFourOpsChn(struct ADL_MIDIPlayer *device, int ops4); /** * @brief Get current total count of 4-operator channels between all chips * @param device Instance of the library * @return 0 on success, <0 when any error has occurred */ -extern int adl_getNumFourOpsChn(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC int adl_getNumFourOpsChn(struct ADL_MIDIPlayer *device); /** * @brief Override Enable(1) or Disable(0) AdLib percussion mode. -1 - use bank default AdLib percussion mode @@ -323,28 +335,28 @@ extern int adl_getNumFourOpsChn(struct ADL_MIDIPlayer *device); * @param device Instance of the library * @param percmod 0 - disabled, 1 - enabled */ -extern void adl_setPercMode(struct ADL_MIDIPlayer *device, int percmod); +extern ADLMIDI_DECLSPEC void adl_setPercMode(struct ADL_MIDIPlayer *device, int percmod); /** * @brief Override Enable(1) or Disable(0) deep vibrato state. -1 - use bank default vibrato state * @param device Instance of the library * @param hvibro 0 - disabled, 1 - enabled */ -extern void adl_setHVibrato(struct ADL_MIDIPlayer *device, int hvibro); +extern ADLMIDI_DECLSPEC void adl_setHVibrato(struct ADL_MIDIPlayer *device, int hvibro); /** * @brief Override Enable(1) or Disable(0) deep tremolo state. -1 - use bank default tremolo state * @param device Instance of the library * @param htremo 0 - disabled, 1 - enabled */ -extern void adl_setHTremolo(struct ADL_MIDIPlayer *device, int htremo); +extern ADLMIDI_DECLSPEC void adl_setHTremolo(struct ADL_MIDIPlayer *device, int htremo); /** * @brief Override Enable(1) or Disable(0) scaling of modulator volumes. -1 - use bank default scaling of modulator volumes * @param device Instance of the library * @param smod 0 - disabled, 1 - enabled */ -extern void adl_setScaleModulators(struct ADL_MIDIPlayer *device, int smod); +extern ADLMIDI_DECLSPEC void adl_setScaleModulators(struct ADL_MIDIPlayer *device, int smod); /** * @brief Enable(1) or Disable(0) full-range brightness (MIDI CC74 used in XG music to filter result sounding) scaling @@ -355,35 +367,35 @@ extern void adl_setScaleModulators(struct ADL_MIDIPlayer *device, int smod); * @param device Instance of the library * @param fr_brightness 0 - disabled, 1 - enabled */ -extern void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_brightness); +extern ADLMIDI_DECLSPEC void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_brightness); /** * @brief Enable or disable built-in loop (built-in loop supports 'loopStart' and 'loopEnd' tags to loop specific part) * @param device Instance of the library * @param loopEn 0 - disabled, 1 - enabled */ -extern void adl_setLoopEnabled(struct ADL_MIDIPlayer *device, int loopEn); +extern ADLMIDI_DECLSPEC void adl_setLoopEnabled(struct ADL_MIDIPlayer *device, int loopEn); /** * @brief Enable or disable soft panning with chip emulators * @param device Instance of the library * @param softPanEn 0 - disabled, 1 - enabled */ -extern void adl_setSoftPanEnabled(struct ADL_MIDIPlayer *device, int softPanEn); +extern ADLMIDI_DECLSPEC void adl_setSoftPanEnabled(struct ADL_MIDIPlayer *device, int softPanEn); /** * @brief [DEPRECATED] Enable or disable Logarithmic volume changer * * This function is deprecated. Suggested replacement: `adl_setVolumeRangeModel` with `ADLMIDI_VolumeModel_NativeOPL3` volume model value; */ -DEPRECATED(extern void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol)); +DEPRECATED(extern ADLMIDI_DECLSPEC void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol)); /** * @brief Set different volume range model * @param device Instance of the library * @param volumeModel Volume model type (#ADLMIDI_VolumeModels) */ -extern void adl_setVolumeRangeModel(struct ADL_MIDIPlayer *device, int volumeModel); +extern ADLMIDI_DECLSPEC void adl_setVolumeRangeModel(struct ADL_MIDIPlayer *device, int volumeModel); /** * @brief Load WOPL bank file from File System @@ -394,7 +406,7 @@ extern void adl_setVolumeRangeModel(struct ADL_MIDIPlayer *device, int volumeMod * @param filePath Absolute or relative path to the WOPL bank file. UTF8 encoding is required, even on Windows. * @return 0 on success, <0 when any error has occurred */ -extern int adl_openBankFile(struct ADL_MIDIPlayer *device, const char *filePath); +extern ADLMIDI_DECLSPEC int adl_openBankFile(struct ADL_MIDIPlayer *device, const char *filePath); /** * @brief Load WOPL bank file from memory data @@ -406,7 +418,7 @@ extern int adl_openBankFile(struct ADL_MIDIPlayer *device, const char *filePath) * @param size Size of given memory block * @return 0 on success, <0 when any error has occurred */ -extern int adl_openBankData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size); +extern ADLMIDI_DECLSPEC int adl_openBankData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size); /** @@ -416,14 +428,14 @@ extern int adl_openBankData(struct ADL_MIDIPlayer *device, const void *mem, unsi * * @return A string that contains a notice to use `adl_chipEmulatorName` instead of this function. */ -DEPRECATED(extern const char *adl_emulatorName()); +DEPRECATED(extern ADLMIDI_DECLSPEC const char *adl_emulatorName()); /** * @brief Returns chip emulator name string * @param device Instance of the library * @return Understandable name of current OPL3 emulator */ -extern const char *adl_chipEmulatorName(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC const char *adl_chipEmulatorName(struct ADL_MIDIPlayer *device); /** * @brief List of available OPL3 emulators @@ -446,7 +458,7 @@ enum ADL_Emulator * @param emulator Type of emulator (#ADL_Emulator) * @return 0 on success, <0 when any error has occurred */ -extern int adl_switchEmulator(struct ADL_MIDIPlayer *device, int emulator); +extern ADLMIDI_DECLSPEC int adl_switchEmulator(struct ADL_MIDIPlayer *device, int emulator); /** * @brief Library version context @@ -466,7 +478,7 @@ typedef struct { * @param enabled 0 - disabled, 1 - enabled * @return 0 on success, <0 when any error has occurred */ -extern int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled); +extern ADLMIDI_DECLSPEC int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled); /** * @brief Set 4-bit device identifier. Used by the SysEx processor. @@ -474,7 +486,7 @@ extern int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled); * @param id 4-bit device identifier * @return 0 on success, <0 when any error has occurred */ -extern int adl_setDeviceIdentifier(struct ADL_MIDIPlayer *device, unsigned id); +extern ADLMIDI_DECLSPEC int adl_setDeviceIdentifier(struct ADL_MIDIPlayer *device, unsigned id); /** * @section Information @@ -484,13 +496,13 @@ extern int adl_setDeviceIdentifier(struct ADL_MIDIPlayer *device, unsigned id); * @brief Returns string which contains a version number * @return String which contains a version of the library */ -extern const char *adl_linkedLibraryVersion(); +extern ADLMIDI_DECLSPEC const char *adl_linkedLibraryVersion(); /** * @brief Returns structure which contains a version number of library * @return Library version context structure which contains version number of the library */ -extern const ADL_Version *adl_linkedVersion(); +extern ADLMIDI_DECLSPEC const ADL_Version *adl_linkedVersion(); /* ======== Error Info ======== */ @@ -503,14 +515,14 @@ extern const ADL_Version *adl_linkedVersion(); * * @return String with error message related to library initialization */ -extern const char *adl_errorString(); +extern ADLMIDI_DECLSPEC const char *adl_errorString(); /** * @brief Returns string which contains last error message on specific device * @param device Instance of the library * @return String with error message related to last function call returned non-zero value. */ -extern const char *adl_errorInfo(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC const char *adl_errorInfo(struct ADL_MIDIPlayer *device); @@ -526,13 +538,13 @@ extern const char *adl_errorInfo(struct ADL_MIDIPlayer *device); * @param sample_rate Output sample rate * @return Instance of the library. If NULL was returned, check the `adl_errorString` message for more info. */ -extern struct ADL_MIDIPlayer *adl_init(long sample_rate); +extern ADLMIDI_DECLSPEC struct ADL_MIDIPlayer *adl_init(long sample_rate); /** * @brief Close and delete ADLMIDI device * @param device Instance of the library */ -extern void adl_close(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC void adl_close(struct ADL_MIDIPlayer *device); @@ -547,7 +559,7 @@ extern void adl_close(struct ADL_MIDIPlayer *device); * @param filePath Absolute or relative path to the music file. UTF8 encoding is required, even on Windows. * @return 0 on success, <0 when any error has occurred */ -extern int adl_openFile(struct ADL_MIDIPlayer *device, const char *filePath); +extern ADLMIDI_DECLSPEC int adl_openFile(struct ADL_MIDIPlayer *device, const char *filePath); /** * @brief Load MIDI (or any other supported format) file from memory data @@ -559,13 +571,13 @@ extern int adl_openFile(struct ADL_MIDIPlayer *device, const char *filePath); * @param size Size of given memory block * @return 0 on success, <0 when any error has occurred */ -extern int adl_openData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size); +extern ADLMIDI_DECLSPEC int adl_openData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size); /** * @brief Resets MIDI player (per-channel setup) into initial state * @param device Instance of the library */ -extern void adl_reset(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC void adl_reset(struct ADL_MIDIPlayer *device); /** * @brief Get total time length of current song @@ -575,7 +587,7 @@ extern void adl_reset(struct ADL_MIDIPlayer *device); * @param device Instance of the library * @return Total song length in seconds */ -extern double adl_totalTimeLength(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC double adl_totalTimeLength(struct ADL_MIDIPlayer *device); /** * @brief Get loop start time if presented. @@ -585,7 +597,7 @@ extern double adl_totalTimeLength(struct ADL_MIDIPlayer *device); * @param device Instance of the library * @return Time position in seconds of loop start point, or -1 when file has no loop points */ -extern double adl_loopStartTime(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC double adl_loopStartTime(struct ADL_MIDIPlayer *device); /** * @brief Get loop endtime if presented. @@ -595,7 +607,7 @@ extern double adl_loopStartTime(struct ADL_MIDIPlayer *device); * @param device Instance of the library * @return Time position in seconds of loop end point, or -1 when file has no loop points */ -extern double adl_loopEndTime(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC double adl_loopEndTime(struct ADL_MIDIPlayer *device); /** * @brief Get current time position in seconds @@ -605,7 +617,7 @@ extern double adl_loopEndTime(struct ADL_MIDIPlayer *device); * @param device Instance of the library * @return Current time position in seconds */ -extern double adl_positionTell(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC double adl_positionTell(struct ADL_MIDIPlayer *device); /** * @brief Jump to absolute time position in seconds @@ -615,7 +627,7 @@ extern double adl_positionTell(struct ADL_MIDIPlayer *device); * @param device Instance of the library * @param seconds Destination time position in seconds to seek */ -extern void adl_positionSeek(struct ADL_MIDIPlayer *device, double seconds); +extern ADLMIDI_DECLSPEC void adl_positionSeek(struct ADL_MIDIPlayer *device, double seconds); /** * @brief Reset MIDI track position to begin @@ -624,7 +636,7 @@ extern void adl_positionSeek(struct ADL_MIDIPlayer *device, double seconds); * * @param device Instance of the library */ -extern void adl_positionRewind(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC void adl_positionRewind(struct ADL_MIDIPlayer *device); /** * @brief Set tempo multiplier @@ -634,21 +646,21 @@ extern void adl_positionRewind(struct ADL_MIDIPlayer *device); * @param device Instance of the library * @param tempo Tempo multiplier value: 1.0 - original tempo, >1 - play faster, <1 - play slower */ -extern void adl_setTempo(struct ADL_MIDIPlayer *device, double tempo); +extern ADLMIDI_DECLSPEC void adl_setTempo(struct ADL_MIDIPlayer *device, double tempo); /** * @brief Returns 1 if music position has reached end * @param device Instance of the library * @return 1 when end of sing has been reached, otherwise, 0 will be returned. <0 is returned on any error */ -extern int adl_atEnd(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC int adl_atEnd(struct ADL_MIDIPlayer *device); /** * @brief Returns the number of tracks of the current sequence * @param device Instance of the library * @return Count of tracks in the current sequence */ -extern size_t adl_trackCount(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC size_t adl_trackCount(struct ADL_MIDIPlayer *device); /** * @brief Track options @@ -669,7 +681,7 @@ enum ADLMIDI_TrackOptions * @param trackNumber Identifier of the designated track. * @return 0 on success, <0 when any error has occurred */ -extern int adl_setTrackOptions(struct ADL_MIDIPlayer *device, size_t trackNumber, unsigned trackOptions); +extern ADLMIDI_DECLSPEC int adl_setTrackOptions(struct ADL_MIDIPlayer *device, size_t trackNumber, unsigned trackOptions); /** * @brief Handler of callback trigger events @@ -677,7 +689,7 @@ extern int adl_setTrackOptions(struct ADL_MIDIPlayer *device, size_t trackNumber * @param trigger Value of the event which triggered this callback. * @param track Identifier of the track which triggered this callback. */ -typedef void (*ADL_TriggerHandler)(void *userData, unsigned trigger, size_t track); +typedef ADLMIDI_DECLSPEC void (*ADL_TriggerHandler)(void *userData, unsigned trigger, size_t track); /** * @brief Defines a handler for callback trigger events @@ -686,7 +698,7 @@ typedef void (*ADL_TriggerHandler)(void *userData, unsigned trigger, size_t trac * @param userData Instance of the library * @return 0 on success, <0 when any error has occurred */ -extern int adl_setTriggerHandler(struct ADL_MIDIPlayer *device, ADL_TriggerHandler handler, void *userData); +extern ADLMIDI_DECLSPEC int adl_setTriggerHandler(struct ADL_MIDIPlayer *device, ADL_TriggerHandler handler, void *userData); @@ -698,14 +710,14 @@ extern int adl_setTriggerHandler(struct ADL_MIDIPlayer *device, ADL_TriggerHandl * @param device Instance of the library * @return A string that contains music title */ -extern const char *adl_metaMusicTitle(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC const char *adl_metaMusicTitle(struct ADL_MIDIPlayer *device); /** * @brief Returns string which contains a copyright string* * @param device Instance of the library * @return A string that contains copyright notice, otherwise NULL */ -extern const char *adl_metaMusicCopyright(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC const char *adl_metaMusicCopyright(struct ADL_MIDIPlayer *device); /** * @brief Returns count of available track titles @@ -715,7 +727,7 @@ extern const char *adl_metaMusicCopyright(struct ADL_MIDIPlayer *device); * @param device Instance of the library * @return Count of available MIDI tracks, otherwise NULL */ -extern size_t adl_metaTrackTitleCount(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC size_t adl_metaTrackTitleCount(struct ADL_MIDIPlayer *device); /** * @brief Get track title by index @@ -723,7 +735,7 @@ extern size_t adl_metaTrackTitleCount(struct ADL_MIDIPlayer *device); * @param index Index of the track to retreive the title * @return A string that contains track title, otherwise NULL. */ -extern const char *adl_metaTrackTitle(struct ADL_MIDIPlayer *device, size_t index); +extern ADLMIDI_DECLSPEC const char *adl_metaTrackTitle(struct ADL_MIDIPlayer *device, size_t index); /** * @brief MIDI Marker structure @@ -743,7 +755,7 @@ struct Adl_MarkerEntry * @param device Instance of the library * @return Count of available MIDI markers */ -extern size_t adl_metaMarkerCount(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC size_t adl_metaMarkerCount(struct ADL_MIDIPlayer *device); /** * @brief Returns the marker entry @@ -751,7 +763,7 @@ extern size_t adl_metaMarkerCount(struct ADL_MIDIPlayer *device); * @param index Index of the marker to retreive it. * @return MIDI Marker description structure. */ -extern struct Adl_MarkerEntry adl_metaMarker(struct ADL_MIDIPlayer *device, size_t index); +extern ADLMIDI_DECLSPEC struct Adl_MarkerEntry adl_metaMarker(struct ADL_MIDIPlayer *device, size_t index); @@ -774,7 +786,7 @@ extern struct Adl_MarkerEntry adl_metaMarker(struct ADL_MIDIPlayer *device, size * @param out Pointer to output with 16-bit stereo PCM output * @return Count of given samples, otherwise, 0 or when catching an error while playing */ -extern int adl_play(struct ADL_MIDIPlayer *device, int sampleCount, short *out); +extern ADLMIDI_DECLSPEC int adl_play(struct ADL_MIDIPlayer *device, int sampleCount, short *out); /** * @brief Generate PCM stereo audio output in sample format declared by given context and iterate MIDI timers @@ -794,7 +806,7 @@ extern int adl_play(struct ADL_MIDIPlayer *device, int sampleCount, short *out) * @param format Destination PCM format format context * @return Count of given samples, otherwise, 0 or when catching an error while playing */ -extern int adl_playFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format); +extern ADLMIDI_DECLSPEC int adl_playFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format); /** * @brief Generate PCM signed 16-bit stereo audio output without iteration of MIDI timers @@ -813,7 +825,7 @@ extern int adl_playFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_U * @param out Pointer to output with 16-bit stereo PCM output * @return Count of given samples, otherwise, 0 or when catching an error while playing */ -extern int adl_generate(struct ADL_MIDIPlayer *device, int sampleCount, short *out); +extern ADLMIDI_DECLSPEC int adl_generate(struct ADL_MIDIPlayer *device, int sampleCount, short *out); /** * @brief Generate PCM stereo audio output in sample format declared by given context without iteration of MIDI timers @@ -834,7 +846,7 @@ extern int adl_generate(struct ADL_MIDIPlayer *device, int sampleCount, short * * @param format Destination PCM format format context * @return Count of given samples, otherwise, 0 or when catching an error while playing */ -extern int adl_generateFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format); +extern ADLMIDI_DECLSPEC int adl_generateFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format); /** * @brief Periodic tick handler. @@ -850,7 +862,7 @@ extern int adl_generateFormat(struct ADL_MIDIPlayer *device, int sampleCount, A * @param granulality Minimal size of one MIDI tick in seconds. * @return desired number of seconds until next call. Pass this value into `seconds` field in next time */ -extern double adl_tickEvents(struct ADL_MIDIPlayer *device, double seconds, double granulality); +extern ADLMIDI_DECLSPEC double adl_tickEvents(struct ADL_MIDIPlayer *device, double seconds, double granulality); @@ -861,13 +873,13 @@ extern double adl_tickEvents(struct ADL_MIDIPlayer *device, double seconds, doub * @brief Force Off all notes on all channels * @param device Instance of the library */ -extern void adl_panic(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC void adl_panic(struct ADL_MIDIPlayer *device); /** * @brief Reset states of all controllers on all MIDI channels * @param device Instance of the library */ -extern void adl_rt_resetState(struct ADL_MIDIPlayer *device); +extern ADLMIDI_DECLSPEC void adl_rt_resetState(struct ADL_MIDIPlayer *device); /** * @brief Turn specific MIDI note ON @@ -877,7 +889,7 @@ extern void adl_rt_resetState(struct ADL_MIDIPlayer *device); * @param velocity Velocity level [Between 0 and 127] * @return 1 when note was successfully started, 0 when note was rejected by any reason. */ -extern int adl_rt_noteOn(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 velocity); +extern ADLMIDI_DECLSPEC int adl_rt_noteOn(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 velocity); /** * @brief Turn specific MIDI note OFF @@ -885,7 +897,7 @@ extern int adl_rt_noteOn(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_U * @param channel Target MIDI channel [Between 0 and 16] * @param note Note number to off [Between 0 and 127] */ -extern void adl_rt_noteOff(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note); +extern ADLMIDI_DECLSPEC void adl_rt_noteOff(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note); /** * @brief Set note after-touch @@ -894,7 +906,7 @@ extern void adl_rt_noteOff(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL * @param note Note number to affect by aftertouch event [Between 0 and 127] * @param atVal After-Touch value [Between 0 and 127] */ -extern void adl_rt_noteAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 atVal); +extern ADLMIDI_DECLSPEC void adl_rt_noteAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 atVal); /** * @brief Set channel after-touch @@ -902,7 +914,7 @@ extern void adl_rt_noteAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 chann * @param channel Target MIDI channel [Between 0 and 16] * @param atVal After-Touch level [Between 0 and 127] */ -extern void adl_rt_channelAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 atVal); +extern ADLMIDI_DECLSPEC void adl_rt_channelAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 atVal); /** * @brief Apply controller change @@ -911,7 +923,7 @@ extern void adl_rt_channelAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 ch * @param type Type of the controller [Between 0 and 255] * @param value Value of the controller event [Between 0 and 127] */ -extern void adl_rt_controllerChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 type, ADL_UInt8 value); +extern ADLMIDI_DECLSPEC void adl_rt_controllerChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 type, ADL_UInt8 value); /** * @brief Apply patch change @@ -919,7 +931,7 @@ extern void adl_rt_controllerChange(struct ADL_MIDIPlayer *device, ADL_UInt8 cha * @param channel Target MIDI channel [Between 0 and 16] * @param patch Patch number [Between 0 and 127] */ -extern void adl_rt_patchChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 patch); +extern ADLMIDI_DECLSPEC void adl_rt_patchChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 patch); /** * @brief Apply pitch bend change @@ -927,7 +939,7 @@ extern void adl_rt_patchChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, * @param channel Target MIDI channel [Between 0 and 16] * @param pitch 24-bit pitch bend value */ -extern void adl_rt_pitchBend(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt16 pitch); +extern ADLMIDI_DECLSPEC void adl_rt_pitchBend(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt16 pitch); /** * @brief Apply pitch bend change @@ -936,7 +948,7 @@ extern void adl_rt_pitchBend(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, A * @param msb MSB part of 24-bit pitch bend value * @param lsb LSB part of 24-bit pitch bend value */ -extern void adl_rt_pitchBendML(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb, ADL_UInt8 lsb); +extern ADLMIDI_DECLSPEC void adl_rt_pitchBendML(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb, ADL_UInt8 lsb); /** * @brief Change LSB of the bank number (Alias to CC-32 event) @@ -944,7 +956,7 @@ extern void adl_rt_pitchBendML(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, * @param channel Target MIDI channel [Between 0 and 16] * @param lsb LSB value of the MIDI bank number */ -extern void adl_rt_bankChangeLSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 lsb); +extern ADLMIDI_DECLSPEC void adl_rt_bankChangeLSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 lsb); /** * @brief Change MSB of the bank (Alias to CC-0 event) @@ -952,7 +964,7 @@ extern void adl_rt_bankChangeLSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channe * @param channel Target MIDI channel [Between 0 and 16] * @param msb MSB value of the MIDI bank number */ -extern void adl_rt_bankChangeMSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb); +extern ADLMIDI_DECLSPEC void adl_rt_bankChangeMSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb); /** * @brief Change bank by absolute signed value @@ -961,7 +973,7 @@ extern void adl_rt_bankChangeMSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channe * @param bank Bank number as concoctated signed 16-bit value of MSB and LSB parts. */ -extern void adl_rt_bankChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_SInt16 bank); +extern ADLMIDI_DECLSPEC void adl_rt_bankChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_SInt16 bank); /** * @brief Perform a system exclusive message @@ -970,7 +982,7 @@ extern void adl_rt_bankChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, * @param size Size of given SysEx message buffer * @return 1 when SysEx message was successfully processed, 0 when SysEx message was rejected by any reason */ -extern int adl_rt_systemExclusive(struct ADL_MIDIPlayer *device, const ADL_UInt8 *msg, size_t size); +extern ADLMIDI_DECLSPEC int adl_rt_systemExclusive(struct ADL_MIDIPlayer *device, const ADL_UInt8 *msg, size_t size); @@ -1011,7 +1023,7 @@ typedef void (*ADL_DebugMessageHook)(void *userdata, const char *fmt, ...); * @param rawEventHook Pointer to the callback function which will be called on every MIDI event * @param userData Pointer to user data which will be passed through the callback. */ -extern void adl_setRawEventHook(struct ADL_MIDIPlayer *device, ADL_RawEventHook rawEventHook, void *userData); +extern ADLMIDI_DECLSPEC void adl_setRawEventHook(struct ADL_MIDIPlayer *device, ADL_RawEventHook rawEventHook, void *userData); /** * @brief Set note hook @@ -1019,7 +1031,7 @@ extern void adl_setRawEventHook(struct ADL_MIDIPlayer *device, ADL_RawEventHook * @param noteHook Pointer to the callback function which will be called on every noteOn MIDI event * @param userData Pointer to user data which will be passed through the callback. */ -extern void adl_setNoteHook(struct ADL_MIDIPlayer *device, ADL_NoteHook noteHook, void *userData); +extern ADLMIDI_DECLSPEC void adl_setNoteHook(struct ADL_MIDIPlayer *device, ADL_NoteHook noteHook, void *userData); /** * @brief Set debug message hook @@ -1027,7 +1039,7 @@ extern void adl_setNoteHook(struct ADL_MIDIPlayer *device, ADL_NoteHook noteHook * @param debugMessageHook Pointer to the callback function which will be called on every debug message * @param userData Pointer to user data which will be passed through the callback. */ -extern void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMessageHook debugMessageHook, void *userData); +extern ADLMIDI_DECLSPEC void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMessageHook debugMessageHook, void *userData); /** * @brief Get a textual description of the channel state. For display only. @@ -1049,7 +1061,7 @@ extern void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMess * The `attr` field receives the MIDI channel from which the chip channel is used. * To get the valid MIDI channel you will need to apply the & 0x0F mask to every value. */ -extern int adl_describeChannels(struct ADL_MIDIPlayer *device, char *text, char *attr, size_t size); +extern ADLMIDI_DECLSPEC int adl_describeChannels(struct ADL_MIDIPlayer *device, char *text, char *attr, size_t size); diff --git a/include/adlmidi.hpp b/include/adlmidi.hpp index 6d01b8d..f2cd59d 100644 --- a/include/adlmidi.hpp +++ b/include/adlmidi.hpp @@ -24,9 +24,11 @@ #ifndef ADLMIDI_HPP #define ADLMIDI_HPP +#include "adlmidi.h" + struct ADL_MIDIPlayer; -class AdlInstrumentTester +class ADLMIDI_DECLSPEC AdlInstrumentTester { struct Impl; Impl *P; -- cgit v1.2.3 From e098e4285af6d565d7b603279ec6e9770ce88436 Mon Sep 17 00:00:00 2001 From: JP Cimalando Date: Tue, 31 Jul 2018 02:31:47 +0200 Subject: fix some warnings --- include/adlmidi.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index f687757..35afe94 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -125,7 +125,7 @@ enum ADLMIDI_SampleType /*! unsigned PCM 32-bit */ ADLMIDI_SampleType_U32, /*! Count of available sample format types */ - ADLMIDI_SampleType_Count, + ADLMIDI_SampleType_Count }; /** @@ -220,7 +220,7 @@ enum ADL_BankAccessFlags /*! create bank, allocating memory as needed */ ADLMIDI_Bank_Create = 1, /*! create bank, never allocating memory */ - ADLMIDI_Bank_CreateRt = 1|2, + ADLMIDI_Bank_CreateRt = 1|2 }; typedef struct ADL_Instrument ADL_Instrument; @@ -672,7 +672,7 @@ enum ADLMIDI_TrackOptions /*! Disabled track */ ADLMIDI_TrackOption_Off = 2, /*! Solo track */ - ADLMIDI_TrackOption_Solo = 3, + ADLMIDI_TrackOption_Solo = 3 }; /** @@ -1073,7 +1073,7 @@ extern ADLMIDI_DECLSPEC int adl_describeChannels(struct ADL_MIDIPlayer *device, */ enum { - ADLMIDI_InstrumentVersion = 0, + ADLMIDI_InstrumentVersion = 0 }; /** @@ -1094,7 +1094,7 @@ typedef enum ADL_InstrumentFlags ADLMIDI_Ins_RhythmModeMask = 0x38, /*! Mask of the flags range */ - ADLMIDI_Ins_ALL_MASK = 0x07, + ADLMIDI_Ins_ALL_MASK = 0x07 } ADL_InstrumentFlags; /** -- cgit v1.2.3 From 9395426e07706546f31c7b0f4e79ca01be5b037d Mon Sep 17 00:00:00 2001 From: Vitaly Novichkov Date: Thu, 2 Aug 2018 00:19:16 +0300 Subject: Better deprecated calls warning --- include/adlmidi.h | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) (limited to 'include') diff --git a/include/adlmidi.h b/include/adlmidi.h index 35afe94..6ae184e 100644 --- a/include/adlmidi.h +++ b/include/adlmidi.h @@ -57,13 +57,29 @@ typedef short ADL_SInt16; /* == Deprecated function markers == */ -#ifdef __GNUC__ -#define DEPRECATED(func) func __attribute__ ((deprecated)) -#elif defined(_MSC_VER) -#define DEPRECATED(func) __declspec(deprecated) func -#else -#define DEPRECATED(func) func -#endif +#if defined(_MSC_VER) /* MSVC */ +# if _MSC_VER >= 1500 /* MSVC 2008 */ + /*! Indicates that the following function is deprecated. */ +# define ADLMIDI_DEPRECATED(message) __declspec(deprecated(message)) +# endif +#endif /* defined(_MSC_VER) */ + +#ifdef __clang__ +# if __has_extension(attribute_deprecated_with_message) +# define JSONCPP_DEPRECATED(message) __attribute__((deprecated(message))) +# endif +#elif defined __GNUC__ /* not clang (gcc comes later since clang emulates gcc) */ +# if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)) +# define ADLMIDI_DEPRECATED(message) __attribute__((deprecated(message))) +# elif (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)) +# define ADLMIDI_DEPRECATED(message) __attribute__((__deprecated__)) +# endif /* GNUC version */ +#endif /* __clang__ || __GNUC__ */ + +#if !defined(ADLMIDI_DEPRECATED) +# define ADLMIDI_DEPRECATED(message) +#endif /* if !defined(ADLMIDI_DEPRECATED) */ + #ifdef ADLMIDI_BUILD # ifndef ADLMIDI_DECLSPEC @@ -388,7 +404,8 @@ extern ADLMIDI_DECLSPEC void adl_setSoftPanEnabled(struct ADL_MIDIPlayer *device * * This function is deprecated. Suggested replacement: `adl_setVolumeRangeModel` with `ADLMIDI_VolumeModel_NativeOPL3` volume model value; */ -DEPRECATED(extern ADLMIDI_DECLSPEC void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol)); +ADLMIDI_DEPRECATED("Use `adl_setVolumeRangeModel(device, ADLMIDI_VolumeModel_NativeOPL3)` instead") +extern ADLMIDI_DECLSPEC void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol); /** * @brief Set different volume range model @@ -428,7 +445,8 @@ extern ADLMIDI_DECLSPEC int adl_openBankData(struct ADL_MIDIPlayer *device, cons * * @return A string that contains a notice to use `adl_chipEmulatorName` instead of this function. */ -DEPRECATED(extern ADLMIDI_DECLSPEC const char *adl_emulatorName()); +ADLMIDI_DEPRECATED("Use `adl_chipEmulatorName(device)` instead") +extern ADLMIDI_DECLSPEC const char *adl_emulatorName(); /** * @brief Returns chip emulator name string -- cgit v1.2.3