include/vcl/bitmap.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_BITMAP_HXX
  21 #define INCLUDED_VCL_BITMAP_HXX
  22
  23 #include <tools/degree.hxx>
  24 #include <vcl/checksum.hxx>
  25 #include <vcl/dllapi.h>
  26 #include <vcl/mapmod.hxx>
  27 #include <vcl/region.hxx>
  28 #include <vcl/scopedbitmapaccess.hxx>
  29 #include <vcl/bitmap/BitmapTypes.hxx>
  30
  31 #include <o3tl/typed_flags_set.hxx>
  32
  33 #include <memory>
  34
  35 #define GAMMA( _def_cVal, _def_InvGamma )   (static_cast<sal_uInt8>(MinMax(FRound(pow( _def_cVal/255.0,_def_InvGamma)*255.0),0,255)))
  36
  37 class Color;
  38
  39 template <typename Arg, typename Ret> class Link;
  40
  41 enum class BmpMirrorFlags
  42 {
  43     NONE             = 0x00,
  44     Horizontal       = 0x01,
  45     Vertical         = 0x02,
  46 };
  47
  48 namespace o3tl
  49 {
  50     template<> struct typed_flags<BmpMirrorFlags> : is_typed_flags<BmpMirrorFlags, 0x03> {};
  51 }
  52
  53 enum class BmpScaleFlag
  54 {
  55 // Try to preferably use these.
  56     Default,
  57     Fast,
  58     BestQuality,
  59 // Specific algorithms, use only if you really need to (mainly used for tests)
  60     NearestNeighbor,
  61     Interpolate, // fast, integer bilinear
  62     Lanczos,
  63     BiCubic,
  64     BiLinear
  65 };
  66
  67 #define BMP_COL_TRANS               Color( 252, 3, 251 )
  68
  69 enum class BmpConversion
  70 {
  71     NNONE,
  72     N1BitThreshold,
  73     N8BitGreys,
  74     N8BitColors,
  75     N24Bit,
  76     N32Bit,
  77     N8BitTrans,
  78     N8BitNoConversion // make 8bit without color conversion (e.g. take the red channel)
  79 };
  80
  81 class   BitmapInfoAccess;
  82 class   BitmapReadAccess;
  83 class   BitmapWriteAccess;
  84 class   BitmapPalette;
  85 class   GDIMetaFile;
  86 class   AlphaMask;
  87 class   OutputDevice;
  88 class   SalBitmap;
  89
  90 struct BitmapSystemData
  91 {
  92     #if defined(_WIN32)
  93     void* pDIB; // device independent byte buffer
  94     #elif defined( MACOSX ) || defined( IOS )
  95     // Nothing needed, apparently
  96     #else
  97     void* aPixmap;
  98     #endif
  99     int mnWidth;
 100     int mnHeight;
 101 };
 102
 103 class SAL_WARN_UNUSED VCL_DLLPUBLIC Bitmap
 104 {
 105 public:
 106
 107                             Bitmap();
 108                             Bitmap( const Bitmap& rBitmap );
 109                             Bitmap( const Size& rSizePixel, vcl::PixelFormat ePixelFormat, const BitmapPalette* pPal = nullptr );
 110     explicit                Bitmap( std::shared_ptr<SalBitmap> const & xSalBitmap );
 111     virtual                 ~Bitmap();
 112
 113     Bitmap&                 operator=( const Bitmap& rBitmap );
 114     Bitmap&                 operator=( Bitmap&& rBitmap ) noexcept;
 115     bool                    operator==( const Bitmap& rBitmap ) const;
 116     bool                    operator!=( const Bitmap& rBitmap ) const { return !operator==(rBitmap); }
 117
 118     inline bool             IsEmpty() const;
 119     void                    SetEmpty();
 120
 121     inline const MapMode&   GetPrefMapMode() const;
 122     inline void             SetPrefMapMode( const MapMode& rMapMode );
 123
 124     inline const Size&      GetPrefSize() const;
 125     inline void             SetPrefSize( const Size& rSize );
 126
 127     Size                    GetSizePixel() const;
 128
 129     vcl::PixelFormat getPixelFormat() const;
 130     inline sal_Int64        GetSizeBytes() const;
 131     bool                    HasGreyPalette8Bit() const;
 132     bool                    HasGreyPaletteAny() const;
 133     /** get system dependent bitmap data
 134
 135         @param rData
 136         The system dependent BitmapSystemData structure to be filled
 137
 138         @return true if the bitmap has a valid system object (e.g. not empty)
 139     */
 140     bool                    GetSystemData( BitmapSystemData& rData ) const;
 141
 142     BitmapChecksum          GetChecksum() const;
 143
 144     Bitmap                  CreateDisplayBitmap( OutputDevice* pDisplay ) const;
 145
 146     static const BitmapPalette&
 147                             GetGreyPalette( int nEntries );
 148
 149 public:
 150
 151     /** Convert bitmap format
 152
 153         @param eConversion
 154         The format this bitmap should be converted to.
 155
 156         @return true the conversion was completed successfully.
 157      */
 158     bool                    Convert( BmpConversion eConversion );
 159
 160     /** Apply a Floyd dither algorithm to the bitmap
 161
 162      This method dithers the bitmap inplace, i.e. a true color
 163      bitmap is converted to a paletted bitmap, reducing the color
 164      deviation by error diffusion.
 165
 166      */
 167     bool                    Dither();
 168
 169     /** Crop the bitmap
 170
 171         @param rRectPixel
 172         A rectangle specifying the crop amounts on all four sides of
 173         the bitmap. If the upper left corner of the bitmap is assigned
 174         (0,0), then this method cuts out the given rectangle from the
 175         bitmap. Note that the rectangle is clipped to the bitmap's
 176         dimension, i.e. negative left,top rectangle coordinates or
 177         exceeding width or height is ignored.
 178
 179         @return true cropping was performed successfully. If
 180         nothing had to be cropped, because e.g. the crop rectangle
 181         included the bitmap, false is returned, too!
 182      */
 183     bool                    Crop( const tools::Rectangle& rRectPixel );
 184
 185     /** Expand the bitmap by pixel padding
 186
 187         @param nDX
 188         Number of pixel to pad at the right border of the bitmap
 189
 190         @param nDY
 191         Number of scanlines to pad at the bottom border of the bitmap
 192
 193         @param pInitColor
 194         Color to use for padded pixel
 195
 196         @return true, if padding was performed successfully. false is
 197         not only returned when the operation failed, but also if
 198         nothing had to be done, e.g. because nDX and nDY were zero.
 199      */
 200     bool                    Expand(
 201                                 sal_Int32 nDX, sal_Int32 nDY,
 202                                 const Color* pInitColor = nullptr );
 203
 204     /** Copy a rectangular area from another bitmap
 205
 206         @param rRectDst
 207         Destination rectangle in this bitmap. This is clipped to the
 208         bitmap dimensions.
 209
 210         @param rRectSrc
 211         Source rectangle in pBmpSrc. This is clipped to the source
 212         bitmap dimensions. Note further that no scaling takes place
 213         during this copy operation, i.e. only the minimum of source
 214         and destination rectangle's width and height are used.
 215
 216         @param pBmpSrc
 217         The source bitmap to copy from. If this argument is NULL, or
 218         equal to the object this method is called on, copying takes
 219         place within the same bitmap.
 220
 221         @return true, if the operation completed successfully. false
 222         is not only returned when the operation failed, but also if
 223         nothing had to be done, e.g. because one of the rectangles are
 224         empty.
 225      */
 226     bool                    CopyPixel(
 227                                 const tools::Rectangle& rRectDst,
 228                                 const tools::Rectangle& rRectSrc,
 229                                 const Bitmap* pBmpSrc = nullptr );
 230
 231     bool                    CopyPixel_AlphaOptimized(
 232                                 const tools::Rectangle& rRectDst,
 233                                 const tools::Rectangle& rRectSrc,
 234                                 const Bitmap* pBmpSrc );
 235
 236     /** Perform boolean OR operation with another bitmap
 237
 238         @param rMask
 239         The mask bitmap in the selected combine operation
 240
 241         @return true, if the operation was completed successfully.
 242      */
 243     bool                    CombineOr( const Bitmap& rMask );
 244
 245     /** Alpha-blend the given bitmap against a specified uniform
 246           background color.
 247
 248         @attention This method might convert paletted bitmaps to
 249         truecolor, to be able to represent every necessary color. Note
 250         that during alpha blending, lots of colors not originally
 251         included in the bitmap can be generated.
 252
 253         @param rAlpha
 254         Alpha mask to blend with
 255
 256         @param rBackgroundColor
 257         Background color to use for every pixel during alpha blending
 258
 259         @return true, if blending was successful, false otherwise
 260      */
 261     bool                    Blend(
 262                                 const AlphaMask& rAlpha,
 263                                 const Color& rBackgroundColor );
 264
 265     /** Fill the entire bitmap with the given color
 266
 267         @param rFillColor
 268         Color value to use for filling
 269
 270         @return true, if the operation was completed successfully.
 271      */
 272     bool                    Erase( const Color& rFillColor );
 273
 274     /** Perform the Invert operation on every pixel
 275
 276         @return true, if the operation was completed successfully.
 277      */
 278     bool                    Invert();
 279
 280     /** Mirror the bitmap
 281
 282         @param nMirrorFlags
 283         About which axis (horizontal, vertical, or both) to mirror
 284
 285         @return true, if the operation was completed successfully.
 286      */
 287     bool                    Mirror( BmpMirrorFlags nMirrorFlags );
 288
 289     /** Scale the bitmap
 290
 291         @param rNewSize
 292         The resulting size of the scaled bitmap
 293
 294         @param nScaleFlag
 295         The algorithm to be used for scaling
 296
 297         @return true, if the operation was completed successfully.
 298      */
 299     bool                    Scale( const Size& rNewSize, BmpScaleFlag nScaleFlag = BmpScaleFlag::Default );
 300
 301     /** Scale the bitmap
 302
 303         @param rScaleX
 304         The scale factor in x direction.
 305
 306         @param rScaleY
 307         The scale factor in y direction.
 308
 309         @param nScaleFlag
 310         Method of scaling - it is recommended that either BmpScaleFlag::Default or BmpScaleFlag::BestQuality be used.
 311
 312         @return true, if the operation was completed successfully.
 313      */
 314     bool                    Scale( const double& rScaleX, const double& rScaleY, BmpScaleFlag nScaleFlag = BmpScaleFlag::Default );
 315
 316     /**
 317       Returns true if bitmap scaling is considered to be fast.
 318
 319       Currently this returns true if OpenGL is used for scaling, otherwise false (CPU scaling is slower).
 320
 321       @since 4.5
 322     */
 323     static bool HasFastScale();
 324
 325     // Adapt the BitCount of rNew to BitCount of total, including grey or color palette
 326     // Can be used to create alpha/mask bitmaps after their processing in 24bit
 327     void AdaptBitCount(Bitmap& rNew) const;
 328
 329     /** Rotate bitmap by the specified angle
 330
 331         @param nAngle10
 332         The rotation angle in tenth of a degree. The bitmap is always rotated around its center.
 333
 334         @param rFillColor
 335         The color to use for filling blank areas. During rotation, the
 336         bitmap is enlarged such that the whole rotation result fits
 337         in. The empty spaces around that rotated original bitmap are
 338         then filled with this color.
 339
 340         @return true, if the operation was completed successfully.
 341      */
 342     bool                    Rotate( Degree10 nAngle10, const Color& rFillColor );
 343
 344     /** Create on-off mask from bitmap
 345
 346         This method creates a bitmask from the bitmap, where every
 347         pixel that equals rTransColor is set transparent, the rest
 348         opaque.
 349
 350         @param rTransColor
 351         Color value where the bitmask should be transparent
 352
 353         @param nTol
 354         Tolerance value. Specifies the maximal difference between
 355         rTransColor and the individual pixel values, such that the
 356         corresponding pixel is still regarded as transparent.
 357
 358         @return the resulting bitmask.
 359      */
 360     Bitmap                  CreateMask( const Color& rTransColor, sal_uInt8 nTol = 0 ) const;
 361
 362     /** Create region of similar colors in a given rectangle
 363
 364         @param rColor
 365         All pixel which have this color are included in the calculated region
 366
 367         @param rRect
 368         The rectangle within which matching pixel are looked for. This
 369         rectangle is always clipped to the bitmap dimensions.
 370
 371         @return the generated region.
 372      */
 373     vcl::Region                  CreateRegion( const Color& rColor, const tools::Rectangle& rRect ) const;
 374
 375     /** Replace all pixel where the given mask is on with the specified color
 376
 377         @param rMask
 378         Mask specifying which pixel should be replaced
 379
 380         @param rReplaceColor
 381         Color to be placed in all changed pixel
 382
 383         @return true, if the operation was completed successfully.
 384      */
 385     bool                    Replace( const Bitmap& rMask, const Color& rReplaceColor );
 386
 387     /** Merge bitmap with given background color according to specified alpha mask
 388
 389         @param rAlpha
 390         Alpha mask specifying the amount of background color to merge in
 391
 392         @param rMergeColor
 393         Background color to be used for merging
 394
 395         @return true, if the operation was completed successfully.
 396      */
 397     bool                    Replace( const AlphaMask& rAlpha, const Color& rMergeColor );
 398
 399     /** Replace all pixel having the search color with the specified color
 400
 401         @param rSearchColor
 402         Color specifying which pixel should be replaced
 403
 404         @param rReplaceColor
 405         Color to be placed in all changed pixel
 406
 407         @param nTol
 408         Tolerance value. Specifies the maximal difference between
 409         rSearchColor and the individual pixel values, such that the
 410         corresponding pixel is still regarded a match.
 411
 412         @return true, if the operation was completed successfully.
 413      */
 414     bool                    Replace( const Color& rSearchColor, const Color& rReplaceColor, sal_uInt8 nTol = 0 );
 415
 416     /** Replace all pixel having one the search colors with the corresponding replace color
 417
 418         @param pSearchColors
 419         Array of colors specifying which pixel should be replaced
 420
 421         @param rReplaceColors
 422         Array of colors to be placed in all changed pixel
 423
 424         @param nColorCount
 425         Size of the aforementioned color arrays
 426
 427         @param pTols
 428         Tolerance value. Specifies the maximal difference between
 429         pSearchColor colors and the individual pixel values, such that
 430         the corresponding pixel is still regarded a match.
 431
 432         @return true, if the operation was completed successfully.
 433      */
 434     bool                    Replace(
 435                                 const Color* pSearchColors,
 436                                 const Color* rReplaceColors,
 437                                 size_t nColorCount,
 438                                 sal_uInt8 const * pTols );
 439
 440     /** Convert the bitmap to a meta file
 441
 442         This works by putting continuous areas of the same color into
 443         polygons painted in this color, by tracing the area's bounding
 444         line.
 445
 446         @param rMtf
 447         The resulting meta file
 448
 449         @param cReduce
 450         If non-null, minimal size of bound rects for individual polygons. Smaller ones are ignored.
 451
 452         @param pProgress
 453         A callback for showing the progress of the vectorization
 454      */
 455     void                    Vectorize(
 456                                 GDIMetaFile& rMtf,
 457                                 sal_uInt8 cReduce,
 458                                 const Link<tools::Long,void>* pProgress );
 459
 460     /** Change various global color characteristics
 461
 462         @param nLuminancePercent
 463         Percent of luminance change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 464
 465         @param nContrastPercent
 466         Percent of contrast change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 467
 468         @param nChannelRPercent
 469         Percent of red channel change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 470
 471         @param nChannelGPercent
 472         Percent of green channel change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 473
 474         @param nChannelBPercent
 475         Percent of blue channel change, valid range [-100,100]. Values outside this range are clipped to the valid range.
 476
 477         @param fGamma
 478         Exponent of the gamma function applied to the bitmap. The
 479         value 1.0 results in no change, the valid range is
 480         (0.0,10.0]. Values outside this range are regarded as 1.0.
 481
 482         @param bInvert
 483         If true, invert the channel values with the logical 'not' operator
 484
 485         @param msoBrightness
 486         Use the same formula for brightness as used by MSOffice.
 487
 488         @return true, if the operation was completed successfully.
 489      */
 490     bool                    Adjust(
 491                                 short nLuminancePercent,
 492                                 short nContrastPercent = 0,
 493                                 short nChannelRPercent = 0,
 494                                 short nChannelGPercent = 0,
 495                                 short nChannelBPercent = 0,
 496                                 double fGamma = 1.0,
 497                                 bool bInvert = false,
 498                                 bool msoBrightness = false );
 499
 500 public:
 501     /** ReassignWithSize and recalculate bitmap.
 502
 503       ReassignWithSizes the bitmap, and recalculates the bitmap size based on the new bitmap.
 504
 505       @param rBitmap Bitmap to reassign and use for size calculation
 506      */
 507     SAL_DLLPRIVATE void     ReassignWithSize(const Bitmap& rBitmap);
 508
 509     SAL_DLLPRIVATE void     ImplMakeUnique();
 510     const std::shared_ptr<SalBitmap>& ImplGetSalBitmap() const { return mxSalBmp; }
 511     SAL_DLLPRIVATE void     ImplSetSalBitmap( const std::shared_ptr<SalBitmap>& xImpBmp );
 512
 513     SAL_DLLPRIVATE bool     ImplMakeGreyscales();
 514
 515 public:
 516
 517     BitmapInfoAccess*       AcquireInfoAccess();
 518     BitmapReadAccess*       AcquireReadAccess();
 519     BitmapWriteAccess*      AcquireWriteAccess();
 520     static void             ReleaseAccess( BitmapInfoAccess* pAccess );
 521
 522     typedef vcl::ScopedBitmapAccess<BitmapReadAccess, Bitmap, &Bitmap::AcquireReadAccess> ScopedReadAccess;
 523     typedef vcl::ScopedBitmapAccess<BitmapInfoAccess, Bitmap, &Bitmap::AcquireInfoAccess> ScopedInfoAccess;
 524
 525 private:
 526     SAL_DLLPRIVATE bool ImplConvertUp(vcl::PixelFormat ePixelFormat, Color const* pExtColor = nullptr);
 527     SAL_DLLPRIVATE bool ImplConvertDown8BPP(Color const* pExtColor = nullptr);
 528
 529 private:
 530     std::shared_ptr<SalBitmap> mxSalBmp;
 531     MapMode maPrefMapMode;
 532     Size maPrefSize;
 533 };
 534
 535 inline bool Bitmap::IsEmpty() const
 536 {
 537     return( mxSalBmp == nullptr );
 538 }
 539
 540 inline const MapMode& Bitmap::GetPrefMapMode() const
 541 {
 542     return maPrefMapMode;
 543 }
 544
 545 inline void Bitmap::SetPrefMapMode( const MapMode& rMapMode )
 546 {
 547     maPrefMapMode = rMapMode;
 548 }
 549
 550 inline const Size& Bitmap::GetPrefSize() const
 551 {
 552     return maPrefSize;
 553 }
 554
 555 inline void Bitmap::SetPrefSize( const Size& rSize )
 556 {
 557     maPrefSize = rSize;
 558 }
 559
 560 inline sal_Int64 Bitmap::GetSizeBytes() const
 561 {
 562     const auto aSizePixel = GetSizePixel();
 563     const sal_Int64 aBitCount = vcl::pixelFormatBitCount(getPixelFormat());
 564     sal_Int64 aSizeInBytes = (aSizePixel.Width() * aSizePixel.Height() * aBitCount) / 8;
 565     return aSizeInBytes;
 566 }
 567
 568 #endif // INCLUDED_VCL_BITMAP_HXX
 569
 570 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */