IpatchDLS2Region: libinstpatch Reference Manual

IpatchDLS2Region

IpatchDLS2Region — DLS region object

Stability Level

Stable, unless otherwise indicated

Functions

IpatchDLS2Region *	ipatch_dls2_region_new ()
IpatchDLS2Region *	ipatch_dls2_region_first ()
IpatchDLS2Region *	ipatch_dls2_region_next ()
char *	ipatch_dls2_region_get_info ()
void	ipatch_dls2_region_set_info ()
void	ipatch_dls2_region_set_sample ()
IpatchDLS2Sample *	ipatch_dls2_region_get_sample ()
IpatchDLS2Sample *	ipatch_dls2_region_peek_sample ()
void	ipatch_dls2_region_set_note_range ()
void	ipatch_dls2_region_set_velocity_range ()
gboolean	ipatch_dls2_region_in_range ()
void	ipatch_dls2_region_set_param ()
void	ipatch_dls2_region_set_param_array ()
GSList *	ipatch_dls2_region_get_conns ()
void	ipatch_dls2_region_set_conn ()
void	ipatch_dls2_region_unset_conn ()
void	ipatch_dls2_region_unset_all_conns ()
guint	ipatch_dls2_region_conn_count ()
int	ipatch_dls2_region_channel_map_stereo ()

Properties

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

Types and Values

enum	IpatchDLS2Param
struct	IpatchDLS2ParamArray
enum	IpatchDLS2RegionChannelType
#define	IPATCH_DLS2_REGION_CHANNEL_MONO
enum	IpatchDLS2RegionFlags
#define	IPATCH_DLS2_REGION_FLAG_MASK
#define	IPATCH_DLS2_REGION_UNUSED_FLAG_SHIFT

Object Hierarchy

    GObject
    ╰── IpatchItem
        ╰── IpatchDLS2Region

Description

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

Functions

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().

[skip]

Parameters

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().

[skip]

Parameters

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).

Parameters

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.

Parameters

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.	[nullable]

ipatch_dls2_region_set_sample ()

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

Sets the referenced sample of a region.

Parameters

region	Region to set sample of
sample	Sample to set region to. Should be NULL or a IpatchDLS2Sample object

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().

Parameters

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.

[transfer full]

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.

[skip]

Parameters

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.

[transfer none]

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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);

Sets all effect parameters of a DLS2 Region.

Parameters

region	Region to set parameter of
array	Array of parameter values to copy to region

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.

Parameters

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.

[element-type IpatchDLS2Conn][transfer full]

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.

Parameters

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.

Parameters

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.

Parameters

region

DLS region

ipatch_dls2_region_conn_count ()

guint
ipatch_dls2_region_conn_count (IpatchDLS2Region *region);

Count number of connections in a region

Parameters

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.

Parameters

chan

Channel steering enum

Returns

-1 = left, 0 = center, 1 = right

Types and Values

enum IpatchDLS2Param

Members

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

struct IpatchDLS2ParamArray

struct IpatchDLS2ParamArray {
    gint32 values[IPATCH_DLS2_PARAM_COUNT];
};

enum IpatchDLS2RegionChannelType

Members

IPATCH_DLS2_REGION_CHANNEL_LEFT
IPATCH_DLS2_REGION_CHANNEL_RIGHT
IPATCH_DLS2_REGION_CHANNEL_CENTER
IPATCH_DLS2_REGION_CHANNEL_LOW_FREQ
IPATCH_DLS2_REGION_CHANNEL_SURROUND_LEFT
IPATCH_DLS2_REGION_CHANNEL_SURROUND_RIGHT
IPATCH_DLS2_REGION_CHANNEL_LEFT_OF_CENTER
IPATCH_DLS2_REGION_CHANNEL_RIGHT_OF_CENTER
IPATCH_DLS2_REGION_CHANNEL_SURROUND_CENTER
IPATCH_DLS2_REGION_CHANNEL_SIDE_LEFT
IPATCH_DLS2_REGION_CHANNEL_SIDE_RIGHT
IPATCH_DLS2_REGION_CHANNEL_TOP
IPATCH_DLS2_REGION_CHANNEL_TOP_FRONT_LEFT
IPATCH_DLS2_REGION_CHANNEL_TOP_FRONT_CENTER
IPATCH_DLS2_REGION_CHANNEL_TOP_FRONT_RIGHT
IPATCH_DLS2_REGION_CHANNEL_TOP_REAR_LEFT
IPATCH_DLS2_REGION_CHANNEL_TOP_REAR_CENTER
IPATCH_DLS2_REGION_CHANNEL_TOP_REAR_RIGHT

IPATCH_DLS2_REGION_CHANNEL_MONO

#define IPATCH_DLS2_REGION_CHANNEL_MONO  IPATCH_DLS2_REGION_CHANNEL_LEFT

enum IpatchDLS2RegionFlags

Members

IPATCH_DLS2_REGION_SELF_NON_EXCLUSIVE
IPATCH_DLS2_REGION_PHASE_MASTER
IPATCH_DLS2_REGION_MULTI_CHANNEL
IPATCH_DLS2_REGION_SAMPLE_INFO_OVERRIDE

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)

Property Details

The `“archive-location”` property

  “archive-location”         char *

Location where subject is archived.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“artist”` property

  “artist”                   char *

Original artist.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“channel”` property

  “channel”                  int

DLS audio channel identifier.

Owner: IpatchDLS2Region

Flags: Read / Write

Allowed values: [0,262143]

Default value: 0

The `“comment”` property

  “comment”                  char *

Comments.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“commissioned”` property

  “commissioned”             char *

Who commissioned the material.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“copyright”` property

  “copyright”                char *

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“date”` property

  “date”                     char *

Creation date (YYYY-MM-DD).

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“engineer”` property

  “engineer”                 char *

Engineers separated by "; ".

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“fine-tune”` property

  “fine-tune”                int

Fine tuning in cents.

Owner: IpatchDLS2Region

Flags: Read / Write

Allowed values: [-99,99]

Default value: 0

The `“flags”` property

  “flags”                    IpatchDLS2SampleFlags

Sample flags.

Owner: IpatchDLS2Region

Flags: Read / Write

The `“gain”` property

  “gain”                     int

Gain in DLS relative gain units.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: 0

The `“genre”` property

  “genre”                    char *

Genre.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“key-group”` property

  “key-group”                int

Percussion key group.

Owner: IpatchDLS2Region

Flags: Read / Write

Allowed values: [0,15]

Default value: 0

The `“keywords”` property

  “keywords”                 char *

Keywords (separated by "; ").

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“layer-group”` property

  “layer-group”              int

Layer group.

Owner: IpatchDLS2Region

Flags: Read / Write

Allowed values: [0,65535]

Default value: 0

The `“link-item”` property

  “link-item”                IpatchDLS2Sample *

Link item.

Owner: IpatchDLS2Region

Flags: Read / Write

The `“loop-end”` property

  “loop-end”                 guint

Loop end in frames (after loop).

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: 0

The `“loop-start”` property

  “loop-start”               guint

Start of loop in frames.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: 0

The `“loop-type”` property

  “loop-type”                IpatchSampleLoopType

Loop method type.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: IPATCH_SAMPLE_LOOP_NONE

The `“medium”` property

  “medium”                   char *

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

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“multi-channel”` property

  “multi-channel”            gboolean

Multi channel.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: FALSE

The `“name”` property

  “name”                     char *

Name.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: "untitled"

The `“note-range”` property

  “note-range”               IpatchRange *

MIDI note range.

Owner: IpatchDLS2Region

Flags: Read / Write

The `“phase-group”` property

  “phase-group”              int

Phase locked sample group.

Owner: IpatchDLS2Region

Flags: Read / Write

Allowed values: [0,65535]

Default value: 0

The `“phase-master”` property

  “phase-master”             gboolean

Multi channel phase lock master.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: FALSE

The `“product”` property

  “product”                  char *

Product intended for.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“root-note”` property

  “root-note”                int

Root MIDI note.

Owner: IpatchDLS2Region

Flags: Read / Write

Allowed values: [0,127]

Default value: 60

The `“sample-info-override”` property

  “sample-info-override”     gboolean

Override sample info.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: FALSE

The `“self-non-exclusive”` property

  “self-non-exclusive”       gboolean

Self non exclusive.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: FALSE

The `“software”` property

  “software”                 char *

Editor software used.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“source”` property

  “source”                   char *

Source of the original material.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“source-form”` property

  “source-form”              char *

Original source that was digitized.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“subject”` property

  “subject”                  char *

Subject of the material.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“technician”` property

  “technician”               char *

Technician who sampled the material.

Owner: IpatchDLS2Region

Flags: Read / Write

Default value: NULL

The `“velocity-range”` property

  “velocity-range”           IpatchRange *

MIDI velocity range.

Owner: IpatchDLS2Region

Flags: Read / Write