<?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>Effects</title>
  <para>
    You may directly inherit by &lt;ags/audio/ags_recall.h&gt; to do some wicked stuff.
    But generally you should inherit by these subclasses of AgsRecall:
  </para>

    <itemizedlist mark="bullet">
      <listitem>
	<para>
	  &lt;ags/audio/ags_recall_audio.h&gt;
	</para>
      </listitem>
      <listitem>
	<para>
	  &lt;ags/audio/ags_recall_audio_run.h&gt;
	</para>
      </listitem>
      <listitem>
	<para>
	  &lt;ags/audio/ags_recall_channel.h&gt;
	</para>
      </listitem>
      <listitem>
	<para>
	  &lt;ags/audio/ags_recall_channel_run.h&gt;
	</para>
      </listitem>
      <listitem>
	<para>
	  &lt;ags/audio/ags_recall_recycling.h&gt;
	</para>
      </listitem>
      <listitem>
	<para>
	  &lt;ags/audio/ags_recall_audio_signal.h&gt;
	</para>
      </listitem>
    </itemizedlist>

    <para>
      You probably wish to have different context for fields of an effect, that's
      what these objects take on. But before we cover them in detail, we take a
      look at the lifecycle an effect must accomplish.
    </para>

    <sect1>
      <title>Play/recall context</title>
      <para>
	Don't mix this context up with static/runtime context we talked before.
	The AgsRecall may have two faces or may be just one for play context.
      </para>

      <para>
	The play context will be called in case the higher level of AgsRecycling
	will output to a device e.g. the soundcard and no further processing will
	be done.
      </para>

      <para>
	The recall context means that the AgsRecall will pass one or more cycles
	of copying or sequencing. This design is intended to make ags as modular
	and reusable over different use cases as possible. Practically it should
	be possible to chain up several sequencers.
      </para>
    </sect1>

    <sect1>
      <title>Hands-On instantiating an effect</title>
      <para>
	After you got an overview of the basic lifecycle of an effect it's time
	to create an effect. In this guide we will cover instatiating an effect
	by using the echo effect. In the following chapter we'll take a look
	inside the echo effect.
      </para>

      <sect2>
	<title>AgsRecallContainer</title>
	<para>
	  AgsRecallContainer isn't a recall itself but you can use it to
	  retrieve a different context.
	</para>

	<example>
	  <title>Creating AgsRecallContainer</title>
	  <programlisting language="C">
<xi:include href="../listings/effects_recall_container.c" parse="text" />
	  </programlisting>
	</example>

      </sect2>

      <sect2>
	<title>AgsRecallAudio context</title>
	<para>
	  This is a context you want to use for fields applicable to the
	  entire AgsAudio object.
	</para>

	<example>
	  <title>Creating AgsEchoAudio</title>
	  <programlisting language="C">
<xi:include href="../listings/effects_echo_audio.c" parse="text" />
	  </programlisting>
	</example>

      </sect2>

      <sect2>
	<title>AgsRecallChannel context</title>
	<para>
	  This context you can use for fields applicable to the AgsChannel
	  you want to modify.
	</para>

	<example>
	  <title>Creating AgsEchoChannel</title>
	  <programlisting language="C">
<xi:include href="../listings/effects_echo_channel.c" parse="text" />
	  </programlisting>
	</example>

      </sect2>

      <sect2>
	<title>AgsRecallAudioRun context</title>
	<para>
	  The AgsRecallAudioRun class will be duplicated for a parental running
	  AgsChannel. There may be several AgsChannel objects as parental owning
	  a run.
	</para>

	<example>
	  <title>Creating AgsEchoAudioRun</title>
	  <programlisting language="C">
<xi:include href="../listings/effects_echo_audio_run.c" parse="text" />
	  </programlisting>
	</example>

      </sect2>

      <sect2>
	<title>AgsRecallChannelRun context</title>
	<para>
	  The AgsRecallChannelRun behaves like an AgsRecallAudioRun but
	  is designated to an AgsChannel object.
	</para>

	<example>
	  <title>Creating AgsEchoChannelRun</title>
	  <programlisting language="C">
<xi:include href="../listings/effects_echo_channel_run.c" parse="text" />
	  </programlisting>
	</example>

      </sect2>

    </sect1>

    <sect1>
      <title>The basic lifecycle of an effect</title>
      <para>
	In this section I'll introduce the keyword run which can be understood as a
	playing instance. But I rather talk about run because it's not guaranted that
	the recall outputs directly to a device.
      </para>

      <mediaobject>
	<imageobject>
	  <imagedata fileref="../images/AGS_recall_lifecycle.png" format="PNG" align="right" />
	</imageobject>
	<caption align="left">
	  AgsRecall life-cycle
	</caption>
      </mediaobject>
	
      <para>
	The implemented effect as a subclass of AgsRecall resides as template on
	the appropriate AgsAudio or AgsChannel.
      </para>

      <para>
	When recycling changes on input, new AgsRecallRecycling will be added.
	This class function may be of relevancy:
      </para>

      <itemizedlist mark="bullet">
	<listitem>
	  <para>
	    AgsChannel::recycling-changed()
	  </para>
	</listitem>
      </itemizedlist>

      <para>
	As a new run occures the AgsRecallAudioRun and AgsRecallChannelRun will be
	duplicated, dependencies resolved, state initialized and enter the play loop
	hierarchy. These class functions will be called on the recall:
      </para>

      <itemizedlist mark="bullet">
	<listitem>
	  <para>
	    AgsChannel::duplicate-recall()
	  </para>
	  <itemizedlist mark="circle">
	    <listitem>
	      This function will be called on the template object to instantiate the
	      the object which will pass further processing.
	    </listitem>
	  </itemizedlist>
	</listitem>
      </itemizedlist>

      <para>
	Further processing:
      </para>

      <itemizedlist mark="bullet">
	<listitem>
	  <para>
	    AgsRecall::resolve-dependency()
	  </para>
	  <itemizedlist mark="circle">
	    <listitem>
	      <para>
		The recall may want to depend on a other recall (eg. a counter) and
		may ignore following calls while rather do processing on an event
		of the dependency.
	      </para>
	    </listitem>
	  </itemizedlist>
	</listitem>

	<listitem>
	  <para>
	    AgsRecall::run-init-pre(), AgsRecall::run-init-inter() &amp;
	    AgsRecall::run-init-post()
	  </para>
	  <itemizedlist mark="circle">
	    <listitem>
	      <para>
		Will be called only once for the run refering to dedicated AgsRecallID.
	      </para>
	    </listitem>
	  </itemizedlist>
	</listitem>

	<listitem>
	  <para>
	    AgsRecall::run-pre(), AgsRecall::run-inter() &amp;
	    AgsRecall::run-post()
	  </para>
	  <itemizedlist mark="circle">
	    <listitem>
	      <para>
		Will be called for each cycle of a run refering to AgsRecallID.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		There may be more than one AgsRecallID for a template i.e. there can
		exist more than one run at the very same time.
	      </para>
	    </listitem>
	  </itemizedlist>
	</listitem>

      </itemizedlist>

      <para>
	As soon as an add_audio_signal event will be emitted on an AgsRecycling, the
	AgsRecallAudioSignal subclass will be instantiated which performs audio stream
	manipulation. These class functions will be called on the recall:
      </para>

      <itemizedlist mark="bullet">
	<listitem>
	  <para>
	    AgsRecall::run-init-pre(), AgsRecall::run-init-inter() &amp;
	    AgsRecall::run-init-post()
	  </para>
	</listitem>
	<listitem>
	  <para>
	    AgsRecall::automate(), AgsRecall::feed-input-queue(), AgsRecall::run-pre(), AgsRecall::run-inter(),
	    AgsRecall::run-post() &amp; AgsRecall::feed-output-queue()
	  </para>
	</listitem>
      </itemizedlist>

      <para>
	When you're done with processing call:
      </para>

      <itemizedlist mark="bullet">
	<listitem>
	  <para>
	    AgsRecall::done()
	  </para>
	</listitem>
      </itemizedlist>
    </sect1>

    <sect1>
      <title>A closer look at effects</title>
      <para>
	As mentioned before audio processing will be done within an AgsRecallAudioSignal
	subclass.
      </para>
    </sect1>
</chapter>