IpatchDLS2Region

IpatchDLS2Region — A DLS region.

Synopsis




                    IpatchDLS2Region;
                    IpatchDLS2RegionClass;
enum                IpatchDLS2RegionChannelType;
#define             IPATCH_DLS2_REGION_CHANNEL_MONO
enum                IpatchDLS2RegionSampleOverride;
#define             IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_MASK
enum                IpatchDLS2RegionFlags;
#define             IPATCH_DLS2_REGION_FLAG_MASK
#define             IPATCH_DLS2_REGION_UNUSED_FLAG_SHIFT
#define             IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_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_ref_sample       (IpatchDLS2Region *region);
IpatchDLS2Sample*   ipatch_dls2_region_peek_sample      (IpatchDLS2Region *region);
guint               ipatch_dls2_region_get_sample_override
                                                        (IpatchDLS2Region *region);
void                ipatch_dls2_region_set_sample_override
                                                        (IpatchDLS2Region *region,
                                                         guint mask);
void                ipatch_dls2_region_set_sample_override_flags
                                                        (IpatchDLS2Region *region,
                                                         guint flags);
void                ipatch_dls2_region_clear_sample_override_flags
                                                        (IpatchDLS2Region *region,
                                                         guint flags);
void                ipatch_dls2_region_set_key_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);
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"         gchararray            : Read / Write
  "artist"                   gchararray            : Read / Write
  "channel"                  gint                  : Read / Write
  "comment"                  gchararray            : Read / Write
  "commissioned"             gchararray            : Read / Write
  "copyright"                gchararray            : Read / Write
  "date"                     gchararray            : Read / Write
  "engineer"                 gchararray            : Read / Write
  "fine-tune"                gint                  : Read / Write
  "flags"                    IpatchDLS2SampleFlags  : Read / Write
  "gain"                     gint                  : Read / Write
  "genre"                    gchararray            : Read / Write
  "key-group"                gint                  : Read / Write
  "key-range"                IpatchRange           : Read / Write
  "keywords"                 gchararray            : 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"                   gchararray            : Read / Write
  "multi-channel"            gboolean              : Read / Write
  "name"                     gchararray            : Read / Write
  "phase-group"              gint                  : Read / Write
  "phase-master"             gboolean              : Read / Write
  "product"                  gchararray            : Read / Write
  "root-note"                gint                  : Read / Write
  "sample"                   IpatchDLS2Sample      : Read / Write
  "sample-override"          IpatchDLS2RegionSampleOverride  : Read / Write
  "self-non-exclusive"       gboolean              : Read / Write
  "software"                 gchararray            : Read / Write
  "source"                   gchararray            : Read / Write
  "source-form"              gchararray            : Read / Write
  "subject"                  gchararray            : Read / Write
  "technician"               gchararray            : Read / Write
  "velocity-range"           IpatchRange           : Read / Write

Description

This object defines a DLS region (analogous to a SoundFont zone - IpatchSF2Zone). Manages a referenced sample, effect connection blocks (IpatchDLS2Conn), and key and velocity ranges among other things. Regions are contained by IpatchDLS2Inst objects.

Details

IpatchDLS2Region

typedef struct _IpatchDLS2Region IpatchDLS2Region;


IpatchDLS2RegionClass

typedef struct {
  IpatchItemClass parent_class;
} IpatchDLS2RegionClass;


enum IpatchDLS2RegionChannelType

typedef enum /*< 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 IpatchDLS2RegionSampleOverride

typedef enum /*< flags >*/
{
  IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_FLAGS      = 1 << 0,
  IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_LOOP       = 1 << 1,
  IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_ROOT_NOTE  = 1 << 2,
  IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_FINE_TUNE  = 1 << 3,
  IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_GAIN       = 1 << 4,
  IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_LOOP_START = 1 << 5,
  IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_LOOP_SIZE  = 1 << 6
} IpatchDLS2RegionSampleOverride;


IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_MASK

#define IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_MASK  0x7F


enum IpatchDLS2RegionFlags

typedef enum /*< flags >*/
{
  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)
} 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_DLS2_REGION_SAMPLE_OVERRIDE_SHIFT

#define             IPATCH_DLS2_REGION_SAMPLE_OVERRIDE_SHIFT


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

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

IpatchDLS2Sample*   ipatch_dls2_region_ref_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_ref_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_get_sample_override ()

guint               ipatch_dls2_region_get_sample_override
                                                        (IpatchDLS2Region *region);

region :
Returns :

ipatch_dls2_region_set_sample_override ()

void                ipatch_dls2_region_set_sample_override
                                                        (IpatchDLS2Region *region,
                                                         guint mask);

Set the sample info override mask of a DLS region. Any flags that are set will cause the specified region sample info field to override the referenced sample info.

region : DLS region
mask : Sample override mask (IpatchDLS2RegionSampleOverride)

ipatch_dls2_region_set_sample_override_flags ()

void                ipatch_dls2_region_set_sample_override_flags
                                                        (IpatchDLS2Region *region,
                                                         guint flags);

Like ipatch_dls2_region_set_sample_override() but only sets flags, does not clear them.

region : DLS region
flags : Sample override flags to set (IpatchDLS2RegionSampleOverride)

