include/drawinglayer/primitive2d/baseprimitive2d.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 <drawinglayer/drawinglayerdllapi.h>
  23
  24 #include <drawinglayer/primitive2d/Primitive2DContainer.hxx>
  25 #include <drawinglayer/primitive2d/Primitive2DVisitor.hxx>
  26 #include <drawinglayer/geometry/viewinformation2d.hxx>
  27
  28 #include <com/sun/star/util/XAccounting.hpp>
  29 #include <basegfx/range/b2drange.hxx>
  30 #include <com/sun/star/graphic/XPrimitive2D.hpp>
  31 #include <comphelper/compbase.hxx>
  32 #include <salhelper/simplereferenceobject.hxx>
  33 #include <rtl/ref.hxx>
  34 #include <deque>
  35 #include <utility>
  36
  37 namespace drawinglayer::geometry
  38 {
  39 class ViewInformation2D;
  40 }
  41
  42 typedef comphelper::WeakComponentImplHelper<css::graphic::XPrimitive2D, css::util::XAccounting>
  43     BasePrimitive2DImplBase;
  44
  45 namespace drawinglayer::primitive2d
  46 {
  47 /** BasePrimitive2D class
  48
  49     Baseclass for all C++ implementations of css::graphic::XPrimitive2D
  50
  51     This class is strongly virtual due to the lack of getPrimitiveID() implementation.
  52     This is by purpose, this base class shall not be incarnated and be used directly as
  53     a XPrimitive2D.
  54
  55     It is noncopyable to make clear that a primitive is a read-only
  56     instance and copying or changing values is not intended. The idea is to hold all data
  57     needed for visualisation of this primitive in unchangeable form.
  58
  59     It is derived from cppu::BaseMutex to have a Mutex at hand; in a base
  60     implementation this may not be needed, but e.g. when buffering at last decomposition
  61     in a local member, multiple threads may try to decompose at the same time, so locking
  62     is needed to avoid race conditions seen from the UNO object implementation.
  63
  64     A method to get a simplified representation is provided by get2DDecomposition. The
  65     default implementation returns an empty sequence. The idea is that processors
  66     using this primitive and do not know it, may get the decomposition and process
  67     these instead. An example is e.g. a fat line, who's decomposition may contain
  68     the geometric representation of that line using filled polygon primitives. When
  69     the renderer knows how to handle fat lines, he may process this primitive directly;
  70     if not he can use the decomposition. With this functionality, renderers may operate by
  71     knowing only a small set of primitives.
  72
  73     When a primitive does not implement get2DDecomposition, it is called a 'Basic Primitive' and
  74     belongs to the set of primitives which a processor should be able to handle. Practice
  75     will define this minimal sets of primitives. When defined and the concept is proved,
  76     unique UNO APIs may be defined/implemented for these set to allow more intense work
  77     with primitives using UNO.
  78
  79     Current Basic 2D Primitives are:
  80
  81     - BitmapPrimitive2D (bitmap data, evtl. with transparence)
  82     - PointArrayPrimitive2D (single points)
  83     - PolygonHairlinePrimitive2D (hairline curves/polygons)
  84     - PolyPolygonColorPrimitive2D (colored polygons)
  85
  86     UPDATE: MetafilePrimitive2D (VCL Metafile) is taken off this list since
  87     it is implemented with the integration of CWS aw078 into DV300m69.
  88
  89     All other implemented primitives have a defined decomposition and can thus be
  90     decomposed down to this small set.
  91
  92     A renderer implementing support for this minimal set of primitives can completely
  93     render primitive-based visualisations. Of course, he also has to take states into account
  94     which are represented by GroupPrimitive2D derivations, see groupprimitive2d.hxx
  95
  96     To support getting the geometric BoundRect, getB2DRange is used. The default
  97     implementation will use the get2DDecomposition result and merge a range from the
  98     entries. Thus, an implementation is only necessary for the Basic Primitives, but
  99     of course speedups are possible (and are used) by implementing the method at higher-level
 100     primitives.
 101
 102     For primitive identification, getPrimitiveID is used currently in this implementations
 103     to allow a fast switch/case processing. This needs a unique identifier mechanism which
 104     currently uses defines (see drawinglayer_primitivetypes2d.hxx). For UNO primitive API
 105     it will be needed to add a unique descriptor (Name?) later to the API.
 106
 107     This base implementation provides mappings from the methods from XPrimitive2D
 108     (getDecomposition/getRange) to the appropriate methods in the C++ implementations
 109     (get2DDecomposition/getB2DRange). The PropertyValue ViewParameters is converted to
 110     the appropriate C++ implementation class ViewInformation2D.
 111
 112     This base class does not implement any buffering; e.g. buffering the decomposition
 113     and/or the range. These may be buffered anytime since the definition is that the primitive
 114     is read-only and thus unchangeable. This implies that the decomposition and/or getting
 115     the range will lead to the same result as last time, under the precondition that
 116     the parameter ViewInformation2D is the same as the last one. This is usually the case
 117     for view-independent primitives which are defined by not using ViewInformation2D
 118     in their get2DDecomposition/getB2DRange implementations.
 119 */
 120 class DRAWINGLAYERCORE_DLLPUBLIC BasePrimitive2D : public salhelper::SimpleReferenceObject
 121 {
 122     BasePrimitive2D(const BasePrimitive2D&) = delete;
 123     BasePrimitive2D& operator=(const BasePrimitive2D&) = delete;
 124
 125 public:
 126     // constructor/destructor
 127     BasePrimitive2D();
 128     virtual ~BasePrimitive2D() override;
 129
 130     /** the ==operator is mainly needed to allow testing newly-created primitives against their last
 131         incarnation which buffers/holds the made decompositions. The default implementation
 132         uses getPrimitive2DID()-calls to test if it's the same ID at last.
 133         Overridden implementations are then based on this implementation
 134      */
 135     virtual bool operator==(const BasePrimitive2D& rPrimitive) const;
 136     bool operator!=(const BasePrimitive2D& rPrimitive) const { return !operator==(rPrimitive); }
 137
 138     /// The default implementation will use getDecomposition results to create the range
 139     virtual basegfx::B2DRange
 140     getB2DRange(const geometry::ViewInformation2D& rViewInformation) const;
 141
 142     /** provide unique ID for fast identifying of known primitive implementations in renderers. These use
 143         the defines from drawinglayer_primitivetypes2d.hxx to define unique IDs.
 144      */
 145     virtual sal_uInt32 getPrimitive2DID() const = 0;
 146
 147     /// The default implementation will return an empty sequence
 148     virtual void get2DDecomposition(Primitive2DDecompositionVisitor& rVisitor,
 149                                     const geometry::ViewInformation2D& rViewInformation) const;
 150
 151     // Methods from XPrimitive2D
 152
 153     /** The getDecomposition implementation for UNO API will use getDecomposition from this implementation. It
 154         will construct a ViewInformation2D from the ViewParameters for that purpose
 155      */
 156     Primitive2DContainer
 157     getDecomposition(const css::uno::Sequence<css::beans::PropertyValue>& rViewParameters);
 158
 159     /** The getRange implementation for UNO API will use getRange from this implementation. It
 160         will construct a ViewInformation2D from the ViewParameters for that purpose
 161      */
 162     css::geometry::RealRectangle2D
 163     getRange(const css::uno::Sequence<css::beans::PropertyValue>& rViewParameters);
 164
 165     // XAccounting
 166     virtual sal_Int64 estimateUsage();
 167 };
 168
 169 /**
 170   Rather than make all the BasePrimitive2D classes bear the cost of being an UNO
 171   object, we just wrap the top level BasePrimitive2D in this class when we need
 172   to pass them over UNO
 173 */
 174 class DRAWINGLAYERCORE_DLLPUBLIC UnoPrimitive2D final : public BasePrimitive2DImplBase
 175 {
 176     UnoPrimitive2D(const UnoPrimitive2D&) = delete;
 177     UnoPrimitive2D& operator=(const UnoPrimitive2D&) = delete;
 178
 179 public:
 180     // constructor/destructor
 181     UnoPrimitive2D(rtl::Reference<BasePrimitive2D> xPrimitive)
 182         : mxPrimitive(std::move(xPrimitive))
 183     {
 184     }
 185     virtual ~UnoPrimitive2D() override;
 186
 187     // Methods from XPrimitive2D
 188
 189     /** The getDecomposition implementation for UNO API will use getDecomposition from this implementation. It
 190         will construct a ViewInformation2D from the ViewParameters for that purpose
 191      */
 192     virtual css::uno::Sequence<::css::uno::Reference<::css::graphic::XPrimitive2D>> SAL_CALL
 193     getDecomposition(const css::uno::Sequence<css::beans::PropertyValue>& rViewParameters) override;
 194
 195     /** The getRange implementation for UNO API will use getRange from this implementation. It
 196         will construct a ViewInformation2D from the ViewParameters for that purpose
 197      */
 198     virtual css::geometry::RealRectangle2D SAL_CALL
 199     getRange(const css::uno::Sequence<css::beans::PropertyValue>& rViewParameters) override;
 200
 201     // XAccounting
 202     virtual sal_Int64 SAL_CALL estimateUsage() override;
 203
 204     rtl::Reference<BasePrimitive2D> const& getBasePrimitive2D() const { return mxPrimitive; }
 205
 206 private:
 207     rtl::Reference<BasePrimitive2D> mxPrimitive;
 208 };
 209
 210 } // end of namespace drawinglayer::primitive2d
 211
 212 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */