|
Swadge 2024 2.0.0
APIs to develop games for the Magfest Swadge
|
Macros | |
| #define | MIDI_DBG(...) |
| #define | PRINT_VOICE_VOLUME(voice) |
| #define | OSC_DITHER |
| #define | UINT14_MAX (0x3FFF) |
| #define | SET_MSB(target, val) |
| Set only the MSB of a 14-bit value. | |
| #define | SET_LSB(target, val) |
| Set only the LSB of a 14-bit value. | |
| #define | SHIFT_HI_HAT (0) |
| #define | SHIFT_WHISTLE (6) |
| #define | SHIFT_GUIRO (12) |
| #define | SHIFT_CUICA (18) |
| #define | SHIFT_TRIANGLE (24) |
| #define | MASK_HI_HAT (0x3F) |
| #define | MASK_WHISTLE (0x3F << SHIFT_WHISTLE) |
| #define | MASK_GUIRO (0x3F << SHIFT_GUIRO) |
| #define | MASK_CUICA (0x3F << SHIFT_CUICA) |
| #define | MASK_TRIANGLE (0x3F << SHIFT_TRIANGLE) |
| #define | VOICE_FREE (0x3F) |
Functions | |
| const midiTimbre_t * | getTimbreForProgram (bool percussion, uint8_t bank, uint8_t program) |
| Return a pointer to the predefined timbre assigned to the given bank and program IDs. | |
| void | midiPlayerInit (midiPlayer_t *player) |
| Initialize the MIDI player. | |
| void | midiPlayerReset (midiPlayer_t *player) |
| Reset the MIDI player state. | |
| void | midiPlayerResetNewSong (midiPlayer_t *player) |
| Reset the MIDI player state by only doing the bare minimum. This is useful when playing multiple sound effects in quick succession. | |
| int32_t | midiPlayerStep (midiPlayer_t *player) |
| Calculate and return the next MIDI sample, stepping the player state forward by one sample. | |
| void | midiPlayerFillBuffer (midiPlayer_t *player, uint8_t *samples, int16_t len) |
| Fill a buffer with the next set of samples from the MIDI player. This should be called by the callback passed into initDac(). Samples are generated at sampling rate of DAC_SAMPLE_RATE_HZ. | |
| void | midiPlayerFillBufferMulti (midiPlayer_t *players, uint8_t playerCount, uint8_t *samples, int16_t len) |
| Fill a buffer with the next set of samples from an array of MIDI players. | |
| void | midiAllSoundOff (midiPlayer_t *player) |
| Stop all sound immediately. This is not affected by the sustain pedal. | |
| void | midiResetChannelControllers (midiPlayer_t *player, uint8_t channel) |
| Reset all controllers on a MIDI channel. | |
| void | midiGmOn (midiPlayer_t *player) |
| Activate General MIDI mode on a MIDI player. | |
| void | midiGmOff (midiPlayer_t *player) |
| Deactivate General MIDI mode on a MIDI player. | |
| void | midiAllNotesOff (midiPlayer_t *player, uint8_t channel) |
| Tun off all notes which are currently on, as though midiNoteOff() were called for each note. This respects the sustain pedal. | |
| const midiVoice_t * | soundNoteOn (midiPlayer_t *player, uint8_t chanId, uint8_t note, uint8_t velocity, const midiTimbre_t *timbre, bool percussion) |
| Play a single note with custom MIDI parameters, without affecting any existing channel settings. | |
| void | soundNoteOff (midiPlayer_t *player, uint8_t chanId, uint8_t note, uint8_t velocity, bool percussion) |
| Stop playing a single note with custom MIDI parameters. | |
| void | soundVoiceOff (midiPlayer_t *player, const midiVoice_t *voice) |
| Immediately stop a single voice from playing, disregarding all ADSR parameters. | |
| void | soundVoiceRelease (midiPlayer_t *player, const midiVoice_t *voice) |
| Transition the given voice into the 'release' state, equivalent to a MIDI Note Off. | |
| void | midiNoteOn (midiPlayer_t *player, uint8_t chanId, uint8_t note, uint8_t velocity) |
| Begin playing a note on a given MIDI channel. | |
| void | midiAfterTouch (midiPlayer_t *player, uint8_t channel, uint8_t note, uint8_t velocity) |
| Change the velocity of a note on a given MIDI channel, after the note starts playing. | |
| void | midiNoteOff (midiPlayer_t *player, uint8_t channel, uint8_t note, uint8_t velocity) |
| Stop playing a particular note on a given MIDI channel. | |
| void | midiSetProgram (midiPlayer_t *player, uint8_t channel, uint8_t program) |
| Change the program (instrument) on a given MIDI channel. | |
| void | midiSustain (midiPlayer_t *player, uint8_t channel, uint8_t val) |
| Set the hold pedal status. | |
| void | midiSustenuto (midiPlayer_t *player, uint8_t channel, uint8_t val) |
| Set the sustenuto pedal status. | |
| void | midiControlChange (midiPlayer_t *player, uint8_t channel, midiControl_t control, uint8_t val) |
| Set a MIDI control value. | |
| uint8_t | midiGetControlValue (midiPlayer_t *player, uint8_t channel, midiControl_t control) |
| Get the value of a MIDI control. | |
| uint16_t | midiGetControlValue14bit (midiPlayer_t *player, uint8_t channel, midiControl_t control) |
| Get the combined value of two MIDI control registers. | |
| void | midiSetParameter (midiPlayer_t *player, uint8_t channel, bool registeredParam, uint16_t param, uint16_t value) |
| Set a registered or non-registered parameter value. | |
| uint16_t | midiGetParameterValue (midiPlayer_t *player, uint8_t channel, bool registered, uint16_t param) |
| Get the value of a registered or non-registered parameter. | |
| void | midiPitchWheel (midiPlayer_t *player, uint8_t channel, uint16_t value) |
| Set the pitch wheel value on a given MIDI channel. | |
| void | midiSetTempo (midiPlayer_t *player, uint32_t tempo) |
| Change the MIDI playback tempo. | |
| void | midiSetFile (midiPlayer_t *player, const midiFile_t *song) |
| Configure this MIDI player to read from a MIDI file. | |
| void | midiPause (midiPlayer_t *player, bool pause) |
| Set the paused state of a MIDI song. | |
| void | midiSeek (midiPlayer_t *player, uint32_t ticks) |
| Seek to a given time offset within a file. | |
| void | initGlobalMidiPlayer (void) |
| Initialize the system-wide MIDI players for both BGM and SFX. | |
| void | deinitGlobalMidiPlayer (void) |
| Deinitialize and free memory associated with the system-wide MIDI players. | |
| void | globalMidiPlayerFillBuffer (uint8_t *samples, int16_t len) |
| Fill the given sample buffer with samples from both the BGM and SFX system-wide MIDI players. | |
| void | globalMidiPlayerPlaySong (midiFile_t *song, uint8_t songIdx) |
| Play a song on one of the system-wide MIDI players, either BGM or SFX. | |
| void | globalMidiPlayerPlaySongCb (midiFile_t *song, uint8_t songIdx, songFinishedCbFn cb) |
| Play a song on one of the system-wide MIDI players, with a callback once the song finishes. | |
| void | globalMidiPlayerSetVolume (uint8_t trackType, int32_t volumeSetting) |
| Set the volume using a value from 0 to 13. | |
| void | globalMidiPlayerPauseAll (void) |
| Pause all songs currently being played by the system-wide MIDI players. | |
| void | globalMidiPlayerResumeAll (void) |
| Resume all songs currently being played by the system-wide MIDI players. | |
| void | globalMidiPlayerStop (bool reset) |
| Stop all songs currently being played by the system-wide MIDI players, optionally resetting their state to the beginning of the song. | |
| midiPlayer_t * | globalMidiPlayerGet (uint8_t songIdx) |
| Return a pointer to the system-wide MIDI player for the given track type, either MIDI_SFX or MIDI_BGM. | |
| #define MIDI_DBG | ( | ... | ) |
| #define PRINT_VOICE_VOLUME | ( | voice | ) |
| #define OSC_DITHER |
| #define UINT14_MAX (0x3FFF) |
| #define SET_MSB | ( | target, | |
| val ) |
Set only the MSB of a 14-bit value.
| #define SET_LSB | ( | target, | |
| val ) |
Set only the LSB of a 14-bit value.
| #define SHIFT_HI_HAT (0) |
| #define SHIFT_WHISTLE (6) |
| #define SHIFT_GUIRO (12) |
| #define SHIFT_CUICA (18) |
| #define SHIFT_TRIANGLE (24) |
| #define MASK_HI_HAT (0x3F) |
| #define MASK_WHISTLE (0x3F << SHIFT_WHISTLE) |
| #define MASK_GUIRO (0x3F << SHIFT_GUIRO) |
| #define MASK_CUICA (0x3F << SHIFT_CUICA) |
| #define MASK_TRIANGLE (0x3F << SHIFT_TRIANGLE) |
| #define VOICE_FREE (0x3F) |
| const midiTimbre_t * getTimbreForProgram | ( | bool | percussion, |
| uint8_t | bank, | ||
| uint8_t | program ) |
Return a pointer to the predefined timbre assigned to the given bank and program IDs.
If no timbre is assigned, the default (Acoustic Grand Piano) will be used
| percussion | True to return the percussion timbre for the bank, otherwise a pitched timbre |
| bank | The bank to select the instrument from, from 0 to 127 with 0 being the GM instruments |
| program | The program ID within the bank corresponding to the timbre, from 0 to 127 |
| void midiPlayerInit | ( | midiPlayer_t * | player | ) |
Initialize the MIDI player.
| player | The MIDI player to initialize |
| void midiPlayerReset | ( | midiPlayer_t * | player | ) |
Reset the MIDI player state.
| player | The MIDI player to reset |
| void midiPlayerResetNewSong | ( | midiPlayer_t * | player | ) |
Reset the MIDI player state by only doing the bare minimum. This is useful when playing multiple sound effects in quick succession.
| player | The MIDI player to reset |
| int32_t midiPlayerStep | ( | midiPlayer_t * | player | ) |
Calculate and return the next MIDI sample, stepping the player state forward by one sample.
| player | The player to step forward |
| void midiPlayerFillBuffer | ( | midiPlayer_t * | player, |
| uint8_t * | samples, | ||
| int16_t | len ) |
Fill a buffer with the next set of samples from the MIDI player. This should be called by the callback passed into initDac(). Samples are generated at sampling rate of DAC_SAMPLE_RATE_HZ.
| player | The MIDI player to sample from |
| samples | An array of unsigned 8-bit samples to fill |
| len | The length of the array to fill |
| void midiPlayerFillBufferMulti | ( | midiPlayer_t * | players, |
| uint8_t | playerCount, | ||
| uint8_t * | samples, | ||
| int16_t | len ) |
Fill a buffer with the next set of samples from an array of MIDI players.
| players | A pointer to an array of MIDI players |
| playerCount | The number of MIDI players in the array |
| samples | An array of unsigned 8-bit samples to fill |
| len | The length of the array to fill |
| void midiAllSoundOff | ( | midiPlayer_t * | player | ) |
Stop all sound immediately. This is not affected by the sustain pedal.
| player | The player to stop |
| void midiResetChannelControllers | ( | midiPlayer_t * | player, |
| uint8_t | channel ) |
Reset all controllers on a MIDI channel.
This includes:
| player | |
| channel |
| void midiGmOn | ( | midiPlayer_t * | player | ) |
Activate General MIDI mode on a MIDI player.
| player | The MIDI player to set to General MIDI mode |
| void midiGmOff | ( | midiPlayer_t * | player | ) |
Deactivate General MIDI mode on a MIDI player.
| player | The MIDI player to take out of General MIDI mode |
| void midiAllNotesOff | ( | midiPlayer_t * | player, |
| uint8_t | channel ) |
Tun off all notes which are currently on, as though midiNoteOff() were called for each note. This respects the sustain pedal.
| player | The MIDI player |
| channel | The MIDI channel on which to stop notes |
| const midiVoice_t * soundNoteOn | ( | midiPlayer_t * | player, |
| uint8_t | chanId, | ||
| uint8_t | note, | ||
| uint8_t | velocity, | ||
| const midiTimbre_t * | timbre, | ||
| bool | percussion ) |
Play a single note with custom MIDI parameters, without affecting any existing channel settings.
| player | The MIDI player to play the note on |
| chanId | The channel ID to used. A channel number greater than 15 may be used, as a sort of tag |
| note | The MIDI note to play |
| velocity | The note velocity, which controls its volume |
| timbre | A reference to the timbre, which defines all instrument parameters. No reference is kept. |
| percussion | True to assign the note to a percussion voice, false to use a normal voices |
| void soundNoteOff | ( | midiPlayer_t * | player, |
| uint8_t | chanId, | ||
| uint8_t | note, | ||
| uint8_t | velocity, | ||
| bool | percussion ) |
Stop playing a single note with custom MIDI parameters.
| player | The MIDI player to stop the note playing on |
| chanId | The channel ID passed to soundNoteOn(). A channel number greater than 15 may be used |
| note | The MIDI note to stop playing |
| velocity | The note off velocity, which is not used but could affect release speed |
| percussion | True to stop a note played with percussion voices, false to stop a note played with normal voices |
| void soundVoiceOff | ( | midiPlayer_t * | player, |
| const midiVoice_t * | voice ) |
Immediately stop a single voice from playing, disregarding all ADSR parameters.
| player | The MIDI player that owns the voice |
| voice | The voice returned by soundNoteOn() |
| void soundVoiceRelease | ( | midiPlayer_t * | player, |
| const midiVoice_t * | voice ) |
Transition the given voice into the 'release' state, equivalent to a MIDI Note Off.
| player | The MIDI player that owns the voice |
| voice |
| void midiNoteOn | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| uint8_t | note, | ||
| uint8_t | velocity ) |
Begin playing a note on a given MIDI channel.
Using a velocity of 0 is equivalent to calling midiNoteOff()
| player | The MIDI player |
| channel | The MIDI channel on which to start the note |
| note | The note number to play |
| velocity | The note velocity which affects its volume and effects |
| void midiAfterTouch | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| uint8_t | note, | ||
| uint8_t | velocity ) |
Change the velocity of a note on a given MIDI channel, after the note starts playing.
| player | The MIDI player |
| channel | The MIDI channel on which to change the note velocity |
| note | The currently-playing note number to modify |
| velocity | The note velocity which affects its volume and effects |
| void midiNoteOff | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| uint8_t | note, | ||
| uint8_t | velocity ) |
Stop playing a particular note on a given MIDI channel.
| player | The MIDI player |
| channel | The MIDI channel on which to stop the note |
| note | The note number to stop |
| velocity | [NYI] The release velocity which affects the note's release time |
| void midiSetProgram | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| uint8_t | program ) |
Change the program (instrument) on a given MIDI channel.
| player | The MIDI player |
| channel | The MIDI channel whose program will be changed |
| program | The program ID, from 0-127, to set for this channel |
| void midiSustain | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| uint8_t | val ) |
Set the hold pedal status.
When set, all notes that are currently on will be sustained until the pedal is unset, as well as all notes that are played after the pedal is set.
This is a convenience method for midiControlChange(player, channel, MCC_HOLD_PEDAL (64), val ? 127:0)
| player | The MIDI player |
| channel | The MIDI channel to set the hold status for |
| val | The sustain pedal value. Values 0-63 are OFF, and 64-127 are ON. |
| void midiSustenuto | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| uint8_t | val ) |
Set the sustenuto pedal status.
When set, only the notes that are currently on will be sustained until the pedal is unset. Notes that are played after the pedal is set will not be sustained.
| player | The MIDI player |
| channel | The MIDI channel to set the sustenuto status for |
| val | The sustenuto pedal value. Values 0-63 are OFF, and 64-127 are ON. |
| void midiControlChange | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| midiControl_t | control, | ||
| uint8_t | val ) |
Set a MIDI control value.
| player | The MIDI player |
| channel | The channel to set the control on |
| control | The control number to set |
| val | The control value, from 0-127 whose meaning depends on the control number |
| uint8_t midiGetControlValue | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| midiControl_t | control ) |
Get the value of a MIDI control.
| player | The MIDI player |
| channel | The channel to retrieve the control from |
| control | The MIDI control number of the control |
| uint16_t midiGetControlValue14bit | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| midiControl_t | control ) |
Get the combined value of two MIDI control registers.
| player | The MIDI player |
| channel | The channel to retrieve the control from |
| control | The MIDI control number of either of the two controls that make up the value |
| void midiSetParameter | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| bool | registered, | ||
| uint16_t | param, | ||
| uint16_t | value ) |
Set a registered or non-registered parameter value.
| player | The MIDI player |
| channel | The channel to set the parameter on |
| registered | true if param refers to a registered parameter number and false if it refers to a non-registered |
| param | The registered or non-registered MIDI parameter to set the value of |
| value | The 14-bit value to set the parameter to |
| uint16_t midiGetParameterValue | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| bool | registered, | ||
| uint16_t | param ) |
Get the value of a registered or non-registered parameter.
| player | The MIDI player |
| channel | The channel to retrieve the parameter from |
| registered | true if param refers to a registered parameter number and false if it refers to a non-registered |
| param | The registered or non-registered MIDI parameter number to retrieve the value for |
| void midiPitchWheel | ( | midiPlayer_t * | player, |
| uint8_t | channel, | ||
| uint16_t | value ) |
Set the pitch wheel value on a given MIDI channel.
By default, the center of the pitch wheel is 0x2000. A value of 0x0000 transposes one step down, while a value of 0x3FFF transposes one step down.
[NYI] The range of the pitch wheel can be changed using the registered parameters, with MSB being the range in (+/-)semitones and LSB being the range in (+/-) cents
| player | The MIDI player |
| channel | The MIDI channel to change the pitch wheel for |
| value | The pitch wheel value, from 0 to 0x3FFF (14-bits) |
| void midiSetTempo | ( | midiPlayer_t * | player, |
| uint32_t | tempo ) |
Change the MIDI playback tempo.
| player | The player to change the tempo of |
| tempo | The new tempo to set, in microseconds per quarter note |
| void midiSetFile | ( | midiPlayer_t * | player, |
| const midiFile_t * | file ) |
Configure this MIDI player to read from a MIDI file.
| player | The MIDI player |
| file | A pointer to the MIDI file to be played |
| void midiPause | ( | midiPlayer_t * | player, |
| bool | pause ) |
Set the paused state of a MIDI song.
| player | The player |
| pause | True to pause, false to play |
| void midiSeek | ( | midiPlayer_t * | player, |
| uint32_t | ticks ) |
Seek to a given time offset within a file.
Note that in the current implementation, seeking backwards by any amount requires re-reading the file from the beginning, and so may be very slow, particularly for large MIDI files.
| player | The MIDI player to seek on |
| ticks | The absolute number of MIDI ticks to seek to. If this is -1, it will seek to the end of the song |
| void initGlobalMidiPlayer | ( | void | ) |
Initialize the system-wide MIDI players for both BGM and SFX.
| void deinitGlobalMidiPlayer | ( | void | ) |
Deinitialize and free memory associated with the system-wide MIDI players.
| void globalMidiPlayerFillBuffer | ( | uint8_t * | samples, |
| int16_t | len ) |
Fill the given sample buffer with samples from both the BGM and SFX system-wide MIDI players.
| [out] | samples | A pointer to the array of unsigned 8-bit samples to be filled |
| len | The number of samples |
| void globalMidiPlayerPlaySong | ( | midiFile_t * | song, |
| uint8_t | trackType ) |
Play a song on one of the system-wide MIDI players, either BGM or SFX.
| song | A pointer to the song to play |
| trackType | The player to use, either MIDI_SFX or MIDI_BGM |
| void globalMidiPlayerPlaySongCb | ( | midiFile_t * | song, |
| uint8_t | trackType, | ||
| songFinishedCbFn | cb ) |
Play a song on one of the system-wide MIDI players, with a callback once the song finishes.
| song | A pointer to the song to play |
| trackType | The player to use, either MIDI_SFX or MIDI_BGM |
| cb | The function to be called once the song completes |
| void globalMidiPlayerSetVolume | ( | uint8_t | trackType, |
| int32_t | volumeSetting ) |
Set the volume using a value from 0 to 13.
| trackType | The player to set the volume for, either MIDI_SFX or MIDI_BGM |
| volumeSetting | The volume value |
| void globalMidiPlayerPauseAll | ( | void | ) |
Pause all songs currently being played by the system-wide MIDI players.
| void globalMidiPlayerResumeAll | ( | void | ) |
Resume all songs currently being played by the system-wide MIDI players.
| void globalMidiPlayerStop | ( | bool | reset | ) |
Stop all songs currently being played by the system-wide MIDI players, optionally resetting their state to the beginning of the song.
| reset | if true, the players will be reset to the beginning of the song |
| midiPlayer_t * globalMidiPlayerGet | ( | uint8_t | trackType | ) |
Return a pointer to the system-wide MIDI player for the given track type, either MIDI_SFX or MIDI_BGM.
| trackType | Which MIDI player to return, either MIDI_SFX or MIDI_BGM |