SIBCTransfod.h

00001 //***************************************************************************************
00002 //
00003 // File supervisor: Softimage 3D Games & 3D Bridge team
00004 //
00005 // (c) Copyright 2001-2002 Avid Technology, Inc. . All rights reserved.
00006 //
00007 //***************************************************************************************
00008 
00009 /****************************************************************************************
00010 THIS CODE IS PUBLISHED AS A SAMPLE ONLY AND IS PROVIDED "AS IS".
00011 IN NO EVENT SHALL SOFTIMAGE, AVID TECHNOLOGY, INC. AND/OR THEIR RESPECTIVE
00012 SUPPLIERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
00013 DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
00014 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
00015 CONNECTION WITH THE USE OR PERFORMANCE OF THIS CODE .
00016 
00017 COPYRIGHT NOTICE. Copyright © 1999-2002 Avid Technology Inc. . All rights reserved. 
00018 
00019 SOFTIMAGE is a registered trademark of Avid Technology Inc. or its subsidiaries 
00020 or divisions. Windows NT is a registered trademark of Microsoft Corp. All other
00021 trademarks contained herein are the property of their respective owners. 
00022 ****************************************************************************************/
00023 
00024 #if (_MSC_VER > 1000) || defined(SGI_COMPILER)
00025 #pragma once
00026 #endif
00027 
00028 //******************************************************************************
00029 // Defines
00030 //******************************************************************************
00031 #ifndef _TRANSFO_H_
00032 #define _TRANSFO_H_
00033 
00034 //******************************************************************************
00035 // Includes
00036 //******************************************************************************
00037 #include "SIBCMathLib.h"
00038 
00039 //******************************************************************************
00040 // Typedefs
00041 //******************************************************************************
00042 
00043 
00048 
00050 const unsigned char oSiTransfoSclFac                =   0x01;
00051 
00053 const unsigned char oSiTransfoSclRot                =   0x02;
00054 
00056 const unsigned char oSiTransfoAllScl                =   0x03;
00057 
00059 const unsigned char oSiTransfoRot                   =   0x04;
00060 
00062 const unsigned char oSiTransfoTrs                   =   0x08;
00063 
00065 const unsigned char oSiTransfoTrsAffectedByScl      =   0x10;   // Used only when combining transformations
00066 
00068 const unsigned char oSiTransfoTrsAffectedByOri      =   0x20;   // Used only when combining transformations
00069 
00071 const unsigned char oSiTransfoAllTrs                =   0x38;
00072 
00074 const unsigned char oSiTransfoNone                  =   0x00;
00075 
00077 const unsigned char oSiTransfoAll                   =   0x3F;
00080 
00081 typedef enum tagE3DSCLTYPE
00082 {
00083    XYZ_SCL_TYPE,        
00084    UNIFORM_SCL_TYPE,    
00085    VOLUMIC_SCL_TYPE     
00086 } E3DSclType;
00087 
00089 typedef enum tagE3DTRANSFOSPACE
00090 {
00091    LOCAL_TRANSFO_SPACE,     
00092    PARENT_TRANSFO_SPACE,    
00093    OTHER_TRANSFO_SPACE      
00094 } E3DTransfoSpace;
00095 
00097 typedef enum tagE3DVECTORTYPE
00098 {
00099    POINT_VECTOR_TYPE,      
00100    LINE_VECTOR_TYPE,       
00101    DIRECTION_VECTOR_TYPE   
00102 } E3DVectorType;
00103 
00104 
00105 //******************************************************************************
00106 //  Mask Values for m_oTransfoInfo. These are used internally by CSIBCTransfod,
00107 //  and thus do not require documentation.
00108 //******************************************************************************
00109 #define MASK_ARE_COMPONENTS_DIRTY       (1 << 0 )   // 0x1  00000001
00110 #define MASK_IS_XFOMAT_DIRTY            (1 << 1 )   // 0x2  00000010
00111 #define MASK_IS_SI_SCALING              (1 << 2 )   // 0x4  00000100
00112 
00115 class XSICOREEXPORT CSIBCTransfod
00116 {
00117     public:
00120         CSIBCTransfod();
00121 
00128         CSIBCTransfod( 
00129                     const CSIBCVector3Dd&   in_vctScl,
00130                     const CSIBCRotationd&   in_rotScl,
00131                     const CSIBCRotationd&   in_rot,
00132                     const CSIBCVector3Dd&   in_vctTrs );
00133 
00139         CSIBCTransfod(  
00140                     const CSIBCVector3Dd&   in_vctScl,
00141                     const CSIBCRotationd&   in_rot,
00142                     const CSIBCVector3Dd&   in_vctTrs );
00143 
00148          CSIBCTransfod( 
00149                     const CSIBCVector3Dd&   in_vctScl,
00150                     const CSIBCRotationd&   in_rotScl );
00151 
00156         bool GetSIScalingFlag() const;
00157 
00162         CSIBCTransfod& SetSIScalingFlag( const bool in_bSIScaling );
00163 
00167          bool IsScalingOrientationExisting() const;
00168 
00170         // TODO  The following Get/Set functions assume that the referential //
00171         //       of this transformation object and of the given/received     //
00172         //       value are the same. We should provide some methods to       //
00173         //       Get/Set one or many transformation components in different  //
00174         //       referential spaces.                                         //
00176 
00181          CSIBCVector3Dd&    GetScaling( CSIBCVector3Dd& out_vctScl );
00182 
00188          void           GetScaling( 
00189                                                 double& out_dX, 
00190                                                 double& out_dY, 
00191                                                 double& out_dZ );
00192 
00197         void            GetScaling( 
00198                                                 CSIBCVector3Dd& out_vctScl,
00199                                                 CSIBCRotationd& out_rotSclOri );
00200 
00205          CSIBCRotationd&    GetScalingOrientation( CSIBCRotationd& in_rotSclOri );
00206 
00211          CSIBCVector3Dd&    GetScalingOrientation( CSIBCVector3Dd&  out_vctSclOri );
00212 
00218          void           GetScalingOrientation( 
00219                                                             double& out_rdX,
00220                                                             double& out_rdY,
00221                                                             double& out_rdZ );
00222 
00227          CSIBCRotationd&        GetRotation( CSIBCRotationd& out_rot );
00228 
00233         CSIBCQuaterniond&       GetRotation( CSIBCQuaterniond& out_quat );
00234 
00239         CSIBCRotMatd&           GetRotation( CSIBCRotMatd& out_matRot );
00240 
00251         const CSIBCRotMatd* GetRotation();
00252 
00257         CSIBCVector3Dd&     GetRotation( CSIBCVector3Dd& out_vctXYZAngles );
00258 
00264         void                    GetRotation( 
00265                                                     double& out_dX, 
00266                                                     double& out_dY, 
00267                                                     double& out_dZ );
00268 
00273         void                    GetRotation(
00274                                                     CSIBCVector3Dd& out_vctAxis, 
00275                                                     double& out_dAngle );
00276 
00281          CSIBCVector3Dd&    GetTranslation( CSIBCVector3Dd& out_vctTrs );
00282 
00288          void           GetTranslation(
00289                                                     double& out_dX, 
00290                                                     double& out_dY, 
00291                                                     double& out_dZ );
00292 
00301          const CSIBCXfoMatd*    GetMatrix();
00302 
00303 
00308          CSIBCXfoMatd&      GetMatrix( CSIBCXfoMatd& out_matXfo );
00309 
00314          CSIBCXfoMatd&      GetInvMatrix( CSIBCXfoMatd& out_matInvXfo );
00315 
00323         CSIBCTransfod&  Set( 
00324                                         const   CSIBCVector3Dd&     in_vctScl,
00325                                         const   CSIBCRotationd& in_rotScl,
00326                                         const   CSIBCRotationd& in_rot,
00327                                         const   CSIBCVector3Dd&     in_vctTrs );
00328     
00335         CSIBCTransfod&  Set( 
00336                                         const   CSIBCVector3Dd&     in_vctScl,
00337                                         const   CSIBCRotationd& in_rot,
00338                                         const   CSIBCVector3Dd&     in_vctTrs );
00339 
00344         CSIBCTransfod&  Set( const CSIBCTransfod& in_xfo );
00345 
00350         CSIBCTransfod&  Set( const CSIBCXfoMatd& in_matXfo );
00351 
00356         CSIBCTransfod&  Set( const CSIBCRotationd& in_rot );
00357 
00362         CSIBCTransfod&  Set( const CSIBCVector3Dd& in_vct );
00363 
00368         CSIBCTransfod&  SetScaling( const CSIBCVector3Dd& in_vctScl );
00369         
00376         CSIBCTransfod&  SetScaling( 
00377                                                 double in_dX, 
00378                                                 double in_dY, 
00379                                                 double in_dZ );
00380 
00386         CSIBCTransfod&  SetScaling( 
00387                                                 const   CSIBCVector3Dd&     in_vctScl,
00388                                                 const   CSIBCRotationd& in_rotSclOri );
00389 
00394         CSIBCTransfod&  SetScalingOrientation( const CSIBCRotationd& in_rotSclOri );
00395 
00400         CSIBCTransfod&  SetScalingOrientation( const CSIBCVector3Dd&  in_vctSclOri );
00401         
00408         CSIBCTransfod&  SetScalingOrientation( 
00409                                                             const   double  in_dX,
00410                                                             const   double  in_dY,
00411                                                             const   double  in_dZ );
00412 
00413 
00418         CSIBCTransfod&  SetRotation( const CSIBCRotationd& in_rot );
00419 
00424         CSIBCTransfod&  SetRotation( const CSIBCQuaterniond& in_quat );
00425 
00430         CSIBCTransfod&  SetRotation( const CSIBCRotMatd& in_matRot );
00431 
00436         CSIBCTransfod&  SetRotation( const CSIBCVector3Dd& in_vctXYZAngles );
00437 
00444         CSIBCTransfod&  SetRotation( 
00445                                                 double  in_dX, 
00446                                                 double  in_dY, 
00447                                                 double  in_dZ );
00448 
00454         CSIBCTransfod&  SetRotation( 
00455                                                 const   E3DAxisType in_axis, 
00456                                                 const   double      in_dAngle );
00457 
00463         CSIBCTransfod&  SetRotation( 
00464                                                 const   CSIBCVector3Dd& in_vctAxis, 
00465                                                 const   double      in_dAngle );
00466 
00474         bool            SetRotation( 
00475                                                 const   CSIBCVector3Dd& in_vctFrom, 
00476                                                 const   CSIBCVector3Dd& in_vctTo, 
00477                                                 int&    out_bFlip );
00478         
00486          CSIBCTransfod& SetRotation( 
00487                                                 const   CSIBCVector3Dd& in_vctX, 
00488                                                 const   CSIBCVector3Dd& in_vctY, 
00489                                                 const   CSIBCVector3Dd& in_vctZ );
00490 
00495          CSIBCTransfod& SetTranslation( const CSIBCVector3Dd& in_vctTrs );
00496 
00503          CSIBCTransfod& SetTranslation( 
00504                                                     double in_dX, 
00505                                                     double in_dY, 
00506                                                     double in_dZ );
00507 
00513          CSIBCTransfod& SetIdentity( const unsigned char in_oWhichTransfo = oSiTransfoAll );
00514 
00519         CSIBCTransfod&  Invert( CSIBCTransfod& in_xfo );
00520         
00524         CSIBCTransfod&  Invert();
00525 
00558         CSIBCTransfod& Mul( 
00559                         CSIBCTransfod&  in_xfo1, 
00560                         CSIBCTransfod& in_xfo2, 
00561                         unsigned char       in_oWhichComponents = oSiTransfoAll );
00562         
00571         CSIBCTransfod& Mul( 
00572                                         CSIBCTransfod& in_xfo, 
00573                                         unsigned char       in_oWhichComponents = oSiTransfoAll );
00574         
00601         CSIBCTransfod& Dif( 
00602                             CSIBCTransfod&  in_xfo1, 
00603                             CSIBCTransfod& in_xfo2, 
00604                             unsigned char       in_oWhichComponents = oSiTransfoAll, 
00605                             CSIBCTransfod* in_pXfo3 = NULL );
00606 
00612         CSIBCTransfod& MapSpaceToWorld( CSIBCTransfod& in_xfoFrom );
00613 
00619         CSIBCTransfod& MapWorldToSpace( CSIBCTransfod& in_xfoTo );
00620 
00628         CSIBCTransfod& MapSpaceToSpace(
00629                                                     CSIBCTransfod& in_xfoFrom,
00630                                                     CSIBCTransfod& in_xfoTo );
00631 
00660         CSIBCTransfod& AddScaling( 
00661                                             const   CSIBCVector3Dd&     in_vctSclApplied,
00662                                             const   E3DTransfoSpace in_eAlong = LOCAL_TRANSFO_SPACE,
00663                                                     CSIBCRotationd* in_protAlong = NULL,
00664                                             const   E3DTransfoSpace in_eAbout = LOCAL_TRANSFO_SPACE,
00665                                             const   CSIBCVector3Dd*     in_pvctAbout = NULL,
00666                                             const   E3DSclType      in_eSclType = XYZ_SCL_TYPE );
00667         
00697         CSIBCTransfod& AddRotation( 
00698                                                     CSIBCRotationd& in_rotApplied,
00699                                             const   E3DTransfoSpace in_eAlong = LOCAL_TRANSFO_SPACE,
00700                                                     CSIBCRotationd* in_protAlong = NULL,
00701                                             const   E3DTransfoSpace in_eAround = LOCAL_TRANSFO_SPACE,
00702                                             const   CSIBCVector3Dd*     in_pvctAround = NULL,
00703                                                     bool            in_bIncrementEulerAngles = false);
00704 
00728         CSIBCTransfod& AddTranslation( 
00729                                             const   CSIBCVector3Dd&     in_vctTrsApplied,
00730                                             const   E3DTransfoSpace in_eAlong = LOCAL_TRANSFO_SPACE,
00731                                                     CSIBCRotationd* in_protAlong = NULL );
00762         CSIBCTransfod& AddScalingOrientation( 
00763                                                     CSIBCRotationd& in_rotApplied,
00764                                             const   E3DTransfoSpace in_eAlong = LOCAL_TRANSFO_SPACE,
00765                                                     CSIBCRotationd* in_protAlong = NULL,
00766                                             const   E3DTransfoSpace in_eAround = LOCAL_TRANSFO_SPACE,
00767                                             const   CSIBCVector3Dd*     in_pvctAround = NULL,
00768                                                     bool            in_bIncrementEulerAngles = false);
00769 
00777         friend CSIBCXfoMatd&    GetMapSpaceToWorld(
00778                                                         const   E3DVectorType   in_eVctType,
00779                                                                 CSIBCTransfod&      in_xfoFrom,
00780                                                                 CSIBCXfoMatd&       out_matXfo );
00787         friend CSIBCXfoMatd&    GetMapWorldToSpace(
00788                                                         const   E3DVectorType   in_eVctType,
00789                                                                 CSIBCTransfod&      in_xfoTo,
00790                                                                 CSIBCXfoMatd&       out_matXfo );
00798         friend CSIBCXfoMatd&    GetMapSpaceToSpace( 
00799                                                         const   E3DVectorType   in_eVctType,
00800                                                                 CSIBCTransfod&      in_xfoFrom,
00801                                                                 CSIBCTransfod&      in_xfoTo,
00802                                                                 CSIBCXfoMatd&       out_matXfo );
00803 
00804     // @access Protected members
00805     protected:
00806 
00807         //****************************************
00808         // IMPLEMENTATION
00809         //****************************************
00810         // @member Factorize          | Factorize the transformation matrix
00811         //                              into individual scaling, scaling 
00812         //                              orientation, orientation and
00813         //                              translation components.
00814         // @member Combine            | Combine the individual scaling, scaling
00815         //                              orientation, orientation and translation
00816         //                              components into a transformation matrix.
00817          void Factorize( const unsigned char in_oWhichComponents = oSiTransfoAll );
00818          void Combine();
00819 
00820         // @member Init               | Initialize members of the object.
00821          void Init();
00822 
00823     // @access Private members
00824     private:
00825 
00826         //****************************************
00827         // ATTRIBUTES
00828         //****************************************
00829         CSIBCRotationd      m_rot;      // @mdata   CSIBCRotationd      | CSIBCTransfod | m_rot  | Orientation.
00830         CSIBCXfoMatd        m_matXfo;   // @mdata   CSIBCXfoMatd | CSIBCTransfod | m_matXfo | Transformation
00831                                     //          matrix to represent scaling, rotation, translation and shearing all
00832                                     //          at once.
00833         CSIBCVector3Dd      m_vctScl;   // @mdata   CSIBCVector3Dd      | CSIBCTransfod | m_vctScl  | XYZ scaling factors.
00834         CSIBCVector3Dd      m_vctTrs;   // @mdata   CSIBCVector3Dd      | CSIBCTransfod | m_vctTrs   | Translation.
00835         CSIBCRotationd* m_pSclOri;  // @mdata   CSIBCRotationd* | CSIBCTransfod | m_pSclOri | Scaling Orientation.
00836                                     //          This field allows to introduce explicit shearing in the transformation.
00837                                     //          The memory holding this pointer is allocated when shearing is detected in the transformation matrix,
00838                                     //          or when shearing is set explicitely by the clients. This same memory is freed whenever there is
00839                                     //          no more shearing.
00840 
00841         // @devnote     Classical vs SI Scaling:
00842         //              With SOFTIMAGE scaling, scaling factors
00843         //              are always applied along local axes.
00844         //              In classical scaling, shearing can occur.
00845         //              This is equivalent to saying that the scaling factors
00846         //              are not applied along local axis, but along other axes.
00847         //              To deal with this, we introduce a Scaling Orientation matrix
00848         //              which represents a rotation applied before scaling the object.
00849 
00850 
00851 
00852 
00853 
00854         // @mdata   bool | CSIBCTransfod | m_bComponentsDirty | Do the individual
00855         //          transformation's components (Scaling, Scaling orientation,
00856         //          Orientation, Translation) corresponding to the transformation
00857         //          matrix are dirty?
00858         // @mdata   bool | CSIBCTransfod | m_bXfoMatDirty | Do the transformation
00859         //          matrix corresponding to the individual transformation's
00860         //          components (Scaling, Scaling orientation, Orientation,
00861         //          Translation) is dirty?
00862 #ifdef _DEBUG
00863 
00864         bool m_bComponentsDirty;
00865         bool m_bXfoMatDirty;
00866 
00867         // @mdata   bool | CSIBCTransfod | m_bSIScaling | Do transformation's
00868         //          components are combined using SOFTIMAGE scaling (true) or
00869         //          classical scaling (false) ?
00870         bool m_bSIScaling;
00871 #endif
00872 
00873 
00874 
00875         // m_oTransfoInfo comprises formely known m_bComponentsDirty, m_bXfoMatDirty
00876         // and m_bSIScaling booleans.
00877         // Bit 0 = m_bComponentsDirty
00878         // Bit 1 = m_bXfoMatDirty
00879         // Bit 2 = m_bSIScaling
00880         // Bit 3 to 7 = unused
00881         unsigned char m_oTransfoInfo;
00882 
00883          void _SetComponentsDirty( const bool in_bIsDirty );
00884          bool _AreComponentsDirty() const;
00885          void _SetXfoMatDirty ( const bool in_bIsDirty );
00886          bool _IsXfoMatDirty() const;
00887          void _SetSIScaling( const bool in_bIsScaling );
00888          bool _IsSIScaling() const;
00889          bool HasShearing() const;
00890          void _AllocateScalingOrientationMatrix(const bool in_bAllocate);
00891 
00892 
00893         // Disable Copy constructor and operator=
00894         // @member CSIBCTransfod         | Copy constructor.
00895         CSIBCTransfod( const CSIBCTransfod& in_xfo );
00896         CSIBCTransfod( const CSIBCXfoMatd& in_matXfo );
00897         CSIBCTransfod( const CSIBCRotationd& in_rot );
00898         CSIBCTransfod( const CSIBCVector3Dd& in_vctTrs );
00899         // @member =                  | Transformation assignment from another
00900         //                              transformation.
00901         CSIBCTransfod& operator =( const CSIBCTransfod& in_xfo );
00902         CSIBCTransfod& operator =( const CSIBCXfoMatd& in_matXfo );
00903 };
00904 
00905 typedef CSIBCTransfod* LP3DTRANSFO;
00906 typedef const CSIBCTransfod* LPC3DTRANSFO;
00907 
00908 
00909 #endif