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