SVG::Rasterize::State - state of settings during traversal
SVG::Rasterize::State
Version 0.003007
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.
SVG
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.
$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.
init(%args)
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)
undef
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.
getChildNodes
[@{$node->getChildNodes}]
node (optional): must be a blessed reference; unused, but available for hooks
matrix (optional): must be an ARRAY reference if provided
Can only be set at construction time. Stores a reference to the parent state object.
Can only be set at construction time. Stores a reference to the SVG::Rasterize object.
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).
DOM
node
$node->getAttributes
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).
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->getNodeName
node_name
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.
node_attributes
Can only be set on construction time. If the node is a character data node, those character data can be stored in here.
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, b, c, d, e, f]
( 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.
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.
text
1
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.
$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.
px
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.
$state->map_length($number, $unit)
Currently, relative units are not supported.
($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).
x
y
$x
$y
See new for a description of the interface. If you overload init, your method should also call this one.
init
Alias to multiply_matrices in SVG::Rasterize. The alias is established via the typeglob:
*multiply_matrices = \&SVG::Rasterize::multiply_matrices;
$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.
child_nodes
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.
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.
_process_...
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).
Not documented, yet. Sorry.
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.
transform
Does not take any parameters and does not return anything. Expects that $self->{matrix} is set properly (which it is in _process_node).
$self->{matrix}
_process_viewBox_attribute
Parses the viewBox and preserveAspectRatio attributes (if present) of the current node and modifies the current transformation matrix accordingly.
viewBox
preserveAspectRatio
_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.
style
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.
white
rgb(255, 255, 255)
FFFFFF
FFF
[255, 255, 255]
_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.
ICC
_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.
POD
SVG::Rasterize::Exception::Attribute
Lutz Gehlen, <perl at lutzgehlen.de>
<perl at lutzgehlen.de>
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.
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.