LCOV - code coverage report
Current view: top level - include/drawinglayer/processor2d - baseprocessor2d.hxx (source / functions) Hit Total Coverage
Test: commit e02a6cb2c3e2b23b203b422e4e0680877f232636 Lines: 0 4 0.0 %
Date: 2014-04-14 Functions: 0 2 0.0 %
Legend: Lines: hit not hit

          Line data    Source code
       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             :             Base class 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, eventually with transparency)
      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 primitive (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           0 :             void updateViewInformation(const geometry::ViewInformation2D& rViewInformation2D)
     168             :             {
     169           0 :                 maViewInformation2D = rViewInformation2D;
     170           0 :             }
     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           0 :             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: */

Generated by: LCOV version 1.10