## IpatchSF2GenItem IpatchSF2GenItem — SoundFont generator item interface |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #define             IPATCH_SF2_GEN_ITEM_FIRST_PROP_ID
    #define             IPATCH_SF2_GEN_ITEM_FIRST_PROP_SET_ID
    #define             IPATCH_SF2_GEN_ITEM_FIRST_PROP_USER_ID
    typedef             IpatchSF2GenItem;
                        IpatchSF2GenItemIface;
    gboolean            ipatch_sf2_gen_item_get_amount      (IpatchSF2GenItem *item,
                                                             guint genid,
                                                             IpatchSF2GenAmount *out_amt);
    void                ipatch_sf2_gen_item_set_amount      (IpatchSF2GenItem *item,
                                                             guint genid,
                                                             IpatchSF2GenAmount *amt);
    void                ipatch_sf2_gen_item_set_gen_flag    (IpatchSF2GenItem *item,
                                                             guint genid,
                                                             gboolean setflag);
    guint               ipatch_sf2_gen_item_count_set       (IpatchSF2GenItem *item);
    void                ipatch_sf2_gen_item_copy_all        (IpatchSF2GenItem *item,
                                                             IpatchSF2GenArray *array);
    void                ipatch_sf2_gen_item_copy_set        (IpatchSF2GenItem *item,
                                                             IpatchSF2GenArray *array);
    void                ipatch_sf2_gen_item_set_note_range  (IpatchSF2GenItem *item,
                                                             int low,
                                                             int high);
    void                ipatch_sf2_gen_item_set_velocity_range
                                                            (IpatchSF2GenItem *item,
                                                             int low,
                                                             int high);
    gboolean            ipatch_sf2_gen_item_in_range        (IpatchSF2GenItem *item,
                                                             int note,
                                                             int velocity);
    gboolean            ipatch_sf2_gen_item_intersect_test  (IpatchSF2GenItem *item,
                                                             const IpatchSF2GenArray *genarray);
    GParamSpec *        ipatch_sf2_gen_item_class_get_pspec (GObjectClass *klass,
                                                             guint genid);
    GParamSpec *        ipatch_sf2_gen_item_class_get_pspec_set
                                                            (GObjectClass *klass,
                                                             guint genid);
    void                ipatch_sf2_gen_item_iface_install_properties
                                                            (GObjectClass *klass,
                                                             IpatchSF2GenPropsType propstype,
                                                             GParamSpec ***specs,
                                                             GParamSpec ***setspecs);
    gboolean            ipatch_sf2_gen_item_iface_set_property
                                                            (IpatchSF2GenItem *item,
                                                             guint property_id,
                                                             const GValue *value);
    gboolean            ipatch_sf2_gen_item_iface_get_property
                                                            (IpatchSF2GenItem *item,
                                                             guint property_id,
                                                             GValue *value);

## Object Hierarchy

      GInterface
       +----IpatchSF2GenItemIface

## Prerequisites

IpatchSF2GenItemIface requires IpatchItem.

## Known Implementations

IpatchSF2GenItemIface is implemented by IpatchSF2Inst, IpatchSF2PZone, IpatchSF2IZone and IpatchSF2Preset.

## Description

Provides an interface for items which have SoundFont generator properties. SoundFont generators are synthesis parameters used by IpatchSF2Preset, IpatchSF2Inst, IpatchSF2PZone and IpatchSF2IZone objects.

## Details

### IPATCH_SF2_GEN_ITEM_FIRST_PROP_ID

    #define IPATCH_SF2_GEN_ITEM_FIRST_PROP_ID	1	/* first gen prop */

### IPATCH_SF2_GEN_ITEM_FIRST_PROP_SET_ID

    #define IPATCH_SF2_GEN_ITEM_FIRST_PROP_SET_ID	80	/* first gen-set prop */

### IPATCH_SF2_GEN_ITEM_FIRST_PROP_USER_ID

    #define IPATCH_SF2_GEN_ITEM_FIRST_PROP_USER_ID	160	/* first ID usable for other properties */

### IpatchSF2GenItem

    typedef IpatchItem IpatchSF2GenItem;

### IpatchSF2GenItemIface

    typedef struct {
      IpatchSF2GenPropsType propstype;	/* gen properties type for this class */
      guint genarray_ofs;	/* offset in item instance to generator array pointer */
      GParamSpec *specs[IPATCH_SF2_GEN_COUNT];  /* genid -> prop pspec array */
      GParamSpec *setspecs[IPATCH_SF2_GEN_COUNT];  /* genid -> "-set" prop pspec array */
    } IpatchSF2GenItemIface;

### ipatch_sf2_gen_item_get_amount ()

    gboolean            ipatch_sf2_gen_item_get_amount      (IpatchSF2GenItem *item,
                                                             guint genid,
                                                             IpatchSF2GenAmount *out_amt);

Get a generator amount from an item with generator properties.

`item` : | Item with generators to get value from
`genid` : | Generator ID (IpatchSF2GenType) of value to get
`out_amt` : | Output: Pointer to store generator amount to
Returns : | `TRUE` if generator value is set, `FALSE` if not set, in which case the value stored to output_amt is the default value for the given generator ID.

### ipatch_sf2_gen_item_set_amount ()

    void                ipatch_sf2_gen_item_set_amount      (IpatchSF2GenItem *item,
                                                             guint genid,
                                                             IpatchSF2GenAmount *amt);

Set a generator amount for an item with generators.

IpatchItem property notify is done for the property and possibly the "-set" property if it was unset before.

`item` : | Item with generators to set value in
`genid` : | Generator ID (IpatchSF2GenType) of generator to set
`amt` : | Value to set generator to

### ipatch_sf2_gen_item_set_gen_flag ()

    void                ipatch_sf2_gen_item_set_gen_flag    (IpatchSF2GenItem *item,
                                                             guint genid,
                                                             gboolean setflag);

Sets the value of a generator "set" flag in an item with generators.

IpatchItem property notify is done for the property and possibly the "-set" property if it was set before.

`item` : | Item with generator properties to set value of a gen "set" flag of
`genid` : | Generator ID (IpatchSF2GenType) of generator to set "set" flag value of
`setflag` : | If `TRUE` then generatore amount is assigned, FALSE will cause the amount to be unset (and revert to its default value)

### ipatch_sf2_gen_item_count_set ()

    guint               ipatch_sf2_gen_item_count_set       (IpatchSF2GenItem *item);

Get count of "set" generators in an item with generators.

`item` : | Item with generators
Returns : | Count of "set" generators.

### ipatch_sf2_gen_item_copy_all ()

    void                ipatch_sf2_gen_item_copy_all        (IpatchSF2GenItem *item,
                                                             IpatchSF2GenArray *array);

Copies an item's generators to a caller supplied generator array.

`item` : | Item with generators
`array` : | Destination generator array to store to

### ipatch_sf2_gen_item_copy_set ()

    void                ipatch_sf2_gen_item_copy_set        (IpatchSF2GenItem *item,
                                                             IpatchSF2GenArray *array);

Copies a item's "set" generators to a caller supplied generator array. This function differs from `ipatch_sf2_gen_item_copy_all()` in that it only copies generators that are set. It can be used to override values in one array with set values in another. Note that this doesn't change any generators in `item`, despite "set" being in the name.

`item` : | Item with generators
`array` : | Destination generator array to store to

### ipatch_sf2_gen_item_set_note_range ()

    void                ipatch_sf2_gen_item_set_note_range  (IpatchSF2GenItem *item,
                                                             int low,
                                                             int high);

Set the MIDI note range that an item with generators is active on. Only a convenience function really.

`item` : | Item with generators
`low` : | Low value of range (MIDI note # between 0 and 127)
`high` : | High value of range (MIDI note # between 0 and 127)

### ipatch_sf2_gen_item_set_velocity_range ()

    void                ipatch_sf2_gen_item_set_velocity_range
                                                            (IpatchSF2GenItem *item,
                                                             int low,
                                                             int high);

Set the MIDI velocity range that an item with generators is active on. Only a convenience function really.

`item` : | Item with generators
`low` : | Low value of range (MIDI velocity # between 0 and 127)
`high` : | High value of range (MIDI velocity # between 0 and 127)

### ipatch_sf2_gen_item_in_range ()

    gboolean            ipatch_sf2_gen_item_in_range        (IpatchSF2GenItem *item,
                                                             int note,
                                                             int velocity);

Check if a note and velocity falls in the ranges of an item with generators

`item` : | Item with generators
`note` : | MIDI note number or -1 for wildcard
`velocity` : | MIDI velocity or -1 for wildcard
Returns : | `TRUE` if `item` is in `note` and `velocity` range, `FALSE` otherwise

### ipatch_sf2_gen_item_intersect_test ()

    gboolean            ipatch_sf2_gen_item_intersect_test  (IpatchSF2GenItem *item,
                                                             const IpatchSF2GenArray *genarray);

Check if a given item's note and velocity ranges intersect with those in a generator array.

`item` : | Item with generators
`genarray` : | Generator array to test note and velocity ranges against
Returns : | `TRUE` if both note and velocity ranges intersect, `FALSE` if one or both do not.

### ipatch_sf2_gen_item_class_get_pspec ()

    GParamSpec *        ipatch_sf2_gen_item_class_get_pspec (GObjectClass *klass,
                                                             guint genid);

Get the parameter specification for a given generator ID and object class.

`genid` : | Generator ID
`klass` : | Class with an IpatchSF2GenItem interface
Returns : | The parameter specification for the generator or `NULL` if the given `genid` for `klass` is not valid.

### ipatch_sf2_gen_item_class_get_pspec_set ()

    GParamSpec *        ipatch_sf2_gen_item_class_get_pspec_set
                                                            (GObjectClass *klass,
                                                             guint genid);

Get a "-set" property parameter specification for a given generator ID and object class.

`genid` : | Generator ID
`klass` : | Class with an IpatchSF2GenItem interface
Returns : | The "-set" property parameter specification for the generator or `NULL` if the given `genid` or `klass` are not valid.

### ipatch_sf2_gen_item_iface_install_properties ()

    void                ipatch_sf2_gen_item_iface_install_properties
                                                            (GObjectClass *klass,
                                                             IpatchSF2GenPropsType propstype,
                                                             GParamSpec ***specs,
                                                             GParamSpec ***setspecs);

Installs generator item properties on the provided `klass`. Used internally in IpatchSF2GenItemIface init functions.

`klass` : | Object class to install properties on
`propstype` : | Type of properties to install (instrument/preset)
`specs` : | Location to store a pointer to an allocated array of parameter specs which should get copied to the interface's specs field and then freed
`setspecs` : | Location to store a pointer to an allocated array of parameter specs which should get copied to the interface's setspecs field and then freed

### ipatch_sf2_gen_item_iface_set_property ()

    gboolean            ipatch_sf2_gen_item_iface_set_property
                                                            (IpatchSF2GenItem *item,
                                                             guint property_id,
                                                             const GValue *value);

Used internally for classes with generators, to set values thereof.

`item` : | IpatchItem instance with generator properties
`property_id` : | Property id to set
`value` : | Value to set property to
Returns : | `TRUE` if `property_id` handled, `FALSE` otherwise

### ipatch_sf2_gen_item_iface_get_property ()

    gboolean            ipatch_sf2_gen_item_iface_get_property
                                                            (IpatchSF2GenItem *item,
                                                             guint property_id,
                                                             GValue *value);

Used internally for classes with generator properties, to get values thereof.

`item` : | IpatchItem instance with generators
`property_id` : | Property id to set
`value` : | Value to set property to
Returns : | `TRUE` if `property_id` handled, `FALSE` otherwise

## See Also

#IpatchSF2Preset, IpatchSF2Inst, IpatchSF2PZone, IpatchSF2IZone