@database "Imagine Attribute Searcher"
@version 1.02


@node Main "Imagine Attribue Searcher"

          Welcome to IAS, Imagine Attribute Searcher, Version 2.
                       Revision 2.02, 31 March 1998


                 @{b}© Oovis 1998. This program is Freeware@{ub}

                        @{"    Introduction    " link Intro}

                        @{"Changes from V  1.06" link Changes}

                        @{"    Requirements    " link Require}

                        @{"Command Line Options" link CLOpts}

                        @{" Output Explanation " link Output}

                        @{"       Author       " link Author}

@endnode

@node Intro "An introduction to IAS"

 This is IAS, the Imagine Attribute Searcher. It was written for a couple of
reasons, the first being that I have a number of objects which have given me
a deal of trouble setting up and rendering. This has been because they are
either saved from the PC version of Imagine, which is not 100% compatible
with the Amiga version, or the creator has used non standard textures which
I don't have, or brushes which have not been included in the distribution
archives.

 The second reason for writing this program was to get myself back into
programming again after a long break. IAS was written in 100% assembler. I
admit that this is not the best way to create something like this program,
and C etc. would have been easier to use, but I don't know C, and can't be
bothered with it at the moment, so assembler it was...

@{b}What it does@{ub}

 IAS will search an Imagine object file and tell you if any textures or
brushes have been used on it. This can save time if you do a quick IAS scan
before setting everything up in Imagine and trying to render, as Imagine
will fall over if it can't find anything specified. IAS can easily tell you
if Imagine will fail to find things, and give you warning that you will have
to do some work on the object to get it to work.

 IAS should find textures from Imagine version 1.0 - 5.0. I only have
specifications for BRS4 chunks which I think are from Imagine 3 upwards, so
some details may not be completely correct with the *b option.

 IAS can convert objects between PC and Amiga versions on the fly, and
resave them after checking.

@endnode

@node Require "Requirements for use"


 To use IAS you should copy it to somewhere in your search path, i.e the
C, S or System directories.

 You must have a version of Imagine on your hard drive as installed by its
included Installer routine.

 Generally IAS will look for textures within the Imagine/textures directory,
however if the object has pointers to external drives/partitions IAS will
try to check them there.

 IAS has only been tested on a 68030, but should work on any processor, as
I believe I have not used any odd processor commands.

@endnode

@node CLOpts "Command Line Options"

 IAS is CLI only at the moment. Here is a template command line, and then
an explanation of what is going on.

 @{b}IAS {*pbc(u)/i} ObjectName HomeDirectory@{ub}
          |          |             |
          |          |             |
          |          |      @{"Home Directory" link HomeDir}
          |          |
          |      @{"ObjectName" link ObjName}
          |
       @{"Options" link Options}

 Please note that IAS will treat any spaces as seperators on the command
line, so file names, and directory names can not contain spaces such
as 'work:ray tracing' or 'imagine object' as IAS will trip over these and
not function correctly.

@endnode

@node HomeDir

@{b}Home Directory@{ub}

 IAS {*pbc(u)/i} ObjectName @{b}HomeDirectory@{ub}

 The Home Directory is where Imagine can be found on your system, for
example, the Installer for Imagine version 4 will try to create a directory
called Im40 in your Work: partition, therefore the Home Directory would be
work:im40

 If your user-startup creates an assign to the Imagine program you can also
enter this as the Home Directory as Imagine: etc.

 The Home Directory, or assign must not contain any spaces as these are used
by IAS as command line separators, and IAS will fall over if you try to do
something like that..

 Text for the Home Directory does not need to end in a / as IAS will cope
with this if you do not enter one...


 To save you typing the Home Directory every time you use IAS you can use
the @{"*i option" link Optioni} to save these details to a pref file.


@endnode

@node ObjName

 IAS {*pbc(u)/i} @{b}ObjectName@{ub} HomeDirectory

 This is where you enter the name of the file you wish to test. The name
must not contain any spaces, and the file must be in the current directory.

 Also note that the file must be on a write enabled disk if you wish to use
any of the convert options, therefore you can't convert a file on a CD ROM
as these are write protected. Copy the file to RAM: first.

@endnode

@node Options "Command Line Options"

 IAS @{b}{*pbc(u)/i}@{ub} ObjectName HomeDirectory

 Here we have the heart of the IAS command line. The options must follow the
name IAS and follow an asterisk (*). If the * is not present IAS will try to
use the option flags as the filename to test!

 The commands can be upper or lower case, and combined in any order with one
or two exceptions..

 u and c cannot be used together as this would ask IAS to convert a file to
 PC version and Amiga version at the same time. IAS will quit.

 i is a special case and will perform only one action as detailed below.

@{b} *p - Open the printer for output.@{ub}

 This causes output from IAS to go to a connected printer instead of the 
screen. If the printer cannot be opened, an error message will be printed
on the screen and IAS will quit.

@{b} *b - Brush information.@{ub}

 This causes IAS to try to show more information about any brushes it finds
such as the size of the IFF file in pixels, the number of colours used,
and what Imagine uses the brush for. Please note that I only have the specs
for BRS4 chunks and so the application data may not be correct for all brushes
and should therefore be treated with caution.

@{"*c and *u" link Optioncu} Convert files

@{"    *i   " link Optioni} Initialise Home Directory Pref file


 So let's assume we have a file called Ship on df0: and we wish to convert it
from a PC object, look at its brush sizes, and print the results. Assuming
the Home Directory is "Imagine:" we can do the following;

 cd df0:

 IAS *cbp ship imagine:

@endnode

@node Optioncu "OptionC/U"

 These options allow automatic conversion between PC and Amiga style objects.

 The only difference between the two formats is that the Amiga uses "/" as
as a directory qualifier, whereas the PC uses "\\". This means that we in
the free world have "...Imagine/Textures", whilst those who are shackled to
1970's architecture have "...Imagine\\Textures" etc

 These characters only appear in texture or brush chunks of the object file,
and IAS simply swaps them for the correct version depending on the selected
command.

 Command C - this will convert PC files to Amiga files

 Command U - this will convert Amiga files to PC ones. The u comes from
             un-convert. I couldn't think of anything better.

 If no conversion was necessary IAS will tell you so.

 If the file was converted, IAS will attempt to save the file back to wherever
it was loaded from. For this reason you cannot convert files straight from a
CD-ROM as these are obviously write protected. Copy the file to RAM: first.

@endnode

@node Optioni "Option i"

@{b}Option I@{ub}

 This is an option to simplify the use of IAS. What it does is this; it allows
you to enter the @{"Home Directory" link HomeDir} and have the details saved to a file in
your S directory so that it can be automatically used by IAS without you
having to bother about it again.

 This pref file can be changed at any time simply by using the *i option again,
and you can delete the file from the S directory if you so wish without
risking causing any harm. The pref file is called "IAS.HD.Prefs".

 However don't edit this disk file if you want to change it as it could easily
cause problems with IAS (and your system) if you do. To change this file use
the *i option again.

@{b}How do I use it then?@{ub}

 Well, you do this;

 IAS *i HomeDirectory

 This directory does not need to end in a / as IAS will automatically add one
to the end of the text if needed.

 IAS will not save the resulting data file to disk if the specified directory
cannot be found. It will prompt you to try again. Check spelling of the name 
of the directory, and more importantly DO NOT put any spaces in the name of
the directory, as IAS will treat these as the end of the command line and
will therefore not find the directory you specify.

 After processing the data IAS will quit immediately.

 Now you don't need to enter the Home Directory on the command line (hurrah!)
as IAS will automatically use the one you've just set up if nothing is found
after the object name on the command line.

@endnode

@node Author "Author Details"

 This program was written by Oovis, contactable at

 Strand Theatre
 Aldwych
 London
 WC2B 4LD
 ENGLAND

 This is version 2 of IAS, subtitled The Post Disaster Rebuild.

 I have been working on an update of IAS for a couple of weeks, and thought
to myself that I'd better back everything up, so out came a fresh Zip disk,
and a backup of my Workbench partition was duly created. However the time
was approaching when I had to leave for work, so I switched my machine off
and went to work.

 On my return I switched my Amiga on and the hard drive started making a
nasty grinding noise, and the machine did not boot up. My heart began to
flutter. I tried a soft reset. Nothing. I started to sweat. Eventually I saw
something I've never seen before on my machine, the boot animation from
ROM!. My hard drive had ground itself to pieces and died. All my work
partition had gone. Everything! MIDI creations, animations, graphics,
letters, paperwork, assembler sources, the lot.

 So farewell then old 360Mb drive and hello 3Gb drive. I managed to get that
up and running despite the fact it took me two hours to get the bloody thing
partitioned and formatted. Is it just my imagination or are the Amiga
operating system floppies flawed? The install disk kept telling me that it
could not find the FastFileSystem on my original Workbench3.1 disk. I had to
make a copy, and move the FFS from another floppy to that copy. Blimey it is
a real labour of love trying to sort these buggers out....

 This is therefore 90% the same as the original IAS, but more streamlined,
as I had to rebuild it from memory, and have reduced some of the silly and
wasteful coding I did in the original. The extra 10% is new routines added
which you probably won't be able to see if you've used version 1.06 of IAS,
except the new command line switch *i.

 If only one person finds this program useful I will be happy.

 The source code, written with DevPacII, is available for £3. If you want
a copy, please send a UK cheque, payable to D I Roberts to the above
address, and I will dispatch one as soon as possible after receipt.

 Please feel free to send me any bug reports. If you can, send me a brief
description of what went wrong, along with the object you were testing
with IAS, and I'll try to sort out what went wrong.

@{b} Thanks To...@{ub}

 Impulse inc. for Imagine

 Dave Madge for the internet cruising

 Frank Zappa, Andreas Vollenweider, Philip Glass and Pink Floyd for the
 musical interest whilst coding

 Spoons and Duncan for keeping everything going while I'm not there

 All trademarks and copyrights acknowledged. 

@endnode

@node Changes "Changes from 1.06"

@{b}Changes from Version 1.06@{ub} (previous public release)

 The search engine within IAS will now locate TXT1 chunks, which are possibly
from version 1 of Imagine. I haven't found any objects from this version of
Imagine which use brushes, so I can't get the BRS chunk format. If I do
I'll release an updated IAS to take this into consideration.

 *I option added. This means you don't have to enter the Home Directory
every time you want to test an object. I don't know why I haven't done
this earlier, lack of foresight maybe :-(

@endnode

@node Output "Output Explanation"

 When you run IAS, assuming there are no errors, you should see something
like the following example;

@{b}
IAS: Imagine Attribute Searcher. Version 2.01. © Oovis 1998.
See documentation for details. This program is Freeware.
Post disaster rebuild! This revision 24 March 1998.

Part Name           Texture/Brush applied                             Test
--------------------------------------------------------------------------
SPHERE              textures/Bathtile(.itx)                           OK
SPHERE              Wraps/bubble                                      BrOK

Textures Applied:    1  Missing Textures:    0
Brushes Applied:    1  Missing Brushes:     0
@{ub}

 The Test column tells you if IAS has found the required texture, or not.
If FAIL appears, and the 'applied' column contains \\s you have a PC
object, so you must convert it using *c.

 The (.itx) appended after the texture name means that IAS found that
version on your hard disk. I think these are for the FP versions, but it
may be that you don't need to worry about this bit.

 BrOK means the file is a brush, and was found. If IAS cannot find a
brush file then BrFL (Brush Fail) will appear here.

 If you've used the *B option then the following should appear for the
brush info line;
@{b}
SPHERE              Wraps/bubble                                      BrOK
Dimensions:  640 x 256  Colours: 16.7 Million
Applied as: Colour Map

Notes@{ub}

 The 'Applied as' field relies on the data I have for BRS4 chunks,
so should be treated carefully, it should be correct, but I can't be certain
for objects from earlier/later versions of Imagine

 The name buffer for loading textures and brushes is 50 characters long, and
so you may find that brushes or textures with long assign paths may cause
IAS to trip up. If I get complaints about this internal problem of IAS then
I'll re-code these routines and buffers, and release an update of IAS as
soon as possible. 


@endnode