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