dali/internal/event/common/property-metadata.h

   1 #ifndef DALI_INTERNAL_PROPERTY_METADATA_H
   2 #define DALI_INTERNAL_PROPERTY_METADATA_H
   3
   4 /*
   5  * Copyright (c) 2019 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <algorithm>
  23 #include <utility>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/common/constants.h>
  27 #include <dali/public-api/object/property.h>
  28 #include <dali/public-api/object/property-value.h>
  29
  30 namespace Dali
  31 {
  32
  33 namespace Internal
  34 {
  35
  36 namespace SceneGraph
  37 {
  38 class PropertyBase;
  39 }
  40
  41 /**
  42  * @brief Base class for the Metadata required by custom and registered animatable properties.
  43  *
  44  * The value type field should be queried, before accessing the scene-graph property:
  45  *
  46  * @code
  47  * void Example(PropertyEntry entry)
  48  * {
  49  *   if (entry.value.GetType() == Property::VECTOR3)
  50  *   {
  51  *     SceneGraph::AnimatableProperty<Vector3>* property = dynamic_cast< SceneGraph::AnimatableProperty<Vector3>* >( entry.property );
  52  *     ...
  53  *   }
  54  * @endcode
  55  *
  56  */
  57 class PropertyMetadata
  58 {
  59 public:
  60
  61   /**
  62    * @brief Virtual Destructor.
  63    */
  64   virtual ~PropertyMetadata() = default;
  65
  66   /**
  67    * @brief Returns whether the property is animatable (i.e. if its a scene graph property).
  68    * @return True if animatable, false otherwise
  69    */
  70   bool IsAnimatable( void ) const
  71   {
  72     return nullptr != mSceneGraphProperty;
  73   }
  74
  75   /**
  76    * @brief Whether the property can be written to.
  77    * @return True if the property can be written to, false otherwise
  78    */
  79   bool IsWritable( void ) const
  80   {
  81     return mWritable;
  82   }
  83
  84   /**
  85    * @brief Retrieves the scene-graph property.
  86    * @return The scene graph property
  87    *
  88    * @note Should only be called if the scene-graph property was passed in originally. Will debug assert if the stored property is NULL.
  89    */
  90   const SceneGraph::PropertyBase* GetSceneGraphProperty() const
  91   {
  92     DALI_ASSERT_DEBUG( mSceneGraphProperty && "Accessing uninitialized SceneGraph property" );
  93     return mSceneGraphProperty;
  94   }
  95
  96   /**
  97    * @brief Retrieve the type of the property.
  98    * @return Type of the held property value
  99    */
 100   inline Property::Type GetType() const
 101   {
 102     return value.GetType();
 103   }
 104
 105   /**
 106    * Set the cached value of the property.
 107    * @param[in] value The propertyValue to set.
 108    */
 109   void SetPropertyValue( const Property::Value& propertyValue );
 110
 111   /**
 112    * Get the cached value of a the property.
 113    * @return The cached value of the property.
 114    */
 115   Property::Value GetPropertyValue() const;
 116
 117   /**
 118    * Modifies the stored value by the relativeValue.
 119    * @param[in] relativeValue The value to change by.
 120    */
 121   void AdjustPropertyValueBy( const Property::Value& relativeValue );
 122
 123 protected:
 124
 125   /**
 126    * @brief Constructor to create Metadata for a property.
 127    * @param[in] propertyValue       The value of the property (this is used by the event thread)
 128    * @param[in] sceneGraphProperty  A pointer to the scene-graph owned property
 129    * @param[in] writable            Whether the property is writable
 130    */
 131   PropertyMetadata( Property::Value propertyValue,
 132                     const SceneGraph::PropertyBase* sceneGraphProperty,
 133                     bool writable )
 134   : value( mStoredValue ),
 135     componentIndex( Property::INVALID_COMPONENT_INDEX ),
 136     mStoredValue( std::move(propertyValue) ),
 137     mSceneGraphProperty( sceneGraphProperty ),
 138     mWritable( writable )
 139   {
 140   }
 141
 142   /**
 143    * @brief Constructor to create Metadata for a component of another property.
 144    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 145    * @param[in] writable                Whether the property is writable
 146    * @param[in] baseValueRef            A reference to the metadata of the base animatable property
 147    * @param[in] propertyComponentIndex  The component index of the property
 148    */
 149   PropertyMetadata( const SceneGraph::PropertyBase* sceneGraphProperty, bool writable, Property::Value& baseValueRef, int32_t propertyComponentIndex )
 150   : value( baseValueRef ),
 151     componentIndex( propertyComponentIndex ),
 152     mStoredValue(),
 153     mSceneGraphProperty( sceneGraphProperty ),
 154     mWritable( writable )
 155   {
 156   }
 157
 158 private:
 159
 160   // Not implemented
 161   PropertyMetadata( const PropertyMetadata& );
 162   PropertyMetadata& operator=( const PropertyMetadata& );
 163
 164 public: // Data
 165
 166   /**
 167    * @brief The value of this property used to read/write by the event thread.
 168    *
 169    * If this PropertyMetadata is for property component, then refers to the value in the PropertyMetadata of the base property
 170    * to ensure the components are kept in sync with the overall value on the event thread.
 171    * Otherwise, this refers to mStoredValue.
 172    */
 173   Property::Value& value;
 174
 175   /**
 176    * @brief The index of the property component.
 177    */
 178   int32_t componentIndex;
 179
 180 private:
 181
 182   Property::Value mStoredValue;                         ///< The cached property value used to read/write by the event thread
 183   const SceneGraph::PropertyBase* mSceneGraphProperty;  ///< A pointer to a scene-graph property; should not be modified from actor-thread
 184   bool mWritable:1;                                     ///< Whether the property is writable
 185 };
 186
 187 /**
 188  * @brief Metadata for a registered animatable property.
 189  */
 190 class AnimatablePropertyMetadata : public PropertyMetadata
 191 {
 192 public:
 193
 194   /**
 195    * @brief Constructs metadata for a registered animatable property.
 196    * @param[in] propertyIndex           The index of the animatable property
 197    * @param[in] propertyComponentIndex  The component index of the animatable property
 198    * @param[in] propertyValue           The value of the property (this is used by the event thread)
 199    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 200    *
 201    * @note The base animatable property MUST be created before the component animatable property.
 202    */
 203   AnimatablePropertyMetadata( Property::Index propertyIndex,
 204                               const Property::Value& propertyValue,
 205                               const SceneGraph::PropertyBase* sceneGraphProperty )
 206   : PropertyMetadata( propertyValue, sceneGraphProperty, true ),
 207     index( propertyIndex )
 208   {
 209     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 210   }
 211
 212   /**
 213    * @brief Constructs metadata for a registered animatable component of another property.
 214    * @param[in] propertyIndex           The index of the animatable property
 215    * @param[in] propertyComponentIndex  The component index of the animatable property
 216    * @param[in] baseValueRef            A reference to the metadata of the base animatable property
 217    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 218    *
 219    * @note The base animatable property MUST be created before the component animatable property.
 220    */
 221   AnimatablePropertyMetadata( Property::Index propertyIndex,
 222                               int propertyComponentIndex,
 223                               Property::Value& baseValueRef,
 224                               const SceneGraph::PropertyBase* sceneGraphProperty )
 225   : PropertyMetadata( sceneGraphProperty, true, baseValueRef, propertyComponentIndex ),
 226     index( propertyIndex )
 227   {
 228     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 229   }
 230
 231   /**
 232    * @brief Destructor.
 233    */
 234   ~AnimatablePropertyMetadata() override = default;
 235
 236 private:
 237
 238   // Not implemented
 239   AnimatablePropertyMetadata();
 240   AnimatablePropertyMetadata( const AnimatablePropertyMetadata& );
 241   AnimatablePropertyMetadata& operator=( const AnimatablePropertyMetadata& );
 242
 243 public: // Data
 244
 245   Property::Index   index;    ///< The index of the property.
 246 };
 247
 248 class CustomPropertyMetadata : public PropertyMetadata
 249 {
 250 public:
 251
 252   /**
 253    * Constructs Metadata for scene-graph-based custom properties, i.e. animatable custom properties.
 254    * @param[in] propertyName        The name of the custom property
 255    * @param[in] propertyKey         The key of the custom property
 256    * @param[in] propertyValue       The value of the property (this is used by the event thread)
 257    * @param[in] sceneGraphProperty  A pointer to the scene-graph owned property
 258    *
 259    * @note A valid sceneGraphProperty is mandatory otherwise this will debug assert.
 260    */
 261   CustomPropertyMetadata( std::string propertyName,
 262                           Property::Index propertyKey,
 263                           Property::Value propertyValue,
 264                           const SceneGraph::PropertyBase* sceneGraphProperty )
 265   : PropertyMetadata( std::move(propertyValue), sceneGraphProperty, true ),
 266     name( std::move(propertyName) ),
 267     key( propertyKey ),
 268     childPropertyIndex( Property::INVALID_INDEX )
 269   {
 270     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 271   }
 272
 273   /**
 274    * Constructs metadata for event side only custom properties.
 275    * @param[in] propertyName   The name of the custom property
 276    * @param[in] propertyValue  The value of the property (this is used by the event thread)
 277    * @param[in] accessMode     The access mode of the custom property (writable, animatable etc)
 278    *
 279    * @note The access mode MUST NOT be animatable otherwise this will debug assert.
 280    */
 281   CustomPropertyMetadata( std::string propertyName,
 282                           Property::Value propertyValue,
 283                           Property::AccessMode accessMode )
 284   : PropertyMetadata( std::move(propertyValue), nullptr, ( accessMode != Property::READ_ONLY ) ),
 285     name( std::move(propertyName) ),
 286     key( Property::INVALID_KEY ),
 287     childPropertyIndex( Property::INVALID_INDEX )
 288   {
 289     DALI_ASSERT_DEBUG( accessMode != Property::ANIMATABLE && "Event side only properties should not be animatable" );
 290   }
 291
 292   /**
 293    * @brief Destructor.
 294    */
 295   ~CustomPropertyMetadata() override = default;
 296
 297 private:
 298
 299   // Not implemented
 300   CustomPropertyMetadata();
 301   CustomPropertyMetadata( const CustomPropertyMetadata& );
 302   CustomPropertyMetadata& operator=( const CustomPropertyMetadata& );
 303
 304 public: // Data
 305
 306   std::string       name;                 ///< The name of the property.
 307   Property::Index   key;                  ///< The key of the property.
 308   Property::Index   childPropertyIndex;   ///< The index as a child property.
 309 };
 310
 311 } // namespace Internal
 312
 313 } // namespace Dali
 314
 315 #endif // DALI_INTERNAL_PROPERTY_METADATA_H