## IpatchSF2Mod IpatchSF2Mod — SoundFont modulators |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchSF2Mod;
    typedef             IpatchSF2ModList;
    #define             IPATCH_TYPE_SF2_MOD
    #define             IPATCH_TYPE_SF2_MOD_LIST
    #define             IPATCH_SF2_MOD_ARE_IDENTICAL        (a, b)
    #define             IPATCH_SF2_MOD_ARE_IDENTICAL_AMOUNT (a, b)
    enum                IpatchSF2ModFieldMasks;
    enum                IpatchSF2ModFieldShifts;
    enum                IpatchSF2ModControl;
    enum                IpatchSF2ModControlPalette;
    enum                IpatchSF2ModDirection;
    enum                IpatchSF2ModPolarity;
    enum                IpatchSF2ModType;
    enum                IpatchSF2ModTransform;
    enum                IpatchSF2ModFlags;
    GType               ipatch_sf2_mod_get_type             (void);
    GType               ipatch_sf2_mod_list_get_type        (void);
    IpatchSF2Mod *      ipatch_sf2_mod_new                  (void);
    void                ipatch_sf2_mod_free                 (IpatchSF2Mod *mod);
    IpatchSF2Mod *      ipatch_sf2_mod_duplicate            (const IpatchSF2Mod *mod);
    GSList *            ipatch_sf2_mod_list_duplicate       (const GSList *list);
    GSList *            ipatch_sf2_mod_list_override        (const GSList *alist,
                                                             const GSList *blist,
                                                             gboolean copy);
    void                ipatch_sf2_mod_list_boxed_free      (GSList *list);
    GSList *            ipatch_sf2_mod_list_insert          (GSList *mods,
                                                             const IpatchSF2Mod *modvals,
                                                             int pos);
    GSList *            ipatch_sf2_mod_list_remove          (GSList *mods,
                                                             const IpatchSF2Mod *modvals,
                                                             gboolean *changed);
    gboolean            ipatch_sf2_mod_list_change          (GSList *mods,
                                                             const IpatchSF2Mod *oldvals,
                                                             const IpatchSF2Mod *newvals);
    GSList *            ipatch_sf2_mod_list_offset          (const GSList *alist,
                                                             const GSList *blist);
    void                ipatch_sf2_mod_list_free            (GSList *list,
                                                             gboolean free_mods);
    const GSList *      ipatch_sf2_mod_list_get_default     (void);

## Description

SoundFont modulators are used to define real time MIDI effect controls.

## Details

### IpatchSF2Mod

    typedef struct {
      guint16 src;			/* source modulator (MIDI controller, etc) */
      guint16 dest;			/* destination generator */
      gint16 amount;		/* degree of modulation */
      guint16 amtsrc;		/* second source controls amount of first */
      guint16 trans;		/* transform function applied to source */
    } IpatchSF2Mod;

### IpatchSF2ModList

    typedef GSList IpatchSF2ModList;

### IPATCH_TYPE_SF2_MOD

    #define IPATCH_TYPE_SF2_MOD   (ipatch_sf2_mod_get_type ())

### IPATCH_TYPE_SF2_MOD_LIST

    #define IPATCH_TYPE_SF2_MOD_LIST   (ipatch_sf2_mod_list_get_type ())

### IPATCH_SF2_MOD_ARE_IDENTICAL()

    #define             IPATCH_SF2_MOD_ARE_IDENTICAL(a, b)

### IPATCH_SF2_MOD_ARE_IDENTICAL_AMOUNT()

    #define             IPATCH_SF2_MOD_ARE_IDENTICAL_AMOUNT(a, b)

### enum IpatchSF2ModFieldMasks

    typedef enum
    {
      IPATCH_SF2_MOD_MASK_CONTROL = 0x007F,
      IPATCH_SF2_MOD_MASK_CC = 0x0080,
      IPATCH_SF2_MOD_MASK_DIRECTION = 0x0100,
      IPATCH_SF2_MOD_MASK_POLARITY = 0x0200,
      IPATCH_SF2_MOD_MASK_TYPE = 0xFC00
    } IpatchSF2ModFieldMasks;

### enum IpatchSF2ModFieldShifts

    typedef enum
    {
      IPATCH_SF2_MOD_SHIFT_CONTROL = 0,
      IPATCH_SF2_MOD_SHIFT_CC = 7,
      IPATCH_SF2_MOD_SHIFT_DIRECTION = 8,
      IPATCH_SF2_MOD_SHIFT_POLARITY = 9,
      IPATCH_SF2_MOD_SHIFT_TYPE = 10
    } IpatchSF2ModFieldShifts;

### enum IpatchSF2ModControl

    typedef enum
    {
      IPATCH_SF2_MOD_CONTROL_NONE = 0,
      IPATCH_SF2_MOD_CONTROL_NOTE_ON_VELOCITY = 2,
      IPATCH_SF2_MOD_CONTROL_NOTE_NUMBER = 3,
      IPATCH_SF2_MOD_CONTROL_POLY_PRESSURE = 10,
      IPATCH_SF2_MOD_CONTROL_CHAN_PRESSURE = 13,
      IPATCH_SF2_MOD_CONTROL_PITCH_WHEEL = 14,
      IPATCH_SF2_MOD_CONTROL_BEND_RANGE = 16
    } IpatchSF2ModControl;

### enum IpatchSF2ModControlPalette

    typedef enum
    {
      IPATCH_SF2_MOD_CC_GENERAL = (0 << IPATCH_SF2_MOD_SHIFT_CC),
      IPATCH_SF2_MOD_CC_MIDI = (1 << IPATCH_SF2_MOD_SHIFT_CC)
    } IpatchSF2ModControlPalette;

### enum IpatchSF2ModDirection

    typedef enum
    {
      IPATCH_SF2_MOD_DIRECTION_POSITIVE = (0 << IPATCH_SF2_MOD_SHIFT_DIRECTION),
      IPATCH_SF2_MOD_DIRECTION_NEGATIVE = (1 << IPATCH_SF2_MOD_SHIFT_DIRECTION)
    } IpatchSF2ModDirection;

### enum IpatchSF2ModPolarity

    typedef enum
    {
      IPATCH_SF2_MOD_POLARITY_UNIPOLAR = (0 << IPATCH_SF2_MOD_SHIFT_POLARITY),
      IPATCH_SF2_MOD_POLARITY_BIPOLAR = (1 << IPATCH_SF2_MOD_SHIFT_POLARITY)
    } IpatchSF2ModPolarity;

### enum IpatchSF2ModType

    typedef enum
    {
      IPATCH_SF2_MOD_TYPE_LINEAR = (0 << IPATCH_SF2_MOD_SHIFT_TYPE),
      IPATCH_SF2_MOD_TYPE_CONCAVE = (1 << IPATCH_SF2_MOD_SHIFT_TYPE),
      IPATCH_SF2_MOD_TYPE_CONVEX = (2 << IPATCH_SF2_MOD_SHIFT_TYPE),
      IPATCH_SF2_MOD_TYPE_SWITCH = (3 << IPATCH_SF2_MOD_SHIFT_TYPE)
    } IpatchSF2ModType;

### enum IpatchSF2ModTransform

    typedef enum
    {
      IPATCH_SF2_MOD_TRANSFORM_LINEAR = 0
    } IpatchSF2ModTransform;

### enum IpatchSF2ModFlags

    typedef enum
    {
      IPATCH_SF2_MOD_NO_DUPLICATE	= 1 << 0,  /* don't duplicate mod list (owned!) */
      IPATCH_SF2_MOD_NO_NOTIFY	= 1 << 1   /* don't do item property notify */
    } IpatchSF2ModFlags;

### ipatch_sf2_mod_get_type ()

    GType               ipatch_sf2_mod_get_type             (void);

### ipatch_sf2_mod_list_get_type ()

    GType               ipatch_sf2_mod_list_get_type        (void);

### ipatch_sf2_mod_new ()

    IpatchSF2Mod *      ipatch_sf2_mod_new                  (void);

Create a new modulator

Returns : | New modulator

### ipatch_sf2_mod_free ()

    void                ipatch_sf2_mod_free                 (IpatchSF2Mod *mod);

Free an IpatchSF2Mod structure

`mod` : | Modulator to free, should not be referenced by any zones.

### ipatch_sf2_mod_duplicate ()

    IpatchSF2Mod *      ipatch_sf2_mod_duplicate            (const IpatchSF2Mod *mod);

Duplicate a modulator

`mod` : | Modulator to duplicate
Returns : | New duplicate modulator

### ipatch_sf2_mod_list_duplicate ()

    GSList *            ipatch_sf2_mod_list_duplicate       (const GSList *list);

Duplicates a modulator list (GSList and modulator data).

`list` : | Modulator list to duplicate
Returns : | New duplicate modulator list which should be freed with `ipatch_sf2_mod_list_free()` with `free_mods` set to `TRUE` when finished with it.

### ipatch_sf2_mod_list_override ()

    GSList *            ipatch_sf2_mod_list_override        (const GSList *alist,
                                                             const GSList *blist,
                                                             gboolean copy);

Creates a new modulator list by combining `alist` and `blist`. Modulators in `blist` override identical modulators in `alist`. If `copy` is set then the modulator data is also duplicated (a new GSList is created).

`alist` : | First modulator list
`blist` : | Second modulator list
`copy` : | If `TRUE` then modulator data is duplicated
Returns : | New GSList of combined modulator lists. Should be freed with `ipatch_sf2_mod_list_free()` with the free_mods parameter set to the value of `copy`.

### ipatch_sf2_mod_list_boxed_free ()

    void                ipatch_sf2_mod_list_boxed_free      (GSList *list);

### ipatch_sf2_mod_list_insert ()

    GSList *            ipatch_sf2_mod_list_insert          (GSList *mods,
                                                             const IpatchSF2Mod *modvals,
                                                             int pos);

Inserts a modulator into a modulator list. Does not check for duplicates! The modulator is not used directly, a new one is created and the values in `mod` are copied to it.

`mods` : | Modulator list to insert into
`modvals` : | Modulator values to insert (a new modulator is created and the values are copied to it)
`pos` : | Index position in zone's modulator list to insert (0 = first, < 0 = last)
Returns : | New start (root) of `mods` list.

### ipatch_sf2_mod_list_remove ()

    GSList *            ipatch_sf2_mod_list_remove          (GSList *mods,
                                                             const IpatchSF2Mod *modvals,
                                                             gboolean *changed);

Remove a modulator from a modulator list. The modulator values in `modvals` are used to search the modulator list. The first modulator that matches all fields in `modvals` is removed.

`mods` : | Modulator list to remove from
`modvals` : | Values of modulator to remove
`changed` : | Pointer to store bool of whether the list was changed (`NULL` to ignore)

### ipatch_sf2_mod_list_change ()

    gboolean            ipatch_sf2_mod_list_change          (GSList *mods,
                                                             const IpatchSF2Mod *oldvals,
                                                             const IpatchSF2Mod *newvals);

Sets the values of an existing modulator in a modulator list. The list is searched for a modulator that matches the values in `oldvals`. If a modulator is found its values are set to those in `newvals`. If it is not found, nothing is done.

`mods` : | Modulator list to change a modulator in
`oldvals` : | Current values of modulator to set
`newvals` : | New modulator values
Returns : | `TRUE` if changed, `FALSE` otherwise (no match)

### ipatch_sf2_mod_list_offset ()

    GSList *            ipatch_sf2_mod_list_offset          (const GSList *alist,
                                                             const GSList *blist);

Creates a new modulator list by combining `list` and `blist`. Modulators in `blist` offset (amounts are added) identical modulators in `alist`. Operation is non-destructive as a new list is created and modulator data is duplicated.

NOTE: Optimized for empty `blist`.

`alist` : | First modulator list
`blist` : | Second modulator list
Returns : | New GSList of combined modulator lists. Should be freed with `ipatch_sf2_mod_list_free()` with `free_mods` set to `TRUE` when finished with it.

### ipatch_sf2_mod_list_free ()

    void                ipatch_sf2_mod_list_free            (GSList *list,
                                                             gboolean free_mods);

Like `ipatch_sf2_mod_list_free()` but used for boxed type declaration and so therefore frees all modulators in the list.

`list` : | Modulator list to free

### ipatch_sf2_mod_list_get_default ()

    const GSList *      ipatch_sf2_mod_list_get_default     (void);

Get the list of default instrument modulators.

Returns : | The list of default modulators. The same modulator list is returned on subsequent calls and should not be modified or freed.