Another set of UI messages fixes and tweaks! No functional changes.
[blender.git] / extern / Eigen3 / Eigen / src / Core / util / Constants.h
1 // This file is part of Eigen, a lightweight C++ template library
2 // for linear algebra.
3 //
4 // Copyright (C) 2008-2009 Gael Guennebaud <gael.guennebaud@inria.fr>
5 // Copyright (C) 2007-2009 Benoit Jacob <jacob.benoit.1@gmail.com>
6 //
7 // Eigen is free software; you can redistribute it and/or
8 // modify it under the terms of the GNU Lesser General Public
9 // License as published by the Free Software Foundation; either
10 // version 3 of the License, or (at your option) any later version.
11 //
12 // Alternatively, you can redistribute it and/or
13 // modify it under the terms of the GNU General Public License as
14 // published by the Free Software Foundation; either version 2 of
15 // the License, or (at your option) any later version.
16 //
17 // Eigen is distributed in the hope that it will be useful, but WITHOUT ANY
18 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
19 // FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License or the
20 // GNU General Public License for more details.
21 //
22 // You should have received a copy of the GNU Lesser General Public
23 // License and a copy of the GNU General Public License along with
24 // Eigen. If not, see <http://www.gnu.org/licenses/>.
25
26 #ifndef EIGEN_CONSTANTS_H
27 #define EIGEN_CONSTANTS_H
28
29 /** This value means that a quantity is not known at compile-time, and that instead the value is
30   * stored in some runtime variable.
31   *
32   * Changing the value of Dynamic breaks the ABI, as Dynamic is often used as a template parameter for Matrix.
33   */
34 const int Dynamic = -1;
35
36 /** This value means +Infinity; it is currently used only as the p parameter to MatrixBase::lpNorm<int>().
37   * The value Infinity there means the L-infinity norm.
38   */
39 const int Infinity = -1;
40
41 /** \defgroup flags Flags
42   * \ingroup Core_Module
43   *
44   * These are the possible bits which can be OR'ed to constitute the flags of a matrix or
45   * expression.
46   *
47   * It is important to note that these flags are a purely compile-time notion. They are a compile-time property of
48   * an expression type, implemented as enum's. They are not stored in memory at runtime, and they do not incur any
49   * runtime overhead.
50   *
51   * \sa MatrixBase::Flags
52   */
53
54 /** \ingroup flags
55   *
56   * for a matrix, this means that the storage order is row-major.
57   * If this bit is not set, the storage order is column-major.
58   * For an expression, this determines the storage order of
59   * the matrix created by evaluation of that expression. 
60   * \sa \ref TopicStorageOrders */
61 const unsigned int RowMajorBit = 0x1;
62
63 /** \ingroup flags
64   *
65   * means the expression should be evaluated by the calling expression */
66 const unsigned int EvalBeforeNestingBit = 0x2;
67
68 /** \ingroup flags
69   *
70   * means the expression should be evaluated before any assignment */
71 const unsigned int EvalBeforeAssigningBit = 0x4;
72
73 /** \ingroup flags
74   *
75   * Short version: means the expression might be vectorized
76   *
77   * Long version: means that the coefficients can be handled by packets
78   * and start at a memory location whose alignment meets the requirements
79   * of the present CPU architecture for optimized packet access. In the fixed-size
80   * case, there is the additional condition that it be possible to access all the
81   * coefficients by packets (this implies the requirement that the size be a multiple of 16 bytes,
82   * and that any nontrivial strides don't break the alignment). In the dynamic-size case,
83   * there is no such condition on the total size and strides, so it might not be possible to access
84   * all coeffs by packets.
85   *
86   * \note This bit can be set regardless of whether vectorization is actually enabled.
87   *       To check for actual vectorizability, see \a ActualPacketAccessBit.
88   */
89 const unsigned int PacketAccessBit = 0x8;
90
91 #ifdef EIGEN_VECTORIZE
92 /** \ingroup flags
93   *
94   * If vectorization is enabled (EIGEN_VECTORIZE is defined) this constant
95   * is set to the value \a PacketAccessBit.
96   *
97   * If vectorization is not enabled (EIGEN_VECTORIZE is not defined) this constant
98   * is set to the value 0.
99   */
100 const unsigned int ActualPacketAccessBit = PacketAccessBit;
101 #else
102 const unsigned int ActualPacketAccessBit = 0x0;
103 #endif
104
105 /** \ingroup flags
106   *
107   * Short version: means the expression can be seen as 1D vector.
108   *
109   * Long version: means that one can access the coefficients
110   * of this expression by coeff(int), and coeffRef(int) in the case of a lvalue expression. These
111   * index-based access methods are guaranteed
112   * to not have to do any runtime computation of a (row, col)-pair from the index, so that it
113   * is guaranteed that whenever it is available, index-based access is at least as fast as
114   * (row,col)-based access. Expressions for which that isn't possible don't have the LinearAccessBit.
115   *
116   * If both PacketAccessBit and LinearAccessBit are set, then the
117   * packets of this expression can be accessed by packet(int), and writePacket(int) in the case of a
118   * lvalue expression.
119   *
120   * Typically, all vector expressions have the LinearAccessBit, but there is one exception:
121   * Product expressions don't have it, because it would be troublesome for vectorization, even when the
122   * Product is a vector expression. Thus, vector Product expressions allow index-based coefficient access but
123   * not index-based packet access, so they don't have the LinearAccessBit.
124   */
125 const unsigned int LinearAccessBit = 0x10;
126
127 /** \ingroup flags
128   *
129   * Means the expression has a coeffRef() method, i.e. is writable as its individual coefficients are directly addressable.
130   * This rules out read-only expressions.
131   *
132   * Note that DirectAccessBit and LvalueBit are mutually orthogonal, as there are examples of expression having one but note
133   * the other:
134   *   \li writable expressions that don't have a very simple memory layout as a strided array, have LvalueBit but not DirectAccessBit
135   *   \li Map-to-const expressions, for example Map<const Matrix>, have DirectAccessBit but not LvalueBit
136   *
137   * Expressions having LvalueBit also have their coeff() method returning a const reference instead of returning a new value.
138   */
139 const unsigned int LvalueBit = 0x20;
140
141 /** \ingroup flags
142   *
143   * Means that the underlying array of coefficients can be directly accessed as a plain strided array. The memory layout
144   * of the array of coefficients must be exactly the natural one suggested by rows(), cols(),
145   * outerStride(), innerStride(), and the RowMajorBit. This rules out expressions such as Diagonal, whose coefficients,
146   * though referencable, do not have such a regular memory layout.
147   *
148   * See the comment on LvalueBit for an explanation of how LvalueBit and DirectAccessBit are mutually orthogonal.
149   */
150 const unsigned int DirectAccessBit = 0x40;
151
152 /** \ingroup flags
153   *
154   * means the first coefficient packet is guaranteed to be aligned */
155 const unsigned int AlignedBit = 0x80;
156
157 const unsigned int NestByRefBit = 0x100;
158
159 // list of flags that are inherited by default
160 const unsigned int HereditaryBits = RowMajorBit
161                                   | EvalBeforeNestingBit
162                                   | EvalBeforeAssigningBit;
163
164 /** \defgroup enums Enumerations
165   * \ingroup Core_Module
166   *
167   * Various enumerations used in %Eigen. Many of these are used as template parameters.
168   */
169
170 /** \ingroup enums
171   * Enum containing possible values for the \p Mode parameter of 
172   * MatrixBase::selfadjointView() and MatrixBase::triangularView(). */
173 enum {
174   /** View matrix as a lower triangular matrix. */
175   Lower=0x1,                      
176   /** View matrix as an upper triangular matrix. */
177   Upper=0x2,                      
178   /** %Matrix has ones on the diagonal; to be used in combination with #Lower or #Upper. */
179   UnitDiag=0x4, 
180   /** %Matrix has zeros on the diagonal; to be used in combination with #Lower or #Upper. */
181   ZeroDiag=0x8,
182   /** View matrix as a lower triangular matrix with ones on the diagonal. */
183   UnitLower=UnitDiag|Lower, 
184   /** View matrix as an upper triangular matrix with ones on the diagonal. */
185   UnitUpper=UnitDiag|Upper,
186   /** View matrix as a lower triangular matrix with zeros on the diagonal. */
187   StrictlyLower=ZeroDiag|Lower, 
188   /** View matrix as an upper triangular matrix with zeros on the diagonal. */
189   StrictlyUpper=ZeroDiag|Upper,
190   /** Used in BandMatrix and SelfAdjointView to indicate that the matrix is self-adjoint. */
191   SelfAdjoint=0x10
192 };
193
194 /** \ingroup enums
195   * Enum for indicating whether an object is aligned or not. */
196 enum { 
197   /** Object is not correctly aligned for vectorization. */
198   Unaligned=0, 
199   /** Object is aligned for vectorization. */
200   Aligned=1 
201 };
202
203 enum { ConditionalJumpCost = 5 };
204
205 /** \ingroup enums
206  * Enum used by DenseBase::corner() in Eigen2 compatibility mode. */
207 // FIXME after the corner() API change, this was not needed anymore, except by AlignedBox
208 // TODO: find out what to do with that. Adapt the AlignedBox API ?
209 enum CornerType { TopLeft, TopRight, BottomLeft, BottomRight };
210
211 /** \ingroup enums
212   * Enum containing possible values for the \p Direction parameter of
213   * Reverse, PartialReduxExpr and VectorwiseOp. */
214 enum DirectionType { 
215   /** For Reverse, all columns are reversed; 
216     * for PartialReduxExpr and VectorwiseOp, act on columns. */
217   Vertical, 
218   /** For Reverse, all rows are reversed; 
219     * for PartialReduxExpr and VectorwiseOp, act on rows. */
220   Horizontal, 
221   /** For Reverse, both rows and columns are reversed; 
222     * not used for PartialReduxExpr and VectorwiseOp. */
223   BothDirections 
224 };
225
226 enum ProductEvaluationMode { NormalProduct, CacheFriendlyProduct };
227
228 /** \internal \ingroup enums
229   * Enum to specify how to traverse the entries of a matrix. */
230 enum {
231   /** \internal Default traversal, no vectorization, no index-based access */
232   DefaultTraversal,
233   /** \internal No vectorization, use index-based access to have only one for loop instead of 2 nested loops */
234   LinearTraversal,
235   /** \internal Equivalent to a slice vectorization for fixed-size matrices having good alignment
236     * and good size */
237   InnerVectorizedTraversal,
238   /** \internal Vectorization path using a single loop plus scalar loops for the
239     * unaligned boundaries */
240   LinearVectorizedTraversal,
241   /** \internal Generic vectorization path using one vectorized loop per row/column with some
242     * scalar loops to handle the unaligned boundaries */
243   SliceVectorizedTraversal,
244   /** \internal Special case to properly handle incompatible scalar types or other defecting cases*/
245   InvalidTraversal
246 };
247
248 /** \internal \ingroup enums
249   * Enum to specify whether to unroll loops when traversing over the entries of a matrix. */
250 enum {
251   /** \internal Do not unroll loops. */
252   NoUnrolling,
253   /** \internal Unroll only the inner loop, but not the outer loop. */
254   InnerUnrolling,
255   /** \internal Unroll both the inner and the outer loop. If there is only one loop, 
256     * because linear traversal is used, then unroll that loop. */
257   CompleteUnrolling
258 };
259
260 /** \ingroup enums
261   * Enum containing possible values for the \p _Options template parameter of
262   * Matrix, Array and BandMatrix. */
263 enum {
264   /** Storage order is column major (see \ref TopicStorageOrders). */
265   ColMajor = 0,
266   /** Storage order is row major (see \ref TopicStorageOrders). */
267   RowMajor = 0x1,  // it is only a coincidence that this is equal to RowMajorBit -- don't rely on that
268   /** \internal Align the matrix itself if it is vectorizable fixed-size */
269   AutoAlign = 0,
270   /** \internal Don't require alignment for the matrix itself (the array of coefficients, if dynamically allocated, may still be requested to be aligned) */ // FIXME --- clarify the situation
271   DontAlign = 0x2
272 };
273
274 /** \ingroup enums
275   * Enum for specifying whether to apply or solve on the left or right. */
276 enum {
277   /** Apply transformation on the left. */
278   OnTheLeft = 1,  
279   /** Apply transformation on the right. */
280   OnTheRight = 2  
281 };
282
283 /* the following could as well be written:
284  *   enum NoChange_t { NoChange };
285  * but it feels dangerous to disambiguate overloaded functions on enum/integer types.
286  * If on some platform it is really impossible to get rid of "unused variable" warnings, then
287  * we can always come back to that solution.
288  */
289 struct NoChange_t {};
290 namespace {
291   EIGEN_UNUSED NoChange_t NoChange;
292 }
293
294 struct Sequential_t {};
295 namespace {
296   EIGEN_UNUSED Sequential_t Sequential;
297 }
298
299 struct Default_t {};
300 namespace {
301   EIGEN_UNUSED Default_t Default;
302 }
303
304 /** \internal \ingroup enums
305   * Used in AmbiVector. */
306 enum {
307   IsDense         = 0,
308   IsSparse
309 };
310
311 /** \ingroup enums
312   * Used as template parameter in DenseCoeffBase and MapBase to indicate 
313   * which accessors should be provided. */
314 enum AccessorLevels {
315   /** Read-only access via a member function. */
316   ReadOnlyAccessors, 
317   /** Read/write access via member functions. */
318   WriteAccessors, 
319   /** Direct read-only access to the coefficients. */
320   DirectAccessors, 
321   /** Direct read/write access to the coefficients. */
322   DirectWriteAccessors
323 };
324
325 /** \ingroup enums
326   * Enum with options to give to various decompositions. */
327 enum DecompositionOptions {
328   /** \internal Not used (meant for LDLT?). */
329   Pivoting            = 0x01, 
330   /** \internal Not used (meant for LDLT?). */
331   NoPivoting          = 0x02, 
332   /** Used in JacobiSVD to indicate that the square matrix U is to be computed. */
333   ComputeFullU        = 0x04,
334   /** Used in JacobiSVD to indicate that the thin matrix U is to be computed. */
335   ComputeThinU        = 0x08,
336   /** Used in JacobiSVD to indicate that the square matrix V is to be computed. */
337   ComputeFullV        = 0x10,
338   /** Used in JacobiSVD to indicate that the thin matrix V is to be computed. */
339   ComputeThinV        = 0x20,
340   /** Used in SelfAdjointEigenSolver and GeneralizedSelfAdjointEigenSolver to specify
341     * that only the eigenvalues are to be computed and not the eigenvectors. */
342   EigenvaluesOnly     = 0x40,
343   /** Used in SelfAdjointEigenSolver and GeneralizedSelfAdjointEigenSolver to specify
344     * that both the eigenvalues and the eigenvectors are to be computed. */
345   ComputeEigenvectors = 0x80,
346   /** \internal */
347   EigVecMask = EigenvaluesOnly | ComputeEigenvectors,
348   /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should
349     * solve the generalized eigenproblem \f$ Ax = \lambda B x \f$. */
350   Ax_lBx              = 0x100,
351   /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should
352     * solve the generalized eigenproblem \f$ ABx = \lambda x \f$. */
353   ABx_lx              = 0x200,
354   /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should
355     * solve the generalized eigenproblem \f$ BAx = \lambda x \f$. */
356   BAx_lx              = 0x400,
357   /** \internal */
358   GenEigMask = Ax_lBx | ABx_lx | BAx_lx
359 };
360
361 /** \ingroup enums
362   * Possible values for the \p QRPreconditioner template parameter of JacobiSVD. */
363 enum QRPreconditioners {
364   /** Do not specify what is to be done if the SVD of a non-square matrix is asked for. */
365   NoQRPreconditioner,
366   /** Use a QR decomposition without pivoting as the first step. */
367   HouseholderQRPreconditioner,
368   /** Use a QR decomposition with column pivoting as the first step. */
369   ColPivHouseholderQRPreconditioner,
370   /** Use a QR decomposition with full pivoting as the first step. */
371   FullPivHouseholderQRPreconditioner
372 };
373
374 #ifdef Success
375 #error The preprocessor symbol 'Success' is defined, possibly by the X11 header file X.h
376 #endif
377
378 /** \ingroups enums
379   * Enum for reporting the status of a computation. */
380 enum ComputationInfo {
381   /** Computation was successful. */
382   Success = 0,        
383   /** The provided data did not satisfy the prerequisites. */
384   NumericalIssue = 1, 
385   /** Iterative procedure did not converge. */
386   NoConvergence = 2
387 };
388
389 /** \ingroup enums
390   * Enum used to specify how a particular transformation is stored in a matrix.
391   * \sa Transform, Hyperplane::transform(). */
392 enum TransformTraits {
393   /** Transformation is an isometry. */
394   Isometry      = 0x1,
395   /** Transformation is an affine transformation stored as a (Dim+1)^2 matrix whose last row is 
396     * assumed to be [0 ... 0 1]. */
397   Affine        = 0x2,
398   /** Transformation is an affine transformation stored as a (Dim) x (Dim+1) matrix. */
399   AffineCompact = 0x10 | Affine,
400   /** Transformation is a general projective transformation stored as a (Dim+1)^2 matrix. */
401   Projective    = 0x20
402 };
403
404 /** \internal \ingroup enums
405   * Enum used to choose between implementation depending on the computer architecture. */
406 namespace Architecture
407 {
408   enum Type {
409     Generic = 0x0,
410     SSE = 0x1,
411     AltiVec = 0x2,
412 #if defined EIGEN_VECTORIZE_SSE
413     Target = SSE
414 #elif defined EIGEN_VECTORIZE_ALTIVEC
415     Target = AltiVec
416 #else
417     Target = Generic
418 #endif
419   };
420 }
421
422 /** \internal \ingroup enums
423   * Enum used as template parameter in GeneralProduct. */
424 enum { CoeffBasedProductMode, LazyCoeffBasedProductMode, OuterProduct, InnerProduct, GemvProduct, GemmProduct };
425
426 /** \internal \ingroup enums
427   * Enum used in experimental parallel implementation. */
428 enum Action {GetAction, SetAction};
429
430 /** The type used to identify a dense storage. */
431 struct Dense {};
432
433 /** The type used to identify a matrix expression */
434 struct MatrixXpr {};
435
436 /** The type used to identify an array expression */
437 struct ArrayXpr {};
438
439 #endif // EIGEN_CONSTANTS_H