1Imager::regmach(3)    User Contributed Perl Documentation   Imager::regmach(3)
2
3
4

NAME

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

SYNOPSIS

10       The register machine is a complete rewrite of the stack machine
11       orginally used by Imager::transform(), written for use by
12       Imager::transform2().
13

DESCRIPTION

15       (This document might be a little incoherent.)
16
17       The register machine is a fast implementation of a small instruction
18       set designed for evaluating an arithmetic expression to produce a
19       colour for an image.
20
21       The machine takes as input:
22
23       instructions
24           An array of instructions
25
26       numeric registers
27           An array of numeric registers.  Some registers are initialized as
28           literals.
29
30       colour registers
31           An array of colour registers.  Currently these registers aren't
32           initialized.
33
34       input images
35           An array of Imager i_img pointers.  The getpn operators read pixels
36           from these images.
37
38       The instructions supplied each take up to 4 input numeric or colour
39       registers with a single output numeric or colour register.  The machine
40       attempts to execute instructions as safely as possible, assuming that
41       correct instructions have been provided, eg. the machine protects
42       against divide by zero, but doesn't check register numbers for valid‐
43       ity.
44
45       The final instruction must be a 'ret' instruction, which returns the
46       result ;)
47
48       Adding new instructions
49
50       To add a new instruction:
51
52       1   Add a new opcode to the enumeration in regmach.h - make sure to add
53           comment after the enum name giving the input registers (rX for
54           numeric, pX for colour) that the instruction takes.  These must be
55           in the order that the instruction expects to take the.  Put a let‐
56           ter (r or p) after -> to indicate the result type.
57
58       2   Add a case to regmach.c that executes the instruction.
59
60       3   make
61
62       The makefile should rebuild the Regops.pm file, and your new instruc‐
63       tion will be added as a function.
64
65       If you want to add a single alternative instruction that might take
66       different argument types (it must take the same number of parameters),
67       create another instruction with that name followed by a p.  The current
68       expression parsers explicitly look for such instruction names.
69
70       Future directions
71
72       Conditional and non-conditional jumps to implement iteration.  This
73       will break the current optimizer in Imager::Expr (and the compilers for
74       both expression compilers, for that matter.)
75
76       Complex arithmetic (Addi suggested this one).  This would most likely
77       be a separate machine.  Otherwise we'll have a very significant perfor‐
78       mance loss.
79

WARNINGS

81       If you feed bad 'machine code' to the register machine, you have a good
82       chance of a SIGSEGV.
83
84
85
86perl v5.8.8                       2008-03-28                Imager::regmach(3)