These principles apply to all types of effects.
At any time, there is at most 1 effect that is running of each
type. The
running effect is the one which has been started with the
highest priority. Priorities are simple integer values:
the higher the number, the more important the effect is. A list
of predefined priority values is defined in priority.h;
these files begin with PRI and have been carefully defined relative
to one another. Use one of these values when possible.
It is possible for no effect to be running if none has been started. In that case, the current priority is considered to be zero. Actual effects always have a priority that is non-zero.
The running effect is executed in a separate task context, except for
music, which is executed on a separate CPU. The
currently running display effect always has the group ID
GID_DEFF; likewise GID_LEFF for the lamps. Effects
that are started but not running do not have a task assigned to them,
and are simply marked as started in memory somehow. Because they do
not have enough priority to run, there is nothing for them to do.
Effect tasks can be preempted, if a higher priority effect is started later. In that case, the old task is killed, and a new task is started. When the task is killed, there is no guarantee as to what was doing previously, and there is no opportunity for it to do cleanup on its own.
Effect functions must be declared in the machine configuration file. Each entry names the function to be called to run the effect, along with its priority and other optional properties.
The APIs and implementation for display/lamp effects are mostly the same, but there are differences due to the following: