diff options
author | Thomas White <taw@physics.org> | 2022-07-16 09:16:23 +0200 |
---|---|---|
committer | Thomas White <taw@physics.org> | 2022-07-17 16:37:14 +0200 |
commit | b102d2403623d515b02eac957690df6a9cbb1e0f (patch) | |
tree | 61afbebeefae3efa12670dd3540d840c379142c0 /docs/cue-list.rst | |
parent | 8e8a922591f704c5860b0b9a6a728920e960935f (diff) |
Update docs
Diffstat (limited to 'docs/cue-list.rst')
-rw-r--r-- | docs/cue-list.rst | 205 |
1 files changed, 205 insertions, 0 deletions
diff --git a/docs/cue-list.rst b/docs/cue-list.rst new file mode 100644 index 0000000..9a83ca0 --- /dev/null +++ b/docs/cue-list.rst @@ -0,0 +1,205 @@ +======================= +Cue lists and playbacks +======================= + +Anatomy of a cue +================ + +A cue is formed by associating a lighting state with a *transition effect*. +As an example, here is cue 4.3 representing a 4 second crossfade to a dim +lighting wash:: + + (cue 4.3 ;; <---- the cue number + + (lighting-state ;; + (at washL washR 30) ;; lighting state + (at washM 40)) ;; + + (crossfade 4)) ;; <---- transition: 4 second crossfade + +The simplest transition effect is ``(snap)``, which produces a hard zero-time +transition to the cue. The usual one is ``crossfade``, which produces a smooth +fade in the time you specify (in seconds). It gives you a lot of control, for +example, to fade intensities up in 4 seconds but down in 2 seconds:: + + (crossfade 4 2) + +To delay the up fade part by 2 seconds relative to everything else:: + + (crossfade 4 #:up-delay 2) + +To delay the down fade part, use ``#:down-delay``. To control the fade times +for non-intensity parameters, use ``#:attr-time`` and ``#:attr-delay``. +Putting it all together for a complicated crossfade:: + + (crossfade 3 4 + #:up-delay 2 + #:attr-time 1 + #:attr-delay 1.5) + +You can write your own transition effects, if you want some other kind of +transition. Documentation pending, but look at snap-transition.scm and +crossfade.scm for some examples. + + +Cue lists +========== + +A cue list is simply a list of cues. For example:: + + (cue-list + + (cue 0.5 + ;; Tab warmers + (lighting-state + (at washL washR 30) + (at washM 40)) + (snap)) + + (cue 0.8 + ;; Blackout + (lighting-state) + (crossfade 6)) ;; 6 second fade + + (cue 1 + ;; Act 1, Scene 1 + (lighting-state + (at front-wash 80) + (at moverL 'colour (cmy 21 0 0))) + (at moverL 25) + (crossfade 3)) + + (cue 2 + (lighting-state + (at washM 100)) + (crossfade 3 4)) ;; Separate up/down fade times + + (cue 2.5 + (lighting-state + (apply-state home-state) + (at moverR 100)) + (crossfade 2))) + +Just so you know, the cue list is represented internally as a Scheme *vector*, +not a real list. + + +Playback objects +================ + +The cue list doesn't do anything on its own. To actually see the contents on +the stage, it needs to be loaded into a playback. In practice, the best way to +work is to put the cue list in a file on its own and create the playback with +a reference to that file:: + + (define pb + (make-playback + #:cue-list-file "shows/my-show.qlist.scm" + #:recovery-file "recovery.q")) + +The ``#:recovery-file`` is optional but highly recommended, discussed below. + +Once the playback has been created like this, if you change the cue list file +then you can re-load it:: + + scheme@(guile-user)> (reload-cue-list! pb) + $8 = cue-list-reloaded + +If the modifications to the cue list file involved the currently active cue, +the state shown on the stage will *not* be updated until you say so, with:: + + (reassert-current-cue! pb) + +The playback object shows useful information when printed:: + + scheme@(guile-user)> pb + $1 = #<<starlet-playback> state: ready current-cue: 43.0 next-cue: 44.0> + +For completeness, know that you can also create a playback like this:: + + (define my-cue-list + (cue-list + (cue ...))) + + (define pb (make-playback #:cue-list my-cue-list)) + +However, this makes it much harder to make subsequent changes to the cue list. + + +Running cues +============ + +To rapidly jump (with a snap transition) to a cue, use ``cut-to-cue-number!``. +To run a cue using the transition specified in the cue list, use +``run-cue-number!``:: + + (cut-to-cue-number! pb 1) + (run-cue-number! pb 4) + +Calling ``go!`` will run the next cue in the cue list:: + + (go! pb) + +Playbacks also implement the other familiar operations: + +* ``(stop! pb)`` - immediately pause any running cue. The next call to + ``go!`` will continue it. +* ``(cut! pb)`` - run the next cue, using a snap transition regardless of what + the cue specifies. +* ``(back! pb)`` - go backwards one step in the cue list, using a snap + transition. + + +Tracking +======== + +By default, non-intensity parameters will "track" from one cue into the next +cue. That helps to avoid unexpected parameter changes, e.g. a moving light +changing position while it dims. If you run cues *out of order*, the result +will be the same as if you'd run the cues *in order* from the start, to get to +the cue you wanted. If you're lucky enough to have never encountered a system +that works any other way, just know that it works the way you'd expect it to +work in a theatrical system. + +If you additionally want to track *intensities* into a cue, use +``#:track-intensities``:: + + (cue 1 + (lighting-state + (at front-wash 80)) + (crossfade 3)) + + (cue 2 + (lighting-state + (at spotC 100)) + (crossfade 3) + #:track-intensities #t) + +In this example, cue 2 will include ``spotC`` at full intensity, **and** +``front-wash`` at 80% intensity. + + +Fixture presetting ("auto move while dark") +=========================================== + +Starlet tries as hard as it can to get non-intensity parameters into the right +state before running a cue. In other words, it makes a big effort to avoid the +audience seeing moving lights actually move. If a fixture's ``intensity`` +parameter is zero after running a cue, Starlet will set all its non-intensity +parameters to the values in the next cue. Of course, if a non-intensity +parameter changes while the intensity is non-zero, the audience will see the +move! + + +The recovery file +================= + +The purpose of the playback recovery file is to make a rapid recovery after a +crash (not that there will be any, of course!). If the file specified by the +``#:recovery-file`` keyword argument to ``make-playback`` exists when the +playback is created, the playback will immediately jump to the cue number in +the file. Whenever you run (or jump to) a cue, the cue number in the file will +be updated. If you don't use a recovery file, the playback will revert to cue +zero on creation and you'll have to use ``cut-to-cue-number!``. That will +create a blackout of a few seconds while you figure out the right cue number to +pick up from where things went wrong. |