lib/Imager/regmach.pod

   1 =head1 NAME
   2
   3 Imager::regmach - documents the register virtual machine used by
   4 Imager::transform2().
   5
   6 =head1 SYNOPSIS
   7
   8 The register machine is a complete rewrite of the stack machine
   9 originally used by Imager::transform(), written for use by
  10 Imager::transform2().
  11
  12 =head1 DESCRIPTION
  13
  14 (This document might be a little incoherent.)
  15
  16 The register machine is a fast implementation of a small instruction
  17 set designed for evaluating an arithmetic expression to produce a
  18 color for an image.
  19
  20 The machine takes as input:
  21
  22 =over 4
  23
  24 =item instructions
  25
  26 An array of instructions
  27
  28 =item numeric registers
  29
  30 An array of numeric registers.  Some registers are initialized as
  31 literals.
  32
  33 =item color registers
  34
  35 An array of color registers.  Currently these registers aren't
  36 initialized.
  37
  38 =item input images
  39
  40 An array of Imager i_img pointers.  The C<getpn> operators read pixels
  41 from these images.
  42
  43 =back
  44
  45 The instructions supplied each take up to 4 input numeric or color
  46 registers with a single output numeric or color register.  The
  47 machine attempts to execute instructions as safely as possible,
  48 assuming that correct instructions have been provided, eg. the machine
  49 protects against divide by zero, but doesn't check register numbers
  50 for validity.
  51
  52 The final instruction must be a C<ret> instruction, which returns the
  53 result ;)
  54
  55 =head2 Adding new instructions
  56
  57 To add a new instruction:
  58
  59 =over 4
  60
  61 =item 1
  62
  63 Add a new opcode to the enumeration in F<regmach.h> - make sure to add
  64 comment after the enum name giving the input registers (C<rX> for
  65 numeric, C<pX> for color) that the instruction takes.  These must be in
  66 the order that the instruction expects to take the.  Put a letter (r
  67 or p) after -> to indicate the result type.
  68
  69 =item 2
  70
  71 Add a case to F<regmach.c> that executes the instruction.
  72
  73 =item 3
  74
  75 make
  76
  77 =back
  78
  79 The F<Makefile> should rebuild the F<Regops.pm> file, and your new
  80 instruction will be added as a function.
  81
  82 If you want to add a single alternative instruction that might take
  83 different argument types (it must take the same number of parameters),
  84 create another instruction with that name followed by a p.  The
  85 current expression parsers explicitly look for such instruction names.
  86
  87 =head2 Future directions
  88
  89 Conditional and non-conditional jumps to implement iteration.  This
  90 will break the current optimizer in L<Imager::Expr> (and the compilers
  91 for both expression compilers, for that matter.)
  92
  93 Complex arithmetic (Addi suggested this one).  This would most likely
  94 be a separate machine.  Otherwise we'll have a very significant
  95 performance loss.
  96
  97 =head1 WARNINGS
  98
  99 If you feed bad 'machine code' to the register machine, you have a
 100 good chance of a C<SIGSEGV>.
 101
 102 =head1 AUTHOR
 103
 104 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
 105
 106 =cut
 107