@database Vect-X.guide
@master Sample-X:/vect-X/doc/Vect-X.guide
@remark Created with Heddley v1.1 (c) Edd Dumbill 1994

@node "Author" "Author of Vect-X"
 Author: Sheun Olatunbosun
 email: sheun@soi.city.ac.uk


@{i}My other MIDI Software@{ui}

  @{fg shine}Sample-X@{fg text}: A powerful MIDI driven sample player (AHI based)
   @{fg shine} Vect-X@{fg text}: A cool arpeggiator indispensable to every MIDI Amiga user :-)
@endnode

@node "Main" "Welcome page for Vect-X"

                               @{fg shine}Vect-X@{fg text}
                             Version 1.0

                       A MIDI Vector Controller
                            for the Amiga

                           © Copyright 1997
                          Sheun  Olatunbosun

                              CONTENTS

                        @{" Introduction        " link "Reason" 0}
                        @{" Features            " link "Features" 0}
                        @{" System Requirements " link "SystemReq" 0}
                        @{" Getting Started     " link "GetStart" 0}
                        @{" Screen Layout       " link "VXWindow" 0}
                        @{" Acknowledgements    " link "Thanks" 0}
                        @{" Register            " link "Register" 0}
                        @{" Bug report          " link "BugR" 0}
                        @{" Copyright           " link "Copyright" 0}
                        @{" Distribution        " link "Distr" 0}
                        @{" Disclaimer          " link "Disclaim" 0}

                              --------
@endnode

@node "Disclaim" "Disclaimer"

                             NO WARRANTY
                             -----------

 The author cannot be held responsible for any loss of data or damage
 occurring directly or indirectly from use of this program. The user
 understands this declaration before using this program on his or her
 computer system.
@endnode

@node "Reason" "The motive behind Sample-X"
@{fg shine}Vect-X@{fg text} is a simple MIDI tool which allows cross-modulation of four sounds
playing through a MIDI device.

Well, I got fed up of being limited to layering just two sounds. I wanted a
huge sound over which I could express a lot of control. Hence Vect-X was born.
I could say I was inspired by the Yamaha SY35 or the Korg WaveStation
keyboards with their miniature joysticks, but I've never played any of them.
Anyway, I do like the new sounds coming out of my TG300 now that Vect-X is
hooked up!!!

Bye

        Sheun Olatunbosun 11-11-97
@endnode

@node "Register" "Register"
Okay, there's nothing for you here. The program is absolutely free. Once
again, send @{"me" link "Author" 0} some email. I'm just interested in getting some feedback from
you Amiga musicians out there. So what are you waiting for?
@endnode

@node "SystemReq" "System requirements"
@{fg shine}Vect-X@{fg text} requires @{b}Workbench 2.04+@{ub} and a @{b}MIDI interface@{ub}. You'll also need an a
MIDI instrument. Any tone generator or synth will do, although you'll get more
mileage out of one which is at least 4 part multitimbral.


The @{b}midi.library@{ub} is also required.
@endnode

@node "Features" "Features"
@{b}Vect-X@{ub} has the following features


   - 4 vectors (or MIDI channels) in operation
   - Configurable vector to MIDI channel
   - Variable modulation parameter (ie volume, pan, reverb)
   - Intuitive joystick action
   - Clear GUI feedback
   - Retargettable MIDI ports
@endnode

@node "GetStart" "Getting Started"
Run the installation script which simply copies the "newtopaz" font to your
FONTS directory (this font is so much nicer than the default Workbench one).

You can start@{b} Vect-X@{ub} from the CLI by entering 'Vect-X' or double clicking on
its icon from Workbench. Vect-X will then attempt to open on an available
public screen, This is typically the Workbench screen. You are greeted by one
window entitled 'Vector Control'.

@{i}If Vect-X fails to start then make sure that you have the midi.library
installed in the LIBS: directory and the newtopaz font in the FONTS:@{ui}

Hook up your MIDI equipment and configure it so that you have four different
sounds playing on channels 1 to 4. Use sounds with long sustains such as pads,
strings and organs to hear the effect of Vect-X in this simple demonstration.
Now, try holding down a few notes on your keyboard/synth... and at the same
time move around the Vect-X joystick which appears as a square inside the
diamond shape. Four the four sounds, you should hear a morphing effect which
varies according to the joystick's position.

That's it! But it sounds great hey :-)

Right, all that remains is to explain the meaning of the various features in
the @{"vector control" link "VXWindow" 0} window. Check out the sample I created with my TG300 synth.
It took me seconds to create it. 

Happy morphing.


@{fg shine}HINTS@{fg text}

Try working first with just two sounds to see how they interact. Then add the
third and fourth sounds. Getting something useful by throwing four sounds
together from scratch can be a hit-or-miss affair.

Use, use, use those FX! You can get some really monstrous stuff with some
delay, reverb or chorus thrown in. Your GM tone generator will never sound the
same again.

Hook up a sequencer to play note loops (or manually play them yourself if
you're that way inclined). Now you can use percussive sounds which will
constantly be heard because they are continuously retriggered. In fact, you
could use a sequencer to record joystick movements as well. Look! No hands!!

Modulation doesn't have to be volume change. Try using control numbers of 10
(panning), 91 (reverb), or 93 (chorus) for completely off-the-wall sounds.
Check your user manual for other control numbers to manipulate filter
settings, LFO's and amplitude envelopes.
@endnode

@node "VXWindow" "The appearance of Vect-X"
@{fg shine}JOYSTICK@{fg text}

The diamond area containing the small square represents the joystick. This is
the main focus of Vect-X. Move the joystick around to hear how it affects
sounds played through 4 MIDI channels.

@{b}X-Y Talk@{ub}

This ticked button causes Vect-X to act in two different modes.

With no tick present, horizontal and vertical movements are independent.
Forcing one vector to have a high value will cause one other vector to have a
low value and leave the remaining two unaffected. The audible result is that
three sounds can usually be heard. This setting is useful for subtle
modulation.

With the tick present, horizontal and vertical movements are linked. Forcing
one vector high causes the other three to go low. This happens when the
joystick is moved to one of the diamond corners and the audible result is that
one vector's sound can be heard in isolation. This setting can therefore
introduce strong modulation.

@{b}Ctrl #@{ub}

This box specifies which MIDI controller value to change on the four MIDI
channels. By default it is set to 7 which corresponds to volume. A value of 10
would cause the joystick to affect the panning position of played sounds.
Please consult your keyboard manual or a standard MIDI book to find out about
other controller values.

@{b}MIDI in@{ub}

Vect-X by default takes its input from the Amiga serial port. However
specifying the name of another port allows its MIDI input to come from another
program such as a sequencer.

Vect-X requires a MIDI input port so that it can duplicate a note played on
one MIDI channel to the other three MIDI channels. It also duplicates other
data such as pitch-bend. 

@{b}MIDI out@{ub}

By default, Vect-X sends its output to the Amiga serial port. However
specifying the name of another port allows its MIDI output, including the
joystick information, to go to another program. This is incredibly handy for
recording joystick movements in a sequencer.

@{fg shine}VECTORS@{fg text}

@{b}Sliders@{ub}

These sliders reflect the @{i}magnitude values@{ui} of the 4 vectors. They are for
display purposes only and they cannot be changed. Anyway, simultaneous
manipulation all oft hem is achieved via the joystick.

@{b}Vector channels & MIDI chan@{ub}

The radio buttons (the stacked circular buttons) under the sliders indicate
the currently selected vector. When another vector is selected, the @{fg shine} MIDI chan@{fg text}
buttons will update to show which MIDI channel is linked to that particular
vector. You alter a vector's MIDI channel by selecting another @{fg shine}MIDI Chan@{fg text} radio
button. If you select a MIDI channel which is already in use by another
vector, then you will not see any update.
@endnode

@node "Glossary" "Glossary"
Some important terms appearing in documentation.

@{b}MIDI@{ub}

Musical Instrument Digital Interface. A protocol used between hardware units
for the transfer of notes and other messages relating to musical information.


@{b}MIDI channel@{ub}

This is one of the sixteen lines on which notes can be transmitted. Each line
has a note span of 128 notes or different pitches and each one has its own
parameters such as volume, panning and pitch-bend. This permits an arrangement
where each channel can trigger a different musical instrument.
@endnode

@node "Thanks" "Acknowledgements"
A sincere thank you goes from me to the following people whose tools have
helped to spur productivity in the Amiga development community.

 @{b}Edd Dumbill@{ub}
 The author of the AmigaGuide editor which has made it easier for me to
 enter this documentation.

 @{b}Michael Sinz@{ub}
 For the excellent (do not code at home without it!) Enforcer tool

 @{b}Matt Dillon@{ub}
 For the DICE compiler.

 @{b}Jan van den Baard@{ub}
 Whose GadToolsBox program was at the heart of the Vect-X GUI creation.

 @{b}Bill Barton@{ub}
 For the midi.library. Saved me the headache of interpreting MIDI messages
 on the serial line.
@endnode

@node "BugR" "Bug Report"
Well I think @{b}Vect-X@{ub} is perfect :-) Nah seriously though, if you think you've
found a bug then let me know so that I can look into it straight away. Please
help me when reporting the bugs by stating the exact procedure of how you
caused them to appear. This will help me immensely in determining how the bug
occurred.

I can be contacted through

    email: sheun@soi.city.ac.uk


@{b}Known bugs@{ub}

None.
@endnode

@node "Copyright" "Copyright"


    @{b}Vect-X@{ub} is the copyright © 1997 of Sheun Olatunbosun.
@endnode

@node "Distr" "Distribution"
This software is freeware and it may be freely distributed so long as the
archive continues to hold the files in @{b}listing.doc@{ub}. Charging for the software
should not be significantly more than the cost incurred from distributing the
media. The author grants the right for @{b}Vect-X@{ub} to appear on a magazine cover
(floppy) disk or any compact disc collection with the premise being that he is
notified of such action.

@{b}Vect-X@{ub} remains the copyright © 1997 of Sheun Olatunbosun
@endnode