libbtcore

libbtcore — core library of the buzztrax application framework

Functions

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.