BtSequence

BtSequence — class for the event timeline of a BtSong instance

Synopsis

#include <libbtcore/core.h>

struct              BtSequence;
gboolean            bt_sequence_add_track               (const BtSequence * const self,
                                                         const BtMachine * const machine,
                                                         const glong ix);
void                bt_sequence_delete_full_rows        (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong rows);
void                bt_sequence_delete_rows             (const BtSequence * const self,
                                                         const gulong time,
                                                         const glong track,
                                                         const gulong rows);
GstClockTime        bt_sequence_get_bar_time            (const BtSequence * const self);
gchar *             bt_sequence_get_label               (const BtSequence * const self,
                                                         const gulong time);
GstClockTime        bt_sequence_get_loop_time           (const BtSequence * const self);
BtMachine *         bt_sequence_get_machine             (const BtSequence * const self,
                                                         const gulong track);
BtPattern *         bt_sequence_get_pattern             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track);
glong               bt_sequence_get_tick_by_pattern     (const BtSequence * const self,
                                                         gulong track,
                                                         const BtPattern * const pattern,
                                                         gulong tick);
glong               bt_sequence_get_track_by_machine    (const BtSequence * const self,
                                                         const BtMachine * const machine,
                                                         gulong track);
void                bt_sequence_insert_full_rows        (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong rows);
void                bt_sequence_insert_rows             (const BtSequence * const self,
                                                         const gulong time,
                                                         const glong track,
                                                         const gulong rows);
gboolean            bt_sequence_is_pattern_used         (const BtSequence * const self,
                                                         const BtPattern * const pattern);
gulong              bt_sequence_limit_play_pos          (const BtSequence * const self,
                                                         const gulong play_pos);
gboolean            bt_sequence_move_track_left         (const BtSequence * const self,
                                                         const gulong track);
gboolean            bt_sequence_move_track_right        (const BtSequence * const self,
                                                         const gulong track);
BtSequence *        bt_sequence_new                     (const BtSong * const song);
gboolean            bt_sequence_remove_track_by_ix      (const BtSequence * const self,
                                                         const gulong ix);
gboolean            bt_sequence_remove_track_by_machine (const BtSequence * const self,
                                                         const BtMachine * const machine);
void                bt_sequence_repair_damage           (const BtSequence * const self);
void                bt_sequence_set_label               (const BtSequence * const self,
                                                         const gulong time,
                                                         const gchar * const label);
void                bt_sequence_set_pattern             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track,
                                                         const BtPattern * const pattern);
gboolean            bt_sequence_set_pattern_quick       (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track,
                                                         const BtPattern * const pattern);
void                bt_sequence_update_tempo            (const BtSequence * const self);

Object Hierarchy

  GObject
   +----BtSequence

Implemented Interfaces

BtSequence implements

Properties

  "length"                   gulong                : Read / Write
  "loop"                     gboolean              : Read / Write
  "loop-end"                 glong                 : Read / Write
  "loop-start"               glong                 : Read / Write
  "properties"               gpointer              : Read
  "song"                     BtSong*               : Read / Write / Construct Only
  "tracks"                   gulong                : Read / Write

Signals

  "pattern-added"                                  : No Hooks
  "pattern-removed"                                : No Hooks
  "rows-changed"                                   : No Hooks
  "track-added"                                    : No Hooks
  "track-removed"                                  : No Hooks

Description

A sequence holds grid of BtPatterns, with labels on the time axis and BtMachine instances on the track axis. It tracks first and last use of patterns and provides two signals for notification - "pattern-added" and "pattern-removed".

It supports looping a section of the sequence (see "loop", "loop-start", "loop-end").

The BtSequence manages the GstController event queues for the BtMachines and BtWires. It uses a damage-repair based two phase algorithm to update the controller queues whenever patterns or the sequence changes.

Details

struct BtSequence

struct BtSequence;

Starting point for the BtSong timeline data-structures. Holds a series of array of BtPatterns for time and tracks, which define the events that are sent to a BtMachine at a time.


bt_sequence_add_track ()

gboolean            bt_sequence_add_track               (const BtSequence * const self,
                                                         const BtMachine * const machine,
                                                         const glong ix);

Adds a new track with the machine at ix or the end.

self :

the BtSequence that holds the tracks

machine :

the BtMachine

ix :

position to add the track at, use -1 to append

Returns :

TRUE for success

bt_sequence_delete_full_rows ()

void                bt_sequence_delete_full_rows        (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong rows);

Delete row for all tracks.

self :

the sequence

time :

the postion to delete

rows :

the number of rows to remove

Since 0.3


bt_sequence_delete_rows ()

void                bt_sequence_delete_rows             (const BtSequence * const self,
                                                         const gulong time,
                                                         const glong track,
                                                         const gulong rows);

Delete row for given track.

self :

the sequence

time :

the postion to delete

track :

the track

rows :

the number of rows to remove

Since 0.3


bt_sequence_get_bar_time ()

GstClockTime        bt_sequence_get_bar_time            (const BtSequence * const self);

Calculates the length of one sequence bar in microseconds. Divide it by G_USEC_PER_SEC to get it in milliseconds.

self :

the BtSequence of the song

Returns :

the length of one sequence bar in microseconds

bt_sequence_get_label ()

gchar *             bt_sequence_get_label               (const BtSequence * const self,
                                                         const gulong time);

Fetches the label for the given time position. Free when done.

self :

the BtSequence that holds the labels

time :

the requested time position

Returns :

a copy of the label or NULL in case of an error

bt_sequence_get_loop_time ()

GstClockTime        bt_sequence_get_loop_time           (const BtSequence * const self);

Calculates the length of the song loop in microseconds. Divide it by G_USEC_PER_SEC to get it in milliseconds.

self :

the BtSequence of the song

Returns :

the length of the song loop in microseconds

bt_sequence_get_machine ()

BtMachine *         bt_sequence_get_machine             (const BtSequence * const self,
                                                         const gulong track);

Fetches the BtMachine for the given track. Unref when done.

self :

the BtSequence that holds the tracks

track :

the requested track index

Returns :

a reference to the BtMachine pointer or NULL in case of an error

bt_sequence_get_pattern ()

BtPattern *         bt_sequence_get_pattern             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track);

Fetches the pattern for the given time and track position. Unref when done.

self :

the BtSequence that holds the patterns

time :

the requested time position

track :

the requested track index

Returns :

a reference to the BtPattern or NULL when empty

bt_sequence_get_tick_by_pattern ()

glong               bt_sequence_get_tick_by_pattern     (const BtSequence * const self,
                                                         gulong track,
                                                         const BtPattern * const pattern,
                                                         gulong tick);

Gets the next tick position >= tick this pattern is on.

self :

the sequence to search in

track :

the track to search in

pattern :

the pattern to find the next track for

tick :

the tick position to start the search from

Returns :

the tick position or -1 if there is no further tick for this pattern.

Since 0.6


bt_sequence_get_track_by_machine ()

glong               bt_sequence_get_track_by_machine    (const BtSequence * const self,
                                                         const BtMachine * const machine,
                                                         gulong track);

Gets the next track >= track this machine is on.

self :

the sequence to search in

machine :

the machine to find the next track for

track :

the track to start the search from

Returns :

the track-index or -1 if there is no further track for this machine.

Since 0.6


bt_sequence_insert_full_rows ()

void                bt_sequence_insert_full_rows        (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong rows);

Insert one empty row for all tracks.

self :

the sequence

time :

the postion to insert at

rows :

the number of rows to insert

Since 0.3


bt_sequence_insert_rows ()

void                bt_sequence_insert_rows             (const BtSequence * const self,
                                                         const gulong time,
                                                         const glong track,
                                                         const gulong rows);

Insert one empty row for given track.

self :

the sequence

time :

the postion to insert at

track :

the track

rows :

the number of rows to insert

Since 0.3


bt_sequence_is_pattern_used ()

gboolean            bt_sequence_is_pattern_used         (const BtSequence * const self,
                                                         const BtPattern * const pattern);

Checks if the pattern is used in the sequence.

self :

the sequence to check for pattern use

pattern :

the pattern to check for

Returns :

TRUE if pattern is used.

bt_sequence_limit_play_pos ()

gulong              bt_sequence_limit_play_pos          (const BtSequence * const self,
                                                         const gulong play_pos);

Enforce the playback position to be within loop start and end or the song bounds if there is no loop.

self :

the sequence to trim the play position of

play_pos :

the time position to lock inbetween loop-boundaries

Returns :

the new play_pos

bt_sequence_move_track_left ()

gboolean            bt_sequence_move_track_left         (const BtSequence * const self,
                                                         const gulong track);

Move the selected track on column left.

self :

the BtSequence that holds the tracks

track :

the track to move

Returns :

TRUE for success

bt_sequence_move_track_right ()

gboolean            bt_sequence_move_track_right        (const BtSequence * const self,
                                                         const gulong track);

Move the selected track on column left.

self :

the BtSequence that holds the tracks

track :

the track to move

Returns :

TRUE for success

bt_sequence_new ()

BtSequence *        bt_sequence_new                     (const BtSong * const song);

Create a new instance. One would not call this directly, but rather get this from a BtSong instance.

song :

the song the new instance belongs to

Returns :

the new instance or NULL in case of an error

bt_sequence_remove_track_by_ix ()

gboolean            bt_sequence_remove_track_by_ix      (const BtSequence * const self,
                                                         const gulong ix);

Removes the specified track.

self :

the BtSequence that holds the tracks

ix :

the requested track index

Returns :

TRUE for success

bt_sequence_remove_track_by_machine ()

gboolean            bt_sequence_remove_track_by_machine (const BtSequence * const self,
                                                         const BtMachine * const machine);

Removes all tracks that belong the the given machine.

self :

the BtSequence that holds the tracks

machine :

the BtMachine

Returns :

TRUE for success

bt_sequence_repair_damage ()

void                bt_sequence_repair_damage           (const BtSequence * const self);

Works through the repair queue and rebuilds controller queues, where needed.

There is usualy no need to call that manualy. Only call after soing mass updates using bt_sequence_set_pattern_quick() functions.

self :

the BtSequence

Since 0.5


bt_sequence_set_label ()

void                bt_sequence_set_label               (const BtSequence * const self,
                                                         const gulong time,
                                                         const gchar * const label);

Sets a new label for the respective time position.

self :

the BtSequence that holds the labels

time :

the requested time position

label :

the new label

bt_sequence_set_pattern ()

void                bt_sequence_set_pattern             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track,
                                                         const BtPattern * const pattern);

Sets the BtPattern for the respective time and track position.

self :

the BtSequence that holds the patterns

time :

the requested time position

track :

the requested track index

pattern :

the BtPattern or NULL to unset

bt_sequence_set_pattern_quick ()

gboolean            bt_sequence_set_pattern_quick       (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track,
                                                         const BtPattern * const pattern);

A quick version of bt_sequence_set_pattern() that does not repair damaged area. Useful when doing mass updates.

self :

the BtSequence that holds the patterns

time :

the requested time position

track :

the requested track index

pattern :

the BtPattern or NULL to unset

Returns :

TRUE if a change has been made. One should call bt_sequence_repair_damage() in that case.

Since 0.5


bt_sequence_update_tempo ()

void                bt_sequence_update_tempo            (const BtSequence * const self);

Refresh sequence after tempo changes. Called from BtSongInfo.

self :

the sequence

Property Details

The "length" property

  "length"                   gulong                : Read / Write

length of the sequence in timeline bars.

Allowed values: <= G_MAXLONG


The "loop" property

  "loop"                     gboolean              : Read / Write

is loop activated.

Default value: FALSE


The "loop-end" property

  "loop-end"                 glong                 : Read / Write

end of the repeat sequence on the timeline.

Allowed values: >= -1

Default value: -1


The "loop-start" property

  "loop-start"               glong                 : Read / Write

start of the repeat sequence on the timeline.

Allowed values: >= -1

Default value: -1


The "properties" property

  "properties"               gpointer              : Read

hashtable of sequence properties.


The "song" property

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

Set song object, the sequence belongs to.


The "tracks" property

  "tracks"                   gulong                : Read / Write

number of tracks in the sequence.

Signal Details

The "pattern-added" signal

void                user_function                      (BtSequence *self,
                                                        BtPattern  *pattern,
                                                        gpointer    user_data)      : No Hooks

A pattern has been used in the sequence for the first time.

self :

the sequence object that emitted the signal

pattern :

the new pattern

user_data :

user data set when the signal handler was connected.

The "pattern-removed" signal

void                user_function                      (BtSequence *self,
                                                        BtPattern  *pattern,
                                                        gpointer    user_data)      : No Hooks

The last occurance of pattern has been removed from the sequence.

self :

the sequence object that emitted the signal

pattern :

the old pattern

user_data :

user data set when the signal handler was connected.

The "rows-changed" signal

void                user_function                      (BtSequence *self,
                                                        gulong      begin,
                                                        gulong      end,
                                                        gpointer    user_data)      : No Hooks

The content of the given rows in the sequence has changed.

self :

the sequence object that emitted the signal

begin :

start row that changed

end :

last row that changed

user_data :

user data set when the signal handler was connected.

Since 0.6


The "track-added" signal

void                user_function                      (BtSequence *self,
                                                        BtMachine  *machine,
                                                        gulong      track,
                                                        gpointer    user_data)      : No Hooks

A new track for machine has been added with the track index.

self :

the sequence object that emitted the signal

machine :

the machine for the track

track :

the track index

user_data :

user data set when the signal handler was connected.

Since 0.6


The "track-removed" signal

void                user_function                      (BtSequence *self,
                                                        BtMachine  *machine,
                                                        gulong      track,
                                                        gpointer    user_data)      : No Hooks

A track for machine has been removed at the track index.

self :

the sequence object that emitted the signal

machine :

the machine for the track

track :

the track index

user_data :

user data set when the signal handler was connected.

Since 0.6