SLIGHT HOWTO

This file will walk you through creating a very simple show, get you
familiar with the patch panel, the process of recording cues, etc.
You really, really, REALLY should at least read this file, because the
interface is not as ... transparent ... as it could be.  And there's no
feature manual; this is it.  Sorry.

1)  Get the dmx4linux dummy driver working.
    At a prompt, as root, 
    $ insmod dmxdev 
    $ insmod dmxdummy
     
2)  Start the dmx4linux display so you can see the effects of what you're
    doing.  Go into the dmx4linux-2.2/X/Display and run
    $ ./dmxdisplay

    Alternately, if you didn't build the X11 tools (you should have!),
    enter dmx4linux-2.2/tools and run
    $ ./dmxconsole

3)  Start SLight.  Assuming it's in your path, run
    $ slight

    If you get a DMX error, you don't have dmx4linux installed and working.
    Check the dmx4linux documentation, that's something I can't help you with.
    (Make sure you've got a /dev/dmx node, for one thing.)

    If you recieve a message that SLight needs to be run SUID root, you 
    havn't installed this according to the INSTALL file.  Please read that;
    if you insist that you don't need it, make sure you've read the README
    so you know what the consequences are.

4)  SLight starts with 24 output *channels* (DMX channels, should be equal
    to the number of sockets or dimmers you can plug lights into).  Each
    is mapped to its own *fader*, the actual SLight object for which
    you can set levels, etc.  You can assign multiple channels to one
    fader (but not vice versa); for example, if you have four frenels
    providing a blue wash, you could assign them all to fader 1 and
    be able to set all their levels simultaneously.

    Let's alter the channel/fader mapping.  Under the Edit menu, select
    "Patch Panel...".  On the left, in spinboxes, one can set the desired
    number of channels and faders.  Set "Faders" to 4 and "Channels" to 6.

    Select fader 1 from the big list box.  The smaller list box to the
    lower right shows which channels are assigned to that fader.  In
    addition to channel 1, which is already selected, select 2 and 3.
    Note how they are automatically removed from faders 2 and 3.

    Now, press the "One-to-one" button.  Note how not only are the faders
    1 through 4 assigned channels 1 through 4, faders 5 and 6 are created
    automatically and assigned their own channels.  The "One-to-one" button
    sets the number of faders to the number of channels, then assignes
    each channel its own fader.

    Move the number of faders back to four.  Assign channels 5 and 6
    to fader 4, then press OK to return to the main program.

5)  Let's write a cue.  Select channel 1 by clicking the one with a zero
    below it with the mouse.  Note that it turns red.  One can also select
    multiple channels by dragging the mouse over them or by holding Ctrl
    and clicking or dragging.  Select channel 3 as well.

    Type "100" on the keyboard to set the faders' levels.  HIT ENTER.  If you
    do not hit enter, the changes never take effect; you ALWAYS must press
    Enter whenever you change a fader's level, either in blind while writing
    a cue or in live.  You'll note that the faders' levels change to RED
    to indicate that they are changed.

6)  Press the "Record New Cue" button, the white sheet with the red circle
    on it.  The form you are presented with is the Edit Cue form.  Name the 
    cue "One" and give it the number 1.  Press OK.  Note how the cue has been
    added to the cue list, and when you select it the levels show up in the 
    fader panel.  Double-clicking on the cue brings you back to the Edit Cue 
    dialog.

7)  Select the blackout cue.  Now, press "+" key, followed by "2" and "*".
    Note how fader 2 is selected: one can select faders from the keyboard
    by pressing "+" and a number, or deselect them by pressing "-" and a
    number.  Ranges are selected by entering a fader number, a "/" and another
    fader number.  Pressing "*" returns you to level input mode.  For example:
    Pressing " + 1 / 4 - 2 * 100 <enter> " selects faders 1 thru 4, excluding
    2, and sets them at 100.  Try it!

    Wait a minute.  We were just interested in fader 2.  Assuming you followed
    the above, 1, 3 and 4 are set at 100 and 2 is still at 0.  Press "Esc"
    to undo changes to the current cue you have not recorded.  Also, if
    you move to another cue, these changes will be lost.  They will only
    be saved if you record the cue.

    Using the keyboard, select cue 2 and set its level to 100.  Press
    the "n" key; this also records a new cue.  Give the cue a name, a number 
    and a fade time.  NOTE:  SLight does not enforce any type of ordering or
    numbering scheme (other than floating point!), they're there for your 
    information only.  Note how the new cue is inserted AFTER THE SELECTED
    CUE.

8)  Select the first cue you wrote, now the 3rd in the list.  Note how 
    faders 1 and 3 are green, while channel 2 is purple.  This indicates
    how the faders' levels have changed:  green is UP, blue is DOWN, and
    purple is NO CHANGE.

