INTEGRATION: CWS aw033 (1.7.2); FILE MERGED

2008/05/14 14:42:30 aw 1.7.2.4: RESYNC: (1.8-1.9); FILE MERGED
2007/12/12 13:13:23 aw 1.7.2.3: #i39532# clipping changes
2007/12/03 13:53:13 aw 1.7.2.2: #i39532# checkin for resync
2005/10/28 11:21:56 aw 1.7.2.1: #i39532#

1 files changed, 44 insertions, 24 deletions

diff --git a/basegfx/inc/basegfx/polygon/b2dpolypolygoncutter.hxx b/basegfx/inc/basegfx/polygon/b2dpolypolygoncutter.hxx
index 74dc57877c4d..9474e51e3904 100644
--- a/basegfx/inc/basegfx/polygon/b2dpolypolygoncutter.hxx
+++ b/basegfx/inc/basegfx/polygon/b2dpolypolygoncutter.hxx
@@ -7,7 +7,7 @@
  * OpenOffice.org - a multi-platform office productivity suite
  *
  * $RCSfile: b2dpolypolygoncutter.hxx,v $
- * $Revision: 1.9 $
+ * $Revision: 1.10 $
  *
  * This file is part of OpenOffice.org.
  *
@@ -31,46 +31,33 @@
 #ifndef _BGFX_POLYGON_B2DPOLYPOLYGONCUTTER_HXX
 #define _BGFX_POLYGON_B2DPOLYPOLYGONCUTTER_HXX
 
-//#ifndef _SAL_TYPES_H_
-//#include <sal/types.h>
-//#endif
-//
-//#ifndef _BGFX_POINT_B2DPOINT_HXX
-//#include <basegfx/point/b2dpoint.hxx>
-//#endif
-//
-//#ifndef _BGFX_RANGE_B2DRANGE_HXX
-//#include <basegfx/range/b2drange.hxx>
-//#endif
-
 #include <basegfx/polygon/b2dpolypolygon.hxx>
 
-//#include <vector>
-
 //////////////////////////////////////////////////////////////////////////////
 
 namespace basegfx
 {
     namespace tools
     {
-        // solve all crossovers in a polyPolygon. This re-layouts all contained polygons so that the
+        // Solve all crossovers in a polyPolygon. This re-layouts all contained polygons so that the
         // result will contain only non-cutting polygons. For that reason, points will be added at
         // crossover and touch points and the single Polygons may be re-combined. The orientations
-        // of the contained polygons in not changed but used as hints.
-        // If bSelfCrossovers is set, first all self-intersections of the contained polygons will be
-        // solved.
-        B2DPolyPolygon SolveCrossovers(const B2DPolyPolygon& rCandidate, bool bSelfCrossovers = true);
+        // of the contained polygons in not changed but used as topological information.
+        // Self crossovers of the contained sub-polygons are implicitely handled, but to not lose
+        // the topological information, it may be necessary to remove self-intersections of the
+        // contained sub-polygons in a preparing step and to explicitely correct their orientations.
+        B2DPolyPolygon solveCrossovers(const B2DPolyPolygon& rCandidate);
 
-        // version for single polygons. This is for solving self-intersections. Result will be free of
+        // Version for single polygons. This is for solving self-intersections. Result will be free of
         // crossovers. When result contains multiple polygons, it may be necessary to rearrange their
         // orientations since holes may have been created (use correctOrientations eventually).
-        B2DPolyPolygon SolveCrossovers(const B2DPolygon& rCandidate);
+        B2DPolyPolygon solveCrossovers(const B2DPolygon& rCandidate);
 
         // Neutral polygons will be stripped. Neutral polygons are ones who's orientation is
         // neutral, so normally they have no volume -> just closed paths. A polygon with the same
         // positive and negative oriented volume is also neutral, so this may not be wanted. It is
         // safe to call with crossover-free polygons, though (that's where it's mostly used).
-        B2DPolyPolygon StripNeutralPolygons(const B2DPolyPolygon& rCandidate);
+        B2DPolyPolygon stripNeutralPolygons(const B2DPolyPolygon& rCandidate);
 
         // Remove not necessary polygons. Works only correct with crossover-free polygons. For each
         // polygon, the depth for the PolyPolygon is calculated. The orientation is used to identify holes.
@@ -83,7 +70,40 @@ namespace basegfx
         // one polygon to another and use this mode -> only parts where two polygons overlapped will be kept.
         // In combination with correct orientation of the input orientations and the SolveCrossover calls this
         // can be combined for logical polygon operations or polygon clipping.
-        B2DPolyPolygon StripDispensablePolygons(const B2DPolyPolygon& rCandidate, bool bKeepAboveZero = false);
+        B2DPolyPolygon stripDispensablePolygons(const B2DPolyPolygon& rCandidate, bool bKeepAboveZero = false);
+
+        // For convenience: The four basic operations OR, XOR, AND and DIFF for
+        // two PolyPolygons. These are combinations of the above methods. To not be forced
+        // to do evtl. already done preparations twice, You have to do the operations Yourself.
+        //
+        // A source preparation consists of preparing it to be seen as XOR-Rule PolyPolygon,
+        // so it is freed of intersections, self-intersections and the orientations are corrected.
+        // Important is that it will define the same areas as before, but is intersection-free.
+        // As an example think about a single polygon looping in itself and having holes. To
+        // topologically correctly handle this, it is necessary to remove all intersections and
+        // to correct the orientations. The orientation of the isolated holes e.g. will be negative.
+        // Topologically it is necessary to prepare each polygon which is seen as entity. It is
+        // not sufficient just to concatenate them and prepare the result, this may be topologically
+        // different since the simple concatenation will be seen as XOR. To work correctly, You
+        // may need to OR those polygons.
+
+        // Preparations: solve self-intersections and intersections, remove neutral
+        // parts and correct orientations.
+        B2DPolyPolygon prepareForPolygonOperation(const B2DPolygon& rCandidate);
+        B2DPolyPolygon prepareForPolygonOperation(const B2DPolyPolygon& rCandidate);
+
+        // OR: Return all areas where CandidateA or CandidateB exist
+        B2DPolyPolygon solvePolygonOperationOr(const B2DPolyPolygon& rCandidateA, const B2DPolyPolygon& rCandidateB);
+
+        // XOR: Return all areas where CandidateA or CandidateB exist, but not both
+        B2DPolyPolygon solvePolygonOperationXor(const B2DPolyPolygon& rCandidateA, const B2DPolyPolygon& rCandidateB);
+
+        // AND: Return all areas where CandidateA and CandidateB exist
+        B2DPolyPolygon solvePolygonOperationAnd(const B2DPolyPolygon& rCandidateA, const B2DPolyPolygon& rCandidateB);
+
+        // DIFF: Return all areas where CandidateA is not covered by CandidateB (cut B out of A)
+        B2DPolyPolygon solvePolygonOperationDiff(const B2DPolyPolygon& rCandidateA, const B2DPolyPolygon& rCandidateB);
+
     } // end of namespace tools
 } // end of namespace basegfx