From 9778dc47c3866af3e3e5e3cf5f96860431d51dc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Mo=C5=84?= Date: Sat, 14 Mar 2009 14:23:18 +0100 Subject: [PATCH] add comments --- TODO | 1 + effects.c | 47 +++++++++++++-- effects.h | 4 +- gdigi.c | 174 ++++++++++++++++++++++++++++++++++++++---------------- gdigi.h | 4 +- tests.c | 3 - 6 files changed, 170 insertions(+), 63 deletions(-) diff --git a/TODO b/TODO index 304642b..ae92e20 100644 --- a/TODO +++ b/TODO @@ -3,3 +3,4 @@ -handling presets (saving, exporting to xml patches) -buildsystem (install knob.png to share dir, don't use inline knob pixbuf) -add expression pedal settings to gui +-read asynchronously from MIDI IN diff --git a/effects.c b/effects.c index 72258f1..5769c89 100644 --- a/effects.c +++ b/effects.c @@ -735,7 +735,7 @@ EffectList effects[] = { int n_effects = G_N_ELEMENTS(effects); typedef struct { - const gchar *label; + gchar *label; guint id; guint position; EffectValues *values; @@ -879,8 +879,14 @@ static Modifier modifiers[] = { int n_modifiers = G_N_ELEMENTS(modifiers); -/* - returned value must not be freed +/** + * get_modifier: + * @id: modifier ID + * @position: modifier position + * + * Gets modifier info. + * + * Return value: Modifier which must not be freed, or NULL if no matching Modifier has been found. */ static Modifier *get_modifier(guint id, guint position) { @@ -893,6 +899,14 @@ static Modifier *get_modifier(guint id, guint position) return NULL; } +/** + * get_modifier_settings: + * @values: possible setting values + * + * Creates EffectSettings containing expression pedal min and max settings. + * + * Return value: EffectSettings which must be freed using effect_settings_free. + **/ static EffectSettings *get_modifier_settings(EffectValues *values) { if (values == NULL) @@ -913,6 +927,24 @@ static EffectSettings *get_modifier_settings(EffectValues *values) return settings; } +/** + * effect_settings_free: + * @settings: settings to be freed + * + * Frees all memory used by EffectSettings. + **/ +static void effect_settings_free(EffectSettings *settings) +{ + g_slice_free1(2 * sizeof(EffectSettings), settings); +} + +/** + * modifier_linkable_list: + * + * Retrieves modifier linkable gruop from device. + * + * Return value: ModifierGroup which must be freed using modifier_group_free. + **/ ModifierGroup *modifier_linkable_list() { guint group_id; @@ -963,6 +995,12 @@ ModifierGroup *modifier_linkable_list() return modifier_group; } +/** + * modifier_group_free: + * @modifier_group: group to be freed + * + * Frees all memory used by ModifierGroup. + **/ void modifier_group_free(ModifierGroup *modifier_group) { g_return_if_fail(modifier_group != NULL); @@ -970,8 +1008,7 @@ void modifier_group_free(ModifierGroup *modifier_group) int x; for (x=0; xgroup_amt; x++) { if (modifier_group->group[x].settings) - g_slice_free1(2 * sizeof(EffectSettings), - modifier_group->group[x].settings); + effect_settings_free(modifier_group->group[x].settings); } g_slice_free1(modifier_group->group_amt * sizeof(EffectGroup), modifier_group->group); diff --git a/effects.h b/effects.h index 0df1ee6..7356994 100644 --- a/effects.h +++ b/effects.h @@ -26,7 +26,7 @@ typedef struct { } EffectValues; typedef struct { - char *label; /* Parameter name */ + gchar *label; /* Parameter name */ guint id; /* ID (to set parameter) */ guint position; /* position */ EffectValues *values; /* valid parameter values */ @@ -42,7 +42,7 @@ typedef struct { } EffectGroup; typedef struct { - char *label; /* Base effect name */ + gchar *label; /* Base effect name */ guint id; /* ID (to set effect on/off) */ guint position; /* position */ EffectGroup *group; /* possible effect types */ diff --git a/gdigi.c b/gdigi.c index 68c5d44..b70045e 100644 --- a/gdigi.c +++ b/gdigi.c @@ -51,10 +51,13 @@ static char calculate_checksum(gchar *array, gint length) return checksum; } -/* - opens MIDI device - Returns TRUE on error -*/ +/** + * open_device: + * + * Opens MIDI device. This function modifies global input and output variables. + * + * Return value: FALSE on success, TRUE on error. + **/ gboolean open_device() { int err; @@ -76,14 +79,27 @@ gboolean open_device() return FALSE; } +/** + * send_data: + * @data: data to be sent + * @length: data length + * + * Sends data to device. This function uses global output variable. + **/ void send_data(char *data, int length) { - if (output == NULL) - open_device(); - snd_rawmidi_write(output, data, length); } +/** + * pack_data: + * @data: data to be packed + * @len: data length + * + * Packs data using method used on all newer DigiTech products. + * + * Return value: GString containing packed data + **/ GString *pack_data(gchar *data, gint len) { GString *packed; @@ -114,6 +130,12 @@ GString *pack_data(gchar *data, gint len) return packed; } +/** + * unpack_message: + * @msg: message to unpack + * + * Unpacks message data. This function modifies given GString. + **/ static void unpack_message(GString *msg) { int offset; @@ -152,11 +174,13 @@ static void unpack_message(GString *msg) g_string_truncate(msg, i); } -/* - reads data from MIDI IN - returns GString containing data - if no data was read it returns NULL -*/ +/** + * read_data: + * + * Reads data from MIDI IN. This function uses global input variable. + * + * Return value: GString containing data, or NULL when no data was read. + **/ GString* read_data() { /* This is mostly taken straight from alsa-utils-1.0.19 amidi/amidi.c @@ -220,19 +244,14 @@ GString* read_data() return string; } -static void clear_midi_in_buffer() -{ - GString *str; - - do { - str = read_data(); - } while (str != NULL); -} - -/* - data - unpacked data to send - len - data length -*/ +/** + * send_message: + * @procedure: procedure ID + * @data: unpacked message data + * @len: data length + * + * Creates SysEx message then sends it. This function uses folowing global variables: device_id, family_id and product_id. + **/ void send_message(gint procedure, gchar *data, gint len) { GString *msg = g_string_new_len("\xF0" /* SysEx status byte */ @@ -258,8 +277,17 @@ void send_message(gint procedure, gchar *data, gint len) g_string_free(msg, TRUE); } -static gint get_message_id(GString *msg) +/** + * get_message_id: + * @msg: SysEx message + * + * Checks message ID. + * + * Return value: MessageID, or -1 on error. + **/ +static MessageID get_message_id(GString *msg) { + /* TODO: sanity checks */ g_return_val_if_fail(msg != NULL, -1); if (msg->len > 7) { @@ -268,6 +296,14 @@ static gint get_message_id(GString *msg) return -1; } +/** + * get_message_by_id: + * @id: MessageID of requested message + * + * Reads data from MIDI IN until message with matching id is found. + * + * Return value: GString containing unpacked message. + **/ GString *get_message_by_id(MessageID id) { GString *data = NULL; @@ -283,6 +319,13 @@ GString *get_message_by_id(MessageID id) return data; } +/** + * append_value: + * @msg: message to append value + * @value: value to append + * + * Packs value using scheme used on all newer DigiTech products. + **/ void append_value(GString *msg, guint value) { /* check how many bytes long the value is */ @@ -310,11 +353,14 @@ void append_value(GString *msg, guint value) } } -/* - id - ID as found in preset file - position - Position as found in preset file - value - Value as found in preset file -*/ +/** + * set_option: + * @id: Parameter ID + * @position: Parameter position + * @value: Parameter value + * + * Forms SysEx message to set parameter then sends it to device. + **/ void set_option(guint id, guint position, guint value) { GString *msg = g_string_sized_new(9); @@ -326,7 +372,13 @@ void set_option(guint id, guint position, guint value) g_string_free(msg, TRUE); } -/* x = 0 to 60 */ +/** + * switch_preset: + * @bank: preset bank + * @x: preset index + * + * Switches to selected preset. + **/ void switch_preset(guint bank, guint x) { GString *msg = g_string_sized_new(6); @@ -339,12 +391,13 @@ void switch_preset(guint bank, guint x) g_string_free(msg, TRUE); } -/* level = 0 to 99 */ -void set_preset_level(int level) -{ - set_option(PRESET_LEVEL, PRESET_POSITION, level); -} - +/** + * store_preset_name: + * @x: preset index + * @name: preset name + * + * Stores current edit buffer in user presets bank. + **/ void store_preset_name(int x, const gchar *name) { GString *msg = g_string_sized_new(6); @@ -357,7 +410,13 @@ void store_preset_name(int x, const gchar *name) g_string_free(msg, TRUE); } -/* x = 0 to 59 (preset number) */ +/** + * set_preset_name: + * @x: preset index + * @name: preset name + * + * Sets preset name. + **/ void set_preset_name(int x, gchar *name) { GString *msg = g_string_sized_new(12); @@ -369,12 +428,14 @@ void set_preset_name(int x, gchar *name) g_string_free(msg, TRUE); } -/* - Queries user preset names - Valid bank values are PRESETS_SYSTEM and PRESETS_USER - Returns GStrv which must be freed with g_strfreev - Returns NULL on error -*/ +/** + * query_preset_names: + * @bank: preset bank + * + * Queries preset names. + * + * Return value: GStrv which must be freed with g_strfreev, or NULL on error. + **/ GStrv query_preset_names(gchar bank) { GString *data = NULL; @@ -383,9 +444,6 @@ GStrv query_preset_names(gchar bank) int n_total; /* total number of presets */ gchar **str_array = NULL; - /* clear MIDI IN buffer */ - clear_midi_in_buffer(); - /* query user preset names */ send_message(REQUEST_PRESET_NAMES, &bank, 1); @@ -412,13 +470,17 @@ GStrv query_preset_names(gchar bank) return str_array; } +/** + * get_current_preset: + * + * Queries current edit buffer. + * + * Return value: GString containing RECEIVE_PRESET_PARAMETERS SysEx message. + **/ GString *get_current_preset() { GString *data = NULL; - /* clear MIDI IN buffer */ - clear_midi_in_buffer(); - send_message(REQUEST_PRESET, "\x04\x00", 3); /* read reply */ @@ -427,6 +489,16 @@ GString *get_current_preset() return data; } +/** + * request_who_am_i: + * @device_id: Variable to hold device ID + * @family_id: Variable to hold family ID + * @product_id: Variable to hold product ID + * + * Requests device information. + * + * Return value: TRUE on success, FALSE on error. + **/ static gboolean request_who_am_i(unsigned char *device_id, unsigned char *family_id, unsigned char *product_id) { diff --git a/gdigi.h b/gdigi.h index 3f6921d..124034e 100644 --- a/gdigi.h +++ b/gdigi.h @@ -539,7 +539,7 @@ enum { #define USB_AUDIO_PLAYBACK_MIX 12297 #define USB_AUDIO_LEVEL 12307 -enum { +typedef enum { PRESETS_SYSTEM = 0, PRESETS_USER = 1, PRESETS_ARTIST = 2, @@ -551,7 +551,7 @@ enum { /* Version 2 and later */ PRESETS_EXTERNAL = 6 -}; +} PresetBank; typedef enum { REQUEST_WHO_AM_I = 0x01, diff --git a/tests.c b/tests.c index e1fd270..a82adb5 100644 --- a/tests.c +++ b/tests.c @@ -210,9 +210,6 @@ void test_presets() for (x=0; x<=60; x++) switch_preset(PRESETS_SYSTEM, x); - - for (x=0; x<=99; x++) - set_preset_level(x); } void test_pickups()