include/basegfx/vector/b2dvector.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/b2dtuple.hxx>
  23 #include <basegfx/vector/b2ivector.hxx>
  24 #include <basegfx/vector/b2enums.hxx>
  25 #include <basegfx/basegfxdllapi.h>
  26
  27 namespace basegfx
  28 {
  29     class B2DHomMatrix;
  30
  31     /** Base Point class with two double values
  32
  33         This class derives all operators and common handling for
  34         a 2D data class from B2DTuple. All necessary extensions
  35         which are special for 2D Vectors are added here.
  36
  37         @see B2DTuple
  38     */
  39     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC B2DVector : public ::basegfx::B2DTuple
  40     {
  41     public:
  42         /** Create a 2D Vector
  43
  44             The vector is initialized to (0.0, 0.0)
  45         */
  46         B2DVector()
  47         :   B2DTuple()
  48         {}
  49
  50         /** Create a 2D Vector
  51
  52             @param fX
  53             This parameter is used to initialize the X-coordinate
  54             of the 2D Vector.
  55
  56             @param fY
  57             This parameter is used to initialize the Y-coordinate
  58             of the 2D Vector.
  59         */
  60         B2DVector(double fX, double fY)
  61         :   B2DTuple(fX, fY)
  62         {}
  63
  64         /** Create a copy of a 2D Vector
  65
  66             @param rVec
  67             The 2D Vector which will be copied.
  68         */
  69         explicit B2DVector(const ::basegfx::B2IVector& rVec)
  70         :   B2DTuple(rVec)
  71         {}
  72
  73         /** constructor with tuple to allow copy-constructing
  74             from B2DTuple-based classes
  75         */
  76         B2DVector(const ::basegfx::B2DTuple& rTuple)
  77         :   B2DTuple(rTuple)
  78         {}
  79
  80         /** *=operator to allow usage from B2DVector, too
  81         */
  82         B2DVector& operator*=( const B2DVector& rPnt )
  83         {
  84             mfX *= rPnt.mfX;
  85             mfY *= rPnt.mfY;
  86             return *this;
  87         }
  88
  89         /** *=operator to allow usage from B2DVector, too
  90         */
  91         B2DVector& operator*=(double t)
  92         {
  93             mfX *= t;
  94             mfY *= t;
  95             return *this;
  96         }
  97
  98         /** assignment operator to allow assigning the results
  99             of B2DTuple calculations
 100         */
 101         B2DVector& operator=( const ::basegfx::B2DTuple& rVec );
 102
 103         /** Calculate the length of this 2D Vector
 104
 105             @return The Length of the 2D Vector
 106         */
 107         double getLength() const;
 108
 109         /** Set the length of this 2D Vector
 110
 111             @param fLen
 112             The to be achieved length of the 2D Vector
 113         */
 114         B2DVector& setLength(double fLen);
 115
 116         /** Normalize this 2D Vector
 117
 118             The length of the 2D Vector is set to 1.0
 119         */
 120         B2DVector& normalize();
 121
 122         /** Calculate the Scalar with another 2D Vector
 123
 124             @param rVec
 125             The second 2D Vector
 126
 127             @return
 128             The Scalar value of the two involved 2D Vectors
 129         */
 130         double scalar( const B2DVector& rVec ) const { return((mfX * rVec.mfX) + (mfY * rVec.mfY)); }
 131
 132         /** Calculate the length of the cross product with another 2D Vector
 133
 134             In 2D, returning an actual vector does not make much
 135             sense here. The magnitude, although, can be readily
 136             used for tasks such as angle calculations, since for
 137             the returned value, the following equation holds:
 138             retVal = getLength(this)*getLength(rVec)*sin(theta),
 139             with theta being the angle between the two vectors.
 140
 141             @param rVec
 142             The second 2D Vector
 143
 144             @return
 145             The length of the cross product of the two involved 2D Vectors
 146         */
 147         double cross( const B2DVector& rVec ) const { return(mfX * rVec.getY() - mfY * rVec.getX()); }
 148
 149         /** Calculate the Angle with another 2D Vector
 150
 151             @param rVec
 152             The second 2D Vector
 153
 154             @return
 155             The Angle value of the two involved 2D Vectors ranging from -pi to +pi
 156         */
 157         double angle( const B2DVector& rVec ) const;
 158
 159         /** Transform vector by given transformation matrix.
 160
 161             Since this is a vector, translational components of the
 162             matrix are disregarded.
 163         */
 164         B2DVector& operator*=( const B2DHomMatrix& rMat );
 165
 166         static const B2DVector& getEmptyVector();
 167     };
 168
 169     // external operators
 170
 171
 172     /** Calculate the orientation to another 2D Vector
 173
 174         @param rVecA
 175         The first 2D Vector
 176
 177         @param rVecB
 178         The second 2D Vector
 179
 180         @return
 181         The mathematical Orientation of the two involved 2D Vectors
 182     */
 183     BASEGFX_DLLPUBLIC B2VectorOrientation getOrientation( const B2DVector& rVecA, const B2DVector& rVecB );
 184
 185     /** Calculate a perpendicular 2D Vector to the given one
 186
 187         @param rVec
 188         The source 2D Vector
 189
 190         @attention This only works if the given 2D Vector is normalized.
 191
 192         @return
 193         A 2D Vector perpendicular to the one given in parameter rVec
 194     */
 195     BASEGFX_DLLPUBLIC B2DVector getPerpendicular( const B2DVector& rNormalizedVec );
 196
 197     /** Calculate a perpendicular 2D Vector to the given one,
 198         normalize the given one as preparation
 199
 200         @param rVec
 201         The source 2D Vector
 202
 203         @return
 204         A normalized 2D Vector perpendicular to the one given in parameter rVec
 205     */
 206     BASEGFX_DLLPUBLIC B2DVector getNormalizedPerpendicular( const B2DVector& rVec );
 207
 208     /** Test two vectors which need not to be normalized for parallelism
 209
 210         @param rVecA
 211         The first 2D Vector
 212
 213         @param rVecB
 214         The second 2D Vector
 215
 216         @return
 217         bool if the two values are parallel. Also true if
 218         one of the vectors is empty.
 219     */
 220     BASEGFX_DLLPUBLIC bool areParallel( const B2DVector& rVecA, const B2DVector& rVecB );
 221
 222     /** Transform vector by given transformation matrix.
 223
 224         Since this is a vector, translational components of the
 225         matrix are disregarded.
 226     */
 227     BASEGFX_DLLPUBLIC B2DVector operator*( const B2DHomMatrix& rMat, const B2DVector& rVec );
 228
 229     /** Test continuity between given vectors.
 230
 231         The two given vectors are assumed to describe control points on a
 232         common point. Calculate if there is a continuity between them.
 233     */
 234     BASEGFX_DLLPUBLIC B2VectorContinuity getContinuity( const B2DVector& rBackVector, const B2DVector& rForwardVector );
 235
 236 } // end of namespace basegfx
 237
 238 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */