libbtcore: Buzztrax Bt-Core Reference Manual

## libbtcore libbtcore — core library of the buzztrax application framework |

## Functions

#define | BT_IS_GVALUE()
#define | BT_IS_STRING()
guint | bt_cpu_load_get_current ()
void | bt_init ()
void | bt_init_add_option_groups ()
gboolean | bt_init_check ()
GOptionGroup * | bt_init_get_option_group ()
void | bt_deinit ()
#define | return_if_disposed
#define | return_val_if_disposed()
#define | safe_string()
#define | G_OBJECT_REF_COUNT()
#define | G_OBJECT_LOG_REF_COUNT()
GType | bt_g_type_get_base_type ()
guint | bt_g_object_idle_add ()
gulong | bt_g_signal_connect ()
#define | g_object_try_ref()
#define | g_object_try_unref()
#define | g_object_try_weak_ref()
#define | g_object_try_weak_unref()
gboolean | bt_bin_activate_tee_chain ()
gboolean | bt_bin_deactivate_tee_chain ()
GstClockTime | bt_gst_analyzer_get_waittime ()
GList * | bt_gst_check_core_elements ()
GList * | bt_gst_check_elements ()
const gchar * | bt_gst_debug_pad_link_return ()
GstPadTemplate * | bt_gst_element_factory_get_pad_template ()
gboolean | bt_gst_element_factory_can_sink_media_type ()
GList * | bt_gst_registry_get_element_factories_matching_all_categories ()
GList * | bt_gst_registry_get_element_names_matching_all_categories ()
gboolean | bt_gst_try_element ()
gdouble | bt_gst_level_message_get_aggregated_field ()
const gchar * | bt_str_format_double ()
const gchar * | bt_str_format_enum ()
const gchar * | bt_str_format_long ()
const gchar * | bt_str_format_uchar ()
const gchar * | bt_str_format_ulong ()
gint | bt_str_parse_enum ()
gchar * | bt_str_format_gvalue ()
gboolean | bt_str_parse_gvalue ()

## Types and Values

extern const guint | bt_major_version
extern const guint | bt_micro_version
extern const guint | bt_minor_version
#define | G_OBJECT_REF_COUNT_FMT

## Includes

    #include <libbtcore/core.h>

## Description

The library offers base objects such as BtApplication and BtSong.

## Functions

### BT_IS_GVALUE()

    #define BT_IS_GVALUE(v) (G_VALUE_TYPE(v)!=G_TYPE_INVALID)

checks if the supplied gvalue is initialized (not all fields zero).

#### Parameters

v | pointer to a GValue |

### BT_IS_STRING()

    #define BT_IS_STRING(a) (a && *a)

Checks if the supplied string pointer is not `NULL` and contains not just '\0'

#### Parameters

a | string pointer |

### bt_cpu_load_get_current ()

    guint
    bt_cpu_load_get_current (void);

Determines the current CPU load. Run this from a timeout handler (with e.g. a 1 second interval).

#### Returns

CPU usage as integer ranging from 0% to 100%

### bt_init ()

    void
    bt_init (gint *argc,
             gchar **argv[]);

Initializes the Buzztrax Core library.

This function will terminate your program if it was unable to initialize the core for some reason. If you want your program to fall back, use `bt_init_check()` instead.

WARNING: This function does not work in the same way as corresponding functions in other glib-style libraries, such as `gtk_init()`. In particular, unknown command line options cause this function to abort program execution.

#### Parameters

argc | pointer to application's argc. | [inout][allow-none]
argv | pointer to application's argv. | [inout][array length=argc][allow-none]

### bt_init_add_option_groups ()

    void
    bt_init_add_option_groups (GOptionContext * const ctx);

Adds all option groups to the main context the core library will pull in.

#### Parameters

ctx | main option context |

### bt_init_check ()

    gboolean
    bt_init_check (gint *argc,
                   gchar **argv[],
                   GError **err);

Initializes the Buzztrax core library.

This function will return `FALSE` if Buzztrax core could not be initialized for some reason. If you want your program to fail fatally, use `bt_init()` instead.

#### Parameters

argc | pointer to application's argc. | [inout][allow-none]
argv | pointer to application's argv. | [inout][array length=argc][allow-none]
err | pointer to a GError to which a message will be posted on error |

#### Returns

`TRUE` if Buzztrax core could be initialized.

### bt_init_get_option_group ()

    GOptionGroup *
    bt_init_get_option_group (void);

Returns a GOptionGroup with libbtcore's argument specifications. The group is set up to use standard GOption callbacks, so when using this group in combination with GOption parsing methods, all argument parsing and initialization is automated.

This function is useful if you want to integrate libbtcore with other libraries that use GOption (see `g_option_context_add_group()` ).

[skip]

#### Returns

a pointer to a GOption group. Should be dereferenced after use.

[transfer full]

### bt_deinit ()

    void
    bt_deinit (void);

It is normally not needed to call this function in a normal application as the resources will automatically be freed when the program terminates. This function is therefore mostly used by testsuites and other memory profiling tools.

### return_if_disposed

    #define return_if_disposed() if(self->priv->dispose_has_run) return

Checks `self->priv->dispose_has_run` and if `TRUE` returns. This macro is handy to use at the start of all class routines such as `GObjectClass.get_property()`, `GObjectClass.set_property()`, `GObjectClass.dispose()`.

### return_val_if_disposed()

    #define return_val_if_disposed(a) if(self->priv->dispose_has_run) return(a)

Checks `self->priv->dispose_has_run` and if `TRUE` returns with the supplied arg `a` . This macro is handy to use at the start of e.g. idle handlers.

#### Parameters

a | return value |

### safe_string()

    #define safe_string(a) ((gchar *)(a)?(gchar *)(a):"")

Pass the supplied string through or return an empty string when it is `NULL`.

#### Parameters

a | string pointer |

#### Returns

the given string or an empty string in the case of a `NULL` argument

### G_OBJECT_REF_COUNT()

    #define G_OBJECT_REF_COUNT(obj) ((obj)?((G_OBJECT(obj))->ref_count):0)

Read the objects reference counter. Implemented as a macro, so don't use expressions for `obj` .

#### Parameters

obj | the object (may be `NULL`) |

#### Returns

the reference counter.

### G_OBJECT_LOG_REF_COUNT()

    #define             G_OBJECT_LOG_REF_COUNT(o)

Logs an object pointer together with its refcount value and the floating flag. Use with G_OBJECT_REF_COUNT_FMT.

#### Parameters

o | the object (may be `NULL`) |

### bt_g_type_get_base_type ()

    GType
    bt_g_type_get_base_type (const GType type);

Call `g_type_parent()` as long as it returns a parent.

#### Parameters

type | a GType |

#### Returns

the super parent type, aka base type.

### bt_g_object_idle_add ()

    guint
    bt_g_object_idle_add (GObject *obj,
                          gint pri,
                          GSourceFunc func);

A `g_idle_add_full()` variant, that passes `obj` as user_data and detaches the handler when `obj` gets destroyed.

#### Parameters

obj | the old GObject |
pri | the priority of the idle source. |
func | the callback. | [scope async]

#### Returns

the handler id

### bt_g_signal_connect ()

    gulong
    bt_g_signal_connect (gpointer instance,
                         const gchar *detailed_signal,
                         GCallback c_handler,
                         gpointer data);

Like `g_signal_connect()`, but checks first if the handler is already connected.

#### Parameters

instance | the instance to connect to. | [type GObject.Object]
detailed_signal | a string of the form "signal-name::detail". |
c_handler | the GCallback to connect. | [scope async]
data | data to pass to c_handler calls. |

#### Returns

the handler id

### g_object_try_ref()

    #define             g_object_try_ref(obj)

If the supplied object is not `NULL` then reference it via `g_object_ref()`.

#### Parameters

obj | the object to reference |

#### Returns

the referenced object or `NULL`

### g_object_try_unref()

    #define             g_object_try_unref(obj)

If the supplied object is not `NULL` then release the reference via `g_object_unref()`.

#### Parameters

obj | the object to release the reference |

### g_object_try_weak_ref()

    #define             g_object_try_weak_ref(obj)

If the supplied object is not `NULL` then reference it via `g_object_add_weak_pointer()`.

#### Parameters

obj | the object to reference |

### g_object_try_weak_unref()

    #define             g_object_try_weak_unref(obj)

If the supplied object is not `NULL` then release the reference via `g_object_remove_weak_pointer()`.

#### Parameters

obj | the object to release the reference |

### bt_bin_activate_tee_chain ()

    gboolean
    bt_bin_activate_tee_chain (GstBin *bin,
                               GstElement *tee,
                               GList *elements,
                               gboolean is_playing);

Add the `elements` to the `bin` and link them. Handle pad blocking in playing mode.

Return: `TRUE` for success

#### Parameters

bin | the bin |
tee | the tee to connect the chain to |
elements | the list of elements to activate. | [element-type Gst.Element]
is_playing | whether the pipeline is streaming data |

### bt_bin_deactivate_tee_chain ()

    gboolean
    bt_bin_deactivate_tee_chain (GstBin *bin,
                                 GstElement *tee,
                                 GList *elements,
                                 gboolean is_playing);

Add the `elements` to the `bin` and link them. Handle pad blocking in playing mode.

Return: `TRUE` for success

#### Parameters

bin | the bin |
tee | the tee to connect the chain to |
elements | the list of elements to deactivate. | [element-type Gst.Element]
is_playing | wheter the pipeline is streaming data |

### bt_gst_analyzer_get_waittime ()

    GstClockTime
    bt_gst_analyzer_get_waittime (GstElement *analyzer,
                                  const GstStructure *structure,
                                  gboolean endtime_is_running_time);

Get the time to wait for audio corresponding to the analyzed data to be rendered.

#### Parameters

analyzer | the analyzer |
structure | the message data |
endtime_is_running_time | some elements (level) report endtime as running time and therefore need segment correction |

#### Returns

the wait time in ns.

### bt_gst_check_core_elements ()

    GList *
    bt_gst_check_core_elements (void);

Check if all core elements exist.

#### Returns

a list of elements that does not exist, `NULL` if all elements exist. The list is static, don't free or modify.

[element-type utf8][transfer none]

### bt_gst_check_elements ()

    GList *
    bt_gst_check_elements (GList *list);

Check if the given elements exist.

#### Parameters

list | a GList with element names. | [element-type utf8]

#### Returns

a list of element-names which do not exist, `NULL` if all elements exist, g_list_free after use.

[element-type utf8][transfer full]

### bt_gst_debug_pad_link_return ()

    const gchar *
    bt_gst_debug_pad_link_return (GstPadLinkReturn link_res,
                                  GstPad *src_pad,
                                  GstPad *sink_pad);

Format a nice debug message from failed pad links.

#### Parameters

link_res | pad link result |
src_pad | the source pad |
sink_pad | the sink pad |

#### Returns

the message. The returned string has to be used before the can be called again, otherwise the previous reult will be overwritten.

[transfer none]

### bt_gst_element_factory_get_pad_template ()

    GstPadTemplate *
    bt_gst_element_factory_get_pad_template
                                   (GstElementFactory *factory,
                                    const gchar *name);

Lookup a pad template by name.

#### Parameters

factory | element factory |
name | name of the pad-template, e.g. "src" or "sink_`u`" |

#### Returns

the pad template or `NULL` if not found.

[transfer full]

### bt_gst_element_factory_can_sink_media_type ()

    gboolean
    bt_gst_element_factory_can_sink_media_type
                                   (GstElementFactory *factory,
                                    const gchar *name);

Check if the sink pads of the given `factory` are compatible with the given `name` . The `name` can e.g. be "audio/x-raw".

#### Parameters

factory | element factory to check |
name | caps type name |

#### Returns

`TRUE` if the pads are compatible.

### bt_gst_registry_get_element_factories_matching_all_categories ()

    GList *
    bt_gst_registry_get_element_factories_matching_all_categories
                                   (const gchar *class_filter);

Iterates over all available elements and filters by categories given in `class_filter` .

#### Parameters

class_filter | path for filtering (e.g. "Sink/Audio") |

#### Returns

list of element factories, use `gst_plugin_feature_list_free()` after use.

[element-type Gst.PluginFeature][transfer full]

Since: 0.6

### bt_gst_registry_get_element_names_matching_all_categories ()

    GList *
    bt_gst_registry_get_element_names_matching_all_categories
                                   (const gchar *class_filter);

Iterates over all available elements and filters by categories given in `class_filter` .

#### Parameters

class_filter | path for filtering (e.g. "Sink/Audio") |

#### Returns

list of read-only element names, g_list_free after use.

[element-type utf8][transfer container]

### bt_gst_try_element ()

    gboolean
    bt_gst_try_element (GstElementFactory *factory,
                        const gchar *format);

Create an instance of the element and try to set it to `GST_STATE_READY`.

#### Parameters

factory | plugin feature to try |
format | required media format |

#### Returns

`TRUE`, if the element is usable

### bt_gst_level_message_get_aggregated_field ()

    gdouble
    bt_gst_level_message_get_aggregated_field
                                   (const GstStructure *structure,
                                    const gchar *field_name,
                                    gdouble default_value);

Aggregate the levels per channel and return the averaged level.

#### Parameters

structure | the message structure |
field_name | the field, such as 'decay' or 'peak' |
default_value | a default, in the case of inf/nan levels |

#### Returns

the average level field for all channels

### bt_str_format_double ()

    const gchar *
    bt_str_format_double (const gdouble val);

Convenience methods, that formats a value to be serialized as a string.

#### Parameters

val | a value |

#### Returns

a reference to static memory containing the formatted value.

[transfer none]

### bt_str_format_enum ()

    const gchar *
    bt_str_format_enum (GType enum_type,
                        gint value);

Convenience methods, that formats a value to be serialized as a string.

#### Parameters

enum_type | the GType for the enum |
value | the integer value for the enum |

#### Returns

a reference to static memory containing the formatted value.

[transfer none]

### bt_str_format_long ()

    const gchar *
    bt_str_format_long (const glong val);

Convenience methods, that formats a value to be serialized as a string.

#### Parameters

val | a value |

#### Returns

a reference to static memory containing the formatted value.

[transfer none]

### bt_str_format_uchar ()

    const gchar *
    bt_str_format_uchar (const guchar val);

Convenience methods, that formats a value to be serialized as a string.

#### Parameters

val | a value |

#### Returns

a reference to static memory containing the formatted value.

[transfer none]

### bt_str_format_ulong ()

    const gchar *
    bt_str_format_ulong (const gulong val);

Convenience methods, that formats a value to be serialized as a string.

#### Parameters

val | a value |

#### Returns

a reference to static memory containing the formatted value.

[transfer none]

### bt_str_parse_enum ()

    gint
    bt_str_parse_enum (GType enum_type,
                       const gchar *str);

Convenience methods, that parses a enum value nick and to get the corresponding integer value.

#### Parameters

enum_type | the GType for the enum |
str | the enum value name |

#### Returns

the integer value for the enum, or -1 for invalid strings.

### bt_str_format_gvalue ()

    gchar *
    bt_str_format_gvalue (GValue * const gvalue);

Returns the string representation of the given `gvalue` . Free it when done.

#### Parameters

gvalue | the event cell |

#### Returns

a newly allocated string with the data or `NULL` on error.

[transfer full]

### bt_str_parse_gvalue ()

    gboolean
    bt_str_parse_gvalue (GValue * const gvalue,
                         const gchar * const svalue);

Stores the supplied value into the given `gvalue` .

#### Parameters

gvalue | a GValue |
svalue | the string representation of the value to store |

#### Returns

`TRUE` for success

## Types and Values

### bt_major_version

    extern const guint bt_major_version;

buzztrax version stamp, major part

### bt_micro_version

    extern const guint bt_micro_version;

buzztrax version stamp, micro part

### bt_minor_version

    extern const guint bt_minor_version;

buzztrax version stamp, minor part

### G_OBJECT_REF_COUNT_FMT

    #define G_OBJECT_REF_COUNT_FMT "p,ref_ct=%d,floating=%d"

Printf format string for G_OBJECT_LOG_REF_COUNT.