1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter>
<!-- Copyright (C) 2005-2018 Jo\u00EBl Kr\u00E4hemann -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
<title>Your tree linked with AgsChannel</title>
<para>
AgsChannel forms your audio processing tree and contains recalls, too. You might
want to iterate the channels of your audio object or just call one of these functions:
</para>
<itemizedlist mark="bullet">
<listitem>
<code language="C">AgsChannel* ags_channel_first(AgsChannel*)</code>
</listitem>
<listitem>
<code language="C">AgsChannel* ags_channel_last(AgsChannel*)</code>
</listitem>
<listitem>
<code language="C">AgsChannel* ags_channel_nth(AgsChannel*, guint)</code>
</listitem>
<listitem>
<code language="C">AgsChannel* ags_channel_pad_first(AgsChannel*)</code>
</listitem>
<listitem>
<code language="C">AgsChannel* ags_channel_pad_last(AgsChannel*)</code>
</listitem>
<listitem>
<code language="C">AgsChannel* ags_channel_pad_nth(AgsChannel*, guint)</code>
</listitem>
</itemizedlist>
<para>
As you see there is a grained access to channels. You can lookup channels from with the
same audio channel with the functions containing pad in its name. An other exciting
feature is finding channels having an assigned recycling. These functions operate on
the very same audio channel.
</para>
<itemizedlist mark="bullet">
<listitem>
<code language="C">AgsChannel* ags_channel_first_with_recycling(AgsChannel*)</code>
</listitem>
<listitem>
<code language="C">AgsChannel* ags_channel_last_with_recycling(AgsChannel*)</code>
</listitem>
<listitem>
<code language="C">AgsChannel* ags_channel_prev_with_recycling(AgsChannel*)</code>
</listitem>
<listitem>
<code language="C">AgsChannel* ags_channel_next_with_recycling(AgsChannel*)</code>
</listitem>
</itemizedlist>
<para>
Following object fields are changed during linking. Further a new AgsRecycling might be instantiated to be provided as
<code>first_recycling</code> and <code>last_recycling</code> of specified AgsInput eg. if it is NULL. So this input has got its
very own recycling as specified by <code>AGS_AUDIO_INPUT_HAS_RECYCLING</code>:
</para>
<itemizedlist mark="bullet">
<listitem>
<code>AgsChannel:link</code>
<code>recursive AgsChannel:first-recycling and AgsChannel:last-recycling as needed</code>
<code>AgsRecycling:parent</code>
<code>AgsRecycling:prev or AgsRecycling:next</code>
</listitem>
</itemizedlist>
<sect1>
<title>The pattern</title>
<para>
There can AgsPattern being added to a channel by <code language="C">void ags_channel_add_pattern(AgsChannel*, GObject*)</code>.
Later if not used anymore likewise call <code language="C">void ags_channel_remove_pattern(AgsChannel*, GObject*)</code>.
</para>
<example>
<title>Adding AgsPattern</title>
<programlisting language="C">
<xi:include href="../listings/add_pattern.c" parse="text" />
</programlisting>
</example>
</sect1>
<sect1>
<title>Linking overview</title>
<para>
In this section you get some knowledge about AgsChannel internals. Here you get an
overview of the audio layer. All code related to it is located in subdirectory
<ags/audio>. Linking AgsChannel is a quiet complex thing but If you wish
to do so you can just call <code language="C">void ags_channel_set_link(AgsChannel*, AgsChannel*, GError**)</code>
and this will the especially covered here.
</para>
<para>
AgsAudio, AgsChannel and AgsRecycling are involved in linking. When talking about
linking we should view AgsChannel objects as networked and therefore exists an
additional nested network of AgsRecycling objects.
</para>
<para>
The AgsAudio object gives clarification about how AgsChannel has to be accessed
either synchronously or asynchronously. Further it tells us whether AgsOutput or
AgsInput has a new audio stream which causes in conjunction a dedicated
AgsRecycling associated with the appropriate AgsChannel.
</para>
<imagedata fileref="../images/AGS_linking.png" format="PNG" />
<table>
<title>AGS network layer table</title>
<tgroup cols="2" align="left" colsep='1' rowsep='1'>
<thead>
<row>
<entry>object</entry>
<entry>flags</entry>
</row>
</thead>
<tbody>
<row>
<entry>Audio#0</entry>
<entry>
AGS_AUDIO_SYNC | AGS_AUDIO_OUTPUT_HAS_RECYCLING
</entry>
</row>
<row>
<entry>Audio#1</entry>
<entry>
AGS_AUDIO_ASYNC
</entry>
</row>
<row>
<entry>Audio#2</entry>
<entry>
AGS_AUDIO_ASYNC | AGS_AUDIO_OUTPUT_HAS_RECYCLING
</entry>
</row>
<row>
<entry>Audio#3</entry>
<entry>
AGS_AUDIO_ASYNC | AGS_AUDIO_OUTPUT_HAS_RECYCLING
</entry>
</row>
<row>
<entry>Audio#4</entry>
<entry>
AGS_AUDIO_ASYNC | AGS_AUDIO_OUTPUT_HAS_RECYCLING
</entry>
</row>
</tbody>
</tgroup>
</table>
<itemizedlist mark="bullet">
<listitem>
<para>
green:
</para>
<itemizedlist mark="circle">
<listitem>
Bidirectional linked AgsChannel to an other AgsChannel.
</listitem>
<listitem>
Generally you link an AgsOutput to an AgsInput.
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
red:
</para>
<itemizedlist mark="circle">
<listitem>
Bidirectional linked AgsRecycling to an other AgsRecycling on the same
level.
</listitem>
<listitem>
They are linked across AgsAudio objects.
</listitem>
<listitem>
Same level means the linked AgsRecycling are all child nodes of a parent
AgsRecycling.
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
yellow:
</para>
<itemizedlist mark="circle">
<listitem>
Unidirectional linked AgsRecycling to an AgsChannel.
</listitem>
<listitem>
First AgsRecycling of an AgsOutput and last AgsRecycling of an (other)
AgsOutput are linked to an AgsChannel.
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Limitations</title>
<itemizedlist mark="bullet">
<listitem>
You may not create any kind of loops.
</listitem>
<listitem>
You may not set AGS_AUDIO_INPUT_HAS_RECYCLING without setting
AGS_AUDIO_OUTPUT_HAS_RECYCLING flag.
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Hands-On</title>
<para>
There may be two ways how you can link AgsChannel objects.
</para>
<example>
<title>Prerequisites</title>
<programlisting language="C">
<xi:include href="../listings/linking_prerequisites.c" parse="text" />
</programlisting>
</example>
<para>
Assumed you know really what you do, you may be interested in following code.
</para>
<example>
<title>Thread-Unsafe way</title>
<programlisting language="C">
<xi:include href="../listings/linking_unsafe.c" parse="text" />
</programlisting>
</example>
<para>
But generally you wish to create an AgsTask object and let it to link the
AgsChannel for you.
</para>
<example>
<title>Multithread-Safe way</title>
<programlisting language="C">
<xi:include href="../listings/linking_safe.c" parse="text" />
</programlisting>
</example>
</sect1>
</chapter>
|
