## IpatchDLS2Region

IpatchDLS2Region — DLS region object

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchDLS2ParamArray;
    enum                IpatchDLS2Param;
                        IpatchDLS2Region;
    enum                IpatchDLS2RegionChannelType;
    #define             IPATCH_DLS2_REGION_CHANNEL_MONO
    enum                IpatchDLS2RegionFlags;
    #define             IPATCH_DLS2_REGION_FLAG_MASK
    #define             IPATCH_DLS2_REGION_UNUSED_FLAG_SHIFT
    IpatchDLS2Region *  ipatch_dls2_region_new              (void);
    IpatchDLS2Region *  ipatch_dls2_region_first            (IpatchIter *iter);
    IpatchDLS2Region *  ipatch_dls2_region_next             (IpatchIter *iter);
    char *              ipatch_dls2_region_get_info         (IpatchDLS2Region *region,
                                                             guint32 fourcc);
    void                ipatch_dls2_region_set_info         (IpatchDLS2Region *region,
                                                             guint32 fourcc,
                                                             const char *val);
    void                ipatch_dls2_region_set_sample       (IpatchDLS2Region *region,
                                                             IpatchDLS2Sample *sample);
    IpatchDLS2Sample *  ipatch_dls2_region_get_sample       (IpatchDLS2Region *region);
    IpatchDLS2Sample *  ipatch_dls2_region_peek_sample      (IpatchDLS2Region *region);
    void                ipatch_dls2_region_set_note_range   (IpatchDLS2Region *region,
                                                             int low,
                                                             int high);
    void                ipatch_dls2_region_set_velocity_range
                                                            (IpatchDLS2Region *region,
                                                             int low,
                                                             int high);
    gboolean            ipatch_dls2_region_in_range         (IpatchDLS2Region *region,
                                                             int note,
                                                             int velocity);
    void                ipatch_dls2_region_set_param        (IpatchDLS2Region *region,
                                                             IpatchDLS2Param param,
                                                             gint32 val);
    void                ipatch_dls2_region_set_param_array  (IpatchDLS2Region *region,
                                                             IpatchDLS2ParamArray *array);
    GSList *            ipatch_dls2_region_get_conns        (IpatchDLS2Region *region);
    void                ipatch_dls2_region_set_conn         (IpatchDLS2Region *region,
                                                             const IpatchDLS2Conn *conn);
    void                ipatch_dls2_region_unset_conn       (IpatchDLS2Region *region,
                                                             const IpatchDLS2Conn *conn);
    void                ipatch_dls2_region_unset_all_conns  (IpatchDLS2Region *region);
    guint               ipatch_dls2_region_conn_count       (IpatchDLS2Region *region);
    int                 ipatch_dls2_region_channel_map_stereo
                                                            (IpatchDLS2RegionChannelType chan);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchDLS2Region

## Implemented Interfaces

IpatchDLS2Region implements IpatchSample.

## Properties

      "archive-location"         gchar*                : Read / Write
      "artist"                   gchar*                : Read / Write
      "channel"                  gint                  : Read / Write
      "comment"                  gchar*                : Read / Write
      "commissioned"             gchar*                : Read / Write
      "copyright"                gchar*                : Read / Write
      "date"                     gchar*                : Read / Write
      "engineer"                 gchar*                : Read / Write
      "fine-tune"                gint                  : Read / Write
      "flags"                    IpatchDLS2SampleFlags  : Read / Write
      "gain"                     gint                  : Read / Write
      "genre"                    gchar*                : Read / Write
      "key-group"                gint                  : Read / Write
      "keywords"                 gchar*                : Read / Write
      "layer-group"              gint                  : Read / Write
      "link-item"                IpatchDLS2Sample*     : Read / Write
      "loop-end"                 guint                 : Read / Write
      "loop-start"               guint                 : Read / Write
      "loop-type"                IpatchSampleLoopType  : Read / Write
      "medium"                   gchar*                : Read / Write
      "multi-channel"            gboolean              : Read / Write
      "name"                     gchar*                : Read / Write
      "note-range"               IpatchRange*          : Read / Write
      "phase-group"              gint                  : Read / Write
      "phase-master"             gboolean              : Read / Write
      "product"                  gchar*                : Read / Write
      "root-note"                gint                  : Read / Write
      "sample-info-override"     gboolean              : Read / Write
      "self-non-exclusive"       gboolean              : Read / Write
      "software"                 gchar*                : Read / Write
      "source"                   gchar*                : Read / Write
      "source-form"              gchar*                : Read / Write
      "subject"                  gchar*                : Read / Write
      "technician"               gchar*                : Read / Write
      "velocity-range"           IpatchRange*          : Read / Write

## Description

DLS regions are child items of IpatchDLSInst objects and define how an individual audio sample is synthesized in an instrument.

## Details

### IpatchDLS2ParamArray

    typedef struct {
      gint32 values[IPATCH_DLS2_PARAM_COUNT];
    } IpatchDLS2ParamArray;

### enum IpatchDLS2Param

    typedef enum
    {
      IPATCH_DLS2_PARAM_MOD_LFO_FREQ,
      IPATCH_DLS2_PARAM_MOD_LFO_DELAY,

      IPATCH_DLS2_PARAM_VIB_LFO_FREQ,
      IPATCH_DLS2_PARAM_VIB_LFO_DELAY,

      IPATCH_DLS2_PARAM_VOL_EG_DELAY,
      IPATCH_DLS2_PARAM_VOL_EG_ATTACK,
      IPATCH_DLS2_PARAM_VOL_EG_HOLD,
      IPATCH_DLS2_PARAM_VOL_EG_DECAY,
      IPATCH_DLS2_PARAM_VOL_EG_SUSTAIN,
      IPATCH_DLS2_PARAM_VOL_EG_RELEASE,
      IPATCH_DLS2_PARAM_VOL_EG_SHUTDOWN,
      IPATCH_DLS2_PARAM_VOL_EG_VELOCITY_TO_ATTACK,
      IPATCH_DLS2_PARAM_VOL_EG_NOTE_TO_DECAY,
      IPATCH_DLS2_PARAM_VOL_EG_NOTE_TO_HOLD,

      IPATCH_DLS2_PARAM_MOD_EG_DELAY,
      IPATCH_DLS2_PARAM_MOD_EG_ATTACK,
      IPATCH_DLS2_PARAM_MOD_EG_HOLD,
      IPATCH_DLS2_PARAM_MOD_EG_DECAY,
      IPATCH_DLS2_PARAM_MOD_EG_SUSTAIN,
      IPATCH_DLS2_PARAM_MOD_EG_RELEASE,
      IPATCH_DLS2_PARAM_MOD_EG_VELOCITY_TO_ATTACK,
      IPATCH_DLS2_PARAM_MOD_EG_NOTE_TO_DECAY,
      IPATCH_DLS2_PARAM_MOD_EG_NOTE_TO_HOLD,

      IPATCH_DLS2_PARAM_SCALE_TUNE,
      IPATCH_DLS2_PARAM_RPN2_TO_NOTE,

      IPATCH_DLS2_PARAM_FILTER_CUTOFF,
      IPATCH_DLS2_PARAM_FILTER_Q,
      IPATCH_DLS2_PARAM_MOD_LFO_TO_FILTER_CUTOFF,
      IPATCH_DLS2_PARAM_MOD_LFO_CC1_TO_FILTER_CUTOFF,
      IPATCH_DLS2_PARAM_MOD_LFO_CHANNEL_PRESS_TO_FILTER_CUTOFF,
      IPATCH_DLS2_PARAM_MOD_EG_TO_FILTER_CUTOFF,
      IPATCH_DLS2_PARAM_VELOCITY_TO_FILTER_CUTOFF,
      IPATCH_DLS2_PARAM_NOTE_TO_FILTER_CUTOFF,
      IPATCH_DLS2_PARAM_MOD_LFO_TO_GAIN,
      IPATCH_DLS2_PARAM_MOD_LFO_CC1_TO_GAIN,
      IPATCH_DLS2_PARAM_MOD_LFO_CHANNEL_PRESS_TO_GAIN,
      IPATCH_DLS2_PARAM_VELOCITY_TO_GAIN,
      IPATCH_DLS2_PARAM_CC7_TO_GAIN,
      IPATCH_DLS2_PARAM_CC11_TO_GAIN,

      IPATCH_DLS2_PARAM_TUNE,
      IPATCH_DLS2_PARAM_PITCH_WHEEL_RPN0_TO_PITCH,
      IPATCH_DLS2_PARAM_NOTE_NUMBER_TO_PITCH,
      IPATCH_DLS2_PARAM_RPN1_TO_PITCH,
      IPATCH_DLS2_PARAM_VIB_LFO_TO_PITCH,
      IPATCH_DLS2_PARAM_VIB_LFO_CC1_TO_PITCH,
      IPATCH_DLS2_PARAM_VIB_LFO_CHANNEL_PRESS_TO_PITCH,
      IPATCH_DLS2_PARAM_MOD_LFO_TO_PITCH,
      IPATCH_DLS2_PARAM_MOD_LFO_CC1_TO_PITCH,
      IPATCH_DLS2_PARAM_MOD_LFO_CHANNEL_PRESS_TO_PITCH,
      IPATCH_DLS2_PARAM_MOD_EG_TO_PITCH,

      IPATCH_DLS2_PARAM_PAN,
      IPATCH_DLS2_PARAM_CC10_TO_PAN,
      IPATCH_DLS2_PARAM_CC91_TO_REVERB_SEND,
      IPATCH_DLS2_PARAM_REVERB_SEND,
      IPATCH_DLS2_PARAM_CC93_TO_CHORUS_SEND,
      IPATCH_DLS2_PARAM_CHORUS_SEND,
      IPATCH_DLS2_PARAM_COUNT
    } IpatchDLS2Param;

### IpatchDLS2Region

    typedef struct _IpatchDLS2Region IpatchDLS2Region;

### enum IpatchDLS2RegionChannelType

    typedef enum
    {
      IPATCH_DLS2_REGION_CHANNEL_LEFT = 0,
      IPATCH_DLS2_REGION_CHANNEL_RIGHT = 1,
      IPATCH_DLS2_REGION_CHANNEL_CENTER = 2,
      IPATCH_DLS2_REGION_CHANNEL_LOW_FREQ = 3,
      IPATCH_DLS2_REGION_CHANNEL_SURROUND_LEFT = 4,
      IPATCH_DLS2_REGION_CHANNEL_SURROUND_RIGHT = 5,
      IPATCH_DLS2_REGION_CHANNEL_LEFT_OF_CENTER = 6,
      IPATCH_DLS2_REGION_CHANNEL_RIGHT_OF_CENTER = 7,
      IPATCH_DLS2_REGION_CHANNEL_SURROUND_CENTER = 8,
      IPATCH_DLS2_REGION_CHANNEL_SIDE_LEFT = 9,
      IPATCH_DLS2_REGION_CHANNEL_SIDE_RIGHT = 10,
      IPATCH_DLS2_REGION_CHANNEL_TOP = 11,
      IPATCH_DLS2_REGION_CHANNEL_TOP_FRONT_LEFT = 12,
      IPATCH_DLS2_REGION_CHANNEL_TOP_FRONT_CENTER = 13,
      IPATCH_DLS2_REGION_CHANNEL_TOP_FRONT_RIGHT = 14,
      IPATCH_DLS2_REGION_CHANNEL_TOP_REAR_LEFT = 15,
      IPATCH_DLS2_REGION_CHANNEL_TOP_REAR_CENTER = 16,
      IPATCH_DLS2_REGION_CHANNEL_TOP_REAR_RIGHT = 17
    } IpatchDLS2RegionChannelType;

### IPATCH_DLS2_REGION_CHANNEL_MONO

    #define IPATCH_DLS2_REGION_CHANNEL_MONO  IPATCH_DLS2_REGION_CHANNEL_LEFT

### enum IpatchDLS2RegionFlags

    typedef enum
    {
      IPATCH_DLS2_REGION_SELF_NON_EXCLUSIVE = 1 << IPATCH_ITEM_UNUSED_FLAG_SHIFT,
      IPATCH_DLS2_REGION_PHASE_MASTER = 1 << (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 1),
      IPATCH_DLS2_REGION_MULTI_CHANNEL = 1 << (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 2),
      IPATCH_DLS2_REGION_SAMPLE_INFO_OVERRIDE=1 << (IPATCH_ITEM_UNUSED_FLAG_SHIFT+3)
    } IpatchDLS2RegionFlags;

### IPATCH_DLS2_REGION_FLAG_MASK

    #define IPATCH_DLS2_REGION_FLAG_MASK  (0x0F << IPATCH_ITEM_UNUSED_FLAG_SHIFT)

### IPATCH_DLS2_REGION_UNUSED_FLAG_SHIFT

    #define IPATCH_DLS2_REGION_UNUSED_FLAG_SHIFT (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 6)

