BtPattern

BtPattern — class for an event pattern of a BtMachine instance

Functions

Properties

BtPattern * copy-source Write / Construct Only
gulong length Read / Write / Construct
gulong voices Read

Signals

void group-changed No Hooks
void param-changed No Hooks
void pattern-changed No Hooks

Types and Values

struct BtPattern

Object Hierarchy

    GObject
    ╰── BtCmdPattern
        ╰── BtPattern

Implemented Interfaces

BtPattern implements BtPersistence.

Includes

#include <libbtcore/core.h>

Description

A pattern contains a grid of events. Events are parameter changes in BtMachine objects. The events are stored as GValues. Cells containing NULL have no event for the parameter at the time.

Patterns can have individual lengths. The length is measured in ticks. How much that is in e.g. milliseconds is determined by “bpm” and “tpb”.

A pattern might consist of several groups. These are mapped to the global parameters of a machine and the voice parameters for each machine voice (if any). The number of voices (tracks) is the same in all patterns of a machine. If the voices are changed on the machine patterns resize themselves.

The patterns are used in the BtSequence to form the score of a song.

Functions

bt_pattern_blend_columns ()

void
bt_pattern_blend_columns (const BtPattern * const self,
                          const gulong start_tick,
                          const gulong end_tick);

Fade values from start_tick to end_tick for all params.

Parameters

self

the pattern

 

start_tick

the start position for the range

 

end_tick

the end position for the range

 

Since: 0.3


bt_pattern_clear_columns ()

void
bt_pattern_clear_columns (const BtPattern * const self,
                          const gulong start_tick,
                          const gulong end_tick);

Clear values from start_tick to end_tick for all params.

Parameters

self

the pattern

 

start_tick

the start position for the range

 

end_tick

the end position for the range

 

Since: 0.6


bt_pattern_copy ()

BtPattern *
bt_pattern_copy (const BtPattern * const self);

Create a new instance as a copy of the given instance.

Parameters

self

the pattern to create a copy from

 

Returns

the new instance or NULL in case of an error.

[transfer full]


bt_pattern_delete_row ()

void
bt_pattern_delete_row (const BtPattern * const self,
                       const gulong tick);

Delete row for all parameters.

Parameters

self

the pattern

 

tick

the position to delete

 

Since: 0.3


bt_pattern_flip_columns ()

void
bt_pattern_flip_columns (const BtPattern * const self,
                         const gulong start_tick,
                         const gulong end_tick);

Flips values from start_tick to end_tick for all params up-side down.

Parameters

self

the pattern

 

start_tick

the start position for the range

 

end_tick

the end position for the range

 

Since: 0.5


bt_pattern_get_global_event ()

gchar *
bt_pattern_get_global_event (const BtPattern * const self,
                             const gulong tick,
                             const gulong param);

Returns the string representation of the specified cell. Free it when done.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

param

the number of the global parameter starting with 0

 

Returns

a newly allocated string with the data or NULL on error


bt_pattern_get_global_event_data ()

GValue *
bt_pattern_get_global_event_data (const BtPattern * const self,
                                  const gulong tick,
                                  const gulong param);

Fetches a cell from the given location in the pattern. If there is no event there, then the GValue is uninitialized. Test with BT_IS_GVALUE(event).

Do not modify the contents!

Parameters

self

the pattern to search for the global param

 

tick

the tick (time) position starting with 0

 

param

the number of the global parameter starting with 0

 

Returns

the GValue or NULL if out of the pattern range


bt_pattern_get_global_group ()

BtValueGroup *
bt_pattern_get_global_group (const BtPattern * const self);

Get the BtValueGroup for global parameters.

Parameters

self

the pattern

 

Returns

the group owned by the pattern.

[transfer none]


bt_pattern_get_group_by_parameter_group ()

BtValueGroup *
bt_pattern_get_group_by_parameter_group
                               (const BtPattern * const self,
                                BtParameterGroup *param_group);

Get the BtValueGroup for the given param_group .

Parameters

self

the pattern

 

param_group

the BtParameterGroup to get the group for

 

Returns

the group owned by the pattern.

[transfer none]


bt_pattern_get_voice_event ()

gchar *
bt_pattern_get_voice_event (const BtPattern * const self,
                            const gulong tick,
                            const gulong voice,
                            const gulong param);

Returns the string representation of the specified cell. Free it when done.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

voice

the voice number starting with 0

 

param

the number of the voice parameter starting with 0

 

Returns

a newly allocated string with the data or NULL on error


bt_pattern_get_voice_event_data ()

GValue *
bt_pattern_get_voice_event_data (const BtPattern * const self,
                                 const gulong tick,
                                 const gulong voice,
                                 const gulong param);

Fetches a cell from the given location in the pattern. If there is no event there, then the GValue is uninitialized. Test with BT_IS_GVALUE(event).

Do not modify the contents!

Parameters

self

the pattern to search for the voice param

 

tick

the tick (time) position starting with 0

 

voice

the voice number starting with 0

 

param

the number of the voice parameter starting with 0

 

Returns

the GValue or NULL if out of the pattern range


bt_pattern_get_voice_group ()

BtValueGroup *
bt_pattern_get_voice_group (const BtPattern * const self,
                            const gulong voice);

Get the BtValueGroup for voice parameters.

Parameters

self

the pattern

 

voice

the voice to get the group for

 

Returns

the group owned by the pattern.

[transfer none]


bt_pattern_get_wire_event ()

gchar *
bt_pattern_get_wire_event (const BtPattern * const self,
                           const gulong tick,
                           const BtWire *wire,
                           const gulong param);

Returns the string representation of the specified cell. Free it when done.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

wire

the related wire object

 

param

the number of the wire parameter starting with 0

 

Returns

a newly allocated string with the data or NULL on error


bt_pattern_get_wire_event_data ()

GValue *
bt_pattern_get_wire_event_data (const BtPattern * const self,
                                const gulong tick,
                                const BtWire *wire,
                                const gulong param);

Fetches a cell from the given location in the pattern. If there is no event there, then the GValue is uninitialized. Test with BT_IS_GVALUE(event).

Do not modify the contents!

Parameters

self

the pattern to search for the wire param

 

tick

the tick (time) position starting with 0

 

wire

the related wire object

 

param

the number of the wire parameter starting with 0

 

Returns

the GValue or NULL if out of the pattern range


bt_pattern_get_wire_group ()

BtValueGroup *
bt_pattern_get_wire_group (const BtPattern * const self,
                           const BtWire *wire);

Get the BtValueGroup for wire parameters.

Parameters

self

the pattern

 

wire

the BtWire to get the group for

 

Returns

the group owned by the pattern.

[transfer none]


bt_pattern_insert_row ()

void
bt_pattern_insert_row (const BtPattern * const self,
                       const gulong tick);

Insert one empty row for all parameters.

Parameters

self

the pattern

 

tick

the position to insert at

 

Since: 0.3


bt_pattern_new ()

BtPattern *
bt_pattern_new (const BtSong * const song,
                const gchar * const name,
                const gulong length,
                const BtMachine * const machine);

Create a new instance. It will be automatically added to the machines pattern list.

Parameters

song

the song the new instance belongs to

 

name

the display name of the pattern

 

length

the number of ticks

 

machine

the machine the pattern belongs to

 

Returns

the new instance or NULL in case of an error


bt_pattern_randomize_columns ()

void
bt_pattern_randomize_columns (const BtPattern * const self,
                              const gulong start_tick,
                              const gulong end_tick);

Randomize values from start_tick to end_tick for all params.

Parameters

self

the pattern

 

start_tick

the start position for the range

 

end_tick

the end position for the range

 

Since: 0.3


bt_pattern_range_randomize_columns ()

void
bt_pattern_range_randomize_columns (const BtPattern * const self,
                                    const gulong start_tick,
                                    const gulong end_tick);

Randomize values from start_tick to end_tick for all params using the first and last value as bounds for the random values.

Parameters

self

the pattern

 

start_tick

the start position for the range

 

end_tick

the end position for the range

 

Since: 0.7


bt_pattern_serialize_columns ()

void
bt_pattern_serialize_columns (const BtPattern * const self,
                              const gulong start_tick,
                              const gulong end_tick,
                              GString *data);

Serializes values from start_tick to end_tick for all params into data .

Parameters

self

the pattern

 

start_tick

the start position for the range

 

end_tick

the end position for the range

 

data

the target

 

Since: 0.6


bt_pattern_set_global_event ()

gboolean
bt_pattern_set_global_event (const BtPattern * const self,
                             const gulong tick,
                             const gulong param,
                             const gchar * const value);

Stores the supplied value into the specified pattern cell.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

param

the number of the global parameter starting with 0

 

value

the string representation of the value to store

 

Returns

TRUE for success


bt_pattern_set_voice_event ()

gboolean
bt_pattern_set_voice_event (const BtPattern * const self,
                            const gulong tick,
                            const gulong voice,
                            const gulong param,
                            const gchar * const value);

Stores the supplied value into the specified pattern cell.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

voice

the voice number starting with 0

 

param

the number of the voice parameter starting with 0

 

value

the string representation of the value to store

 

Returns

TRUE for success


bt_pattern_set_wire_event ()

gboolean
bt_pattern_set_wire_event (const BtPattern * const self,
                           const gulong tick,
                           const BtWire *wire,
                           const gulong param,
                           const gchar * const value);

Stores the supplied value into the specified pattern cell.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

wire

the related wire object

 

param

the number of the wire parameter starting with 0

 

value

the string representation of the value to store

 

Returns

TRUE for success


bt_pattern_test_global_event ()

gboolean
bt_pattern_test_global_event (const BtPattern * const self,
                              const gulong tick,
                              const gulong param);

Tests if there is an event in the specified cell.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

param

the number of the global parameter starting with 0

 

Returns

TRUE if there is an event


bt_pattern_test_tick ()

gboolean
bt_pattern_test_tick (const BtPattern * const self,
                      const gulong tick);

Check if there are any event in the given pattern-row.

Parameters

self

the pattern to check

 

tick

the tick index in the pattern

 

Returns

TRUE is there are events, FALSE otherwise


bt_pattern_test_voice_event ()

gboolean
bt_pattern_test_voice_event (const BtPattern * const self,
                             const gulong tick,
                             const gulong voice,
                             const gulong param);

Tests if there is an event in the specified cell.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

voice

the voice number starting with 0

 

param

the number of the voice parameter starting with 0

 

Returns

TRUE if there is an event


bt_pattern_test_wire_event ()

gboolean
bt_pattern_test_wire_event (const BtPattern * const self,
                            const gulong tick,
                            const BtWire *wire,
                            const gulong param);

Tests if there is an event in the specified cell.

Parameters

self

the pattern the cell belongs to

 

tick

the tick (time) position starting with 0

 

wire

the related wire object

 

param

the number of the wire parameter starting with 0

 

Returns

TRUE if there is an event

Types and Values

struct BtPattern

struct BtPattern;

Holds a sequence of events for a BtMachine.

Property Details

The “copy-source” property

  “copy-source”              BtPattern *

pattern to copy data from.

Flags: Write / Construct Only


The “length” property

  “length”                   gulong

length of the pattern in ticks.

Flags: Read / Write / Construct


The “voices” property

  “voices”                   gulong

number of voices in the pattern.

Flags: Read

Signal Details

The “group-changed” signal

void
user_function (BtPattern        *self,
               BtParameterGroup *param_group,
               gboolean          intermediate,
               gpointer          user_data)

Signals that a group of this pattern has been changed (more than in one place). When doing e.g. line inserts, one will receive two updates, one before and one after. The first will have intermediate =TRUE. Applications can use that to defer change-consolidation.

Parameters

self

the pattern object that emitted the signal

 

param_group

the parameter group

 

intermediate

flag that is TRUE to signal that more change are coming

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “param-changed” signal

void
user_function (BtPattern        *self,
               BtParameterGroup *param_group,
               gulong            tick,
               gulong            param,
               gpointer          user_data)

Signals that a param of this pattern has been changed.

Parameters

self

the pattern object that emitted the signal

 

param_group

the parameter group

 

tick

the tick position inside the pattern

 

param

the parameter index

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “pattern-changed” signal

void
user_function (BtPattern *self,
               gboolean   intermediate,
               gpointer   user_data)

Signals that this pattern has been changed (more than in one place). When doing e.g. line inserts, one will receive two updates, one before and one after. The first will have intermediate =TRUE. Applications can use that to defer change-consolidation.

Parameters

self

the pattern object that emitted the signal

 

intermediate

flag that is TRUE to signal that more change are coming

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks