                             PSYCHO-MOVIE
                             
                   A MIDI Picture Modulator Program and
                      Slideshow for the Atari ST

           Copyright 1994 - MEGASTAR SYNTHESISER COLLECTIVE
                              Version 1.2

Program written and compiled in GFA Basic Version 3.5 by GARETH JONES.

     This program is not in the Public Domain and futher distribution is
prohibited. All material on this disk is copyright. It may not be copied or
altered in any way without the permission of the author.


In the PSYCHO MOVIE folder you should find the following files-

     PSYMOV.PRG - The Main Program.
     PSYMOV.TXT - This document.
     PSYMOV.NEO - Title Screen.
     PSYMOV.AVR - My Mum Sampled and Processed.
   MEGASTAR.AVR - Jingle Sample.
   MEGASTAR.NEO - Intro Picture.
    COLSWAP.PRG - Picture Converter.
       DEMO.MOV - Demonstration Movie File.
       DEMO.MOV - Demonstration Script File.
            PSY - Folder containing several PSYCHO files.

     To run this program you will need an Atari ST working in medium
resolution colour mode, and if using MIDI control an external MIDI controller
preferably with a sequencer function.
    Best results will be obtained if the synthesiser, workstation, or drum -
machine can support 16 MIDI channels. However the program is perfectly happy
to work with a smaller system, even down to a single channel ( in NOTE mode ).



ABOUT PSYCHO
************
     A few months ago a coincidence struck me. There are 16 colours used in
the ST's low resolution mode and 16 channels used by MIDI. It seemed natural
to combine them in some way, and this program is the result.
     PSYCHO allows the user to colour-modulate low resolution pictures
on the ST by means of MIDI commands. This allows the MIDI musician with a
hardware sequencer, workstation, or drum-machine to "play" real-time graphics
to accompany the music.
     The program is able to load any standard NEOCHROME or low-res DEGAS
pictures, so many different art packages, fractal generators, CAD's etc.
may be used as source material. PSYCHO is the able to save these pictures
together with the appropriate settings in a special .PSY file for future use.

     Since I wrote the original PSYCHO and PSYCHO-MOVIE I've had many requests
to develop a non MIDI version. This program and the P.D. release PSYCHO-SCRIPT
are the result. All the "rotational" effects can now be operated by an
internal clock. This allows the non-MIDI user to program up their own
psychedelic slideshows.



ABOUT THE PSYCHO-MOVIE
**********************
     PSYCHO-MOVIE allows the user to colour-modulate low resolution colour
pictures and to sequence these effects into a dynamic psychedelic slideshow
which can be controlled by an internal clock or externally by MIDI commands.
Under MIDI control the program programmer is able create a real-time computer
video, synchronised to your MIDI music.
     The program is able to load NEOCHROME and low-res DEGAS colour pictures
and save pictures and various parameters as a PSYCHO (.PSY) file.These
pictures can then have their colour palattes modulated by one of the 31
modulation MODES. These can rotate the colours, switch them on and off in
set sequences, run animations, fade pictures up and down etc.
     PSYCHO-MOVIE runs from a programmable Script which controls the selection
of pictures and effects. The Script consists of 300 SCRIPT LINES each of which
allow the selection of a loaded picture, a picture colour palatte, and the
relative depth and speed of the modulation effects. SCRIPT LINES are selected
and displayed in blocks of ten known as a SCRIPT PAGE.
     SCRIPT LINES can be viewed individualy ( in Manual Mode ) by using the
keys on the keyboard or MIDI Program Changes. Or viewed in sequence using the
two Script Modes. The speed of the sequence being controlled by the internal
or MIDI clock, the display time of each SCRIPT LINE is set by the "Steps"
parameter.
     Once the SCRIPT LINES have been programmed all the PSYCHO and Script
parameters are saved as a SCRIPT file (.SCP) and all the picture data is saved
as a MOVIE file (.MOV). These can be loaded back into program for immediate
playback.


PSYCHO-MOVIE PROGRAM VARIATIONS
*******************************
    PSYCHO-MOVIE can run in 5 different configurations. These correspond to
the different ST memory capacities, and the saving media.

      1/2 Meg  - Is designed for ST's with 1/2 Meg of memory and is capable
                 of holding up to 8 pictures.

         1 Meg - Is for ST's with 1 Meg of memory and is capable of holding
                 up to holding up to 16 pictures.

         2 Meg - Is for 2 Meg ST's and holds 32 pictures. Since the picture
                 data is saved as a single large file, to save any more than
                 20 pictures a Hard Disk must be used

   4 Meg Hard - Is for 4 Meg ST's and Hard Disk saving and loading. The
                 program can hold up to 64 pictures

