BtPattern

BtPattern — class for an event pattern of a BtMachine instance

Synopsis

#include <libbtcore/core.h>

                    BtPattern;
enum                BtPatternCmd;
BtPattern *         bt_pattern_new                      (const BtSong * const song,
                                                         const gchar * const id,
                                                         const gchar * const name,
                                                         const gulong length,
                                                         const BtMachine * const machine);
BtPattern *         bt_pattern_new_with_event           (const BtSong * const song,
                                                         const BtMachine * const machine,
                                                         const BtPatternCmd cmd);
BtPattern *         bt_pattern_copy                     (const BtPattern * const self);
gulong              bt_pattern_get_global_param_index   (const BtPattern * const self,
                                                         const gchar * const name,
                                                         GError **error);
gulong              bt_pattern_get_voice_param_index    (const BtPattern * const self,
                                                         const gchar * const name,
                                                         GError **error);
GValue *            bt_pattern_get_global_event_data    (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong param);
GValue *            bt_pattern_get_voice_event_data     (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong voice,
                                                         const gulong param);
gboolean            bt_pattern_set_global_event         (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong param,
                                                         const gchar * const value);
gboolean            bt_pattern_set_voice_event          (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong voice,
                                                         const gulong param,
                                                         const gchar * const value);
gchar *             bt_pattern_get_global_event         (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong param);
gchar *             bt_pattern_get_voice_event          (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong voice,
                                                         const gulong param);
gboolean            bt_pattern_test_global_event        (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong param);
gboolean            bt_pattern_test_voice_event         (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong voice,
                                                         const gulong param);
BtPatternCmd        bt_pattern_get_cmd                  (const BtPattern * const self,
                                                         const gulong tick);
gboolean            bt_pattern_tick_has_data            (const BtPattern * const self,
                                                         const gulong tick);
void                bt_pattern_insert_row               (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong param);
void                bt_pattern_insert_full_row          (const BtPattern * const self,
                                                         const gulong tick);
void                bt_pattern_delete_row               (const BtPattern * const self,
                                                         const gulong tick,
                                                         const gulong param);
void                bt_pattern_delete_full_row          (const BtPattern * const self,
                                                         const gulong tick);
void                bt_pattern_delete_column            (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick,
                                                         const gulong param);
void                bt_pattern_delete_columns           (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick);
void                bt_pattern_blend_column             (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick,
                                                         const gulong param);
void                bt_pattern_blend_columns            (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick);
void                bt_pattern_randomize_column         (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick,
                                                         const gulong param);
void                bt_pattern_randomize_columns        (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick);
void                bt_pattern_serialize_column         (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick,
                                                         const gulong param,
                                                         GString *data);
void                bt_pattern_serialize_columns        (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick,
                                                         GString *data);
gboolean            bt_pattern_deserialize_column       (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick,
                                                         const gulong param,
                                                         const gchar *data);

Object Hierarchy

  GObject
   +----BtPattern

Implemented Interfaces

BtPattern implements BtPersistence.

Properties

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

Signals

  "global-param-changed"                           : Run Last / No Recursion / No Hooks
  "pattern-changed"                                : Run Last / No Recursion / No Hooks
  "voice-param-changed"                            : Run Last / No Recursion / No Hooks

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;

Holds a sequence of events for a BtMachine.


enum BtPatternCmd

typedef enum {
  BT_PATTERN_CMD_NORMAL=0,
  BT_PATTERN_CMD_MUTE,
  BT_PATTERN_CMD_BREAK,
  BT_PATTERN_CMD_SOLO,
  BT_PATTERN_CMD_BYPASS
} BtPatternCmd;

A pattern has a command field for every tick. The commands are only used in static internal patterns.

BT_PATTERN_CMD_NORMAL

just working

BT_PATTERN_CMD_MUTE

be quiet immediately

BT_PATTERN_CMD_BREAK

no more notes

BT_PATTERN_CMD_SOLO

be the only one playing

BT_PATTERN_CMD_BYPASS

be uneffective (pass through)

bt_pattern_new ()

BtPattern *         bt_pattern_new                      (const BtSong * const song,
                                                         const gchar * const id,
                                                         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.

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 * const song,
                                                         const BtMachine * const machine,
                                                         const BtPatternCmd cmd);

Create a new default pattern instance containg the given cmd event. It will be automatically added to the machines pattern list. If cmd is BT_PATTERN_CMD_NORMAL use bt_pattern_new() instead.

Don't call this from applications.

song :

the song the new instance belongs to

machine :

the machine the pattern belongs to

cmd :

a BtPatternCmd

Returns :

the new instance or NULL in case of an error

bt_pattern_copy ()

BtPattern *         bt_pattern_copy                     (const BtPattern * const 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 * const self,
                                                         const gchar * const 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 * const self,
                                                         const gchar * const 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 * 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 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 * 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 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 * const self,
                                                         const gulong tick,
                                                         const gulong param,
                                                         const gchar * const 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 * const self,
                                                         const gulong tick,
                                                         const gulong voice,
                                                         const gulong param,
                                                         const gchar * const 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 * const self,
                                                         const gulong tick,
                                                         const 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 * const self,
                                                         const gulong tick,
                                                         const gulong voice,
                                                         const 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 * const self,
                                                         const gulong tick,
                                                         const 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 * const self,
                                                         const gulong tick,
                                                         const gulong voice,
                                                         const 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 * const self,
                                                         const 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 * const self,
                                                         const 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_insert_row ()

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

Insert one empty row for given param.

self :

the pattern

tick :

the postion to insert at

param :

the parameter

Since 0.3


bt_pattern_insert_full_row ()

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

Insert one empty row for all parameters.

self :

the pattern

tick :

the postion to insert at

Since 0.3


bt_pattern_delete_row ()

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

Delete row for given param.

self :

the pattern

tick :

the postion to delete

param :

the parameter

Since 0.3


bt_pattern_delete_full_row ()

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

Delete row for all parameters.

self :

the pattern

tick :

the postion to delete

Since 0.3


bt_pattern_delete_column ()

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

Randomize values from start_tick to end_tick for param.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

param :

the parameter

Since 0.6


bt_pattern_delete_columns ()

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

Clear values from start_tick to end_tick for all params.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

Since 0.6


bt_pattern_blend_column ()

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

Fade values from start_tick to end_tick for param.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

param :

the parameter

Since 0.3


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.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

Since 0.3


bt_pattern_randomize_column ()

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

Randomize values from start_tick to end_tick for param.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

param :

the parameter

Since 0.3


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.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

Since 0.3


bt_pattern_serialize_column ()

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

Serializes values from start_tick to end_tick for param into data.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

param :

the parameter

data :

the target

Since 0.6


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.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

data :

the target

Since 0.6


bt_pattern_deserialize_column ()

gboolean            bt_pattern_deserialize_column       (const BtPattern * const self,
                                                         const gulong start_tick,
                                                         const gulong end_tick,
                                                         const gulong param,
                                                         const gchar *data);

Deserializes values to start_tick to end_tick for param from data.

self :

the pattern

start_tick :

the start postion for the range

end_tick :

the end postion for the range

param :

the parameter

data :

the source data

Returns :

TRUE for success, FALSE e.g. to indicate incompative GType values for the column specified by param and the data.

Since 0.6

Property Details

The "id" property

  "id"                       gchar*                : Read / Write / Construct

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 / Construct

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"                     gchar*                : Read / Write / Construct

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.

Signal Details

The "global-param-changed" signal

void                user_function                      (BtPattern *self,
                                                        gulong     tick,
                                                        gulong     param,
                                                        gpointer   user_data)      : Run Last / No Recursion / No Hooks

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 "pattern-changed" signal

void                user_function                      (BtPattern *self,
                                                        gpointer   user_data)      : Run Last / No Recursion / No Hooks

signals that this pattern has been changed (more than in one place)

self :

the pattern object that emitted the signal

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)      : Run Last / No Recursion / No Hooks

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.