IpatchSF2Mod

IpatchSF2Mod — SoundFont modulator structure and related functions

Synopsis




                    IpatchSF2Mod;
#define             IPATCH_TYPE_SF2_MOD
#define             IPATCH_SF2_MOD_ARE_IDENTICAL        (a, b)
#define             IPATCH_SF2_MOD_ARE_IDENTICAL_AMOUNT (a, b)
enum                IpatchSF2ModFieldMasks;
enum                IpatchSF2ModFieldShifts;
enum                IpatchSF2ModControl;
enum                IpatchSF2ModControlPalette;
enum                IpatchSF2ModDirection;
enum                IpatchSF2ModPolarity;
enum                IpatchSF2ModType;
enum                IpatchSF2ModTransform;
GType               ipatch_sf2_mod_get_type             (void);
IpatchSF2Mod*       ipatch_sf2_mod_new                  (void);
void                ipatch_sf2_mod_free                 (IpatchSF2Mod *mod);
IpatchSF2Mod*       ipatch_sf2_mod_duplicate            (const IpatchSF2Mod *mod);
GSList*             ipatch_sf2_mod_list_duplicate       (const GSList *list);
GSList*             ipatch_sf2_mod_list_override        (GSList *alist,
                                                         GSList *blist,
                                                         gboolean copy);
GSList*             ipatch_sf2_mod_list_offset          (const GSList *alist,
                                                         const GSList *blist);
void                ipatch_sf2_mod_list_free            (GSList *list,
                                                         gboolean free_mods);
const GSList*       ipatch_sf2_mod_list_get_default     (void);

Description

A SoundFont modulator is a structure defining real time control of a SoundFont generator (IpatchSF2Gen).

Details

IpatchSF2Mod

typedef struct {
  guint16 src;			/* source modulator (MIDI controller, etc) */
  guint16 dest;			/* destination generator */
  gint16 amount;		/* degree of modulation */
  guint16 amtsrc;		/* second source controls amount of first */
  guint16 trans;		/* transform function applied to source */
} IpatchSF2Mod;

Modulator structure.

guint16 src; Control source fields (see IpatchSF2ModFieldMasks).
guint16 dest; Control destination generator (IpatchSF2GenType).
gint16 amount; Signed amount multiplier
guint16 amtsrc; Secondary source fields (see IpatchSF2ModFieldMasks).
guint16 trans; Output transform type (IpatchSF2ModTransform).

IPATCH_TYPE_SF2_MOD

#define IPATCH_TYPE_SF2_MOD   (ipatch_sf2_mod_get_type ())

The GType of a SoundFont modulator (GBoxed type).

Returns : GType of SoundFont modulators.

IPATCH_SF2_MOD_ARE_IDENTICAL()

#define             IPATCH_SF2_MOD_ARE_IDENTICAL(a, b)

Checks if two IpatchSF2Mod objects are identical (matching in all fields except amount).

a : First modulator
b : Second modulator
Returns : TRUE if identical (all fields except amount), FALSE, otherwise

IPATCH_SF2_MOD_ARE_IDENTICAL_AMOUNT()

#define             IPATCH_SF2_MOD_ARE_IDENTICAL_AMOUNT(a, b)

Checks if two IpatchSF2Mod objects are identical (including amount field).

a : First modulator
b : Second modulator
Returns : TRUE if identical in all fields (including amount), FALSE otherwise

enum IpatchSF2ModFieldMasks

typedef enum
{
  IPATCH_SF2_MOD_MASK_CONTROL = 0x007F,
  IPATCH_SF2_MOD_MASK_CC = 0x0080,
  IPATCH_SF2_MOD_MASK_DIRECTION = 0x0100,
  IPATCH_SF2_MOD_MASK_POLARITY = 0x0200,
  IPATCH_SF2_MOD_MASK_TYPE = 0xFC00
} IpatchSF2ModFieldMasks;

Bit masks for the different bit fields within modulator source "enumerators" (src and amtsrc in IpatchSF2Mod).

IPATCH_SF2_MOD_MASK_CONTROL Control ID. If "CC" flag is set then this field is a MIDI custom controller number otherwise its a IpatchSF2ModControl enum.
IPATCH_SF2_MOD_MASK_CC Toggles function of control field (IpatchSF2ModControlPalette)
IPATCH_SF2_MOD_MASK_DIRECTION Direction of control mapping (IpatchSF2ModDirection)
IPATCH_SF2_MOD_MASK_POLARITY Polarity of control mapping (IpatchSF2ModPolarity).
IPATCH_SF2_MOD_MASK_TYPE Mapping function type (IpatchSF2ModType).

enum IpatchSF2ModFieldShifts

typedef enum
{
  IPATCH_SF2_MOD_SHIFT_CONTROL = 0,
  IPATCH_SF2_MOD_SHIFT_CC = 7,
  IPATCH_SF2_MOD_SHIFT_DIRECTION = 8,
  IPATCH_SF2_MOD_SHIFT_POLARITY = 9,
  IPATCH_SF2_MOD_SHIFT_TYPE = 10
} IpatchSF2ModFieldShifts;

Bit shifts to each field within modulator source "enumerators" (src and amtsrc in IpatchSF2Mod). See IpatchSF2ModFieldMasks for descriptions.

IPATCH_SF2_MOD_SHIFT_CONTROL
IPATCH_SF2_MOD_SHIFT_CC Bit shift to CC field.
IPATCH_SF2_MOD_SHIFT_DIRECTION Bit shift to direction field.
IPATCH_SF2_MOD_SHIFT_POLARITY Bit shift to polarity field.
IPATCH_SF2_MOD_SHIFT_TYPE Bit shift to map function type field.

enum IpatchSF2ModControl

typedef enum
{
  IPATCH_SF2_MOD_CONTROL_NONE = 0,
  IPATCH_SF2_MOD_CONTROL_NOTE_ON_VELOCITY = 2,
  IPATCH_SF2_MOD_CONTROL_KEY_NUMBER = 3,
  IPATCH_SF2_MOD_CONTROL_POLY_PRESSURE = 10,
  IPATCH_SF2_MOD_CONTROL_CHAN_PRESSURE = 13,
  IPATCH_SF2_MOD_CONTROL_PITCH_WHEEL = 14,
  IPATCH_SF2_MOD_CONTROL_BEND_RANGE = 16
} IpatchSF2ModControl;

Values for control bit field of modulator source "enumerators" if CC field is not set (IPATCH_SF2_MODE_CC_GENERAL).

IPATCH_SF2_MOD_CONTROL_NONE No controller (equivalent to a constant 1)
IPATCH_SF2_MOD_CONTROL_NOTE_ON_VELOCITY Use MIDI velocity as source control
IPATCH_SF2_MOD_CONTROL_KEY_NUMBER Use MIDI note # as source control
IPATCH_SF2_MOD_CONTROL_POLY_PRESSURE Use MIDI poly pressure as source control
IPATCH_SF2_MOD_CONTROL_CHAN_PRESSURE Use MIDI channel pressure as source control
IPATCH_SF2_MOD_CONTROL_PITCH_WHEEL Use MIDI pitch wheel as source control
IPATCH_SF2_MOD_CONTROL_BEND_RANGE Use MIDI pitch bend range as source control

enum IpatchSF2ModControlPalette

typedef enum
{
  IPATCH_SF2_MOD_CC_GENERAL = (0 << IPATCH_SF2_MOD_SHIFT_CC),
  IPATCH_SF2_MOD_CC_MIDI = (1 << IPATCH_SF2_MOD_SHIFT_CC)
} IpatchSF2ModControlPalette;

Values for CC bit of modulator source "enumerators". Determines function of control bit field.

IPATCH_SF2_MOD_CC_GENERAL Selects general palette of controls (IpatchSF2ModControl).
IPATCH_SF2_MOD_CC_MIDI Control field defines a MIDI custom controller number

enum IpatchSF2ModDirection

typedef enum
{
  IPATCH_SF2_MOD_DIRECTION_POSITIVE = (0 << IPATCH_SF2_MOD_SHIFT_DIRECTION),
  IPATCH_SF2_MOD_DIRECTION_NEGATIVE = (1 << IPATCH_SF2_MOD_SHIFT_DIRECTION)
} IpatchSF2ModDirection;

Values for direction bit of modulator source "enumerators". Determines direction of control mapping function.

IPATCH_SF2_MOD_DIRECTION_POSITIVE Control is mapped as is.
IPATCH_SF2_MOD_DIRECTION_NEGATIVE Control is inversed.

enum IpatchSF2ModPolarity

typedef enum
{
  IPATCH_SF2_MOD_POLARITY_UNIPOLAR = (0 << IPATCH_SF2_MOD_SHIFT_POLARITY),
  IPATCH_SF2_MOD_POLARITY_BIPOLAR = (1 << IPATCH_SF2_MOD_SHIFT_POLARITY)
} IpatchSF2ModPolarity;

Values for polarity bit of modulator source "enumerators". Determines polarity of control mapping function.

IPATCH_SF2_MOD_POLARITY_UNIPOLAR Control is normalized to 0.0 -> 1.0
IPATCH_SF2_MOD_POLARITY_BIPOLAR Control is normalized to -1.0 -> 1.0

enum IpatchSF2ModType

typedef enum
{
  IPATCH_SF2_MOD_TYPE_LINEAR = (0 << IPATCH_SF2_MOD_SHIFT_TYPE),
  IPATCH_SF2_MOD_TYPE_CONCAVE = (1 << IPATCH_SF2_MOD_SHIFT_TYPE),
  IPATCH_SF2_MOD_TYPE_CONVEX = (2 << IPATCH_SF2_MOD_SHIFT_TYPE),
  IPATCH_SF2_MOD_TYPE_SWITCH = (3 << IPATCH_SF2_MOD_SHIFT_TYPE)
} IpatchSF2ModType;

Values for type bit field of modulator source "enumerators". Determines the math function used in mapping control values.

IPATCH_SF2_MOD_TYPE_LINEAR Linear mapping
IPATCH_SF2_MOD_TYPE_CONCAVE Concave mapping (inward curve)
IPATCH_SF2_MOD_TYPE_CONVEX Convex mapping (outward curve)
IPATCH_SF2_MOD_TYPE_SWITCH A switch (on/1.0 or off/0.0)

enum IpatchSF2ModTransform

typedef enum
{
  IPATCH_SF2_MOD_TRANSFORM_LINEAR = 0
} IpatchSF2ModTransform;

Output transform function (only one value defined).

IPATCH_SF2_MOD_TRANSFORM_LINEAR Linear output transform.

ipatch_sf2_mod_get_type ()

GType               ipatch_sf2_mod_get_type             (void);

Get the IpatchSF2Mod boxed type

Returns : Boxed GType of the IpatchSF2Mod structure

ipatch_sf2_mod_new ()

IpatchSF2Mod*       ipatch_sf2_mod_new                  (void);

Create a new modulator

Returns : New modulator

ipatch_sf2_mod_free ()

void                ipatch_sf2_mod_free                 (IpatchSF2Mod *mod);

Free an IpatchSF2Mod structure

mod : Modulator to free, should not be referenced by any zones.

ipatch_sf2_mod_duplicate ()

IpatchSF2Mod*       ipatch_sf2_mod_duplicate            (const IpatchSF2Mod *mod);

Duplicate a modulator

mod : Modulator to duplicate
Returns : New duplicate modulator

ipatch_sf2_mod_list_duplicate ()

GSList*             ipatch_sf2_mod_list_duplicate       (const GSList *list);

Duplicates a modulator list (GSList and modulator data). NOTE: Since this routine is optimized for speed, new list is actually backwards from original.

list : Modulator list to duplicate
Returns : New duplicate modulator list which should be freed with ipatch_sf2_mod_list_free() when finished with it.

ipatch_sf2_mod_list_override ()

GSList*             ipatch_sf2_mod_list_override        (GSList *alist,
                                                         GSList *blist,
                                                         gboolean copy);

Creates a new modulator list by combining alist and blist. Modulators in blist override identical modulators in alist. If copy is set then the modulator data is also duplicated (a new GSList is always created).

alist : First modulator list
blist : Second modulator list
copy : If TRUE then modulator data is duplicated
Returns : New GSList of combined modulator lists. Should be freed with g_slist_free if copy is FALSE or ipatch_sf2_mod_list_free() if TRUE.

ipatch_sf2_mod_list_offset ()

GSList*             ipatch_sf2_mod_list_offset          (const GSList *alist,
                                                         const GSList *blist);

Creates a new modulator list by combining list and blist. Modulators in blist offset (amounts are added) identical modulators in alist. Operation is non-destructive as a new list is created and modulator data is duplicated.

NOTE: Optimized for empty blist.

alist : First modulator list
blist : Second modulator list
Returns : New GSList of combined modulator lists. Should be freed with ipatch_sf2_mod_list_free() when finished with it.

ipatch_sf2_mod_list_free ()

void                ipatch_sf2_mod_list_free            (GSList *list,
                                                         gboolean free_mods);

Free a list of modulators

list : Modulator list to free
free_mods : If TRUE then the modulators themselves are freed, FALSE makes this function act just like g_slist_free() (only the list is freed not the modulators).

ipatch_sf2_mod_list_get_default ()

const GSList*       ipatch_sf2_mod_list_get_default     (void);

Get the list of default instrument modulators.

Returns : The list of default modulators. The same modulator list is returned on subsequent calls and should not be modified or freed.

See Also

IpatchSF2Gen, IpatchSF2IZone, IpatchSF2PZone