Visual AGI
----------

Version 2002-07-10.

Note: This is a special Sound Resource only version of Visual AGI.


1. BETA INFORMATION
-------------------

This is a beta release of the sound editor that is originally part of the Visual AGI package.
During the beta phase, other functionality will be added as soon as we have the time.

Any saved sound resources will now have larger possibility to load in a future version of 
Visual AGI. The file format has now finally changed into XML.

Please send all feature requests, bug reports (including full dump of your system information)
to me, Joakim Mller, at the following e-mail adress: jmoller@algonet.se

Find more information about Visual AGI at http://visualagi.cjb.net

Please visit http://www.agidev.com and http://agiboard.cjb.net for AGI information.


2. INSTALLATION
---------------

Just run the provided "Visual AGI.exe".

This beta version has been tested on Windows 95(*)/2000/XP.
Please tell me (e-mail above) any success/failure with your operating system.

(*): According to Nick Sonneveld (thanks for testing!), you can make it run on Windows 95 by
downloading the Active Accessibility 1.3 package from Microsoft and installing the
redistributable components on your system. See: http://msdn.microsoft.com/at for details.



3. INSTRUCTIONS
---------------

3.1 General
-----------

File Menu;
New - Creates a new resource. (select "Sound Resource")
Open - Opens a resource in Visual AGI format (.va?)
Save - Saves a resource in Visual AGI format (.va?)
Import - Imports a dumped, pure, AGI sound resource (select type in the drop down list)


4. SOUND RESOURCE
-----------------

4.1 Menus
---------

File->Export Submenu;
AGI Resource - Exports the song (within the play range) to a pure AGI sound resource
MIDI - Exports the song (within the play range) to a MIDI file

View Menu;
Sequencer - Chooses the Sequencer pane (the left)
Pattern - Chooses the Pattern pane (the right)

Sound Resource Menu;
Pattern->New - Adds a pattern at the current cursor position
Pattern->Properties - Sets the properties of a pattern at the current cursor position
Manage patterns - Opens a dialog to get an overview of all your patterns
Control->Play - Plays your song
Control->Pause - Pauses
Control->Stop - Stops playing
Control->Play notes - If selected, notes will play as you edit
Properties - Changes the BPM, TPB and step size of your resource


4.2 Commands
------------

'.': Clears the field at cursor position
TAB: Switch between Pattern and Sequence Mode
INSERT: Inserts empty pattern/note at cursor position, moves everything one step down
DELETE: Deletes pattern/note at cursor position, moves everything one step up

F3: Plays the song
Shift-F3: Pauses
F4: Stops playing


4.2.1.1 Pattern Mode (Voice)
----------------------------

Use Z-M (base octave) or Q-P (base octave + 1) to insert notes.
Set octaves using numbers.
Set attenuation (0 = full volume, 15 = silent) using numbers.

'1' or ',' sets "OFF" note

(numpad) '/' and '*' moves the base octave up and down


4.2.1.2 Pattern Mode (Noise)
----------------------------

The first digit sets the frequency mode (from 0 to 3), ',' sets "OFF"
The second digit sets the noise type (1 = white, 0 = periodic)

Set attenuation (0 = full volume, 15 = silent) using numbers.


4.2.2 Sequence Mode
-------------------

Use right-click and "Set Pattern", or directly type the character next to your pattern (0-9, a-z) using the keyboard.

CTRL-B: Sets start position directly above cursor position
CTRL-E: Sets end position directly above cursor position

ENTER (on empty slot):  Creates a new pattern
ENTER (on a pattern):	Opens the pattern in the pattern editor

You can use drag and drop to move or copy patterns in the sequencer, just as you would in Explorer.


4.3 Editing
-----------

The Sequencer is where you arrange a list of patterns that will play in the specified order.

Using the step size, you select the zoom level. Normally you will not change this more than once.
The step size defines in which "steps" the sequencer will show patterns. For example, a step size
of 16 will show every 16th row in the sequencer. Let's assume that you have a pattern called 000
containing 16 rows. If you place it on rows 0 and 16 in the sequencer, and then set the song range
(using CTRL-E) at the 32th row, the player will interpret it as follows;

Row		Pattern		Pattern Row
  0		000			0
  1					1
  2					2
 ..		until		..
 15					15
 16		000			0
 17					1
 18					2
 ..					..
 
But, what would happen if you had a step size of 8, and a pattern with 16 rows, and placed it on
rows 0 and 8? Let's see;

Row		Pattern		Pattern Row
  0		000			0
  1					1
  2					2
 ..		until		..
  7					7
  8		000			0
  9					1
 ..		until		..
 23					15
 
It can be quite difficult to understand this in the beginning, but play around and try different
step sizes and different pattern lengths, and you will soon understand.


5. HISTORY
----------

2002-07-10:

	More rewrites.. Now, all of the loading and storing code has been rewritten. The XML
	reader/writer is not very optimized at this point, and could have trouble reading
	data that is not written by vAGI itself. It will be fixed later on.
	As well, a slew of bugfixes.

2002-05-15:

	Added DRAG AND DROP of patterns. Just click and drag in the sequence editor. You can even drag
	between resources, and between applications! ;)
	Added help texts on every menu item, as well as in the pattern editor. Look in the status bar.
	Added more code to the Manage Pattern dialog. It's actually useable now.
	Fixed some more bugs, as always...
	
2002-05-08:

	Rewrote the Sound Editor classes, now the two edit modes share the same base class (pheeew...)
	Added some code in the Manage pattern dialog
	Added OLE clipboard support in Sound Editor. You can now copy and paste patterns between resources.
	Added picture resource. Mostly renders at this point, even though most of the code is done "behind".
	
	Fixed _loads_ of bugs.
	
2002-04-27:

	Fixed some scrollbar issues
	Added some logic editor syntax coloring code
	Added some view editor code (right now only in debug, so you won't see anything ;)

2002-04-24:

	Fixed some serious errors with exported resources.
	Added instrument selection when exporting MIDI file.
	Added the resource properties dialog.
	
2002-04-23:

	Added noise editing. I have yet to see an AGI resource using noise, but it is done according to AGISpecs.
	Added rudimentary MIDI export
	Fixed bug with scrollbars when importing a resource (thanks Joel!)

2002-04-22:

	Fixed tempo bug when exporting resources. (how come no-one discovered this one? ;)
	Added some code for the Logic resource. Right now it's just a simple text editor.

2002-04-21:

	Fixed numerous bugs in the file import routine (thanks Joel!)
	Added pattern properties dialog (to be able to change pattern name/rows)
	Began adapting the application for future use with other resources (view, picture etc)

2002-04-15:

	First public release of the rewritten sound editor.


6. THANKS TO
------------

All people at the AGI Messageboard (http://agiboard.cjb.net)
Andrei Stcherbatchenko for the excellent code I "borrowed" from Crystal Edit


/ Joakim