IpatchDLS2

IpatchDLS2 — DLS Object

Synopsis




                    IpatchDLS2;
                    IpatchDLS2Class;
enum                IpatchDLS2Flags;
#define             IPATCH_DLS2_UNUSED_FLAG_SHIFT
IpatchDLS2*         ipatch_dls2_new                     (void);
#define             ipatch_dls2_get_insts               (dls)
#define             ipatch_dls2_get_samples             (dls)
void                ipatch_dls2_set_file                (IpatchDLS2 *dls,
                                                         IpatchDLSFile *file);
IpatchDLSFile*      ipatch_dls2_ref_file                (IpatchDLS2 *dls);
char*               ipatch_dls2_get_info                (IpatchDLS2 *dls,
                                                         guint32 fourcc);
void                ipatch_dls2_set_info                (IpatchDLS2 *dls,
                                                         guint32 fourcc,
                                                         const char *val);
char*               ipatch_dls2_make_unique_name        (IpatchDLS2 *dls,
                                                         GType child_type,
                                                         const char *name,
                                                         const IpatchItem *exclude);
IpatchDLS2Inst*     ipatch_dls2_find_inst_ref           (IpatchDLS2 *dls,
                                                         const char *name,
                                                         int bank,
                                                         int program,
                                                         const IpatchDLS2Inst *exclude);
IpatchDLS2Sample*   ipatch_dls2_find_sample_ref         (IpatchDLS2 *dls,
                                                         const char *name,
                                                         const IpatchDLS2Sample *exclude);
IpatchList*         ipatch_dls2_ref_region_references   (IpatchDLS2Sample *sample);

Object Hierarchy


  GObject
   +----IpatchItem
         +----IpatchContainer
               +----IpatchBase
                     +----IpatchDLS2
                           +----IpatchGig

Properties


  "archive-location"         gchararray            : Read / Write
  "artist"                   gchararray            : Read / Write
  "comment"                  gchararray            : Read / Write
  "commissioned"             gchararray            : Read / Write
  "copyright"                gchararray            : Read / Write
  "date"                     gchararray            : Read / Write
  "engineer"                 gchararray            : Read / Write
  "genre"                    gchararray            : Read / Write
  "keywords"                 gchararray            : Read / Write
  "medium"                   gchararray            : Read / Write
  "name"                     gchararray            : Read / Write
  "product"                  gchararray            : Read / Write
  "software"                 gchararray            : Read / Write
  "source"                   gchararray            : Read / Write
  "source-form"              gchararray            : Read / Write
  "subject"                  gchararray            : Read / Write
  "technician"               gchararray            : Read / Write
  "version"                  gchararray            : Read / Write

Description

This is the toplevel object of a DLS patch. Its a container for IpatchDLS2Inst and IpatchDLS2Sample objects.

Details

IpatchDLS2

typedef struct {
  IpatchBase parent_instance;

  /* NOTE: This is not the DLS version! Optional descriptive stamp version */
  guint32 ms_version; /* most significant 32 bits of 64 bit version */
  guint32 ls_version; /* least significant 32 bits of 64 bit version */

  IpatchDLS2Info *info;		/* info strings */
  GSList *insts;		/* list of #IpatchDLS2Inst objects */
  GSList *samples;		/* list of #IpatchDLS2Sample objects */

  guint8 *dlid;	/* 16 bytes or NULL - globally unique ID (indicates changes) */
} IpatchDLS2;


IpatchDLS2Class

typedef struct {
  IpatchBaseClass parent_class;
} IpatchDLS2Class;


enum IpatchDLS2Flags

typedef enum /*< flags >*/
{
  /* set if the ms_version/ls_version values are valid */
  IPATCH_DLS2_VERSION_SET = 1 << IPATCH_BASE_UNUSED_FLAG_SHIFT
} IpatchDLS2Flags;

Flags in IpatchItem flags field.

IPATCH_DLS2_VERSION_SET Set if version major and minor fields are valid.

IPATCH_DLS2_UNUSED_FLAG_SHIFT

#define IPATCH_DLS2_UNUSED_FLAG_SHIFT (IPATCH_BASE_UNUSED_FLAG_SHIFT + 4)

The next unused flag in the IpatchItem flags field.


ipatch_dls2_new ()

IpatchDLS2*         ipatch_dls2_new                     (void);

Create a new DLS base object.

Returns : New DLS base object with a reference count of 1. Caller owns the reference and removing it will destroy the item.

ipatch_dls2_get_insts()

#define             ipatch_dls2_get_insts(dls)

Get an iterator of the instruments in a DLS object.

dls : DLS object
Returns : Iterator populated with IpatchDLS2Inst objects.

ipatch_dls2_get_samples()

#define             ipatch_dls2_get_samples(dls)

Get an iterator of the samples in a DLS object.

dls : DLS object
Returns : Iterator populated with IpatchDLS2Sample objects.

ipatch_dls2_set_file ()

void                ipatch_dls2_set_file                (IpatchDLS2 *dls,
                                                         IpatchDLSFile *file);

Sets the file object of a DLS object. DLS files are kept open for sample data that references the file. This function sets a DLS object's authoritive file. A convenience function, as ipatch_base_set_file() does the same thing (albeit without more specific type casting).

dls : DLS to set file object of
file : File object to use with the DLS object

ipatch_dls2_ref_file ()

IpatchDLSFile*      ipatch_dls2_ref_file                (IpatchDLS2 *dls);

Gets the file object of a DLS. The returned DLS file object's reference count has been incremented. The caller owns the reference and is responsible for removing it with g_object_unref. A convenience function as ipatch_base_ref_file() does the same thing (albeit without more specific type casting).

dls : DLS object to get file object of
Returns : The DLS file object or NULL if dls is not open. Remember to unref the file object with g_object_unref() when done with it.

ipatch_dls2_get_info ()

char*               ipatch_dls2_get_info                (IpatchDLS2 *dls,
                                                         guint32 fourcc);

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

dls : DLS 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_set_info ()

void                ipatch_dls2_set_info                (IpatchDLS2 *dls,
                                                         guint32 fourcc,
                                                         const char *val);

Sets an INFO value in a DLS object.

Emits changed signal on DLS object.

dls : DLS 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_make_unique_name ()

char*               ipatch_dls2_make_unique_name        (IpatchDLS2 *dls,
                                                         GType child_type,
                                                         const char *name,
                                                         const IpatchItem *exclude);

Generates a unique name for the given child_type in dls. The name parameter is used as a base and is modified, by appending a number, to make it unique (if necessary). The exclude parameter is used to exclude an existing dls child item from the search.

MT-Note: To ensure that an item is actually unique before being added to a DLS object, ipatch_container_add_unique() should be used.

dls : DLS object
child_type : A child type of dls to search for a unique name in
name : An initial name to use or NULL
exclude : An item to exclude from search or NULL
Returns : A new unique name which should be freed when finished with it.

ipatch_dls2_find_inst_ref ()

IpatchDLS2Inst*     ipatch_dls2_find_inst_ref           (IpatchDLS2 *dls,
                                                         const char *name,
                                                         int bank,
                                                         int program,
                                                         const IpatchDLS2Inst *exclude);

Find a instrument by name or bank:program MIDI numbers. If instrument name and bank:program are specified then match for either condition. If a instrument is found its reference count is incremented before it is returned. The caller is responsible for removing the reference with g_object_unref() when finished with it.

dls : DLS object to search in
name : Name of instrument to find or NULL to match any name
bank : MIDI bank number of instrument to search for or -1 to not search by MIDI bank:program numbers
program : MIDI program number of instrument to search for, only used if bank is 0-128
exclude : A instrument to exclude from the search or NULL
Returns : The matching instrument or NULL if not found. Remember to unref the item when finished with it.

ipatch_dls2_find_sample_ref ()

IpatchDLS2Sample*   ipatch_dls2_find_sample_ref         (IpatchDLS2 *dls,
                                                         const char *name,
                                                         const IpatchDLS2Sample *exclude);

Find a sample by name in a SoundFont. If a sample is found its reference count is incremented before it is returned. The caller is responsible for removing the reference with g_object_unref() when finished with it.

dls : SoundFont to search in
name : Name of sample to find
exclude : A sample to exclude from the search or NULL
Returns : The matching sample or NULL if not found. Remember to unref the item when finished with it.

ipatch_dls2_ref_region_references ()

IpatchList*         ipatch_dls2_ref_region_references   (IpatchDLS2Sample *sample);

sample :
Returns :

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 "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 "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 "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 "medium" property

  "medium"                   gchararray            : Read / Write

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

Default value: NULL


The "name" property

  "name"                     gchararray            : Read / Write

Stores the title of the material.

Default value: "untitled"


The "product" property

  "product"                  gchararray            : Read / Write

The name of the product the material is intended for.

Default value: NULL


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 "version" property

  "version"                  gchararray            : Read / Write

A version for the material of the file in the format "major.minor" (not the DLS version!).

Default value: NULL

See Also

IpatchDLS2Inst, IpatchDLS2Sample