include/canvas/canvastools.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_CANVAS_CANVASTOOLS_HXX
  21 #define INCLUDED_CANVAS_CANVASTOOLS_HXX
  22
  23 #include <com/sun/star/uno/Reference.hxx>
  24 #include <com/sun/star/uno/Sequence.hxx>
  25 #include <com/sun/star/uno/RuntimeException.hpp>
  26 #include <osl/diagnose.h>
  27 #include <rtl/ustring.hxx>
  28 #include <sal/log.hxx>
  29
  30 #include <math.h>
  31 #include <string.h>
  32 #include <vector>
  33 #include <limits>
  34
  35 #include <canvas/canvastoolsdllapi.h>
  36
  37 namespace basegfx
  38 {
  39     class B2DHomMatrix;
  40     class B2DRange;
  41     class B2IRange;
  42     class B2IPoint;
  43     class B2DPolyPolygon;
  44 }
  45
  46 namespace com::sun::star::geometry
  47 {
  48     struct RealSize2D;
  49     struct IntegerSize2D;
  50     struct AffineMatrix2D;
  51     struct Matrix2D;
  52 }
  53
  54 namespace com::sun::star::rendering
  55 {
  56     struct RenderState;
  57     struct ViewState;
  58     struct IntegerBitmapLayout;
  59     class  XCanvas;
  60     struct Texture;
  61     class  XIntegerBitmapColorSpace;
  62 }
  63
  64 namespace com::sun::star::awt
  65 {
  66     struct Rectangle;
  67     class  XWindow2;
  68 }
  69
  70 namespace com::sun::star::beans {
  71     struct PropertyValue;
  72 }
  73
  74 class Color;
  75 class OutputDevice;
  76
  77 namespace canvas
  78 {
  79     namespace tools
  80     {
  81         /** Compute the next highest power of 2 of a 32-bit value
  82
  83             Code devised by Sean Anderson, in good ole HAKMEM
  84             tradition.
  85
  86             @return 1 << (lg(x - 1) + 1)
  87         */
  88         inline sal_uInt32 nextPow2( sal_uInt32 x )
  89         {
  90             --x;
  91             x |= x >> 1;
  92             x |= x >> 2;
  93             x |= x >> 4;
  94             x |= x >> 8;
  95             x |= x >> 16;
  96
  97             return ++x;
  98         }
  99
 100         /**
 101          *
 102          * Count the number of 1-bits of a n-bit value
 103          *
 104          */
 105
 106         /** Round given floating point value down to next integer
 107          */
 108         inline sal_Int32 roundDown( const double& rVal )
 109         {
 110             return static_cast< sal_Int32 >( floor( rVal ) );
 111         }
 112
 113         /** Round given floating point value up to next integer
 114          */
 115         inline sal_Int32 roundUp( const double& rVal )
 116         {
 117             return static_cast< sal_Int32 >( ceil( rVal ) );
 118         }
 119
 120         /** Create a RealSize2D with both coordinate values set to +infinity
 121          */
 122         CANVASTOOLS_DLLPUBLIC css::geometry::RealSize2D createInfiniteSize2D();
 123
 124
 125         // View- and RenderState utilities
 126
 127
 128         CANVASTOOLS_DLLPUBLIC css::rendering::RenderState&
 129             initRenderState( css::rendering::RenderState&                      renderState );
 130
 131         CANVASTOOLS_DLLPUBLIC css::rendering::ViewState&
 132             initViewState( css::rendering::ViewState&                          viewState );
 133
 134         CANVASTOOLS_DLLPUBLIC ::basegfx::B2DHomMatrix&
 135             getViewStateTransform( ::basegfx::B2DHomMatrix&                    transform,
 136                                    const css::rendering::ViewState&            viewState );
 137
 138         CANVASTOOLS_DLLPUBLIC css::rendering::ViewState&
 139             setViewStateTransform( css::rendering::ViewState&                  viewState,
 140                                    const ::basegfx::B2DHomMatrix&              transform );
 141
 142         CANVASTOOLS_DLLPUBLIC ::basegfx::B2DHomMatrix&
 143             getRenderStateTransform( ::basegfx::B2DHomMatrix&                  transform,
 144                                      const css::rendering::RenderState&        renderState );
 145
 146         CANVASTOOLS_DLLPUBLIC css::rendering::RenderState&
 147             setRenderStateTransform( css::rendering::RenderState&              renderState,
 148                                      const ::basegfx::B2DHomMatrix&            transform );
 149
 150         CANVASTOOLS_DLLPUBLIC css::rendering::RenderState&
 151             appendToRenderState( css::rendering::RenderState&                  renderState,
 152                                  const ::basegfx::B2DHomMatrix&                transform );
 153
 154         CANVASTOOLS_DLLPUBLIC css::rendering::RenderState&
 155             prependToRenderState( css::rendering::RenderState&                 renderState,
 156                                   const ::basegfx::B2DHomMatrix&               transform );
 157
 158         CANVASTOOLS_DLLPUBLIC ::basegfx::B2DHomMatrix&
 159             mergeViewAndRenderTransform( ::basegfx::B2DHomMatrix&              transform,
 160                                          const css::rendering::ViewState&      viewState,
 161                                          const css::rendering::RenderState&    renderState );
 162
 163
 164         // Matrix utilities
 165
 166
 167         CANVASTOOLS_DLLPUBLIC css::geometry::AffineMatrix2D&
 168             setIdentityAffineMatrix2D( css::geometry::AffineMatrix2D&  matrix );
 169
 170         CANVASTOOLS_DLLPUBLIC css::geometry::Matrix2D&
 171             setIdentityMatrix2D( css::geometry::Matrix2D&              matrix );
 172
 173
 174         // Special utilities
 175
 176
 177         /** Calc the bounding rectangle of a transformed rectangle.
 178
 179             The method applies the given transformation to the
 180             specified input rectangle, and returns the bounding box of
 181             the resulting output area.
 182
 183             @param o_Rect
 184             Output rectangle
 185
 186             @param i_Rect
 187             Input rectangle
 188
 189             @param i_Transformation
 190             Transformation to apply to the input rectangle
 191
 192             @return a reference to the resulting rectangle
 193          */
 194         CANVASTOOLS_DLLPUBLIC ::basegfx::B2DRange& calcTransformedRectBounds( ::basegfx::B2DRange&          o_Rect,
 195                                                         const ::basegfx::B2DRange&      i_Rect,
 196                                                         const ::basegfx::B2DHomMatrix&  i_Transformation );
 197
 198         /** Calc a transform that maps the upper, left corner of a
 199              rectangle to the origin.
 200
 201             The method is a specialized version of
 202             calcRectToRectTransform() (Removed now), mapping the input rectangle's
 203             the upper, left corner to the origin, and leaving the size
 204             untouched.
 205
 206             @param o_transform
 207             Output parameter, to receive the resulting transformation
 208             matrix.
 209
 210             @param i_srcRect
 211             Input parameter, specifies the original source
 212             rectangle. The resulting transformation will exactly map
 213             the source rectangle's upper, left corner to the origin.
 214
 215             @param i_transformation
 216             The original transformation matrix. This is changed with
 217             translations (if necessary), to exactly map the source
 218             rectangle to the origin.
 219
 220             @return a reference to the resulting transformation matrix
 221
 222             @see calcRectToRectTransform()
 223             @see calcTransformedRectBounds()
 224         */
 225         CANVASTOOLS_DLLPUBLIC ::basegfx::B2DHomMatrix& calcRectToOriginTransform( ::basegfx::B2DHomMatrix&      o_transform,
 226                                                             const ::basegfx::B2DRange&      i_srcRect,
 227                                                             const ::basegfx::B2DHomMatrix&  i_transformation );
 228
 229         /** Check whether a given rectangle is within another
 230             transformed rectangle.
 231
 232             This method checks for polygonal containedness, i.e. the
 233             transformed rectangle is not represented as an axis-aligned
 234             rectangle anymore (like calcTransformedRectBounds()), but
 235             polygonal. Thus, the insideness test is based on tight
 236             bounds.
 237
 238             @param rContainedRect
 239             This rectangle is checked, whether it is fully within the
 240             transformed rTransformRect.
 241
 242             @param rTransformRect
 243             This rectangle is transformed, and then checked whether it
 244             fully contains rContainedRect.
 245
 246             @param rTransformation
 247             This transformation is applied to rTransformRect
 248          */
 249         CANVASTOOLS_DLLPUBLIC bool isInside( const ::basegfx::B2DRange&         rContainedRect,
 250                        const ::basegfx::B2DRange&       rTransformRect,
 251                        const ::basegfx::B2DHomMatrix&   rTransformation );
 252
 253         /** Clip a scroll to the given bound rect
 254
 255             @param io_rSourceArea
 256             Source area to scroll. The resulting clipped source area
 257             is returned therein.
 258
 259             @param io_rDestPoint
 260             Destination point of the scroll (upper, left corner of
 261             rSourceArea after the scroll). The new, resulting
 262             destination point is returned therein.q
 263
 264             @param o_ClippedAreas
 265             Vector of rectangles in the <em>destination</em> area
 266             coordinate system, which are clipped away from the source
 267             area, and thus need extra updates (i.e. they are not
 268             correctly copy from the scroll operation, since there was
 269             no information about them in the source).
 270
 271             @param rBounds
 272             Bounds to clip against.
 273
 274             @return false, if the resulting scroll area is empty
 275          */
 276         CANVASTOOLS_DLLPUBLIC bool clipScrollArea( ::basegfx::B2IRange&                  io_rSourceArea,
 277                              ::basegfx::B2IPoint&                  io_rDestPoint,
 278                              ::std::vector< ::basegfx::B2IRange >& o_ClippedAreas,
 279                              const ::basegfx::B2IRange&            rBounds );
 280
 281         /** Clip a blit between two differently surfaces.
 282
 283             This method clips source and dest rect for a clip between
 284             two differently clipped surfaces, such that the resulting
 285             blit rects are fully within both clip areas.
 286
 287             @param io_rSourceArea
 288             Source area of the blit. Returned therein is the computed
 289             clipped source area.
 290
 291             @param io_rDestPoint
 292             Dest area of the blit. Returned therein is the computed
 293             clipped dest area.
 294
 295             @param rSourceBounds
 296             Clip bounds of the source surface
 297
 298             @param rDestBounds
 299             Clip bounds of the dest surface
 300
 301             @return false, if the resulting blit is empty, i.e. fully
 302             clipped away.
 303          */
 304         CANVASTOOLS_DLLPUBLIC ::basegfx::B2IRange spritePixelAreaFromB2DRange( const ::basegfx::B2DRange& rRange );
 305
 306         /** Retrieve various internal properties of the actual canvas implementation.
 307
 308             This method retrieves a bunch of internal, implementation-
 309             and platform-dependent values from the canvas
 310             implementation. Among them are for example operating
 311             system window handles. The actual layout and content of
 312             the returned sequence is dependent on the component
 313             implementation, undocumented and subject to change.
 314
 315             @param i_rxCanvas
 316             Input parameter, the canvas representation for which the device information
 317             is to be retrieved
 318
 319             @param o_rxParams
 320             Output parameter, the sequence of Anys that hold the device parameters. Layout is as described above
 321
 322             @return A reference to the resulting sequence of parameters
 323         */
 324         CANVASTOOLS_DLLPUBLIC css::uno::Sequence< css::uno::Any >& getDeviceInfo(
 325             const css::uno::Reference< css::rendering::XCanvas >& i_rxCanvas,
 326             css::uno::Sequence< css::uno::Any >& o_rxParams );
 327
 328         /** Return a color space for a default RGBA integer format
 329
 330             Use this method for dead-simple bitmap implementations,
 331             that map all their formats to 8888 RGBA color.
 332          */
 333         CANVASTOOLS_DLLPUBLIC css::uno::Reference< css::rendering::XIntegerBitmapColorSpace> const & getStdColorSpace();
 334
 335         /** Return a color space for a default RGB integer format
 336
 337             Use this method for dead-simple bitmap implementations,
 338             that map all their formats to 8888 RGB color (the last byte
 339             is unused).
 340          */
 341         CANVASTOOLS_DLLPUBLIC css::uno::Reference< css::rendering::XIntegerBitmapColorSpace> const & getStdColorSpaceWithoutAlpha();
 342
 343         /** Return a memory layout for a default RGBA integer format
 344
 345             Use this method for dead-simple bitmap implementations,
 346             that map all their formats to 8888 RGBA color.
 347          */
 348         CANVASTOOLS_DLLPUBLIC css::rendering::IntegerBitmapLayout getStdMemoryLayout(
 349             const css::geometry::IntegerSize2D& rBitmapSize );
 350
 351         /// Convert standard 8888 RGBA color to vcl color
 352         CANVASTOOLS_DLLPUBLIC css::uno::Sequence<sal_Int8> colorToStdIntSequence( const ::Color& rColor );
 353
 354         // Modelled closely after boost::numeric_cast, only that we
 355         // issue some trace output here and throw a RuntimeException
 356
 357         /** Cast numeric value into another (numeric) data type
 358
 359             Apart from converting the numeric value, this template
 360             also checks if any overflow, underflow, or sign
 361             information is lost (if yes, it throws an
 362             uno::RuntimeException.
 363          */
 364         template< typename Target, typename Source > inline Target numeric_cast( Source arg )
 365         {
 366             // typedefs abbreviating respective trait classes
 367             typedef ::std::numeric_limits< Source > SourceLimits;
 368             typedef ::std::numeric_limits< Target > TargetLimits;
 369
 370 #undef min
 371 #undef max
 372
 373             if( ( arg<0 && !TargetLimits::is_signed) ||                     // losing the sign here
 374                 ( SourceLimits::is_signed && arg<TargetLimits::min()) ||    // underflow will happen
 375                 ( arg>TargetLimits::max() ) )                               // overflow will happen
 376             {
 377 # if OSL_DEBUG_LEVEL > 2
 378                 SAL_WARN("canvas", "numeric_cast detected data loss");
 379 #endif
 380                 throw css::uno::RuntimeException(
 381                     "numeric_cast detected data loss",
 382                     nullptr );
 383             }
 384
 385             return static_cast<Target>(arg);
 386         }
 387
 388         CANVASTOOLS_DLLPUBLIC css::awt::Rectangle getAbsoluteWindowRect(
 389             const css::awt::Rectangle&                       rRect,
 390             const css::uno::Reference< css::awt::XWindow2 >& xWin  );
 391
 392         /** Retrieve for small bound marks around each corner of the given rectangle
 393          */
 394         CANVASTOOLS_DLLPUBLIC ::basegfx::B2DPolyPolygon getBoundMarksPolyPolygon( const ::basegfx::B2DRange& rRange );
 395
 396         /** Calculate number of gradient "strips" to generate (takes
 397            into account device resolution)
 398
 399            @param nColorSteps
 400            Maximal integer difference between all color stops, needed
 401            for smooth gradient color differences
 402          */
 403         CANVASTOOLS_DLLPUBLIC int calcGradientStepCount( ::basegfx::B2DHomMatrix&   rTotalTransform,
 404                                    const css::rendering::ViewState&   viewState,
 405                                    const css::rendering::RenderState& renderState,
 406                                    const css::rendering::Texture&     texture,
 407                                    int                                nColorSteps );
 408
 409         /** A very simplistic map for ASCII strings and arbitrary value
 410             types.
 411
 412             This class internally references a constant, static array of
 413             sorted MapEntries, and performs a binary search to look up
 414             values for a given query string. Note that this map is static,
 415             i.e. not meant to be extended at runtime.
 416
 417             @tpl ValueType
 418             The value type this map should store, associated with an ASCII
 419             string.
 420         */
 421         template< typename ValueType > class ValueMap
 422         {
 423         public:
 424             struct MapEntry
 425             {
 426                 const char*     maKey;
 427                 ValueType       maValue;
 428             };
 429
 430             /** Create a ValueMap for the given array of MapEntries.
 431
 432                 @param pMap
 433                 Pointer to a <em>static</em> array of MapEntries. Must
 434                 live longer than this object! Make absolutely sure that
 435                 the string entries passed via pMap are ASCII-only -
 436                 everything else might not yield correct string
 437                 comparisons, and thus will result in undefined behaviour.
 438
 439                 @param nEntries
 440                 Number of entries for pMap
 441
 442                 @param bCaseSensitive
 443                 Whether the map query should be performed case sensitive
 444                 or not. When bCaseSensitive is false, all MapEntry strings
 445                 must be lowercase!
 446             */
 447             ValueMap( const MapEntry*   pMap,
 448                       ::std::size_t     nEntries,
 449                       bool              bCaseSensitive ) :
 450                 mpMap( pMap ),
 451                 mnEntries( nEntries ),
 452                 mbCaseSensitive( bCaseSensitive )
 453             {
 454 #ifdef DBG_UTIL
 455                 // Ensure that map entries are sorted (and all lowercase, if this
 456                 // map is case insensitive)
 457                 const OString aStr( pMap->maKey );
 458                 if( !mbCaseSensitive &&
 459                     aStr != aStr.toAsciiLowerCase() )
 460                 {
 461                     SAL_WARN("canvas", "ValueMap::ValueMap(): Key is not lowercase " << pMap->maKey);
 462                 }
 463
 464                 if( mnEntries > 1 )
 465                 {
 466                     for( ::std::size_t i=0; i<mnEntries-1; ++i, ++pMap )
 467                     {
 468                         if( !mapComparator(pMap[0], pMap[1]) &&
 469                             mapComparator(pMap[1], pMap[0]) )
 470                         {
 471                             SAL_WARN("canvas", "ValueMap::ValueMap(): Map is not sorted, keys are wrong, "
 472                                       << pMap[0].maKey << " and " << pMap[1].maKey);
 473                             OSL_FAIL( "ValueMap::ValueMap(): Map is not sorted" );
 474                         }
 475
 476                         const OString aStr2( pMap[1].maKey );
 477                         if( !mbCaseSensitive &&
 478                             aStr2 != aStr2.toAsciiLowerCase() )
 479                         {
 480                             SAL_WARN("canvas", "ValueMap::ValueMap(): Key is not lowercase" << pMap[1].maKey);
 481                         }
 482                     }
 483                 }
 484 #endif
 485             }
 486
 487             /** Lookup a value for the given query string
 488
 489                 @param rName
 490                 The string to lookup. If the map was created with the case
 491                 insensitive flag, the lookup is performed
 492                 case-insensitive, otherwise, case-sensitive.
 493
 494                 @param o_rResult
 495                 Output parameter, which receives the value associated with
 496                 the query string. If no value was found, the referenced
 497                 object is kept unmodified.
 498
 499                 @return true, if a matching entry was found.
 500             */
 501             bool lookup( const OUString& rName,
 502                          ValueType&             o_rResult ) const
 503             {
 504                 // rName is required to contain only ASCII characters.
 505                 // TODO(Q1): Enforce this at upper layers
 506                 OString aKey( OUStringToOString( mbCaseSensitive ? rName : rName.toAsciiLowerCase(),
 507                                                                RTL_TEXTENCODING_ASCII_US ) );
 508                 MapEntry aSearchKey =
 509                     {
 510                         aKey.getStr(),
 511                         ValueType()
 512                     };
 513
 514                 const MapEntry* pEnd = mpMap+mnEntries;
 515                 const MapEntry* pRes = ::std::lower_bound( mpMap,
 516                                               pEnd,
 517                                               aSearchKey,
 518                                               &mapComparator );
 519                 if( pRes != pEnd )
 520                 {
 521                     // place to _insert before_ found - is it equal to
 522                     // the search key?
 523                     if( strcmp( pRes->maKey, aSearchKey.maKey ) == 0 )
 524                     {
 525                         // yep, correct entry found
 526                         o_rResult = pRes->maValue;
 527                         return true;
 528                     }
 529                 }
 530
 531                 // not found
 532                 return false;
 533             }
 534
 535         private:
 536             static bool mapComparator( const MapEntry& rLHS,
 537                                        const MapEntry& rRHS )
 538             {
 539                 return strcmp( rLHS.maKey,
 540                                rRHS.maKey ) < 0;
 541             }
 542
 543             const MapEntry*     mpMap;
 544             ::std::size_t       mnEntries;
 545             bool                mbCaseSensitive;
 546         };
 547
 548         CANVASTOOLS_DLLPUBLIC void clipOutDev(const css::rendering::ViewState& viewState,
 549                         const css::rendering::RenderState& renderState,
 550                         OutputDevice& rOutDev,
 551                         OutputDevice* p2ndOutDev=nullptr);
 552
 553         CANVASTOOLS_DLLPUBLIC void extractExtraFontProperties(const css::uno::Sequence<css::beans::PropertyValue>& rExtraFontProperties,
 554                         sal_uInt32& rEmphasisMark);
 555     }
 556 }
 557
 558 #endif /* INCLUDED_CANVAS_CANVASTOOLS_HXX */
 559
 560 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */