Fledex.Effect.Interface behaviour (fledex v0.7.0)

View Source

This module defines the interface for an LED effect. Effects can be used in Animations. Examples are:

  • Rotation
  • Dimming
  • Randomize
  • Wanishing
  • Blinking
  • etc.

Summary

Types

effect_state_t()

Typical states of an effect or an animation that should be published

Callbacks

apply(leds, count, config, triggers, context)

Applies an effect to the list of LEDs.

enabled?(config)

a standardized interface to check whether the effect is enabled or disabled

Functions

__using__(opts)

By using this Interface you get a lot boilerplate functionality of enabling and disabling the effect for free.

Types

effect_state_t()

@type effect_state_t() :: :start | :middle | :end | :disabled

Typical states of an effect or an animation that should be published

An animation or effect can publish state events that a Fledex.Animation.Coordinator (or anyone who listens to them) can react to. Any atom can be used as an event and animations and effects can create their own, but this list are the most common and re-occuring ones. If possible try to use them.

  • :start: effect will start with the next iteration (and will move into the :progress state).
  • :middle: offen an effect consists of 2 phases (back and forth, wanish and reappear, ...). This event indicates the mid-point.
  • :end: effect has reached it's final state. IF the effect cycles in rounds, the the next step will restart the effect.
  • :disabled: the effect or animation has been disabled

Note

This is not used yet and still very much in flux

Callbacks

apply(leds, count, config, triggers, context)

@callback apply(
  leds :: [Fledex.Color.Types.colorint()],
  count :: non_neg_integer(),
  config :: keyword(),
  triggers :: map(),
  context :: map()
) :: {[Fledex.Color.Types.colorint()], non_neg_integer(), map()}

Applies an effect to the list of LEDs.

Every LED in the list can be modified at will, however, the amount should NOT (but can be as can be seen in the offset effect) be changed. The function takes the following parameters:

  • The leds is a list of colorints representing the different colors
  • The count is the amount of LEDs in the list (to avoid that we have to traverse it unnecessarily)
  • The config are some settings that can be used to configure the effect
  • The triggers map contains all the triggers can that can be used by the effect. It does contain also the extra parameters passed in in previous calls (see below)
  • The context is a map containing information of strip_name, animation_name and effect index.

The function returns

  • a list of LEDs (color integers),
  • the new count of the list (usually it's the same, but does not need to be)
  • and a (potentially modified) triggers map. This allows to retain some state between applying the filter in consecutive calls.

The most simplest effect is the one that simply returns the passed in parameters:

def apply(leds, count, _config, trigggers, _context) do
  {leds, count, triggers}
end

You probably do not want to implement this function, which has a default implementation, but the do_apply/5 version (which takes the same arguments). This way you don't need to explicitly handle the case that the effect is disabled.

enabled?(config)

@callback enabled?(config :: keyword()) :: boolean()

a standardized interface to check whether the effect is enabled or disabled

Functions

__using__(opts)

(macro) 
@spec __using__(keyword()) :: Macro.t()

By using this Interface you get a lot boilerplate functionality of enabling and disabling the effect for free.

The only thing you need to implement is the do_apply/5 function. Both apply/5 and do_apply/5 have a default implementation and can be overwritten.