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