Lutz Gehlen
and 2 contributors

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

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

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

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

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

  • 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

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

  • 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

Copyright 2011 Lutz Gehlen.

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.