BtMachine: Buzztrax Bt-Core Reference Manual

## BtMachine BtMachine — base class for signal processing machines |

## Functions

gboolean | bt_machine_activate_adder ()
gboolean | bt_machine_activate_spreader ()
void | bt_machine_add_pattern ()
void | bt_machine_bind_parameter_control ()
void | bt_machine_bind_poly_parameter_control ()
gboolean | bt_machine_enable_input_gain ()
gboolean | bt_machine_enable_input_post_level ()
gboolean | bt_machine_enable_input_pre_level ()
gboolean | bt_machine_enable_output_gain ()
gboolean | bt_machine_enable_output_post_level ()
gboolean | bt_machine_enable_output_pre_level ()
BtParameterGroup * | bt_machine_get_global_param_group ()
BtCmdPattern * | bt_machine_get_pattern_by_index ()
BtCmdPattern * | bt_machine_get_pattern_by_name ()
BtParameterGroup * | bt_machine_get_prefs_param_group ()
gchar * | bt_machine_get_unique_pattern_name ()
BtParameterGroup * | bt_machine_get_voice_param_group ()
BtWire * | bt_machine_get_wire_by_dst_machine ()
gboolean | bt_machine_handles_waves ()
gboolean | bt_machine_has_active_adder ()
gboolean | bt_machine_has_active_spreader ()
gboolean | bt_machine_has_patterns ()
gboolean | bt_machine_is_polyphonic ()
void | bt_machine_randomize_parameters ()
void | bt_machine_remove_pattern ()
void | bt_machine_reset_parameters ()
void | bt_machine_set_param_defaults ()
void | bt_machine_unbind_parameter_control ()
void | bt_machine_unbind_parameter_controls ()

## Properties

GstElement * | adder-convert | Read
gpointer | construction-error | Read / Write / Construct Only
gulong | global-params | Read
gchar * | id | Read / Write / Construct
GstElement * | input-gain | Read
GstElement * | input-post-level | Read
GstElement * | input-pre-level | Read
GstElement * | machine | Read
GstElement * | output-gain | Read
GstElement * | output-post-level | Read
GstElement * | output-pre-level | Read
gpointer | patterns | Read
gchar * | plugin-name | Read / Write / Construct
gulong | prefs-params | Read
gchar * | pretty-name | Read
gpointer | properties | Read
BtSong * | song | Read / Write / Construct Only
BtMachineState | state | Read / Write
gulong | voice-params | Read
gulong | voices | Read / Write / Construct

## Signals

void | pattern-added | No Hooks
void | pattern-removed | No Hooks

## Types and Values

struct | BtMachine
struct | BtMachineClass
enum | BtMachineState

## Object Hierarchy

        GEnum
        ╰── BtMachineState
        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── GstBin
                        ╰── BtMachine
                            ├── BtProcessorMachine
                            ├── BtSinkMachine
                            ╰── BtSourceMachine

## Implemented Interfaces

BtMachine implements GstChildProxy and BtPersistence.

## Includes

    #include <libbtcore/core.h>

## Description

Machines are pieces in a BtSong that generate, process or play media.

The machine class takes care of inserting additional low-level elemnts to do signal conversion etc.. Further it provides general facillities like input/output level monitoring. The resulting machine instance is a box containing several processing elements.

A machine can have several GstElements:

adder: | mixes all incoming signals
input volume: | gain for incoming signals
input pre/post-gain level: | level meter for incoming signal
machine: | the real machine
output volume: | gain for outgoing signal
output pre/post-gain level: | level meter for outgoing signal
spreader: | distibutes signal to outgoing connections

The adder and spreader elements are activated depending on element type. The volume controls and level meters are activated as requested via the API. It is recommended to only activate them, when needed. The instances are cached after deactivation (so that they can be easily reactivated) and destroyed with the BtMachine object.

Furthermore the machine handles a list of BtCmdPattern instances. These contain event patterns that form a BtSequence.

## Functions

### bt_machine_activate_adder ()

    gboolean
    bt_machine_activate_adder (BtMachine * const self);

Machines use an adder to allow multiple incoming wires. This method is used by the BtWire class to activate the adder when needed.

#### Parameters

self | the machine to activate the adder in |

#### Returns

`TRUE` for success

### bt_machine_activate_spreader ()

    gboolean
    bt_machine_activate_spreader (BtMachine * const self);

Machines use a spreader to allow multiple outgoing wires. This method is used by the BtWire class to activate the spreader when needed.

#### Parameters

self | the machine to activate the spreader in |

#### Returns

`TRUE` for success

### bt_machine_add_pattern ()

    void
    bt_machine_add_pattern (const BtMachine *self,
                            const BtCmdPattern *pattern);

Add the supplied pattern to the machine. This is automatically done by `bt_pattern_new()`.

#### Parameters

self | the machine to add the pattern to |
pattern | the new pattern instance |

### bt_machine_bind_parameter_control ()

    void
    bt_machine_bind_parameter_control (const BtMachine * const self,
                                       GstObject *object,
                                       const gchar *property_name,
                                       BtIcControl *control,
                                       BtParameterGroup *pg);

Connect the interaction control object to the give parameter. Changes of the control-value are mapped into a change of the parameter.

#### Parameters

self | machine |
object | child object (global or voice child) |
property_name | name of the parameter |
control | interaction control object |
pg | the parameter group of the property |

### bt_machine_bind_poly_parameter_control ()

    void
    bt_machine_bind_poly_parameter_control
                                   (const BtMachine * const self,
                                    const gchar *property_name,
                                    BtIcControl *control,
                                    BtParameterGroup *pg);

Connect the interaction control object to the give parameter. Changes of the control-value are mapped into a change of the parameter.

#### Parameters

self | machine |
property_name | name of the parameter |
control | interaction control object |
pg | the parameter group of the property |

### bt_machine_enable_input_gain ()

    gboolean
    bt_machine_enable_input_gain (BtMachine * const self);

Creates the input-gain element of the machine and activates it.

#### Parameters

self | the machine to enable the input-gain element in |

#### Returns

`TRUE` for success, `FALSE` otherwise

### bt_machine_enable_input_post_level ()

    gboolean
    bt_machine_enable_input_post_level (BtMachine * const self);

Creates the post-gain input-level analyser of the machine and activates it.

#### Parameters

self | the machine to enable the post-gain input-level analyser in |

#### Returns

`TRUE` for success, `FALSE` otherwise

### bt_machine_enable_input_pre_level ()

    gboolean
    bt_machine_enable_input_pre_level (BtMachine * const self);

Creates the pre-gain input-level analyser of the machine and activates it.

#### Parameters

self | the machine to enable the pre-gain input-level analyser in |

#### Returns

`TRUE` for success, `FALSE` otherwise

### bt_machine_enable_output_gain ()

    gboolean
    bt_machine_enable_output_gain (BtMachine * const self);

Creates the output-gain element of the machine and activates it.

#### Parameters

self | the machine to enable the output-gain element in |

#### Returns

`TRUE` for success, `FALSE` otherwise

### bt_machine_enable_output_post_level ()

    gboolean
    bt_machine_enable_output_post_level (BtMachine * const self);

Creates the post-gain output-level analyser of the machine and activates it.

#### Parameters

self | the machine to enable the post-gain output-level analyser in |

#### Returns

`TRUE` for success, `FALSE` otherwise

### bt_machine_enable_output_pre_level ()

    gboolean
    bt_machine_enable_output_pre_level (BtMachine * const self);

Creates the pre-gain output-level analyser of the machine and activates it.

#### Parameters

self | the machine to enable the pre-gain output-level analyser in |

#### Returns

`TRUE` for success, `FALSE` otherwise

### bt_machine_get_global_param_group ()

    BtParameterGroup *
    bt_machine_get_global_param_group (const BtMachine * const self);

Get the parameter group of global parameters.

#### Parameters

self | the machine |

#### Returns

the BtParameterGroup or `NULL`.

[transfer none]

### bt_machine_get_pattern_by_index ()

    BtCmdPattern *
    bt_machine_get_pattern_by_index (const BtMachine * const self,
                                     const gulong index);

Fetches the pattern from the given position of the machines pattern list. The pattern must have been added previously to this setup with `bt_machine_add_pattern()`.

#### Parameters

self | the machine to search for the pattern |
index | the index of the pattern in the machines pattern list |

#### Returns

BtCmdPattern instance or `NULL` if not found. Unref the pattern, when done with it.

[transfer full]

### bt_machine_get_pattern_by_name ()

    BtCmdPattern *
    bt_machine_get_pattern_by_name (const BtMachine * const self,
                                    const gchar * const name);

Search the machine for a pattern by the supplied name. The pattern must have been added previously to this setup with `bt_machine_add_pattern()`.

#### Parameters

self | the machine to search for the pattern |
name | the name of the pattern |

#### Returns

BtCmdPattern instance or `NULL` if not found. Unref the pattern, when done with it.

[transfer full]

### bt_machine_get_prefs_param_group ()

    BtParameterGroup *
    bt_machine_get_prefs_param_group (const BtMachine * const self);

Get the parameter group of machine properties. Properties are settings that cannot be changed during playback.

#### Parameters

self | the machine |

#### Returns

the BtParameterGroup or `NULL`.

[transfer none]

### bt_machine_get_unique_pattern_name ()

    gchar *
    bt_machine_get_unique_pattern_name (const BtMachine * const self);

The function generates a unique pattern name for this machine by eventually adding a number postfix. This method should be used when adding new patterns.

#### Parameters

self | the machine for which the name should be unique |

#### Returns

the newly allocated unique name.

[transfer full]

### bt_machine_get_voice_param_group ()

    BtParameterGroup *
    bt_machine_get_voice_param_group (const BtMachine * const self,
                                      const gulong voice);

Get the parameter group of voice parameters for the given `voice` .

#### Parameters

self | the machine |
voice | the voice number |

#### Returns

the BtParameterGroup or `NULL`.

[transfer none]

### bt_machine_get_wire_by_dst_machine ()

    BtWire *
    bt_machine_get_wire_by_dst_machine (const BtMachine * const self,
                                        const BtMachine * const dst);

Searches for a wire in the wires originating from this machine that uses the given BtMachine instances as a target.

#### Parameters

self | the machine that is at src of a wire |
dst | the machine that is at the dst end of the wire |

#### Returns

the BtWire or `NULL`. Unref the wire, when done with it.

[transfer full]

Since: 0.6

### bt_machine_handles_waves ()

    gboolean
    bt_machine_handles_waves (const BtMachine * const self);

Tells if the machine is using the wave-table.

#### Parameters

self | the machine to check |

#### Returns

`TRUE` for wavetable machines, `FALSE` otherwise

Since: 0.7

### bt_machine_has_active_adder ()

    gboolean
    bt_machine_has_active_adder (const BtMachine * const self);

Checks if the machine currently uses an adder. This method is used by the BtWire class to activate the adder when needed.

#### Parameters

self | the machine to check |

#### Returns

`TRUE` for success

### bt_machine_has_active_spreader ()

    gboolean
    bt_machine_has_active_spreader (const BtMachine * const self);

Checks if the machine currently uses an spreader. This method is used by the BtWire class to activate the spreader when needed.

#### Parameters

self | the machine to check |

#### Returns

`TRUE` for success

### bt_machine_has_patterns ()

    gboolean
    bt_machine_has_patterns (const BtMachine * const self);

Check if the machine has BtPattern entries appart from the standart private ones.

#### Parameters

self | the machine for which to check the patterns |

#### Returns

`TRUE` if it has patterns

### bt_machine_is_polyphonic ()

    gboolean
    bt_machine_is_polyphonic (const BtMachine * const self);

Tells if the machine can produce (multiple) voices. Monophonic machines have their (one) voice params as part of the global params.

#### Parameters

self | the machine to check |

#### Returns

`TRUE` for polyphic machines, `FALSE` for monophonic ones

### bt_machine_randomize_parameters ()

    void
    bt_machine_randomize_parameters (const BtMachine * const self);

Randomizes machine parameters.

#### Parameters

self | machine |

### bt_machine_remove_pattern ()

    void
    bt_machine_remove_pattern (const BtMachine *self,
                               const BtCmdPattern *pattern);

Remove the given pattern from the machine.

#### Parameters

self | the machine to remove the pattern from |
pattern | the existing pattern instance |

### bt_machine_reset_parameters ()

    void
    bt_machine_reset_parameters (const BtMachine * const self);

Resets machine parameters back to defaults.

#### Parameters

self | machine |

### bt_machine_set_param_defaults ()

    void
    bt_machine_set_param_defaults (const BtMachine *const self);

Sets default values that should be used before the first control-point. Should be called, if all parameters are changed (like after switching presets).

#### Parameters

self | the machine |

### bt_machine_unbind_parameter_control ()

    void
    bt_machine_unbind_parameter_control (const BtMachine * const self,
                                         GstObject *object,
                                         const gchar *property_name);

Disconnect the interaction control object from the give parameter.

#### Parameters

self | machine |
object | child object (global or voice child) |
property_name | name of the parameter |

### bt_machine_unbind_parameter_controls ()

    void
    bt_machine_unbind_parameter_controls (const BtMachine * const self);

Disconnect all interaction controls.

#### Parameters

self | machine |

## Types and Values

### struct BtMachine

    struct BtMachine {
      /*< read-only >*/
      GList *src_wires;
      GList *dst_wires;
    };

Base object for a virtual piece of hardware (generator, effect, ...).

#### Members

GList *`src_wires`; | read-only list of outgoing BtWire objects |
GList *`dst_wires`; | read-only list of incomming BtWire objects |

### struct BtMachineClass

    struct BtMachineClass {
      /* virtual methods for subclasses */
      gboolean (*check_type)(const BtMachine * const machine, const gulong pad_src_ct, const gulong pad_sink_ct);
    };

Base class for machines.

#### Members

`check_type` () | sanity check that the given input/output characteristics are okay for the implementation |

### enum BtMachineState

A machine is always in one of the 4 states. Use the "state" property of the BtMachine to change or query the current state.

#### Members

BT_MACHINE_STATE_NORMAL | just working |
BT_MACHINE_STATE_MUTE | be quiet |
BT_MACHINE_STATE_SOLO | be the only one playing |
BT_MACHINE_STATE_BYPASS | be uneffective (pass through) |

## Property Details

### The `“adder-convert”` property

      “adder-convert”            GstElement *

the after mixing format converter element, if any.

Flags: Read

### The `“construction-error”` property

      “construction-error”       gpointer

signal failed instance creation.

Flags: Read / Write / Construct Only

### The `“global-params”` property

      “global-params”            gulong

number of dynamic params for the machine.

Flags: Read

### The `“id”` property

      “id”                       gchar *

machine identifier.

Flags: Read / Write / Construct

Default value: "unamed machine"

### The `“input-gain”` property

      “input-gain”               GstElement *

the input-gain element, if any.

Flags: Read

### The `“input-post-level”` property

      “input-post-level”         GstElement *

the post-gain input-level element, if any.

Flags: Read

### The `“input-pre-level”` property

      “input-pre-level”          GstElement *

the pre-gain input-level element, if any.

Flags: Read

### The `“machine”` property

      “machine”                  GstElement *

the machine element, if any.

Flags: Read

### The `“output-gain”` property

      “output-gain”              GstElement *

the output-gain element, if any.

Flags: Read

### The `“output-post-level”` property

      “output-post-level”        GstElement *

the post-gain output-level element, if any.

Flags: Read

### The `“output-pre-level”` property

      “output-pre-level”         GstElement *

the pre-gain output-level element, if any.

Flags: Read

### The `“patterns”` property

      “patterns”                 gpointer

a copy of the list of patterns.

Flags: Read

### The `“plugin-name”` property

      “plugin-name”              gchar *

the name of the gst plugin for the machine.

Flags: Read / Write / Construct

Default value: "unamed plugin"

### The `“prefs-params”` property

      “prefs-params”             gulong

number of static params for the machine.

Flags: Read

### The `“pretty-name”` property

      “pretty-name”              gchar *

pretty-printed name for display purposes.

Flags: Read

Default value: NULL

### The `“properties”` property

      “properties”               gpointer

hashtable of machine properties.

Flags: Read

### The `“song”` property

      “song”                     BtSong *

song object, the machine belongs to.

Flags: Read / Write / Construct Only

### The `“state”` property

      “state”                    BtMachineState

the current state of this machine.

Flags: Read / Write

Default value: BT_MACHINE_STATE_NORMAL

### The `“voice-params”` property

      “voice-params”             gulong

number of dynamic params for each machine voice.

Flags: Read

### The `“voices”` property

      “voices”                   gulong

number of voices in the machine.

Flags: Read / Write / Construct

## Signal Details

### The `“pattern-added”` signal

    void
    user_function (BtMachine *self,
                   BtPattern *pattern,
                   gpointer   user_data)

A new pattern item has been added to the machine

#### Parameters

self | the machine object that emitted the signal |
pattern | the new pattern |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

### The `“pattern-removed”` signal

    void
    user_function (BtMachine *self,
                   BtPattern *pattern,
                   gpointer   user_data)

A pattern item has been removed from the machine

#### Parameters

self | the machine object that emitted the signal |
pattern | the old pattern |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks