include/vcl/bitmapex.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_VCL_BITMAPEX_HXX
  21 #define INCLUDED_VCL_BITMAPEX_HXX
  22
  23 #include <vcl/dllapi.h>
  24 #include <vcl/alpha.hxx>
  25 #include <vcl/Scanline.hxx>
  26 #include <tools/color.hxx>
  27 #include <tools/degree.hxx>
  28
  29 #include <sal/types.h>
  30
  31 namespace com::sun::star::rendering {
  32     class XBitmapCanvas;
  33 }
  34 namespace com::sun::star::uno { template <class interface_type> class Reference; }
  35 namespace basegfx { class BColorModifierStack; }
  36
  37 class SAL_WARN_UNUSED VCL_DLLPUBLIC BitmapEx
  38 {
  39 public:
  40
  41                         BitmapEx();
  42     explicit            BitmapEx( const OUString& rIconName );
  43                         BitmapEx( const BitmapEx& rBitmapEx );
  44                         BitmapEx( const BitmapEx& rBitmapEx, Point aSrc, Size aSize );
  45                         BitmapEx(Size aSize, vcl::PixelFormat ePixelFormat);
  46     explicit            BitmapEx( const Bitmap& rBmp );
  47                         BitmapEx( const Bitmap& rBmp, const Bitmap& rMask );
  48                         BitmapEx( const Bitmap& rBmp, const AlphaMask& rAlphaMask );
  49                         BitmapEx( const Bitmap& rBmp, const Color& rTransparentColor );
  50
  51     BitmapEx&           operator=( const BitmapEx& rBitmapEx );
  52     BitmapEx&           operator=( const Bitmap& rBitmap ) { return operator=(BitmapEx(rBitmap)); }
  53     bool                operator==( const BitmapEx& rBitmapEx ) const;
  54     bool                operator!=( const BitmapEx& rBitmapEx ) const { return !(*this==rBitmapEx); }
  55
  56     bool                IsEmpty() const;
  57     void                SetEmpty();
  58     void                Clear();
  59     void                ClearAlpha();
  60
  61     void                Draw( OutputDevice* pOutDev,
  62                               const Point& rDestPt ) const;
  63     void                Draw( OutputDevice* pOutDev,
  64                               const Point& rDestPt, const Size& rDestSize ) const;
  65
  66     Bitmap              GetBitmap( Color aTransparentReplaceColor ) const;
  67     /// Gives direct access to the contained bitmap.
  68     const Bitmap&       GetBitmap() const;
  69
  70     bool                IsAlpha() const;
  71     const AlphaMask &   GetAlphaMask() const { return maAlphaMask; }
  72
  73     const Size&         GetSizePixel() const { return maBitmapSize; }
  74     void                SetSizePixel(const Size& rNewSize);
  75
  76     const Size&         GetPrefSize() const { return maBitmap.GetPrefSize(); }
  77     void                SetPrefSize( const Size& rPrefSize ) { maBitmap.SetPrefSize( rPrefSize ); }
  78
  79     const MapMode&      GetPrefMapMode() const { return maBitmap.GetPrefMapMode(); }
  80     void                SetPrefMapMode( const MapMode& rPrefMapMode ) { maBitmap.SetPrefMapMode( rPrefMapMode ); }
  81
  82     vcl::PixelFormat getPixelFormat() const
  83     {
  84         return maBitmap.getPixelFormat();
  85     }
  86
  87     sal_Int64           GetSizeBytes() const;
  88     BitmapChecksum      GetChecksum() const;
  89
  90     /** Convert bitmap format
  91
  92         @param eConversion
  93         The format this bitmap should be converted to.
  94
  95         @return true, if the conversion was completed successfully.
  96      */
  97     bool                Convert( BmpConversion eConversion );
  98
  99     /** Crop the bitmap
 100
 101         @param rRectPixel
 102         A rectangle specifying the crop amounts on all four sides of
 103         the bitmap. If the upper left corner of the bitmap is assigned
 104         (0,0), then this method cuts out the given rectangle from the
 105         bitmap. Note that the rectangle is clipped to the bitmap's
 106         dimension, i.e. negative left,top rectangle coordinates or
 107         exceeding width or height is ignored.
 108
 109         @return true, if cropping was performed successfully. If
 110         nothing had to be cropped, because e.g. the crop rectangle
 111         included the bitmap, false is returned, too!
 112      */
 113     bool                Crop( const tools::Rectangle& rRectPixel );
 114
 115     /** Expand the bitmap by pixel padding
 116
 117         @param nDX
 118         Number of pixel to pad at the right border of the bitmap
 119
 120         @param nDY
 121         Number of scanlines to pad at the bottom border of the bitmap
 122
 123         @param bExpandTransparent
 124         Whether to expand the transparency color or not.
 125      */
 126     void                Expand(
 127                             sal_Int32 nDX, sal_Int32 nDY,
 128                             bool bExpandTransparent = false );
 129
 130     /** Copy a rectangular area from another bitmap
 131
 132         @param rRectDst
 133         Destination rectangle in this bitmap. This is clipped to the
 134         bitmap dimensions.
 135
 136         @param rRectSrc
 137         Source rectangle in pBmpSrc. This is clipped to the source
 138         bitmap dimensions. Note further that no scaling takes place
 139         during this copy operation, i.e. only the minimum of source
 140         and destination rectangle's width and height are used.
 141
 142         @param rBmpExSrc
 143         The source bitmap to copy from.
 144
 145         @return true, if the operation completed successfully. false
 146         is not only returned when the operation failed, but also if
 147         nothing had to be done, e.g. because one of the rectangles are
 148         empty.
 149      */
 150     bool                CopyPixel(
 151                             const tools::Rectangle& rRectDst,
 152                             const tools::Rectangle& rRectSrc,
 153                             const BitmapEx& rBmpExSrc );
 154
 155     /** Copy a rectangular area from one part of the bitmap to another.
 156
 157         @param rRectDst
 158         Destination rectangle in this bitmap. This is clipped to the
 159         bitmap dimensions.
 160
 161         @param rRectSrc
 162         Source rectangle in this bitmap. This is clipped to the
 163         bitmap dimensions. Note further that no scaling takes place
 164         during this copy operation, i.e. only the minimum of source
 165         and destination rectangle's width and height are used.
 166
 167         @return true, if the operation completed successfully. false
 168         is not only returned when the operation failed, but also if
 169         nothing had to be done, e.g. because one of the rectangles are
 170         empty.
 171      */
 172     bool                CopyPixel(
 173                             const tools::Rectangle& rRectDst,
 174                             const tools::Rectangle& rRectSrc );
 175
 176     /** Fill the entire bitmap with the given color
 177
 178         @param rFillColor
 179         Color value to use for filling. Set the transparency part of
 180         the color to fill the mask.
 181
 182         @return true, if the operation was completed successfully.
 183      */
 184     bool                Erase( const Color& rFillColor );
 185
 186     /** Perform the Invert operation on every pixel
 187
 188         @return true, if the operation was completed successfully.
 189      */
 190     bool                Invert();
 191
 192     /** Mirror the bitmap
 193
 194         @param nMirrorFlags
 195         About which axis (horizontal, vertical, or both) to mirror
 196
 197         @return true, if the operation was completed successfully.
 198      */
 199     bool                Mirror( BmpMirrorFlags nMirrorFlags );
 200
 201     /** Scale the bitmap
 202
 203         @param rNewSize
 204         The resulting size of the scaled bitmap
 205
 206         @param nScaleFlag
 207         The algorithm to be used for scaling
 208
 209         @return true, if the operation was completed successfully.
 210      */
 211     bool                Scale(
 212                             const Size& rNewSize,
 213                             BmpScaleFlag nScaleFlag = BmpScaleFlag::Default );
 214
 215     /** Scale the bitmap
 216
 217         @param rScaleX
 218         The scale factor in x direction.
 219
 220         @param rScaleY
 221         The scale factor in y direction.
 222
 223         @param nScaleFlag
 224         The algorithm to be used for scaling
 225
 226         @return true, if the operation was completed successfully.
 227      */
 228     bool                Scale(
 229                             const double& rScaleX,
 230                             const double& rScaleY,
 231                             BmpScaleFlag nScaleFlag = BmpScaleFlag::Default );
 232
 233     /** Rotate bitmap by the specified angle
 234
 235         @param nAngle10
 236         The rotation angle in tenth of a degree. The bitmap is always rotated around its center.
 237
 238         @param rFillColor
 239         The color to use for filling blank areas. During rotation, the
 240         bitmap is enlarged such that the whole rotation result fits
 241         in. The empty spaces around that rotated original bitmap are
 242         then filled with this color.
 243
 244         @return true, if the operation was completed successfully.
 245      */
 246     bool                Rotate(
 247                             Degree10 nAngle10,
 248                             const Color& rFillColor );
 249
 250     /** Replace all pixel having the search color with the specified color
 251
 252         @param rSearchColor
 253         Color specifying which pixel should be replaced
 254
 255         @param rReplaceColor
 256         Color to be placed in all changed pixel
 257      */
 258     void                Replace(
 259                             const Color& rSearchColor,
 260                             const Color& rReplaceColor );
 261
 262     /** Replace all pixel having the search color with the specified color
 263
 264         @param rSearchColor
 265         Color specifying which pixel should be replaced
 266
 267         @param rReplaceColor
 268         Color to be placed in all changed pixel
 269
 270         @param nTolerance
 271         Tolerance value. Specifies the maximal difference between
 272         rSearchColor and the individual pixel values, such that the
 273         corresponding pixel is still regarded a match.
 274      */
 275     void                Replace(
 276                             const Color& rSearchColor,
 277                             const Color& rReplaceColor,
 278                             sal_uInt8 nTolerance );
 279
 280     /** Replace all pixel having one the search colors with the corresponding replace color
 281
 282         @param pSearchColors
 283         Array of colors specifying which pixel should be replaced
 284
 285         @param pReplaceColors
 286         Array of colors to be placed in all changed pixel
 287
 288         @param nColorCount
 289         Size of the aforementioned color arrays
 290
 291         @param pTols
 292         Tolerance value. Specifies the maximal difference between
 293         pSearchColor colors and the individual pixel values, such that
 294         the corresponding pixel is still regarded a match.
 295      */
 296     void                Replace(
 297                             const Color* pSearchColors,
 298                             const Color* pReplaceColors,
 299                             size_t nColorCount );
 300
 301     /** Replace all pixel having one the search colors with the corresponding replace color
 302
 303         @param pSearchColors
 304         Array of colors specifying which pixel should be replaced
 305
 306         @param rReplaceColors
 307         Array of colors to be placed in all changed pixel
 308
 309         @param nColorCount
 310         Size of the aforementioned color arrays
 311
 312         @param pTols
 313         Tolerance value. Specifies the maximal difference between
 314         pSearchColor colors and the individual pixel values, such that
 315         the corresponding pixel is still regarded a match.
 316
 317         @return true, if the operation was completed successfully.
 318      */
 319     void                Replace(
 320                             const Color* pSearchColors,
 321                             const Color* pReplaceColors,
 322                             size_t nColorCount,
 323                             sal_uInt8 const * pTols );
 324
 325     /** Replace transparency with given color.
 326      */
 327     void                ReplaceTransparency( const Color& rColor );
 328
 329     /** Get contours in image */
 330     tools::Polygon      GetContour( bool bContourEdgeDetect, const tools::Rectangle* pWorkRect );
 331
 332     /** Change various global color characteristics
 333
 334         @param nLuminancePercent
 335         Percent of luminance change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 336
 337         @param nContrastPercent
 338         Percent of contrast change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 339
 340         @param nChannelRPercent
 341         Percent of red channel change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 342
 343         @param nChannelGPercent
 344         Percent of green channel change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 345
 346         @param nChannelBPercent
 347         Percent of blue channel change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 348
 349         @param fGamma
 350         Exponent of the gamma function applied to the bitmap. The
 351         value 1.0 results in no change, the valid range is
 352         (0.0,10.0]. Values outside this range are regarded as 1.0.
 353
 354         @param bInvert
 355         If true, invert the channel values with the logical 'not' operator
 356
 357         @param msoBrightness
 358         Use the same formula for brightness as used by MSOffice.
 359
 360         @return true, if the operation was completed successfully.
 361      */
 362     bool                Adjust(
 363                             short nLuminancePercent,
 364                             short nContrastPercent,
 365                             short nChannelRPercent,
 366                             short nChannelGPercent,
 367                             short nChannelBPercent,
 368                             double fGamma = 1.0,
 369                             bool bInvert = false,
 370                             bool msoBrightness = false );
 371
 372     /** Get alpha at given position
 373
 374         @param nX
 375         integer X-Position in Bitmap
 376
 377         @param nY
 378         integer Y-Position in Bitmap
 379
 380         @return alpha value in the range of [0 .. 255] where
 381                 0 is fully transparent, 255 is not transparent
 382      */
 383     sal_uInt8           GetAlpha(
 384                             sal_Int32 nX,
 385                             sal_Int32 nY) const;
 386
 387     /** Get pixel color (including alpha) at given position
 388
 389         @param nX
 390         integer X-Position in Bitmap
 391
 392         @param nY
 393         integer Y-Position in Bitmap
 394      */
 395     ::Color             GetPixelColor(
 396                             sal_Int32 nX,
 397                             sal_Int32 nY) const;
 398
 399     /** Create transformed Bitmap
 400
 401         @param fWidth
 402         The target width in pixels
 403
 404         @param fHeight
 405         The target height in pixels
 406
 407         @param rTransformation
 408         The back transformation for each pixel in (0 .. fWidth),(0 .. fHeight) to
 409         local pixel coordinates
 410     */
 411     [[nodiscard]]
 412     BitmapEx            TransformBitmapEx(
 413                             double fWidth,
 414                             double fHeight,
 415                             const basegfx::B2DHomMatrix& rTransformation) const;
 416
 417     /** Create transformed Bitmap
 418
 419         @param rTransformation
 420         The transformation from unit coordinates to the unit range
 421
 422         @param rVisibleRange
 423         The relative visible range in unit coordinates, relative to (0,0,1,1) which
 424         defines the whole target area
 425
 426         @param fMaximumArea
 427         A limitation for the maximum size of pixels to use for the result
 428
 429         The target size of the result bitmap is defined by transforming the given
 430         rTargetRange with the given rTransformation; the area of the result is
 431         linearly scaled to not exceed the given fMaximumArea
 432
 433         @return The transformed bitmap
 434     */
 435     [[nodiscard]]
 436     BitmapEx            getTransformed(
 437                             const basegfx::B2DHomMatrix& rTransformation,
 438                             const basegfx::B2DRange& rVisibleRange,
 439                             double fMaximumArea) const;
 440
 441     /** Create ColorStack-modified version of this BitmapEx
 442
 443         @param rBColorModifierStack
 444         A ColrModifierStack which defines how each pixel has to be modified
 445     */
 446     [[nodiscard]]
 447     BitmapEx            ModifyBitmapEx( const basegfx::BColorModifierStack& rBColorModifierStack) const;
 448
 449     [[nodiscard]]
 450     static BitmapEx     AutoScaleBitmap( BitmapEx const & aBitmap, const tools::Long aStandardSize );
 451
 452     /// populate from a canvas implementation
 453     bool                Create(
 454                             const css::uno::Reference< css::rendering::XBitmapCanvas > &xBitmapCanvas,
 455                             const Size &rSize );
 456
 457     void                ChangeColorAlpha( sal_uInt8 cIndexFrom, sal_Int8 nAlphaTo );
 458
 459     void                AdjustTransparency( sal_uInt8 cTrans );
 460
 461     void                CombineMaskOr(Color maskColor, sal_uInt8 nTol);
 462
 463     /**
 464      * Retrieves the color model data we need for the XImageConsumer stuff.
 465      */
 466     void                GetColorModel(css::uno::Sequence< sal_Int32 >& rRGBPalette,
 467                             sal_uInt32& rnRedMask, sal_uInt32& rnGreenMask, sal_uInt32& rnBlueMask, sal_uInt32& rnAlphaMask, sal_uInt32& rnTransparencyIndex,
 468                             sal_uInt32& rnWidth, sal_uInt32& rnHeight, sal_uInt8& rnBitCount);
 469
 470     SAL_DLLPRIVATE std::shared_ptr<SalBitmap> const & ImplGetBitmapSalBitmap() const { return maBitmap.ImplGetSalBitmap(); }
 471
 472     /// Dumps the pixels as PNG in bitmap.png.
 473     void DumpAsPng(const char* pFileName = nullptr) const;
 474
 475 private:
 476     friend class ImpGraphic;
 477     friend class OutputDevice;
 478     friend bool VCL_DLLPUBLIC WriteDIBBitmapEx(const BitmapEx& rSource, SvStream& rOStm);
 479     friend bool VCL_DLLPUBLIC ReadRawDIB(BitmapEx& rTarget, const unsigned char* pBuf,
 480                                     const ScanlineFormat nFormat,
 481                                     const int nHeight,
 482                                     const int nStride);
 483
 484     void  loadFromIconTheme( const OUString& rIconName );
 485
 486     Bitmap              maBitmap;
 487     AlphaMask           maAlphaMask;
 488     Size                maBitmapSize;
 489 };
 490
 491
 492 /** Create a blend frame as BitmapEx
 493
 494     @param nAlpha
 495     The blend value defines how strong the frame will be blended with the
 496     existing content, 255 == full coverage, 0 == no frame will be drawn
 497
 498     @param aColorTopLeft, aColorBottomRight
 499     The colors defining the frame. These colors are linearly interpolated from
 500     aColorTopLeft and aColorBottomRight using the width and height of the area
 501
 502     @param rSize
 503     The size of the frame in pixels
 504     */
 505 BitmapEx VCL_DLLPUBLIC createBlendFrame(
 506     const Size& rSize,
 507     sal_uInt8 nAlpha,
 508     Color aColorTopLeft,
 509     Color aColorBottomRight);
 510
 511
 512 /** Create a blend frame as BitmapEx
 513
 514     @param nAlpha
 515     The blend value defines how strong the frame will be blended with the
 516     existing content, 255 == full coverage, 0 == no frame will be drawn
 517
 518     @param aColorTopLeft, aColorBottomRight, aColorTopRight, aColorBottomLeft
 519     The colors defining the frame.
 520
 521     @param rSize
 522     The size of the frame in pixels
 523     */
 524 BitmapEx createBlendFrame(
 525     const Size& rSize,
 526     sal_uInt8 nAlpha,
 527     Color aColorTopLeft,
 528     Color aColorTopRight,
 529     Color aColorBottomRight,
 530     Color aColorBottomLeft);
 531
 532 #endif // INCLUDED_VCL_BITMAPEX_HXX
 533
 534 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */