From b102d2403623d515b02eac957690df6a9cbb1e0f Mon Sep 17 00:00:00 2001 From: Thomas White Date: Sat, 16 Jul 2022 09:16:23 +0200 Subject: Update docs --- docs/basic-control.rst | 136 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 docs/basic-control.rst (limited to 'docs/basic-control.rst') diff --git a/docs/basic-control.rst b/docs/basic-control.rst new file mode 100644 index 0000000..f326a5d --- /dev/null +++ b/docs/basic-control.rst @@ -0,0 +1,136 @@ +=========================================== +Basic attribute control and building states +=========================================== + +Once your fixtures are patched (see ``_), you can set attributes +sing ``at``. For example, to set the intensity of ``my-dimmer`` to 100%:: + + (at my-dimmer 'intensity 100) + +If you leave out the attribute name, then ``intensity`` will be assumed:: + + (at my-dimmer 100) + +The available parameters are determined by the fixture definition (see +``_), and are referred to by their symbolic name (i.e. quote +them with ``'``). For example:: + + (at my-moving-light 'pan 32) + (at my-moving-light 'tilt 70) + (at my-moving-light 'zoom 60) + +Not all fixtures accept a single number. For example, ``'colour`` (note: UK +spelling) takes a colour object, which can be constructed using ``rgb`` or +``cmy``. Starlet (or rather, the fixture definition code) is responsible for +converting the colour to the native representation used by the fixture:: + + (at my-moving-light 'colour (rgb 80 23 25)) + +You can set attributes for multiple fixtures at once:: + + (at spotCS spotSR spotSL 90) + +Or you can set attributes for a list of fixtures:: + + (define all-spots (list spotSL spotCS spotSR)) + (at all-spots 90) + +You can mix individual fixtures and lists of fixtures. However, you can only +set one attribute (to one value) at a time. + + +The selection +============= + +When setting many attributes for one fixture, you can avoid typing the +fixture name each time by using the selection. To select a fixture, call +``sel`` with the fixture(s) to select:: + + (sel my-dimmer) + (sel all-spots my-moving-light) + +If the fixture name is left out from subsequent calls to ``at``, they will +apply to the currently selected fixture(s). To clear the selection, simply +call ``(sel #f)`` or simply ``(sel)``:: + + (sel my-moving-light) + (at 100) + (at 'colour (rgb 80 23 25)) + (at 'tilt 70) + (at 'pan 32) + (sel #f) + +The fixture display window (see ``_) will highlight the +selection, and physical control devices (see ``_) will +affect the selected fixture(s). + +To see the contents of the selection, use ``(get-selection)``. + + +State objects +============= + +Attribute values must be stored within a state object. When you set an +attribute from the Guile REPL, the values will be stored in the programmer +state. You can examine the contents using ``state-source``, which returns +the Scheme code corresponding to the state's contents:: + + (state-source programmer-state) + +You can also use ``print-state``, which just pretty-prints the output of +``state-source``. To reduce typing, you can use ``ps`` as a synonym for +``programmer-state``:: + + (print-state ps) + +You can construct new states by wrapping your ``at`` forms inside +``lighting-state``. These state objects can be used inside cue lists +(see ``_), bound to variables etc:: + + (define my-state + (lighting-state + (at spotSR spotSL 50) + (at spotCS 100))) + +The programmer state has priority over everything else (e.g. cue list +playbacks). To avoid surprises, you should make sure that it's empty before +trying to run a show. The ``clear-state!`` procedure empties a state object +of its contents, without deleting the state itself:: + + (clear-state! ps) + +There are some utility routines for handling states: + +* ``(state-empty? my-state)`` returns ``#t`` if ``my-state`` is empty, + otherwise ``#f``. +* ``(remove-fixture-from-state! my-state spotCS)`` removes all attributes for + ``spotCS`` from ``my-state``. +* ``(remove-fixtures-from-state! my-state (list spotCS spotSL))`` is the same, + but removes a list of fixtures from the state. +* ``(remove-selection-from-programmer!)`` removes from the programmer any + attributes referring to fixtures which are currently selected. It is + defined as follows:: + + (define (remove-selection-from-programmer!) + (remove-fixtures-from-state! + programmer-state + (get-selection))) + + +Effects +======= + +Attribute values aren't restricted to constants. You can also provide a +function, for example:: + + (let ((clock (make-clock))) + (at washM + (lambda () + (* 50 + (+ 1 (sin (* 2 (elapsed-time clock)))))))) + +That's obvious quite complicated, so use the functions in module ``(starlet +effects)`` instead. For a sine wave once every 2 seconds (0.5 Hz) ranging +between zero and 100%:: + + (at washM (sinewave 0.5 0 100)) -- cgit v1.2.3