SVG Properties

What is an SVG property?

It is a storage for data type which can be primitive, DOM type or SVG type. Example of primitive types are int, float, boolean. Examples for DOM type is DOMString. And examples for SVG types are SVGNumber, SVGNumberList, SVGLength, SVGLengthList, SVGAngle, SVGPoint, SVGPointList.

What is so special about SVG property?

1. It has to provide a DOM interface. The interface can get or set its value similar to getAttribute() and setAttribute() methods.
2. It has to be RefCounted because the DOM object will encapsulate the same SVG property and this DOM object can outlive the owner element.
3. It is a reflection of a DOM attribute. Two cases have to be handled:
   1. When setAttribute() called for the underlaying attribute, SVGElement::parseAttribute() will be called to update the SVG property. Then SVGElement::svgAttributeChanged() is called to invalidate the renderer and the dependent SVG objects.
   2. When the SVG property is changed through the DOM interface. This change will be handled in two steps:
      • The commit step which is called immediately after changing the property's value. It will mark the value of the underlaying attribute to be invalid and it will call SVGElement::svgAttributeChanged().
      • The synchronize step which happens later when the value of attribute is required. The valueAsString() of the SVG property is set as the attribute value. In other words, synchronizing the attribute value is lazily updated from the reflection SVG property only when it is needed.
4. Most of the properties are animated properties. The animated property has two members baseVal() and the animal(). Each of them are from the same SVG property type. animal() differs from baseVal() only when animating. Otherwise they have to be the same value.
5. The animal() of the animated property is read only; no changes from the DOM is allowed.
6. The SVG property can be attached to an SVGElement or it can be detached.
   • When the property is attached, a change in its value has to be synchronized with the attribute value.
   • When the property is detached, a change in its value has no effect on any other element.
7. Some properties are SVG lists of SVG types, e.g. SVGNumberList and SVGPointList. In addition of having the list itself Refcounted, all the items of this list have to be RefCounted also. The items can outlive the owner list and the owner list.

SVG Tear-Off objects

The old design of managing the SVG properties relied on storing only the underlaying data in the SVG element. For example, the SVGRectElement was storing an an SVGLengthValue for the baseVal of 'x' property. When the property is requested from the DOM an SVGAnimatedLength has to be constructed. Constructing the SVGAnimatedLength happens through creating and caching an animated SVG tear-off object. The animated tear-off object is a RefCounted and it holds two SVGLength objects for the baseVal and the animVal. The SVGLength object is another type of tear-off objects. This design has many flaws:

1. The animated tear off objects are cached in a hash table outside of the SVGElement although it holds a raw pointer to the property raw data in the SVGElement.
2. It was difficult to deal with optional properties, for example the 'stdDeviation' property of SVGFEGaussianBlurElement. This is because the key of hash table is the pair <SVGElement, attributeName>
3. It was difficult to deal with list properties, for example the 'x' property of SVGTextPositioningElement. The individual items of the SVG tear off object holds raw pointers to the raw data items in the SVGElement. It becomes even more difficult when animating. The animVal tear off list owns the values of the items while the baseVal tear off list items hold pointers to the raw data which is held by the SVGElement.
4. When animating, SVGAnimateElementBase creates SVGAnimatedType objects for from, to, toAtEndOfDuration and current values. The SVGAnimatedType is basically a union of raw pointers to the raw data. The current SVGAnimatedType points to the raw data stored by the animVal of the SVG tear off objects. The rest of the SVGAnimatedType objects points to raw data created by the SVGAnimator when parsing the from, to and toAtEndOfDuration strings.

New Design for the SVG properties

The goal of the new design is to make the life cycle of the SVG properties clear. It has to well define the relationship between the property and its owner such that synchronizing the change in the property with the SVGElement becomes straightforward.

• The SVGElement will own the RefCounted animated SVG property which will own the RefCounted SVG properties for the baseVal and the animVal. This eliminates the need to cache the animated SVG property outside the SVGElement like what the SVG tear off objects were doing.
• If the property is of list of an SVG type, the items will be RefCounted of the SVG type.
• The properties will be registered once by the owner SVGElement to associate a pointer to a member in the SVGElement with an attributeName.
• The property registry will create an accessor for every property. The accessor knows how to get the property value when it is given a pointer to an SVGElement.
• The SMIL animation is carried out by new types of SVGAnimator. The SVGAnimator calculates the new value of the animVal by the SVGAnimationFunction. The SVGAnimator commits the change in the animVal by invalidating the SVGElement. The SVG renderer will get the new animVal when it gets the property value and the SVGElement finds that the property is being animated.

Mechanic of the SVG property

1. Define the property registry of the element such that it associate the class with its all superclasses. And define a member of this type. For example the SVGRectElement has this definition and member declartion:

   using PropertyRegistry = SVGPropertyOwnerRegistry<SVGRectElement, SVGGeometryElement, SVGExternalResourcesRequired>;
   PropertyRegistry m_propertyRegistry { *this };
   

2. Override the virtual method propertyRegistry() which will allow the base class SVGElement to perform operations on all the SVG properties of any superclass.

   const SVGPropertyRegistry& propertyRegistry() const final { return m_propertyRegistry; }
   

3. The property of defined in the header file of the SVG element exactly as it is defined in the IDL file. For example, SVGRectElement will have this member

   Ref<SVGAnimatedLength> m_x { SVGAnimatedLength::create(this, LengthModeWidth) };
   

4. Define the following two functions for every property with the same name. The first is one a const function. This function will return the current value. The expectation is this function will be called from the rendering code. So it does not have to get a RefCounted to the animated property. But rather it cares about the current value only. The second one is none const function. The expectation is this function will be called from the DOM interface. So it needs the RefCounted animated property. For example the SVGRectElement will have these two methods for the 'x' property:

   const SVGLengthValue& x() const { return m_x->currentValue(); }
   Ref<SVGAnimatedLength>& x() { return m_x; }
   

5. The SVGAnimatedLength has two members named m_baseVal and m_animVal. Both of them are of type SVGLength.
6. The property is registered only once in the constructor of the SVG element. This registration will associate the data member with the attribute name. For example the constructor of the SVGRectElement will have this statement:

   PropertyRegistry::registerProperty<SVGNames::xAttr, &SVGRectElement::m_x>();
   

7. This statement calls the override method of SVGPropertyOwnerRegistry

   template<const LazyNeverDestroyed<const QualifiedName>& attributeName, Ref<SVGAnimatedLength> OwnerType::*property>
   static void registerProperty()
   {
       registerProperty(attributeName, SVGAnimatedLengthAccessor<OwnerType>::template singleton<property>());
   }
   

8. This registration associates a pointer to a member of SVGRectElement with the attributeName through the SVGAnimatedLengthAccessor.
9. When the animation of an SVG animated property starts, SVGAnimateElementBase asks the SVGPropertyRegistry to create an SVGAnimator for this property. SVGPropertyRegistry finds the property accessor and asks it to create the SVGAnimator. For example, this is the createAnimator method of SVGAnimatedLengthAccessor:

   RefPtr<SVGAnimator> createAnimator(OwnerType& owner, const QualifiedName& attributeName, AnimationMode animationMode, CalcMode calcMode, bool isAccumulated, bool isAdditive) const final
   {
       SVGLengthMode lengthMode = property(owner)->baseVal()->value().unitMode();
       return SVGAnimatedLengthAnimator::create(attributeName, property(owner), animationMode, calcMode, isAccumulated, isAdditive, lengthMode);
   }
   

10. When SVGAnimateElementBase wants to progress the animation, it asks the animator to calculate a new value of the property based on the timeline of the animation. The SVGAnimator asks the SVGAnimationFunction to do so given a reference to the animVal of the property. For example here is the progress() method of SVGAnimatedLengthAnimator:

    void progress(SVGElement* targetElement, float percentage, unsigned repeatCount) final
    {
        m_function.progress(targetElement, percentage, repeatCount, m_animated->animVal()->value());
    }
    

Important classes

Below is a list of some important classes which are used for manipulating the SVG properties.

Class name	Description	Important Methods
SVGProperty	It is a RefCounted object. It is the base of the SVG types: SVGNumber, SVGPoint, SVGRect, SVGMatrix, SVGTransfrom, SVGLength and SVGPathSeg.
SVGPathSeg	It is a special kind of SVGProperty because it is only an abstract class. Only the super classes of it can be created.
SVGPathSegValue	It is a template class of SVGPathSeg with a template parameter pack. All the SVGPathSeg types are derived from this template.
SVGAnimatedProperty	It is the base class of all the animated properties, e.g. SVGAnimatedLength and SVGAnimatedString. It maintains two members baseVal and animVal..
SVGList	It is a template class and which provides the basic DOM interface of an SVG list.
SVGPropertyList	It holds RefCounted items. It is the base class of SVGValuePropertyList and SVGPathSegList.
SVGValuePropertyList	It holds SVG type items, e.g. SVGNumber and SVGPoint.
SVGPathSegList	It is a SVGList of Ref<SVGPathSeg> but it does lazy conversions: from SVGPathByteStream to list of Ref<SVGPathSeg> and from list of Ref<SVGPathSeg> to SVGPathByteStream.
SVGPropertyOwner	It is the base class of all the SVGProperty owners. It is driven by SVGElement, SVGAnimatedProperty, SVGPropertyList and SVGTransform.
SVGPropertyRegistry	It manages the SVGProperties, connect them to their attributes and defines their accessors.
SVGAccessor	It is used to access an SVGProperty in an SVGElement. The accessor can access a pair of SVGProperties if they are associated with the same attribute. One important task of an accessor is creating the SVGAnimator of an SVGAnimatedProperty of an SVGElement.
SVGAnimator	It is responsible of changing the animVal of an SVGAnimatedProperty over a period of time.
SVGAnimationFunction	This is where the new animated value of an SVGAnimator is calculated.