### ipatch_dls2_region_new ()

    IpatchDLS2Region *  ipatch_dls2_region_new              (void);

Create a new DLS region object.

Returns : | Newly created DLS region with a ref count of 1 which the caller owns.

### ipatch_dls2_region_first ()

    IpatchDLS2Region *  ipatch_dls2_region_first            (IpatchIter *iter);

Gets the first item in a region iterator. A convenience wrapper for `ipatch_iter_first()`.

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

### ipatch_dls2_region_next ()

    IpatchDLS2Region *  ipatch_dls2_region_next             (IpatchIter *iter);

Gets the next item in a region iterator. A convenience wrapper for `ipatch_iter_next()`.

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

### ipatch_dls2_region_get_info ()

    char *              ipatch_dls2_region_get_info         (IpatchDLS2Region *region,
                                                             guint32 fourcc);

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

`region` : | DLS region 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_region_set_info ()

    void                ipatch_dls2_region_set_info         (IpatchDLS2Region *region,
                                                             guint32 fourcc,
                                                             const char *val);

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

`region` : | DLS region 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_region_set_sample ()

    void                ipatch_dls2_region_set_sample       (IpatchDLS2Region *region,
                                                             IpatchDLS2Sample *sample);

Sets the referenced sample of a region.

`region` : | Region to set sample of
`sample` : | Sample to set region to

### ipatch_dls2_region_get_sample ()

    IpatchDLS2Sample *  ipatch_dls2_region_get_sample       (IpatchDLS2Region *region);

Gets the referenced sample from a region. The returned item's reference count is incremented and the caller is responsible for unrefing it with `g_object_unref()`.

`region` : | Region to get referenced sample from
Returns : | Region's referenced sample or `NULL` if not set yet. Remember to unreference the item with `g_object_unref()` when done with it.

### ipatch_dls2_region_peek_sample ()

    IpatchDLS2Sample *  ipatch_dls2_region_peek_sample      (IpatchDLS2Region *region);

Like `ipatch_dls2_region_get_sample()` but does not add a reference to the returned item. This function should only be used if a reference of the returned item is ensured or only the pointer value is of interest.

`region` : | Region to get referenced sample from
Returns : | Region's referenced sample or `NULL` if not set yet. Remember that the item has NOT been referenced.

### ipatch_dls2_region_set_note_range ()

    void                ipatch_dls2_region_set_note_range   (IpatchDLS2Region *region,
                                                             int low,
                                                             int high);

Set the MIDI note range that a region is active on.

`region` : | Region to set note range of
`low` : | Low value of range (MIDI note # between 0 and 127)
`high` : | High value of range (MIDI note # between 0 and 127)

### ipatch_dls2_region_set_velocity_range ()

    void                ipatch_dls2_region_set_velocity_range
                                                            (IpatchDLS2Region *region,
                                                             int low,
                                                             int high);

Set the MIDI velocity range that a region is active on.

`region` : | Region to set velocity range of
`low` : | Low value of range (MIDI velocity # between 0 and 127)
`high` : | High value of range (MIDI velocity # between 0 and 127)

### ipatch_dls2_region_in_range ()

    gboolean            ipatch_dls2_region_in_range         (IpatchDLS2Region *region,
                                                             int note,
                                                             int velocity);

Check if a note and velocity falls in a region's ranges

`region` : | Region to check if in range
`note` : | MIDI note number or -1 for wildcard
`velocity` : | MIDI velocity or -1 for wildcard
Returns : | `TRUE` if region is in note and velocity range, `FALSE` otherwise

### ipatch_dls2_region_set_param ()

    void                ipatch_dls2_region_set_param        (IpatchDLS2Region *region,
                                                             IpatchDLS2Param param,
                                                             gint32 val);

Sets an effect parameter of a DLS2 Region. DLS2 defines a standard set of connections (effect parameters). Any non-standard connections can be manipulated with the connection related functions.

`region` : | Region to set parameter of
`param` : | Parameter to set
`val` : | Value for parameter

### ipatch_dls2_region_set_param_array ()

    void                ipatch_dls2_region_set_param_array  (IpatchDLS2Region *region,
                                                             IpatchDLS2ParamArray *array);

### ipatch_dls2_region_get_conns ()

    GSList *            ipatch_dls2_region_get_conns        (IpatchDLS2Region *region);

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

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

### ipatch_dls2_region_set_conn ()

    void                ipatch_dls2_region_set_conn         (IpatchDLS2Region *region,
                                                             const IpatchDLS2Conn *conn);

Set a DLS connection in a region. See `ipatch_dls2_conn_list_set()` for more details.

`region` : | DLS region
`conn` : | Connection

### ipatch_dls2_region_unset_conn ()

    void                ipatch_dls2_region_unset_conn       (IpatchDLS2Region *region,
                                                             const IpatchDLS2Conn *conn);

Remove a DLS connection from a region. See `ipatch_dls2_conn_list_unset()` for more details.

`region` : | DLS region
`conn` : | Connection

### ipatch_dls2_region_unset_all_conns ()

    void                ipatch_dls2_region_unset_all_conns  (IpatchDLS2Region *region);

Remove all connections in a region.

`region` : | DLS region

### ipatch_dls2_region_conn_count ()

    guint               ipatch_dls2_region_conn_count       (IpatchDLS2Region *region);

Count number of connections in a region

`region` : | Region to count connections in
Returns : | Count of connections

### ipatch_dls2_region_channel_map_stereo ()

    int                 ipatch_dls2_region_channel_map_stereo
                                                            (IpatchDLS2RegionChannelType chan);

Map a DLS2 channel steering enumeration (surround sound capable) to stereo steering.

`chan` : | Channel steering enum
Returns : | -1 = left, 0 = center, 1 = right

## 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 `"channel"` property

      "channel"                  gint                  : Read / Write

DLS audio channel identifier.

Allowed values: [0,262143]

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 `"fine-tune"` property

      "fine-tune"                gint                  : Read / Write

Fine tuning in cents.

Allowed values: [-99,99]

Default value: 0

### The `"flags"` property

      "flags"                    IpatchDLS2SampleFlags  : Read / Write

Sample flags.

### The `"gain"` property

      "gain"                     gint                  : Read / Write

Gain in DLS relative gain units.

Default value: 0

### The `"genre"` property

      "genre"                    gchar*                : Read / Write

Genre.

Default value: NULL

### The `"key-group"` property

      "key-group"                gint                  : Read / Write

Percussion key group.

Allowed values: [0,15]

Default value: 0

### The `"keywords"` property

      "keywords"                 gchar*                : Read / Write

Keywords (separated by "; ").

Default value: NULL

### The `"layer-group"` property

      "layer-group"              gint                  : Read / Write

Layer group.

Allowed values: [0,65535]

Default value: 0

### The `"link-item"` property

      "link-item"                IpatchDLS2Sample*     : Read / Write

Link item.

### The `"loop-end"` property

      "loop-end"                 guint                 : Read / Write

Loop end in frames (after loop).

Default value: 0

### The `"loop-start"` property

      "loop-start"               guint                 : Read / Write

Start of loop in frames.

Default value: 0

### The `"loop-type"` property

      "loop-type"                IpatchSampleLoopType  : Read / Write

Loop method type.

Default value: IPATCH_SAMPLE_LOOP_NONE

### The `"medium"` property

      "medium"                   gchar*                : Read / Write

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

Default value: NULL

### The `"multi-channel"` property

      "multi-channel"            gboolean              : Read / Write

Multi channel.

Default value: FALSE

### The `"name"` property

      "name"                     gchar*                : Read / Write

Name.

Default value: "untitled"

### The `"note-range"` property

      "note-range"               IpatchRange*          : Read / Write

MIDI note range.

### The `"phase-group"` property

      "phase-group"              gint                  : Read / Write

Phase locked sample group.

Allowed values: [0,65535]

Default value: 0

### The `"phase-master"` property

      "phase-master"             gboolean              : Read / Write

Multi channel phase lock master.

Default value: FALSE

### The `"product"` property

      "product"                  gchar*                : Read / Write

Product intended for.

Default value: NULL

### The `"root-note"` property

      "root-note"                gint                  : Read / Write

Root MIDI note.

Allowed values: [0,127]

Default value: 60

### The `"sample-info-override"` property

      "sample-info-override"     gboolean              : Read / Write

Override sample info.

Default value: FALSE

### The `"self-non-exclusive"` property

      "self-non-exclusive"       gboolean              : Read / Write

Self non exclusive.

Default value: FALSE

### 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

### The `"velocity-range"` property

      "velocity-range"           IpatchRange*          : Read / Write

MIDI velocity range.

## See Also

#IpatchDLSInst