Line data Source code
1 : /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 : /* This Source Code Form is subject to the terms of the Mozilla Public
4 : * License, v. 2.0. If a copy of the MPL was not distributed with this
5 : * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 :
7 : #ifndef NS_ISMILTYPE_H_
8 : #define NS_ISMILTYPE_H_
9 :
10 : #include "mozilla/Attributes.h"
11 : #include "nscore.h"
12 :
13 : class nsSMILValue;
14 :
15 : //////////////////////////////////////////////////////////////////////////////
16 : // nsISMILType: Interface for defining the basic operations needed for animating
17 : // a particular kind of data (e.g. lengths, colors, transformation matrices).
18 : //
19 : // This interface is never used directly but always through an nsSMILValue that
20 : // bundles together a pointer to a concrete implementation of this interface and
21 : // the data upon which it should operate.
22 : //
23 : // We keep the data and type separate rather than just providing different
24 : // subclasses of nsSMILValue. This is so that sizeof(nsSMILValue) is the same
25 : // for all value types, allowing us to have a type-agnostic nsTArray of
26 : // nsSMILValue objects (actual objects, not pointers). It also allows most
27 : // nsSMILValues (except those that need to allocate extra memory for their
28 : // data) to be allocated on the stack and directly assigned to one another
29 : // provided performance benefits for the animation code.
30 : //
31 : // Note that different types have different capabilities. Roughly speaking there
32 : // are probably three main types:
33 : //
34 : // +---------------------+---------------+-------------+------------------+
35 : // | CATEGORY: | DISCRETE | LINEAR | ADDITIVE |
36 : // +---------------------+---------------+-------------+------------------+
37 : // | Example: | strings, | path data? | lengths, |
38 : // | | color k/words?| | RGB color values |
39 : // | | | | |
40 : // | -- Assign? | X | X | X |
41 : // | -- Add? | - | X? | X |
42 : // | -- SandwichAdd? | - | -? | X |
43 : // | -- ComputeDistance? | - | - | X? |
44 : // | -- Interpolate? | - | X | X |
45 : // +---------------------+---------------+-------------+------------------+
46 : //
47 :
48 0 : class nsISMILType
49 : {
50 : /**
51 : * Only give the nsSMILValue class access to this interface.
52 : */
53 : friend class nsSMILValue;
54 :
55 : protected:
56 : /**
57 : * Initialises aValue and sets it to some identity value such that adding
58 : * aValue to another value of the same type has no effect.
59 : *
60 : * @pre aValue.IsNull()
61 : * @post aValue.mType == this
62 : */
63 : virtual void Init(nsSMILValue& aValue) const = 0;
64 :
65 : /**
66 : * Destroys any data associated with a value of this type.
67 : *
68 : * @pre aValue.mType == this
69 : * @post aValue.IsNull()
70 : */
71 : virtual void Destroy(nsSMILValue& aValue) const = 0;
72 :
73 : /**
74 : * Assign this object the value of another. Think of this as the assignment
75 : * operator.
76 : *
77 : * @param aDest The left-hand side of the assignment.
78 : * @param aSrc The right-hand side of the assignment.
79 : * @return NS_OK on success, an error code on failure such as when the
80 : * underlying type of the specified object differs.
81 : *
82 : * @pre aDest.mType == aSrc.mType == this
83 : */
84 : virtual nsresult Assign(nsSMILValue& aDest,
85 : const nsSMILValue& aSrc) const = 0;
86 :
87 : /**
88 : * Test two nsSMILValue objects (of this nsISMILType) for equality.
89 : *
90 : * A return value of true represents a guarantee that aLeft and aRight are
91 : * equal. (That is, they would behave identically if passed to the methods
92 : * Add, SandwichAdd, ComputeDistance, and Interpolate).
93 : *
94 : * A return value of false simply indicates that we make no guarantee
95 : * about equality.
96 : *
97 : * NOTE: It's perfectly legal for implementations of this method to return
98 : * false in all cases. However, smarter implementations will make this
99 : * method more useful for optimization.
100 : *
101 : * @param aLeft The left-hand side of the equality check.
102 : * @param aRight The right-hand side of the equality check.
103 : * @return true if we're sure the values are equal, false otherwise.
104 : *
105 : * @pre aDest.mType == aSrc.mType == this
106 : */
107 : virtual bool IsEqual(const nsSMILValue& aLeft,
108 : const nsSMILValue& aRight) const = 0;
109 :
110 : /**
111 : * Adds two values.
112 : *
113 : * The count parameter facilitates repetition.
114 : *
115 : * By equation,
116 : *
117 : * aDest += aValueToAdd * aCount
118 : *
119 : * Therefore, if aCount == 0, aDest will be unaltered.
120 : *
121 : * This method will fail if this data type is not additive or the value was
122 : * not specified using an additive syntax.
123 : *
124 : * See SVG 1.1, section 19.2.5. In particular,
125 : *
126 : * "If a given attribute or property can take values of keywords (which are
127 : * not additive) or numeric values (which are additive), then additive
128 : * animations are possible if the subsequent animation uses a numeric value
129 : * even if the base animation uses a keyword value; however, if the
130 : * subsequent animation uses a keyword value, additive animation is not
131 : * possible."
132 : *
133 : * If this method fails (e.g. because the data type is not additive), aDest
134 : * will be unaltered.
135 : *
136 : * @param aDest The value to add to.
137 : * @param aValueToAdd The value to add.
138 : * @param aCount The number of times to add aValueToAdd.
139 : * @return NS_OK on success, an error code on failure.
140 : *
141 : * @pre aValueToAdd.mType == aDest.mType == this
142 : */
143 : virtual nsresult Add(nsSMILValue& aDest,
144 : const nsSMILValue& aValueToAdd,
145 : uint32_t aCount) const = 0;
146 :
147 : /**
148 : * Adds aValueToAdd to the underlying value in the animation sandwich, aDest.
149 : *
150 : * For most types this operation is identical to a regular Add() but for some
151 : * types (notably <animateTransform>) the operation differs. For
152 : * <animateTransform> Add() corresponds to simply adding together the
153 : * transform parameters and is used when calculating cumulative values or
154 : * by-animation values. On the other hand SandwichAdd() is used when adding to
155 : * the underlying value and requires matrix post-multiplication. (This
156 : * distinction is most clearly indicated by the SVGT1.2 test suite. It is not
157 : * obvious within the SMIL specifications.)
158 : *
159 : * @param aDest The value to add to.
160 : * @param aValueToAdd The value to add.
161 : * @return NS_OK on success, an error code on failure.
162 : *
163 : * @pre aValueToAdd.mType == aDest.mType == this
164 : */
165 0 : virtual nsresult SandwichAdd(nsSMILValue& aDest,
166 : const nsSMILValue& aValueToAdd) const
167 : {
168 0 : return Add(aDest, aValueToAdd, 1);
169 : }
170 :
171 : /**
172 : * Calculates the 'distance' between two values. This is the distance used in
173 : * paced interpolation.
174 : *
175 : * @param aFrom The start of the interval for which the distance should
176 : * be calculated.
177 : * @param aTo The end of the interval for which the distance should be
178 : * calculated.
179 : * @param aDistance The result of the calculation.
180 : * @return NS_OK on success, or an appropriate error code if there is no
181 : * notion of distance for the underlying data type or the distance
182 : * could not be calculated.
183 : *
184 : * @pre aFrom.mType == aTo.mType == this
185 : */
186 : virtual nsresult ComputeDistance(const nsSMILValue& aFrom,
187 : const nsSMILValue& aTo,
188 : double& aDistance) const = 0;
189 :
190 : /**
191 : * Calculates an interpolated value between two values using the specified
192 : * proportion.
193 : *
194 : * @param aStartVal The value defining the start of the interval of
195 : * interpolation.
196 : * @param aEndVal The value defining the end of the interval of
197 : * interpolation.
198 : * @param aUnitDistance A number between 0.0 and 1.0 (inclusive) defining
199 : * the distance of the interpolated value in the
200 : * interval.
201 : * @param aResult The interpolated value.
202 : * @return NS_OK on success, NS_ERROR_FAILURE if this data type cannot be
203 : * interpolated or NS_ERROR_OUT_OF_MEMORY if insufficient memory was
204 : * available for storing the result.
205 : *
206 : * @pre aStartVal.mType == aEndVal.mType == aResult.mType == this
207 : */
208 : virtual nsresult Interpolate(const nsSMILValue& aStartVal,
209 : const nsSMILValue& aEndVal,
210 : double aUnitDistance,
211 : nsSMILValue& aResult) const = 0;
212 : };
213 :
214 : #endif // NS_ISMILTYPE_H_
|
