NAME

SVG::Rasterize::State - state of settings during traversal

VERSION

Version 0.003007

DESCRIPTION

An instance of this class saves one state during the traversal through an SVG tree. At encounter of a new child element the old state is pushed to a stack and retrieved later. A state saves the current transformation matrix, style settings and so on. Part of this functionality overlaps with the ability of Cairo to push its state onto a stack, but I do not want to entirely rely on that because I am not sure if everything can be handled in that way and also because future alternative backends might not have this feature.

This class is instanced only by SVG::Rasterize. The information of this document will mainly be interesting for maintainers of SVG::Rasterize and possibly for advanced users who want to write hooks.

INTERFACE

Constructors

new

  $state = SVG::Rasterize::State->new(%args)

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

Supported arguments:

• rasterize (mandatory): SVG::Rasterize object

• parent (optional): the parent state object, always expected except for the root

• node_name (mandatory): defined scalar, name of the current node

• node_attributes (mandatory): HASH reference

• cdata (mandatory): undef or scalar (no reference)

• child_nodes (mandatory): undef or an ARRAY reference

  Array entries are not further validated as they are not used within this object. Do not just provide the return value of getChildNodes on a node object, because modification of the array (e.g. by shift_child_node) will (usually) affect the list saved in the node object itself. Make a copy, e.g. [@{$node->getChildNodes}]. Note that changing the objects in the list will still affect the child nodes saved in the node object unless you perform some kind of deep cloning.

• node (optional): must be a blessed reference; unused, but available for hooks

• matrix (optional): must be an ARRAY reference if provided

Public Attributes

parent

Can only be set at construction time. Stores a reference to the parent state object.

rasterize

Can only be set at construction time. Stores a reference to the SVG::Rasterize object.

node

Can only be set at construction time. If the SVG data to rasterize are provided as an SVG object (or, in fact, some DOM object in general) this attribute stores the node object for which this state object was created. All processing uses the node_name and node_attributes attributes which are always present. It is also recommended that you use these instead of node wherever possible. For example, $node->getAttributes might be undefined or not normalized (see White Space Handling in SVG::Rasterize).

This attribute is only provided for use in hooks. Note that it is not validated. If set at all it holds a blessed reference, but nothing else is checked (within this class).

node_name

Can only be set at construction time. Stores the name of the current node even if node above is undef. If it differs from $node->getNodeName (usage not recommended), node_name is used.

node_attributes

Can only be set at construction time (any arguments to the accessor are silently ignored). Stores the attributes of the current node as a HASH reference even if node above is undef. The accessor does not create a copy of the hash, so changes will affect the hash stored in the object. This is on purpose to give you full control e.g. inside a hook. In case the node has no attributes an empty HASH reference is returned. If the content differs from $node->getAttributes (usage not recommended), node_attributes is used.

cdata

Can only be set on construction time. If the node is a character data node, those character data can be stored in here.

matrix

Readonly attribute (you can change the contents, of course, but this is considered a hack bypassing the interface). Stores an ARRAY reference with 6 numbers [a, b, c, d, e, f] such that the matrix

  ( a  c  e )
  ( b  d  f )
  ( 0  0  1 )

represents the map from coordinates in the current user coordinate system to the output pixel grid. See multiply_matrices in SVG::Rasterize for more background.

Before you use the matrix directly have a look at transform below.

defer_rasterization

Readonly attribute. Some elements (namely text elements) can only be rasterized once their entire content is known (e.g. for alignment issues). If an SVG::Rasterize::State object is initialized with such an element or if the parent state is deferring rasterization then this attribute is set to 1 at construction time. The content is then only rasterized once the root element of this subtree (i.e. the element whose parent is not deferring) is about to run out of scope.

Methods for Users

The distinction between users and developers is a bit arbitrary because these methods are only interesting for users who write hooks which makes them almost a developer.

map_length

  $state->map_length($length)

This method takes a length and returns the corresponding value in px according to the conversion rates described in the ADVANCED TOPICS section of SVG::Rasterize. Surrounding white space is not allowed.

Examples:

  $x = $rasterize->map_length('5.08cm');  # returns 180
  $x = $rasterize->map_length(10);        # returns 10
  $x = $rasterize->map_length('  1in ');  # error
  $x = $rasterize->map_length('50%')      # depends on context

Note that there is no $state->map_length($number, $unit) interface like in map_abs_length in SVG::Rasterize. It can be added on request.

Currently, relative units are not supported.

transform

  ($x_abs, $y_abs) = $state->transform($x, $y)

Takes an x and a y coordinate and maps them from the current user space to the output pixel coordinate system using the current value of matrix. $x and $y can be numbers or lengths (see Lengths versus Numbers in SVG::Rasterize).

Methods for Developers

init

See new for a description of the interface. If you overload init, your method should also call this one.

multiply_matrices

Alias to multiply_matrices in SVG::Rasterize. The alias is established via the typeglob:

  *multiply_matrices = \&SVG::Rasterize::multiply_matrices;

shift_child_node

  $node = $state->shift_child_node

Shifts an element from the child_nodes list and returns it. This list has been populated (or not) at construction time via the child_nodes argument. This will usually only be the case if we are traversing through a DOM tree. If the list is exhausted (or has never been filled) then undef is returned.

Note that the elements of the child_nodes list have not been validated at all as they are not used within this object. They can be anything that has been provided at construction time.

process_node_extra

This method is named without an underscore and mentioned here because it is available for overloading. Logically, it rather belongs to the _process_... methods described under Internal Methods.

Called by _process_node at the very end, does nothing. Only available for overloading to enable subclasses to perform special processing (see e.g. SVG::Rasterize::State::Text).

DIAGNOSTICS

Exceptions

Not documented, yet. Sorry.

Warnings

Not documented, yet. Sorry.

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.

• _process_node

  Called after creation of the state object. Checks for relevant attributes and processes them.

  Does not take any arguments and does not return anything.

• _process_transform_attribute

  Parses the string given in a transform attribute and sets the matrix attribute accordingly.

  Does not take any parameters and does not return anything. Expects that $self->{matrix} is set properly (which it is in _process_node).

• _process_viewBox_attribute

  Parses the viewBox and preserveAspectRatio attributes (if present) of the current node and modifies the current transformation matrix accordingly.

  Does not take any parameters and does not return anything. Expects that $self->{matrix} is set properly (which it is in _process_node).

• _process_style_properties

  Creates a hash with current style properties which are taken from (in order of decreasing preference) the style attribute or the respective property attribute or (if inheritable) from the parent state or from the hash of default values in SVG::Rasterize::Properties.

  Does not take any arguments. Returns the properties HASH reference.

• _process_css_color

  Takes a string that describes a color either as color name (e.g. white) or as RGB expression (e.g. rgb(255, 255, 255)) or as hexadecimal value (e.g. FFFFFF or FFF) and returns an ARRAY reference representing the color ([255, 255, 255] in each of the examples above. Throws an exception if none of the pattern matches.

• _process_direct_color

  I cannot remember why I called the method like this. Takes a color string and a current color. Returns the current color if this is requested. Splits ICC color settings (unsupported) and returns the result of _process_css_color|/_process_css_color.

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

cpanm SVG::Rasterize

perl -MCPAN -e shell
install SVG::Rasterize