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);