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