## IpatchSF2VoiceCache IpatchSF2VoiceCache — SoundFont voice cache object |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchSF2Voice;
                        IpatchSF2VoiceUpdate;
                        IpatchSF2VoiceSelInfo;
    void                (*IpatchSF2VoiceCacheItemFunc)      (IpatchSF2VoiceCache *cache,
                                                             GObject *item);
                        IpatchSF2VoiceCache;
    int                 (*IpatchSF2VoiceCacheUpdateHandler) (IpatchSF2VoiceCache *cache,
                                                             int *select_values,
                                                             GObject *cache_item,
                                                             GObject *item,
                                                             GParamSpec *pspec,
                                                             const GValue *value,
                                                             IpatchSF2VoiceUpdate *updates,
                                                             guint max_updates);
    enum                IpatchSF2VoiceSelType;
    #define             IPATCH_SF2_VOICE_CACHE_MAX_SEL_VALUES
    #define             IPATCH_SF2_VOICE_SEL_WILDCARD
    #define             ipatch_sf2_voice_cache_declare_item (cache, item)
    #define             IPATCH_SF2_VOICE_CACHE_GET_VOICE    (cache, index)
    IpatchSF2VoiceCache * ipatch_sf2_voice_cache_new        (IpatchSF2VoiceSelInfo *info,
                                                             int sel_count);
    void                ipatch_sf2_voice_cache_set_default_mods
                                                            (IpatchSF2VoiceCache *cache,
                                                             GSList *mods);
    IpatchSF2Voice *    ipatch_sf2_voice_cache_add_voice    (IpatchSF2VoiceCache *cache);
    void                ipatch_sf2_voice_cache_set_voice_range
                                                            (IpatchSF2VoiceCache *cache,
                                                             IpatchSF2Voice *voice,
                                                             guint sel_index,
                                                             int low,
                                                             int high);
    void                ipatch_sf2_voice_set_sample_data    (IpatchSF2Voice *voice,
                                                             IpatchSampleData *sample_data);
    gboolean            ipatch_sf2_voice_cache_sample_data  (IpatchSF2Voice *voice,
                                                             GError **err);
    void                ipatch_sf2_voice_copy               (IpatchSF2Voice *dest,
                                                             IpatchSF2Voice *src);
    void                ipatch_sf2_voice_cache_optimize     (IpatchSF2VoiceCache *cache);
    int                 ipatch_sf2_voice_cache_select       (IpatchSF2VoiceCache *cache,
                                                             int *select_values,
                                                             guint16 *index_array,
                                                             guint16 max_indexes);
    int                 ipatch_sf2_voice_cache_update       (IpatchSF2VoiceCache *cache,
                                                             int *select_values,
                                                             GObject *cache_item,
                                                             GObject *item,
                                                             GParamSpec *pspec,
                                                             const GValue *value,
                                                             IpatchSF2VoiceUpdate *updates,
                                                             guint max_updates);

## Object Hierarchy

      GObject
       +----IpatchSF2VoiceCache

## Description

This is used for pre-processing instruments into arrays of SoundFont compatible voices which can then be accessed very quickly without multi-thread locking or other issues (during synthesis for example).

## Details

### IpatchSF2Voice

    typedef struct {
      /* Set by SF2VoiceCache converter via ipatch_sf2_voice_set_sample_data() */
      IpatchSampleData *sample_data;	/* sample data for voice */
      IpatchSampleStore *sample_store;	/* Cached store */
      guint32 sample_size;			/* size of sample in frames */

      /* Set by SF2VoiceCache converter */
      guint32 loop_start;		/* loop start offset (in samples) */
      guint32 loop_end;   /* loop end offset (in samples, 1st sample after loop) */
      guint32 rate;			/* sample rate */
      guint8 root_note;		/* MIDI root note of sample */
      gint8 fine_tune;		/* fine tune (in cents, -99 - 99) */
      guint16 reserved;		/* reserved (should be 0) */

      IpatchSF2GenArray gen_array;	/* generator effect values */
      GSList *mod_list;		/* modulator list */

      /* IpatchSF2VoiceCache user defined */
      gpointer user_data;           /* Arbitrary data defined by IpatchSF2VoiceCache user */

      /* Set internally */
      int range_index;  /* index in ranges array (int *) to first selection range */
    } IpatchSF2Voice;

### IpatchSF2VoiceUpdate

    typedef struct {
      guint16 voice;	/* index of voice with parameter to update */

      union			/* new value for parameter */
      {
        gint16 ival;
        guint16 uval;
    } IpatchSF2VoiceUpdate;

### IpatchSF2VoiceSelInfo

    typedef struct {
      IpatchSF2VoiceSelType type;
      int param1;
      int param2;				/* currently not used */
    } IpatchSF2VoiceSelInfo;

### IpatchSF2VoiceCacheItemFunc ()

    void                (*IpatchSF2VoiceCacheItemFunc)      (IpatchSF2VoiceCache *cache,
                                                             GObject *item);

A callback function type which is called during voice cache population for each item which the voice cache is dependent on. This can be useful for determining when a voice cache needs to be updated or for real time effects.

`cache` : | Voice cache
`item` : | Item which voice cache is dependent on

### IpatchSF2VoiceCache

    typedef struct _IpatchSF2VoiceCache IpatchSF2VoiceCache;

### IpatchSF2VoiceCacheUpdateHandler ()

    int                 (*IpatchSF2VoiceCacheUpdateHandler) (IpatchSF2VoiceCache *cache,
                                                             int *select_values,
                                                             GObject *cache_item,
                                                             GObject *item,
                                                             GParamSpec *pspec,
                                                             const GValue *value,
                                                             IpatchSF2VoiceUpdate *updates,
                                                             guint max_updates);

Function prototype used to re-calculate SoundFont effect generators for a single object property change. Useful for real time effect changes.

`cache` : | Voice cache to get updates for
`select_values` : | The voice selection criteria to use, should be the same number of select values as in `cache`
`cache_item` : | Original item `cache` was created from
`item` : | Object for which a property changed
`pspec` : | Parameter specification of property which changed
`value` : | The new value of the property
`updates` : | Output array to store updates to
`max_updates` : | Size of `updates` array (max possible update values).
Returns : | Should return number of updates stored to `updates` array. Will be 0 if no updates required.

### enum IpatchSF2VoiceSelType

    typedef enum
    {
      IPATCH_SF2_VOICE_SEL_NOTE,		/* MIDI note range */
      IPATCH_SF2_VOICE_SEL_VELOCITY,	/* MIDI velocity range */
      IPATCH_SF2_VOICE_SEL_AFTER_TOUCH,	/* MIDI aftertouch range */
      IPATCH_SF2_VOICE_SEL_MIDI_CC	/* MIDI custom controller (param1: ctrlnum) */
    } IpatchSF2VoiceSelType;

### IPATCH_SF2_VOICE_CACHE_MAX_SEL_VALUES

    #define IPATCH_SF2_VOICE_CACHE_MAX_SEL_VALUES   32

### IPATCH_SF2_VOICE_SEL_WILDCARD

    #define IPATCH_SF2_VOICE_SEL_WILDCARD (G_MININT)

### ipatch_sf2_voice_cache_declare_item()

    #define             ipatch_sf2_voice_cache_declare_item(cache, item)

### IPATCH_SF2_VOICE_CACHE_GET_VOICE()

    #define             IPATCH_SF2_VOICE_CACHE_GET_VOICE(cache, index)

### ipatch_sf2_voice_cache_new ()

    IpatchSF2VoiceCache * ipatch_sf2_voice_cache_new        (IpatchSF2VoiceSelInfo *info,
                                                             int sel_count);

Create a new SoundFont voice cache object. The `sel_count` parameter defines the number of selection ranges for the cache. Examples of selection ranges include MIDI note and velocity ranges for a voice. The `info` parameter should be a pointer to an array of selection info structures which describes each selection type.

`info` : | Array of selection info structures (length should be `sel_count`), use `NULL` for default selection info (MIDI note and velocity)
`sel_count` : | Count of selection ranges for this cache (ignored if `info` is `NULL`)
Returns : | New SoundFont voice cache with a reference count of 1 which the caller owns.

### ipatch_sf2_voice_cache_set_default_mods ()

    void                ipatch_sf2_voice_cache_set_default_mods
                                                            (IpatchSF2VoiceCache *cache,
                                                             GSList *mods);

Set the default modulator list for the voice cache. Modulator list is used directly and the allocation of the list is taken over by the voice cache.

`cache` : | Voice cache
`mods` : | SoundFont modulator list to use as default (used directly)

### ipatch_sf2_voice_cache_add_voice ()

    IpatchSF2Voice *    ipatch_sf2_voice_cache_add_voice    (IpatchSF2VoiceCache *cache);

Adds a new initialized voice to a SoundFont voice cache.

`cache` : | Voice cache to create voice for
Returns : | Newly allocated and initialized SoundFont voice structure. The sample pointer is set to NULL, generator array is initialized to default absolute unset values, selection ranges are set to G_MININT-G_MAXINT and all other fields are initialized to defaults.

### ipatch_sf2_voice_cache_set_voice_range ()

    void                ipatch_sf2_voice_cache_set_voice_range
                                                            (IpatchSF2VoiceCache *cache,
                                                             IpatchSF2Voice *voice,
                                                             guint sel_index,
                                                             int low,
                                                             int high);

Set a voice selection range. Selection ranges are used for selection criteria such as MIDI velocity and note ranges.

`cache` : | Voice cache object
`voice` : | Voice pointer in cache
`sel_index` : | Selection index
`low` : | Range low value
`high` : | Range high value

### ipatch_sf2_voice_set_sample_data ()

    void                ipatch_sf2_voice_set_sample_data    (IpatchSF2Voice *voice,
                                                             IpatchSampleData *sample_data);

Assign sample data to a SoundFont voice.

`voice` : | SoundFont voice structure
`sample_data` : | Sample data to assign to voice
`err` : | Location to store error info or `NULL` to ignore

### ipatch_sf2_voice_cache_sample_data ()

    gboolean            ipatch_sf2_voice_cache_sample_data  (IpatchSF2Voice *voice,
                                                             GError **err);

Cache an already assigned sample data object of a voice. The sample data is cached as 16 bit mono native endian format, if not already cached, and the new cached sample is assigned to the sample_store field.

`voice` : | SoundFont voice structure
`err` : | Location to store error info or `NULL` to ignore
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set)

