Per-song functions and callbacks in Modipulate.

Data Structures
struct	ModipulateSongInfo
Typedefs
typedef void *	ModipulateSong
typedef void(*	modipulate_song_pattern_change_cb )(ModipulateSong song, int pattern_number, void *user_data)
typedef void(*	modipulate_song_note_cb )(ModipulateSong song, unsigned channel, int note, int instrument, int sample, int volume_command, int volume_value, int effect_command, int effect_value, void *user_data)
typedef void(*	modipulate_song_row_change_cb )(ModipulateSong song, int row, void *user_data)
Functions
ModipulateErr	modipulate_song_load (const char *filename, ModipulateSong *song)
ModipulateErr	modipulate_song_unload (ModipulateSong song)
ModipulateErr	modipulate_song_play (ModipulateSong song, int play)
ModipulateErr	modipulate_song_get_info (ModipulateSong song, ModipulateSongInfo **song_info)
ModipulateErr	modipulate_song_info_free (ModipulateSongInfo *song_info)
ModipulateErr	modipulate_song_volume_command (ModipulateSong song, unsigned channel, int volume_command, int volume_value)
ModipulateErr	modipulate_song_enable_volume (ModipulateSong song, unsigned channel, int volume_command, int enable)
ModipulateErr	modipulate_song_effect_command (ModipulateSong song, unsigned channel, int effect_command, int effect_value)
ModipulateErr	modipulate_song_enable_effect (ModipulateSong song, unsigned channel, int effect_command, int enable)
ModipulateErr	modipulate_song_set_transposition (ModipulateSong song, unsigned channel, int offset)
ModipulateErr	modipulate_song_get_transposition (ModipulateSong song, unsigned channel, int *offset)
void	modipulate_song_set_channel_enabled (ModipulateSong song, unsigned channel, int enabled)
int	modipulate_song_get_channel_enabled (ModipulateSong song, unsigned channel)
ModipulateErr	modipulate_song_on_pattern_change (ModipulateSong song, modipulate_song_pattern_change_cb cb, void *user_data)
ModipulateErr	modipulate_song_on_row_change (ModipulateSong song, modipulate_song_row_change_cb cb, void *user_data)
ModipulateErr	modipulate_song_on_note (ModipulateSong song, modipulate_song_note_cb cb, void *user_data)

---

Typedef Documentation

typedef void(* modipulate_song_note_cb)(ModipulateSong song, unsigned channel, int note, int instrument, int sample, int volume_command, int volume_value, int effect_command, int effect_value, void *user_data)

Note change callback.

Called whenever a note is issued.

Parameters:

song	Song that triggered this callback.
channel	Channel number that this note is on.
note	Note number, where each step is a semitone.
instrument	Instrument number or -1 if none
sample	Sample number of -1 if none
volume_command	Identifier for the volume command type, or -1 if none
volume_value	Value of the command. Will be set to zero if volume_command is -1
effect_command	Identifier for the effect command type, or -1 if none
effect_value	Value of the command. Will be set to zero if effect_command is -1
user_data	Arbitrary per-song callback data.

typedef void(* modipulate_song_pattern_change_cb)(ModipulateSong song, int pattern_number, void *user_data)

Pattern change callback.

Called when the the pattern has changed.

Parameters:

song	Song that triggered this callback.
patter_number	Number of pattern that has started.
user_data	Arbitrary per-song callback data.

typedef void(* modipulate_song_row_change_cb)(ModipulateSong song, int row, void *user_data)

Row change callback

Parameters:

song	Song that triggered this callback.
row	The new row that has started playing.
user_data	Arbitrary per-song callback data.

typedef void* ModipulateSong

ID (or "handle") of a song loaded by Modipulate.

---

Function Documentation

ModipulateErr modipulate_song_effect_command	(	ModipulateSong	song,
		unsigned	channel,
		int	effect_command,
		int	effect_value
	)

Issues an effect command.

Parameters:

song	Song to act on.
channel	Channel number to issue the command on.
effect	Command ID to issue
effect	Command value

Returns:

Error

ModipulateErr modipulate_song_enable_effect	(	ModipulateSong	song,
		unsigned	channel,
		int	effect_command,
		int	enable
	)

Supresses effect commands on a given channel.

Note that commands issued by the user

Parameters:

song	Song to change
channel	Channel to enable or disable effects on
effect_command	The specific effect to supress.
enable	Whether to enable effect commands on this channel. True (1) is default. False (0) disables commands.

Returns:

Error

ModipulateErr modipulate_song_enable_volume	(	ModipulateSong	song,
		unsigned	channel,
		int	volume_command,
		int	enable
	)

Supresses effect commands on a given channel.

Parameters:

song	Song to change
channel	Channel to enable or disable effects on
volume_command	The specific volume command to supress.
enable	Whether to enable volume commands on this channel. True (1) is default. False (0) disables commands.

Returns:

Error

ModipulateErr modipulate_song_get_info	(	ModipulateSong	song,
		ModipulateSongInfo **	song_info
	)

Gets information about song.

Inspect meta information about the song such as the title and instrument names.

Parameters:

song	Song to retrieve information on.
song_info	[out] Metadata struct. Must not be null. Must free with modipulate_song_info_free()

Returns:

Error

ModipulateErr modipulate_song_get_transposition	(	ModipulateSong	song,
		unsigned	channel,
		int *	offset
	)

Returns the transposition offset for a given channel.

Parameters:

song	The song to act on.
channel	The channel to set the offset on.
offset	[out] The current semitone offset on this channel.

Returns:

Error

ModipulateErr modipulate_song_info_free

(

ModipulateSongInfo *

song_info

)

Frees a ModipulateSongInfo instance.

Parameters:

song_info

Metadata struct. Freed by this call; must ONLY be called once with given song_info.

Returns:

Error

ModipulateErr modipulate_song_load	(	const char *	filename,
		ModipulateSong *	song
	)

Loads a song into Modipulate.

Loads a song into memory. To play the song or pause it once it's started, call modipulate_song_play()

Parameters:

filename	Name of a MOD-style file to open (MOD, IT, XM, S3M, and many more). String must be null terminated.
song	[out] Song handle. Must not be null.

Returns:

Error

ModipulateErr modipulate_song_on_note	(	ModipulateSong	song,
		modipulate_song_note_cb	cb,
		void *	user_data
	)

Sets a callback to be triggered on a note event.

Parameters:

song	Song to set callback for
cb	Your callback function.
user_data	Arbitrary data to be passed to callback.

Returns:

Error

ModipulateErr modipulate_song_on_pattern_change	(	ModipulateSong	song,
		modipulate_song_pattern_change_cb	cb,
		void *	user_data
	)

Sets a callback to be triggered on a pattern change.

Parameters:

cb	your callback function

Returns:

Error

ModipulateErr modipulate_song_on_row_change	(	ModipulateSong	song,
		modipulate_song_row_change_cb	cb,
		void *	user_data
	)

Sets a callback to be triggered on a row change.

Parameters:

cb	your callback function

Returns:

Error

ModipulateErr modipulate_song_play	(	ModipulateSong	song,
		int	play
	)

Plays or pauses the song.

All songs start paused, this must be called to start them. Can also be used for pausing and unpausing audio.

Parameters:

song	Song to play or pause.
play	1 to play, 0 to pause

ModipulateErr modipulate_song_set_transposition	(	ModipulateSong	song,
		unsigned	channel,
		int	offset
	)

Sets a transposition offset for a given channel.

Parameters:

song	The song to act on.
channel	The channel to set the offset on.
offset	The semitone offset to set on this channel. Can be positive or negative. Zero means no offset.

Returns:

Error

ModipulateErr modipulate_song_unload

(

ModipulateSong

song

)

Unloads a song from Modipulate.

Frees a song from memory. Song will be stopped if playing.

Parameters:

song	Song to stop. The song ID is no longer valid after this call.
Error

ModipulateErr modipulate_song_volume_command	(	ModipulateSong	song,
		unsigned	channel,
		int	volume_command,
		int	volume_value
	)

Issues a volume command.

Parameters:

song	Song to act on.
channel	Channel number to issue the command on.
volume_command	Command ID to issue
volume_command	Command value

Returns:

Error