.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::regmach 3pm"
.TH Imager::regmach 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Imager::regmach \- documents the register virtual machine used by
Imager::transform2().
.SH SYNOPSIS
.IX Header "SYNOPSIS"
The register machine is a complete rewrite of the stack machine
originally used by \fBImager::transform()\fR, written for use by
\&\fBImager::transform2()\fR.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
(This document might be a little incoherent.)
.PP
The register machine is a fast implementation of a small instruction
set designed for evaluating an arithmetic expression to produce a
color for an image.
.PP
The machine takes as input:
.IP instructions 4
.IX Item "instructions"
An array of instructions
.IP "numeric registers" 4
.IX Item "numeric registers"
An array of numeric registers.  Some registers are initialized as
literals.
.IP "color registers" 4
.IX Item "color registers"
An array of color registers.  Currently these registers aren't
initialized.
.IP "input images" 4
.IX Item "input images"
An array of Imager i_img pointers.  The \f(CW\*(C`getpn\*(C'\fR operators read pixels
from these images.
.PP
The instructions supplied each take up to 4 input numeric or color
registers with a single output numeric or color 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.
.PP
The final instruction must be a \f(CW\*(C`ret\*(C'\fR instruction, which returns the
result ;)
.SS "Adding new instructions"
.IX Subsection "Adding new instructions"
To add a new instruction:
.IP 1. 4
Add a new opcode to the enumeration in \fIregmach.h\fR \- make sure to add
comment after the enum name giving the input registers (\f(CW\*(C`rX\*(C'\fR for
numeric, \f(CW\*(C`pX\*(C'\fR for color) 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.
.IP 2. 4
Add a case to \fIregmach.c\fR that executes the instruction.
.IP 3. 4
make
.PP
The \fIMakefile\fR should rebuild the \fIRegops.pm\fR file, and your new
instruction will be added as a function.
.PP
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.
.SS "Future directions"
.IX Subsection "Future directions"
Conditional and non-conditional jumps to implement iteration.  This
will break the current optimizer in Imager::Expr (and the compilers
for both expression compilers, for that matter.)
.PP
Complex arithmetic (Addi suggested this one).  This would most likely
be a separate machine.  Otherwise we'll have a very significant
performance loss.
.SH WARNINGS
.IX Header "WARNINGS"
If you feed bad 'machine code' to the register machine, you have a
good chance of a \f(CW\*(C`SIGSEGV\*(C'\fR.
.SH AUTHOR
.IX Header "AUTHOR"
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson