## IpatchDLS2Inst IpatchDLS2Inst — DLS instrument object |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchDLS2Inst;
    #define             IPATCH_DLS2_INST_BANK_MAX
    enum                IpatchDLS2InstFlags;
    #define             IPATCH_DLS2_INST_UNUSED_FLAG_SHIFT
    IpatchDLS2Inst *    ipatch_dls2_inst_new                (void);
    #define             ipatch_dls2_inst_get_regions        (inst)
    IpatchDLS2Inst *    ipatch_dls2_inst_first              (IpatchIter *iter);
    IpatchDLS2Inst *    ipatch_dls2_inst_next               (IpatchIter *iter);
    char *              ipatch_dls2_inst_get_info           (IpatchDLS2Inst *inst,
                                                             guint32 fourcc);
    void                ipatch_dls2_inst_set_info           (IpatchDLS2Inst *inst,
                                                             guint32 fourcc,
                                                             const char *val);
    void                ipatch_dls2_inst_set_midi_locale    (IpatchDLS2Inst *inst,
                                                             int bank,
                                                             int program);
    void                ipatch_dls2_inst_get_midi_locale    (IpatchDLS2Inst *inst,
                                                             int *bank,
                                                             int *program);
    int                 ipatch_dls2_inst_compare            (const IpatchDLS2Inst *p1,
                                                             const IpatchDLS2Inst *p2);
    GSList *            ipatch_dls2_inst_get_conns          (IpatchDLS2Inst *inst);
    void                ipatch_dls2_inst_set_conn           (IpatchDLS2Inst *inst,
                                                             const IpatchDLS2Conn *conn);
    void                ipatch_dls2_inst_unset_conn         (IpatchDLS2Inst *inst,
                                                             const IpatchDLS2Conn *conn);
    void                ipatch_dls2_inst_unset_all_conns    (IpatchDLS2Inst *inst);
    guint               ipatch_dls2_inst_conn_count         (IpatchDLS2Inst *inst);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchContainer
                   +----IpatchDLS2Inst
                         +----IpatchGigInst

## Properties

      "archive-location"         gchar*                : Read / Write
      "artist"                   gchar*                : Read / Write
      "bank"                     gint                  : Read / Write
      "comment"                  gchar*                : Read / Write
      "commissioned"             gchar*                : Read / Write
      "copyright"                gchar*                : Read / Write
      "date"                     gchar*                : Read / Write
      "engineer"                 gchar*                : Read / Write
      "genre"                    gchar*                : Read / Write
      "keywords"                 gchar*                : Read / Write
      "medium"                   gchar*                : Read / Write
      "name"                     gchar*                : Read / Write
      "percussion"               gboolean              : Read / Write
      "product"                  gchar*                : Read / Write
      "program"                  gint                  : Read / Write
      "software"                 gchar*                : Read / Write
      "source"                   gchar*                : Read / Write
      "source-form"              gchar*                : Read / Write
      "subject"                  gchar*                : Read / Write
      "technician"               gchar*                : Read / Write

## Description

Defines a DLS instrument object. DLS instruments are the toplevel objects in the DLS instrument file tree hierarchy.

## Details

### IpatchDLS2Inst

    typedef struct _IpatchDLS2Inst IpatchDLS2Inst;

### IPATCH_DLS2_INST_BANK_MAX

    #define IPATCH_DLS2_INST_BANK_MAX  0x3FFF

### enum IpatchDLS2InstFlags

    typedef enum
    {
      IPATCH_DLS2_INST_PERCUSSION = 1 << IPATCH_CONTAINER_UNUSED_FLAG_SHIFT
    } IpatchDLS2InstFlags;

### IPATCH_DLS2_INST_UNUSED_FLAG_SHIFT

    #define             IPATCH_DLS2_INST_UNUSED_FLAG_SHIFT

### ipatch_dls2_inst_new ()

    IpatchDLS2Inst *    ipatch_dls2_inst_new                (void);

Create a new DLS instrument object.

Returns : | New DLS instrument with a reference count of 1. Caller owns the reference and removing it will destroy the item, unless another reference is added (if its parented for example).

### ipatch_dls2_inst_get_regions()

    #define             ipatch_dls2_inst_get_regions(inst)

### ipatch_dls2_inst_first ()

    IpatchDLS2Inst *    ipatch_dls2_inst_first              (IpatchIter *iter);

Gets the first item in an instrument iterator. A convenience wrapper for `ipatch_iter_first()`.

`iter` : | Patch item iterator containing IpatchDLS2Inst items
Returns : | The first instrument in `iter` or `NULL` if empty.

### ipatch_dls2_inst_next ()

    IpatchDLS2Inst *    ipatch_dls2_inst_next               (IpatchIter *iter);

Gets the next item in an instrument iterator. A convenience wrapper for `ipatch_iter_next()`.

`iter` : | Patch item iterator containing IpatchDLS2Inst items
Returns : | The next instrument in `iter` or `NULL` if at the end of the list.

### ipatch_dls2_inst_get_info ()

    char *              ipatch_dls2_inst_get_info           (IpatchDLS2Inst *inst,
                                                             guint32 fourcc);

Get a DLS instrument info string by FOURCC integer ID (integer representation of a 4 character RIFF chunk ID, see IpatchRiff).

`inst` : | DLS instrument to get info from
`fourcc` : | FOURCC integer id of INFO to get
Returns : | New allocated info string value or `NULL` if no info with the given `fourcc` ID. String should be freed when finished with it.

### ipatch_dls2_inst_set_info ()

    void                ipatch_dls2_inst_set_info           (IpatchDLS2Inst *inst,
                                                             guint32 fourcc,
                                                             const char *val);

Sets an INFO value in a DLS instrument object. Emits changed signal.

`inst` : | DLS instrument to set info of
`fourcc` : | FOURCC integer ID of INFO to set
`val` : | Value to set info to or `NULL` to unset (clear) info.

### ipatch_dls2_inst_set_midi_locale ()

    void                ipatch_dls2_inst_set_midi_locale    (IpatchDLS2Inst *inst,
                                                             int bank,
                                                             int program);

Sets the MIDI locale of a DLS instrument (bank and program numbers).

`inst` : | DLS instrument to set MIDI locale of
`bank` : | MIDI bank number to assign to instrument
`program` : | MIDI program number to assign to instrument

### ipatch_dls2_inst_get_midi_locale ()

    void                ipatch_dls2_inst_get_midi_locale    (IpatchDLS2Inst *inst,
                                                             int *bank,
                                                             int *program);

Gets the MIDI locale of a DLS instrument (bank and program numbers).

`inst` : | Instrument to get MIDI locale from
`bank` : | Location to store instrument's MIDI bank number or `NULL`
`program` : | Location to store instrument's MIDI program number or `NULL`

### ipatch_dls2_inst_compare ()

    int                 ipatch_dls2_inst_compare            (const IpatchDLS2Inst *p1,
                                                             const IpatchDLS2Inst *p2);

Instrument comparison function for sorting. Compare two instruments by their MIDI bank:program numbers. Note that this function is compatible with GCompareFunc and can therefore be used with g_list_sort, etc.

FIXME: Also note that percussion instruments are sorted after regular ones.

`p1` : | First instrument in comparison
`p2` : | Second instrument in comparison
Returns : | Comparison result that is less than, equal to, or greater than zero if `p1` is found, respectively, to be less than, to match, or be greater than `p2`.

### ipatch_dls2_inst_get_conns ()

    GSList *            ipatch_dls2_inst_get_conns          (IpatchDLS2Inst *inst);

Gets a list of connections from a DLS instrument. List should be freed with `ipatch_dls2_conn_list_free()` (free_conns set to `TRUE`) when finished with it.

`inst` : | Instrument to get connections from
Returns : | New list of connections (IpatchDLS2Conn) in `inst` or `NULL` if no connections. Remember to free it when finished.

### ipatch_dls2_inst_set_conn ()

    void                ipatch_dls2_inst_set_conn           (IpatchDLS2Inst *inst,
                                                             const IpatchDLS2Conn *conn);

Set a global DLS connection in an instrument. See `ipatch_dls2_conn_list_set()` for more details.

`inst` : | DLS instrument
`conn` : | Connection

### ipatch_dls2_inst_unset_conn ()

    void                ipatch_dls2_inst_unset_conn         (IpatchDLS2Inst *inst,
                                                             const IpatchDLS2Conn *conn);

Remove a global DLS connection from an instrument. See `ipatch_dls2_conn_list_unset()` for more details.

`inst` : | DLS instrument
`conn` : | Connection

### ipatch_dls2_inst_unset_all_conns ()

    void                ipatch_dls2_inst_unset_all_conns    (IpatchDLS2Inst *inst);

Remove all global connections in an instrument.

`inst` : | DLS instrument

### ipatch_dls2_inst_conn_count ()

    guint               ipatch_dls2_inst_conn_count         (IpatchDLS2Inst *inst);

Count number of connections in a instrument

`inst` : | Instrument to count connections in
Returns : | Count of connections

## Property Details

### The `"archive-location"` property

      "archive-location"         gchar*                : Read / Write

Location where subject is archived.

Default value: NULL

### The `"artist"` property

      "artist"                   gchar*                : Read / Write

Original artist.

Default value: NULL

### The `"bank"` property

      "bank"                     gint                  : Read / Write

MIDI bank number.

Allowed values: [0,16383]

Default value: 0

### The `"comment"` property

      "comment"                  gchar*                : Read / Write

Comments.

Default value: NULL

### The `"commissioned"` property

      "commissioned"             gchar*                : Read / Write

Who commissioned the material.

Default value: NULL

### The `"copyright"` property

      "copyright"                gchar*                : Read / Write

Copyright.

Default value: NULL

### The `"date"` property

      "date"                     gchar*                : Read / Write

Creation date (YYYY-MM-DD).

Default value: NULL

### The `"engineer"` property

      "engineer"                 gchar*                : Read / Write

Engineers separated by "; ".

Default value: NULL

### The `"genre"` property

      "genre"                    gchar*                : Read / Write

Genre.

Default value: NULL

### The `"keywords"` property

      "keywords"                 gchar*                : Read / Write

Keywords (separated by "; ").

Default value: NULL

### The `"medium"` property

      "medium"                   gchar*                : Read / Write

Original medium of the material (record, CD, etc).

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write

Name.

Default value: "untitled"

### The `"percussion"` property

      "percussion"               gboolean              : Read / Write

Percussion instrument?.

Default value: FALSE

### The `"product"` property

      "product"                  gchar*                : Read / Write

Product intended for.

Default value: NULL

### The `"program"` property

      "program"                  gint                  : Read / Write

MIDI program number.

Allowed values: [0,127]

Default value: 0

### The `"software"` property

      "software"                 gchar*                : Read / Write

Editor software used.

Default value: NULL

### The `"source"` property

      "source"                   gchar*                : Read / Write

Source of the original material.

Default value: NULL

### The `"source-form"` property

      "source-form"              gchar*                : Read / Write

Original source that was digitized.

Default value: NULL

### The `"subject"` property

      "subject"                  gchar*                : Read / Write

Subject of the material.

Default value: NULL

### The `"technician"` property

      "technician"               gchar*                : Read / Write

Technician who sampled the material.

Default value: NULL