1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/smil/nsISMILType.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,213 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef NS_ISMILTYPE_H_
1.10 +#define NS_ISMILTYPE_H_
1.11 +
1.12 +#include "mozilla/Attributes.h"
1.13 +#include "nscore.h"
1.14 +
1.15 +class nsSMILValue;
1.16 +
1.17 +//////////////////////////////////////////////////////////////////////////////
1.18 +// nsISMILType: Interface for defining the basic operations needed for animating
1.19 +// a particular kind of data (e.g. lengths, colors, transformation matrices).
1.20 +//
1.21 +// This interface is never used directly but always through an nsSMILValue that
1.22 +// bundles together a pointer to a concrete implementation of this interface and
1.23 +// the data upon which it should operate.
1.24 +//
1.25 +// We keep the data and type separate rather than just providing different
1.26 +// subclasses of nsSMILValue. This is so that sizeof(nsSMILValue) is the same
1.27 +// for all value types, allowing us to have a type-agnostic nsTArray of
1.28 +// nsSMILValue objects (actual objects, not pointers). It also allows most
1.29 +// nsSMILValues (except those that need to allocate extra memory for their
1.30 +// data) to be allocated on the stack and directly assigned to one another
1.31 +// provided performance benefits for the animation code.
1.32 +//
1.33 +// Note that different types have different capabilities. Roughly speaking there
1.34 +// are probably three main types:
1.35 +//
1.36 +// +---------------------+---------------+-------------+------------------+
1.37 +// | CATEGORY: | DISCRETE | LINEAR | ADDITIVE |
1.38 +// +---------------------+---------------+-------------+------------------+
1.39 +// | Example: | strings, | path data? | lengths, |
1.40 +// | | color k/words?| | RGB color values |
1.41 +// | | | | |
1.42 +// | -- Assign? | X | X | X |
1.43 +// | -- Add? | - | X? | X |
1.44 +// | -- SandwichAdd? | - | -? | X |
1.45 +// | -- ComputeDistance? | - | - | X? |
1.46 +// | -- Interpolate? | - | X | X |
1.47 +// +---------------------+---------------+-------------+------------------+
1.48 +//
1.49 +
1.50 +class nsISMILType
1.51 +{
1.52 + /**
1.53 + * Only give the nsSMILValue class access to this interface.
1.54 + */
1.55 + friend class nsSMILValue;
1.56 +
1.57 +protected:
1.58 + /**
1.59 + * Initialises aValue and sets it to some identity value such that adding
1.60 + * aValue to another value of the same type has no effect.
1.61 + *
1.62 + * @pre aValue.IsNull()
1.63 + * @post aValue.mType == this
1.64 + */
1.65 + virtual void Init(nsSMILValue& aValue) const = 0;
1.66 +
1.67 + /**
1.68 + * Destroys any data associated with a value of this type.
1.69 + *
1.70 + * @pre aValue.mType == this
1.71 + * @post aValue.IsNull()
1.72 + */
1.73 + virtual void Destroy(nsSMILValue& aValue) const = 0;
1.74 +
1.75 + /**
1.76 + * Assign this object the value of another. Think of this as the assignment
1.77 + * operator.
1.78 + *
1.79 + * @param aDest The left-hand side of the assignment.
1.80 + * @param aSrc The right-hand side of the assignment.
1.81 + * @return NS_OK on success, an error code on failure such as when the
1.82 + * underlying type of the specified object differs.
1.83 + *
1.84 + * @pre aDest.mType == aSrc.mType == this
1.85 + */
1.86 + virtual nsresult Assign(nsSMILValue& aDest,
1.87 + const nsSMILValue& aSrc) const = 0;
1.88 +
1.89 + /**
1.90 + * Test two nsSMILValue objects (of this nsISMILType) for equality.
1.91 + *
1.92 + * A return value of true represents a guarantee that aLeft and aRight are
1.93 + * equal. (That is, they would behave identically if passed to the methods
1.94 + * Add, SandwichAdd, ComputeDistance, and Interpolate).
1.95 + *
1.96 + * A return value of false simply indicates that we make no guarantee
1.97 + * about equality.
1.98 + *
1.99 + * NOTE: It's perfectly legal for implementations of this method to return
1.100 + * false in all cases. However, smarter implementations will make this
1.101 + * method more useful for optimization.
1.102 + *
1.103 + * @param aLeft The left-hand side of the equality check.
1.104 + * @param aRight The right-hand side of the equality check.
1.105 + * @return true if we're sure the values are equal, false otherwise.
1.106 + *
1.107 + * @pre aDest.mType == aSrc.mType == this
1.108 + */
1.109 + virtual bool IsEqual(const nsSMILValue& aLeft,
1.110 + const nsSMILValue& aRight) const = 0;
1.111 +
1.112 + /**
1.113 + * Adds two values.
1.114 + *
1.115 + * The count parameter facilitates repetition.
1.116 + *
1.117 + * By equation,
1.118 + *
1.119 + * aDest += aValueToAdd * aCount
1.120 + *
1.121 + * Therefore, if aCount == 0, aDest will be unaltered.
1.122 + *
1.123 + * This method will fail if this data type is not additive or the value was
1.124 + * not specified using an additive syntax.
1.125 + *
1.126 + * See SVG 1.1, section 19.2.5. In particular,
1.127 + *
1.128 + * "If a given attribute or property can take values of keywords (which are
1.129 + * not additive) or numeric values (which are additive), then additive
1.130 + * animations are possible if the subsequent animation uses a numeric value
1.131 + * even if the base animation uses a keyword value; however, if the
1.132 + * subsequent animation uses a keyword value, additive animation is not
1.133 + * possible."
1.134 + *
1.135 + * If this method fails (e.g. because the data type is not additive), aDest
1.136 + * will be unaltered.
1.137 + *
1.138 + * @param aDest The value to add to.
1.139 + * @param aValueToAdd The value to add.
1.140 + * @param aCount The number of times to add aValueToAdd.
1.141 + * @return NS_OK on success, an error code on failure.
1.142 + *
1.143 + * @pre aValueToAdd.mType == aDest.mType == this
1.144 + */
1.145 + virtual nsresult Add(nsSMILValue& aDest,
1.146 + const nsSMILValue& aValueToAdd,
1.147 + uint32_t aCount) const = 0;
1.148 +
1.149 + /**
1.150 + * Adds aValueToAdd to the underlying value in the animation sandwich, aDest.
1.151 + *
1.152 + * For most types this operation is identical to a regular Add() but for some
1.153 + * types (notably <animateTransform>) the operation differs. For
1.154 + * <animateTransform> Add() corresponds to simply adding together the
1.155 + * transform parameters and is used when calculating cumulative values or
1.156 + * by-animation values. On the other hand SandwichAdd() is used when adding to
1.157 + * the underlying value and requires matrix post-multiplication. (This
1.158 + * distinction is most clearly indicated by the SVGT1.2 test suite. It is not
1.159 + * obvious within the SMIL specifications.)
1.160 + *
1.161 + * @param aDest The value to add to.
1.162 + * @param aValueToAdd The value to add.
1.163 + * @return NS_OK on success, an error code on failure.
1.164 + *
1.165 + * @pre aValueToAdd.mType == aDest.mType == this
1.166 + */
1.167 + virtual nsresult SandwichAdd(nsSMILValue& aDest,
1.168 + const nsSMILValue& aValueToAdd) const
1.169 + {
1.170 + return Add(aDest, aValueToAdd, 1);
1.171 + }
1.172 +
1.173 + /**
1.174 + * Calculates the 'distance' between two values. This is the distance used in
1.175 + * paced interpolation.
1.176 + *
1.177 + * @param aFrom The start of the interval for which the distance should
1.178 + * be calculated.
1.179 + * @param aTo The end of the interval for which the distance should be
1.180 + * calculated.
1.181 + * @param aDistance The result of the calculation.
1.182 + * @return NS_OK on success, or an appropriate error code if there is no
1.183 + * notion of distance for the underlying data type or the distance
1.184 + * could not be calculated.
1.185 + *
1.186 + * @pre aFrom.mType == aTo.mType == this
1.187 + */
1.188 + virtual nsresult ComputeDistance(const nsSMILValue& aFrom,
1.189 + const nsSMILValue& aTo,
1.190 + double& aDistance) const = 0;
1.191 +
1.192 + /**
1.193 + * Calculates an interpolated value between two values using the specified
1.194 + * proportion.
1.195 + *
1.196 + * @param aStartVal The value defining the start of the interval of
1.197 + * interpolation.
1.198 + * @param aEndVal The value defining the end of the interval of
1.199 + * interpolation.
1.200 + * @param aUnitDistance A number between 0.0 and 1.0 (inclusive) defining
1.201 + * the distance of the interpolated value in the
1.202 + * interval.
1.203 + * @param aResult The interpolated value.
1.204 + * @return NS_OK on success, NS_ERROR_FAILURE if this data type cannot be
1.205 + * interpolated or NS_ERROR_OUT_OF_MEMORY if insufficient memory was
1.206 + * available for storing the result.
1.207 + *
1.208 + * @pre aStartVal.mType == aEndVal.mType == aResult.mType == this
1.209 + */
1.210 + virtual nsresult Interpolate(const nsSMILValue& aStartVal,
1.211 + const nsSMILValue& aEndVal,
1.212 + double aUnitDistance,
1.213 + nsSMILValue& aResult) const = 0;
1.214 +};
1.215 +
1.216 +#endif // NS_ISMILTYPE_H_
