diff --git a/src/Graphic3d/Graphic3d_TransformPers.hxx b/src/Graphic3d/Graphic3d_TransformPers.hxx index fa7f7a53b5..7ad65a0a50 100644 --- a/src/Graphic3d/Graphic3d_TransformPers.hxx +++ b/src/Graphic3d/Graphic3d_TransformPers.hxx @@ -27,9 +27,21 @@ DEFINE_STANDARD_HANDLE(Graphic3d_TransformPers, Standard_Transient) -//! Class for keeping and computing transformation persistence. -//! 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 definition. +//! +//! 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, diff --git a/src/PrsMgr/PrsMgr_PresentableObject.hxx b/src/PrsMgr/PrsMgr_PresentableObject.hxx index a45fbb2c91..00b378b1d9 100644 --- a/src/PrsMgr/PrsMgr_PresentableObject.hxx +++ b/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(); }