<commit_before>= Effects
<NAME> <<EMAIL>>
:icons: font
:toc:
:toc-placement: preamble

// Set up support for relative links on GitHub; add more conditions
// if you need to support other environments and extensions.
ifdef::env-github[:outfilesuffix: .adoc]

Effects determine what a light or group of lights are doing at a given
moment in time.

== Overview

When creating an effect, you assign one or more
<<fixture_definitions#fixture-definitions,Fixtures>> to it, and it
will generate control values for only those fixtures. The fixture
channels affected by the effect depend on the kind of effect it is,
and are grouped into several primary categories. The simplest kinds of
effects apply to a single channel per fixture, or perhaps per head, if
the fixture has multiple independent light-emitting heads. A very
common single-channel effect is the <<dimmer-effects,dimmer effect>>.

Many effects assign <<color-effects,colors>> to lights, which often
involves multiple channels. RGB fixtures will use three channels, one
each for the red, green, and blue levels which make up the color. Some
fixtures add other LED colors, such as amber, white, and even
ultraviolet. Other fixtures simply use a rotating color wheel to pick
from a fixed set of colors, using a single channel. Regardless of how
the color is finally produced, at most stages of effect processing,
Afterglow works in terms of the
<<working_with_color#working-with-color,color itself>>, allowing you
to blend, lighten, darken, shift hue, and the like so you can produce
interesting looks, without regard to details of fixture
implementation. It is only at the
<<rendering_loop#the-rendering-loop,final rendering stage>> that the
color is broken down into channel assignments.

Another important category of effects control the
<<direction-effects,direction>> of moving-head fixtures. These work in
terms of a desired 3D direction vector or <<aim-effects,target point>>
with respect to the <<show_space#show-space,show frame of reference>>,
and at the last stage of rendering, convert that to pan and tilt
channel values, with reference to the angle at which the fixture has
actually been hung.

You can also conveniently use features which are shared by a number of
fixtures, or completely unique to a single fixture, through
<<function-effects,function effects>>, or drop right down to the
level of individual DMX channel values with
<<channel-effects,channel effects>>.

Finally, Afterglow includes some examples of how to build up
<<complex-effects,special-purpose effects>>, which can be fun in
themselves, and also serve as templates and inspiration for whole new
kinds of effects you create on your own.

== Effect Types

Effects in afterglow are divided by the aspect of a light that they
control. Not all fixtures have features which allow them to
participate in all kinds of effects. Afterglow effects will
simply ignore fixtures which are unable to reapond to them.

=== Dimmer Effects

Dimmer effects set the basic brightness level of a fixture. To create
an effect that will set the dimmer level of a fixture, use:

[source,clojure]
----
(afterglow.effects.dimmer/dimmer-effect level fixtures)
----

This effect finds all the dimmer channels associated with the
specified fixtures (there may be multiple, if the fixture has more
than one light-emitting head), and assigns them a level. 0 is off, 255
is maximum brightness. Dimmer effects can work with either fully
dedicated dimmer channels (in which case the channel itself has a
`:type` of `:dimmer`, and the entire DMX range is used for dimming),
or multipurpose channels in which a subset of the DMX range is
assigned to a function of type `:dimmer`, and the channel `:type` is
something else.

If `htp?` is true, uses highest-takes-precedence rules when replacing
any earlier or lower-priority effects which attempted to set this
particular dimmer in the current rendering cycle. In other words, if
an earlier effect chose a higher value, let it win, otherwise use the
value this effect wants.

The
http://deepsymmetry.org/afterglow/doc/afterglow.effects.dimmer.html#var-dimmer-effect[API
documentation] also identifies two optional keyword arguments you can
pass. If `:htp?` passed with a `false`, value this effect will simply
overwrite any previous assignments it finds for the dimmers it is
controlling. Omitting `:htp?` is the same as passing it with a `true`
value. And you can change the
http://deepsymmetry.org/afterglow/doc/afterglow.effects.dimmer.html#var-master[master]
that scales the dimmer value by passing one along with `:master`. If
you do not, the effect will be tied directly to the show's grand
master.

TIP: If you want your dimmer cue to affect only one head of a fixture, you
can pass it just that head, rather than the entire fixture.

For some fixtures, generally those with a single, white light source,
the dimmer is the only thing that determines the amount of light output.
For color-mixing fixtures like RGB LED lights, each color channel has
its own separate brightness level, and then dimmer scales the actual
output of the light, so the final brightness will be a combination of
both. In other words, if the red channel is set to 50% brightness, and
the dimmer is also set to 50% brightness, the final red output will be
at 25% brightness.

In addition to passing in a literal number for the `level` parameter,
you can pass a <<parameters#dynamic-parameters,Dynamic Parameter>>
whose value depends on a <<metronomes#metronomes,Metronome>>, the
physical location or orientation of the head, or a show variable,
perhaps <<mapping_sync#mapping-a-control-to-a-variable,bound>> to a
MIDI control surface. It often makes sense to use
<<parameters#oscillated-parameters,oscillated parameters>> with dimmer
cues.

TIP: If you have color effects running for a light and you aren’t seeing
anything, make sure you have a dimmer effect setting the dimmer to some
visible level.

=== Color Effects

One of the most common basic effects you will be using to create the
looks you want is the color effect. To create an effect that will
assign a color to a fixture (which will assign colors to all of the
fixture’s heads), or a single head of a fixture, pass the fixture or
head to
http://deepsymmetry.org/afterglow/doc/afterglow.effects.color.html#var-color-effect[color-effect]:

[source,clojure]
----
(afterglow.effects.color/color-effect name color fixtures)
----

The `name` parameter is intended to help identify the purpose of the
effect, and shows up when examining the created effect. Put something
descriptive in there, or use a helper function like
http://deepsymmetry.org/afterglow/doc/afterglow.examples.html#var-global-color-effect[afterglow.examples/global-color-effect]
which builds the effect for you, figuring out a reasonable name in
many cases.

The `color` parameter is where you specify the color to assign to the
lights. It should be a color object returned by one of the factories
in the https://github.com/jolby/colors[jolby/colors] library, as
described in <<color#working-with-color,Working with Color>>.

In addition to passing in a color for the `color` parameter,
you can pass a <<parameters#dynamic-parameters,Dynamic Parameter>>
whose value depends on a <<metronomes#metronomes,Metronome>>, the
physical location or orientation of the head, or a show variable,
perhaps <<mapping_sync#mapping-a-control-to-a-variable,bound>> to a
MIDI control surface. The flexibility offered by
<<parameters#color-parameters,dynamic color parameters>> is huge,
especially when combined with
<<parameters#oscillated-parameters,oscillated parameters>>. Learning
how to effectively leverage these in combination with each other will
enable you to create most of the basic lighting looks you need.

The following code creates a effect that assigns a pure red color to
all fixtures with RGB channels, then adds it to the current show under
the keyword `:color`:

[source,clojure]
----
(show/add-effect! :color (afterglow.effects.color/color-effect
                          "Plain red" (create-color "red") (show/all-fixtures)))
----

TIP: Remember that if aren’t seeing anything when you have assigned color
effects to a fixture to make sure you also have a dimmer effect setting
that fixture’s dimmer to some visible level.

You can also assign colors to lights that use color wheels instead of
RGB mixing by passing a `true` value with the optional keyword
argument `:include-color-wheels?` to `color-effect`. Afterglow will
try to find a color wheel position which is close enough to the
desired color, and if one can be found, tell the light to use it.

=== Direction Effects

Moving-head fixtures can create particularly exciting and dynamic shows.
To create an effect that will tell a fixture or head what direction it
should be pointing, pass the fixture or head to:

[source,clojure]
----
(afterglow.effects.movement/direction-effect name direction fixtures)
----

The `name` parameter is intended to help identify the purpose of the
effect, and shows up when examining the created effect.

The `direction` parameter is where you specify the direction the
lights should be pointing. It is a `javax.vector.Vector3d` pointing in<commit_msg>Examples of two effects working at the same time with different set of fixtures<commit_after>= Effects
<NAME> <<EMAIL>>
:icons: font
:toc:
:toc-placement: preamble

// Set up support for relative links on GitHub; add more conditions
// if you need to support other environments and extensions.
ifdef::env-github[:outfilesuffix: .adoc]

Effects determine what a light or group of lights are doing at a given
moment in time.

== Overview

When creating an effect, you assign one or more
<<fixture_definitions#fixture-definitions,Fixtures>> to it, and it
will generate control values for only those fixtures. The fixture
channels affected by the effect depend on the kind of effect it is,
and are grouped into several primary categories. The simplest kinds of
effects apply to a single channel per fixture, or perhaps per head, if
the fixture has multiple independent light-emitting heads. A very
common single-channel effect is the <<dimmer-effects,dimmer effect>>.

Many effects assign <<color-effects,colors>> to lights, which often
involves multiple channels. RGB fixtures will use three channels, one
each for the red, green, and blue levels which make up the color. Some
fixtures add other LED colors, such as amber, white, and even
ultraviolet. Other fixtures simply use a rotating color wheel to pick
from a fixed set of colors, using a single channel. Regardless of how
the color is finally produced, at most stages of effect processing,
Afterglow works in terms of the
<<working_with_color#working-with-color,color itself>>, allowing you
to blend, lighten, darken, shift hue, and the like so you can produce
interesting looks, without regard to details of fixture
implementation. It is only at the
<<rendering_loop#the-rendering-loop,final rendering stage>> that the
color is broken down into channel assignments.

Another important category of effects control the
<<direction-effects,direction>> of moving-head fixtures. These work in
terms of a desired 3D direction vector or <<aim-effects,target point>>
with respect to the <<show_space#show-space,show frame of reference>>,
and at the last stage of rendering, convert that to pan and tilt
channel values, with reference to the angle at which the fixture has
actually been hung.

You can also conveniently use features which are shared by a number of
fixtures, or completely unique to a single fixture, through
<<function-effects,function effects>>, or drop right down to the
level of individual DMX channel values with
<<channel-effects,channel effects>>.

Finally, Afterglow includes some examples of how to build up
<<complex-effects,special-purpose effects>>, which can be fun in
themselves, and also serve as templates and inspiration for whole new
kinds of effects you create on your own.

== Effect Types

Effects in afterglow are divided by the aspect of a light that they
control. Not all fixtures have features which allow them to
participate in all kinds of effects. Afterglow effects will
simply ignore fixtures which are unable to reapond to them.

=== Dimmer Effects

Dimmer effects set the basic brightness level of a fixture. To create
an effect that will set the dimmer level of a fixture, use:

[source,clojure]
----
(afterglow.effects.dimmer/dimmer-effect level fixtures)
----

This effect finds all the dimmer channels associated with the
specified fixtures (there may be multiple, if the fixture has more
than one light-emitting head), and assigns them a level. 0 is off, 255
is maximum brightness. Dimmer effects can work with either fully
dedicated dimmer channels (in which case the channel itself has a
`:type` of `:dimmer`, and the entire DMX range is used for dimming),
or multipurpose channels in which a subset of the DMX range is
assigned to a function of type `:dimmer`, and the channel `:type` is
something else.

If `htp?` is true, uses highest-takes-precedence rules when replacing
any earlier or lower-priority effects which attempted to set this
particular dimmer in the current rendering cycle. In other words, if
an earlier effect chose a higher value, let it win, otherwise use the
value this effect wants.

The
http://deepsymmetry.org/afterglow/doc/afterglow.effects.dimmer.html#var-dimmer-effect[API
documentation] also identifies two optional keyword arguments you can
pass. If `:htp?` passed with a `false`, value this effect will simply
overwrite any previous assignments it finds for the dimmers it is
controlling. Omitting `:htp?` is the same as passing it with a `true`
value. And you can change the
http://deepsymmetry.org/afterglow/doc/afterglow.effects.dimmer.html#var-master[master]
that scales the dimmer value by passing one along with `:master`. If
you do not, the effect will be tied directly to the show's grand
master.

TIP: If you want your dimmer cue to affect only one head of a fixture, you
can pass it just that head, rather than the entire fixture.

For some fixtures, generally those with a single, white light source,
the dimmer is the only thing that determines the amount of light output.
For color-mixing fixtures like RGB LED lights, each color channel has
its own separate brightness level, and then dimmer scales the actual
output of the light, so the final brightness will be a combination of
both. In other words, if the red channel is set to 50% brightness, and
the dimmer is also set to 50% brightness, the final red output will be
at 25% brightness.

In addition to passing in a literal number for the `level` parameter,
you can pass a <<parameters#dynamic-parameters,Dynamic Parameter>>
whose value depends on a <<metronomes#metronomes,Metronome>>, the
physical location or orientation of the head, or a show variable,
perhaps <<mapping_sync#mapping-a-control-to-a-variable,bound>> to a
MIDI control surface. It often makes sense to use
<<parameters#oscillated-parameters,oscillated parameters>> with dimmer
cues.

TIP: If you have color effects running for a light and you aren’t seeing
anything, make sure you have a dimmer effect setting the dimmer to some
visible level.

=== Color Effects

One of the most common basic effects you will be using to create the
looks you want is the color effect. To create an effect that will
assign a color to a fixture (which will assign colors to all of the
fixture’s heads), or a single head of a fixture, pass the fixture or
head to
http://deepsymmetry.org/afterglow/doc/afterglow.effects.color.html#var-color-effect[color-effect]:

[source,clojure]
----
(afterglow.effects.color/color-effect name color fixtures)
----

The `name` parameter is intended to help identify the purpose of the
effect, and shows up when examining the created effect. Put something
descriptive in there, or use a helper function like
http://deepsymmetry.org/afterglow/doc/afterglow.examples.html#var-global-color-effect[afterglow.examples/global-color-effect]
which builds the effect for you, figuring out a reasonable name in
many cases.

The `color` parameter is where you specify the color to assign to the
lights. It should be a color object returned by one of the factories
in the https://github.com/jolby/colors[jolby/colors] library, as
described in <<color#working-with-color,Working with Color>>.

In addition to passing in a color for the `color` parameter,
you can pass a <<parameters#dynamic-parameters,Dynamic Parameter>>
whose value depends on a <<metronomes#metronomes,Metronome>>, the
physical location or orientation of the head, or a show variable,
perhaps <<mapping_sync#mapping-a-control-to-a-variable,bound>> to a
MIDI control surface. The flexibility offered by
<<parameters#color-parameters,dynamic color parameters>> is huge,
especially when combined with
<<parameters#oscillated-parameters,oscillated parameters>>. Learning
how to effectively leverage these in combination with each other will
enable you to create most of the basic lighting looks you need.

The following code creates a effect that assigns a pure red color to
all fixtures with RGB channels, then adds it to the current show under
the keyword `:color`:

[source,clojure]
----
(show/add-effect! :color (afterglow.effects.color/color-effect
                          "Plain red" (create-color "red") (show/all-fixtures)))
----

TIP: Remember that if aren’t seeing anything when you have assigned color
effects to a fixture to make sure you also have a dimmer effect setting
that fixture’s dimmer to some visible level.

You can also assign colors to lights that use color wheels instead of
RGB mixing by passing a `true` value with the optional keyword
argument `:include-color-wheels?` to `color-effect`. Afterglow will
try to find a color wheel position which is close enough to the
desired color, and if one can be found, tell the light to use it.

You can assign different color effects to different set of fixtures.
Following example will assign red color on odd fixtures and blue color on
even fixtures. You need to use this code inside cue or use `end-effect!`.

[source,clojure]
----
(show/add-effect! :color (afterglow.effects/scene "Different colors"
  (afterglow.effects.color/color-effect
    "Plain red" (create-color "red") (show/fixtures-named "odd"))
  (afterglow.effects.color/color-effect
    "Plain Blue" (create-color "blue") (show/fixtures-named "even"))
  ))
----

To achieve the same effect inside a cue:

[source,clojure]
----
(ct/set-cue! (:cue-grid *show*) 0 17
  (cues/cue :color  (fn [_] (afterglow.effects/scene
    "Blue and red 2"
      (afterglow.effects.color/color-effect
        "Plain red" (create-color "red") (show/fixtures-named "odd"))
      (afterglow.effects.color/color-effect
        "Plain Blue" (create-color "blue") (show/fixtures-named "even"))
  ))))
----

=== Direction Effects

Moving-head fixtures can create particularly exciting and dynamic shows.
To create an effect that will tell a fixture or head what direction it
should be pointing, pass the fixture or head to:

[source,clojure]
----
(afterglow.effects.movement/direction-effect name direction fixtures)
----

The `name` parameter is intended to help identify the purpose of the
effect, and shows up when examining the created effect.

The `direction` parameter is where you specify the direction the
lights should be pointing. It is a `javax.vector.Vector3d` pointing in
{'fraction_non_alphanumeric': 0.06569605926535652, 'fraction_numerical': 0.0014404774153719518, 'mean_word_length': 4.665695132614398, 'pattern_counts': {'":': 0, '<': 93, '<?xml version=': 0, '>': 93, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4178287', 'n_tokens_mistral': 5248, 'n_tokens_neox': 4997, 'n_words': 2739}