### ipatch_sf2_voice_copy ()

    void                ipatch_sf2_voice_copy               (IpatchSF2Voice *dest,
                                                             IpatchSF2Voice *src);

Copy a source (`src`) voice's information to a destination voice (`dest`). Does not copy selection criteria integers in parent IpatchSF2VoiceCache objects.

`dest` : | Destination voice to copy to (initialized to 0s or already valid)
`src` : | Source voice to copy from

### ipatch_sf2_voice_cache_optimize ()

    void                ipatch_sf2_voice_cache_optimize     (IpatchSF2VoiceCache *cache);

Can be called after all voices have been added to a voice cache. Will optimize voice cache for use with `ipatch_sf2_voice_cache_select()`. NOTE: Currently does nothing, but will in the future..

`cache` : | SoundFont voice cache

### ipatch_sf2_voice_cache_select ()

    int                 ipatch_sf2_voice_cache_select       (IpatchSF2VoiceCache *cache,
                                                             int *select_values,
                                                             guint16 *index_array,
                                                             guint16 max_indexes);

Stores pointers to voices matching `select_values` criteria.

`cache` : | SoundFont voice cache
`select_values` : | Array of select values which must be the same length as the voice cache was initialized with. Each selection value is tested against each voice's selection ranges (use IPATCH_SF2_VOICE_SEL_WILDCARD as a wildcard selection value).
`index_array` : | Voice indexes are stored in this array.
`max_indexes` : | Maximum number of voices to match. `index_array` should be at least this value in size.
Returns : | Number of indexes stored to `index_array`.

### ipatch_sf2_voice_cache_update ()

    int                 ipatch_sf2_voice_cache_update       (IpatchSF2VoiceCache *cache,
                                                             int *select_values,
                                                             GObject *cache_item,
                                                             GObject *item,
                                                             GParamSpec *pspec,
                                                             const GValue *value,
                                                             IpatchSF2VoiceUpdate *updates,
                                                             guint max_updates);