MPImage 7.5 Contents
********************

@Remark $VER: MPImage_guide 7.5 (14.3.97)

Quick overview
**************

MPImage is a tool for viewing, scaling and converting Images.

It can load the following formats:

     ILBM     : All standard ILBM formats including EHB, HAM6, HAM8 and 24bit;
     PBM      : All formats (P1, P2, P3, P4, P5 and P6);
     DataTypes: Any datatype supported format;
     JPEG     : Loads JPEGs with Djpeg;
     PNG      : Loads PNGs with pngtopnm.
     DCTV     : DCTV ILBMs with dctv.library version 3.

It can view in the following modes:

     Workbench    : View in a window on the Workbench;
     Public Screen: View in a window on a named Public Screen;
     EGS Screen   : View in a window on the default EGS screen.
     Screen       : View on a custom screen

It can save in the following formats:

     Greyscale: ILBM 16 shades and 256 shades;
     HAM6     : ILBM HAM6 with fixed, computed or supplied palette;
     HAM8     : ILBM HAM8 with fixed, computed or supplied palette;
     EHB      : ILBM EHB with computed or supplied palette;
     COLOUR   : ILBM with computed or supplied palette, 2 to 256 colours;
     ILBM24   : 24 bit ILBM;
     PPM      : P5 and P6 modes.
     JPEG     : JPEG with Cjpeg.
     PNG      : PNG with pnmtopng.
     DCTV     : DCTV ILBMs with dctv.library version 3

Installation Instructions
*************************

The following files are included in this distribution and require installing in one directory:

You will also need to copy MPGui.library from libs/ and MPImage.library.??? to MPImage.library. Use .000 for 68000, .020 for 68020+, .881 for 68020+ and 68881+, .040 for 68040+, .060 for 68060.

The Install-MPImage script will do this for you. It will also let you set env: variables to enable JPEGs and PNGs to be loaded and saved.

     MPImage           : IconX script for ConvertMPImage with Gui interface.
     MPImage.guide     : This file.
     ConvertMPImage    : Shell command to convert/scale/view images.
     RunMPGui          : Shell command to display a parameter requester
     libs/MPImage.library.#?: Image conversion library.
     libs/MPGui.library     : Gui library.
     Install-MPImage   : Installer script.
     gui/MPImage.gui   : Gui definition file for MPImage.
     si/#?             : Source code to ConvertMPImage.
     include/#?        : Include files for MPImage.library.
     docs/#?           : Autodocs for MPImage.library.

Software and Hardware required
******************************

OS3.0+ is required.

egs.library is required to display on EGS screens.

dctv.library is required to load and save DCTV images.

Shell and GUI parameters
************************

The following parameters can be supplied:

MPImage displays a Gui with a View/Convert gadget to select the running mode and a Size gadget to select the sizing mode. It also displays Ok (keyboard shortcut O), Cancel (keyboard shortcut C) and Help (keyboard shortcut Help). The Esc key can also be used to cancel the requester. Help can also be used over/in any of the gadgets to display context sensitive help.

FROM parameter
==============

This parameter specifies the name of the input file. See Overview for a list of the image formats that can be loaded.

F can be used to activate the string gadget. With Right Shift a file requester is displayed.

X parameter
===========

If this parameter is specified then the X size of the image is scaled to the number supplied.

X can be used to toggle the selection of the parameter and activate the number gadget. With Left Shift the number gadget is activated.

If viewing on the Workbench or a Public screen then simple scaling is used. If saving or viewing using EGS then more clever scaling is used.

Y parameter
===========

If this parameter is specified then the Y size of the image is scaled to the number supplied.

Y can be used to toggle the selection of the parameter and activate the number gadget. With Left Shift the number gadget is activated.

If viewing on the Workbench or a Public screen then simple scaling is used. If saving or viewing using EGS then more clever scaling is used.

MINX parameter
==============

This parameter (with the MAXX parameter overrides the X parameter. If the input image is narrower than then specified size then it is scaled to this width.

W can be used to toggle the selection of the parameter and activate the number gadget. With Left Shift the number gadget is activated.

MINY parameter
==============

This parameter (with the MAXY parameter overrides the Y parameter. If the input image is shorter than then specified size then it is scaled to this height.

H can be used to toggle the selection of the parameter and activate the number gadget. With Left Shift the number gadget is activated.

MAXX parameter
==============

This parameter (with the MINX parameter overrides the X parameter. If the input image is wider than then specified size then it is scaled to this width.

I can be used to toggle the selection of the parameter and activate the number gadget. With Left Shift the number gadget is activated.

MAXY parameter
==============

This parameter (with the MINY parameter overrides the Y parameter. If the input image is taller than then specified size then it is scaled to this height.

E can be used to toggle the selection of the parameter and activate the number gadget. With Left Shift the number gadget is activated.

PUBSCREEN parameter
===================

This specifies the name of a Public screen on which to open a window and display the image.

P can be used to activate the string gadget.

EGS parameter
=============

Specifiying this parameter displays the image on the default EGS screen.

This parameter is automatically specified if the View/Convert gadget is set to EGS.

NOREMAP parameter
=================

Specifying this parameter prevents the image being remapped to the screen palette it is to be displayed on.

R can be used to toggle this gadget.

CLONE parameter
===============

Specifying this parameter can reduce the amount of chip memory used when loading Datatype images.

L can be used to toggle this gadget.

TO parameter
============

This parameter specifies the name of the output file the image will be saved to.

If FORMAT is supplied TO is not supplied or supplied as "" then the image is displayed on a screen. Note FORMAT=PPM is not valid for this option.

T can be used to activate the string gadget. With Right Shift a file requester is displayed.

FORMAT parameter
================

This parameter specifies the output format.

The following formats are available:

     BW16   : 16 colour grey scale ILBM
     BW256  : 256 colour grey scale ILBM
     HAM6   : HAM6 ILBM with fixed (internal) palette
     HAM6P  : HAM6 ILBM with computed or supplied palette
     HAM8   : HAM8 ILBM with fixed (internal) palette
     HAM8P  : HAM8 ILBM with computed or supplied palette
     EHB    : EHB ILBM with computed or supplied palette
     COLOUR : 2 to 256 colour ILBM with computed or supplied palette
     ILBM24 : 24 bit ILBM
     PPM    : P5 (if grey input) or P6 PBM format
     JPEG   : JPEG format (using cjpeg)
     PNG    : PNG format (using pnmtopng)
     DCTV3  : 3 plane DCTV ILBM with dctv.library version 3
     DCTV4  : 4 plane DCTV ILBM with dctv.library version 3

If the output format is not a 24 bit format then the image is dithered using the Floyd-Steinberg method.

S can be used to cycle the list view. With Shift the list view cycles backwards.

FORCEGREY parameter
===================

If the image is being saved or viewed on screen then this forces the input to grey scale. This can save memory and speed up processing when scaling and saving GreyScale images as only one chunky buffer has to be scaled.

PALETTE parameter
=================

If FORMAT is set to HAM6P, HAM8P, EHB or COLOUR then this paramter can be used to specify the palette to use for the output file.

The file specified should be an ILBM file.

A can be used to toggle the selection of the parameter and activate the string gadget. With Left Shift the string gadget is activated. With Right Shift a file requester is displayed.

COLOURS parameter
=================

if FORMAT is set to COLOUR then this gadget can be used to specify the number of colours in the output image (from 2 to 256). If not specified (not possible from the Gui) then the default is the number of colours in the PALETTE file or 16 if no palette is supplied.

U can be used to increase the value. With Shift the value is decreased.

12BIT paramter
==============

if FORMAT is set to COLOUR then this gadget can be used to specify that colour remapping should use a 12 bit palette. The default is to generate an 18 bit palette.

You should specifying this parameter if you are viewing the image on a pre AGA machine as the image conversion is much quicker.

B can be used to toggle this gadget.

LINEAR paramter
===============

if FORMAT is set to BW16 or BW256 then this gadget can be used to specify that Linear Greyscale mapping should be used.

This can be used if the images are otherwise produced to bright.

N can be used to toggle this gadget.

WHITE0 paramter
===============

if FORMAT is set to BW16 or BW256 then this gadget can be used to specify that Colour 0 should be white, rather than black.

This can be used to e.g. better display menus on a screen.

1 can be used to toggle this gadget.

MODENAME parameter
==================

If the FORMAT parameter specifies an ILBM then this parameter can be used to specify the screen mode (CAMG chunk) of the output file.

If not specified then a reasonable one is generated.

M can be used to activate the string gadget. With Right Shift a screen mode requester is displyed.

NOPROGRESS parameter
====================

If this is specified then no progress requester is shown.

GUI parameter
=============

If this is specified then error messages are displayed on a Workbench requester rather than the console.

View/Convert gadget
===================

This gadget selects the action. It has the following values:

     View Workbench    : View on the Workbench
     View Public Screen: View on a named public screen
     View EGS          : View on the default EGS screen
     Save/View Screen  : Convert and save the image or view on a screen

V can be used to cycle this gadget. With Shift the gadget cycles in reverse.

Size gadget
===========

This gadget enables either the X and Y gadgets or the MINX, MINY, MAXX and MAXY gadgets.

This lets either the actual or minimum and maximum scaled image sizes to be specified.

Z can be used to cycle this gadget. With Shift the gadget cycles in reverse.

Known (and unknown) errors
**************************

A Palette file requires a body which is also loaded and then discarded.

The MODENAME may lose the monitor part.

Version History
***************

  * Version 7.5

       * Corrected some spelling mistakes.

       * Update Library Version number correctly.

  * Version 7.4

       * SaveMPImage now returns correct response when MPIS_BITMAP supplied.

  * Version 7.3

       * Fixed enforcer hit when no progress displayed.

       * Opens locale.library(38) to work on OS3.0.

  * Version 7.2

       * Non beta version.

       * Moved location of libraries.

  * Version beta1 7.0

       * Many new library functions/tags added.

  * Version beta1 6.1

       * Fix for V43 picture.datatype (does not like PDTA_ColorRegisters).

       * 040 library now has correct version.

  * Version beta1 6.0

       * Added ProgressHook.

       * Recompiled using SAS/C 6.57.

       * Added 060 version.

       * Localised.

  * Version 5.1

       * Non beta version of 5.0.

       * Source code released under GNU License.

       * FORCEGREY option now works correctly for IFF and Datatype images. Thanks to Fred. Calendini. It used to ignore the Green and Blue parts of the palette.

       * Determination of Grey scale IFF and Datatype images corrected.

       * Some speed improvements.

       * Fixed remapping to screen palette.

  * Version 5.0

       * Added LINEAR parameter.

       * Added WHITE0 parameter.

  * Version 4.2

       * Minor fix to HAM6 and HAM8 saving.

  * Version 4.1

       * Removed MPGui docs and includes. Now in seperate archive.

       * Can now load and save PNG images.

       * Added documentation of NOPROGRESS parameter.

       * Added 68000 version.

       * Gives an error when PUBSCREEN does not exist.

       * Now loads P1 and P4 images.

       * Fixed remapping of grey scale white to screen.

       * Added MINX, MINY, MAXX and MAXY parameters.

       * Can now correctly load HAM8 images on non AGA.

  * Version 4.0

       * Included multiple library versions and Installer script.

       * Included source code to ConvertMPImage.

       * Included Autodocs and includes for MPGui.library and MPImage.library.

       * MPImage.library can now be called by more than one caller.

       * MPGui.library now tries to create requesters in columns if screen not deep enough.

       * Added option to view on a screen.

       * Fixed a bug when scaling EGS images.

       * Included other docs.

       * MPImage.library now show progress requester unless loading without remapping.

       * Checkboxes now scale.

       * Listviews have selectable number of items displayed.

       * Uses env:mpimage/djpeg for non bitmap jpegs and env:mpimage/cjpeg.

       * Added FORCEGREY parameter.

       * Added GUI parameter.

       * Fixed loading of 24bit ILBMs (used to hang).

  * Version 3.3

       * Initial release

Copyright and distribution requirements
***************************************

      MPImage - Amiga Image Load/Conversion program
      Copyright (C) © 1996 Mark John Paddock

      This program is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published by
      the Free Software Foundation; either version 2 of the License, or
      any later version.

      This program is distributed in the hope that it 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 this program; if not, write to the Free Software
      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

      mark@topic.demon.co.uk
      mpaddock@cix.compulink.co.uk

MPImage 5.1 is copyright © 1996 Mark John Paddock.

I can be contacted at:

mark@topic.demon.co.uk or mpaddock@cix.compulink.co.uk.

It can be freely distributed.

The palette construction is from Dr Dobbs Journal and is Copyright (c) Truda Software by Anton Kruger.

              215 Marengo Rd, #2,
              Oxford, IA 52322-9383

The chunky<->planar conversion is by Morten Eriksen (mortene@stud.unit.no).