IpatchUnit

IpatchUnit — Unit conversion system

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── IpatchUnitInfo

Description

System for registering unit types and conversion functions.

Functions

IpatchValueTransform ()

void
(*IpatchValueTransform) (const GValue *src,
                         GValue *dest);

Transform from one value to another. The src and dest values have already been initialized to specific types and the transform function should convert/process them as necessary.

Parameters

src

Source value to transform from

 

dest

Destination value to transform to

 

ipatch_unit_info_new ()

IpatchUnitInfo *
ipatch_unit_info_new (void);

Allocate a unit info structure for registering unit types with ipatch_unit_register(). Using this function should minimize API changes if additional fields are added to IpatchUnitInfo. Free the returned structure with ipatch_unit_free() when finished registering unit types.

[skip]

Returns

The newly allocated unit info structure.


ipatch_unit_info_free ()

void
ipatch_unit_info_free (IpatchUnitInfo *info);

Free a unit info structure that was created with ipatch_unit_info_new().

[skip]

Parameters

info

Unit info to free

 

ipatch_unit_info_duplicate ()

IpatchUnitInfo *
ipatch_unit_info_duplicate (const IpatchUnitInfo *info);

Duplicate a unit info structure.

[skip]

Parameters

info

Unit info to duplicate

 

Returns

Newly allocated duplicate unit info structure

Since: 1.1.0


ipatch_unit_register ()

guint16
ipatch_unit_register (const IpatchUnitInfo *info);

Add a new unit type to the unit registry. Note that the info structure is shallow copied, so strings should be constant or guaranteed to not be freed. If the <structfield>id</structfield> field is already set (non-zero) in info , then it is used (should be 0 for dynamic unit types). If the <structfield>label</structfield> field of the info structure is NULL then it is set to the i18n translated string for <structfield>name</structfield>. Unit types can not be un-registered. Unit IDs of dynamic (non built-in types) should not be relied apon to always be the same between program executions.

Parameters

info

Unit info (shallow copied).

[transfer none]

Returns

New unit ID


ipatch_unit_lookup ()

IpatchUnitInfo *
ipatch_unit_lookup (guint16 id);

Looks up unit info by ID.

Parameters

id

Unit ID

 

Returns

Unit info structure with id or NULL if not found, returned structure is internal and should not be modified or freed.

[transfer none]


ipatch_unit_lookup_by_name ()

IpatchUnitInfo *
ipatch_unit_lookup_by_name (const char *name);

Looks up unit info by name.

Parameters

name

Unit name identifier

 

Returns

Unit info structure with name or NULL if not found, returned structure is internal and should not be modified or freed.

[transfer none]


ipatch_unit_class_register_map ()

void
ipatch_unit_class_register_map (guint16 class_type,
                                guint16 src_units,
                                guint16 dest_units);

Register a unit class mapping. Unit class types define domains of conversion, an example is the "user" unit class (IPATCH_UNIT_CLASS_USER) which is used to convert values to units digestable by a human. A conversion class is essentially a mapping between unit types, which can then be used to lookup conversion functions.

Parameters

class_type

Class type (see IpatchUnitClassType).

[type IpatchUnitClassType]

src_units

Source unit type of mapping

 

dest_units

Destination unit type for this map

 

ipatch_unit_class_lookup_map ()

IpatchUnitInfo *
ipatch_unit_class_lookup_map (guint16 class_type,
                              guint16 src_units);

Lookup a unit class mapping (see ipatch_unit_class_register_map()).

Parameters

class_type

Class type (see IpatchUnitClassType).

[type IpatchUnitClassType]

src_units

Source unit type of mapping to lookup

 

Returns

Pointer to destination unit info structure, or NULL if not found. Returned structure is internal and should not be modified or freed.

[transfer none]


ipatch_unit_conversion_register ()

void
ipatch_unit_conversion_register (guint16 src_units,
                                 guint16 dest_units,
                                 IpatchValueTransform func);

Register a parameter unit conversion function.

[skip]

Parameters

src_units

Source unit type

 

dest_units

Destination unit type

 

func

Conversion function handler or NULL for unity conversion (the value type will be converted but not the actual value, example: float -> int).

 

ipatch_unit_conversion_register_full ()

void
ipatch_unit_conversion_register_full (guint16 src_units,
                                      guint16 dest_units,
                                      IpatchValueTransform func,
                                      GDestroyNotify notify_func,
                                      gpointer user_data);

Register a parameter unit conversion function. Like ipatch_unit_conversion_register() but friendlier to GObject Introspection.

[rename-to ipatch_unit_conversion_register]

Parameters

src_units

Source unit type

 

dest_units

Destination unit type

 

func

Conversion function handler or NULL for unity conversion (the value type will be converted but not the actual value, example: float to int).

 

notify_func

Destroy notification when conversion function is removed.

[nullable][scope async][closure user_data]

user_data

Data to pass to notify_func callback.

[nullable]

Since: 1.1.0


ipatch_unit_conversion_lookup ()

IpatchValueTransform
ipatch_unit_conversion_lookup (guint16 src_units,
                               guint16 dest_units,
                               gboolean *set);

Lookup a conversion function by source and destination unit types.

[skip]

Parameters

src_units

Source unit type

 

dest_units

Destination unit type

 

set

Location to store a boolean value indicating if the conversion is set, to differentiate between a NULL conversion function and an invalid conversion. Can be NULL in which case this parameter is ignored.

 

Returns

Conversion function pointer or NULL if a unity conversion or no matching handlers (use set to determine which).


ipatch_unit_convert ()

gboolean
ipatch_unit_convert (guint16 src_units,
                     guint16 dest_units,
                     const GValue *src_val,
                     GValue *dest_val);

Convert a value from one unit type to another.

Parameters

src_units

Source unit type ID

 

dest_units

Destination unit type ID

 

src_val

Source value (type should be compatible with the source unit's value type)

 

dest_val

Destination value (value should be initialized to a type that is compatible with the destination unit's value type).

[transfer none]

Returns

TRUE if value was successfully converted, FALSE otherwise (the only reasons for failure are invalid function parameters, no conversion function for the given unit types, or incompatible GValue types in conversion, therefore the return value can be safely ignored if the caller is sure the parameters and types are OK).


ipatch_unit_user_class_convert ()

double
ipatch_unit_user_class_convert (guint16 src_units,
                                const GValue *src_val);

Converts a value to "user" units. User units are unit types that are adequate for human consumption. The IPATCH_UNIT_CLASS_USER map is used to lookup the corresponding user type to convert to. Not all unit types have an associated user type or the src_units type can itself be a user type; in either of these cases the src_val is converted as is (possibly converted from another value type to double).

Parameters

src_units

Source unit type ID

 

src_val

Source value (type should be compatible with the source unit's value type)

 

Returns

The value converted to user units.

Types and Values

enum IpatchUnitFlags

Members

IPATCH_UNIT_LOGARITHMIC

   

IPATCH_UNIT_USER

   

enum IpatchUnitType

Members

IPATCH_UNIT_TYPE_NONE

   

IPATCH_UNIT_TYPE_INT

   

IPATCH_UNIT_TYPE_UINT

   

IPATCH_UNIT_TYPE_RANGE

   

IPATCH_UNIT_TYPE_DECIBELS

   

IPATCH_UNIT_TYPE_PERCENT

   

IPATCH_UNIT_TYPE_SEMITONES

   

IPATCH_UNIT_TYPE_CENTS

   

IPATCH_UNIT_TYPE_TIME_CENTS

   

IPATCH_UNIT_TYPE_SAMPLE_RATE

   

IPATCH_UNIT_TYPE_SAMPLES

   

IPATCH_UNIT_TYPE_HERTZ

   

IPATCH_UNIT_TYPE_SECONDS

   

IPATCH_UNIT_TYPE_MULTIPLIER

   

IPATCH_UNIT_TYPE_DLS_GAIN

   

IPATCH_UNIT_TYPE_DLS_ABS_TIME

   

IPATCH_UNIT_TYPE_DLS_REL_TIME

   

IPATCH_UNIT_TYPE_DLS_ABS_PITCH

   

IPATCH_UNIT_TYPE_DLS_REL_PITCH

   

IPATCH_UNIT_TYPE_DLS_PERCENT

   

IPATCH_UNIT_TYPE_SF2_ABS_PITCH

   

IPATCH_UNIT_TYPE_SF2_OFS_PITCH

   

IPATCH_UNIT_TYPE_SF2_ABS_TIME

   

IPATCH_UNIT_TYPE_SF2_OFS_TIME

   

IPATCH_UNIT_TYPE_CENTIBELS

   

IPATCH_UNIT_TYPE_32K_SAMPLES

   

IPATCH_UNIT_TYPE_TENTH_PERCENT

   

enum IpatchUnitClassType

Members

IPATCH_UNIT_CLASS_NONE

   

IPATCH_UNIT_CLASS_USER

   

IPATCH_UNIT_CLASS_DLS

   

IPATCH_UNIT_CLASS_COUNT