include/basegfx/utils/gradienttools.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 <config_options.h>
  23 #include <basegfx/point/b2dpoint.hxx>
  24 #include <basegfx/vector/b2dvector.hxx>
  25 #include <basegfx/matrix/b2dhommatrix.hxx>
  26 #include <basegfx/basegfxdllapi.h>
  27
  28 namespace basegfx { class B2DRange; }
  29
  30 namespace basegfx
  31 {
  32     /** Gradient definition as used in ODF 1.2
  33
  34         This struct collects all data necessary for rendering ODF
  35         1.2-compatible gradients. Use the createXXXODFGradientInfo()
  36         methods below for initializing from ODF attributes.
  37      */
  38     class UNLESS_MERGELIBS(BASEGFX_DLLPUBLIC) ODFGradientInfo
  39     {
  40     private:
  41         /** transformation mapping from [0,1]^2 texture coordinate
  42            space to [0,1]^2 shape coordinate space
  43          */
  44         B2DHomMatrix    maTextureTransform;
  45
  46         /** transformation mapping from [0,1]^2 shape coordinate space
  47            to [0,1]^2 texture coordinate space. This is the
  48            transformation commonly used to create gradients from a
  49            scanline rasterizer (put shape u/v coordinates into it, get
  50            texture s/t coordinates out of it)
  51          */
  52         B2DHomMatrix    maBackTextureTransform;
  53
  54         /** Aspect ratio of the gradient. Only used in drawinglayer
  55            for generating nested gradient polygons currently. Already
  56            catered for in the transformations above.
  57          */
  58         double          mfAspectRatio;
  59
  60         /** Requested gradient steps to render. See the
  61            implementations of the getXXXGradientAlpha() methods below,
  62            the semantic differs slightly for the different gradient
  63            types.
  64          */
  65         sal_uInt32      mnSteps;
  66
  67     public:
  68         ODFGradientInfo()
  69         :   maTextureTransform(),
  70             maBackTextureTransform(),
  71             mfAspectRatio(1.0),
  72             mnSteps(0)
  73         {
  74         }
  75
  76         ODFGradientInfo(
  77             const B2DHomMatrix& rTextureTransform,
  78             double fAspectRatio,
  79             sal_uInt32 nSteps)
  80         :   maTextureTransform(rTextureTransform),
  81             maBackTextureTransform(),
  82             mfAspectRatio(fAspectRatio),
  83             mnSteps(nSteps)
  84         {
  85         }
  86
  87         ODFGradientInfo(const ODFGradientInfo& rODFGradientInfo)
  88         :   maTextureTransform(rODFGradientInfo.getTextureTransform()),
  89             maBackTextureTransform(rODFGradientInfo.maBackTextureTransform),
  90             mfAspectRatio(rODFGradientInfo.getAspectRatio()),
  91             mnSteps(rODFGradientInfo.getSteps())
  92         {
  93         }
  94
  95         ODFGradientInfo& operator=(const ODFGradientInfo& rODFGradientInfo)
  96         {
  97             maTextureTransform = rODFGradientInfo.getTextureTransform();
  98             maBackTextureTransform = rODFGradientInfo.maBackTextureTransform;
  99             mfAspectRatio = rODFGradientInfo.getAspectRatio();
 100             mnSteps = rODFGradientInfo.getSteps();
 101
 102             return *this;
 103         }
 104
 105         // compare operator
 106         bool operator==(const ODFGradientInfo& rGeoTexSvx) const;
 107
 108         const B2DHomMatrix& getTextureTransform() const { return maTextureTransform; }
 109         const B2DHomMatrix& getBackTextureTransform() const;
 110         double getAspectRatio() const { return mfAspectRatio; }
 111         sal_uInt32 getSteps() const { return mnSteps; }
 112
 113         void setTextureTransform(const B2DHomMatrix& rNew)
 114         {
 115             maTextureTransform = rNew;
 116             maBackTextureTransform.identity();
 117         }
 118     };
 119
 120     namespace utils
 121     {
 122         /** Create matrix for ODF's linear gradient definition
 123
 124             Note that odf linear gradients are varying in y direction.
 125
 126             @param o_rGradientInfo
 127             Receives the calculated texture transformation matrix (for
 128             use with standard [0,1]x[0,1] texture coordinates)
 129
 130             @param rTargetArea
 131             Output area, needed for aspect ratio calculations and
 132             texture transformation
 133
 134             @param nSteps
 135             Number of gradient steps (from ODF)
 136
 137             @param fBorder
 138             Width of gradient border (from ODF)
 139
 140             @param fAngle
 141             Gradient angle (from ODF)
 142          */
 143         BASEGFX_DLLPUBLIC ODFGradientInfo createLinearODFGradientInfo(
 144             const B2DRange& rTargetArea,
 145             sal_uInt32 nSteps,
 146             double fBorder,
 147             double fAngle);
 148
 149
 150         /** Calculate linear gradient blend value
 151
 152             This method generates you the lerp alpha value for
 153             blending linearly between gradient start and end color,
 154             according to the formula (startCol*(1.0-alpha) + endCol*alpha)
 155
 156             @param rUV
 157             Current uv coordinate. Values outside [0,1] will be
 158             clamped. Assumes gradient color varies along the y axis.
 159
 160             @param rGradInfo
 161             Gradient info, for transformation and number of steps
 162          */
 163         BASEGFX_DLLPUBLIC double getLinearGradientAlpha(const B2DPoint& rUV,
 164             const ODFGradientInfo& rGradInfo);
 165
 166         /** Create matrix for ODF's axial gradient definition
 167
 168             Note that odf axial gradients are varying in y
 169             direction. Note further that you can map the axial
 170             gradient to a linear gradient (in case you want or need to
 171             avoid an extra gradient renderer), by using
 172             createLinearODFGradientInfo() instead, shifting the
 173             resulting texture transformation by 0.5 to the top and
 174             appending the same stop colors again, but mirrored.
 175
 176             @param o_rGradientInfo
 177             Receives the calculated texture transformation matrix (for
 178             use with standard [0,1]x[0,1] texture coordinates)
 179
 180             @param rTargetArea
 181             Output area, needed for aspect ratio calculations and
 182             texture transformation
 183
 184             @param nSteps
 185             Number of gradient steps (from ODF)
 186
 187             @param fBorder
 188             Width of gradient border (from ODF)
 189
 190             @param fAngle
 191             Gradient angle (from ODF)
 192          */
 193         BASEGFX_DLLPUBLIC ODFGradientInfo createAxialODFGradientInfo(
 194             const B2DRange& rTargetArea,
 195             sal_uInt32 nSteps,
 196             double fBorder,
 197             double fAngle);
 198
 199
 200         /** Calculate axial gradient blend value
 201
 202             This method generates you the lerp alpha value for
 203             blending linearly between gradient start and end color,
 204             according to the formula (startCol*(1.0-alpha) + endCol*alpha)
 205
 206             @param rUV
 207             Current uv coordinate. Values outside [0,1] will be
 208             clamped. Assumes gradient color varies along the y axis.
 209
 210             @param rGradInfo
 211             Gradient info, for transformation and number of steps
 212          */
 213         BASEGFX_DLLPUBLIC double getAxialGradientAlpha(const B2DPoint& rUV,
 214             const ODFGradientInfo& rGradInfo);
 215
 216         /** Create matrix for ODF's radial gradient definition
 217
 218             @param o_rGradientInfo
 219             Receives the calculated texture transformation matrix (for
 220             use with standard [0,1]x[0,1] texture coordinates)
 221
 222             @param rTargetArea
 223             Output area, needed for aspect ratio calculations and
 224             texture transformation
 225
 226             @param rOffset
 227             Gradient offset value (from ODF)
 228
 229             @param nSteps
 230             Number of gradient steps (from ODF)
 231
 232             @param fBorder
 233             Width of gradient border (from ODF)
 234
 235             @param fAngle
 236             Gradient angle (from ODF)
 237          */
 238         BASEGFX_DLLPUBLIC ODFGradientInfo createRadialODFGradientInfo(
 239             const B2DRange& rTargetArea,
 240             const B2DVector& rOffset,
 241             sal_uInt32 nSteps,
 242             double fBorder);
 243
 244
 245         /** Calculate radial gradient blend value
 246
 247             This method generates you the lerp alpha value for
 248             blending linearly between gradient start and end color,
 249             according to the formula (startCol*(1.0-alpha) + endCol*alpha)
 250
 251             @param rUV
 252             Current uv coordinate. Values outside [0,1] will be
 253             clamped.
 254
 255             @param rGradInfo
 256             Gradient info, for transformation and number of steps
 257          */
 258         BASEGFX_DLLPUBLIC double getRadialGradientAlpha(const B2DPoint& rUV,
 259             const ODFGradientInfo& rGradInfo);
 260
 261         /** Create matrix for ODF's elliptical gradient definition
 262
 263             @param o_rGradientInfo
 264             Receives the calculated texture transformation matrix (for
 265             use with standard [0,1]x[0,1] texture coordinates)
 266
 267             @param rTargetArea
 268             Output area, needed for aspect ratio calculations and
 269             texture transformation
 270
 271             @param rOffset
 272             Gradient offset value (from ODF)
 273
 274             @param nSteps
 275             Number of gradient steps (from ODF)
 276
 277             @param fBorder
 278             Width of gradient border (from ODF)
 279
 280             @param fAngle
 281             Gradient angle (from ODF)
 282          */
 283         BASEGFX_DLLPUBLIC ODFGradientInfo createEllipticalODFGradientInfo(
 284             const B2DRange& rTargetArea,
 285             const B2DVector& rOffset,
 286             sal_uInt32 nSteps,
 287             double fBorder,
 288             double fAngle);
 289
 290
 291         /** Calculate elliptical gradient blend value
 292
 293             This method generates you the lerp alpha value for
 294             blending linearly between gradient start and end color,
 295             according to the formula (startCol*(1.0-alpha) + endCol*alpha)
 296
 297             @param rUV
 298             Current uv coordinate. Values outside [0,1] will be
 299             clamped.
 300
 301             @param rGradInfo
 302             Gradient info, for transformation and number of steps
 303          */
 304         BASEGFX_DLLPUBLIC double getEllipticalGradientAlpha(const B2DPoint& rUV,
 305             const ODFGradientInfo& rGradInfo);
 306
 307         /** Create matrix for ODF's square gradient definition
 308
 309             @param o_rGradientInfo
 310             Receives the calculated texture transformation matrix (for
 311             use with standard [0,1]x[0,1] texture coordinates)
 312
 313             @param rTargetArea
 314             Output area, needed for aspect ratio calculations and
 315             texture transformation
 316
 317             @param rOffset
 318             Gradient offset value (from ODF)
 319
 320             @param nSteps
 321             Number of gradient steps (from ODF)
 322
 323             @param fBorder
 324             Width of gradient border (from ODF)
 325
 326             @param fAngle
 327             Gradient angle (from ODF)
 328          */
 329         BASEGFX_DLLPUBLIC ODFGradientInfo createSquareODFGradientInfo(
 330             const B2DRange& rTargetArea,
 331             const B2DVector& rOffset,
 332             sal_uInt32 nSteps,
 333             double fBorder,
 334             double fAngle);
 335
 336
 337         /** Calculate square gradient blend value
 338
 339             This method generates you the lerp alpha value for
 340             blending linearly between gradient start and end color,
 341             according to the formula (startCol*(1.0-alpha) + endCol*alpha)
 342
 343             @param rUV
 344             Current uv coordinate. Values outside [0,1] will be
 345             clamped.
 346
 347             @param rGradInfo
 348             Gradient info, for transformation and number of steps
 349          */
 350         BASEGFX_DLLPUBLIC double getSquareGradientAlpha(const B2DPoint& rUV,
 351             const ODFGradientInfo& rGradInfo);
 352
 353         /** Create matrix for ODF's rectangular gradient definition
 354
 355             @param o_rGradientInfo
 356             Receives the calculated texture transformation matrix (for
 357             use with standard [0,1]x[0,1] texture coordinates)
 358
 359             @param rTargetArea
 360             Output area, needed for aspect ratio calculations and
 361             texture transformation
 362
 363             @param rOffset
 364             Gradient offset value (from ODF)
 365
 366             @param nSteps
 367             Number of gradient steps (from ODF)
 368
 369             @param fBorder
 370             Width of gradient border (from ODF)
 371
 372             @param fAngle
 373             Gradient angle (from ODF)
 374          */
 375         BASEGFX_DLLPUBLIC ODFGradientInfo createRectangularODFGradientInfo(
 376             const B2DRange& rTargetArea,
 377             const B2DVector& rOffset,
 378             sal_uInt32 nSteps,
 379             double fBorder,
 380             double fAngle);
 381
 382
 383         /** Calculate rectangular gradient blend value
 384
 385             This method generates you the lerp alpha value for
 386             blending linearly between gradient start and end color,
 387             according to the formula (startCol*(1.0-alpha) + endCol*alpha)
 388
 389             @param rUV
 390             Current uv coordinate. Values outside [0,1] will be
 391             clamped.
 392
 393             @param rGradInfo
 394             Gradient info, for transformation and number of steps
 395          */
 396         BASEGFX_DLLPUBLIC double getRectangularGradientAlpha(const B2DPoint& rUV,
 397             const ODFGradientInfo& rGradInfo);
 398     }
 399 }
 400
 401 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */