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