include/basegfx/polygon/b2dpolypolygoncutter.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_BASEGFX_POLYGON_B2DPOLYPOLYGONCUTTER_HXX
  21 #define INCLUDED_BASEGFX_POLYGON_B2DPOLYPOLYGONCUTTER_HXX
  22
  23 #include <basegfx/polygon/b2dpolypolygon.hxx>
  24 #include <basegfx/basegfxdllapi.h>
  25
  26
  27
  28 namespace basegfx
  29 {
  30     namespace tools
  31     {
  32         /** Solve all crossovers (aka self-intersections) in a polyPolygon.
  33
  34             This re-layouts all contained polygons so that the result
  35             will contain only non-cutting polygons. For that reason,
  36             points will be added at crossover and touch points and the
  37             single Polygons may be re-combined. The orientations of
  38             the contained polygons in not changed but used as
  39             topological information.  Self crossovers of the contained
  40             sub-polygons are implicitly handled, but to not lose the
  41             topological information, it may be necessary to remove
  42             self-intersections of the contained sub-polygons in a
  43             preparing step and to explicitly correct their
  44             orientations.
  45         */
  46         BASEGFX_DLLPUBLIC B2DPolyPolygon solveCrossovers(const B2DPolyPolygon& rCandidate);
  47
  48         /** Solve all crossovers (aka self-intersections) in a Polygon
  49
  50             Same as above, but for single polygons. Result will be
  51             free of self-intersections. When result contains multiple
  52             polygons, it may be necessary to rearrange their
  53             orientations since holes may have been created (use
  54             correctOrientations eventually).
  55         */
  56         BASEGFX_DLLPUBLIC B2DPolyPolygon solveCrossovers(const B2DPolygon& rCandidate);
  57
  58         /** Strip neutral polygons from PolyPolygon.
  59
  60             Neutral polygons are ones who's orientation is neutral, so
  61             normally they have no volume -> just closed paths. A
  62             polygon with the same positive and negative oriented
  63             volume is also neutral, so this may not be wanted. It is
  64             safe to call with self-intersection-free polygons, though
  65             (that's where it's mostly used).
  66         */
  67         BASEGFX_DLLPUBLIC B2DPolyPolygon stripNeutralPolygons(const B2DPolyPolygon& rCandidate);
  68
  69         /** Remove unnecessary/non-displayed polygons.
  70
  71             Works only correct with self-intersection-free
  72             polygons. For each polygon, the depth for the PolyPolygon
  73             is calculated. The orientation is used to identify holes.
  74             Start value for holes is -1, for polygons it's zero. Ech
  75             time a polygon is contained in another one, it's depth is
  76             increased when inside a polygon, decreased when inside a
  77             hole. The result is a depth which e.g. is -1 for holes
  78             outside everything, 1 for a polygon covered by another
  79             polygon and zero for e.g. holes in a polygon or polygons
  80             outside everythig else.  In the 2nd step, all polygons
  81             with depth other than zero are removed. If bKeepAboveZero
  82             is used, all polygons < 1 are removed. The bKeepAboveZero
  83             mode is useful for clipping, e.g. just append one polygon
  84             to another and use this mode -> only parts where two
  85             polygons overlapped will be kept.  In combination with
  86             correct orientation of the input orientations and the
  87             SolveCrossover calls this can be combined for logical
  88             polygon operations or polygon clipping.
  89         */
  90         BASEGFX_DLLPUBLIC B2DPolyPolygon stripDispensablePolygons(const B2DPolyPolygon& rCandidate, bool bKeepAboveZero = false);
  91
  92         /** Emulate nonzero winding rule filling.
  93
  94             Geometrically convert PolyPolygons which are proposed to
  95             use nonzero fill rule to a representation where evenodd
  96             paint will give the same result. To do this all
  97             intersections and self-intersections get solved (the
  98             polygons will be rearranged if needed). Then all polygons
  99             which are inside another one with the same orientation get
 100             deleted
 101         */
 102         BASEGFX_DLLPUBLIC B2DPolyPolygon createNonzeroConform(const B2DPolyPolygon& rCandidate);
 103
 104         // For convenience: The four basic operations OR, XOR, AND and DIFF for
 105         // two PolyPolygons. These are combinations of the above methods. To not be forced
 106         // to do evtl. already done preparations twice, You have to do the operations Yourself.
 107
 108         // A source preparation consists of preparing it to be seen as XOR-Rule PolyPolygon,
 109         // so it is freed of intersections, self-intersections and the orientations are corrected.
 110         // Important is that it will define the same areas as before, but is intersection-free.
 111         // As an example think about a single polygon looping in itself and having holes. To
 112         // topologically correctly handle this, it is necessary to remove all intersections and
 113         // to correct the orientations. The orientation of the isolated holes e.g. will be negative.
 114         // Topologically it is necessary to prepare each polygon which is seen as entity. It is
 115         // not sufficient just to concatenate them and prepare the result, this may be topologically
 116         // different since the simple concatenation will be seen as XOR. To work correctly, You
 117         // may need to OR those polygons.
 118
 119         /// prep for ops - solve self-intersections and intersections, remove neutral parts and check orientations.
 120         BASEGFX_DLLPUBLIC B2DPolyPolygon prepareForPolygonOperation(const B2DPolygon& rCandidate);
 121         /// prep for ops - solve self-intersections and intersections, remove neutral parts and check orientations.
 122         BASEGFX_DLLPUBLIC B2DPolyPolygon prepareForPolygonOperation(const B2DPolyPolygon& rCandidate);
 123
 124         /// OR: Return all areas where CandidateA or CandidateB exist
 125         BASEGFX_DLLPUBLIC B2DPolyPolygon solvePolygonOperationOr(const B2DPolyPolygon& rCandidateA, const B2DPolyPolygon& rCandidateB);
 126
 127         /// XOR: Return all areas where CandidateA or CandidateB exist, but not both
 128         BASEGFX_DLLPUBLIC B2DPolyPolygon solvePolygonOperationXor(const B2DPolyPolygon& rCandidateA, const B2DPolyPolygon& rCandidateB);
 129
 130         /// AND: Return all areas where CandidateA and CandidateB exist
 131         BASEGFX_DLLPUBLIC B2DPolyPolygon solvePolygonOperationAnd(const B2DPolyPolygon& rCandidateA, const B2DPolyPolygon& rCandidateB);
 132
 133         /// DIFF: Return all areas where CandidateA is not covered by CandidateB (cut B out of A)
 134         BASEGFX_DLLPUBLIC B2DPolyPolygon solvePolygonOperationDiff(const B2DPolyPolygon& rCandidateA, const B2DPolyPolygon& rCandidateB);
 135
 136         /** merge all single PolyPolygons to a single, OR-ed PolyPolygon
 137
 138             @param rInput
 139             The source PolyPolygons
 140
 141             @return A single PolyPolygon containing the Or-merged result
 142         */
 143         BASEGFX_DLLPUBLIC B2DPolyPolygon mergeToSinglePolyPolygon(const B2DPolyPolygonVector& rInput);
 144
 145     } // end of namespace tools
 146 } // end of namespace basegfx
 147
 148
 149
 150
 151 #endif // INCLUDED_BASEGFX_POLYGON_B2DPOLYPOLYGONCUTTER_HXX
 152
 153 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */