AgsChannel: Advanced Gtk+ Sequencer Reference Manual

AgsChannel

AgsChannel — Acts as entry point to the audio tree.

Functions

GQuark	ags_channel_error_quark ()
AgsRecall *	ags_channel_find_recall ()
AgsChannel *	ags_channel_first ()
AgsChannel *	ags_channel_last ()
AgsChannel *	ags_channel_nth ()
AgsChannel *	ags_channel_pad_first ()
AgsChannel *	ags_channel_pad_last ()
AgsChannel *	ags_channel_pad_nth ()
AgsChannel *	ags_channel_first_with_recycling ()
AgsChannel *	ags_channel_last_with_recycling ()
AgsChannel *	ags_channel_prev_with_recycling ()
AgsChannel *	ags_channel_next_with_recycling ()
void	ags_channel_set_soundcard ()
void	ags_channel_set_samplerate ()
void	ags_channel_set_buffer_size ()
void	ags_channel_set_format ()
void	ags_channel_remove_recall_id ()
void	ags_channel_add_recall_id ()
void	ags_channel_add_recall_container ()
void	ags_channel_remove_recall_container ()
void	ags_channel_remove_recall ()
void	ags_channel_add_recall ()
void	ags_channel_remove_pattern ()
void	ags_channel_add_pattern ()
GList *	ags_channel_add_effect ()
void	ags_channel_remove_effect ()
void	ags_channel_safe_resize_audio_signal ()
void	ags_channel_duplicate_recall ()
void	ags_channel_resolve_recall ()
void	ags_channel_init_recall ()
void	ags_channel_play ()
void	ags_channel_done ()
void	ags_channel_cancel ()
void	ags_channel_remove ()
void	ags_channel_recall_id_set ()
GList *	ags_channel_find_port ()
void	ags_channel_set_link ()
void	ags_channel_set_recycling ()
void	ags_channel_recursive_reset_recycling_context ()
void	ags_channel_recycling_changed ()
AgsRecallID *	ags_channel_recursive_play_init ()
void	ags_channel_recursive_play_threaded ()
void	ags_channel_tillrecycling_cancel ()
void	ags_channel_recursive_reset_recall_ids ()
AgsChannel *	ags_channel_new ()

Properties

GObject *	audio	Read / Write
guint	audio-channel	Read
guint	buffer-size	Read
AgsRecycling *	first-recycling	Read
guint	format	Read
AgsRecycling *	last-recycling	Read
guint	line	Read
AgsChannel *	link	Read / Write
gchar *	note	Read / Write
guint	pad	Read
AgsPattern *	pattern	Read / Write
AgsRecall *	play	Read / Write
AgsPlayback *	playback	Read / Write
AgsRecall *	recall	Read / Write
AgsRecallContainer *	recall-container	Read / Write
AgsRecallID *	recall-id	Read / Write
guint	samplerate	Read
GObject *	soundcard	Read / Write

Signals

gpointer	add-effect	Run Last
void	done	Run Last
void	recycling-changed	Run Last
void	remove-effect	Run Last

Types and Values

enum	AgsChannelFlags
enum	AgsChannelRecallIDMode
#define	AGS_CHANNEL_ERROR
enum	AgsChannelError

Object Hierarchy

    GObject
    ╰── AgsChannel
        ├── AgsInput
        ╰── AgsOutput

Implemented Interfaces

AgsChannel implements AgsConnectable.

Includes

#include <ags/audio/ags_channel.h>

Description

AgsChannel is the entry point to the entire audio tree and its nested recycling tree.

Every channel has its own AgsRecallID. As modifying link a new AgsRecyclingContext is indicated, since it acts as a kind of recall id tree context.

Functions

ags_channel_error_quark ()

GQuark
ags_channel_error_quark ();

ags_channel_find_recall ()

AgsRecall *
ags_channel_find_recall (AgsChannel *channel,
                         char *effect,
                         char *name);

ags_channel_first ()

AgsChannel *
ags_channel_first (AgsChannel *channel);

Iterates until the first AgsChannel was found.

Parameters

channel

an AgsChannel

Returns

the first AgsChannel

Since: 0.3

ags_channel_last ()

AgsChannel *
ags_channel_last (AgsChannel *channel);

Iterates until the last AgsChannel was found.

Parameters

channel

an AgsChannel

Returns

the last AgsChannel

Since: 0.3

ags_channel_nth ()

AgsChannel *
ags_channel_nth (AgsChannel *channel,
                 guint nth);

Iterates nth times forward.

Parameters

channel	an AgsChannel
nth	the count to iterate

Returns

the nth AgsChannel

Since: 0.3

ags_channel_pad_first ()

AgsChannel *
ags_channel_pad_first (AgsChannel *channel);

Iterates until the first pad has been reached.

Parameters

channel

an AgsChannel

Returns

the first AgsChannel with the same audio_channel as channel

Since: 0.3

ags_channel_pad_last ()

AgsChannel *
ags_channel_pad_last (AgsChannel *channel);

Iterates until the last pad has been reached.

Parameters

channel

an AgsChannel

Returns

the last AgsChannel with the same audio_channel as channel

Since: 0.3

ags_channel_pad_nth ()

AgsChannel *
ags_channel_pad_nth (AgsChannel *channel,
                     guint nth);

Iterates nth times.

Parameters

channel	an AgsChannel
nth	the count of pads to step

Returns

the nth pad

Since: 0.3

ags_channel_first_with_recycling ()

AgsChannel *
ags_channel_first_with_recycling (AgsChannel *channel);

Iterates over pads forwards as long as there is no AgsRecycling on the AgsChannel.

Parameters

channel

an AgsChannel

Returns

the first channel with an AgsRecycling

Since: 0.3

ags_channel_last_with_recycling ()

AgsChannel *
ags_channel_last_with_recycling (AgsChannel *channel);

Iterates over pads backwards as long as there is no AgsRecycling on the AgsChannel.

Parameters

channel

an AgsChannel

Returns

the last channel with an AgsRecycling

Since: 0.3

ags_channel_prev_with_recycling ()

AgsChannel *
ags_channel_prev_with_recycling (AgsChannel *channel);

ags_channel_next_with_recycling ()

AgsChannel *
ags_channel_next_with_recycling (AgsChannel *channel);

ags_channel_set_soundcard ()

void
ags_channel_set_soundcard (AgsChannel *channel,
                           GObject *soundcard);

Sets soundcard.

Parameters

channel	an AgsChannel
soundcard	an GObject

Since: 0.4

ags_channel_set_samplerate ()

void
ags_channel_set_samplerate (AgsChannel *channel,
                            guint samplerate);

ags_channel_set_buffer_size ()

void
ags_channel_set_buffer_size (AgsChannel *channel,
                             guint buffer_size);

ags_channel_set_format ()

void
ags_channel_set_format (AgsChannel *channel,
                        guint format);

ags_channel_remove_recall_id ()

void
ags_channel_remove_recall_id (AgsChannel *channel,
                              AgsRecallID *recall_id);

Removes a recall id.

Parameters

channel	an AgsChannel
recall_id	the AgsRecallID

Since: 0.4

ags_channel_add_recall_id ()

void
ags_channel_add_recall_id (AgsChannel *channel,
                           AgsRecallID *recall_id);

Adds a recall id.

Parameters

channel	an AgsChannel
recall_id	the AgsRecallID

Since: 0.4

ags_channel_add_recall_container ()

void
ags_channel_add_recall_container (AgsChannel *channel,
                                  GObject *recall_container);

Adds a recall container.

Parameters

channel	an AgsChannel
recall_container	the AgsRecallContainer

Since: 0.4

ags_channel_remove_recall_container ()

void
ags_channel_remove_recall_container (AgsChannel *channel,
                                     GObject *recall_container);

Removes a recall container.

Parameters

channel	an AgsChannel
recall_container	the AgsRecallContainer

Since: 0.4

ags_channel_remove_recall ()

void
ags_channel_remove_recall (AgsChannel *channel,
                           GObject *recall,
                           gboolean play);

Removes a recall.

Parameters

channel	an AgsChannel
recall	the AgsRecall
play	`TRUE` if simple playback.

Since: 0.4

ags_channel_add_recall ()

void
ags_channel_add_recall (AgsChannel *channel,
                        GObject *recall,
                        gboolean play);

Adds a recall.

Parameters

channel	an AgsChannel
recall	the AgsRecall
play	`TRUE` if simple playback.

Since: 0.4

ags_channel_remove_pattern ()

void
ags_channel_remove_pattern (AgsChannel *channel,
                            GObject *pattern);

Removes a pattern.

Parameters

channel	an AgsChannel
pattern	the AgsPattern

Since: 0.7.2

ags_channel_add_pattern ()

void
ags_channel_add_pattern (AgsChannel *channel,
                         GObject *pattern);

ags_channel_add_effect ()

GList *
ags_channel_add_effect (AgsChannel *channel,
                        char *filename,
                        gchar *effect);

ags_channel_remove_effect ()

void
ags_channel_remove_effect (AgsChannel *channel,
                           guint nth);

ags_channel_safe_resize_audio_signal ()

void
ags_channel_safe_resize_audio_signal (AgsChannel *channel,
                                      guint length);

Resize audio data.

Parameters

channel	an AgsChannel
length	new frame count length

Since: 0.4

ags_channel_duplicate_recall ()

void
ags_channel_duplicate_recall (AgsChannel *channel,
                              AgsRecallID *recall_id);

Duplicate AgsRecall templates for use with ags_channel_recursive_play(), but ags_channel_recursive_play_init() may call this function for you.

Parameters

channel	an AgsChannel that contains the AgsRecall templates
recall_id	the AgsRecallID the newly allocated AgsRecall objects belongs to

Since: 0.3

ags_channel_resolve_recall ()

void
ags_channel_resolve_recall (AgsChannel *channel,
                            AgsRecallID *recall_id);

Resolve step of initialization.

Parameters

channel	an AgsChannel
recall_id	appropriate AgsRecallID

Since: 0.4

ags_channel_init_recall ()

void
ags_channel_init_recall (AgsChannel *channel,
                         gint stage,
                         AgsRecallID *recall_id);

Prepare AgsRecall objects to become runnning, ags_channel_recursive_play_init() may call this function for you.

Parameters

channel	an AgsChannel that contains the recalls
stage	the stage to init
recall_id	the AgsRecallId this recall belongs to

Since: 0.3

ags_channel_play ()

void
ags_channel_play (AgsChannel *channel,
                  AgsRecallID *recall_id,
                  gint stage);

Play one single run of stage step.

Parameters

channel	an AgsChannel
recall_id	appropriate AgsRecallID
stage	run_pre, run_inter or run_post

Since: 0.3

ags_channel_done ()

void
ags_channel_done (AgsChannel *channel,
                  AgsRecallID *recall_id);

Is emitted as playing channel is done.

Parameters

channel	an AgsChannel
recall_id	the current AgsRecallID

Since: 0.4

ags_channel_cancel ()

void
ags_channel_cancel (AgsChannel *channel,
                    AgsRecallID *recall_id);

Calls for every matching recall_id ags_recall_cancel()

Parameters

channel	an AgsChannel
recall_id	and AgsRecallID

Since: 0.3

ags_channel_remove ()

void
ags_channel_remove (AgsChannel *channel,
                    AgsRecallID *recall_id);

Calls for every matching recall_id ags_recall_remove()

Parameters

channel	an AgsChannel
recall_id	and AgsRecallID

Since: 0.3

ags_channel_recall_id_set ()

void
ags_channel_recall_id_set (AgsChannel *output,
                           AgsRecallID *recall_id,
                           gboolean ommit_own_channel,
                           guint mode,
                           ...);

ags_channel_find_port ()

GList *
ags_channel_find_port (AgsChannel *channel);

Retrieve all ports of AgsChannel

Parameters

channel

an AgsChannel

Returns

a GList containing AgsPort

Since: 0.4

ags_channel_set_link ()

void
ags_channel_set_link (AgsChannel *channel,
                      AgsChannel *link,
                      GError **error);

Change the linking of AgsChannel objects. Sets link, calls ags_channel_set_recycling() and ags_channel_recursive_reset_recall_ids(). Further it does loop detection and makes your machine running. Thus it adds AgsRecallID. Asynchronously only.

Parameters

channel	an AgsChannel to link
link	an other AgsChannel to link with
error	you may retrieve a AGS_CHANNEL_ERROR_LOOP_IN_LINK error

Since: 0.3

ags_channel_set_recycling ()

void
ags_channel_set_recycling (AgsChannel *channel,
                           AgsRecycling *first_recycling,
                           AgsRecycling *last_recycling,
                           gboolean update,
                           gboolean destroy_old);

Called by ags_channel_set_link() to handle outdated AgsRecycling references. Asynchronously only.

Parameters

channel	the channel to reset
first_recycling	the recycling to set for channel->first_recycling
last_recycling	the recycling to set for channel->last_recycling
update	reset allthough the AgsRecyclings are still the same
destroy_old	destroy old AgsRecyclings

Since: 0.3

ags_channel_recursive_reset_recycling_context ()

void
ags_channel_recursive_reset_recycling_context
                               (AgsChannel *channel,
                                AgsRecyclingContext *old_recycling_context,
                                AgsRecyclingContext *recycling_context);

Resets the recycling container context. Asynchronously only.

Parameters

channel	the channel to reset
old_recycling_context	the old recycling container context
recycling_context	the new recycling container context

Since: 0.4

ags_channel_recycling_changed ()

void
ags_channel_recycling_changed (AgsChannel *channel,
                               AgsRecycling *old_start_region,
                               AgsRecycling *old_end_region,
                               AgsRecycling *new_start_region,
                               AgsRecycling *new_end_region,
                               AgsRecycling *old_start_changed_region,
                               AgsRecycling *old_end_changed_region,
                               AgsRecycling *new_start_changed_region,
                               AgsRecycling *new_end_changed_region);

Modify recycling. Asynchronously only.

Parameters

channel	the object recycling changed
old_start_region	first recycling
old_end_region	last recycling
new_start_region	new first recycling
new_end_region	new last recycling
old_start_changed_region	modified link recycling start
old_end_changed_region	modified link recyclig end
new_start_changed_region	replacing link recycling start
new_end_changed_region	replacing link recycling end

Since: 0.3

ags_channel_recursive_play_init ()

AgsRecallID *
ags_channel_recursive_play_init (AgsChannel *channel,
                                 gint stage,
                                 gboolean arrange_recall_id,
                                 gboolean duplicate_templates,
                                 gboolean do_playback,
                                 gboolean do_sequencer,
                                 gboolean do_notation,
                                 gboolean resolve_dependencies,
                                 AgsRecallID *recall_id);

Make the tree ready for a new AgsPlayback. Only for asynchronous use, take a look at AgsInitChannel or AgsInitAudio task.

Parameters

channel	the AgsChannel to prepare
stage	valid values for `stage` are: -1 for running all three stages, or the stages 0 through 2 to run just the specified stage. With stage is meant the AgsRecall run_init_pre, AgsRecall run_init_inter and AgsRecall run_init_post stages.
arrange_recall_id	`TRUE` if new AgsRecallID objects should be created
duplicate_templates	`TRUE` if the AgsRecall templates should be duplicated
do_playback	`TRUE` if the purpose is a simple playback of the tree, this option is used to omit the duplication of AgsRecall templates which haven't set `AGS_RECALL_PLAYBACK` flag
do_sequencer	`TRUE` if the purpose is playing the tree for a sequencer, this option is used to omit the duplication of AgsRecall templates which haven't set the `AGS_RECALL_SEQUENCER` flag
do_notation	`TRUE` if the purpose is playing the tree for a notation, this option is used to omit the duplication of AgsRecall templates which haven't set the `AGS_RECALL_NOTATION` flag
resolve_dependencies	`TRUE` if the
recall_id	the initial recall id or `NULL`

Returns

a new AgsRecallID

Since: 0.3

ags_channel_recursive_play_threaded ()

void
ags_channel_recursive_play_threaded (AgsChannel *channel,
                                     AgsRecallID *recall_id,
                                     gint stage);

Super-threaded version of ags_channel_recursive_play() one single run of stage step. This function expects to be called by AgsIteratorThread and having a functional AgsRecyclingThread setup.

Parameters

channel	an AgsChannel
recall_id	appropriate AgsRecallID
stage	run_pre, run_inter or run_post

Since: 0.4

ags_channel_tillrecycling_cancel ()

void
ags_channel_tillrecycling_cancel (AgsChannel *channel,
                                  AgsRecallID *recall_id);

Traverses the tree down and up and calls ags_channel_cancel() for corresponding recall_id .

Parameters

channel	an AgsChannel
recall_id	an AgsRecallID

Since: 0.4

ags_channel_recursive_reset_recall_ids ()

void
ags_channel_recursive_reset_recall_ids
                               (AgsChannel *channel,
                                AgsChannel *link,
                                AgsChannel *old_channel_link,
                                AgsChannel *old_link_link);

Called by ags_channel_set_link() to handle running AgsAudio objects correctly. This function destroys AgsRecall objects which were uneeded because they became invalid due to unlinking. By the way it destroys the uneeded AgsRecallID objects, too. Additionally it creates AgsRecall and AgsRecallID objects to prepare becoming a running object (AgsAudio or AgsChannel). By the clean up the invalid AgsRecall objects will be removed. Once the clean up has done ags_channel_recursive_play_init() will be called for every playing instance that was found.

Parameters

channel	an AgsChannel that was linked with `link`
link	an AgsChannel that was linked with `channel`
old_channel_link	the old link of `channel`
old_link_link	the old link of `link`

Since: 0.4

ags_channel_new ()

AgsChannel *
ags_channel_new (GObject *audio);

Creates a AgsChannel, linking tree to audio .

Parameters

audio

the AgsAudio

Returns

a new AgsChannel

Since: 0.3

Types and Values

enum AgsChannelFlags

Members

AGS_CHANNEL_CONNECTED
AGS_CHANNEL_RUNNING

enum AgsChannelRecallIDMode

Members

AGS_CHANNEL_RECALL_ID_RUN_STAGE
AGS_CHANNEL_RECALL_ID_CANCEL

AGS_CHANNEL_ERROR

#define AGS_CHANNEL_ERROR (ags_channel_error_quark())

enum AgsChannelError

Members

AGS_CHANNEL_ERROR_LOOP_IN_LINK

Property Details

The `“audio”` property

  “audio”                    GObject *

The audio it is assigned with.

Flags: Read / Write

Since: 0.4.0

The `“audio-channel”` property

  “audio-channel”            guint

The nth audio channel.

Flags: Read

Allowed values: <= 65535

Default value: 0

The `“buffer-size”` property

  “buffer-size”              guint

The buffer size.

Flags: Read

Default value: 0

The `“first-recycling”` property

  “first-recycling”          AgsRecycling *

The first recycling it contains.

Flags: Read

Since: 0.7.2

The `“format”` property

  “format”                   guint

The format.

Flags: Read

Default value: 0

The `“last-recycling”` property

  “last-recycling”           AgsRecycling *

The last recycling it contains.

Flags: Read

Since: 0.7.2

The `“line”` property

  “line”                     guint

The nth line.

Flags: Read

Allowed values: <= 65535

Default value: 0

The `“link”` property

  “link”                     AgsChannel *

The link it is assigned with.

Flags: Read / Write

Since: 0.7.2

The `“note”` property

  “note”                     gchar *

The note it is assigned with.

Flags: Read / Write

Default value: NULL

Since: 0.7.2

The `“pad”` property

  “pad”                      guint

The nth pad.

Flags: Read

Allowed values: <= 65535

Default value: 0

The `“pattern”` property

  “pattern”                  AgsPattern *

The pattern it contains.

Flags: Read / Write

Since: 0.7.2

The `“play”` property

  “play”                     AgsRecall *

The play it contains.

Flags: Read / Write

Since: 0.7.2

The `“playback”` property

  “playback”                 AgsPlayback *

The playback it is assigned with.

Flags: Read / Write

Since: 0.7.2

The `“recall”` property

  “recall”                   AgsRecall *

The recall it contains.

Flags: Read / Write

Since: 0.7.2

The `“recall-container”` property

  “recall-container”         AgsRecallContainer *

The recall container it contains.

Flags: Read / Write

Since: 0.7.2

The `“recall-id”` property

  “recall-id”                AgsRecallID *

The recall id it is assigned with.

Flags: Read / Write

Since: 0.7.2

The `“samplerate”` property

  “samplerate”               guint

The samplerate.

Flags: Read

Default value: 0

The `“soundcard”` property

  “soundcard”                GObject *

The soundcard it is assigned with.

Flags: Read / Write

Since: 0.4.0

Signal Details

The `“add-effect”` signal

gpointer
user_function (AgsChannel *channel,
               gchar      *effect,
               gchar      *arg2,
               gpointer    user_data)

Flags: Run Last

The `“done”` signal

void
user_function (AgsChannel *channel,
               GObject    *recall_id,
               gpointer    user_data)

Flags: Run Last

The `“recycling-changed”` signal

void
user_function (AgsChannel *old_start_region,
               GObject    *old_end_region,
               GObject    *new_start_region,
               GObject    *new_end_region,
               GObject    *old_start_changed_region,
               GObject    *old_end_changed_region,
               GObject    *new_start_changed_region,
               GObject    *new_end_changed_region,
               GObject    *arg8,
               gpointer    user_data)

Flags: Run Last

The `“remove-effect”` signal

void
user_function (AgsChannel *channel,
               guint       nth,
               gpointer    user_data)

Flags: Run Last