# Effects

You may directly inherit by <ags/audio/ags_recall.h> to do some wicked stuff. But generally you should inherit by these subclasses of AgsRecall:

- <ags/audio/ags_recall_audio.h>

- <ags/audio/ags_recall_audio_run.h>

- <ags/audio/ags_recall_channel.h>

- <ags/audio/ags_recall_channel_run.h>

- <ags/audio/ags_recall_recycling.h>

- <ags/audio/ags_recall_audio_signal.h>

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.

## Play/recall context

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.

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.

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.

## Hands-On instantiating an effect

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.

### AgsRecallContainer

AgsRecallContainer isn't a recall itself but you can use it to retrieve a different context.

#### Creating AgsRecallContainer

### AgsRecallAudio context

This is a context you want to use for fields applicable to the entire AgsAudio object.

#### Creating AgsEchoAudio

### AgsRecallChannel context

This context you can use for fields applicable to the AgsChannel you want to modify.

#### Creating AgsEchoChannel

### AgsRecallAudioRun context

The AgsRecallAudioRun class will be duplicated for a parental running AgsChannel. There may be several AgsChannel objects as parental owning a run.

#### Creating AgsEchoAudioRun

### AgsRecallChannelRun context

The AgsRecallChannelRun behaves like an AgsRecallAudioRun but is designated to an AgsChannel object.

#### Creating AgsEchoChannelRun

## The basic lifecycle of an effect

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.

AgsRecall life-cycle

The implemented effect as a subclass of AgsRecall resides as template on the appropriate AgsAudio or AgsChannel.

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

- AgsChannel::recycling-changed()

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:

- AgsChannel::duplicate-recall()

  - This function will be called on the template object to instantiate the the object which will pass further processing.

Further processing:

- AgsRecall::resolve-dependency()

  - 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.

- AgsRecall::run-init-pre(), AgsRecall::run-init-inter() & AgsRecall::run-init-post()

  - Will be called only once for the run refering to dedicated AgsRecallID.

- AgsRecall::run-pre(), AgsRecall::run-inter() & AgsRecall::run-post()

  - Will be called for each cycle of a run refering to AgsRecallID.

  - There may be more than one AgsRecallID for a template i.e. there can exist more than one run at the very same time.

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:

- AgsRecall::run-init-pre(), AgsRecall::run-init-inter() & AgsRecall::run-init-post()

- AgsRecall::automate(), AgsRecall::feed-input-queue(), AgsRecall::run-pre(), AgsRecall::run-inter(), AgsRecall::run-post() & AgsRecall::feed-output-queue()

When you're done with processing call:

- AgsRecall::done()

## A closer look at effects

As mentioned before audio processing will be done within an AgsRecallAudioSignal subclass.