include/drawinglayer/processor2d/baseprocessor2d.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_DRAWINGLAYER_PROCESSOR2D_BASEPROCESSOR2D_HXX
  21 #define INCLUDED_DRAWINGLAYER_PROCESSOR2D_BASEPROCESSOR2D_HXX
  22
  23 #include <drawinglayer/drawinglayerdllapi.h>
  24
  25 #include <drawinglayer/primitive2d/Primitive2DVisitor.hxx>
  26 #include <drawinglayer/primitive2d/baseprimitive2d.hxx>
  27 #include <drawinglayer/geometry/viewinformation2d.hxx>
  28
  29
  30 namespace drawinglayer::processor2d
  31     {
  32         /** BaseProcessor2D class
  33
  34             Base class for all C++ implementations of instances which process
  35             primitives.
  36
  37             Instances which process primitives can be renderers, but also stuff
  38             for HitTests, BoundRect calculations and/or animation processing. The
  39             main usage are renderers, but they are supposed to handle any primitive
  40             processing.
  41
  42             The base implementation is constructed with a ViewInformation2D which
  43             is accessible throughout the processor implementations. The idea is
  44             to construct any processor with a given ViewInformation2D. To be able
  45             to handle primitives which need to change the current transformation
  46             (as e.g. TransformPrimitive2D) it is allowed for the processor implementation
  47             to change its local value using updateViewInformation.
  48
  49             The basic processing method is process(..) which gets handed over the
  50             sequence of primitives to process. For convenience of the C++ implementations,
  51             the default implementation of process(..) maps all accesses to primitives to
  52             single calls to processBasePrimitive2D(..) where the primitive in question is
  53             already casted to the C++ implementation class.
  54
  55             The process(..) implementation makes a complete iteration over the given
  56             sequence of primitives. If the Primitive is not derived from BasePrimitive2D
  57             and thus not part of the C++ implementations, it converts ViewInformation2D
  58             to the corresponding API implementation (a uno::Sequence< beans::PropertyValue >)
  59             and recursively calls the method process(..) at the primitive with the decomposition
  60             derived from that primitive. This is the preparation to handle unknown implementations
  61             of the css::graphic::XPrimitive2D interface in the future.
  62
  63             So, to implement a basic processor, it is necessary to override and implement the
  64             processBasePrimitive2D(..) method. A minimal renderer has to support the
  65             Basic Primitives (see baseprimitive2d.hxx) and the Grouping Primitives (see
  66             groupprimitive2d.hxx). These are (currently):
  67
  68             Basic Primitives:
  69
  70             - BitmapPrimitive2D (bitmap data, possibly with transparency)
  71             - PointArrayPrimitive2D (single points)
  72             - PolygonHairlinePrimitive2D (hairline curves/polygons)
  73             - PolyPolygonColorPrimitive2D (colored polygons)
  74
  75             Grouping Primitives:
  76
  77             - TransparencePrimitive2D (objects with freely defined transparence)
  78             - InvertPrimitive2D (for XOR)
  79             - MaskPrimitive2D (for masking)
  80             - ModifiedColorPrimitive2D (for a stack of color modifications)
  81             - TransformPrimitive2D (for a transformation stack)
  82
  83             A processor doing so is a minimal processor. Of course a processor may
  84             handle any higher-level primitive (that has a decomposition implementation)
  85             for more direct data access or performance reasons, too.
  86
  87             The main part of a processBasePrimitive2D implementation is a switch..case
  88             construct, looking like the following:
  89
  90             void foo::processBasePrimitive2D(const BasePrimitive2D& rCandidate)
  91             {
  92                 switch(rCandidate.getPrimitive2DID())
  93                 {
  94                     case PRIMITIVE2D_ID_??? :
  95                     {
  96                         // process PRIMITIVE2D_ID_??? here...
  97
  98                         ...
  99
 100                         break;
 101                     }
 102
 103                     ...
 104
 105                     default :
 106                     {
 107                         // process recursively
 108                         process(rCandidate.get2DDecomposition(getViewInformation2D()));
 109                         break;
 110                     }
 111                 }
 112             }
 113
 114             The default case makes the processor work with all complex primitives
 115             by recursively using their decomposition.
 116
 117             You can also add a case for ignoring primitives by using:
 118
 119                     case PRIMITIVE2D_ID_...IGNORE.A.. :
 120                     case PRIMITIVE2D_ID_...IGNORE.B.. :
 121                     case PRIMITIVE2D_ID_...IGNORE.C.. :
 122                     {
 123                         // ignore these primitives by neither processing nor
 124                         // recursively processing their decomposition
 125                         break;
 126                     }
 127
 128             Another useful case is embedding the processing of a complex primitive by
 129             bracketing it with some actions:
 130
 131                     case PRIMITIVE2D_ID_SOME_TEXT :
 132                     {
 133                         // encapsulate e.g. with changing local variables, e.g.
 134                         // sometimes it's good to know if a basic primitive is
 135                         // part of a text, especially when not handling the text
 136                         // self but by purpose want to handle the decomposed
 137                         // geometries in the processor
 138                         startText();
 139                         process(rCandidate.get2DDecomposition(getViewInformation2D()));
 140                         endText();
 141                         break;
 142                     }
 143
 144             As an example a processor collecting the outlines of a sequence of primitives
 145             only needs to handle some Basic Primitives and create outline and collect
 146             outline polygons e.g. for primitives with area like BitmapPrimitive2D (a
 147             rectangle) and PolyPolygonColorPrimitive2D. When also handling the Grouping
 148             Primitives MaskPrimitive2D (e.g. ignoring its content, using the mask polyPolygon)
 149             and TransformPrimitive2D (to have the correct local transformation), a processor
 150             creating the outline can be written using just four (4) primitives. As a tipp, it can
 151             be helpful to add many for the purpose not interesting higher level primitives
 152             to not force their decomposition to be created and/or parsed.
 153          */
 154         class DRAWINGLAYER_DLLPUBLIC BaseProcessor2D : public  drawinglayer::primitive2d::Primitive2DDecompositionVisitor
 155         {
 156         private:
 157             /// The ViewInformation2D itself. It's private to isolate accesses to it
 158             geometry::ViewInformation2D                     maViewInformation2D;
 159
 160         protected:
 161             /*  access method to allow the implementations to change the current
 162                 ViewInformation2D if needed. This allows isolating these accesses
 163                 later if needed
 164              */
 165             void updateViewInformation(const geometry::ViewInformation2D& rViewInformation2D)
 166             {
 167                 maViewInformation2D = rViewInformation2D;
 168             }
 169
 170             /*  as tooling, the process() implementation takes over API handling and calls this
 171                 virtual render method when the primitive implementation is BasePrimitive2D-based.
 172                 Default implementation does nothing
 173              */
 174             virtual void processBasePrimitive2D(const primitive2d::BasePrimitive2D& rCandidate);
 175
 176             void process(const primitive2d::BasePrimitive2D& rCandidate);
 177
 178             // Primitive2DDecompositionVisitor
 179             virtual void visit(const primitive2d::Primitive2DReference&) override final;
 180             virtual void visit(const primitive2d::Primitive2DContainer&) override final;
 181             virtual void visit(primitive2d::Primitive2DContainer&&) override final;
 182
 183         public:
 184             /// constructor/destructor
 185             explicit BaseProcessor2D(geometry::ViewInformation2D aViewInformation);
 186             virtual ~BaseProcessor2D();
 187
 188             /// the central processing method
 189             void process(const primitive2d::Primitive2DContainer& rSource);
 190
 191             /// data read access
 192             const geometry::ViewInformation2D& getViewInformation2D() const { return maViewInformation2D; }
 193         };
 194
 195 } // end of namespace drawinglayer::processor2d
 196
 197
 198 #endif //INCLUDED_DRAWINGLAYER_PROCESSOR2D_BASEPROCESSOR2D_HXX
 199
 200 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */