## IpatchSF2 IpatchSF2 — SoundFont instrument file object |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchSF2;
    enum                IpatchSF2Flags;
    #define             IPATCH_SF2_UNUSED_FLAG_SHIFT
    enum                IpatchSF2InfoType;
    #define             IPATCH_SF2_INFO_COUNT
    #define             IPATCH_SF2_DEFAULT_ENGINE
    IpatchSF2 *         ipatch_sf2_new                      (void);
    #define             ipatch_sf2_get_presets              (sfont)
    #define             ipatch_sf2_get_insts                (sfont)
    #define             ipatch_sf2_get_samples              (sfont)
    void                ipatch_sf2_set_file                 (IpatchSF2 *sf,
                                                             IpatchSF2File *file);
    IpatchSF2File *     ipatch_sf2_get_file                 (IpatchSF2 *sf);
    char *              ipatch_sf2_get_info                 (IpatchSF2 *sf,
                                                             IpatchSF2InfoType id);
    void                ipatch_sf2_set_info                 (IpatchSF2 *sf,
                                                             IpatchSF2InfoType id,
                                                             const char *val);
    IpatchSF2Info *     ipatch_sf2_get_info_array           (IpatchSF2 *sf);
    void                ipatch_sf2_free_info_array          (IpatchSF2Info *array);
    gboolean            ipatch_sf2_info_id_is_valid         (guint32 id);
    int                 ipatch_sf2_get_info_max_size        (IpatchSF2InfoType infotype);
    IpatchSF2Preset *   ipatch_sf2_find_preset              (IpatchSF2 *sf,
                                                             const char *name,
                                                             int bank,
                                                             int program,
                                                             const IpatchSF2Preset *exclude);
    IpatchSF2Inst *     ipatch_sf2_find_inst                (IpatchSF2 *sf,
                                                             const char *name,
                                                             const IpatchSF2Inst *exclude);
    IpatchSF2Sample *   ipatch_sf2_find_sample              (IpatchSF2 *sf,
                                                             const char *name,
                                                             const IpatchSF2Sample *exclude);
    IpatchList *        ipatch_sf2_get_zone_references      (IpatchItem *item);
    char *              ipatch_sf2_make_unique_name         (IpatchSF2 *sfont,
                                                             GType child_type,
                                                             const char *name,
                                                             const IpatchItem *exclude);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchContainer
                   +----IpatchBase
                         +----IpatchSF2

## Properties

      "author"                   gchar*                : Read / Write
      "comment"                  gchar*                : Read / Write
      "copyright"                gchar*                : Read / Write
      "date"                     gchar*                : Read / Write
      "engine"                   gchar*                : Read / Write
      "name"                     gchar*                : Read / Write
      "product"                  gchar*                : Read / Write
      "rom-name"                 gchar*                : Read / Write
      "rom-version"              gchar*                : Read / Write
      "samples-24bit"            gboolean              : Read / Write
      "software"                 gchar*                : Read / Write
      "version"                  gchar*                : Read / Write

## Description

SoundFont version 2 instrument file object. Parent to IpatchSF2Preset, IpatchSF2Inst and IpatchSF2Sample objects.

## Details

### IpatchSF2

    typedef struct {
      IpatchBase parent_instance;

      guint16 ver_major, ver_minor;	/* SoundFont version */
      guint16 romver_major, romver_minor; /* ROM version (if any) */

      GHashTable *info;		/* hash of info strings by 4 char ID */
      GSList *presets;		/* list of #IpatchSF2Preset structures */
      GSList *insts;		/* list of #IpatchSF2Inst structures */
      GSList *samples;		/* list of #IpatchSF2Sample structures */
    } IpatchSF2;

### enum IpatchSF2Flags

    typedef enum
    {
      /* SoundFont 24 bit samples enabled flag */
      IPATCH_SF2_SAMPLES_24BIT = 1 << IPATCH_BASE_UNUSED_FLAG_SHIFT
    } IpatchSF2Flags;

### IPATCH_SF2_UNUSED_FLAG_SHIFT

    #define IPATCH_SF2_UNUSED_FLAG_SHIFT (IPATCH_BASE_UNUSED_FLAG_SHIFT + 3)

### enum IpatchSF2InfoType

    typedef enum
    {
      IPATCH_SF2_UNKNOWN,		/* unknown chunk ("NULL" value) */
      IPATCH_SF2_VERSION = IPATCH_SFONT_FOURCC_IFIL, /* SoundFont version */
      IPATCH_SF2_ENGINE = IPATCH_SFONT_FOURCC_ISNG,/* target sound engine */
      IPATCH_SF2_NAME = IPATCH_SFONT_FOURCC_INAM, /* SoundFont name */
      IPATCH_SF2_ROM_NAME = IPATCH_SFONT_FOURCC_IROM, /* ROM name */
      IPATCH_SF2_ROM_VERSION = IPATCH_SFONT_FOURCC_IVER, /* ROM version */
      IPATCH_SF2_DATE = IPATCH_SFONT_FOURCC_ICRD, /* creation date */
      IPATCH_SF2_AUTHOR = IPATCH_SFONT_FOURCC_IENG,/* sound designers/engineers */
      IPATCH_SF2_PRODUCT = IPATCH_SFONT_FOURCC_IPRD, /* product intended for */
      IPATCH_SF2_COPYRIGHT = IPATCH_SFONT_FOURCC_ICOP, /* copyright message */
      IPATCH_SF2_COMMENT = IPATCH_SFONT_FOURCC_ICMT, /* comments */
      IPATCH_SF2_SOFTWARE = IPATCH_SFONT_FOURCC_ISFT /* software "create:modify" */
    }IpatchSF2InfoType;

### IPATCH_SF2_INFO_COUNT

    #define IPATCH_SF2_INFO_COUNT 11

### IPATCH_SF2_DEFAULT_ENGINE

    #define IPATCH_SF2_DEFAULT_ENGINE "EMU8000"

### ipatch_sf2_new ()

    IpatchSF2 *         ipatch_sf2_new                      (void);

Create a new SoundFont base object.

Returns : | New SoundFont base object with a reference count of 1. Caller owns the reference and removing it will destroy the item.

### ipatch_sf2_get_presets()

    #define             ipatch_sf2_get_presets(sfont)

### ipatch_sf2_get_insts()

    #define             ipatch_sf2_get_insts(sfont)

### ipatch_sf2_get_samples()

    #define             ipatch_sf2_get_samples(sfont)

### ipatch_sf2_set_file ()

    void                ipatch_sf2_set_file                 (IpatchSF2 *sf,
                                                             IpatchSF2File *file);

Sets the file object of a SoundFont. SoundFont files are kept open for sample data that references the file. This function sets a SoundFonts authoritive file object. A convenience function, as `ipatch_base_set_file()` does the same thing (albeit without more specific type casting).

`sf` : | SoundFont to set file object of
`file` : | File object to use with the SoundFont.

### ipatch_sf2_get_file ()

    IpatchSF2File *     ipatch_sf2_get_file                 (IpatchSF2 *sf);

Gets the file object of a SoundFont. The returned SoundFont file object's reference count has incremented. The caller owns the reference and is responsible for removing it with ``g_object_unref()``. A convenience function as `ipatch_base_get_file()` does the same thing (albeit without more specific type casting).

`sf` : | SoundFont to get file object of
Returns : | The SoundFont file object or `NULL` if `sf` is not open. Remember to unref the file object with ``g_object_unref()`` when done with it.

### ipatch_sf2_get_info ()

    char *              ipatch_sf2_get_info                 (IpatchSF2 *sf,
                                                             IpatchSF2InfoType id);

Get a SoundFont info string by RIFF FOURCC ID.

`sf` : | SoundFont to get info from
`id` : | RIFF FOURCC id
Returns : | New allocated info string value or `NULL` if no info with the given `id`. String should be freed when finished with it.

### ipatch_sf2_set_info ()

    void                ipatch_sf2_set_info                 (IpatchSF2 *sf,
                                                             IpatchSF2InfoType id,
                                                             const char *val);

Set SoundFont info. Validates `id` and ensures `val` does not exceed the maximum allowed length for the given info type.

Emits changed signal on SoundFont.

`sf` : | SoundFont to set info of
`id` : | RIFF FOURCC id
`val` : | Value to set info to or `NULL` to unset (clear) info.

### ipatch_sf2_get_info_array ()

    IpatchSF2Info *     ipatch_sf2_get_info_array           (IpatchSF2 *sf);

Get all string info (not IPATCH_SF2_VERSION or IPATCH_SF2_ROM_VERSION) from a SoundFont object. The array is sorted in the order recommended by the SoundFont standard for saving.

`sf` : | SoundFont to get all info strings from
Returns : | A newly allocated array of info structures terminated by an array member with 0 valued `id` field. Remember to free the array with `ipatch_sf2_free_info_array()` when finished with it.

### ipatch_sf2_free_info_array ()

    void                ipatch_sf2_free_info_array          (IpatchSF2Info *array);

Frees an info array returned by `ipatch_sf2_get_info_array()`.

`array` : | SoundFont info array

### ipatch_sf2_info_id_is_valid ()

    gboolean            ipatch_sf2_info_id_is_valid         (guint32 id);

Check if a given RIFF FOURCC id is a valid SoundFont info id.

`id` : | RIFF FOURCC id (see IpatchSF2InfoType)
Returns : | `TRUE` if `id` is a valid info id, `FALSE` otherwise

### ipatch_sf2_get_info_max_size ()

    int                 ipatch_sf2_get_info_max_size        (IpatchSF2InfoType infotype);

Get maximum chunk size for info chunks.

NOTE: Max size includes terminating NULL character so subtract one from returned value to get max allowed string length.

`infotype` : | An info enumeration
Returns : | Maximum info chunk size or 0 if invalid or variable length info chunk type. Subtract one to get max allowed string length (if returned value was not 0).

### ipatch_sf2_find_preset ()

    IpatchSF2Preset *   ipatch_sf2_find_preset              (IpatchSF2 *sf,
                                                             const char *name,
                                                             int bank,
                                                             int program,
                                                             const IpatchSF2Preset *exclude);

Find a preset by name or bank:preset MIDI numbers. If preset `name` and `bank`:`program` are specified then match for either condition. If a preset is found its reference count is incremented before it is returned. The caller is responsible for removing the reference with `g_object_unref()` when finished with it.

`sf` : | SoundFont to search in
`name` : | Name of preset to find or `NULL` to match any name
`bank` : | MIDI bank number of preset to search for or -1 to not search by MIDI bank:program numbers
`program` : | MIDI program number of preset to search for, only used if `bank` is 0-128
`exclude` : | A preset to exclude from the search or `NULL`
Returns : | The matching preset or `NULL` if not found. Remember to unref the item when finished with it.

### ipatch_sf2_find_inst ()

    IpatchSF2Inst *     ipatch_sf2_find_inst                (IpatchSF2 *sf,
                                                             const char *name,
                                                             const IpatchSF2Inst *exclude);

Find an instrument by `name` in a SoundFont. If a matching instrument is found, its reference count is incremented before it is returned. The caller is responsible for removing the reference with `g_object_unref()` when finished with it.

`sf` : | SoundFont to search in
`name` : | Name of Instrument to find
`exclude` : | An instrument to exclude from the search or `NULL`
Returns : | The matching instrument or `NULL` if not found. Remember to unref the item when finished with it.

### ipatch_sf2_find_sample ()

    IpatchSF2Sample *   ipatch_sf2_find_sample              (IpatchSF2 *sf,
                                                             const char *name,
                                                             const IpatchSF2Sample *exclude);

Find a sample by `name` in a SoundFont. If a sample is found its reference count is incremented before it is returned. The caller is responsible for removing the reference with `g_object_unref()` when finished with it.

`sf` : | SoundFont to search in
`name` : | Name of sample to find
`exclude` : | A sample to exclude from the search or `NULL`
Returns : | The matching sample or `NULL` if not found. Remember to unref the item when finished with it.

### ipatch_sf2_get_zone_references ()

    IpatchList *        ipatch_sf2_get_zone_references      (IpatchItem *item);

Get list of zones referencing an IpatchSF2Inst or IpatchSF2Sample.

`item` : | Item to locate referencing zones of, must be of type IpatchSF2Inst or IpatchSF2Sample and be parented to an IpatchSF2 object.
Returns : | New object list containing IpatchSF2Zone objects that refer to `item`. The new list object has a reference count of 1 which the caller owns, unreference to free the list.

### ipatch_sf2_make_unique_name ()

    char *              ipatch_sf2_make_unique_name         (IpatchSF2 *sfont,
                                                             GType child_type,
                                                             const char *name,
                                                             const IpatchItem *exclude);

Generates a unique name for the given `child_type` in `sfont`. The `name` parameter is used as a base and is modified, by appending a number, to make it unique (if necessary). The `exclude` parameter is used to exclude an existing `sfont` child item from the search.

MT-Note: To ensure that an item is actually unique before being added to a SoundFont object, `ipatch_container_add_unique()` should be used.

`sfont` : | SoundFont item
`child_type` : | A child type of `sfont` to search for a unique name in
`name` : | An initial name to use or NULL
`exclude` : | An item to exclude from search or NULL
Returns : | A new unique name which should be freed when finished with it.

## Property Details

### The `"author"` property

      "author"                   gchar*                : Read / Write

Author of SoundFont.

Default value: NULL

### The `"comment"` property

      "comment"                  gchar*                : Read / Write

Comments.

Default value: NULL

### The `"copyright"` property

      "copyright"                gchar*                : Read / Write

Copyright.

Default value: NULL

### The `"date"` property

      "date"                     gchar*                : Read / Write

Creation date.

Default value: NULL

### The `"engine"` property

      "engine"                   gchar*                : Read / Write

Sound synthesis engine identifier.

Default value: "EMU8000"

### The `"name"` property

      "name"                     gchar*                : Read / Write

SoundFont name.

Default value: NULL

### The `"product"` property

      "product"                  gchar*                : Read / Write

Product SoundFont is intended for.

Default value: NULL

### The `"rom-name"` property

      "rom-name"                 gchar*                : Read / Write

ROM name identifier.

Default value: NULL

### The `"rom-version"` property

      "rom-version"              gchar*                : Read / Write

ROM version "major.minor".

Default value: NULL

### The `"samples-24bit"` property

      "samples-24bit"            gboolean              : Read / Write

Enable 24 bit samples.

Default value: FALSE

### The `"software"` property

      "software"                 gchar*                : Read / Write

Software 'created by:modified by'.

Default value: NULL

### The `"version"` property

      "version"                  gchar*                : Read / Write

SoundFont version ("major.minor").

Default value: "2.01"

## See Also

#IpatchSF2Preset, IpatchSF2Inst, IpatchSF2Sample