![]() |
![]() |
![]() |
libInstPatch Reference Manual | ![]() |
---|---|---|---|---|
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);
"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
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.
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;
#define IPATCH_DLS2_REGION_CHANNEL_MONO IPATCH_DLS2_REGION_CHANNEL_LEFT
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;
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;
#define IPATCH_DLS2_REGION_FLAG_MASK (0x0F << IPATCH_ITEM_UNUSED_FLAG_SHIFT)
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. |
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.
|
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.
|
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.
|
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.
|
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 |
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.
|
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.
|
guint ipatch_dls2_region_get_sample_override (IpatchDLS2Region *region);
region : |
|
Returns : |
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) |
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) |
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) |
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) |
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) |
gboolean ipatch_dls2_region_in_range (IpatchDLS2Region *region, int note, int velocity);
Check if a key and velocity falls in a region's ranges
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.
|
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 |
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 |
void ipatch_dls2_region_unset_all_conns (IpatchDLS2Region *region);
Remove all connections in a region.
region : |
DLS region |
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 |
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 |
archive-location
" property"archive-location" gchararray : Read / Write
Location of archived material.
Default value: NULL
artist
" property"artist" gchararray : Read / Write
Artist of the original subject material.
Default value: NULL
channel
" property"channel" gint : Read / Write
DLS channel position enumeration.
Allowed values: [0,262143]
Default value: 0
commissioned
" property"commissioned" gchararray : Read / Write
Person or organization who commissioned the material.
Default value: NULL
copyright
" property"copyright" gchararray : Read / Write
Copyright information.
Default value: NULL
date
" property"date" gchararray : Read / Write
Creation date in YYYY-MM-DD format.
Default value: NULL
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
fine-tune
" property"fine-tune" gint : Read / Write
Sample override fine tune amount in DLS relative pitch.
Allowed values: [-99,99]
Default value: 0
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.
gain
" property"gain" gint : Read / Write
Sample override gain in DLS relative gain.
Default value: 0
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
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
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
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
loop-end
" property"loop-end" guint : Read / Write
Sample override loop end in samples.
Default value: 0
loop-start
" property"loop-start" guint : Read / Write
Sample override loop start offset in samples.
Default value: 0
loop-type
" property"loop-type" IpatchSampleLoopType : Read / Write
Loop method type.
Default value: IPATCH_SAMPLE_LOOP_NONE
medium
" property"medium" gchararray : Read / Write
Describes the original medium of the material, such as, CD, MP3, etc.
Default value: NULL
multi-channel
" property"multi-channel" gboolean : Read / Write
Enables or disables multi-channel mode.
Default value: FALSE
name
" property"name" gchararray : Read / Write
Stores the title of the material.
Default value: "untitled"
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
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
product
" property"product" gchararray : Read / Write
The name of the product the material is intended for.
Default value: NULL
root-note
" property"root-note" gint : Read / Write
Sample override root MIDI note.
Allowed values: [0,127]
Default value: 60
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.
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
software
" property"software" gchararray : Read / Write
Identifies the software used to create the material.
Default value: NULL
source
" property"source" gchararray : Read / Write
Identifies the name of the person or organization who supplied the original material.
Default value: NULL
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
subject
" property"subject" gchararray : Read / Write
Defines the subject of the material such as "Music to milk by".
Default value: NULL
technician
" property"technician" gchararray : Read / Write
The technician who sampled the material.
Default value: NULL