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       originally 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 color
19       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       color registers
31           An array of color registers.  Currently these registers aren't
32           initialized.
33
34       input images
35           An array of Imager i_img pointers.  The "getpn" operators read
36           pixels from these images.
37
38       The instructions supplied each take up to 4 input numeric or color
39       registers with a single output numeric or color 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
43       validity.
44
45       The final instruction must be a "ret" instruction, which returns the
46       result ;)
47
48   Adding new instructions
49       To add a new instruction:
50
51       1.  Add a new opcode to the enumeration in regmach.h - make sure to add
52           comment after the enum name giving the input registers ("rX" for
53           numeric, "pX" for color) that the instruction takes.  These must be
54           in the order that the instruction expects to take the.  Put a
55           letter (r or p) after -> to indicate the result type.
56
57       2.  Add a case to regmach.c that executes the instruction.
58
59       3.  make
60
61       The Makefile should rebuild the Regops.pm file, and your new
62       instruction will be added as a function.
63
64       If you want to add a single alternative instruction that might take
65       different argument types (it must take the same number of parameters),
66       create another instruction with that name followed by a p.  The current
67       expression parsers explicitly look for such instruction names.
68
69   Future directions
70       Conditional and non-conditional jumps to implement iteration.  This
71       will break the current optimizer in Imager::Expr (and the compilers for
72       both expression compilers, for that matter.)
73
74       Complex arithmetic (Addi suggested this one).  This would most likely
75       be a separate machine.  Otherwise we'll have a very significant
76       performance loss.
77

WARNINGS

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

AUTHOR

83       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
84
85
86
87perl v5.34.0                      2022-01-21                Imager::regmach(3)