## BtWire

BtWire — class for a connection of two BtMachines

## Synopsis

    #include <libbtcore/core.h>

    #define             BT_WIRE_MAX_NUM_PARAMS
    struct              BtWire;
    void                bt_wire_add_wire_pattern            (const BtWire * const self,
                                                             const BtPattern * const pattern,
                                                             const BtWirePattern * const wire_pattern);
    void                bt_wire_controller_change_value     (const BtWire * const self,
                                                             const gulong param,
                                                             const GstClockTime timestamp,
                                                             GValue * const value);
    void                bt_wire_get_param_details           (const BtWire * const self,
                                                             const gulong index,
                                                             GParamSpec **pspec,
                                                             GValue **min_val,
                                                             GValue **max_val);
    glong               bt_wire_get_param_index             (const BtWire *const self,
                                                             const gchar * const name,
                                                             GError **error);
    const gchar *       bt_wire_get_param_name              (const BtWire * const self,
                                                             const gulong index);
    GParamSpec *        bt_wire_get_param_spec              (const BtWire * const self,
                                                             const gulong index);
    GType               bt_wire_get_param_type              (const BtWire * const self,
                                                             const gulong index);
    BtWirePattern *     bt_wire_get_pattern                 (const BtWire * const self,
                                                             const BtPattern * const pattern);
    BtWire *            bt_wire_new                         (const BtSong *song,
                                                             const BtMachine *src_machine,
                                                             const BtMachine *dst_machine,
                                                             GError **err);
    gboolean            bt_wire_reconnect                   (BtWire *self);

## Object Hierarchy

      GObject
       +----GstObject
             +----GstElement
                   +----GstBin
                         +----BtWire

## Implemented Interfaces

BtWire implements GstChildProxy.

## Properties

      "analyzers"                gpointer              : Read / Write
      "construction-error"       gpointer              : Read / Write / Construct Only
      "dst"                      BtMachine*            : Read / Write / Construct Only
      "gain"                     GstElement*           : Read
      "num-params"               gulong                : Read / Write
      "pan"                      GstElement*           : Read
      "properties"               gpointer              : Read
      "song"                     BtSong*               : Read / Write / Construct Only
      "src"                      BtMachine*            : Read / Write / Construct Only

## Signals

      "pattern-created"                                : No Hooks

## Description

Abstracts connection between two BtMachines. After creation, the elements are connected. In contrast to directly wiring GstElements this insert needed conversion elements automatically.

Furthermore each wire has a volume and if possible panorama/balance element. Volume and panorama/balance can be sequenced like machine parameters in BtWirePattern objects.

## Details

### BT_WIRE_MAX_NUM_PARAMS

    #define BT_WIRE_MAX_NUM_PARAMS 2

Maximum number of parameters per wire.

### struct BtWire

    struct BtWire;

A link between two BtMachine instances.

### bt_wire_add_wire_pattern ()

    void                bt_wire_add_wire_pattern            (const BtWire * const self,
                                                             const BtPattern * const pattern,
                                                             const BtWirePattern * const wire_pattern);

Add the supplied wire-pattern to the wire. This is automatically done by #`bt_wire_pattern_new()`.

`self` : | the wire to add the wire-pattern to
`pattern` : | the pattern that the wire-pattern is associated with
`wire_pattern` : | the new wire-pattern instance

### bt_wire_controller_change_value ()

    void                bt_wire_controller_change_value     (const BtWire * const self,
                                                             const gulong param,
                                                             const GstClockTime timestamp,
                                                             GValue * const value);

Depending on wheter the given value is NULL, sets or unsets the controller value for the specified param and at the given time.

`self` : | the wire to change the param for
`param` : | the parameter index
`timestamp` : | the time stamp of the change
`value` : | the new value or `NULL` to unset a previous one

### bt_wire_get_param_details ()

    void                bt_wire_get_param_details           (const BtWire * const self,
                                                             const gulong index,
                                                             GParamSpec **pspec,
                                                             GValue **min_val,
                                                             GValue **max_val);

Retrieves the details of a voice param. Any detail can be `NULL` if its not wanted.

`self` : | the wire to search for the param details
`index` : | the offset in the list of params
`pspec` : | place for the param spec
`min_val` : | place to hold new GValue with minimum
`max_val` : | place to hold new GValue with maximum

### bt_wire_get_param_index ()

    glong               bt_wire_get_param_index             (const BtWire *const self,
                                                             const gchar * const name,
                                                             GError **error);

Searches the list of registered param of a wire for a param of the given name and returns the index if found.

`self` : | the wire to search for the param
`name` : | the name of the param
`error` : | the location of an error instance to fill with a message, if an error occures
Returns : | the index or sets error if it is not found and returns -1.

### bt_wire_get_param_name ()

    const gchar *       bt_wire_get_param_name              (const BtWire * const self,
                                                             const gulong index);

Gets the param name. Do not modify returned content.

`self` : | the wire to get the param name from
`index` : | the offset in the list of params
Returns : | the requested name

### bt_wire_get_param_spec ()

    GParamSpec *        bt_wire_get_param_spec              (const BtWire * const self,
                                                             const gulong index);

Retrieves the parameter specification for the param

`self` : | the wire to search for the param
`index` : | the offset in the list of params
Returns : | the GParamSpec for the requested param

### bt_wire_get_param_type ()

    GType               bt_wire_get_param_type              (const BtWire * const self,
                                                             const gulong index);

Retrieves the GType of a param

`self` : | the wire to search for the param type
`index` : | the offset in the list of params
Returns : | the requested GType

### bt_wire_get_pattern ()

    BtWirePattern *     bt_wire_get_pattern                 (const BtWire * const self,
                                                             const BtPattern * const pattern);

Gets the wire-pattern that hold the automation data for this `wire`.

`self` : | the wire that has the pattern
`pattern` : | the pattern that the wire-pattern is associated with
Returns : | a reference to the wire-pattern, unref when done.

### bt_wire_new ()

    BtWire *            bt_wire_new                         (const BtSong *song,
                                                             const BtMachine *src_machine,
                                                             const BtMachine *dst_machine,
                                                             GError **err);

Create a new instance. The new wire is automaticall added to a songs setup. You don't need to call `bt_setup_add_wire(setup,wire);`.

`song` : | the song the new instance belongs to
`src_machine` : | the data source (BtSourceMachine or BtProcessorMachine)
`dst_machine` : | the data sink (BtSinkMachine or BtProcessorMachine)
`err` : | inform about failed instance creation
Returns : | the new instance or `NULL` in case of an error

### bt_wire_reconnect ()

    gboolean            bt_wire_reconnect                   (BtWire *self);

Call this method after internal elements in a BtMachine have changed, but failed to link.

`self` : | the wire to re-link
Returns : | `TRUE` for success and `FALSE` otherwise

## Property Details

### The `"analyzers"` property

      "analyzers"                gpointer              : Read / Write

list of wire analyzers.

### The `"construction-error"` property

      "construction-error"       gpointer              : Read / Write / Construct Only

signal failed instance creation.

### The `"dst"` property

      "dst"                      BtMachine*            : Read / Write / Construct Only

dst machine object, the wire links to.

### The `"gain"` property

      "gain"                     GstElement*           : Read

the gain element for the connection.

### The `"num-params"` property

      "num-params"               gulong                : Read / Write

number of params for the wire.

Allowed values: <= 2

### The `"pan"` property

      "pan"                      GstElement*           : Read

the panorama element for the connection.

### The `"properties"` property

      "properties"               gpointer              : Read

list of wire properties.

### The `"song"` property

      "song"                     BtSong*               : Read / Write / Construct Only

the song object, the wire belongs to.

### The `"src"` property

      "src"                      BtMachine*            : Read / Write / Construct Only

src machine object, the wire links to.

## Signal Details

### The `"pattern-created"` signal

    void                user_function                      (BtWire        *self,
                                                            BtWirePattern *tick,
                                                            gpointer       user_data)      : No Hooks

signals that a param of this wire-pattern has been changed

`self` : | the wire-pattern object that emitted the signal
`tick` : | the tick position inside the pattern
`param` : | the parameter index
`user_data` : | user data set when the signal handler was connected.