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