]>
Commit | Line | Data |
---|---|---|
02d1d628 AMH |
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 | |
5715f7c3 | 9 | originally used by Imager::transform(), written for use by |
02d1d628 AMH |
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 | |
5715f7c3 | 18 | color for an image. |
02d1d628 AMH |
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 | ||
5715f7c3 | 33 | =item color registers |
02d1d628 | 34 | |
5715f7c3 | 35 | An array of color registers. Currently these registers aren't |
02d1d628 AMH |
36 | initialized. |
37 | ||
38 | =item input images | |
39 | ||
5715f7c3 | 40 | An array of Imager i_img pointers. The C<getpn> operators read pixels |
02d1d628 AMH |
41 | from these images. |
42 | ||
43 | =back | |
44 | ||
5715f7c3 TC |
45 | The instructions supplied each take up to 4 input numeric or color |
46 | registers with a single output numeric or color register. The | |
02d1d628 AMH |
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 | ||
5715f7c3 | 52 | The final instruction must be a C<ret> instruction, which returns the |
02d1d628 AMH |
53 | result ;) |
54 | ||
55 | =head2 Adding new instructions | |
56 | ||
57 | To add a new instruction: | |
58 | ||
59 | =over 4 | |
60 | ||
61 | =item 1 | |
62 | ||
5715f7c3 TC |
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 | |
02d1d628 AMH |
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 | ||
5715f7c3 | 71 | Add a case to F<regmach.c> that executes the instruction. |
02d1d628 AMH |
72 | |
73 | =item 3 | |
74 | ||
75 | make | |
76 | ||
77 | =back | |
78 | ||
5715f7c3 | 79 | The F<Makefile> should rebuild the F<Regops.pm> file, and your new |
02d1d628 AMH |
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 | |
5715f7c3 | 100 | good chance of a C<SIGSEGV>. |
02d1d628 | 101 | |
8ba1b8a6 TC |
102 | =head1 AUTHOR |
103 | ||
104 | Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson | |
105 | ||
02d1d628 AMH |
106 | =cut |
107 |