NAME

SVG::Rasterize::Engine - rasterization engine base class

VERSION

Version 0.003008

SYNOPSIS

# explicit construction (unusual)
use SVG::Rasterize::Engine;
my $engine = SVG::Rasterize::Engine->new(width  => 640,
                                         height => 480);

DESCRIPTION

This class defines the interface for rasterization backends. It does not do any rasterization itself. Implementations of rasterization backends should subclass this class.

Warning: Please be aware of that this interface has to be considered rather unstable at this state of the development.

This class is only instantiated by the rasterize method of SVG::Rasterize via one of its subclasses.

INTERFACE

Constructors

new

SVG::Rasterize::Engine->new(%args)

Creates a new SVG::Rasterize::Engine object and calls init(%args). If you subclass SVG::Rasterize::Engine overload init, not new.

init

$cairo->init(%args)

If you overload init, your method should also call this one. It initializes the attributes width and height which are mandatory parameters and have to be non-negative integers.

Backends are also required to validate their init parameters because the engine_args hash given by the user to SVG::Rasterize is handed over to the new constructor of the engine class without validation.

Public Attributes

These following attributes are provided by this class.

width

Can only be set at construction time. Saves the width of the output image.
height

Can only be set at construction time. Saves the height of the output image.

These are the attributes which alternative rasterization engines have to implement.

currently none

Mandatory Methods

The following methods have to be overloaded by subclasses.

draw_path

Expects a SVG::Rasterize::State object and a list of instructions. None of the parameters must be validated, it is expected that this has happened before. Each instruction must be an ARRAY reference with one of the following sets of entries (the first entry is always a letter, the rest are numbers):

M or m, followed by two numbers
Z
L or l, followed by two numbers
H or h, followed by one number
V or v, followed by one number
C or c, followed by six numbers
S or s, followed by four numbers
Q or q, followed by four numbers
T or t, followed by two numbers
A or a, followed by seven numbers

draw_text

Expects the following parameters:

an SVG::Rasterize::State object
the x coordinate of the start of the text

For left-to-right text this is always the left end of the text. Alignment issues have been taken into account before (at least if text_width is implemented. Right-to-left and top-to-bottom text and alignment issues in the absence of a text_width have not been worked out, yet.

If text_width is implemented then the value is always defined. In the absence of a text_width method it will only be defined if an x coordinate has been set explicitly (or at the beginning of a text element where x defaults to 0.
the y coordinated of the text
the rotate value of the text, possibly undef
the text itself

Can be undef which should result in an immediate return.

None of these parameters must be validated. It is assumed that this has been done before.

write

$engine->write(%args)

Writes the rendered image to a file.

Example:

$engine->write(type => 'png', file_name => 'foo.png');

type and file_name must be accepted (but can be ignored, of course). If file_name has a false value, no output is written and a warning may be issued. Besides that, file_name must not validated at all. The user must provide a sane value (whatever that means to him or her).

Optional Methods

The following methods are part of the interface, but do not have to be provided.

text_width

Called with an SVG::Rasterize::State object and the text to render. Returns the width that the rendered text would occupy. The second argument may be undef in which case 0 should be returned.

NB: The base class method throws an exception. The exception is caught by SVG::Rasterize. This behaviour is used to determine if this method is implemented by the engine or not.

draw_rect

If this method is not implemented then an equivalent call to draw_path is used. If closed paths are implemented by the engine there is no real reason to provide this method. Called with the following parameters (for the exact meanings see the SVG specification):

an SVG::Rasterize::State object
the x coordinate in pixel
the y coordinate in pixel
the width in pixel
the height in pixel
the corner x radius in pixel
the corner y radius in pixel

None of these parameters must be validated. It is assumed that this has been done before.

draw_circle

an SVG::Rasterize::State object
the center x coordinate in pixel
the center y coordinate in pixel
the radius in pixel

None of these parameters must be validated. It is assumed that this has been done before.

draw_ellipse

an SVG::Rasterize::State object
the center x coordinate in pixel
the center y coordinate in pixel
the x radius in pixel
the y radius in pixel

None of these parameters must be validated. It is assumed that this has been done before.

draw_line

an SVG::Rasterize::State object
the x coordinate of the start point in pixel
the y coordinate of the start point in pixel
the x coordinate of the end point in pixel
the y coordinate of the end point in pixel

None of these parameters must be validated. It is assumed that this has been done before.

draw_polyline

an SVG::Rasterize::State object
reference to an array of points (each is ARRAY reference with two numbers)

None of these parameters must be validated. It is assumed that this has been done before.

draw_polygon

an SVG::Rasterize::State object
reference to an array of points (each is ARRAY reference with two numbers)

None of these parameters must be validated. It is assumed that this has been done before.

DIAGNOSTICS

Exceptions

Warnings

INTERNALS

Internal Methods

These methods are just documented for myself. You can read on to satisfy your voyeuristic desires, but be aware of that they might change or vanish without notice in a future version.

make_ro_accessor

This piece of documentation is mainly here to make the POD coverage test happy. SVG::Rasterize::State overloads make_ro_accessor to make the readonly accessors throw an exception object (of class SVG::Rasterize::Exception::Attribute) instead of just croaking.

AUTHOR

Lutz Gehlen, <perl at lutzgehlen.de>

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install SVG::Rasterize, copy and paste the appropriate command in to your terminal.

cpanm

cpanm SVG::Rasterize

CPAN shell

perl -MCPAN -e shell
install SVG::Rasterize

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

INTERFACE

Constructors

new

init

Public Attributes

Mandatory Methods

draw_path

draw_text

write

Optional Methods

text_width

draw_rect

draw_circle

draw_ellipse

draw_line

draw_polyline

draw_polygon

DIAGNOSTICS

Exceptions

Warnings

INTERNALS

Internal Methods

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions