include/basegfx/vector/b3dvector.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_BASEGFX_VECTOR_B3DVECTOR_HXX
  21 #define INCLUDED_BASEGFX_VECTOR_B3DVECTOR_HXX
  22
  23 #include <basegfx/tuple/b3dtuple.hxx>
  24 #include <basegfx/basegfxdllapi.h>
  25
  26 namespace basegfx
  27 {
  28     class B3DHomMatrix;
  29
  30     /** Base Point class with three double values
  31
  32         This class derives all operators and common handling for
  33         a 3D data class from B3DTuple. All necessary extensions
  34         which are special for 3D Vectors are added here.
  35
  36         @see B3DTuple
  37     */
  38     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC B3DVector : public ::basegfx::B3DTuple
  39     {
  40     public:
  41         /** Create a 3D Vector
  42
  43             The vector is initialized to (0.0, 0.0, 0.0)
  44         */
  45         B3DVector()
  46         :   B3DTuple()
  47         {}
  48
  49         /** Create a 3D Vector
  50
  51             @param fX
  52             This parameter is used to initialize the X-coordinate
  53             of the 3D Vector.
  54
  55             @param fY
  56             This parameter is used to initialize the Y-coordinate
  57             of the 3D Vector.
  58
  59             @param fZ
  60             This parameter is used to initialize the Z-coordinate
  61             of the 3D Vector.
  62         */
  63         B3DVector(double fX, double fY, double fZ)
  64         :   B3DTuple(fX, fY, fZ)
  65         {}
  66
  67         /** constructor with tuple to allow copy-constructing
  68             from B3DTuple-based classes
  69         */
  70         B3DVector(const ::basegfx::B3DTuple& rTuple)
  71         :   B3DTuple(rTuple)
  72         {}
  73
  74         /** *=operator to allow usage from B3DVector, too
  75         */
  76         B3DVector& operator*=( const B3DVector& rPnt )
  77         {
  78             mfX *= rPnt.mfX;
  79             mfY *= rPnt.mfY;
  80             mfZ *= rPnt.mfZ;
  81             return *this;
  82         }
  83
  84         /** *=operator to allow usage from B3DVector, too
  85         */
  86         B3DVector& operator*=(double t)
  87         {
  88             mfX *= t;
  89             mfY *= t;
  90             mfZ *= t;
  91             return *this;
  92         }
  93
  94         /** assignment operator to allow assigning the results
  95             of B3DTuple calculations
  96         */
  97         B3DVector& operator=( const ::basegfx::B3DTuple& rVec )
  98         {
  99             mfX = rVec.getX();
 100             mfY = rVec.getY();
 101             mfZ = rVec.getZ();
 102             return *this;
 103         }
 104
 105         /** Calculate the length of this 3D Vector
 106
 107             @return The Length of the 3D Vector
 108         */
 109         double getLength() const
 110         {
 111             double fLen(scalar(*this));
 112             if((0.0 == fLen) || (1.0 == fLen))
 113                 return fLen;
 114             return sqrt(fLen);
 115         }
 116
 117         /** Calculate the length in the XZ-Plane for this 3D Vector
 118
 119             @return The XZ-Plane Length of the 3D Vector
 120         */
 121         double getXZLength() const
 122         {
 123             double fLen((mfX * mfX) + (mfZ * mfZ)); // #i73040#
 124             if((0.0 == fLen) || (1.0 == fLen))
 125                 return fLen;
 126             return sqrt(fLen);
 127         }
 128
 129         /** Calculate the length in the YZ-Plane for this 3D Vector
 130
 131             @return The YZ-Plane Length of the 3D Vector
 132         */
 133         double getYZLength() const
 134         {
 135             double fLen((mfY * mfY) + (mfZ * mfZ));
 136             if((0.0 == fLen) || (1.0 == fLen))
 137                 return fLen;
 138             return sqrt(fLen);
 139         }
 140
 141         /** Set the length of this 3D Vector
 142
 143             @param fLen
 144             The to be achieved length of the 3D Vector
 145         */
 146         B3DVector& setLength(double fLen)
 147         {
 148             double fLenNow(scalar(*this));
 149
 150             if(!::basegfx::fTools::equalZero(fLenNow))
 151             {
 152                 const double fOne(1.0);
 153
 154                 if(!::basegfx::fTools::equal(fOne, fLenNow))
 155                 {
 156                     fLen /= sqrt(fLenNow);
 157                 }
 158
 159                 mfX *= fLen;
 160                 mfY *= fLen;
 161                 mfZ *= fLen;
 162             }
 163
 164             return *this;
 165         }
 166
 167         /** Normalize this 3D Vector
 168
 169             The length of the 3D Vector is set to 1.0
 170         */
 171         B3DVector& normalize();
 172
 173         /** get a 3D Vector which is perpendicular to this and a given 3D Vector
 174
 175             @attention This only works if this and the given 3D Vector are
 176             both normalized.
 177
 178             @param rNormalizedVec
 179             A normalized 3D Vector.
 180
 181             @return
 182             A 3D Vector perpendicular to this and the given one
 183         */
 184         B3DVector getPerpendicular(const B3DVector& rNormalizedVec) const;
 185
 186         /** Calculate the Scalar product
 187
 188             This method calculates the Scalar product between this
 189             and the given 3D Vector.
 190
 191             @param rVec
 192             A second 3D Vector.
 193
 194             @return
 195             The Scalar Product of two 3D Vectors
 196         */
 197         double scalar(const B3DVector& rVec) const
 198         {
 199             return ((mfX * rVec.mfX) + (mfY * rVec.mfY) + (mfZ * rVec.mfZ));
 200         }
 201
 202         /** Transform vector by given transformation matrix.
 203
 204             Since this is a vector, translational components of the
 205             matrix are disregarded.
 206         */
 207         B3DVector& operator*=( const B3DHomMatrix& rMat );
 208
 209         static const B3DVector& getEmptyVector()
 210         {
 211             return static_cast<const B3DVector&>( ::basegfx::B3DTuple::getEmptyTuple() );
 212         }
 213     };
 214
 215     // external operators
 216
 217
 218     /** Test two vectors which need not to be normalized for parallelism
 219
 220         @param rVecA
 221         The first 3D Vector
 222
 223         @param rVecB
 224         The second 3D Vector
 225
 226         @return
 227         bool if the two values are parallel. Also true if
 228         one of the vectors is empty.
 229     */
 230     BASEGFX_DLLPUBLIC bool areParallel( const B3DVector& rVecA, const B3DVector& rVecB );
 231
 232     /** Transform vector by given transformation matrix.
 233
 234         Since this is a vector, translational components of the
 235         matrix are disregarded.
 236     */
 237     BASEGFX_DLLPUBLIC B3DVector operator*( const B3DHomMatrix& rMat, const B3DVector& rVec );
 238
 239     /** Calculate the Cross Product of two 3D Vectors
 240
 241         @param rVecA
 242         A first 3D Vector.
 243
 244         @param rVecB
 245         A second 3D Vector.
 246
 247         @return
 248         The Cross Product of both 3D Vectors
 249     */
 250     inline B3DVector cross(const B3DVector& rVecA, const B3DVector& rVecB)
 251     {
 252         B3DVector aVec(
 253             rVecA.getY() * rVecB.getZ() - rVecA.getZ() * rVecB.getY(),
 254             rVecA.getZ() * rVecB.getX() - rVecA.getX() * rVecB.getZ(),
 255             rVecA.getX() * rVecB.getY() - rVecA.getY() * rVecB.getX());
 256         return aVec;
 257     }
 258 } // end of namespace basegfx
 259
 260 #endif // INCLUDED_BASEGFX_VECTOR_B3DVECTOR_HXX
 261
 262 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */