1 #ifndef DALI_SCENE3D_MODEL_COMPONENTS_MATERIAL_H
2 #define DALI_SCENE3D_MODEL_COMPONENTS_MATERIAL_H
5 * Copyright (c) 2023 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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>
31 #include <dali-scene3d/public-api/api.h>
37 // Forward declarations.
41 } // namespace Internal
44 * @addtogroup dali_scene3d_model_components_material
49 * @brief Class for setting Material properties of 3D models
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.
59 * Material material = Material::New();
60 * ModelPrimitive modelPrimitive = ModelPrimitive::New();
61 * modelPrimitive.SetMaterial(material);
62 * material.SetProperty(PropertyIndex, PropertyValue);
65 class DALI_SCENE3D_API Material : public Dali::BaseHandle
69 * @brief Enumeration for the start and end property ranges for material.
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
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
83 * @brief Enumeration for the instance of properties belonging to the Material class.
91 * @brief Name of material.
92 * @details type Property::STRING.
95 NAME = MATERIAL_PROPERTY_START_INDEX,
98 * @brief Property for the URL of the base color texture.
99 * @details Type Property::STRING.
105 * @brief Property for the base color factor of the material surface.
106 * @details Type Property::VECTOR4.
112 * @brief Property for the URL of the metallic-roughness texture.
113 * @details Type Property::STRING.
116 METALLIC_ROUGHNESS_URL,
119 * @brief Property for the metallic factor of the material surface.
120 * @details Type Property::FLOAT.
126 * @brief Property for the roughness factor of the material surface.
127 * @details Type Property::FLOAT.
133 * @brief Property for the URL of the normal texture.
134 * @details Type Property::STRING.
140 * @brief Property for the scale factor applied to normal vectors.
141 * @details Type Property::FLOAT.
147 * @brief Property for the URL of the occlusion texture.
148 * @details Type Property::STRING.
154 * @brief Property for the occlusion strength of the material surface.
155 * @details Type Property::FLOAT.
161 * @brief Property for the URL of the emissive texture.
162 * @details Type Property::STRING.
168 * @brief Emissive factor Property.
169 * @details type Property::VECTOR3.
175 * @brief Alpha mode Property.
176 * @details type Property::INTEGER.
182 * @brief Alpha cutoff Property.
183 * @details type Property::FLOAT.
189 * @brief Double sided Property.
190 * @details type Property::BOOLEAN.
196 * @brief Index of refraction (IOR) of the material surface
197 * @details type Property::FLOAT
203 * @brief Property for the URL of the specular texture.
204 * @details Type Property::STRING.
210 * @brief Property for the specular factor of the material surface.
211 * @details Type Property::FLOAT.
217 * @brief Property for the URL of the specular color texture.
218 * @details Type Property::STRING.
224 * @brief Property for the specular color factor of the material surface.
225 * @details Type Property::VECTOR3.
228 SPECULAR_COLOR_FACTOR,
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)
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.
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.
259 * @brief Base Color Texture Property.
261 * @note This texture represents the base color of the material. In most cases, this will be the diffuse color of the material.
266 * @brief Metallic Roughness Texture Property.
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.
273 * @brief Normal Texture Property.
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.
280 * @brief Occlusion Texture Property.
282 * @note This texture represents the depth of the material. This texture can be used to make the material look more three-dimensional.
287 * @brief Emissive Texture Property.
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.
294 * @brief Specular Texture Property.
296 * @note This texture represents the specular reflection of the material. This texture can be used to make the material look more reflective.
301 * @brief Specular Color Texture Property.
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.
311 * @brief This indicates that the material is fully opaque and that the alpha value should be ignored.
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.
323 * @brief This indicates that the material is transparent and that the alpha value should be used to blend the material with the background.
329 public: // Creation & Destruction
331 * @brief Create an initialized Material.
334 * @return A handle to a newly allocated Dali resource
336 static Material New();
339 * @brief Creates an uninitialized Material.
341 * Only derived versions can be instantiated. Calling member
342 * functions with an uninitialized Dali::Object is not allowed.
351 * This is non-virtual since derived Handle types must not contain data or virtual methods.
358 * @brief Copy constructor.
361 * @param[in] material Handle to an object
363 Material(const Material& material);
366 * @brief Move constructor
369 * @param[in] rhs A reference to the moved handle
371 Material(Material&& rhs) noexcept;
374 * @brief Assignment operator.
377 * @param[in] material Handle to an object
378 * @return reference to this
380 Material& operator=(const Material& material);
383 * @brief Move assignment
386 * @param[in] rhs A reference to the moved handle
387 * @return A reference to this
389 Material& operator=(Material&& rhs) noexcept;
392 * @brief Downcasts an Object handle to Material.
394 * If handle points to a Material, the downcast produces valid handle.
395 * If not, the returned handle is left uninitialized.
398 * @param[in] handle Handle to an object
399 * @return Handle to a Material or an uninitialized handle
401 static Material DownCast(BaseHandle handle);
403 public: // Public Method
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
409 * @param[in] index The index of the property
410 * @param[in] propertyValue The new value of the property
412 void SetProperty(Dali::Property::Index index, Dali::Property::Value propertyValue);
415 * @brief Retrieves a property value.
416 * @note BaseHandle is not subclass of Handle. So this API is not use Handle.SetProperty
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.
423 Dali::Property::Value GetProperty(Dali::Property::Index index) const;
426 * @brief Convenience function for obtaining a property of a known type.
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).
435 T GetProperty(Dali::Property::Index index) const
437 Dali::Property::Value value = GetProperty(index);
439 return T(value.Get<T>());
443 * @brief Sets the texture for a given texture type.
446 * @param[in] index The texture type index
447 * @param[in] texture The texture to set.
449 void SetTexture(Scene3D::Material::TextureType index, Dali::Texture texture);
452 * @brief Gets the texture for a given texture type.
455 * @param[in] index The texture type index
456 * @return The texture at the given index.
458 Dali::Texture GetTexture(Scene3D::Material::TextureType index);
461 * @brief Sets the sampler for a given texture type.
464 * @param[in] index The texture type index
465 * @param[in] sampler The sampler to use for this texture type
467 void SetSampler(Scene3D::Material::TextureType index, Dali::Sampler sampler);
470 * @brief Gets the sampler for a given texture type.
473 * @param[in] index The texture type index
474 * @return The sampler used for this texture type
476 Dali::Sampler GetSampler(Scene3D::Material::TextureType index);
478 public: // Not intended for application developers
481 * @brief Creates a handle using the Scene3D::Internal implementation.
483 * @param[in] implementation The Material implementation
485 DALI_INTERNAL Material(Dali::Scene3D::Internal::Material* implementation);
493 } // namespace Scene3D
497 #endif // DALI_SCENE3D_MODEL_COMPONENTS_MATERIAL_H