0029372: Graphic3d_TransformPers - improve description of Local Coordinate system defined by Transformation Persistence

src/Graphic3d/Graphic3d_TransformPers.hxx

@@ -27,9 +27,21 @@
 
 DEFINE_STANDARD_HANDLE(Graphic3d_TransformPers, Standard_Transient)
 
-//! Class for keeping and computing transformation persistence.
+//! Transformation Persistence definition.
-//! Note that instance of this class can not define
+//!
-//! no transformation persistence Graphic3d_TMF_None - NULL handle should be used for this purpose.
+//! Transformation Persistence defines a mutable Local Coordinate system which depends on camera position,
+//! so that visual appearance of the object becomes partially immutable while camera moves.
+//! Object visually preserves particular property such as size, placement, rotation or their combination.
+//!
+//! Graphic3d_TMF_ZoomPers, Graphic3d_TMF_RotatePers and Graphic3d_TMF_ZoomRotatePers define Local Coordinate system
+//! having origin in specified anchor point defined in World Coordinate system,
+//! while Graphic3d_TMF_TriedronPers and Graphic3d_TMF_2d define origin as 2D offset from screen corner in pixels.
+//!
+//! Graphic3d_TMF_2d, Graphic3d_TMF_TriedronPers and Graphic3d_TMF_ZoomPers defines Local Coordinate system where length units are pixels.
+//! Beware that Graphic3d_RenderingParams::ResolutionRatio() will be ignored!
+//! For other Persistence flags, normal (world) length units will apply.
+//!
+//! WARNING: Graphic3d_TMF_None is not permitted for defining instance of this class - NULL handle should be used for this purpose!
 class Graphic3d_TransformPers : public Standard_Transient
 {
   DEFINE_STANDARD_RTTIEXT(Graphic3d_TransformPers, Standard_Transient)
@@ -73,6 +85,7 @@ public:
   }
 
   //! Set Zoom/Rotate transformation persistence with an anchor 3D point.
+  //! Anchor point defines the origin of Local Coordinate system within World Coordinate system.
   //! Throws an exception if persistence mode is not Graphic3d_TMF_ZoomPers, Graphic3d_TMF_ZoomRotatePers or Graphic3d_TMF_RotatePers.
   Graphic3d_TransformPers (const Graphic3d_TransModeFlags theMode,
                            const gp_Pnt& thePnt)
@@ -82,6 +95,7 @@ public:
   }
 
   //! Set 2d/trihedron transformation persistence with a corner and 2D offset.
+  //! 2D offset defines the origin of Local Coordinate system as projection of 2D point on screen plane into World Coordinate system.
   //! Throws an exception if persistence mode is not Graphic3d_TMF_TriedronPers or Graphic3d_TMF_2d.
   //! The offset is a positive displacement from the view corner in pixels.
   Graphic3d_TransformPers (const Graphic3d_TransModeFlags theMode,

src/PrsMgr/PrsMgr_PresentableObject.hxx

@@ -59,10 +59,16 @@ public:
   //! Returns information on whether the object accepts display in HLR mode or not.
   PrsMgr_TypeOfPresentation3d TypeOfPresentation3d() const { return myTypeOfPresentation3d; }
 
-  //! @return transform persistence of the presentable object.
+  //! Returns Transformation Persistence defining a special Local Coordinate system where this presentable object is located or NULL handle if not defined.
+  //! Position of the object having Transformation Persistence is mutable and depends on camera position.
+  //! The same applies to a bounding box of the object.
+  //! @sa Graphic3d_TransformPers class description
   const Handle(Graphic3d_TransformPers)& TransformPersistence() const { return myTransformPersistence; }
 
-  //! Sets up Transform Persistence for this object.
+  //! Sets up Transform Persistence defining a special Local Coordinate system where this object should be located.
+  //! Note that management of Transform Persistence object is more expensive than of the normal one,
+  //! because it requires its position being recomputed basing on camera position within each draw call / traverse.
+  //! @sa Graphic3d_TransformPers class description
   Standard_EXPORT virtual void SetTransformPersistence (const Handle(Graphic3d_TransformPers)& theTrsfPers);
 
   //! Sets up Transform Persistence Mode for this object.
@@ -114,26 +120,38 @@ public:
   Standard_EXPORT void ToBeUpdated (TColStd_ListOfInteger& ListOfMode) const;
   
   //! Return the local transformation.
+  //! Note that the local transformation of the object having Transformation Persistence
+  //! is applied within Local Coordinate system defined by this Persistence.
   const Handle(Geom_Transformation)& LocalTransformationGeom() const { return myLocalTransformation; }
 
   //! Sets local transformation to theTransformation.
+  //! Note that the local transformation of the object having Transformation Persistence
+  //! is applied within Local Coordinate system defined by this Persistence.
   void SetLocalTransformation (const gp_Trsf& theTrsf) { setLocalTransformation (new Geom_Transformation (theTrsf)); }
 
   //! Sets local transformation to theTransformation.
+  //! Note that the local transformation of the object having Transformation Persistence
+  //! is applied within Local Coordinate system defined by this Persistence.
   void SetLocalTransformation (const Handle(Geom_Transformation)& theTrsf) { setLocalTransformation (theTrsf); }
 
   //! Returns true if object has a transformation that is different from the identity.
   Standard_Boolean HasTransformation() const { return !myTransformation.IsNull() && myTransformation->Form() != gp_Identity; }
 
   //! Return the transformation taking into account transformation of parent object(s).
+  //! Note that the local transformation of the object having Transformation Persistence
+  //! is applied within Local Coordinate system defined by this Persistence.
   const Handle(Geom_Transformation)& TransformationGeom() const { return myTransformation; }
 
   //! Return the local transformation.
+  //! Note that the local transformation of the object having Transformation Persistence
+  //! is applied within Local Coordinate system defined by this Persistence.
   const gp_Trsf& LocalTransformation() const { return !myLocalTransformation.IsNull()
                                                      ? myLocalTransformation->Trsf()
                                                      : getIdentityTrsf(); }
 
   //! Return the transformation taking into account transformation of parent object(s).
+  //! Note that the local transformation of the object having Transformation Persistence
+  //! is applied within Local Coordinate system defined by this Persistence.
   const gp_Trsf& Transformation() const { return !myTransformation.IsNull()
                                                 ? myTransformation->Trsf()
                                                 : getIdentityTrsf(); }