9)  Let's run the cues!  Select the LIVE button on the toolbar: note how
    the selection disappears.  The BOLD cue is the one that you're currently
    at.

    Press the spacebar.  Watch in dmxdisp how channel 2 fades to 100 over
    the timeperiod you specified, and the fader 2 continually shows the
    status over the point of the fade.  Press space again to fade to
    bring up faders 1 and 3.

10) Double-click the second cue.  Note how the channel/fader levels are 
    set immediately: you can jump to a cue in LIVE mode by double-clicking
    it.

11) "AARG!  Channel 2 is too high!" your director shouts.  While still
    in LIVE, select fader 2 (either with the mouse or keyboard) and give it a 
    level of 80.  (Don't forget to press ENTER!!)  Note how the level 
    changes immediately, both on dmxdisp and on the fader display.  To make 
    the change permanent, press the Record button (the large red circle on the
    toolbar) or the "r" key.  This level will be saved to your cue list.

12) Double-click on the Blackout cue, then return to BLIND.  Lets assume the
    first two light cues for this show don't depend on the vagaries of actors;
    they can be automated.  Double-click on the second cue; set a fade time of
    5, then enable "Follow Time".  Set a follow time of 10 and press OK.

    Return to live mode.  Make sure the Blackout cue is current, then
    press Space.  Note how the second cue fades in over 5 seconds, and then
    5 seconds later the third cue starts fading.  IMPORTANT NOTE: the follow
    timer starts WHEN THE PREVIOUS CUE STARTS, NOT when it finishes.  This
    allows you to have MULTIPLE cues running at once, eg to fade down
    one set of lights and start fading up other 2 seconds later, but have
    them finish at the same time.  You don't have to specify a "split cue"
    or anything, just write two cues with a follow.

13) Let's reemphasize that last point.  Select the blackout cue.  Press the
    spacebar, then 2 seconds later, press it again.  Note how BOTH cues
    turn red; they're both running.  They can be started (and will be
    stopped) independently of one another.  The only deviation from this
    is if the second cue you start affects faders that are already being
    faded by the first cue:  the second one "takes control" of them; they
    will fade from where they were when the second cue started to the level
    the second cue specifies.

14) Make the blackout cue current, then return to BLIND.  Double-click on
    the second cue and remove the follow time.  Select the third cue and 
    set channel 2 to 0; (press enter, then) press Record; then double-click 
    on it.  This time, enable "Jump to...".  This allows one to jump 
    forward or backward in the cue list when you hit the Space bar and 
    can be used for loops.  Select "3 times" from the spin box, and your 
    second cue from the drop-down combo box.  (You did give it a unique 
    name, right?  If not, it should just be the second one.)

15) Return to LIVE.  Fade to the second cue, then the third.  Hit the space-
    bar again to fade back to the second cue.

    WAIT!  Faders 1 and 3 didn't go back to 0!  Why is that?  If you've
    used Horizon, you know the "feature" is called tracking: the levels
    stay set unless you explicitly change them.  When you press space
    again, fader 2 returns to 0 but 1 and 3 remain at 100.

14) Let's fix this.  Go to the blackout cue, then return to BLIND.
    Select the second cue; note how the fader number "2" is highlighted,
    while the rest are gray: only fader 2 was recorded in this cue.
    Select the first and third faders; press Enter, then Record.  Note how
    they are now highlighted; you don't have to change levels in a cue to
    record them!

    Change back to LIVE and verify that the cues function as they should.
    After looping twice, hit the "Reset" button just to the right of
    the LIVE button.  Note how SLight jumps to the Blackout cue and
    resets the Jump To... counts.  You should probably reset before
    running a show, just to make sure.

15) While we're on the subject of channels recorded, return to BLIND.
    Select the third cue, then set fader 4 (previously unused) to 50 and
    record a new cue.  Before hitting OK, change the radio buttons at the
    bottom from "Record changed levels" to "Record all levels."  Hit OK,
    and note how ALL the levels were recorded for this cue, not just
    the changed ones.

    The recommended use of this feature is as follows: for major scene 
    changes, record ALL levels; for intra-scene changes, just record the
    changed levels.  This ensures that if you have to make an emergency 
    change in the middle of the show, (eg bring up specials because the 
    follow spot isn't working), they won't track through the rest of the 
    show.  If you want tracking behaviour, make sure NOT to record all 
    the levels.  It's your choice.  


Well.  You survived the tutorial: this was a crash course for SLight features.
The only one we didn't cover was the "%" symbol on the toolbar: this changes
the display from percent of full to the actual DMX value 0-255.  Otherwise,
the cut/copy/paste/delete features behave as expected.  (I think.)

You should be well-prepared to actually use this thing now.  If there are
further questions, you are NOW authorized to email me.  Or figure it out,
update the documentation, and send me a diff!

Thanks!
Brian Teague
bteague@rice.edu
SLight creator
