The display and music should always be doing something, even when nothing really important is happening. Thus, these effect modules implement background effects, a way to determine what to do in these circumstances. Lamp effects do not support a background mode; it is OK for no effect to be running, as the lamps have a default state that shows through.
The strategy for handling background effects is as follows: When
there is no explicitly started effect, an event is generated:
either display_update or music_refresh. Any module that can
provide a background effect should implement these handlers.
The handler can decide which effect, if any, it wants to provide by
calling either deff_start_bg or music_request. (If the
conditions are not correct, it can simply return without doing anything,
as with a mode that is not running.) The handler request includes
the ID for the deff or music to be started, plus a priority value. After all of the
event handlers have been invoked, the one with the highest priority
wins and will be started.
The common code provides many of the implementations to deal with the usual cases. For example, while a game is running, the default effect is to show the game scores. Default music codes can be defined for different circumstances: normal game play, ball at plunger, during bonus.
Because handlers can use the values of other variables in the
determination (are we in game, for example?), the calculations need to
be redone periodically, in case the conditions change. To force a refresh
of both the display and music,
call effect_update_request. The update will take place within the next
100ms; the delay is intended to smooth out multiple such requests within
a short time, and the delay is not really noticeable.
When a foreground display or music effect exits, an update will take place immediately. In this case, if display update is needed, then music is not updated, and vice-versa.
If an update is not requested, the display and music will still be refreshed
periodically by the system, about twice per second, as the conditions checked
within the handlers may have changed. Because of this, effect_update_request
is really an optional call, and only forces the update to happen faster.