dali-scene3d/public-api/model-components/material.h

   1 #ifndef DALI_SCENE3D_MODEL_COMPONENTS_MATERIAL_H
   2 #define DALI_SCENE3D_MODEL_COMPONENTS_MATERIAL_H
   3
   4 /*
   5  * Copyright (c) 2023 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 <dali/public-api/common/dali-common.h>
  23 #include <dali/public-api/object/base-handle.h>
  24 #include <dali/public-api/object/property-index-ranges.h>
  25 #include <dali/public-api/object/property-value.h>
  26 #include <dali/public-api/object/property.h>
  27 #include <dali/public-api/rendering/sampler.h>
  28 #include <dali/public-api/rendering/texture.h>
  29
  30 // INTERNAL INCLUDES
  31 #include <dali-scene3d/public-api/api.h>
  32
  33 namespace Dali
  34 {
  35 namespace Scene3D
  36 {
  37 // Forward declarations.
  38 namespace Internal
  39 {
  40 class Material;
  41 } // namespace Internal
  42
  43 /**
  44  * @addtogroup dali_scene3d_model_components_material
  45  * @{
  46  */
  47
  48 /**
  49  * @brief Class for setting Material properties of 3D models
  50  *
  51  * @SINCE_2_2.22
  52  *
  53  * @note This Material class is for setting Material properties of 3D models.
  54  * This Material supports properties and textures for PBR.
  55  * Also, Material can be shared with multiple ModelPrimitives and if the value is modified,
  56  * the rendering results of all ModelPrimitives using this Material will be changed.
  57  *
  58  * @code
  59  * Material material = Material::New();
  60  * ModelPrimitive modelPrimitive = ModelPrimitive::New();
  61  * modelPrimitive.SetMaterial(material);
  62  * material.SetProperty(PropertyIndex, PropertyValue);
  63  * @endcode
  64  */
  65 class DALI_SCENE3D_API Material : public Dali::BaseHandle
  66 {
  67 public:
  68   /**
  69    * @brief Enumeration for the start and end property ranges for material.
  70    * @SINCE_2_2.22
  71    */
  72   enum PropertyRange
  73   {
  74     PROPERTY_START_INDEX          = PROPERTY_REGISTRATION_START_INDEX,    ///< Start index is used by the property registration macro. @SINCE_2_2.22
  75     MATERIAL_PROPERTY_START_INDEX = PROPERTY_START_INDEX,                 ///< Start index of Control properties. @SINCE_2_2.22
  76     MATERIAL_PROPERTY_END_INDEX   = MATERIAL_PROPERTY_START_INDEX + 1000, ///< Reserving 1000 property indices. @SINCE_2_2.22
  77
  78     ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX,        ///< @SINCE_2_2.22
  79     ANIMATABLE_PROPERTY_END_INDEX   = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000, ///< Reserve animatable property indices, @SINCE_2_2.22
  80   };
  81
  82   /**
  83    * @brief Enumeration for the instance of properties belonging to the Material class.
  84    * @SINCE_2_2.22
  85    */
  86   struct Property
  87   {
  88     enum
  89     {
  90       /**
  91        * @brief Name of material.
  92        * @details type Property::STRING.
  93        * @SINCE_2_2.22
  94        */
  95       NAME = MATERIAL_PROPERTY_START_INDEX,
  96
  97       /**
  98        * @brief Property for the URL of the base color texture.
  99        * @details Type Property::STRING.
 100        * @SINCE_2_2.22
 101        */
 102       BASE_COLOR_URL,
 103
 104       /**
 105        * @brief Property for the base color factor of the material surface.
 106        * @details Type Property::VECTOR4.
 107        * @SINCE_2_2.22
 108        */
 109       BASE_COLOR_FACTOR,
 110
 111       /**
 112        * @brief Property for the URL of the metallic-roughness texture.
 113        * @details Type Property::STRING.
 114        * @SINCE_2_2.22
 115        */
 116       METALLIC_ROUGHNESS_URL,
 117
 118       /**
 119        * @brief Property for the metallic factor of the material surface.
 120        * @details Type Property::FLOAT.
 121        * @SINCE_2_2.22
 122        */
 123       METALLIC_FACTOR,
 124
 125       /**
 126        * @brief Property for the roughness factor of the material surface.
 127        * @details Type Property::FLOAT.
 128        * @SINCE_2_2.22
 129        */
 130       ROUGHNESS_FACTOR,
 131
 132       /**
 133        * @brief Property for the URL of the normal texture.
 134        * @details Type Property::STRING.
 135        * @SINCE_2_2.22
 136        */
 137       NORMAL_URL,
 138
 139       /**
 140        * @brief Property for the scale factor applied to normal vectors.
 141        * @details Type Property::FLOAT.
 142        * @SINCE_2_2.22
 143        */
 144       NORMAL_SCALE,
 145
 146       /**
 147        * @brief Property for the URL of the occlusion texture.
 148        * @details Type Property::STRING.
 149        * @SINCE_2_2.22
 150        */
 151       OCCLUSION_URL,
 152
 153       /**
 154        * @brief Property for the occlusion strength of the material surface.
 155        * @details Type Property::FLOAT.
 156        * @SINCE_2_2.22
 157        */
 158       OCCLUSION_STRENGTH,
 159
 160       /**
 161        * @brief Property for the URL of the emissive texture.
 162        * @details Type Property::STRING.
 163        * @SINCE_2_2.22
 164        */
 165       EMISSIVE_URL,
 166
 167       /**
 168        * @brief Emissive factor Property.
 169        * @details type Property::VECTOR3.
 170        * @SINCE_2_2.22
 171        */
 172       EMISSIVE_FACTOR,
 173
 174       /**
 175        * @brief Alpha mode Property.
 176        * @details type Property::INTEGER.
 177        * @SINCE_2_2.22
 178        */
 179       ALPHA_MODE,
 180
 181       /**
 182        * @brief Alpha cutoff Property.
 183        * @details type Property::FLOAT.
 184        * @SINCE_2_2.22
 185        */
 186       ALPHA_CUTOFF,
 187
 188       /**
 189        * @brief Double sided Property.
 190        * @details type Property::BOOLEAN.
 191        * @SINCE_2_2.22
 192        */
 193       DOUBLE_SIDED,
 194
 195       /**
 196        * @brief Index of refraction (IOR) of the material surface
 197        * @details type Property::FLOAT
 198        * @SINCE_2_2.22
 199        */
 200       IOR,
 201
 202       /**
 203        * @brief Property for the URL of the specular texture.
 204        * @details Type Property::STRING.
 205        * @SINCE_2_2.22
 206        */
 207       SPECULAR_URL,
 208
 209       /**
 210        * @brief Property for the specular factor of the material surface.
 211        * @details Type Property::FLOAT.
 212        * @SINCE_2_2.22
 213        */
 214       SPECULAR_FACTOR,
 215
 216       /**
 217        * @brief Property for the URL of the specular color texture.
 218        * @details Type Property::STRING.
 219        * @SINCE_2_2.22
 220        */
 221       SPECULAR_COLOR_URL,
 222
 223       /**
 224        * @brief Property for the specular color factor of the material surface.
 225        * @details Type Property::VECTOR3.
 226        * @SINCE_2_2.22
 227        */
 228       SPECULAR_COLOR_FACTOR,
 229
 230       /**
 231        * @brief Property to define rendering order.
 232        * @details Depth index is used to define rendering order. This property
 233        * is compatible with Dali::Renderer::Property::DepthIndex. Basically,
 234        * a Renderer that has smaller depth index is rendered earlier.
 235        * In the ordinary DALI UI components has 0 as depth index by default.
 236        * (For the case of Toolkit::Control, its renderer has depth index
 237        * value between [-20, 20] as fallowing the renderer's purpose)
 238        *
 239        * In the Scene3D cases, the rendering order of each Renderer may need
 240        * to be manually defined to match scene developer's intent.
 241        * Scene3D::DepthIndex::Ranges could be used to adjust rendering order
 242        * between 3D Scene content.
 243        * Or it also could be used to manage UI component in 3D Scene independently.
 244        *
 245        * Changing the depth index only affects the rendering order, and does not
 246        * mean that objects drawn later will be drawn on top. To compute final
 247        * rendering order, whether the object is opaque or non-opaque takes precedence
 248        * over the depth index. Changing the rendering order among translucent objects
 249        * has a significant impact on the rendering results.
 250        * @SINCE_2_3.3
 251        */
 252       DEPTH_INDEX,
 253     };
 254   };
 255
 256   enum TextureType
 257   {
 258     /**
 259      * @brief Base Color Texture Property.
 260      * @SINCE_2_2.22
 261      * @note This texture represents the base color of the material. In most cases, this will be the diffuse color of the material.
 262      */
 263     BASE_COLOR,
 264
 265     /**
 266      * @brief Metallic Roughness Texture Property.
 267      * @SINCE_2_2.22
 268      * @note This texture represents the metallicness and roughness of the material. This texture can be used to make the material look more metallic or rough.
 269      */
 270     METALLIC_ROUGHNESS,
 271
 272     /**
 273      * @brief Normal Texture Property.
 274      * @SINCE_2_2.22
 275      * @note This texture represents the surface of the material. This texture can be used to make the surface of the material look smooth or rough.
 276      */
 277     NORMAL,
 278
 279     /**
 280      * @brief Occlusion Texture Property.
 281      * @SINCE_2_2.22
 282      * @note This texture represents the depth of the material. This texture can be used to make the material look more three-dimensional.
 283      */
 284     OCCLUSION,
 285
 286     /**
 287      * @brief Emissive Texture Property.
 288      * @SINCE_2_2.22
 289      * @note This texture makes the material look like it's emitting light. This texture can be used to make the material look like it's glowing.
 290      */
 291     EMISSIVE,
 292
 293     /**
 294      * @brief Specular Texture Property.
 295      * @SINCE_2_2.22
 296      * @note This texture represents the specular reflection of the material. This texture can be used to make the material look more reflective.
 297      */
 298     SPECULAR,
 299
 300     /**
 301      * @brief Specular Color Texture Property.
 302      * @SINCE_2_2.22
 303      * @note This texture represents the color of the specular reflection of the material. This texture can be used to set the color of the specular reflection of the material.
 304      */
 305     SPECULAR_COLOR,
 306   };
 307
 308   enum AlphaModeType
 309   {
 310     /**
 311      * @brief This indicates that the material is fully opaque and that the alpha value should be ignored.
 312      * @SINCE_2_2.22
 313      */
 314     OPAQUE,
 315
 316     /**
 317      * @brief This indicates that the material is either fully opaque or fully transparent depending on the alpha value. The alpha value is used to mask out areas of the material that should be transparent.
 318      * @SINCE_2_2.22
 319      */
 320     MASK,
 321
 322     /**
 323      * @brief This indicates that the material is transparent and that the alpha value should be used to blend the material with the background.
 324      * @SINCE_2_2.22
 325      */
 326     BLEND,
 327   };
 328
 329 public: // Creation & Destruction
 330   /**
 331    * @brief Create an initialized Material.
 332    *
 333    * @SINCE_2_2.22
 334    * @return A handle to a newly allocated Dali resource
 335    */
 336   static Material New();
 337
 338   /**
 339    * @brief Creates an uninitialized Material.
 340    *
 341    * Only derived versions can be instantiated. Calling member
 342    * functions with an uninitialized Dali::Object is not allowed.
 343    *
 344    * @SINCE_2_2.22
 345    */
 346   Material();
 347
 348   /**
 349    * @brief Destructor.
 350    *
 351    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 352    *
 353    * @SINCE_2_2.22
 354    */
 355   ~Material();
 356
 357   /**
 358    * @brief Copy constructor.
 359    *
 360    * @SINCE_2_2.22
 361    * @param[in] material Handle to an object
 362    */
 363   Material(const Material& material);
 364
 365   /**
 366    * @brief Move constructor
 367    *
 368    * @SINCE_2_2.22
 369    * @param[in] rhs A reference to the moved handle
 370    */
 371   Material(Material&& rhs) noexcept;
 372
 373   /**
 374    * @brief Assignment operator.
 375    *
 376    * @SINCE_2_2.22
 377    * @param[in] material Handle to an object
 378    * @return reference to this
 379    */
 380   Material& operator=(const Material& material);
 381
 382   /**
 383    * @brief Move assignment
 384    *
 385    * @SINCE_2_2.22
 386    * @param[in] rhs A reference to the moved handle
 387    * @return A reference to this
 388    */
 389   Material& operator=(Material&& rhs) noexcept;
 390
 391   /**
 392    * @brief Downcasts an Object handle to Material.
 393    *
 394    * If handle points to a Material, the downcast produces valid handle.
 395    * If not, the returned handle is left uninitialized.
 396    *
 397    * @SINCE_2_2.22
 398    * @param[in] handle Handle to an object
 399    * @return Handle to a Material or an uninitialized handle
 400    */
 401   static Material DownCast(BaseHandle handle);
 402
 403 public: // Public Method
 404   /**
 405    * @brief Sets the value of an existing property.
 406    * @note BaseHandle is not subclass of Handle. So this API is not use Handle.SetProperty
 407    *
 408    * @SINCE_2_2.22
 409    * @param[in] index The index of the property
 410    * @param[in] propertyValue The new value of the property
 411    */
 412   void SetProperty(Dali::Property::Index index, Dali::Property::Value propertyValue);
 413
 414   /**
 415    * @brief Retrieves a property value.
 416    * @note BaseHandle is not subclass of Handle. So this API is not use Handle.SetProperty
 417    *
 418    * @SINCE_2_2.22
 419    * @param[in] index The index of the property
 420    * @return The property value
 421    * @note This returns the value set by SetProperty() or the animation target value if it is being animated.
 422    */
 423   Dali::Property::Value GetProperty(Dali::Property::Index index) const;
 424
 425   /**
 426    * @brief Convenience function for obtaining a property of a known type.
 427    *
 428    * @SINCE_2_2.22
 429    * @param[in] index The index of the property
 430    * @return The property value
 431    * @pre The property types match i.e. PropertyTypes::Get<T>() is equal to GetPropertyType(index).
 432    * @see GetProperty()
 433    */
 434   template<typename T>
 435   T GetProperty(Dali::Property::Index index) const
 436   {
 437     Dali::Property::Value value = GetProperty(index);
 438
 439     return T(value.Get<T>());
 440   }
 441
 442   /**
 443    * @brief Sets the texture for a given texture type.
 444    *
 445    * @SINCE_2_2.22
 446    * @param[in] index The texture type index
 447    * @param[in] texture The texture to set.
 448    */
 449   void SetTexture(Scene3D::Material::TextureType index, Dali::Texture texture);
 450
 451   /**
 452    * @brief Gets the texture for a given texture type.
 453    *
 454    * @SINCE_2_2.22
 455    * @param[in] index The texture type index
 456    * @return The texture at the given index.
 457    */
 458   Dali::Texture GetTexture(Scene3D::Material::TextureType index);
 459
 460   /**
 461    * @brief Sets the sampler for a given texture type.
 462    *
 463    * @SINCE_2_2.22
 464    * @param[in] index The texture type index
 465    * @param[in] sampler The sampler to use for this texture type
 466    */
 467   void SetSampler(Scene3D::Material::TextureType index, Dali::Sampler sampler);
 468
 469   /**
 470    * @brief Gets the sampler for a given texture type.
 471    *
 472    * @SINCE_2_2.22
 473    * @param[in] index The texture type index
 474    * @return The sampler used for this texture type
 475    */
 476   Dali::Sampler GetSampler(Scene3D::Material::TextureType index);
 477
 478 public: // Not intended for application developers
 479   /// @cond internal
 480   /**
 481    * @brief Creates a handle using the Scene3D::Internal implementation.
 482    *
 483    * @param[in] implementation The Material implementation
 484    */
 485   DALI_INTERNAL Material(Dali::Scene3D::Internal::Material* implementation);
 486   /// @endcond
 487 };
 488
 489 /**
 490  * @}
 491  */
 492
 493 } // namespace Scene3D
 494
 495 } // namespace Dali
 496
 497 #endif // DALI_SCENE3D_MODEL_COMPONENTS_MATERIAL_H