NAME

       Imager::regmach - documents the register virtual machine used by Imager::transform2().

SYNOPSIS

       The register machine is a complete rewrite of the stack machine originally used by
       Imager::transform(), written for use by Imager::transform2().

DESCRIPTION

       (This document might be a little incoherent.)

       The register machine is a fast implementation of a small instruction set designed for
       evaluating an arithmetic expression to produce a color for an image.

       The machine takes as input:

       instructions
           An array of instructions

       numeric registers
           An array of numeric registers.  Some registers are initialized as literals.

       color registers
           An array of color registers.  Currently these registers aren't initialized.

       input images
           An array of Imager i_img pointers.  The "getpn" operators read pixels from these
           images.

       The instructions supplied each take up to 4 input numeric or color registers with a single
       output numeric or color register.  The machine attempts to execute instructions as safely
       as possible, assuming that correct instructions have been provided, eg. the machine
       protects against divide by zero, but doesn't check register numbers for validity.

       The final instruction must be a "ret" instruction, which returns the result ;)

   Adding new instructions
       To add a new instruction:

       1.  Add a new opcode to the enumeration in regmach.h - make sure to add comment after the
           enum name giving the input registers ("rX" for numeric, "pX" for color) that the
           instruction takes.  These must be in the order that the instruction expects to take
           the.  Put a letter (r or p) after -> to indicate the result type.

       2.  Add a case to regmach.c that executes the instruction.

       3.  make

       The Makefile should rebuild the Regops.pm file, and your new instruction will be added as
       a function.

       If you want to add a single alternative instruction that might take different argument
       types (it must take the same number of parameters), create another instruction with that
       name followed by a p.  The current expression parsers explicitly look for such instruction
       names.

   Future directions
       Conditional and non-conditional jumps to implement iteration.  This will break the current
       optimizer in Imager::Expr (and the compilers for both expression compilers, for that
       matter.)

       Complex arithmetic (Addi suggested this one).  This would most likely be a separate
       machine.  Otherwise we'll have a very significant performance loss.

WARNINGS

       If you feed bad 'machine code' to the register machine, you have a good chance of a
       "SIGSEGV".

AUTHOR

       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson