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