ipatch_dls2_region_clear_sample_override_flags ()

void                ipatch_dls2_region_clear_sample_override_flags
                                                        (IpatchDLS2Region *region,
                                                         guint flags);

Like ipatch_dls2_region_set_sample_override_flags() but only clears flags, does not set them.

region : DLS region
flags : Sample override flags to clear (IpatchDLS2RegionSampleOverride)

ipatch_dls2_region_set_key_range ()

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

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

region : Region to set key 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 key 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 key and velocity range, FALSE otherwise

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"         gchararray            : Read / Write

Location of archived material.

Default value: NULL


The "artist" property

  "artist"                   gchararray            : Read / Write

Artist of the original subject material.

Default value: NULL


The "channel" property

  "channel"                  gint                  : Read / Write

DLS channel position enumeration.

Allowed values: [0,262143]

Default value: 0


The "comment" property

  "comment"                  gchararray            : Read / Write

A comment.

Default value: NULL


The "commissioned" property

  "commissioned"             gchararray            : Read / Write

Person or organization who commissioned the material.

Default value: NULL


The "copyright" property

  "copyright"                gchararray            : Read / Write

Copyright information.

Default value: NULL


The "date" property

  "date"                     gchararray            : Read / Write

Creation date in YYYY-MM-DD format.

Default value: NULL


The "engineer" property

  "engineer"                 gchararray            : Read / Write

Name of the engineer who worked on material (if multiple engineers separate with semicolon and a blank).

Default value: NULL


The "fine-tune" property

  "fine-tune"                gint                  : Read / Write

Sample override fine tune amount in DLS relative pitch.

Allowed values: [-99,99]

Default value: 0


The "flags" property

  "flags"                    IpatchDLS2SampleFlags  : Read / Write

Sample override flags for ensuring bit width is not truncated and sample is not compressed by the synthesis engine.


The "gain" property

  "gain"                     gint                  : Read / Write

Sample override gain in DLS relative gain.

Default value: 0


The "genre" property

  "genre"                    gchararray            : Read / Write

Describes the genre of the original work such as electro industrial, gothic, instrumental surf, psycho-billy, EBM, rock, etc.

Default value: NULL


The "key-group" property

  "key-group"                gint                  : Read / Write

Exclusive key group or 0 for no group (used for percussion instruments).

Allowed values: [0,15]

Default value: 0


The "key-range" property

  "key-range"                IpatchRange           : Read / Write

MIDI key range.


The "keywords" property

  "keywords"                 gchararray            : Read / Write

Keywords that refere to the material. Multiple keywords separated by a semicolon and a blank (example: FX; barnyard; animal).

Default value: NULL


The "layer-group" property

  "layer-group"              gint                  : Read / Write

Layer group (used to group regions into layers for user editing convenience).

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

Sample override loop end in samples.

Default value: 0


The "loop-start" property

  "loop-start"               guint                 : Read / Write

Sample override loop start offset in samples.

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"                   gchararray            : Read / Write

Describes the original medium of the material, such as, CD, MP3, etc.

Default value: NULL


The "multi-channel" property

  "multi-channel"            gboolean              : Read / Write

Enables or disables multi-channel mode.

Default value: FALSE


The "name" property

  "name"                     gchararray            : Read / Write

Stores the title of the material.

Default value: "untitled"


The "phase-group" property

  "phase-group"              gint                  : Read / Write

Defines a phase group for phase locked samples or 0 for no phase group.

Allowed values: [0,65535]

Default value: 0


The "phase-master" property

  "phase-master"             gboolean              : Read / Write

Set if a region is to be the phase master of a set of phase locked regions.

Default value: FALSE


The "product" property

  "product"                  gchararray            : Read / Write

The name of the product the material is intended for.

Default value: NULL


The "root-note" property

  "root-note"                gint                  : Read / Write

Sample override root MIDI note.

Allowed values: [0,127]

Default value: 60


The "sample" property

  "sample"                   IpatchDLS2Sample      : Read / Write

Linked sample write parameter.


The "sample-override" property

  "sample-override"          IpatchDLS2RegionSampleOverride  : Read / Write

Sample info override flags. Flags that are set will cause the corresponding sample info field of the region to overide the linked sample.


The "self-non-exclusive" property

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

Set if multiple note-on events without a note-off should not terminate all notes.

Default value: FALSE


The "software" property

  "software"                 gchararray            : Read / Write

Identifies the software used to create the material.

Default value: NULL


The "source" property

  "source"                   gchararray            : Read / Write

Identifies the name of the person or organization who supplied the original material.

Default value: NULL


The "source-form" property

  "source-form"              gchararray            : Read / Write

The original form of the material that was digitally sampled. Not necessarily the same as "medium".

Default value: NULL


The "subject" property

  "subject"                  gchararray            : Read / Write

Defines the subject of the material such as "Music to milk by".

Default value: NULL


The "technician" property

  "technician"               gchararray            : Read / Write

The technician who sampled the material.

Default value: NULL


The "velocity-range" property

  "velocity-range"           IpatchRange           : Read / Write

MIDI velocity range.

See Also

IpatchDLS2Inst