@DATABASE "CUR2ILBM.guide"
@$VER: CUR2ILBM.guide 1.1 (26.1.2000)
@AUTHOR "Deok-Min Yun"

@NODE Main "CUR2ILBM Documentation"

@{JCENTER}
This is the documentation for CUR2ILBM 1.1.

CUR2ILBM is ©1998-2000 by Deok-Min Yun.


@{U}WHAT'S NEW?@{UU}

  - Transparency support.
  - Verbose option.
  - Various error checks.
  - HTML documentation.


@{B}Table of Contents@{UB}

@{" Introduction     " link Introduction}
@{" Legal Stuff      " link LegalStuff}
@{" Requirements     " link Requirements}
@{" How To Install   " link Installation}
@{" How To Use       " link Usage}
@{" Revision History " link History}
@{" Things To Do     " link ToDo}
@{" Author           " link Author}
@{JLEFT}

@ENDNODE

@NODE Introduction
@{B}Introduction@{UB}

@{U}Description@{UU}

CUR2ILBM is a program to convert Windows 3.1/95/NT cursor (.CUR/.ANI) or
icon (.ICO) files to ILBM-IFF files.


@{U}Features@{UU}

- Nominated transparent colour support.
- Extracts multiple icon images within a file.
- Converts an animation cursor file into multiple images.
- Support for 2/16/256 colour cursors/icons.
- Converts cursors/icons with any width or height combinations including
  rectangular images.
- Preserves attributes like name of the file, author, grab position
  (cursors only), mask bits (for transparency), etc.

@ENDNODE

@NODE LegalStuff
@{B}Legal Stuff@{UB}

@{U}Copyright@{UU}

This program is freeware.  You can do whatever you want with this
software as long as you do not use it for anti-social behaviour.  If you
include this software into a compilation CD or other media type, please
send me a copy so that I can verify it (except Aminet CDs).

Windows 3.1, Windows 95 and Windows NT are the trademarks of Microsoft
Corporation.


@{U}Disclaimer@{UU}

This program is provided "AS IS" without warranty of any kind.  The
author assumes no responsibility or liability whatsoever for any damage
or data loss caused by using this program.

@ENDNODE

@NODE Requirements
@{B}Requirements@{UB}

- iffparse.library in LIBS: (should have been installed from your
  Workbench disks).
- AmigaOS 2.04 or better (not Windows, of course).

@ENDNODE

@NODE Installation
@{B}How To Install@{UB}

There is no installation required.  It would be a good idea to copy this
program to be in your system path (e.g. C:, SYS:Utilities).

@ENDNODE

@NODE Usage
@{B}How To Use@{UB}

@{U}Template@{UU}
You can only use this program from CLI.


CUR2ILBM FILE/A,TC=TRANSCOLOR=TRANSCOLOUR/N,V=VERBOSE/S

FILE/A :  name of the file to be converted (.CUR/.ANI/.ICO).  This is
          mandatory.

TC=TRANSCOLOR=TRANSCOLOUR/N :  nominated transparent colour to use.  It
	must be less than the number of colours in the icon/cursor.
	Without this option, a mask plane will be generated instead.  If
	the nominated colour is already being used in the icon/cursor,
	it will be swapped with a free palette.  If there are no free
	palettes available, the closest pair of colours will be chosen
	and merged into the median colour of the two to make a free
	palette.  Then that free palette will be swapped with the
	nominated colour.

V=VERBOSE/S : shows some information about the file.


If the file contains multiple images, all the images will be converted
with incrementing numbers.

e.g., if EXAMPLE.ICO contains 32x32, 48x48, and 64x64 images, they will
be converted as EXAMPLE.0.ILBM, EXAMPLE.1.ILBM, and EXAMPLE.2.ILBM,
respectively.

Additionally, animated cursor images will be converted with padded frame
numbers.

e.g., EXAMPLE.ANI containing 5 frames will be converted to,
EXAMPLE.ILBM.000, EXAMPLE.ILBM.001, EXAMPLE.ILBM.002, EXAMPLE.ILBM.003,
and EXAMPLE.ILBM.004.


@{U}Examples@{UU}

> CUR2ILBM MyIcon.ICO V TC=0

This will convert @{B}MyIcon.ICO@{UB} file into MyIcon.ilbm and show
information about the icon.  Colour 0 will be the transparent colour.


> CUR2ILBM Coin.ANI

This will convert all frames from the @{B}Coin.ANI@{UB} file with a mask
plane.

@ENDNODE

@NODE History
@{B}Revision History@{UB}

> : Changed      + : Added        - : Removed      ! : Fixed    * : Misc.

*** Version 1.1 ***

26-Jan-2000: > Updated the documentation.
25-Jan-2000: ! There was a memory leak problem with animated cursor
               routines.
             + Aborting the program by CTRL-C has been added.
             ! Transparency colour could be greater than the maximum
               number of colours.
24-Jan-2000: ! An enforcer hit was occurring when saving GRAB chunk.
             ! A mask plane was not generated properly when used the
               transparency option.
23-Jan-2000: ! Colour registers were not converted with transparency.
22-Jan-2000: ! Transparent colour was not swapped with free palette.
21-Jan-2000: + Added ILBM support functions.
14-Jan-2000: + Added the verbose option.
13-Jan-2000: > Modified the smakefile for batch processing.
12-Jan-2000: + Added functions to deal with transparency.
11-Jan-2000: > Modularised the source code.


*** Version 1.0 ***

11-Jan-1998: + Wrote AmigaGuide document.
 8-Jan-1998: + Support for GRAB chunk.
 4-Jan-1998: * Multiple images within an icon are decoded correctly.
             * Properly parses the icon structure.
 3-Jan-1998: > AND-Map is now used as mask plane. This required change of main
               loop.
             * Name chunk and artist chunk from RIFF are recognised and being
               written as name chunk and author chunk for IFF respectively.
 2-Jan-1998: ! Fixed a bug with AnimCurHeader structure.
 1-Jan-1998: * Got 256-colour icons working.
30-Dec-1997: ! Fixed bugs caused by omitting brackets (doh!).
             ! Fixed AND-Map output.
29-Dec-1997: + Added variables to accomodate variable sized icons.
             ! Fixed a problem with upside-down images (stupid MS).
             * Realised that the images are encoded in little-endian (Intel
               binary).
             * Got 16-colour icons working.
28-Dec-1997: * Started coding.

@ENDNODE

@NODE ToDo
@{B}Things To Do@{UB}

- Optional Amiga icon output.
- Add CAMG chunk.
- Support for animation rate and sequence.
- When converting anim cursor file, it should respect the sequence.
- Support for 24-bit BMP format (some icons have an extension '.ICO'
  even though they are '.BMP' files.
- Split Windows icon handling routines into their own library.
- Optimise transparency routines.

@ENDNODE

@NODE Author
@{B}Author@{UB}

Name   :  Deok-Min Yun
E-Mail :  dmyun@excite.com
          dmyun@rocketmail.com
          dmyun@hotmail.com
WWW     : http://dmyun.tripod.com/

@ENDNODE