;----------------------------------------------------------------------------
;File name:	COLORTOS.TXT			Revision date:	1998.10.18
;Created by:	Ronald Andersson		Creation date:	1998.09.02
;----------------------------------------------------------------------------
;File purpose:	Short introduction to the COLORTOS package.
;----------------------------------------------------------------------------
Introduction:
-------------
COLORTOS is a program to put in the \AUTO\ folder, to activate it at bootup.
It is useful on systems running one of the TOS versions  2.06,  3.05,  3.06,
for which it will give the built-in desktop the ability to display icons in
colour and with animation at selection, quite similar to MultiTOS desktop.

The COLORTOS package was originally created by Guillaume Tello under the
name COLOR_TT, which was motivated by the fact that his version only had
support for TOS 3.05 and TOS 3.06, which require a TT to function. Since
the new version also supports TOS 2.06, which runs on ST/STE, there is no
longer any reason to name the package after a specific machine.

Some files of Guillaime's original package are included in this one too,
and I recommend that you read his docs as well, in addition to this one.
I have made several enhancements too, so check out the section entitled
"Revision history:" further below in this file:


Installation:
-------------
Copy COLORTOS.PRG into the \AUTO\ folder, preferably in such a way that it
boots after most other programs.  It will sense some incompatible programs
through cookies and turn itself off automatically if any of these are active,
but this requires that they boot earlier...

Copy the supplied DESKCICN.RSC and DESKICON.RSC into the root of the boot
partition.

Once all three files have been copied as described above COLORTOS is ready
for booting.


Customization:
--------------
You can use a resource editor (preferably INTRFACE) to modify the icon sets
or create entirely new ones, but you must be aware of some limitations that
apply, beyond those that are customary for all icon resource files.  Those
additional limitations are summarized below

1:  There must always be full correspondence between the two icon files, so
    that there exists one icon in DESKCICN.RSC for each in DESKICON.RSC .
    (If not, you will not get the icons you expect displayed.)

2:  The DESKCICN file should never exceed 200 Kilobytes.

3:  All icons in DESKCICN should have a sixteen colour icon definition, and
    that definition is the only one that will be used by the current COLORTOS
    version.  Even so, all should also have a monochrome definition, because
    that is part of the standard for colour icons.

4:  All icons in both DESKCICN and DESKICON must be exactly 32*32 pixels in
    size, since any deviations from this will produce garbage on screen.

5:  Editing label width to affect icon positioning can not be done by editing
    DESKCICN.RSC.  Edit the label width of the first icon in DESKICON.RSC to
    do that instead.  The system assumes all other icons use the same width.
    

Revision history:
-----------------
1:	Converted source into DevPac_3 format
2:	Added XBRA headers to all 'bent' vector code.  (XBRA id = 'CoIc')
3:	Added XBRA protocol to all vector 'bending' code.
4:	Added new TOS version adaption, leading to a single program for all
	supported TOS versions.
5:	Added TOS version adaption data for TOS 2.06.
6:	Replaced 68030-dependent code for ST/STE compatibility
7:	Added recognition of two more cookies (_CPU, Gnva)
8:	Renamed the program from COLOR_TT to COLORTOS, since it now does
	support ST/STE machines as well (when using TOS 2.06 that is).
9:	Added multiple XBRA vector installation to circumvent the 'delinking'
	operations of NVDI, which otherwise prevent proper function.
10:	Corrected a bug in declaration of 'adr_actu' (must be ds.l not ds.w).
	This bug was 'mostly harmless' but lowered drawing speed a bit.
11:	Modified storage methods to allow for selected icon definitions.
12:	Modified vrt_cpyfm function to support selected icon definitions.
13:	Added code to generate selected icons for icon definitions lacking it.
--------
NB:	Lack of XBRA protocol is the main reason why the original version
	did not cooperate well with other utilities bending AES/VDI vectors.
	NVDI additionally demands extra precautions against 'delinking',
	and it is those that are mentioned as change number 9 above.
--------
After the above changes I contacted Guillaume and together we agreed that I
should merge my changes with some that he had developed since his release,
and we also agreed on some modifications of both sets of enhancements.
The resulting changes are summarized below:
--------
14:	Merged (incomplete) TOS adaption data for TOS 2.05, from COL_MSTE.
15:	Merged TOS 3.06 3D window support from Guillaume's COLOR_TT version.
16:	I've added TOS adaption data for TOS 2.06 3D window gadgets.
17:	I've restructured the XGEM dispatcher completely, for better speed.
18:	I've added ability to relocate some AES pointers for compatibility
	with TOS patchers (eg: GEMRAM + WINX + SHBUF) and RAM TOS versions.
	This support is complete for TOS 2.06 and 3.06, but I lack info on
	the AES start adress of the others... (plus lots other stuff on 2.05)
	Since I also lack any atari RAM TOS some stuff remains untested
--------
After further discussions with Guillaume we agreed that TOS 1.x are not to
be targeted for COLORTOS adaptions.  Their TOS and desktops differ too much
from TOS 2.x for it to be meaningful to combine their support into COLORTOS.
Instead Guillaume produces some separate programs specifically for those
TOS, giving them some new icons etc.
--------
We also agreed that I should try to use the methods of Guillaume's newer
program COL_MSTE for COLORTOS, so that fewer TOS dependent vectors will
be used.  (This has not yet been implemented.)
--------
A bug was discovered in trying to use 'Pure Debugger' with COLORTOS, which
was due to XBRA smashing by the debugger.  A patch for that debugger was
quickly produced, but I also decided to develop a better mechanism for
protecting the XBRA chains.  This involves compatibility to lots of very
important software, such as debuggers, NVDI, other AES enhancers etc,
of which nearly all mishandle the XBRA chains in some way.
--------
19:	I've implemented XBRA chain protection for the XGEM vector, such
	that debugging under COLORTOS does not require patched debuggers.
20:	I've eliminated the (erroneous) 3D drawing of d-clicked icon labels.
21:	I've added 3D-support for atari mode with 2 bitplanes (ST_M) and
	also for single-plane mode (ST_H, TT_H), which latter also works
	with the Nova graphics board.
22:	I added version number info (1.00) to the startup message.
23:	I sent this version 1.00 to Guillaume, and posted it on my homepage
	(http://www.oden.se/~dlanor/).
--------
This marks the first public release of COLORTOS, Ver:1.00 of 1998.10.12
--------
24:	I added clipping of 3D rectangles, to avoid crossing screen borders.
25:	I added limit checks for window ids to avoid bombs under WinX.
	This means that windows with id >7 under WinX or similar will get
	proper 3D, except that title/info lines of desktop under WinX are not
	recognized (so just 2D).  Windows of normal APPs do not have that
	that problem, which is due to internal methods of WinX.
26:	I improved the 3D rutines for 1 or 2 bitplanes to use a grey hatch
	pattern rather than black for the 3D shadows.
27:	I sent this version 1.01 to Guillaume and posted it on my homepage.
--------
This marks the 2nd public release of COLORTOS, Ver:1.01 of 1998.10.18
--------

NB:	3D gadgets are now supported for all native Atari ST and TT rez modes
	and also for 3 rez modes of the Nova board (1 or 8 planes, 16bit TC).

NB:	TOS versions now supported are: 2.06, 3.05, 3.06 . (2.05 is coming)
	As yet 3D gadget support only covers TOS 2.06 and TOS 3.06 .
;----------------------------------------------------------------------------
;End of file:	COLORTOS.TXT
;----------------------------------------------------------------------------
