IpatchSF2

IpatchSF2 — SoundFont instrument file object

Stability Level

Stable, unless otherwise indicated

Synopsis

                    IpatchSF2;
enum                IpatchSF2Flags;
#define             IPATCH_SF2_UNUSED_FLAG_SHIFT
enum                IpatchSF2InfoType;
#define             IPATCH_SF2_INFO_COUNT
#define             IPATCH_SF2_DEFAULT_ENGINE
IpatchSF2 *         ipatch_sf2_new                      (void);
#define             ipatch_sf2_get_presets              (sfont)
#define             ipatch_sf2_get_insts                (sfont)
#define             ipatch_sf2_get_samples              (sfont)
void                ipatch_sf2_set_file                 (IpatchSF2 *sf,
                                                         IpatchSF2File *file);
IpatchSF2File *     ipatch_sf2_get_file                 (IpatchSF2 *sf);
char *              ipatch_sf2_get_info                 (IpatchSF2 *sf,
                                                         IpatchSF2InfoType id);
void                ipatch_sf2_set_info                 (IpatchSF2 *sf,
                                                         IpatchSF2InfoType id,
                                                         const char *val);
IpatchSF2Info *     ipatch_sf2_get_info_array           (IpatchSF2 *sf);
void                ipatch_sf2_free_info_array          (IpatchSF2Info *array);
gboolean            ipatch_sf2_info_id_is_valid         (guint32 id);
int                 ipatch_sf2_get_info_max_size        (IpatchSF2InfoType infotype);
IpatchSF2Preset *   ipatch_sf2_find_preset              (IpatchSF2 *sf,
                                                         const char *name,
                                                         int bank,
                                                         int program,
                                                         const IpatchSF2Preset *exclude);
IpatchSF2Inst *     ipatch_sf2_find_inst                (IpatchSF2 *sf,
                                                         const char *name,
                                                         const IpatchSF2Inst *exclude);
IpatchSF2Sample *   ipatch_sf2_find_sample              (IpatchSF2 *sf,
                                                         const char *name,
                                                         const IpatchSF2Sample *exclude);
IpatchList *        ipatch_sf2_get_zone_references      (IpatchItem *item);
char *              ipatch_sf2_make_unique_name         (IpatchSF2 *sfont,
                                                         GType child_type,
                                                         const char *name,
                                                         const IpatchItem *exclude);

Object Hierarchy

  GObject
   +----IpatchItem
         +----IpatchContainer
               +----IpatchBase
                     +----IpatchSF2

Properties

  "author"                   gchar*                : Read / Write
  "comment"                  gchar*                : Read / Write
  "copyright"                gchar*                : Read / Write
  "date"                     gchar*                : Read / Write
  "engine"                   gchar*                : Read / Write
  "name"                     gchar*                : Read / Write
  "product"                  gchar*                : Read / Write
  "rom-name"                 gchar*                : Read / Write
  "rom-version"              gchar*                : Read / Write
  "samples-24bit"            gboolean              : Read / Write
  "software"                 gchar*                : Read / Write
  "version"                  gchar*                : Read / Write

Description

SoundFont version 2 instrument file object. Parent to IpatchSF2Preset, IpatchSF2Inst and IpatchSF2Sample objects.

Details

IpatchSF2

typedef struct {
  IpatchBase parent_instance;

  guint16 ver_major, ver_minor; /* SoundFont version */
  guint16 romver_major, romver_minor; /* ROM version (if any) */

  GHashTable *info;		/* hash of info strings by 4 char ID */
  GSList *presets;		/* list of #IpatchSF2Preset structures */
  GSList *insts;		/* list of #IpatchSF2Inst structures */
  GSList *samples;		/* list of #IpatchSF2Sample structures */
} IpatchSF2;

enum IpatchSF2Flags

typedef enum
{
  /* SoundFont 24 bit samples enabled flag */
  IPATCH_SF2_SAMPLES_24BIT = 1 << IPATCH_BASE_UNUSED_FLAG_SHIFT
} IpatchSF2Flags;

IPATCH_SF2_UNUSED_FLAG_SHIFT

#define IPATCH_SF2_UNUSED_FLAG_SHIFT (IPATCH_BASE_UNUSED_FLAG_SHIFT + 3)

enum IpatchSF2InfoType

typedef enum
{
  IPATCH_SF2_UNKNOWN,		/* unknown chunk ("NULL" value) */
  IPATCH_SF2_VERSION = IPATCH_SFONT_FOURCC_IFIL, /* SoundFont version */
  IPATCH_SF2_ENGINE = IPATCH_SFONT_FOURCC_ISNG,/* target sound engine */
  IPATCH_SF2_NAME = IPATCH_SFONT_FOURCC_INAM, /* SoundFont name */
  IPATCH_SF2_ROM_NAME = IPATCH_SFONT_FOURCC_IROM, /* ROM name */
  IPATCH_SF2_ROM_VERSION = IPATCH_SFONT_FOURCC_IVER, /* ROM version */
  IPATCH_SF2_DATE = IPATCH_SFONT_FOURCC_ICRD, /* creation date */
  IPATCH_SF2_AUTHOR = IPATCH_SFONT_FOURCC_IENG,/* sound designers/engineers */
  IPATCH_SF2_PRODUCT = IPATCH_SFONT_FOURCC_IPRD, /* product intended for */
  IPATCH_SF2_COPYRIGHT = IPATCH_SFONT_FOURCC_ICOP, /* copyright message */
  IPATCH_SF2_COMMENT = IPATCH_SFONT_FOURCC_ICMT, /* comments */
  IPATCH_SF2_SOFTWARE = IPATCH_SFONT_FOURCC_ISFT /* software "create:modify" */
}IpatchSF2InfoType;

IPATCH_SF2_INFO_COUNT

#define IPATCH_SF2_INFO_COUNT 11

IPATCH_SF2_DEFAULT_ENGINE

#define IPATCH_SF2_DEFAULT_ENGINE "EMU8000"

ipatch_sf2_new ()

IpatchSF2 *         ipatch_sf2_new                      (void);

Create a new SoundFont base object.

Returns :

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

ipatch_sf2_get_presets()

#define             ipatch_sf2_get_presets(sfont)

ipatch_sf2_get_insts()

#define             ipatch_sf2_get_insts(sfont)

ipatch_sf2_get_samples()

#define             ipatch_sf2_get_samples(sfont)

ipatch_sf2_set_file ()

void                ipatch_sf2_set_file                 (IpatchSF2 *sf,
                                                         IpatchSF2File *file);

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

sf :

 SoundFont to set file object of

file :

 File object to use with the SoundFont.

ipatch_sf2_get_file ()

IpatchSF2File *     ipatch_sf2_get_file                 (IpatchSF2 *sf);

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

sf :

 SoundFont to get file object of

Returns :

 The SoundFont file object or NULL if sf is not open. Remember to unref the file object with g_object_unref() when done with it.

ipatch_sf2_get_info ()

char *              ipatch_sf2_get_info                 (IpatchSF2 *sf,
                                                         IpatchSF2InfoType id);

Get a SoundFont info string by RIFF FOURCC ID.

sf :

 SoundFont to get info from

id :

 RIFF FOURCC id

Returns :

 New allocated info string value or NULL if no info with the given id. String should be freed when finished with it.

ipatch_sf2_set_info ()

void                ipatch_sf2_set_info                 (IpatchSF2 *sf,
                                                         IpatchSF2InfoType id,
                                                         const char *val);

Set SoundFont info. Validates id and ensures val does not exceed the maximum allowed length for the given info type.

Emits changed signal on SoundFont.

sf :

 SoundFont to set info of

id :

 RIFF FOURCC id

val :

 Value to set info to or NULL to unset (clear) info.

ipatch_sf2_get_info_array ()

IpatchSF2Info *     ipatch_sf2_get_info_array           (IpatchSF2 *sf);

Get all string info (not IPATCH_SF2_VERSION or IPATCH_SF2_ROM_VERSION) from a SoundFont object. The array is sorted in the order recommended by the SoundFont standard for saving.

sf :

 SoundFont to get all info strings from

Returns :

 A newly allocated array of info structures terminated by an array member with 0 valued id field. Remember to free the array with ipatch_sf2_free_info_array() when finished with it.

ipatch_sf2_free_info_array ()

void                ipatch_sf2_free_info_array          (IpatchSF2Info *array);

Frees an info array returned by ipatch_sf2_get_info_array().

array :

 SoundFont info array

ipatch_sf2_info_id_is_valid ()

gboolean            ipatch_sf2_info_id_is_valid         (guint32 id);

Check if a given RIFF FOURCC id is a valid SoundFont info id.

id :

 RIFF FOURCC id (see IpatchSF2InfoType)

Returns :

 TRUE if id is a valid info id, FALSE otherwise

ipatch_sf2_get_info_max_size ()

int                 ipatch_sf2_get_info_max_size        (IpatchSF2InfoType infotype);

Get maximum chunk size for info chunks.

NOTE: Max size includes terminating NULL character so subtract one from returned value to get max allowed string length.

infotype :

 An info enumeration

Returns :

 Maximum info chunk size or 0 if invalid or variable length info chunk type. Subtract one to get max allowed string length (if returned value was not 0).

ipatch_sf2_find_preset ()

IpatchSF2Preset *   ipatch_sf2_find_preset              (IpatchSF2 *sf,
                                                         const char *name,
                                                         int bank,
                                                         int program,
                                                         const IpatchSF2Preset *exclude);

Find a preset by name or bank:preset MIDI numbers. If preset name and bank:program are specified then match for either condition. If a preset 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.

sf :

 SoundFont to search in

name :

 Name of preset to find or NULL to match any name

bank :

 MIDI bank number of preset to search for or -1 to not search by MIDI bank:program numbers

program :

 MIDI program number of preset to search for, only used if bank is 0-128

exclude :

 A preset to exclude from the search or NULL

Returns :

 The matching preset or NULL if not found. Remember to unref the item when finished with it.

ipatch_sf2_find_inst ()

IpatchSF2Inst *     ipatch_sf2_find_inst                (IpatchSF2 *sf,
                                                         const char *name,
                                                         const IpatchSF2Inst *exclude);

Find an instrument by name in a SoundFont. If a matching 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.

sf :

 SoundFont to search in

name :

 Name of Instrument to find

exclude :

 An 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_sf2_find_sample ()

IpatchSF2Sample *   ipatch_sf2_find_sample              (IpatchSF2 *sf,
                                                         const char *name,
                                                         const IpatchSF2Sample *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.

sf :

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

IpatchList *        ipatch_sf2_get_zone_references      (IpatchItem *item);

Get list of zones referencing an IpatchSF2Inst or IpatchSF2Sample.

item :

 Item to locate referencing zones of, must be of type IpatchSF2Inst or IpatchSF2Sample and be parented to an IpatchSF2 object.

Returns :

 New object list containing IpatchSF2Zone objects that refer to item. The new list object has a reference count of 1 which the caller owns, unreference to free the list.

ipatch_sf2_make_unique_name ()

char *              ipatch_sf2_make_unique_name         (IpatchSF2 *sfont,
                                                         GType child_type,
                                                         const char *name,
                                                         const IpatchItem *exclude);

Generates a unique name for the given child_type in sfont. 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 sfont child item from the search.

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

sfont :

 SoundFont item

child_type :

 A child type of sfont 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.

Property Details

The "author" property

  "author"                   gchar*                : Read / Write

Author of SoundFont.

Default value: NULL

The "comment" property

  "comment"                  gchar*                : Read / Write

Comments.

Default value: NULL

The "copyright" property

  "copyright"                gchar*                : Read / Write

Copyright.

Default value: NULL

The "date" property

  "date"                     gchar*                : Read / Write

Creation date.

Default value: NULL

The "engine" property

  "engine"                   gchar*                : Read / Write

Sound synthesis engine identifier.

Default value: "EMU8000"

The "name" property

  "name"                     gchar*                : Read / Write

SoundFont name.

Default value: NULL

The "product" property

  "product"                  gchar*                : Read / Write

Product SoundFont is intended for.

Default value: NULL

The "rom-name" property

  "rom-name"                 gchar*                : Read / Write

ROM name identifier.

Default value: NULL

The "rom-version" property

  "rom-version"              gchar*                : Read / Write

ROM version "major.minor".

Default value: NULL

The "samples-24bit" property

  "samples-24bit"            gboolean              : Read / Write

Enable 24 bit samples.

Default value: FALSE

The "software" property

  "software"                 gchar*                : Read / Write

Software 'created by:modified by'.

Default value: NULL

The "version" property

  "version"                  gchar*                : Read / Write

SoundFont version ("major.minor").

Default value: "2.01"

See Also

IpatchSF2Preset, IpatchSF2Inst, IpatchSF2Sample
Generated by GTK-Doc V1.15