afterglow.effects.dimmer
Effects pipeline functions for working with dimmer channels for fixtures and heads. Dimmer effects are always tied to a master chain, which can scale back the maximum allowable value for that dimmer channel, as a percentage. Unless otherwise specified, the dimmer cue will be attached to the show grand master, but you can create other masters to adjust the brightness of groups of fixtures, perhaps because they are intrinsically brighter, or to adjust the balance of lighting for artistic reasons. Secondary masters can be chained to each other, and are always chained to the show grand master, so turning that down will dim the entire show; setting it to zero will black out the show.
This master scaling capability is so useful that you will almost always want a prominent fader on a MIDI controller tied to the show grand master, and possibly others to secondary masters. show/add-midi-control-to-master-mapping makes that easy, especially for the grand master, and for submasters stored in show variables, which can be referred to by their keywords.
Some fixtures have damping functions that slow down their dimmer response, so you may not get the kind of coordination you would like from oscillated dimmer cues. A potential workaround is to use the dimmer channels as a maximum brightness level to allow tweaking the overall brightness of an effect, and using the lightness attribute of a color cue to create time-varying brightness effects.
dimmer-effect
(dimmer-effect level fixtures & {:keys [htp? master effect-name add-virtual-dimmers?], :or {htp? true, master (:grand-master *show*)}})Returns an effect which assigns a dynamic value to all the supplied dimmers. If a true value is passed for :htp?, applies highest-takes-precedence (i.e. compares the value to the previous assignment for the channel, and lets the highest value remain).
All dimmer cues are associated with a master chain which can scale down the values to which they are set. If none is supplied when creating the dimmer cue, the show’s grand master is used.
Dimmers are either a channel fully dedicated to dimming, identified by the channel :type of :dimmer, or a dimmer function range defined over only part of a multi-purpose channel, where the function :type is :dimmer, and the channel :type must be something else. A single head cannot have both types of dimmer, since a function can only exist on one channel in a given head.
If you have any fixtures that are capable of RGB color mixing, but lack dedicated dimmer channels, you can have this effect simulate a dimmer channel for those fixtures by passing a true value with add-virtual-dimmers?. The virtual dimmer works by modifying any color effect that has already run for those fixtures, to reduce the brightness of the color being assigned. To do that, this dimmer effect needs to run at a higher effect priority than any color effect you want it to modify, so be sure to add it to your show with an appropriate priority value. Virtual dimmers are incompatible with hightest-takes-precedence dimming, because there is no actual previous dimmer value for them to work with, so you cannot use both htp? and add-virtual-dimmers at the same time.
gather-dimmer-channels
(gather-dimmer-channels fixtures)Finds all channels in the supplied fixture list which are dimmers, even if they are inside heads.
gather-no-dimmer-rgb-heads
(gather-no-dimmer-rgb-heads fixtures)Finds all the RGB heads from the supplied fixture list which have no dimmer capability at either the head or fixture level. These heads are suitable for creating virtual dimmer effects when desired.
gather-partial-dimmer-function-heads
(gather-partial-dimmer-function-heads fixtures)Find all heads in the supplied fixture list which contain multipurpose channels that are partially used for dimming, rather than full dedicated dimmer channels.
IDimmerMaster
protocol
A chainable limiter of dimmer cues.
members
master-get-level
(master-get-level master)Get the level of this master, as a percentage from 0 to 100. Any value less than 100 will cause the dimmer cues attached to this master to have their levels scaled back by that amount. If there are any parent masters attached to this one, they may further scale back the value in turn.
master-scale
(master-scale master value)Scale down the value being sent to a dimmer according to this master level, and any parent masters associated with it.
master-set-level
(master-set-level master new-level)Set the level of this master, as a percentage from 0 to 100. Any value less than 100 will cause the dimmer cues attached to this master to have their levels scaled back by that amount. If there are any parent masters attached to this one, they may further scale back the value in turn.
master
(master show & {:keys [level parent], :or {level 100, parent (:grand-master show)}})Create a master for scaling dimmer cues. If you set its level to less than 100 (interpreted as a percentage), all dimmer cues created with this master will be scaled back appropriately. If you supply a parent master, it will get a chance to scale them back as well. If you don’t, the show’s grand master is used as the parent master.