summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl0/lib/Imager/regmach.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Imager/regmach.pod')
-rwxr-xr-xMaster/tlpkg/tlperl0/lib/Imager/regmach.pod103
1 files changed, 103 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Imager/regmach.pod b/Master/tlpkg/tlperl0/lib/Imager/regmach.pod
new file mode 100755
index 00000000000..844742d6d8a
--- /dev/null
+++ b/Master/tlpkg/tlperl0/lib/Imager/regmach.pod
@@ -0,0 +1,103 @@
+=head1 NAME
+
+Imager::regmach - documents the register virtual machine used by
+Imager::transform2().
+
+=head1 SYNOPSIS
+
+The register machine is a complete rewrite of the stack machine
+orginally used by Imager::transform(), written for use by
+Imager::transform2().
+
+=head1 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
+colour for an image.
+
+The machine takes as input:
+
+=over 4
+
+=item instructions
+
+An array of instructions
+
+=item numeric registers
+
+An array of numeric registers. Some registers are initialized as
+literals.
+
+=item colour registers
+
+An array of colour registers. Currently these registers aren't
+initialized.
+
+=item input images
+
+An array of Imager i_img pointers. The getpn operators read pixels
+from these images.
+
+=back
+
+The instructions supplied each take up to 4 input numeric or colour
+registers with a single output numeric or colour 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 ;)
+
+=head2 Adding new instructions
+
+To add a new instruction:
+
+=over 4
+
+=item 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 colour) 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.
+
+=item 2
+
+Add a case to regmach.c that executes the instruction.
+
+=item 3
+
+make
+
+=back
+
+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.
+
+=head2 Future directions
+
+Conditional and non-conditional jumps to implement iteration. This
+will break the current optimizer in L<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.
+
+=head1 WARNINGS
+
+If you feed bad 'machine code' to the register machine, you have a
+good chance of a SIGSEGV.
+
+=cut
+