OptIcon                                                               OptIcon

   NAME
	OptIcon -- Optimize icon images for size and speed (V36)

   SYNOPSIS
	OptIcon NAME/A/M,DEPTH=PLANES/N,NOEXPAND/S,CRITICAL/S,VERBOSE/S

   FUNCTION
	OptIcon reads in given ".info" files and scans the icon image
	in order to optimize the PlanePick and PlaneOnOff fields in the
	icon Image structure.  This is a space-saving mechanism for image
	data.
	Rather than defining the image data for every plane of the RastPort,
	you need define data only for the planes that are not entirely zero
	or one.  As you define your Imagery, you will often find that most
	of the planes ARE just as color selectors.  For instance, if you're
	designing a two-color icon to use colors one and three, and the icon
	will reside in a five-plane display, bit plane zero of your
	imagery would be all ones, bit plane one would have data that
	describes the imagery, and bit planes two through four would be
	all zeroes.  Using these flags avoids wasting all that memory in
	this way:  first, you specify which planes you want your data to
	appear in using the PlanePick variable.  For each bit set in the
	variable, the next "plane" of your image data is blitted to the
	display.  For each bit clear in this variable, the corresponding bit
	in PlaneOnOff is examined.  If that bit is clear, a "plane" of zeroes
	will be used.  If the bit is set, ones will go out instead.
	Note that if you want an Image that is only a filled rectangle, you
	can get this by setting PlanePick to zero (pick no planes of data)
	and set PlaneOnOff to describe the pen color of the rectangle.

   INPUTS
	NAME          - name of the icon image file.  A trailing ".info"
			is optional but not required.
	DEPTH         - maximum number of bitplanes to be saved.
	VERBOSE       - display input and output information for each icon.

   EXAMPLE
	;Remove all but the first 3 planes of the icon image for the
	;disk in drive DF0: but don't add any planes
	opticon df0:disk planes=3 noexpand

   NOTES
	Since the IconEdit from Commodore will always save 8 bitplane icons
	the above example might be of great use to you.  (Note that 3 plane
	images are not only smaller but also faster!)
	Coming with OptIcon is the script PatchIcons which will recursively
	descend all subdirectories of a given path deleting all but the first
	3 planes of all icon images in that path.

	OptIcon now also allows you to expand your 8 or more color icons
	for the use on a 16 or more color Workbench.  This is important due
	to the new color system under OS3.x which always shifts the second
	four colors to the end of the system palette.  Therefore you might
	want to adapt an icon's color depth to the actual screenmode it is
	used on.

   EXAMPLE
	;Remap the last 4 of at least 8 colors of the RAM DISK icon
	;to the last 4 colors in a 16 or more colors Workbench palette
	opticon ram:disk planes=4

   BUGS
	Commodore's PutDiskObject() currently [icon.library 40.1 (15.2.93)]
	re-expands icon images using the PlanePick/PlaneOnOff mechanism and
	in fact PutDiskObject() has quite a lot of problems doing so!
	For this reason OptIcon will perform the PlanePick/PlaneOnOff
	optimization only if the keyword CRITICAL is given in the command
	line.

   DISCLAIMER
	This file is part of the Icon2C and OptIcon distribution.

	Icon2C and OptIcon are free software; you can redistribute them
	and/or modify them under the terms of the GNU General Public License
	as published by the Free Software Foundation; either version 1 of
	the License, or (at your option) any later version.

	Icon2C and Opticon are distributed in the hope that they will be
	useful, but WITHOUT ANY WARRANTY; without even the implied warranty
	of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with these programs; see the file COPYING.  If not, write to
	the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

   SEE ALSO
	PatchIcons, Icon2C