2-4 Meg Floppy - Is for 4 Meg ST's without Hard Disk and can hold 40 pictures.
                 Here the first 20 pictures and Script data are saved onto one
                 disk. Then the computer will ask the operator to insert a
                 second disk. Then the remaining pictures are then saved. When
                 re-loading insert the first disk, with the first 20 pictures
                 and Script data. Then on prompting, insert the second disk
                 with the remaining picture data.


INSTALLATION
************
    The program decides which configuration to adopt by looking at a
information "INSTALL.INF" file in the same directory as PSYMOV.PRG. Initially
this is set to the 1/2 Meg option. To alter the information file the user
should click the "INSTALL PSYCHO" button from the Main Screen. A dialogue
will appear listing the 5 options. Select the option you wish to install, and
click the "OK" button. A Fileselector will appear, the user should save the
new information file by overwriting the previous "INSTALL.INF". Then next time
the program is run it be automatically set to the required configuration



WARNING FOR MIDI USERS

    Normally during the intro screens the program plays several samples.
However it has been discovered that if any MIDI data, such timing clocks or
Active Sensing messages, are received by the "MIDI IN" socket of the ST, then
the program will freeze up. There are two ways this can be avoided. First of
these is to not switch on any MIDI equipment that is attached to "MIDI IN"
until the main screen appears. Secondly, the user can delete the two sample
files ( MEGASTAR.AVR and PSYMOV.AVR ) from the PSYMOV folder. Don't worry the
program will still operate.



GETTING STARTED
***************
    If you will be running the program on internal clock then double-click
on the PSYMOV.PRG. If you are running the program from a MIDI device, make
sure that the MIDI IN socket of you ST is connected to the MIDI OUT socket of
your controlling instrument. Configure your instrument so that it transmits
MIDI Note data, and Program Changes on MIDI channel 1.Then double-click on the
PSYMOV.PRG icon.
    Once the program has loaded the main screen will displayed. To load the
demo MOVIE file, click the "MOVIE LOAD" button and select the "MOV+SCP" option
from the dialogue box. You then select "DEMO.MOV" from the Fileselector. Once
the files have been loaded the SCRIPT PAGE will be updated. The program will
also be automatically set to the internal clock.
    Now click the "SCRIPT START" button. The program should display a
selection of pictures modulated by various effects at a tempo set by the TEMPO
value. If you have a MIDI controller set the program to "MIDI ON" and click
"SCRIPT START". The speed of the effects in the Movie is under direct control
of the MIDI Clock messages sent by the controller.
    After the MOVIE has finished, you can view each SCRIPT LINE by clicking
the appropriate SCRIPT LINE SELECT column and clicking the "MANUAL" button.
You can now switch between SCRIPT LINES manually using the "a" to "z" keys on
the ST's keyboard, or in MIDI mode, 1 to 128 by Program Change messages. To
return to the Main Screen, just click the mouse.
    You can now experiment with setting different pictures, palattes, and
effects and viewing the results using the "MANUAL" button.



MODULATION MODES
****************
The 31 modulation modes in this program are :-

 No.1 ( CHAN ) CHANNEL. Only available in MIDI mode.
      The colours are switched on and off by MIDI NOTE ON and OFF messages
      i.e. MIDI channel 2 switches colour 2 etc. If limiters are set to
      different values, then the colours between limiters will be rotated by
      the clock.

 No.2 ( NOTE ) MIDI NOTE. Only available in MIDI mode.
      Here the colours are controlled by 16 notes ( c2 to D#3 when Note
      Transpose is set to MIDI note 48 ) of a single MIDI channel set by the
      user. If limiters are set to different values, then the colours between
      limiters will be rotated by the MIDI clock.

 No.3 ( MCLK ) CLOCK.
      In this mode the colours between the colour limiters are cycled by the
      presence of internal or MIDI clocks.

 No.4 ( VELC ) : VELOCITY CHANNEL. Only available in MIDI mode.
      As in CHAN, but the displayed colour depends on the initial
      velocity of the note. If limiters are set to different values, then the
      colours between limiters will be rotated by MIDI clocks.

 No.5 ( VELN ) : VELOCITY NOTE. Only available in MIDI mode.
      As in NOTE, but the final displayed colour is selected by note
      velocity. If limiters are set to different values then the colours
      between the limiters will be rotated by MIDI clocks.

 No.6 ( ANIM ) ANIMATION.
      Displays pictures between the limiters in sequence. Therefore any
      animations are limited to the first 16 pictures.

 No.7 ( NPIC ) NOTE PICTURE. Only available in MIDI mode.
      Allows the the selection of any of the pictures using notes C2, C#2, D2,
      and D#2 etc...( Note Transpose set to MIDI Note 48 ) on MIDI channel set
      by "MIDI EDIT". All pictures displayed retain the colour palatte of the
      the intially displayed picture. This feature can be used to show
      animations of more than 16 pictures long.

 No.8 ( POLR ) POLARISATION.
      Sweeps the colours through all possible values.

 No.9 ( PSWP ) POSITIVE SWEEP.
      "Blacks outs" all the colours between the limiters, then in
      sequence, displays then one at a time

No.10 ( NSWP ) NEGATIVE SWEEP.
      "Blacks out" each colour in turn between the two limiters.

No.11 ( RAND ) RANDOM.
      "Blacks out" all colours between limiters and then displays a
      single randomly selected colour.

No.12 ( RNDC ) RANDOM COLOUR.
      As with RAND but the final colour screen is a random selection
      of those available in the palatte.

No.13 ( STRB ) STROBE.
      Alternates picture with blank screen to get strobe effect.

No.14 ( BSTR ) BACKGROUND STROBE.
      Alternates the background colour between black and white.

No.15 ( BILD ) BUILD.
      "Blacks out" all colours between the limiters, then puts them
      back one by one.

No.16 ( DCAY ) DECAY.
      "Blacks out" one by one, all the colours between the limiters.

No.17 ( RPAL ) ROTATE PALATTES.
      Displays the selected picture with a succession of colour palattes. The
      palattes used are selected from the first 16 available by the limiter
      values. If you are using the 1/2 Meg configuration the limiter values
      must not be greater than 8 or the program may crash.

No.18 ( POL2 ) POLARISATION 2
      A deep and rapid colour modulation.

No.19 ( POL3 ) POLARISATION 3
      A more subtle modulation effect.

No.20 ( RGB. ) RED,GREEN,BLUE.
      Displays in turn, the red, green, and blue elements of the picture
      palatte.

No.21 ( YCM. ) YELLOW,CYAN,MAGENTA.
      Displays in turn, the yellow, cyan and magenta elements of the picture
      palatte.

No.22 ( FD/\ ) FADE UP.
      Wipes out the colours between the two limiters, then gradually fades
      them back up.

No.23 ( FD/ ) FADE UP AND HOLD.
      Wipes out the colours between the two limiters, then gradually fades
      them back up. Then holds them at their maximum brightness.

No.24 ( FD\/ ) FADE DOWN.
      Graudually fades down to black the colours between the two limiters.

No.25 ( FD\_ ) FADE DOWN AND HOLD.
      Graudually fades down to black the colours between the two limiters.
      Then holds those colours at black.

No.26 ( NEGA ) NEGATIVE.
      Alternates the picture between colour-negative and colour-positive.

No.27 ( CSWP ) CONTROLLER SWEEP POSITIVE. Only available in MIDI mode.
      Colours are switched on and off in turn according to the values received
      from an external MIDI controller - MIDI controller No.80 General
      Controller #5. The receiving MIDI channel is set from the MIDI EDIT
      button by the Note Channel value.

No.28 ( CSWN ) CONTROLLER SWEEP NEGATIVE. Only available in MIDI mode.
      "Blacks out" colours in turn according to the value received from the
      MIDI controller.

No.29 ( CBLD ) CONTROLLER BUILD. Only available in MIDI mode.
      Builds colours up one by one as controller values increases, and
      "Blacked out" as values decrease.

No.30 ( CFD/ ) CONTROLLER FADE UP. Only available in MIDI mode.
      The colours between the limiters are switched to Black. Then as the
      controller value increases, the colours are faded up to their standard
      values.

No.31 ( CFD\ ) CONTROLLER FADE DOWN. Only available in MIDI mode.
      As the controller value increases the colours are faded down to black.

NOTE - With Modes 20 - 31 the pictures are displayed in 256 colour resolution
       only.



GUIDE TO SCRIPT FUNCTIONS
*************************

***** PAGE SELECT ( 1, 11, 21, ... ) *****
    This button ( Top left hand button on the Script display ) controls which
of the thrity SCRIPT PAGES are displayed.

***** SCRIPT LINE SELECT ( 1 - 300 ) *****
    Clicking on this column ( on the far left side of the Script display )
