#i97509# added base class for 3d primitive, re-structured group primitives, added documentation

14 files changed, 77 insertions, 49 deletions

diff --git a/drawinglayer/inc/drawinglayer/primitive3d/baseprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/baseprimitive3d.hxx
index 4dc5a7da4acb..73d28c82ebda 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/baseprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/baseprimitive3d.hxx
@@ -79,7 +79,12 @@ namespace drawinglayer
         /** Baseclass for all C++ implementations of com::sun::star::graphic::XPrimitive2D
 
             The description/functionality is identical with the 2D case in baseprimitive2d.hxx,
-            please see there for detailed information
+            please see there for detailed information.
+
+            Current Basic 3D Primitives are:
+
+            - PolygonHairlinePrimitive3D (for 3D hairlines)
+            - PolyPolygonMaterialPrimitive3D (for 3D filled plane polygons)
          */
         class BasePrimitive3D
         :   private boost::noncopyable,
@@ -96,7 +101,7 @@ namespace drawinglayer
             /** the ==operator is mainly needed to allow testing newly-created high level primitives against their last
                 incarnation which buffers/holds the decompositionsThe default implementation
                 uses getPrimitive3DID()-calls to test if it's the same ID at last. Overloaded implementation are then
-                based on this implementation
+                based on this implementation.
              */
             virtual bool operator==( const BasePrimitive3D& rPrimitive ) const;
             bool operator!=( const BasePrimitive3D& rPrimitive ) const { return !operator==(rPrimitive); }
@@ -133,7 +138,7 @@ namespace drawinglayer
 } // end of namespace drawinglayer
 
 //////////////////////////////////////////////////////////////////////////////
-// BufDecPrimitive3D class
+// BufferedDecompositionPrimitive3D class
 
 namespace drawinglayer
 {
@@ -144,32 +149,32 @@ namespace drawinglayer
             The description/functionality is identical with the 2D case in baseprimitive2d.hxx,
             please see there for detailed information
          */
-        class BufDecPrimitive3D
+        class BufferedDecompositionPrimitive3D
         :   public BasePrimitive3D
         {
         private:
-            /// a sequence used for buffering the last createLocal3DDecomposition() result
-            Primitive3DSequence                             maLocal3DDecomposition;
+            /// a sequence used for buffering the last create3DDecomposition() result
+            Primitive3DSequence                             maBuffered3DDecomposition;
 
         protected:
-            /** access methods to maLocal3DDecomposition. The usage of this methods may allow
+            /** access methods to maBuffered3DDecomposition. The usage of this methods may allow
                 later thread-safe stuff to be added if needed. Only to be used by getDecomposition()
                 implementations for buffering the last decomposition.
              */
-            const Primitive3DSequence& getLocal3DDecomposition() const { return maLocal3DDecomposition; }
-            void setLocal3DDecomposition(const Primitive3DSequence& rNew) { maLocal3DDecomposition = rNew; }
+            const Primitive3DSequence& getBuffered3DDecomposition() const { return maBuffered3DDecomposition; }
+            void setBuffered3DDecomposition(const Primitive3DSequence& rNew) { maBuffered3DDecomposition = rNew; }
 
             /** method which is to be used to implement the local decomposition of a 2D primitive. The default
                 implementation will just return an empty decomposition
              */
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            virtual Primitive3DSequence create3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
 
         public:
             // constructor
-            BufDecPrimitive3D();
+            BufferedDecompositionPrimitive3D();
 
-            /** The getDecomposition default implementation will on demand use createLocal3DDecomposition() if
-                maLocal3DDecomposition is empty. It will set maLocal3DDecomposition to this obtained decomposition
+            /** The getDecomposition default implementation will on demand use create3DDecomposition() if
+                maBuffered3DDecomposition is empty. It will set maBuffered3DDecomposition to this obtained decomposition
                 to buffer it. If the decomposition is also ViewInformation-dependent, this method needs to be
                 overloaded and the ViewInformation for the last decomposition needs to be remembered, too, and
                 be used in the next call to decide if the buffered decomposition may be reused or not.
@@ -192,7 +197,7 @@ namespace drawinglayer
         // get range3D from a given Primitive3DSequence
         basegfx::B3DRange getB3DRangeFromPrimitive3DSequence(const Primitive3DSequence& rCandidate, const geometry::ViewInformation3D& aViewInformation);
 
-        // compare two Primitive2DReferences for equality, including trying to get implementations (BufferedDecompositionPrimitive2D)
+        // compare two Primitive2DReferences for equality, including trying to get implementations (BasePrimitive2D)
         // and using compare operator
         bool arePrimitive3DReferencesEqual(const Primitive3DReference& rA, const Primitive3DReference& rB);
 
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/groupprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/groupprimitive3d.hxx
index 93ca09af8e93..6912ff25b04d 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/groupprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/groupprimitive3d.hxx
@@ -44,16 +44,29 @@ namespace drawinglayer
 {
     namespace primitive3d
     {
-        class GroupPrimitive3D : public BufDecPrimitive3D
+        /** Baseclass for all grouping 3D primitives
+
+            The description/functionality is identical with the 2D case in groupprimitive2d.hxx,
+            please see there for detailed information.
+
+            Current Basic 3D StatePrimitives are:
+
+            - ModifiedColorPrimitive3D (for a stack of color modifications)
+            - ShadowPrimitive3D (for 3D objects with shadow; this is a special case
+              since the shadow of a 3D primitive is a 2D primitive set)
+            - TexturePrimitive3D (with the following variations)
+                - GradientTexturePrimitive3D (for 3D gradient fill)
+                - BitmapTexturePrimitive3D (for 3D Bitmap fill)
+                - AlphaTexturePrimitive3D (for 3D transparence)
+                - HatchTexturePrimitive3D (for 3D hatch fill)
+            - TransformPrimitive3D (for a transformation stack)
+         */
+        class GroupPrimitive3D : public BasePrimitive3D
         {
         private:
             // the children. Declared private since this shall never be changed at all after construction
             Primitive3DSequence                             maChildren;
 
-        protected:
-            // local decomposition. Implementation will just return children
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
-
         public:
             // constructor
             GroupPrimitive3D(const Primitive3DSequence& rChildren);
@@ -64,6 +77,9 @@ namespace drawinglayer
             // compare operator
             virtual bool operator==( const BasePrimitive3D& rPrimitive ) const;
 
+            // local decomposition. Implementation will just return children
+            virtual Primitive3DSequence get3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+
             // provide unique ID
             DeclPrimitrive3DIDBlock()
         };
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/hatchtextureprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/hatchtextureprimitive3d.hxx
index a8ce982f3560..2e1d7e0b5fe4 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/hatchtextureprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/hatchtextureprimitive3d.hxx
@@ -44,14 +44,24 @@ namespace drawinglayer
 {
     namespace primitive3d
     {
+        /** HatchTexturePrimitive3D is derived from GroupPrimitive3D, but implements
+            a decomposition which is complicated enough for buffering. Since the group
+            primitive has no default buffering, it is necessary here to add a local
+            buffering mechanism for the decomposition
+         */
         class HatchTexturePrimitive3D : public TexturePrimitive3D
         {
         private:
             attribute::FillHatchAttribute                   maHatch;
+            Primitive3DSequence                             maBuffered3DDecomposition;
 
         protected:
-            // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            /// helper: local decomposition
+            Primitive3DSequence impCreate3DDecomposition() const;
+
+            /// local access methods to maBufferedDecomposition
+            const Primitive3DSequence& getBuffered3DDecomposition() const { return maBuffered3DDecomposition; }
+            void setBuffered3DDecomposition(const Primitive3DSequence& rNew) { maBuffered3DDecomposition = rNew; }
 
         public:
             HatchTexturePrimitive3D(
@@ -67,6 +77,9 @@ namespace drawinglayer
             // compare operator
             virtual bool operator==(const BasePrimitive3D& rPrimitive) const;
 
+            // local decomposition.
+            virtual Primitive3DSequence get3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+
             // provide unique ID
             DeclPrimitrive3DIDBlock()
         };
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/hittestprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/hittestprimitive3d.hxx
index f79fe21dd920..0c5082699e8d 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/hittestprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/hittestprimitive3d.hxx
@@ -56,11 +56,6 @@ namespace drawinglayer
         // use it and it's children subcontent.
         class HitTestPrimitive3D : public GroupPrimitive3D
         {
-        protected:
-            // local decomposition. Implementation will return empty Primitive3DSequence
-            // since this is no visualisation data
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
-
         public:
             HitTestPrimitive3D(const Primitive3DSequence& rChildren);
 
@@ -69,6 +64,10 @@ namespace drawinglayer
             // the local implementation will return the children's range
             virtual basegfx::B3DRange getB3DRange(const geometry::ViewInformation3D& rViewInformation) const;
 
+            // local decomposition. Implementation will return empty Primitive3DSequence
+            // since this is no visualisation data
+            virtual Primitive3DSequence get3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+
             // provide unique ID
             DeclPrimitrive3DIDBlock()
         };
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/polygonprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/polygonprimitive3d.hxx
index b54f5e6c6119..9b97f60d3642 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/polygonprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/polygonprimitive3d.hxx
@@ -48,7 +48,7 @@ namespace drawinglayer
 {
     namespace primitive3d
     {
-        class PolygonHairlinePrimitive3D : public BufDecPrimitive3D
+        class PolygonHairlinePrimitive3D : public BasePrimitive3D
         {
         private:
             basegfx::B3DPolygon                     maPolygon;
@@ -81,7 +81,7 @@ namespace drawinglayer
 {
     namespace primitive3d
     {
-        class PolygonStrokePrimitive3D : public BufDecPrimitive3D
+        class PolygonStrokePrimitive3D : public BufferedDecompositionPrimitive3D
         {
         private:
             basegfx::B3DPolygon                     maPolygon;
@@ -90,7 +90,7 @@ namespace drawinglayer
 
         protected:
             // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            virtual Primitive3DSequence create3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
 
         public:
             PolygonStrokePrimitive3D(
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/polygontubeprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/polygontubeprimitive3d.hxx
index 1fa43c0e27fc..5ce81e8c7ad6 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/polygontubeprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/polygontubeprimitive3d.hxx
@@ -62,7 +62,7 @@ namespace drawinglayer
 
         protected:
             // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            virtual Primitive3DSequence create3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
 
         public:
             PolygonTubePrimitive3D(
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/polypolygonprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/polypolygonprimitive3d.hxx
index 2069ab08cdb2..1c5b9e400bbb 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/polypolygonprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/polypolygonprimitive3d.hxx
@@ -46,7 +46,7 @@ namespace drawinglayer
 {
     namespace primitive3d
     {
-        class PolyPolygonMaterialPrimitive3D : public BufDecPrimitive3D
+        class PolyPolygonMaterialPrimitive3D : public BasePrimitive3D
         {
         private:
             basegfx::B3DPolyPolygon                     maPolyPolygon;
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/sdrcubeprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/sdrcubeprimitive3d.hxx
index 13ccc8d80411..42a9ab94f327 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/sdrcubeprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/sdrcubeprimitive3d.hxx
@@ -48,7 +48,7 @@ namespace drawinglayer
         {
         protected:
             // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            virtual Primitive3DSequence create3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
 
         public:
             SdrCubePrimitive3D(
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/sdrextrudeprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/sdrextrudeprimitive3d.hxx
index e3b96a1b0d3e..a5975b050797 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/sdrextrudeprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/sdrextrudeprimitive3d.hxx
@@ -77,7 +77,7 @@ namespace drawinglayer
 
         protected:
             // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            virtual Primitive3DSequence create3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
 
         public:
             SdrExtrudePrimitive3D(
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/sdrlatheprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/sdrlatheprimitive3d.hxx
index 0925d798a52a..7d80cbde015c 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/sdrlatheprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/sdrlatheprimitive3d.hxx
@@ -91,7 +91,7 @@ namespace drawinglayer
                 const basegfx::B2DPoint& rEnd) const;
 
             // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            virtual Primitive3DSequence create3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
 
         public:
             SdrLathePrimitive3D(
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/sdrpolypolygonprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/sdrpolypolygonprimitive3d.hxx
index bd020022f12f..b0d7cc5c26a2 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/sdrpolypolygonprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/sdrpolypolygonprimitive3d.hxx
@@ -52,7 +52,7 @@ namespace drawinglayer
 
         protected:
             // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            virtual Primitive3DSequence create3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
 
         public:
             SdrPolyPolygonPrimitive3D(
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/sdrprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/sdrprimitive3d.hxx
index 729de313267a..d2296968a000 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/sdrprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/sdrprimitive3d.hxx
@@ -47,9 +47,13 @@
 
 namespace drawinglayer
 {
+    /** base class for the more complicated geometric primitives, so
+        derive from buffered primitive to allow overloading of
+        create3DDecomposition there
+     */
     namespace primitive3d
     {
-        class SdrPrimitive3D : public BufDecPrimitive3D
+        class SdrPrimitive3D : public BufferedDecompositionPrimitive3D
         {
         private:
             basegfx::B3DHomMatrix                       maTransform;
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/sdrsphereprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/sdrsphereprimitive3d.hxx
index 38a0f94ee07b..3e6349df0bb9 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/sdrsphereprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/sdrsphereprimitive3d.hxx
@@ -52,7 +52,7 @@ namespace drawinglayer
 
         protected:
             // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+            virtual Primitive3DSequence create3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
 
         public:
             SdrSpherePrimitive3D(
diff --git a/drawinglayer/inc/drawinglayer/primitive3d/textureprimitive3d.hxx b/drawinglayer/inc/drawinglayer/primitive3d/textureprimitive3d.hxx
index c351fcd0aff0..a0c18f34788e 100644
--- a/drawinglayer/inc/drawinglayer/primitive3d/textureprimitive3d.hxx
+++ b/drawinglayer/inc/drawinglayer/primitive3d/textureprimitive3d.hxx
@@ -88,10 +88,6 @@ namespace drawinglayer
         private:
             double                                      mfTransparence;
 
-        protected:
-            // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
-
         public:
             UnifiedAlphaTexturePrimitive3D(
                 double fTransparence,
@@ -103,6 +99,9 @@ namespace drawinglayer
             // compare operator
             virtual bool operator==(const BasePrimitive3D& rPrimitive) const;
 
+            // local decomposition.
+            virtual Primitive3DSequence get3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
+
             // provide unique ID
             DeclPrimitrive3DIDBlock()
         };
@@ -120,10 +119,6 @@ namespace drawinglayer
         private:
             attribute::FillGradientAttribute        maGradient;
 
-        protected:
-            // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
-
         public:
             GradientTexturePrimitive3D(
                 const attribute::FillGradientAttribute& rGradient,
@@ -155,10 +150,6 @@ namespace drawinglayer
         private:
             attribute::FillBitmapAttribute      maBitmap;
 
-        protected:
-            // local decomposition.
-            virtual Primitive3DSequence createLocal3DDecomposition(const geometry::ViewInformation3D& rViewInformation) const;
-
         public:
             BitmapTexturePrimitive3D(
                 const attribute::FillBitmapAttribute& rBitmap,