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