SIBCTransfod.h

00001 //***************************************************************************************
00002 //
00003 // File supervisor: Crosswalk team
00004 //
00005 // Copyright 2008 Autodesk, Inc.  All rights reserved.  
00006 // Use of this software is subject to the terms of the Autodesk license agreement 
00007 // provided at the time of installation or download, or which otherwise accompanies 
00008 // this software in either electronic or hard copy form.
00009 //
00010 //***************************************************************************************
00011 
00012 #if (_MSC_VER > 1000) || defined(SGI_COMPILER)
00013 #pragma once
00014 #endif
00015 
00016 //******************************************************************************
00017 // Defines
00018 //******************************************************************************
00019 #ifndef _TRANSFO_H_
00020 #define _TRANSFO_H_
00021 
00022 //******************************************************************************
00023 // Includes
00024 //******************************************************************************
00025 #include "SIBCMathLib.h"
00026 
00027 //******************************************************************************
00028 // Typedefs
00029 //******************************************************************************
00030 
00031 
00036 
00038 const unsigned char oSiTransfoSclFac                =   0x01;
00039 
00041 const unsigned char oSiTransfoSclRot                =   0x02;
00042 
00044 const unsigned char oSiTransfoAllScl                =   0x03;
00045 
00047 const unsigned char oSiTransfoRot                   =   0x04;
00048 
00050 const unsigned char oSiTransfoTrs                   =   0x08;
00051 
00053 const unsigned char oSiTransfoTrsAffectedByScl      =   0x10;   // Used only when combining transformations
00054 
00056 const unsigned char oSiTransfoTrsAffectedByOri      =   0x20;   // Used only when combining transformations
00057 
00059 const unsigned char oSiTransfoAllTrs                =   0x38;
00060 
00062 const unsigned char oSiTransfoNone                  =   0x00;
00063 
00065 const unsigned char oSiTransfoAll                   =   0x3F;
00068 
00069 typedef enum tagE3DSCLTYPE
00070 {
00071    XYZ_SCL_TYPE,        
00072    UNIFORM_SCL_TYPE,    
00073    VOLUMIC_SCL_TYPE     
00074 } E3DSclType;
00075 
00077 typedef enum tagE3DTRANSFOSPACE
00078 {
00079    LOCAL_TRANSFO_SPACE,     
00080    PARENT_TRANSFO_SPACE,    
00081    OTHER_TRANSFO_SPACE      
00082 } E3DTransfoSpace;
00083 
00085 typedef enum tagE3DVECTORTYPE
00086 {
00087    POINT_VECTOR_TYPE,      
00088    LINE_VECTOR_TYPE,       
00089    DIRECTION_VECTOR_TYPE   
00090 } E3DVectorType;
00091 
00092 
00093 //******************************************************************************
00094 //  Mask Values for m_oTransfoInfo. These are used internally by CSIBCTransfod,
00095 //  and thus do not require documentation.
00096 //******************************************************************************
00097 #define MASK_ARE_COMPONENTS_DIRTY       (1 << 0 )   // 0x1  00000001
00098 #define MASK_IS_XFOMAT_DIRTY            (1 << 1 )   // 0x2  00000010
00099 #define MASK_IS_SI_SCALING              (1 << 2 )   // 0x4  00000100
00100 
00103 class XSICOREEXPORT CSIBCTransfod
00104 {
00105     public:
00108         CSIBCTransfod();
00109 
00116         CSIBCTransfod( 
00117                     const CSIBCVector3Dd&   in_vctScl,
00118                     const CSIBCRotationd&   in_rotScl,
00119                     const CSIBCRotationd&   in_rot,
00120                     const CSIBCVector3Dd&   in_vctTrs );
00121 
00127         CSIBCTransfod(  
00128                     const CSIBCVector3Dd&   in_vctScl,
00129                     const CSIBCRotationd&   in_rot,
00130                     const CSIBCVector3Dd&   in_vctTrs );
00131 
00136          CSIBCTransfod( 
00137                     const CSIBCVector3Dd&   in_vctScl,
00138                     const CSIBCRotationd&   in_rotScl );
00139 
00144         bool GetSIScalingFlag() const;
00145 
00150         CSIBCTransfod& SetSIScalingFlag( const bool in_bSIScaling );
00151 
00155          bool IsScalingOrientationExisting() const;
00156 
00158         // TODO  The following Get/Set functions assume that the referential //
00159         //       of this transformation object and of the given/received     //
00160         //       value are the same. We should provide some methods to       //
00161         //       Get/Set one or many transformation components in different  //
00162         //       referential spaces.                                         //
00164 
00169          CSIBCVector3Dd&    GetScaling( CSIBCVector3Dd& out_vctScl );
00170 
00176          void           GetScaling( 
00177                                                 double& out_dX, 
00178                                                 double& out_dY, 
00179                                                 double& out_dZ );
00180 
00185         void            GetScaling( 
00186                                                 CSIBCVector3Dd& out_vctScl,
00187                                                 CSIBCRotationd& out_rotSclOri );
00188 
00193          CSIBCRotationd&    GetScalingOrientation( CSIBCRotationd& in_rotSclOri );
00194 
00199          CSIBCVector3Dd&    GetScalingOrientation( CSIBCVector3Dd&  out_vctSclOri );
00200 
00206          void           GetScalingOrientation( 
00207                                                             double& out_rdX,
00208                                                             double& out_rdY,
00209                                                             double& out_rdZ );
00210 
00215          CSIBCRotationd&        GetRotation( CSIBCRotationd& out_rot );
00216 
00221         CSIBCQuaterniond&       GetRotation( CSIBCQuaterniond& out_quat );
00222 
00227         CSIBCRotMatd&           GetRotation( CSIBCRotMatd& out_matRot );
00228 
00239         const CSIBCRotMatd* GetRotation();
00240 
00245         CSIBCVector3Dd&     GetRotation( CSIBCVector3Dd& out_vctXYZAngles );
00246 
00252         void                    GetRotation( 
00253                                                     double& out_dX, 
00254                                                     double& out_dY, 
00255                                                     double& out_dZ );
00256 
00261         void                    GetRotation(
00262                                                     CSIBCVector3Dd& out_vctAxis, 
00263                                                     double& out_dAngle );
00264 
00269          CSIBCVector3Dd&    GetTranslation( CSIBCVector3Dd& out_vctTrs );
00270 
00276          void           GetTranslation(
00277                                                     double& out_dX, 
00278                                                     double& out_dY, 
00279                                                     double& out_dZ );
00280 
00289          const CSIBCXfoMatd*    GetMatrix();
00290 
00291 
00296          CSIBCXfoMatd&      GetMatrix( CSIBCXfoMatd& out_matXfo );
00297 
00302          CSIBCXfoMatd&      GetInvMatrix( CSIBCXfoMatd& out_matInvXfo );
00303 
00311         CSIBCTransfod&  Set( 
00312                                         const   CSIBCVector3Dd&     in_vctScl,
00313                                         const   CSIBCRotationd& in_rotScl,
00314                                         const   CSIBCRotationd& in_rot,
00315                                         const   CSIBCVector3Dd&     in_vctTrs );
00316     
00323         CSIBCTransfod&  Set( 
00324                                         const   CSIBCVector3Dd&     in_vctScl,
00325                                         const   CSIBCRotationd& in_rot,
00326                                         const   CSIBCVector3Dd&     in_vctTrs );
00327 
00332         CSIBCTransfod&  Set( const CSIBCTransfod& in_xfo );
00333 
00338         CSIBCTransfod&  Set( const CSIBCXfoMatd& in_matXfo );
00339 
00344         CSIBCTransfod&  Set( const CSIBCRotationd& in_rot );
00345 
00350         CSIBCTransfod&  Set( const CSIBCVector3Dd& in_vct );
00351 
00356         CSIBCTransfod&  SetScaling( const CSIBCVector3Dd& in_vctScl );
00357         
00364         CSIBCTransfod&  SetScaling( 
00365                                                 double in_dX, 
00366                                                 double in_dY, 
00367                                                 double in_dZ );
00368 
00374         CSIBCTransfod&  SetScaling( 
00375                                                 const   CSIBCVector3Dd&     in_vctScl,
00376                                                 const   CSIBCRotationd& in_rotSclOri );
00377 
00382         CSIBCTransfod&  SetScalingOrientation( const CSIBCRotationd& in_rotSclOri );
00383 
00388         CSIBCTransfod&  SetScalingOrientation( const CSIBCVector3Dd&  in_vctSclOri );
00389         
00396         CSIBCTransfod&  SetScalingOrientation( 
00397                                                             const   double  in_dX,
00398                                                             const   double  in_dY,
00399                                                             const   double  in_dZ );
00400 
00401 
00406         CSIBCTransfod&  SetRotation( const CSIBCRotationd& in_rot );
00407 
00412         CSIBCTransfod&  SetRotation( const CSIBCQuaterniond& in_quat );
00413 
00418         CSIBCTransfod&  SetRotation( const CSIBCRotMatd& in_matRot );
00419 
00424         CSIBCTransfod&  SetRotation( const CSIBCVector3Dd& in_vctXYZAngles );
00425 
00432         CSIBCTransfod&  SetRotation( 
00433                                                 double  in_dX, 
00434                                                 double  in_dY, 
00435                                                 double  in_dZ );
00436 
00442         CSIBCTransfod&  SetRotation( 
00443                                                 const   E3DAxisType in_axis, 
00444                                                 const   double      in_dAngle );
00445 
00451         CSIBCTransfod&  SetRotation( 
00452                                                 const   CSIBCVector3Dd& in_vctAxis, 
00453                                                 const   double      in_dAngle );
00454 
00462         bool            SetRotation( 
00463                                                 const   CSIBCVector3Dd& in_vctFrom, 
00464                                                 const   CSIBCVector3Dd& in_vctTo, 
00465                                                 int&    out_bFlip );
00466         
00474          CSIBCTransfod& SetRotation( 
00475                                                 const   CSIBCVector3Dd& in_vctX, 
00476                                                 const   CSIBCVector3Dd& in_vctY, 
00477                                                 const   CSIBCVector3Dd& in_vctZ );
00478 
00483          CSIBCTransfod& SetTranslation( const CSIBCVector3Dd& in_vctTrs );
00484 
00491          CSIBCTransfod& SetTranslation( 
00492                                                     double in_dX, 
00493                                                     double in_dY, 
00494                                                     double in_dZ );
00495 
00501          CSIBCTransfod& SetIdentity( const unsigned char in_oWhichTransfo = oSiTransfoAll );
00502 
00507         CSIBCTransfod&  Invert( CSIBCTransfod& in_xfo );
00508         
00512         CSIBCTransfod&  Invert();
00513 
00546         CSIBCTransfod& Mul( 
00547                         CSIBCTransfod&  in_xfo1, 
00548                         CSIBCTransfod& in_xfo2, 
00549                         unsigned char       in_oWhichComponents = oSiTransfoAll );
00550         
00559         CSIBCTransfod& Mul( 
00560                                         CSIBCTransfod& in_xfo, 
00561                                         unsigned char       in_oWhichComponents = oSiTransfoAll );
00562         
00589         CSIBCTransfod& Dif( 
00590                             CSIBCTransfod&  in_xfo1, 
00591                             CSIBCTransfod& in_xfo2, 
00592                             unsigned char       in_oWhichComponents = oSiTransfoAll, 
00593                             CSIBCTransfod* in_pXfo3 = NULL );
00594 
00600         CSIBCTransfod& MapSpaceToWorld( CSIBCTransfod& in_xfoFrom );
00601 
00607         CSIBCTransfod& MapWorldToSpace( CSIBCTransfod& in_xfoTo );
00608 
00616         CSIBCTransfod& MapSpaceToSpace(
00617                                                     CSIBCTransfod& in_xfoFrom,
00618                                                     CSIBCTransfod& in_xfoTo );
00619 
00648         CSIBCTransfod& AddScaling( 
00649                                             const   CSIBCVector3Dd&     in_vctSclApplied,
00650                                             const   E3DTransfoSpace in_eAlong = LOCAL_TRANSFO_SPACE,
00651                                                     CSIBCRotationd* in_protAlong = NULL,
00652                                             const   E3DTransfoSpace in_eAbout = LOCAL_TRANSFO_SPACE,
00653                                             const   CSIBCVector3Dd*     in_pvctAbout = NULL,
00654                                             const   E3DSclType      in_eSclType = XYZ_SCL_TYPE );
00655         
00685         CSIBCTransfod& AddRotation( 
00686                                                     CSIBCRotationd& in_rotApplied,
00687                                             const   E3DTransfoSpace in_eAlong = LOCAL_TRANSFO_SPACE,
00688                                                     CSIBCRotationd* in_protAlong = NULL,
00689                                             const   E3DTransfoSpace in_eAround = LOCAL_TRANSFO_SPACE,
00690                                             const   CSIBCVector3Dd*     in_pvctAround = NULL,
00691                                                     bool            in_bIncrementEulerAngles = false);
00692 
00716         CSIBCTransfod& AddTranslation( 
00717                                             const   CSIBCVector3Dd&     in_vctTrsApplied,
00718                                             const   E3DTransfoSpace in_eAlong = LOCAL_TRANSFO_SPACE,
00719                                                     CSIBCRotationd* in_protAlong = NULL );
00750         CSIBCTransfod& AddScalingOrientation( 
00751                                                     CSIBCRotationd& in_rotApplied,
00752                                             const   E3DTransfoSpace in_eAlong = LOCAL_TRANSFO_SPACE,
00753                                                     CSIBCRotationd* in_protAlong = NULL,
00754                                             const   E3DTransfoSpace in_eAround = LOCAL_TRANSFO_SPACE,
00755                                             const   CSIBCVector3Dd*     in_pvctAround = NULL,
00756                                                     bool            in_bIncrementEulerAngles = false);
00757 
00765         friend CSIBCXfoMatd&    GetMapSpaceToWorld(
00766                                                         const   E3DVectorType   in_eVctType,
00767                                                                 CSIBCTransfod&      in_xfoFrom,
00768                                                                 CSIBCXfoMatd&       out_matXfo );
00775         friend CSIBCXfoMatd&    GetMapWorldToSpace(
00776                                                         const   E3DVectorType   in_eVctType,
00777                                                                 CSIBCTransfod&      in_xfoTo,
00778                                                                 CSIBCXfoMatd&       out_matXfo );
00786         friend CSIBCXfoMatd&    GetMapSpaceToSpace( 
00787                                                         const   E3DVectorType   in_eVctType,
00788                                                                 CSIBCTransfod&      in_xfoFrom,
00789                                                                 CSIBCTransfod&      in_xfoTo,
00790                                                                 CSIBCXfoMatd&       out_matXfo );
00791 
00792     // @access Protected members
00793     protected:
00794 
00795         //****************************************
00796         // IMPLEMENTATION
00797         //****************************************
00798         // @member Factorize          | Factorize the transformation matrix
00799         //                              into individual scaling, scaling 
00800         //                              orientation, orientation and
00801         //                              translation components.
00802         // @member Combine            | Combine the individual scaling, scaling
00803         //                              orientation, orientation and translation
00804         //                              components into a transformation matrix.
00805          void Factorize( const unsigned char in_oWhichComponents = oSiTransfoAll );
00806          void Combine();
00807 
00808         // @member Init               | Initialize members of the object.
00809          void Init();
00810 
00811     // @access Private members
00812     private:
00813 
00814         //****************************************
00815         // ATTRIBUTES
00816         //****************************************
00817         CSIBCRotationd      m_rot;      // @mdata   CSIBCRotationd      | CSIBCTransfod | m_rot  | Orientation.
00818         CSIBCXfoMatd        m_matXfo;   // @mdata   CSIBCXfoMatd | CSIBCTransfod | m_matXfo | Transformation
00819                                     //          matrix to represent scaling, rotation, translation and shearing all
00820                                     //          at once.
00821         CSIBCVector3Dd      m_vctScl;   // @mdata   CSIBCVector3Dd      | CSIBCTransfod | m_vctScl  | XYZ scaling factors.
00822         CSIBCVector3Dd      m_vctTrs;   // @mdata   CSIBCVector3Dd      | CSIBCTransfod | m_vctTrs   | Translation.
00823         CSIBCRotationd* m_pSclOri;  // @mdata   CSIBCRotationd* | CSIBCTransfod | m_pSclOri | Scaling Orientation.
00824                                     //          This field allows to introduce explicit shearing in the transformation.
00825                                     //          The memory holding this pointer is allocated when shearing is detected in the transformation matrix,
00826                                     //          or when shearing is set explicitely by the clients. This same memory is freed whenever there is
00827                                     //          no more shearing.
00828 
00829         // @devnote     Classical vs SI Scaling:
00830         //              With SOFTIMAGE scaling, scaling factors
00831         //              are always applied along local axes.
00832         //              In classical scaling, shearing can occur.
00833         //              This is equivalent to saying that the scaling factors
00834         //              are not applied along local axis, but along other axes.
00835         //              To deal with this, we introduce a Scaling Orientation matrix
00836         //              which represents a rotation applied before scaling the object.
00837 
00838 
00839 
00840 
00841 
00842         // @mdata   bool | CSIBCTransfod | m_bComponentsDirty | Do the individual
00843         //          transformation's components (Scaling, Scaling orientation,
00844         //          Orientation, Translation) corresponding to the transformation
00845         //          matrix are dirty?
00846         // @mdata   bool | CSIBCTransfod | m_bXfoMatDirty | Do the transformation
00847         //          matrix corresponding to the individual transformation's
00848         //          components (Scaling, Scaling orientation, Orientation,
00849         //          Translation) is dirty?
00850 #ifdef _DEBUG
00851 
00852         bool m_bComponentsDirty;
00853         bool m_bXfoMatDirty;
00854 
00855         // @mdata   bool | CSIBCTransfod | m_bSIScaling | Do transformation's
00856         //          components are combined using SOFTIMAGE scaling (true) or
00857         //          classical scaling (false) ?
00858         bool m_bSIScaling;
00859 #endif
00860 
00861 
00862 
00863         // m_oTransfoInfo comprises formely known m_bComponentsDirty, m_bXfoMatDirty
00864         // and m_bSIScaling booleans.
00865         // Bit 0 = m_bComponentsDirty
00866         // Bit 1 = m_bXfoMatDirty
00867         // Bit 2 = m_bSIScaling
00868         // Bit 3 to 7 = unused
00869         unsigned char m_oTransfoInfo;
00870 
00871          void _SetComponentsDirty( const bool in_bIsDirty );
00872          bool _AreComponentsDirty() const;
00873          void _SetXfoMatDirty ( const bool in_bIsDirty );
00874          bool _IsXfoMatDirty() const;
00875          void _SetSIScaling( const bool in_bIsScaling );
00876          bool _IsSIScaling() const;
00877          bool HasShearing() const;
00878          void _AllocateScalingOrientationMatrix(const bool in_bAllocate);
00879 
00880 
00881         // Disable Copy constructor and operator=
00882         // @member CSIBCTransfod         | Copy constructor.
00883         CSIBCTransfod( const CSIBCTransfod& in_xfo );
00884         CSIBCTransfod( const CSIBCXfoMatd& in_matXfo );
00885         CSIBCTransfod( const CSIBCRotationd& in_rot );
00886         CSIBCTransfod( const CSIBCVector3Dd& in_vctTrs );
00887         // @member =                  | Transformation assignment from another
00888         //                              transformation.
00889         CSIBCTransfod& operator =( const CSIBCTransfod& in_xfo );
00890         CSIBCTransfod& operator =( const CSIBCXfoMatd& in_matXfo );
00891 };
00892 
00893 typedef CSIBCTransfod* LP3DTRANSFO;
00894 typedef const CSIBCTransfod* LPC3DTRANSFO;
00895 
00896 
00897 #endif