/ 
SVG-Rasterize-0.003003
River stage zero No dependents
/ SVG::Rasterize::State

NAME

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

VERSION

Version 0.003003

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 weakened reference to the parent state object.

rasterize

Can only be set at construction time. Stores a weakened 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.

child_states

Readonly attribute (the accessor does not make a copy, though). If rasterization is deferred (see above) then child states store themselves in this list (see push_child_state). Thereby, it is possible to rasterize the subtree when its time comes.

Do not rely on getting an ARRAY reference from the accessor. If no child state has been added, the value will be undef. Consider using shift_child_state.

current_text_position

For a SVG::Rasterize::State object representing a text or textPath element, this attribute saves the current text position, i.e. the coordinates where the next text chunk will be drawn.

A text or textPath element can contain multiple tspan elements and character data sections. All these nodes do not maintain their own current text position, but their rendering updates the current text position of their ancestor text or textPath element. Therefore, the accessor of this attribute has some special behaviour: It only accesses the attribute, if the node represented by this object is a text or textPath element. If this is not the case it calls the accessor of the parent state object. By that, it walks up the state object tree until it reaches the first ancestor text or textPath element. If this does not exist an exception is raised.

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.

push_child_state

$state->push_child_state($child_state)

If rasterization is deferred (see defer_rasterization) then a SVG::Rasterize::State object representing a child node of this one will use this method to add itself to the child_states list. Thereby the subtree of the document can be accessed when the rasterization time comes.

Expects one SVG::Rasterize::State object. Returns the return value of push which is the new number of elements in the child_states list.

shift_child_state

$state = $state->shift_child_state

Shifts an element from the child_states list and returns it. This list is populated while rasterization is deferred (see defer_rasterization). This method is called by the rasterize method of SVG::Rasterize when the time has come to finally render the deferred subtree. If the list is exhausted (or has never been filled) then undef is returned.

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.

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