BtSequence

BtSequence — class for the event timeline of a BtSong instance

Synopsis

#include <libbtcore/core.h>

                    BtSequence;
BtSequence *        bt_sequence_new                     (const BtSong * const song);
void                bt_sequence_repair_damage           (const BtSequence * const self);
BtMachine *         bt_sequence_get_machine             (const BtSequence * const self,
                                                         const gulong track);
gboolean            bt_sequence_add_track               (const BtSequence * const self,
                                                         const BtMachine * const machine);
gboolean            bt_sequence_remove_track_by_ix      (const BtSequence * const self,
                                                         const gulong track);
gboolean            bt_sequence_remove_track_by_machine (const BtSequence * const self,
                                                         const BtMachine * const machine);
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);
gchar *             bt_sequence_get_label               (const BtSequence * const self,
                                                         const gulong time);
void                bt_sequence_set_label               (const BtSequence * const self,
                                                         const gulong time,
                                                         const gchar * const label);
BtPattern *         bt_sequence_get_pattern             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track);
gboolean            bt_sequence_set_pattern_quick       (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track,
                                                         const BtPattern * const pattern);
void                bt_sequence_set_pattern             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track,
                                                         const BtPattern * const pattern);
GstClockTime        bt_sequence_get_bar_time            (const BtSequence * const self);
GstClockTime        bt_sequence_get_loop_time           (const BtSequence * const self);
gulong              bt_sequence_limit_play_pos          (const BtSequence * const self,
                                                         const gulong play_pos);
gboolean            bt_sequence_is_pattern_used         (const BtSequence * const self,
                                                         const BtPattern * const pattern);
void                bt_sequence_insert_rows             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong track,
                                                         const gulong rows);
void                bt_sequence_insert_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 gulong track,
                                                         const gulong rows);
void                bt_sequence_delete_full_rows        (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong rows);
void                bt_sequence_update_tempo            (const BtSequence * const self);

Object Hierarchy

  GObject
   +----BtSequence

Implemented Interfaces

BtSequence implements BtPersistence.

Properties

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

Description

A sequence holds grid of BtPatterns, with labels on the time axis and BtMachine instances on the track axis. 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

BtSequence

typedef struct _BtSequence 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_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_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_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_add_track ()

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

Adds a new track with the machine to the end.

self :

the BtSequence that holds the tracks

machine :

the BtMachine

Returns :

TRUE for success

bt_sequence_remove_track_by_ix ()

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

Removes the specified track.

self :

the BtSequence that holds the tracks

track :

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_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_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_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_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_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_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_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_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_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_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_insert_rows ()

void                bt_sequence_insert_rows             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong 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_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_delete_rows ()

void                bt_sequence_delete_rows             (const BtSequence * const self,
                                                         const gulong time,
                                                         const gulong 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_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_update_tempo ()

void                bt_sequence_update_tempo            (const BtSequence * const self);

Refresh sequence after tempo changes.

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 "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.