MPRender 4.8 Contents
*********************

@Remark $VER: MPRender_guide 4.8 (18.3.97)

Parameters to MPRender
**********************

The following parameters can be supplied.

See @{"MPMorph.guide" link "MPMorph.guide/Main"} on how to supply them.

FILES=filename
==============

This is only relevant to the Shell, only one name can be supplied - default is to show an ASL file requester for the file to run.

DX=number
=========

This parameter can be used to speed up the rendering process. The default value is 0.

If set to a number then only some Horizontal pixels will be generated. e.g. if set to 3 then only every 4th pixel will be generated. The others will be copied from the previous pixel. This can be overridden by using ARexx. Also see DY.

DY=number
=========

This parameter can be used to speed up the rendering process. The default value is 0.

If set to a number then only some Vertical pixels will be generated. e.g. if set to 1 then only every other line will be generated. The others will be copied from the previous line. This can be overridden by using ARexx. Also see DX.

ANTIALIAS=NO/YES
================

This parameter and menu item select if the output files should be Anti-Aliased. Setting to YES can improve the quality of the images but will slow down the rendering process.

This parameter is ignored if INTEGER is set to YES.

Default value is NO.

INTEGER=NO/YES
==============

This parameter and menu item select if the render process should use integer or floating point arithmetic. The process will be faster if integer arithmetic is used (especially on machines without an FPU). However the output quality will not be so good.

If this parameter is set to YES then the ANTIALIAS parameter is ignored.

Default value is NO for CPUs without an FPU, YES for CPUs with an FPU.

MODE=0-15
=========

This parameter and menu item indicate how the Morphing algorithm should search to find the points to use for morphing.

The values are additive:

        1 : Leaves un-triangled point stationary
        2 : Precalculate close points
        4 : Searches all the closest points
        8 : Uses a Delaunay algorithm to find triangles

Default value is 0.

DEPTH=number
============

This parameter indicates how deep the Morphing algorithm should search to find the points to use for morphing. The maximum value is 20 (higher values are accepted but will be taken as 20).

SAVEFORMAT=xxx
==============

This parameter and menu item specify the format MPRender should use to save the output images.

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.

PPM format is basically uncompressed 24 bit. The files are therefore very large and it is suggested that a compressing file handler (such as XFH or EPU) is used. This format is provided mainly to allow the easy production of MPEG movies.

MODENAME=xxx
============

If the SAVEFORMAT 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.

COLOURS=number
==============

if SAVEFORMAT 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 then the default is the number of colours in the PALETTE file or 16 if no palette is supplied.

PALETTE=filename
================

If SAVEFORMAT 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.

12BIT=YES/NO
============

If SAVEFORMAT 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.

QUICKGREY=YES/NO
================

If the input files are greyscale and this is set to YES then the rendering will be quicker. Set to NO if the ARexx scripts alter the colours.

FORCEGREY=YES/NO
================

This forces the render to be done in greyscale, speeding up the rendering.

PUBSCREEN=pubscreenname
=======================

This gives the name of the Public Screen on which to open MPRender windows - default is the default public screen.

LOADSCRIPT=Scriptname/OFF
=========================

This specifies the name of an ARexx script to run before each image 24 bit image is loaded. This can be used to e.g. hold the images on disc in JPEG format to save space and convert each image back to 24 bit ILBM when required. Note however that MPRender now has the ability to load a large variety of image formats.

The default script is:

@{"Loadscript.MPM" link "Rexx/Loadscript.MPM/Main"}.

The version supplied does nothing.

Set to OFF to run no script.

PRESCRIPT=Scriptname/OFF
========================

This specifies the name of an ARexx script to run before each image is rendered. This can be used to produce only some of the frames and control the movement and colour of the images.

The default script is:

@{"Prescript.MPM" link "Rexx/Prescript.MPM/Main"}.

The version supplied does nothing.

Set to OFF to run no script.

POSTSCRIPT=Scriptname/OFF
=========================

This specifies the name of an ARexx script to run after each image is rendered. This can be used to build an animation or change the image format from 24 bit.

The default script is:

@{"Postscript.MPM" link "Rexx/Postscript.MPM/Main"}.

The version supplied does nothing.

Set to OFF to run no script.

CREATEICONS=NO/YES
==================

This paramete selects if Icons are to be saved with image files. If it is YES then an Icon will be saved.

The following Icon is used (selected in order):

     ENV:MPMorph/def_pic.info
     ENV:SYS/def_pic.info
     Default Project Icon

Default value is NO.

EGS=YES/NO
==========

If this is set to YES then an EGS preview is shown when rendering.

PORTNAME=name
=============

This gives the name of the ARexx port to open.

The default is MPRENDER.

See @{"MPRender-rexx" link "MPRender-rexx/main"}.

TOOLPRI=number
==============

This can only be supplied as a Tool Icon tool type. It sets the priority of the rendering process.

Setting to -1 is a good idea if you wish to run the program in the background. The default value is 0. Setting to positive values is generally not a good idea.

NOPROGRESS=YES/NO
=================

If this is set to YES then the progress window just shows the Stop gadget.

PROGRESSHOOK=number
===================

This specifies the address of a progress hook to call to display messages and progress. See MPMorph Rexx GetAttr Hook. This should always remain valid when MPRender is running.

MPRender Requesters
*******************

The following requesters are displayed:

Progress Requester
==================

This displays progress messages and a stop button.

Quit Requester
==============

This is displays a confirmation when trying to quit MPRender.

Errors from MPRender
********************

The following message can be displayed:

Error - Unable to Open xxxx.library(n)
======================================

The library xxxx version number n could not be opened. It could just be a lack of memory.

Resolution - Ensure you are running at least version 3.0 of the operating system, or free up some memory and retry.

Error - Error AllocVec for output
=================================

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Error Opening points file
=================================

The input file specified to MPRender does not exist or is in an invalid format.

Resolution - Either specify a valid input file, or manually edit the points file.

Error - Error opening progress window
=====================================

Some error occurred opening the Progress requester in MPRender. Probably a lack of memory, or the PUBSCREEN parameter specifies a not open public screen name.

Resolution - Free up some memory or correct the parameter and retry.

Error - Invalid file format - Line 'xxxx'
=========================================

The points file being loaded is in an incorrect format or is not a points file.

Resolution - Specify a correct points file or manually edit the file and retry.

Error - Point out of range - Line 'xxxx'
========================================

The point coordinates specified in the input file is larger than the image size.

Resolution - Manually edit the input file and retry.

Error - Out of memory for points
================================

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Error closing file 'xxxx'
=================================

The file xxxx could not be successfully closed. The disc may be full.

Resolution - If saving then save the file to a different disk or free up some disk space and retry with another name. The original file may not be accessible until after a reboot.

Error - Must have at least 3 points
===================================

In order to correctly render an image at least 3 points must be defined.

Resolution - Use MPMorph to define at least 3 points - e.g. in 3 of the corners.

Error - Error opening file 'xxxx'
=================================

The file xxxx could not be opened. The file does not exist (when reading), the name is invalid, the file is already in use, or the disk is write protected.

Resolution - Use a different file name or allow the disk to be written to.

Error - Error sending ARexx message - 'xxxx'
============================================

MPRender has had a problem sending the ARexx message. ARexx may not be running, or the script may not exist or have errors.

Resolution - Ensure ARexx is running, check the scripts - See parameters PRESCRIPT, POSTSCRIPT and LOADSCRIPT exist and have MPM as a suffix.

If the above is OK then use TCO and TS to interactively trace the script.

Error - Assuming version 1.0 file format
========================================

The current version of the File Format has a header record. This error is saying no header is present, it is assumed that the file is in an old format.

Resolution - Select OK to continue. Load and Save in MPMorph to save in the new format if required.

Error - Loading image
=====================

There has been a problem loading an image. The message should provide more information.

Error - Saving image
====================

There has been a problem saving an image. The message should provide more information.

Error - Scaling image
=====================

There has been a problem loading an image. The message should provide more information.

ARexx interface to MPRender
***************************

There is a full ARexx interface to MPRender.

See @{"MPRender-rexx" link "MPRender-rexx/main"}.

Also see the example scripts supplied.

ARexx scripts are run before and after each image is rendered, and before each 24 bit image is loaded. The script names can be supplied as parameters (LOADSCRIPT, PRESCRIPT and POSTSCRIPT) to MPRender.

The suffix to each ARexx script should be .MPM.

ARexx script run before loading 24 bit image
============================================

This script is run before each 24 bit ILBM image is loaded.

It is passed the following parameters:

     Frame       : The current frame number.
     TotalFrames : The total number of frames being rendered.
     Single      : Set to 1 if a Warp, 0 for a Morph, 2 for Anim Morph, 3 for Anim Warp.
     Image       : Set to 0 for 1st image, 1 for second.
     FileName    : Name of file just rendered.

This script can be used to change the format of the input file (by running it through a conversion program).

One example is included:

     @{"Loadscript.MPM" ALINK "Rexx/Loadscript.MPM/Main"} - Do nothing example

ARexx script run before rendering
=================================

This script is run before each image is rendered.

It is also called for the first image (for warps and morphs) and for the last image (for morphs). By default the first and last frames are not rendered. Produce will need to be set to 1 to output these frames. This allows the first and last frames to be converted to the same format as the other output images.

It is passed one parameter - Base - the address of a structure which contains the following:

     Frame       = 0  : The current frame number, starting at 1 (0 for 1st frame) - read only.
     TotalFrames = 1  : The total number of frames being rendered - read only.
     Single      = 2  : Set to 1 if a Warp, 0 = Morph, 2 = Anim Morph, 3 = Anim Warp - read only.
     Movement    = 3  : 0 to 1024 - the proportion of movement from first to second image.
     Red1        = 4  : 0 to 1024 - the proportion of Image 1 Red to use.
     Green1      = 5  : As Red1 for Green.
     Blue1       = 6  : As Red1 for Blue.
     Red2        = 7  : 0 to 1024 - the proportion of Image 2 Red to use.
     Green2      = 8  : As Red2 for Green.
     Blue2       = 9  : As Red2 for Blue.
     Produce     = 10 : Set to 0 to not render this frame, 1 otherwise.
     RPlus       = 11 : 0 to 255 to add to Red in rendered image.
     GPlus       = 12 : As RPlus for Green.
     BPlus       = 13 : As RPlus for Blue.
     RMinus      = 14 : 0 to 255 to subtract from Red in rendered image.
     GMinus      = 15 : As RMinus for Green.
     BMinus      = 16 : As RMinus for Blue.
     DX          = 17 : 0 to ? - X amount to skip - see parameters.
     DY          = 18 : 0 to ? - Y amount to skip - see parameters.
     Start       = 19 : Starting frame number.

The values of these parameters may be set and read using the SetAttr and GetAttr functions.

     Movement            : (1024 * Frame)/(TotalFrames + 1) Morphs
                           (1024 * Frame)/TotalFrames       Warps

     Red1,Green1,Blue1   : Movement                         Morphs
                           1024                             Warps

     Red2,Green2,Blue2   : (1024 - Movement)                Morphs
                           0                 Irrelevant for Warps

     Produce             : 1                                Rendered frames
                           0                 Frames 0 and TotalFrames+1
     RPlus,GPlus,BPlus   : 0
     RMinus,GMinus,BMinus: 0
     DX,DY               : Initially set by DX and DY parameters

Changing these values allows acceleration of movement, colour fades etc. and the generation of only some images (to check a long animation).

Example scripts included are:

     @{"FadeToBlack.MPM" ALINK "Rexx/FadeToBlack.MPM/Main"} - Warp fade to black
     @{"FadeToWhite.MPM" ALINK "Rexx/FadeToWhite.MPM/Main"} - Warp fade to white
     @{"PixelMorph.MPM" ALINK "Rexx/PixelMorph.MPM/Main"}  - Morph by pixelating
     @{"PixelWarp.MPM" ALINK "Rexx/PixelWarp.MPM/Main"}   - Warp pixelating
     @{"PreAll.MPM" ALINK "Rexx/PreAll.MPM/Main"}      - Render all images
     @{"Prescript.MPM" ALINK "Rexx/Prescript.MPM/Main"}   - Do nothing example

ARexx script run after rendering
================================

This script is run after each image is rendered.

It is passed the following parameters:

     Frame       : The current frame number.
     TotalFrames : The total number of frames being rendered.
     Single      : Set to 1 if a Warp, 0 for a Morph.
     FileName    : Name of file just rendered.

This script can be used to change the format of the output file (by running it through a conversion program) or build an animation.

Three examples are included:

     @{"PostAnim.MPM" ALINK "Rexx/PostAnim.MPM/Main"}   - Convert to Anim
     @{"Postscript.MPM" ALINK "Rexx/Postscript.MPM/Main"} - Do nothing example
     @{"ToHam.MPM" ALINK "Rexx/ToHam.MPM/Main"}      - Convert using PPM and Wasp

Morphing Algorithms
*******************

The morphing algorithm is defined using the parameters MODE and DEPTH to MPRender.

The basic algorithm is to find 3 points which make a triangle around the point and morph this triangle between the start and end images.

The DEPTH parameter controls how many points will be checked to form a triangle. 0 means just the closest 3 points are examined, 1 the closest 4, 2 the closest 5 etc.

The MODE parameter controls both which triangle is chosen and what to do if no surrounding triangle is found.

If MODE=0 2 4 ... 14 (i.e. bit 1 not set [do not add 1]) then if no triangle surrounding the point is found examining the closest points then the 3 closest points are used to decide how to morph. Otherwise the point is assumed to be stationery.

If MODE=2 3 4 ... 15 (i.e. bit 2 set [add 2]) then the closest triangles are only calculated once at the start (based on the average of start and end). This should only be used if the points do not move a lot between the start and end images. It can speed things up a lot for a lot of frames. It does not make sense to use this for Animated Warps/Morphs. This uses a lot of memory:

If MODE=2 3 6 7 ... 30 31 (i.e. bit 2 set [add 2]) then all the closest points (the exact number controlled by DEPTH) are examined to determine the smallest triangle. Otherwise the first surrounding triangle found is used.

If MODE=8 9 10 ... (i.e. bit 4 set [add 8]) then a Delauany triangle algorithm is used to find triangles. For these modes the DEPTH parameter should normally be set to 0. Also floating point calculations are still done even if INTEGER is set to YES.

Setting precalculate can use a lot of memory. e.g.

         (DEPTH + 4) * Image_Width * Image_Height * 4

         e.g. 640x512 image, DEPTH=2 uses 7.5 MB (contiguous) memory

The DEPTH parameter can have a major effect on the rendering speed.