Login or Register to Ask a Question and Join Our Community

Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

imager::regmach(3pm) [debian man page]

Imager::regmach(3pm)					User Contributed Perl Documentation				      Imager::regmach(3pm)

NAME

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

SYNOPSIS

       The register machine is a complete rewrite of the stack machine originally used by Imager::transform(), written for use by
       Imager::transform2().

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
       color for an image.

       The machine takes as input:

       instructions
	   An array of instructions

       numeric registers
	   An array of numeric registers.  Some registers are initialized as literals.

       color registers
	   An array of color registers.  Currently these registers aren't initialized.

       input images
	   An array of Imager i_img pointers.  The "getpn" operators read pixels from these images.

       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.

       The final instruction must be a "ret" instruction, which returns the result ;)

   Adding new instructions
       To add a new instruction:

       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 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.

       2.  Add a case to regmach.c that executes the instruction.

       3.  make

       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.

   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.)

       Complex arithmetic (Addi suggested this one).  This would most likely be a separate machine.  Otherwise we'll have a very significant
       performance loss.

WARNINGS

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

perl v5.14.2							    2011-06-06						      Imager::regmach(3pm)

Check Out this Related Man Page

Imager::Transform(3pm)					User Contributed Perl Documentation				    Imager::Transform(3pm)

NAME

	 Imager::Transform - a library of register machine image transformations

SYNOPSIS

	 # get a list of transformations
	 my @funcs = Imager::Transform->list;
	 # create a transformation object
	 my $tran = Imager::Transform->new($name);
	 # describe it
	 print $tran->describe;
	 # a list of constant names
	 my @constants = $tran->constants;
	 # information about some of the constants
	 my @info = $tran->constants(@constants);

DESCRIPTION

       This module provides a library of transformations that use the Imager transform2() function.

       The aim is to provide a place to collect these transformations.

       At some point there might be an interface to add new functions, but there's not a whole lot of point to that.

       The interface is a little sparse as yet.

METHODS

       my @names = Imager::Transform->list
	   Returns a list of the transformations.

       my $desc = Imager::Transform->describe($name);
       my $desc = $tran->describe()
	   Describes a transformation specified either by name (as a class method) or by reference (as an instance method).

	   The class method returns undef if there is no such transformation.

       my $tran = Imager::Transform->new($name)
	   Create a new transformation object.	Returns undef if there is no such transformation.

       my @inputs = $tran->inputs;
       my $inputs = $tran->inputs;
	   Returns a list of input image descriptions, or the number of them, depending on content.

	   The list contains hash references, which current contain only one member, "desc", a description of the use of the input image.

       $tran->constants
	   Returns a list of names of constants that can be set for the transformation.

       $tran->constants($name, $name, ...)
	   Returns a hashref for each named constant, which contains the default in key "default" and a description in key "desc".

       my $out = $tran->transform(\%opts, \%constants, @imgs)
	   Perform the image transformation.

	   Returns the new image on success, or undef on failure, in which case you can use $tran->errstr to get an error message.

       $tran->errstr
	   The error message, if any from the last image transformation.

BUGS

       Needs more transformations.

SEE ALSO

       Imager(3), transform.perl

perl v5.14.2							    2011-06-06						    Imager::Transform(3pm)
Man Page