Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/413a.lha/IFFMaster_v1.0/iffmaster.doc

Text File | 1990-08-31 | 26KB | 562 lines

            Documentation file for IFFMaster by JUNIX of ARCANE




                   This documentation is for version 1.0


        IFFMaster ver. 1.0 is the latest version of IFFMaster, and
    any references throughout the text to "IFFMaster" or "the program"
                    are all references to this version.

                          DOCUMENTATION OVERVIEW:
                         ­


SECTION 1:  Introduction to IFFMaster

SECTION 2:  IFFMaster overview
        2.1:  Basic Terms
        2.2:  The Workscreen
        2.3:  The Mouse
        2.4:  The Menus
        2.5:  The Preferences Window

SECTION 3:  Using IFFMaster
        3.1:  Loading A Picture
        3.2:  Saving Data
        3.3:  The keyboard
        3.4:  Brush
        3.5:  Palette

APPENDIX A:  IFFMaster Version & Development History




Small print at bottom of contract:

This program is entirely Public Domain - Its use is entirely at your own
risk - I can, but will not salvage your disks after you've messed them up.
I am not a magician (at longer distances, anyway) and you gotta clean up
your own messes.  I don't care if IFFMaster causes any of you any trouble
at all.  Got it?

         ­
                   SECTION 1:  Introduction to IFFMaster



  IFFMaster is an IFF ILBM utility.  It is able to load and save IFF ILBM
and Raw format pictures.  It is able to save the palette as binary or
source file.  It is able to save in sprite format (binary or as a source
file).
  Then of course, as the only IFF converter I've seen to date, IFFMaster
includes a palette, ability to select planes and resolution, HAM or
XHALFBRITE modes features etc.  etc.  And surely you can load and save
images of sizes up to 1024x1024 pixels, the maximum defined by the Amiga
System (and the blitter).  This is for now, Kickstart 1.3 and library
version 34.  In the future, when the new blitter (ECS - Extended Chip Set)
becomes the standard, the system will permit larger blits and then larger
bitmaps will be possible, and IFFMaster will be updated to support this.
  You are naturally not limited to saving images of the same size as the
loaded one - with the brush feature you can save pictures of any size you
could possibly want...

                      A C K N O W L E D G E M E N T S


  I would like to thank:

 Amanda, for calling on me when I was ill
 the rest of ARCANE, for their support and help with this project (I'm
   afraid I'm not very useful to the group these days, anyway)
 Mike of ARCANE (in particular), for the technical discussions
 my dog,  for pouring tea all over my disks· my other dog,  for biting my fingers whenever possible
 Dirty Harry Callahan, for providing entertainment
   (Go ahead, make my day!)
 The Coca-Cola Company, for that strange dark acid
 Electronic Arts, for EA IFF 85
 Commodore-Amiga, for the Amiga
 the ones I've already forgotten, for everything!

If any C freaks out there want to contact me, just talk to any member af
ARCANE and ask for JUNIX, the crazy C programmer (me). Then I'll get in
touch with you ASAP.

                      SECTION 2:  IFFMaster Overview


2.1:  Basic Terms :


2.1.1:  IFF ILBM Files:
  IFF means »Interchange File Format« and the story of IFF began back in
1985 back in good old U.S.  of A.  when Electronic Arts introduced IFF to
Commodore-Amiga.  At CMB-Amiga everybody seemed to like the idea, and this
was the beginning af "EA IFF 85", the standard itself.  At that point IFF
included ILBM (the picture format:  InterLeaved Bit Map), SMUS (Simple
MUsical Score), 8SVX (8-bit Sampled Voice/VoX) and FTXT (Formatted TeXT).
This was the "core" of IFF.
  The IFF standard, I might add, was revised in some ways in november 1988
- some new registered FORMs and chunks was introduced.
  An IFF file consists of a group of chunks.  A group is either a FORM, a
LIST or a CAT.  The ILBM is a form, although a FORM might appear in a LIST
or a CAT (actually DeluxeVideo saved the movie in a CAT (concatenation)
of FORM ILBMs).

  The ILBM FORM consists of a number of chunks:
  BMHD BitMap HeaDer   - main info structure
  CMAP Color MAP       - the palette
  GRAB GRABbed point   - an (x,y) offset form the mouse (brush handle)
  DEST DESTination      - used for merging few planes into a large bitmap
  SPRT Sprite PRioriTy - sprite priority
  CAMG Commodore-AMiGa - Amiga display modes (HIRES,LACE,HAM etc.)
  CRNG Color RaNGe      - cycling info (DeluxePaint)
  CCRT Color Cycling      Range & Timing  - cycling info (Graphicraft)
  BODY bitmap BODY      - contains all bitmap and masking data
                    (possibly compressed)
(Not complete)

  Of all these chunk types only BMHD and BODY are needed.  (That is not
quite true, 'cuz an ILBM with no planes and a CMAP is the proper way to
save a palette - then a BODY chunk is not needed.)

  The IFF ILBM is stored in standard AmigaDOS files, often referred to as
pictures, images or ILBMs.  It is in that shape (the file) the user of
IFFMaster will use the ILBM file.

2.1.2:  Raw data:
  As a contrast to the very portable ILBM files (even the PC/MS DOS of
DeluxePaint uses the ILBM standard) is the raw data file.  The raw data
file is simply the planes dumped to disk one by one.  These raw files (as
they will be referred to) are normally bigger than the corresponding ILBM
file (in spite of the IFF overhead waste structures), as raw files are not
compressed (ILBMs are normally compressed by the ByteRun compression
technique).
  A raw file will be garbage to anyone who doesn't know it's width, height
and number of planes, as these values are not stored in the file.  Also the
palette CAN BE out in the thin air, as it is stored quite incognito in the
beginning or at the end of the file, if stored at all.
  However, in spite of all the disadvantages of the raw file (or raw
format, as it is also called at times), there is one MAJOR advantage.  The
raw file is ready for direct inclusion in programs, as the »bare« raw
format is the same format as the one the SCREEN-DMA (DMA=Direct Memory
Access) uses, meaning that the raw file is 100% ready to splashed out to
the screen.

2.1.3:  AmigaDOS File:
  An AmigaDOS file is a collection of bytes managed by the AmigaDOS
operating system, referred to by a file name, such as

   DF1:Source/myprog.c

   Where "DF1:" is the device name (allways followed by a colon), "Source/"
is the drawer or directory specification.  "myprog.c" is the actual name of
the file.  (Some people often makes a destinction between "myprog" and
".c".  Anything after a period is normally called a file extension.  This
is mainly a remainder from MS/PC-DOS where all files MUST have an extension
of 3 characters)
  If all this is new to you you should either :
  1:  Buy yourself a ZX-81
  2 :  Study "The AmigaDOS Manual" (Bantam Computer Books)


2.2:  The Workscreen:

  When the IFFMaster program is started off and running, that is, if
IFFMaster could allocate the memory for the screen, the window and the
fast-text routines, it opens a customscreen with the title "IFFMaster vx.x
by JUNIX / »ARCANE!«" (or the like).  If the machine has recognized the PAL
mode, IFFMaster will sense this and use the PAL screen sizes.
  Under the title bar, the status-line is placed.  It displays information
about:

  Screen Mode and number of bitplanes:
  An 'M' denotes "Modes" then a number (1-6), the number of planes.  Then a
  symbol:
  Either h for HIRES, ½ for EXTRA_HALFBRITE or a capital H for HAM (Hold And
  Modify).  After this mode symbol the "interlace active" symbol is shown. If
  interlace is active, a capital I, for interLACE, is displayed.
  (Please note that HAM and EXTRA_HALFBRITE are only available when using six
  bitplanes, and that HIRES is not allowed with more than four bitplanes - 16
  colors total)

Brush information:
  The values shown depend on what's happening.  If you havent selcted a
  brush yet, nothing is displayed.  If, however, you are selecting the
  brush size or have selected it, the field will show the size of the
  brush.  If you have fixed the brush-size, however, you will see the
  fixed size, even before you have selcted the position.
  This information is shown in the form bWxxx bHxxx, for brushWidth and
  brushHeight, respectively.  xxx represents the number.

Width and height information for the entire image:
  You are at all times able to to see the width and height of the entire image.
  This information is displayed in the form Wxxx Hxxx, for the Width and
  Height of the image, respectively.  xxx represents the number.

Mouse X and Y coordinates:
  At the rightmost positions of the status line, you are able to see the X-
  and Y-axis coordinates of the mouse, relative to (0,0) at the leftmost,
  and topmost position of the image.  If the image is scrolled, the
  coordinates follow (0,0), so that you allways have the correct figures.
  These X and Y numbers are updated every time you move the mouse, and
  becomes incorrect when you distract the program (e.g) use the mouse for
  menu-selection.  To account for this, just move the mouse - as soon as
  you move the mouse the program notes the new position and prints it.
  These numbers are shown in the form Xxxx Yxxx, which should be self
  explanatory.  Of course, xxx represents the number.

Ruler: (if selected in preferences)
  The ruler helps you in your orientation around the loaded image.  Every
  square is 8x8 pixels, and two of these squares are then 16 pixels - a
  magic number on most occations.
  This can be toggled on/off by the preferences screen - the default is off.

  Having these things put right, you should be able to understand the
following subsections of the IFFMaster overview.

2.3:  The Mouse:


  In IFFMaster, the mouse serves the duty of brush and menu selection.
Additionally, you might want to use the mouse for checking that images are
the way you want them to be - when that little dot should be in line with
this little dot, etc. etc.
  As explained above, the coordinates at the of the screen are updated when
you move the mouse.
  The mouse is used for brush-pickups, and you can clear the brush
with the mouse: Hold the left button down, click the right (menu) button,
and then release the left mouse button again. This will clear the brush,
and prepare the program for picking another one up.

2.4:  The Menus:


The menus are set up like this:

Project                           ToolBox

Load                              Brush
Save picture as raw               Fix brush size
             as IFF               Un-fix brush
Save brush   as raw               Palette
             as IFF               Convert ANIM file »NOT AVAILABLE«
Save sprite  in 4 colors          Save picture windows »NOT AVAILABLE«
             in 16 colors          Open new CLI
Append raw (GHOSTED AT START)      Generate palette
Process batch »NOT AVAILABLE«      Save brush mask
Preferences                       Save picture mask
About
Quit IFFMaster

  Note 1:  The items marked »NOT AVAILABLE« are only appetizers - they
will be included is a later version of IFFMaster.  If you have any other
suggestions, please contact me.

  When the menus are used, a menu-palette is loaded into the hardware.
This way the menu-entries display correctly in all modes - even HAM...
This changing of colors will (sometimes) make the display flash.  THIS IS
NOT A FAULT, just a necessity!  And if you have loaded a picture, the
colors appearing when you press the right mouse button will be very
*interesting*.  Try it out!  (Prepare for a mental check afterwards -
ACIIIIID!)

2.5:  The Preferences Window:

  The preferences window will provide the options not given other places in
the program (rulers on/off, save sprite mode, etc).  At startup the
configuration file "S:IFFMaster.prefs" is loaded (if located).  This 24
bytes long file will contain the IFFMaster preferences.
  To use the preferences, select Project Preferences (or right-Amiga P),
and click any of the items you see. You can, of course, press the key just
left of the item you want instead.
  Here are the options in you can alter:

  Rulers: Hidden or shown - self explanatory
* Bitplanes save method: Normal/Raster save - see note 1
  Palette information: Not used/Behind picture/Before picture - see note 2
  Separate palette save: Binary data/ASM source/ASM source for copper-list
  Sprites save method: Binary data/ASM source files
  Sprite control words: Not used/Used - the hardware sprite words
* Extra blitter words: Not used/Left of picture/Right of picture - for bobs
  Brush pickup: One click/Two clicks - a good solution for bad mice
* IFF ILBM compression: None/Byte Run 1 Algorithm - decide for yourself

And the three commands:

Cancel preferences - quit the prefs while discarding the changes
Use these prefs - leave and use the new settings (same as the closegadget)
Save and use prefs - leave prefs, use and SAVE prefs.

* is used to indicate that the option only applies to files written from
IFFMaster. When reading, these options are ignored.


Note 1:
Raster save is when the planes are interleaved; (example with 3 bitplanes):
1st line from plane1, then 1st line from plane2, then 1st line from plane3,
then 2nd line from plane1, then 2nd line from plane2, then 2nd line from
plane3, then 3rd line from plane1, and so forth.

Note 2:
This is the position of the palette data. If saved within the raw file, it
is possible to load the image back into IFFMaster with the correct colors.
As this will not be important to very many people, I've chosen to pick "Not
used" as the preference.

        SECTION 3: Using IFFMaster

:  Loading A Picture:

  When you select Project Load picture (Right-Amiga L) the file requester
opens, prompting you for a file to load.  Now select the file, and press
the "Load!" gadget.  Then IFFMaster will try to load the picture file into
the Amiga's memory.  If the file is an IFF ILBM file, it will load
automatically.  If - however - the file is not an IFF ILBM file, IFFMaster
assumes the file to be a raw dump of a picture.  The program will then ask
the user (that's you!) how wide and tall the file is and how many bytes
IFFMaster should skip at the beginning of the file (if needed, leave empty
if not).  Then, after pressing <RETURN> after this last number (use decimal
numbers), you have to press one of the keys 1-7 to decide how many
bit-planes the picture's got.  If you press '6' IFFMaster will load the
picture as an EXTRA_HALFBRITE picture (6 planes and 32 palette entries).
If you press '7' IFFMaster will load the picture as a HAM picture (6 planes
but only 16 palette entries).  If, however, you press the space bar, the
cursor will re-appear at the width box, leaving you to alter the numbers
entered (this is handy because you don'r have to use the mouse).  When you
have selected the width, height, offset (if needed) and number of
bitplanes, just press <RETURN> (or press Load gadget) to confirm the inputs
and load, or <ESC> (or press Abandon gadget) to drop out.
  If you choose to load the picture, IFFMaster will get the memory the
image would fit (memory is allocated dynamically = at load time) and
commence the load.
  If any errors occur IFFMaster will inform you, and the load will be
cancelled.

  If you have loaded a raw picture with a palette (specify this in the
preferences) and the colors are all equal (typically black) press the
<HELP> key.  This will give you the standard (DPaint III) palette.  This
litte trick works, needless to say, at all times.

3.2:  Saving Data :


  When you feel like saving some data, you'll have to consider these two
things:

What to save (brush/entire image)

How the data should be saved (IFF, raw or as a sprite, mask)

  Of course, you'll know this all by yourself before you load IFFMaster.
  For full pictures, there's no problems - you simply load them, and then
save them again.
  I recommend that you only use brush mode if you really need it real bad.
If, for instance, you have an ILBM with a little graphical item in it and
you want to take it out for use within your own program, the normal
procedure is to load the picture into DPaint and cut out the brush there
and then load this IFF brush into IFFMaster and finally save it to a raw
file.
  But, if you don't have DPaint (e.g on an island in the Pacific Ocean) or
think it would be a waste of time to load it, just for the sake of that
little stupid brush - use IFFMaster.
  First, load the picture.  Then cut out the brush you want to save (for a
discussion of the brush feature, see subsection 3.4).  Now save the brush
using the Project Save Brush command.  Simple as that.  Got it?
  When you have loaded the image (and cut a brush out if that's what you
desire), it's saving time.  It is most likely that you save as a raw file,
if you want to use the image in a demo or an application program.  If you
save it as a raw file you are able to use the image with the copper or the
blitter, without any decompression or translation (which is essential with
IFF ILBMs).
  For the first two categories, IFF ILBM and raw file, the image is saved
with the attributes of the IFFMaster screen.  The number of bitplanes (1-6)
used is based ONLY upon the number of planes selected within the program at
saving time, and NOT the number of planes loaded.  The other screen
attributes are not REALLY interesting, only you should not save an ILBM in
HAM mode, unless you really mean it.  A raw image will not load into
DPaint, while an EXTRA_HALFBRITE (also 6 bitplanes) will (in DPaint III,
that is).
  The width and height of the saved output depends on the brush size (for
brushes) or the size of the entire image (for whole pictures).  However,
the width of the image saved to raw files is allways rounded up to the
nearest higher multiply of 16 (pixels), which is a processor word.
  For IFF saved output, you need not bother about rounding off, only note
that only some very few chunk types are written out to the file, namely
BMHD(BitMapHeaDer), CMAP(ColorMAP), CAMG(Commodore-AMiGa display modes) and
BODY (the picture "body" - the bitmap itself).  The picture will be saved
without masking (mskNone).  If you load an ILBM with cycling, GRAB
information etc.  and save this back again, you lose these informations.
But - why on earth use this converter program to load AND save ILBMs?

  The Project Append (right Amiga-'M') is used when you have to put a large number
of graphical objects (source codes or binary data) together in one file.
Firstly, save the first object in the file where you want all your data to
go. Then select the next object and use the Append command. This will put
the data at the end of the original file. This is very useful in
conjunction with the fix brush size facility.

  Please note that you can NOT append ILBM files on to one another. Only
raw format output is appendable.

3.3:  The Keyboard :


When using IFFMaster the keyboard is used for many various things:

Enterings text or numbers, in the File Requester or the Load raw file
function, or at the preferences window.

* Scrolling around in the bitmap (the image). Use the cursor keys for this.
  If you use the cursor key alone, the scrolling speed is 4 pixels.
However, if you press an ALT key while scrolling the speed will be higher,
16 pixels, to be exact.  And if you use a SHIFT key whilst scrolling, the
speed will be very slow, only one pixel per keystroke or repeat impulse.
  Use the CTRL key to move to the edge of the bitmap (the image):  Press
CTRL-CursorLeft to move to the leftmost position, CTRL-CursorLeft to go to
the bottommost, etc. etc.

* Selecting the screen depth (number of bitplanes, and colors).  Press the
keys 1-6 for this.  The number of colors are equal to 2^<number of
bit-planes>.  Thus a depth of one equald 2 colors, 2 bitplanes are 4
colors, and 3 bitplanes gives you 8 colors, and so forth.  6 bitplanes is a
special case, though.  If you select this (or load a picture with this
setting), you'll get either 64 colors (EXTRA_HALFBRITE) or the special
Hold-And-Modify (HAM) mode.  For description of these modes, see the
official Amiga Hardware Reference Manual.
  Please note that you cannot use the numbers on the keypad for this.
  If you have loaded a picture in, say 4 bitplanes, and want to cut off
some of these, please note that IFFMaster will just chop off the high order
(MSB) planes.  It doesn't actually inspect the picture to check its colors.
To use less colors (remove the least used ones) please turn to PixMate,
which is written for that purpose.

* Setting the screen mode.  Use the following keys:

  The 'I' key is used to toggle INTERLACE mode.  This doubles the vertical
(Y) resulution.
  The 'H' key will, in case you do not use more than 4 bitplanes, toggle
HIRES mode.  This will double the horizontal (X) resolution
  The 'A' key will (in 6 bitplane mode only) turn on HAM, if it's not
already active.
  The 'E' key will (in 6 bitplane mode only) turn on EXTRA_HALFBRITE, if
it's not already active.

* Use the HELP key (unshifted) to reset the palette to a standard,
high-contrast DPaint III palette.

* Use shift-HELP to show information about the program...

* Use the SPACE BAR instead of the left mouse button when selecting
brushes.

* Use the keyboard to select some of the menu-items.

3.4:  Brush :

To select a brush, use the brush menu item, ToolBox Brush, or press 'b'
(non-shifted).  This will clear the brush currently selected and the brush
will be ready for pickup.  First, move to the first corner of the brush you
want to pick up.  Now press the left mouse button(do not release it if you
haven't selected "Brush Pickup:  Two click method") or press the SPACE BAR.
Then move to the opposite corner.
  If you have selected "Brush Pickup:  Two click method" in the
preferences, you have to click the left mouse button or press the SPACE BAR
again.  However, if this option is NOT active, just release the left mouse
button.
  While selecting the brush, the width and height of the brush will be
displayed in the menu-bar.
  If you have to save a number of brushes of the the same size (e.g.
sprites) you may prefer the "Fix brush size"-facility.  To fix the brush
size, select ToolBox Fix brush size or press 'f' (unshifted).  Then proceed
the same way as above (the normal brush selection).  Then, when the size is
fixed, use the 'b' key (or the corresponding menu item) to clear the old
brush.
  Now, when the brush size if fixed, use the fixed brush as the normal one.
Only, when you select the location, it has to be in the upper left corner.
The size will be displayed while moving around.  When you have reached the
right spot, press SPACE BAR or click the left mouse button.
  You can clear the old brush in a very simple way:  Hold the left button
down, click the right (menu) button, and then release the left mouse button
again.  Then the brush is cleared.

3.5:  Palette :


Use the palette to change to colors.  When inside the palette, use the
three proportional gadgets to adjust the Red, Green and Blue portions of
the color, or (in HSL mode) the Hue, Saturation or Luminance of the color.
  To copy a color, select the first color, click the COLOR-gadget, and then
select the second color.
  To spread the colors, click the range gadget, select the first color,
then the second, and the colors will be spread inbetween these two colors.
  To leave the palette subsection, use the OK-gadget to accept the changes,
or the CANCEL to abandon any modifications.



           APPENDIX A: IFFMaster Version & Development History:


                             Program history:

--------------------------------------------------------------------------
 10-11-89    Created this file for the good of ARCANE!
 12-11-89    Put in palette! Began scrolling.
 13-11-89    Joke!, Planes and Modes ok!, colors and menus ok, etc.
            Fixed the mouse-movement, too (no waiting!)
 14-11-89    Coordinates, W,H Modes displayed correctly. Mem usage!
 15-11-89    Decided to semi-drop the original IFF stuff and do it myself!
 16-11-89    Joined with IFF reader routines. It Works (a bit)...
   ...      IFF read works 100%. Write raw works.
 19-11-89    Wrote some of the documentation
 21-11-89    Preferences meditation. Found an ok solution
 22-11-89    Prefs programming + error window
 23-11-89    Further pref coding
 04-12-89    I find "Family Ties" repulsive and jukky!
 06-12-89    LNP - Late Night Programming - ScrollXY OK!
 09-12-89    Changed ScrollXY to use only one blit/Brush features
 10-12-89    It's debugging time! Got it!
 11-12-89    programming overnight - feeling fine!
 13-12-89    raw load...
 16-12-89    Amanda and I together for half a year!
 17-12-89    ILBM Save fixed ysterday - today: LButton+RButton=bress_b
 19-12-89    Fix I/O (saved 200 bytes). Startup text. Pointer. MENUVERIFY
 25-12-89    Did Mask routines - fixed pr_WindowPtr things and colors
 26-12-89    Happy BirthDay N - Amanda home in 4 days - SavePic modes
   ...      Coding overnight - Docs and append. Mabye sprites and Palette
   ...      (coding overnight to provide Mike+Merlin with a pre-release)
    01-90    Chopped off some bytes and added some more
 18-01-90    Sprites...
 21-01-90    Added INTERNAL VERSION...
 22-01-90    Fixed the last peculiarities, linked and crunched the release
            version
 25-01-90    Fixed the DOCument
--------------------------------------------------------------------------

                             Version history:


IFFMaster version 0.5 (pre-release 1):

This version is not complete
There is no Append/Erase function. The "Save picture windows", "Convert
ANIM file" and "Process Batch" smart-ass routines are not even thought
of...
Finally, the documentation is not complete...


  A lot of things put right.  This version is smaller, it has PAL support,
it doesn't use as much chipmem on fastmem machines as the old one did, it
is now a suave program.

Finally, the documentation has been fixed!

All in all, this is well - er... for now, anyway - complete!

<End of file>