BtPattern

BtPattern — class for an event pattern of a BtMachine instance [Description]

Synopsis


#include <bt-core.h>


            BtPattern;
BtPattern*  bt_pattern_new                  (const BtSong *song,
                                             const gchar *id,
                                             const gchar *name,
                                             gulong length,
                                             const BtMachine *machine);
BtPattern*  bt_pattern_new_with_event       (const BtSong *song,
                                             const BtMachine *machine,
                                             BtPatternCmd cmd);
BtPattern*  bt_pattern_copy                 (const BtPattern *self);
gulong      bt_pattern_get_global_param_index
                                            (const BtPattern *self,
                                             const gchar *name,
                                             GError **error);
gulong      bt_pattern_get_voice_param_index
                                            (const BtPattern *self,
                                             const gchar *name,
                                             GError **error);
GValue*     bt_pattern_get_global_event_data
                                            (const BtPattern *self,
                                             gulong tick,
                                             gulong param);
GValue*     bt_pattern_get_voice_event_data (const BtPattern *self,
                                             gulong tick,
                                             gulong voice,
                                             gulong param);
gboolean    bt_pattern_set_global_event     (const BtPattern *self,
                                             gulong tick,
                                             gulong param,
                                             const gchar *value);
gboolean    bt_pattern_set_voice_event      (const BtPattern *self,
                                             gulong tick,
                                             gulong voice,
                                             gulong param,
                                             const gchar *value);
gchar*      bt_pattern_get_global_event     (const BtPattern *self,
                                             gulong tick,
                                             gulong param);
gchar*      bt_pattern_get_voice_event      (const BtPattern *self,
                                             gulong tick,
                                             gulong voice,
                                             gulong param);
gboolean    bt_pattern_test_global_event    (const BtPattern *self,
                                             gulong tick,
                                             gulong param);
gboolean    bt_pattern_test_voice_event     (const BtPattern *self,
                                             gulong tick,
                                             gulong voice,
                                             gulong param);
BtPatternCmd bt_pattern_get_cmd             (const BtPattern *self,
                                             gulong tick);
gboolean    bt_pattern_tick_has_data        (const BtPattern *self,
                                             gulong tick);
void        bt_pattern_play_tick            (const BtPattern *self,
                                             gulong tick);

Object Hierarchy


  GObject
   +----BtPattern

Properties


  "id"                   gchararray            : Read / Write
  "is-internal"          gboolean              : Read / Write / Construct Only
  "length"               gulong                : Read / Write
  "machine"              BtMachine             : Read / Write / Construct Only
  "name"                 gchararray            : Read / Write
  "song"                 BtSong                : Read / Write / Construct Only
  "voices"               gulong                : Read / Write

Signal Prototypes


"global-param-changed"
            void        user_function      (BtPattern *self,
                                            gulong tick,
                                            gulong param,
                                            gpointer user_data);
"voice-param-changed"
            void        user_function      (BtPattern *self,
                                            gulong tick,
                                            gulong voice,
                                            gulong param,
                                            gpointer user_data);

Description

A pattern contains a grid of events. Events are parameter changes in BtMachine objects. The events are stored aas GValues.

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

Details

BtPattern

typedef struct _BtPattern BtPattern;

Class that holds a sequence of events for a BtMachine. A BtTimeLineTrack denotes which pattern will be played at which time..

bt_pattern_new ()

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

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

song : the song the new instance belongs to
id : the id, we can use to lookup the pattern
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_new_with_event ()

BtPattern*  bt_pattern_new_with_event       (const BtSong *song,
                                             const BtMachine *machine,
                                             BtPatternCmd cmd);

Create a new default pattern instance containg the given cmd event. It will be automatically added to the machines pattern list.

song : the song the new instance belongs to
machine : the machine the pattern belongs to
cmd : the
Returns : the new instance or NULL in case of an error

bt_pattern_copy ()

BtPattern*  bt_pattern_copy                 (const BtPattern *self);

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

self : the pattern to create a copy from
Returns : the new instance or NULL in case of an error

bt_pattern_get_global_param_index ()

gulong      bt_pattern_get_global_param_index
                                            (const BtPattern *self,
                                             const gchar *name,
                                             GError **error);

Searches the list of registered dparam of the machine the pattern belongs to for a global dparam of the given name and returns the index if found.

self : the pattern to search for the global dparam
name : the name of the global dparam
error : pointer to an error variable
Returns : the index. If an error occurs the function returns 0 and sets the error variable. You should always check for error if you use this function.

bt_pattern_get_voice_param_index ()

gulong      bt_pattern_get_voice_param_index
                                            (const BtPattern *self,
                                             const gchar *name,
                                             GError **error);

Searches the list of registered dparam of the machine the pattern belongs to for a voice dparam of the given name and returns the index if found.

self : the pattern to search for the voice dparam
name : the name of the voice dparam
error : pointer to an error variable
Returns : the index. If an error occurs the function returns 0 and sets the error variable. You should always check for error if you use this function.

bt_pattern_get_global_event_data ()

GValue*     bt_pattern_get_global_event_data
                                            (const BtPattern *self,
                                             gulong tick,
                                             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 G_IS_VALUE(event).

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_voice_event_data ()

GValue*     bt_pattern_get_voice_event_data (const BtPattern *self,
                                             gulong tick,
                                             gulong voice,
                                             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 G_IS_VALUE(event).

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_set_global_event ()

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

Stores the supplied value into the specified pattern cell.

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 *self,
                                             gulong tick,
                                             gulong voice,
                                             gulong param,
                                             const gchar *value);

Stores the supplied value into the specified pattern cell.

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 global parameter starting with 0
value : the string representation of the value to store
Returns : TRUE for success

bt_pattern_get_global_event ()

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

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

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_voice_event ()

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

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

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 global parameter starting with 0
Returns : a newly allocated string with the data or NULL on error

bt_pattern_test_global_event ()

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

Tests if there is an event in the specified cell.

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_voice_event ()

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

Tests if there is an event in the specified cell.

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 global parameter starting with 0
Returns : TRUE if there is an event

bt_pattern_get_cmd ()

BtPatternCmd bt_pattern_get_cmd             (const BtPattern *self,
                                             gulong tick);

Returns the command id in the specified tick row.

self : the pattern to query the command from
tick : the tick (time) position starting with 0
Returns : the command id

bt_pattern_tick_has_data ()

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

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

self : the pattern to check
tick : the tick index in the pattern
Returns : TRUE is there are events, FALSE otherwise

bt_pattern_play_tick ()

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

Pushes all control changes from this pattern-row into the BtMachine params.

self : the pattern a tick should be played from
tick : the tick index in the pattern

Properties

The "id" property

  "id"                   gchararray            : Read / Write

pattern identifier.

Default value: "unamed pattern"

The "is-internal" property

  "is-internal"          gboolean              : Read / Write / Construct Only

internal (cmd-pattern) indicator.

Default value: FALSE

The "length" property

  "length"               gulong                : Read / Write

length of the pattern in ticks.

Allowed values: >= 1

The "machine" property

  "machine"              BtMachine             : Read / Write / Construct Only

Machine object, the pattern belongs to.

The "name" property

  "name"                 gchararray            : Read / Write

the display-name of the pattern.

Default value: "unamed"

The "song" property

  "song"                 BtSong                : Read / Write / Construct Only

Song object, the pattern belongs to.

The "voices" property

  "voices"               gulong                : Read / Write

number of voices in the pattern.

Signals

The "global-param-changed" signal

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

signals that a global param of this pattern has been changed

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

The "voice-param-changed" signal

void        user_function                  (BtPattern *self,
                                            gulong tick,
                                            gulong voice,
                                            gulong param,
                                            gpointer user_data);

signals that a voice param of this pattern has been changed

self : the pattern object that emitted the signal
tick : the tick position inside the pattern
voice : the voice number
param : the voice parameter index
user_data : user data set when the signal handler was connected.