OpenWalnut 1.3.1
WPropertyTypes.h
00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WPROPERTYTYPES_H
00026 #define WPROPERTYTYPES_H
00027 
00028 #include <stdint.h>
00029 
00030 #include <list>
00031 #include <string>
00032 #include <vector>
00033 #include <utility>
00034 
00035 #include <boost/filesystem.hpp>
00036 
00037 #include "WStringUtils.h"
00038 #include "math/linearAlgebra/WLinearAlgebra.h"
00039 #include "math/linearAlgebra/WMatrixFixed.h"
00040 #include "math/linearAlgebra/WVectorFixed.h"
00041 #include "WAssert.h"
00042 #include "WColor.h"
00043 #include "WItemSelector.h"
00044 
00045 template < typename T >
00046 class WPropertyVariable;
00047 class WPropertyGroup;
00048 
00049 class WTransferFunction;
00050 
00051 ////////////////////////////////////////////////////////////////////////////////////////////////////////
00052 // NOTE: If you add new types here, please also add corresponding addProperty methods to WPropertyGroup
00053 ////////////////////////////////////////////////////////////////////////////////////////////////////////
00054 
00055 ////////////////////////////////////////////////////////////////////////////////////////////////////////
00056 // NOTE: Always use the WPVBaseTypes in all your declarations to allow easy type modifications later on
00057 ////////////////////////////////////////////////////////////////////////////////////////////////////////
00058 
00059 /**
00060  * Enum of all possible types, that can be used with WProperty.
00061  */
00062 typedef enum
00063 {
00064     PV_UNKNOWN,          //!< type not known
00065     PV_GROUP,            //!< the group property
00066     PV_INT,              //!< integer value
00067     PV_DOUBLE,           //!< floating point value
00068     PV_BOOL,             //!< boolean
00069     PV_STRING,           //!< a string
00070     PV_PATH,             //!< a Boost Path object denoting a filename/path
00071     PV_SELECTION,        //!< a list of strings, selectable
00072     PV_POSITION,         //!< a position property
00073     PV_COLOR,            //!< a color property
00074     PV_TRIGGER,          //!< for triggering an event
00075     PV_MATRIX4X4,        //!< for 4x4 matrices
00076     PV_TRANSFERFUNCTION, //!< for transfer function textures
00077     PV_STRUCT,           //!< for complex, structured properties (used by \ref WPropertyStruct)
00078     PV_LIST              //!< for a dynamic list of properties of the same type (see \ref WPropertyList)
00079 }
00080 PROPERTY_TYPE;
00081 
00082 /**
00083  * Enum of all possible purpose of a property. The purpose describes which meaning a property has for the creator of it. A PP_PARAMETER is a
00084  * property which is meant to be modified to adopt the behaviour of the module (or whomever has created it). A PP_INFORMATION is only an output
00085  * from the creator who wants to inform the outside world about values, states or whatever.
00086  */
00087 typedef enum
00088 {
00089     PV_PURPOSE_INFORMATION,     //!< information property not meant to be modified from someone (except the creating object)
00090     PV_PURPOSE_PARAMETER        //!< a parameter meant to be modified by others to manipulate the behaviour of the module (or whomever created
00091         //!< the property)
00092 }
00093 PROPERTY_PURPOSE;
00094 
00095 /**
00096  * Namespace containing all base types of the WPropertyVariables. Use these types instead of issuing int32_t, double, bool, ...
00097  * directly. It also contains some user defined types including the needed operators.
00098  *
00099  * \note You can use only types which overwrite the << and >> operators!
00100  */
00101 namespace WPVBaseTypes
00102 {
00103     typedef int32_t                                         PV_INT;              //!< base type used for every WPVInt
00104     typedef double                                          PV_DOUBLE;           //!< base type used for every WPVDouble
00105     typedef bool                                            PV_BOOL;             //!< base type used for every WPVBool
00106     typedef std::string                                     PV_STRING;           //!< base type used for every WPVString
00107     typedef boost::filesystem::path                         PV_PATH;             //!< base type used for every WPVFilename
00108     typedef WItemSelector                                   PV_SELECTION;        //!< base type used for every WPVSelection
00109     typedef WPosition                                       PV_POSITION;         //!< base type used for every WPVPosition
00110     typedef WColor                                          PV_COLOR;            //!< base type used for every WPVColor
00111     typedef WMatrix4d                                       PV_MATRIX4X4;        //!< base type used for every WPVMatrix4X4
00112     typedef WTransferFunction                               PV_TRANSFERFUNCTION; //!< base type for every transfer function
00113 
00114     /**
00115      * Enum denoting the possible trigger states. It is used for trigger properties.
00116      */
00117     typedef enum
00118     {
00119         PV_TRIGGER_READY = 0,                                               //!< Trigger property: is ready to be triggered (again)
00120         PV_TRIGGER_TRIGGERED                                                //!< Trigger property: got triggered
00121     }
00122     PV_TRIGGER;     //!< base type used for every WPVTrigger
00123 
00124     /**
00125      * Checks which property types are derived from \ref WPropertyGroupBase. This, for example, is true for PV_GROUP and PV_STRUCT.
00126      *
00127      * \param type the type to check.
00128      *
00129      * \return true if cast-able \ref WPropertyGroupBase.
00130      */
00131     bool isPropertyGroup( PROPERTY_TYPE  type );
00132 
00133     /**
00134      * Write a PV_TRIGGER in string representation to the given output stream.
00135      *
00136      * \param out the output stream to print the value to
00137      * \param c the trigger value to output
00138      *
00139      * \return the output stream extended by the trigger value.
00140      */
00141     std::ostream& operator<<( std::ostream& out, const PV_TRIGGER& c );
00142 
00143     /**
00144      * Write a PV_TRIGGER in string representation to the given input stream.
00145      *
00146      * \param in the input stream to read the value from
00147      * \param c  set the value red to this
00148      *
00149      * \return the input stream.
00150      */
00151     std::istream& operator>>( std::istream& in, PV_TRIGGER& c );
00152 }
00153 
00154 /**
00155  * Some convenience type alias for a even more easy usage of WPropertyVariable.
00156  * These typedefs are useful for casts, as they alias the PropertyVariable types. Please use these types instead of directly
00157  * int32_t, double, bool, ... so we are able to change the type later on without modifications of thousands of modules.
00158  */
00159 
00160 /**
00161  * Group properties.
00162  */
00163 typedef WPropertyGroup WPVGroup;
00164 
00165 /**
00166  * Int properties.
00167  */
00168 typedef WPropertyVariable< WPVBaseTypes::PV_INT > WPVInt;
00169 
00170 /**
00171  * Floating point properties.
00172  */
00173 typedef WPropertyVariable< WPVBaseTypes::PV_DOUBLE > WPVDouble;
00174 
00175 /**
00176  * Boolean properties.
00177  */
00178 typedef WPropertyVariable< WPVBaseTypes::PV_BOOL > WPVBool;
00179 
00180 /**
00181  * String properties.
00182  */
00183 typedef WPropertyVariable< WPVBaseTypes::PV_STRING > WPVString;
00184 
00185 /**
00186  * Filename properties.
00187  */
00188 typedef WPropertyVariable< WPVBaseTypes::PV_PATH > WPVFilename;
00189 
00190 /**
00191  * Selection properties
00192  */
00193 typedef WPropertyVariable< WPVBaseTypes::PV_SELECTION > WPVSelection;
00194 
00195 /**
00196  * position (vec3d) properties
00197  */
00198 typedef WPropertyVariable< WPVBaseTypes::PV_POSITION > WPVPosition;
00199 
00200 /**
00201  * Color properties
00202  */
00203 typedef WPropertyVariable< WPVBaseTypes::PV_COLOR > WPVColor;
00204 
00205 /**
00206  * Trigger properties
00207  */
00208 typedef WPropertyVariable< WPVBaseTypes::PV_TRIGGER > WPVTrigger;
00209 
00210 /**
00211  * Trigger properties
00212  */
00213 typedef WPropertyVariable< WPVBaseTypes::PV_MATRIX4X4 > WPVMatrix4X4;
00214 
00215 /**
00216  * Transfer Function properties
00217  */
00218 typedef WPropertyVariable< WPVBaseTypes::PV_TRANSFERFUNCTION > WPVTransferFunction;
00219 
00220 /**
00221  * Some convenience type alias for a even more easy usage of WPropertyVariable.
00222  * These typdefs define some pointer alias.
00223  */
00224 
00225 /**
00226  * Alias for int32_t property variables.
00227  */
00228 typedef boost::shared_ptr< WPVInt > WPropInt;
00229 
00230 /**
00231  * Alias for int32_t property variables.
00232  */
00233 typedef boost::shared_ptr< WPVDouble > WPropDouble;
00234 
00235 /**
00236  * Alias for bool property variables.
00237  */
00238 typedef boost::shared_ptr< WPVBool > WPropBool;
00239 
00240 /**
00241  * Alias for string property variables.
00242  */
00243 typedef boost::shared_ptr< WPVString > WPropString;
00244 
00245 /**
00246  * Alias for filename property variables.
00247  */
00248 typedef boost::shared_ptr< WPVFilename > WPropFilename;
00249 
00250 /**
00251  * Alias for string list property variables.
00252  */
00253 typedef boost::shared_ptr< WPVSelection > WPropSelection;
00254 
00255 /**
00256  * Alias for position property variables.
00257  */
00258 typedef boost::shared_ptr< WPVPosition > WPropPosition;
00259 
00260 /**
00261  * Alias for color property variables.
00262  */
00263 typedef boost::shared_ptr< WPVColor > WPropColor;
00264 
00265 /**
00266  * Alias for the group properties.
00267  */
00268 typedef boost::shared_ptr< WPVGroup > WPropGroup;
00269 
00270 /**
00271  * Alias for the trigger properties.
00272  */
00273 typedef boost::shared_ptr< WPVTrigger > WPropTrigger;
00274 
00275 /**
00276  * Alias for the 4x4 matrix properties.
00277  */
00278 typedef boost::shared_ptr< WPVMatrix4X4 > WPropMatrix4X4;
00279 
00280 /**
00281  * Alias for the transfer function properties
00282  */
00283 typedef boost::shared_ptr< WPVTransferFunction > WPropTransferFunction;
00284 
00285 /**
00286  * This namespace contains several helper classes which translate their template type to an enum.
00287  */
00288 namespace PROPERTY_TYPE_HELPER
00289 {
00290     /**
00291      * Class helping to adapt types specified as template parameter into an enum.
00292      */
00293     template< typename T >
00294     class WTypeIdentifier
00295     {
00296     public:
00297         /**
00298          * Get type identifier of the template type T.
00299          *
00300          * \return type identifier-
00301          */
00302         PROPERTY_TYPE getType()
00303         {
00304             return PV_UNKNOWN;
00305         }
00306     };
00307 
00308     /**
00309      * Class helping to create a new instance of the property content from an old one. This might be needed by some types (some need to have a
00310      * predecessor for creation).
00311      * You only need to specialize this class for types not allowing the direct use of string_utils::fromString
00312      */
00313     template< typename T >
00314     class WStringConversion
00315     {
00316     public:
00317         /**
00318          * Creates a new instance of the type from a given string. Some classes need a predecessor which is also specified here.
00319          *
00320          * \param str the new value as string
00321          *
00322          * \return the new instance
00323          */
00324         T create( const T& /*old*/, const std::string str )
00325         {
00326             return string_utils::fromString< T >( str );
00327         }
00328 
00329         /**
00330          * Creates a string from the specified value.
00331          *
00332          * \param v the value to convert
00333          *
00334          * \return the string representation
00335          */
00336         std::string asString( const T& v )
00337         {
00338             return string_utils::toString( v );
00339         }
00340     };
00341 
00342     /**
00343      * Class helping to adapt types specified as template parameter into an enum.
00344      */
00345     template<>
00346     class WTypeIdentifier< WPVBaseTypes::PV_BOOL >
00347     {
00348     public:
00349         /**
00350          * Get type identifier of the template type T.
00351          *
00352          * \return type identifier-
00353          */
00354         PROPERTY_TYPE getType()
00355         {
00356             return PV_BOOL;
00357         }
00358     };
00359 
00360     /**
00361      * Class helping to adapt types specified as template parameter into an enum.
00362      */
00363     template<>
00364     class WTypeIdentifier< WPVBaseTypes::PV_INT >
00365     {
00366     public:
00367         /**
00368          * Get type identifier of the template type T.
00369          *
00370          * \return type identifier-
00371          */
00372         PROPERTY_TYPE getType()
00373         {
00374             return PV_INT;
00375         }
00376     };
00377 
00378     /**
00379      * Class helping to adapt types specified as template parameter into an enum.
00380      */
00381     template<>
00382     class WTypeIdentifier< WPVBaseTypes::PV_DOUBLE >
00383     {
00384     public:
00385         /**
00386          * Get type identifier of the template type T.
00387          *
00388          * \return type identifier-
00389          */
00390         PROPERTY_TYPE getType()
00391         {
00392             return PV_DOUBLE;
00393         }
00394     };
00395 
00396     /**
00397      * Class helping to adapt types specified as template parameter into an enum.
00398      */
00399     template<>
00400     class WTypeIdentifier< WPVBaseTypes::PV_STRING >
00401     {
00402     public:
00403         /**
00404          * Get type identifier of the template type T.
00405          *
00406          * \return type identifier-
00407          */
00408         PROPERTY_TYPE getType()
00409         {
00410             return PV_STRING;
00411         }
00412     };
00413 
00414     /**
00415      * Class helping to adapt types specified as template parameter into an enum.
00416      */
00417     template<>
00418     class WTypeIdentifier< WPVBaseTypes::PV_PATH >
00419     {
00420     public:
00421         /**
00422          * Get type identifier of the template type T.
00423          *
00424          * \return type identifier-
00425          */
00426         PROPERTY_TYPE getType()
00427         {
00428             return PV_PATH;
00429         }
00430     };
00431 
00432     /**
00433      * Class helping to adapt types specified as template parameter into an enum.
00434      */
00435     template<>
00436     class WTypeIdentifier< WPVBaseTypes::PV_SELECTION >
00437     {
00438     public:
00439         /**
00440          * Get type identifier of the template type T.
00441          *
00442          * \return type identifier-
00443          */
00444         PROPERTY_TYPE getType()
00445         {
00446             return PV_SELECTION;
00447         }
00448     };
00449 
00450     /**
00451      * Class helping to create a new instance of the property content from an old one. Selections need this special care since they contain not
00452      * serializable content which needs to be acquired from its predecessor instance.
00453      */
00454     template<>
00455     class WStringConversion< WPVBaseTypes::PV_SELECTION >
00456     {
00457     public:
00458         /**
00459          * Creates a new instance of the type from a given string. Some classes need a predecessor which is also specified here.
00460          *
00461          * \param old the old value
00462          * \param str the new value as string
00463          *
00464          * \return the new instance
00465          */
00466         WPVBaseTypes::PV_SELECTION  create( const WPVBaseTypes::PV_SELECTION& old, const std::string str )
00467         {
00468             return old.newSelector( str );
00469         }
00470 
00471         /**
00472          * Creates a string from the specified value.
00473          *
00474          * \param v the value to convert
00475          *
00476          * \return the string representation
00477          */
00478         std::string asString( const WPVBaseTypes::PV_SELECTION& v )
00479         {
00480             return string_utils::toString( v );
00481         }
00482     };
00483 
00484     /**
00485      * Class helping to adapt types specified as template parameter into an enum.
00486      */
00487     template<>
00488     class WTypeIdentifier< WPVBaseTypes::PV_POSITION >
00489     {
00490     public:
00491         /**
00492          * Get type identifier of the template type T.
00493          *
00494          * \return type identifier-
00495          */
00496         PROPERTY_TYPE getType()
00497         {
00498             return PV_POSITION;
00499         }
00500     };
00501 
00502     /**
00503      * Class helping to adapt types specified as template parameter into an enum.
00504      */
00505     template<>
00506     class WTypeIdentifier< WPVBaseTypes::PV_COLOR >
00507     {
00508     public:
00509         /**
00510          * Get type identifier of the template type T.
00511          *
00512          * \return type identifier-
00513          */
00514         PROPERTY_TYPE getType()
00515         {
00516             return PV_COLOR;
00517         }
00518     };
00519 
00520     /**
00521      * Class helping to adapt types specified as template parameter into an enum.
00522      */
00523     template<>
00524     class WTypeIdentifier< WPVBaseTypes::PV_TRIGGER >
00525     {
00526     public:
00527         /**
00528          * Get type identifier of the template type T.
00529          *
00530          * \return type identifier-
00531          */
00532         PROPERTY_TYPE getType()
00533         {
00534             return PV_TRIGGER;
00535         }
00536     };
00537 
00538     /**
00539      * Class helping to adapt types specified as template parameter into an enum.
00540      */
00541     template<>
00542     class WTypeIdentifier< WPVBaseTypes::PV_MATRIX4X4 >
00543     {
00544     public:
00545         /**
00546          * Get type identifier of the template type T.
00547          *
00548          * \return type identifier-
00549          */
00550         PROPERTY_TYPE getType()
00551         {
00552             return PV_MATRIX4X4;
00553         }
00554     };
00555 
00556     /**
00557      * Class helping to create a new instance of the property content from an old one. Selections need this special care since they contain not
00558      * serializable content which needs to be acquired from its predecessor instance.
00559      */
00560     template<>
00561     class WStringConversion< WPVBaseTypes::PV_MATRIX4X4 >
00562     {
00563     public:
00564         /**
00565          * Creates a new instance of the type from a given string. Some classes need a predecessor which is also specified here.
00566          *
00567          * \param str the new value as string
00568          *
00569          * \return the new instance
00570          */
00571         WPVBaseTypes::PV_MATRIX4X4 create( const WPVBaseTypes::PV_MATRIX4X4& /*old*/, const std::string str )
00572         {
00573             WMatrix4d c;
00574             std::vector< std::string > tokens;
00575             tokens = string_utils::tokenize( str, ";" );
00576             WAssert( tokens.size() >= 16, "There weren't 16 values for a 4x4 Matrix" );
00577 
00578             size_t idx = 0;
00579             for( size_t row = 0; row < 4; ++row )
00580             {
00581                 for( size_t col = 0; col < 4; ++col )
00582                 {
00583                     c( row, col ) = string_utils::fromString< double >( tokens[ idx ] );
00584                     idx++;
00585                 }
00586             }
00587 
00588             return c;
00589         }
00590 
00591         /**
00592          * Creates a string from the specified value.
00593          *
00594          * \param v the value to convert
00595          *
00596          * \return the string representation
00597          */
00598         std::string asString( const WPVBaseTypes::PV_MATRIX4X4& v )
00599         {
00600             std::ostringstream out;
00601             for( size_t row = 0; row < 4; ++row )
00602             {
00603                 for( size_t col = 0; col < 4; ++col )
00604                 {
00605                     out << v( row, col ) << ";";
00606                 }
00607             }
00608             return out.str();
00609         }
00610     };
00611 
00612     /**
00613      * Class helping to adapt types specified as template parameter into an enum.
00614      */
00615     template<>
00616     class WTypeIdentifier< WPVBaseTypes::PV_TRANSFERFUNCTION >
00617     {
00618     public:
00619         /**
00620          * Get type identifier of the template type T.
00621          *
00622          * \return type identifier-
00623          */
00624         PROPERTY_TYPE getType()
00625         {
00626             return PV_TRANSFERFUNCTION;
00627         }
00628     };
00629 
00630     /**
00631      * Class helping to create a new instance of the property content from an old one. Selections need this special care since they contain not
00632      * serializable content which needs to be acquired from its predecessor instance.
00633      */
00634     template<>
00635     class WStringConversion< WPVBaseTypes::PV_TRANSFERFUNCTION >
00636     {
00637     public:
00638         /**
00639          * Creates a new instance of the type from a given string. Some classes need a predecessor which is also specified here.
00640          *
00641          * \param str the new value as string
00642          *
00643          * \return the new instance
00644          */
00645         WPVBaseTypes::PV_TRANSFERFUNCTION create( const WPVBaseTypes::PV_TRANSFERFUNCTION& /*old*/, const std::string str );
00646 
00647         /**
00648          * Creates a string from the specified value.
00649          *
00650          * \param tf the value to convert
00651          *
00652          * \return the string representation
00653          */
00654         std::string asString( const WPVBaseTypes::PV_TRANSFERFUNCTION& tf );
00655     };
00656 
00657     /**
00658      * Class helping to create a new instance of the property content from an old one. Selections need this special care since they contain not
00659      * serializable content which needs to be acquired from its predecessor instance.
00660      */
00661     template<>
00662     class WStringConversion< WPVBaseTypes::PV_POSITION >
00663     {
00664     public:
00665         /**
00666          * Creates a new instance of the type from a given string. Some classes need a predecessor which is also specified here.
00667          *
00668          * \param str the new value as string
00669          *
00670          * \return the new instance
00671          */
00672         WPVBaseTypes::PV_POSITION create( const WPVBaseTypes::PV_POSITION& /*old*/, const std::string str )
00673         {
00674             WPVBaseTypes::PV_POSITION c;
00675             std::vector< std::string > tokens;
00676             tokens = string_utils::tokenize( str, ";" );
00677             WAssert( tokens.size() >= 3, "There weren't 3 values for a 3D vector" );
00678 
00679             size_t idx = 0;
00680             for( size_t col = 0; col < 3; ++col )
00681             {
00682                 c[ col ] = string_utils::fromString< double >( tokens[ idx ] );
00683                 idx++;
00684             }
00685             return c;
00686         }
00687 
00688         /**
00689          * Creates a string from the specified value.
00690          *
00691          * \param v the value to convert
00692          *
00693          * \return the string representation
00694          */
00695         std::string asString( const WPVBaseTypes::PV_POSITION& v )
00696         {
00697             std::ostringstream out;
00698             for( size_t col = 0; col < 3; ++col )
00699             {
00700                 out << v[ col ] << ";";
00701             }
00702             return out.str();
00703         }
00704     };
00705 }
00706 
00707 #endif  // WPROPERTYTYPES_H