highlights the selected SCRIPT LINE. This automatically changes when "PAGE
SELECT" is altered.

***** PICTURE SELECT ( 1 to Picture capacity, blank ) *****
    Using the left and right mouse buttons the operator is able to select from
the Picture Loction, the required picture.

***** PALATTE ( 1 to Picture capacity ) *****
    This allows the choice of any of the palattes that have been loaded
with picture data. Alternatively you can use the "VEIW" method - see VIEW in
the Guide to Buttons.

***** MODE ( CHAN to CFD\ ) *****
    Controls the selection of Modulation Modes to be applied to picture and
palatte.

***** LIMITERS ( 1 to 16 ) *****
    These control the range of most of the Modulation effects. The numbers
correspond directly to the colours in the palatte. With some of the Modulation
Modes ( eg. MCLK ) if the first limiter value is higher than the second the
direction of the effect may be reversed.

***** STEPS ( 1 - 999 ) *****
    When running the Script either from STEP or START, this parameter controls
the number of clocks that each picture is displayed before moving on to the
next SCRIPT LINE.



GUIDE TO BUTTONS
****************

***** VIEW *****
     Clicking on this button will display the picture and palatte of the
currently selected SCRIPT LINE. To see the effect of using another loaded
palatte on the picture, left or right-click on the palatte-bar. To return
to the main screen, move the mouse off the palatte-bar and click. On
returning to the main screen the palatte selected will be automatically up-
dated on the SCRIPT LINE.


***** MANUAL*****
    Select any other SCRIPT LINE on the selected SCRIPT PAGE using MIDI
Program Change messages 1-128 on a MIDI channel set by the "MIDI EDIT" button.
Or if in "MIDI OFF" mode, keys "a" to "z" selects the 26 SCRIPT LINEs starting
at the first SCRIPT LINE on the SCRIPT PAGE. Also ">" and "<" ( "." and "," )
button will move the program forward to the next SCRIPT LINE or back to
previous one .Clicking the mouse will return you to the main screen.


***** SCRIPT STEP *****
    Runs the script from the currently selected SCRIPT LINE. The program will
automatically return to the main screen when the first blank SCRIPT LINE is
reached.


***** SCRIPT START *****
    This runs the script from the first SCRIPT LINE. When the program reaches
the first blank SCRIPT LINE it will loop back to the start. To break this loop
and return to the main screen, click a mouse button.


***** CLEAR PICTURE *****
    Will clear the picture displayed in the currently selected SCRIPT LINE.
Also it will remove the picture and palatte from the corresponding Picture
Location.


***** MIDI ON/OFF *****
    This button allows the operator to switch from External (MIDI) clock to
Internal clock. The speed of the clock is set by the TEMPO button.


***** TEMPO *****
    Sets the rate of the internal clock and thereby the modulation and SCRIPT
speed when the program is set to "MIDI OFF".


***** MIDI EDIT *****
    With this button you can edit the various MIDI parameters used by the
MODULATION MODES. Program Channel ( 1-16 ) sets the receiveing channel of
the program for MIDI Program Change messages, used in changing SCRIPT LINES in
"MANUAL" mode. Note Channel ( 1-16 ) sets the channel for receiving MIDI note
and MIDI controller ( No.80 - general controller #5 ) data.


*** EXIT ***
    Returns you to the desktop.


**** INSTALL MOVIE ****
    From this button you can program which of the 5 media and memory
configurations you want PYSCHO-MOVIE to run in the next time you run the
program. This is cone by saving, via a fileselector, a "INSTALL.INF" file
in the same directory as PSYMOV.PRG.


***** INSERT *****
    Will insert blank SCRIPT LINES into the script. When the button is pressed
a dialogue box will appear. Using the left and right buttons of your mouse set
"Start Loc" and "End Loc" to the required values, and then click the "OK"
button. Then the SCRIPT LINES at "Start Loc" and "End Loc" and all lines
between will be filled with the standard settings. SCRIPT LINES higher than
"End loc" will be shifted up the appropiate number of lines.


***** DELETE *****
    Will delete unwanted SCRIPT LINES from the script. When the button is
pressed a dialogue box will appear. Using the left and right buttons of your
mouse to set "Start Loc" and "End Loc" to the required values. Click the "OK"
button. The SCRIPT LINES between and including "Start Loc" and "End Loc" will
be removed. SCRIPT LINES higher than "End Loc" will be shifted down the
appropiate number of lines.


***** WIPE *****
    This will reset the SCRIPT LINES from "Start Loc" to "End Loc" to the
standard values.


***** COPY *****
    Will copy the SCRIPT LINES between "Start Loc" and "End Loc" to the SCRIPT
LINE selected by the "DESTINATION" value.


** LOAD PICTURE *****
    PSYCHO is able to load four low resolution colour picture formats,
Neochrome, Degas, Degas Elite, and its own PSYCHO ( .PSY ) format. The latter
allows the additional storing of the Modulation Mode, MIDI Channel, MIDI Note
transpose, and the colour limiters.
    Once the button has been pressed a dialogue box will appear showing the
Picture Locations and the names of the currently stored pictures in groups of
eight ( 1-8, 9-16, etc ). You are able to select which group of eight is
currently displayed using the "" button. Select which Location you wish to
load your picture into, and click "OK". A second dialogue box appears, from
which you select the desired picture format. Then select the appropriate file
from the File Selector.


***** SAVE PICTURE *****
    PSYCHO is able to save the data shown in the currently displayed SCRIPT
LINE ( picture, palatte, modulation mode, and the colour limiters, plus MIDI
Channel and MIDI Note Transpose ) as a PSYCHO file, .PSY. Just click the SAVE
Picture button, and enter file name in the File Selector.


***** SAVE MOVIE *****
    PSYCHO is able to save all the loaded pictures and script data as a MOVIE
( .MOV ) and SCRIPT ( .SCP ) file. This can be done seperately or together.
    Click on the SAVE MOVIE file button, and enter the required name in the
File Selector. The program will save all the pictures in the Picture Store one
by one until it reaches a empty Picture Location. Therefore it is important
that NO EMPTY PICTURE LOCATIONS are left between pictures. If you do, the
pictures after the empty location will not be saved. All the pictures are
saved as one large .MOV file, and all the Script data, ( including picture
names ), as a .SCP file.
For differences in saving methods see PSYCHO-MOVIE PROGRAM VARIATIONS earlier
in this document.


***** LOAD MOVIE *****
    This enable the user to load a complete set of pictures and and Script
data that was previously saved as MOVIE and SCRIPT files. Click the LOAD MOVIE
button and pick which of the three file options ( Script, Movie, or Script
and Movie together ). Then select the appropriate name the file selector. The
program will load the MOVie pictures into consecutive Picture Locations.
     If the dual MOV +SCP is selected, the user selects the MOV file they
want to load. Once this is completed the program will search for a
corresponding SCP file. If no file is found the Script remains unaltered
( including picture names ).
     For differences in the loading methods see PSYCHO-MOVIE PROGRAM
VARIATIONS earlier in this document.



SWAPPING PALATTES
*****************
    You may find that when you rotate the colours of some pictures the
effect is not linear, and the colours become jumbled. This because some art
packages have their colours in logical order, colour1, colour2, colour3,etc.
Whereas other packages ( including PSYCHO, NEOCHROME, KOZMIC ) use the colours
in the hardware order, colour1 colour16 colour2, etc.
    To overcome these difficulties I have included a picture converter
program that will automatically convert the colours from logical order to
hardware order. Just load in a Neochrome or low-res Degas picture into the
program, the order of the palatte colours will be swapped immediately, then
pixel by pixel, the picture data will be converted to match.

NOTE! - The COLSWAP program must be run in LOW RESOLUTION.


USING THE MOUSE
***************
All parameters can be altered using either the left or right mouse
buttons. To change a value just position the pointer over the corresponding
button and use the left button to raise ,the right to lower. With switches,
the left button is ON, the right, OFF. This makes PSYCHO a very easy program
to operate.


CLOSING
*******
     If you have any queries or comments about this program please don't
hesitate to write to me at the address below. Any donations, suggestions,
etc. would be gratefully accepted.
     2 January 1994
     Copyright Megastar Synthesiser Collective.

     Write to -
     Mr. G.W. Jones .
     36 Tarn Drive ,
     Creekmoor ,
     Poole ,
     Dorset ,
     BH17 7DQ ,
     Great Britain .

DISCLAIMER - Mr. G.W.Jones and the MEGASTAR SYNTHESISER COLLECTIVE take
absolutely no reponsibilty for any resultant damage to hardware, software,
data, bank balance, or state of mind of anyone running one of their programs.
"NOTHING TO DO WITH US GUV!.

BYE  BYE  !
The Megastar Synthesiser Collective - " I Used to think all Synthesiser
Collectives were the same, until I discovered the Megastars "
