dali-scene3d/public-api/loader/scene-definition.h

   1 #ifndef DALI_SCENE3D_LOADERER_SCENE_DEFINITION_H_
   2 #define DALI_SCENE3D_LOADERER_SCENE_DEFINITION_H_
   3 /*
   4  * Copyright (c) 2022 Samsung Electronics Co., Ltd.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 // INTERNAL INCLUDES
  21 #include "dali-scene3d/public-api/loader/customization.h"
  22 #include "dali-scene3d/public-api/loader/node-definition.h"
  23 #include "dali-scene3d/public-api/loader/string-callback.h"
  24 #include "dali-scene3d/public-api/loader/utils.h"
  25
  26 // EXTERNAL INCLUDES
  27 #include <memory>
  28 #include <string>
  29 #include "dali/public-api/actors/actor.h"
  30 #include "dali/public-api/math/matrix.h"
  31 #include "dali/public-api/math/quaternion.h"
  32 #include "dali/public-api/math/vector4.h"
  33
  34 namespace Dali
  35 {
  36 namespace Scene3D
  37 {
  38 namespace Loader
  39 {
  40 class MatrixStack;
  41
  42 /*
  43  * @brief Intermediate representation of a scene with functionality required to
  44  *  create DALi objects (Actors, Renderers) from it.
  45  */
  46 class DALI_SCENE3D_API SceneDefinition
  47 {
  48 public: // TYPES
  49   using NodePredicate     = std::function<bool(const NodeDefinition&)>;
  50   using NodeConsumer      = std::function<void(NodeDefinition&)>;
  51   using ConstNodeConsumer = std::function<void(const NodeDefinition&)>;
  52
  53 public: // METHODS
  54   SceneDefinition();
  55   SceneDefinition(SceneDefinition&& other);
  56   ~SceneDefinition();
  57
  58   /*
  59    * @brief Registers a scene root node.
  60    * @return The index of the scene root node *registration*.
  61    */
  62   Index AddRootNode(Index iNode);
  63
  64   /*
  65    * @return the list of scene root node IDs in the order of their loading.
  66    */
  67   const std::vector<Index>& GetRoots() const;
  68
  69   /*
  70    * @brief Removes scene root registration at the given index @a iRoot.
  71    * @note @a iRoot is the index of the registration (i.e. into the vector returned by GetRoots()),
  72    *  not of the node.
  73    */
  74   void RemoveRootNode(Index iRoot);
  75
  76   /*
  77    * @return The number of node( definition)s in the scene.
  78    */
  79   uint32_t GetNodeCount() const;
  80
  81   /*
  82    * @return Const pointer to the node (definition) at the given index.
  83    */
  84   const NodeDefinition* GetNode(Index iNode) const;
  85
  86   /*
  87    * @return Pointer to the node (definition) at the given index.
  88    */
  89   NodeDefinition* GetNode(Index iNode);
  90
  91   /*
  92    * @brief Traverses the scene starting from the node at the given index into
  93    *  nodes, using the given customization @a choices and the visitor @a v.
  94    */
  95   void Visit(Index iNode, const Customization::Choices& choices, NodeDefinition::IVisitor& v);
  96
  97   /*
  98    * @brief Traverses the scene starting from the node at the given index into
  99    *  nodes, using the given customization @a choices and the visitor @a v.
 100    */
 101   void Visit(Index iNode, const Customization::Choices& choices, NodeDefinition::IConstVisitor& v) const;
 102
 103   /*
 104    * @brief Counts the references to meshes, shaders, materials that nodes in
 105    *  the scene are holding, writing the results into @a refCounts.
 106    * @note @a refCounts' entries must have the correct size. Use ResourceBundle::GetRefCounter().
 107    */
 108   void CountResourceRefs(Index iNode, const Customization::Choices& choices, ResourceRefCounts& refCounts) const;
 109
 110   /*
 111    * @brief Given a bundle of @a resources that are loaded, and customization
 112    *  @a choices, this method traverses the scene, creating the actors and renderers
 113    *  from node definitions.
 114    * @return Handle to the root actor.
 115    */
 116   Actor CreateNodes(Index iNode, const Customization::Choices& choices, NodeDefinition::CreateParams& params) const;
 117
 118   /*
 119    * @brief Creates / update a registry of mappings from customization tags to
 120    *  a lists of names of customizable nodes under each tag, and the number of
 121    *  options. If @a outMissingChoices was specified, each tag that it encounters
 122    *  in the scene but not in @a choices, will be registered on it with the default
 123    *  choice of 0.
 124    */
 125   void GetCustomizationOptions(const Customization::Choices& choices,
 126                                Customization::Map&           outCustomizationOptions,
 127                                Customization::Choices*       outMissingChoices) const;
 128
 129   /*
 130    * @brief Attempts to add @a nodeDef to the end of nodes, and its index to the end of
 131    *  its parent's list of children (if iParent != NodeDefinition::INVALID_PARENT).
 132    * @return If the operation was successful - which requires nodeDef->name to be unique -
 133    *  a pointer to the stored node definition; nullptr otherwise.
 134    */
 135   NodeDefinition* AddNode(std::unique_ptr<NodeDefinition>&& nodeDef);
 136
 137   /*
 138    * @brief Moves the node to some other parent and / or to a different index.
 139    * @return Whether the operation was successful.
 140    * @note This is currently breaking an assumption of never having a child of a node at a lower
 141    *  index as that of the node itself, due to the fact that we're only changing parent ids (and
 142    *  entries into the vector of children of node definitions), to save the complication of having
 143    *  to move about, and offset indices to, everything past the reparented node. This should be
 144    *  sufficient AT LEAST AS LONG AS we recreate the SceneDefinition when loading the scene; if
 145    *  we ever needed to serialize it, we should ensure correct ordering of nodes.
 146    */
 147   bool ReparentNode(const std::string& name, const std::string& newParentName, Index siblingOrder);
 148
 149   /*
 150    * @brief Removes a node with the given name, including all of its children, and updating
 151    *  the indices on all remaining node definitions.
 152    * @return Whether the operation was successful.
 153    */
 154   bool RemoveNode(const std::string& name);
 155
 156   /*
 157    * @brief Builds the model matrix stack for the node at the given @a index.
 158    * @note It only pushes new matrices; does not require the stack to be empty (or cares if it was not).
 159    */
 160   void GetNodeModelStack(Index index, MatrixStack& model) const;
 161
 162   /*
 163    * @brief Attempts to find the definition of a node with the given @a name. Only upon
 164    *  success, and if @a outIndex is non-null, the index of the node is written to it.
 165    * @return Pointer to the node definition; nullptr if not found.
 166    * @note No ownership transfer.
 167    */
 168   NodeDefinition* FindNode(const std::string& name, Index* outIndex = nullptr);
 169
 170   /*
 171    * @brief Attempts to find the definition of a node with the given @a name. Only upon
 172    *  success, and if @a outIndex is non-null, the index of the node is written to it.
 173    * @return Pointer to the node definition; nullptr if not found.
 174    * @note No ownership transfer.
 175    */
 176   const NodeDefinition* FindNode(const std::string& name, Index* outIndex = nullptr) const;
 177
 178   /*
 179    * @return The index of the given NodeDefinition@ a node, or -1 if the node definition
 180    *  was not found.
 181    */
 182   Index FindNodeIndex(const NodeDefinition& node) const;
 183
 184   /*
 185    * @brief Calls @a consumer with up to @a limit NodeDefinitions that evaluate to true
 186    *  with @a predicate.
 187    * @note A @a limit value of 0 means no limit.
 188    */
 189   void FindNodes(NodePredicate predicate, NodeConsumer consumer, unsigned int limit = 0);
 190
 191   /*
 192    * @brief Calls @a consumer with up to @a limit NodeDefinitions that evaluate to true
 193    *  with @a predicate.
 194    * @note A @a limit value of 0 means no limit.
 195    */
 196   void FindNodes(NodePredicate predicate, ConstNodeConsumer consumer, unsigned int limit = 0) const;
 197
 198   /*
 199    * @brief Applies constraints from the given requests.
 200    */
 201   void ApplyConstraints(Actor&                           root,
 202                         std::vector<ConstraintRequest>&& constrainables,
 203                         StringCallback                   onError = DefaultErrorCallback) const;
 204
 205   /*
 206    * @brief Sets up joint matrix properties and constraints on actors that are involved in skeletal
 207    *  animation (i.e. those that are between (inclusive) the lower and upper bounds of any skeleton),
 208    *  to ensure the correct update of meshes skinned to these skeletons.
 209    * @param iRoot The index of the scene root node. Skeletons that aren't descendants of this node
 210    *  will be ignored.
 211    * @param skeletons The list of skeletons that require setting up.
 212    * @param rootActor The Actor corresponding to the root node, which will be used to locate
 213    *  other actors.
 214    */
 215   void ConfigureSkeletonJoints(uint32_t iRoot, const SkeletonDefinition::Vector& skeletons, Actor rootActor) const;
 216
 217   /*
 218    * @brief Ensures that there is no overlap between shaders used by nodes that have
 219    *  meshes skinned to different skeletons.
 220    */
 221   void EnsureUniqueSkinningShaderInstances(ResourceBundle& resources) const;
 222
 223   /*
 224    * @brief Performs the configuration of the given skinning shaders with the given skeleton
 225    *   This means that the absolute transforms of the joints are calculated and set as one of
 226    *   the uniforms in the mat4 @b uBone array (in depth first traversal). Further, the following
 227    *   are created:<br />
 228    *   - a @b jointMatrix property on each joint Actor;<br />
 229    *   - constraint from the Actor's local position and rotation (and if it has a @e joint
 230    *     parent, the jointMatrix of the parent) to its @b jointMatrix property;<br />
 231    *   - a constraint from the the Actor's @b jointMatrix property to the related entry in
 232    *     the shader's @b uBone property;<br />
 233    *   This ensures the automatic update of the skeletal animation, should any of the joints'
 234    *   transform changes, by whatever means.
 235    * @return The success of the operations. Error messages will be posted to the optional
 236    *   @a onError callback.
 237    * @note A maximum of SkinningDetails::MAX_JOINTS joints per skeleton are supported at the moment.
 238    * @note Even if multiple skinned meshes use the same skinning shader, the correct number
 239    *   of separate instances need to be declared in the .dli to avoid clashing uniform
 240    *   definitions and constraints.
 241    */
 242   void ConfigureSkinningShaders(const ResourceBundle&                             resources,
 243                                 Actor                                             root,
 244                                 std::vector<SkinningShaderConfigurationRequest>&& requests) const;
 245
 246   /*
 247    * @brief Ensures there is no two meshes with blend shapes sharing the same shader.
 248    */
 249   void EnsureUniqueBlendShapeShaderInstances(ResourceBundle& resources) const;
 250
 251   /**
 252    * @brief Performs the configuration of the given blend shapes.
 253    *
 254    * For each node with blend shapes it registers into the actor the weights properties for each morph target
 255    * and some needed uniforms into the shader.
 256    *
 257    * @param[in] root The root actor.
 258    * @param[in] requests The requests to configure blend shapes.
 259    * @param[in] resources The resources bundle. Meshes need to be accessed to configure the blend shapes.
 260    * @param[in] onError The error callback.
 261    */
 262   bool ConfigureBlendshapeShaders(const ResourceBundle&                               resources,
 263                                   Actor                                               root,
 264                                   std::vector<BlendshapeShaderConfigurationRequest>&& requests,
 265                                   StringCallback                                      onError = DefaultErrorCallback) const;
 266
 267   SceneDefinition& operator=(SceneDefinition&& other);
 268
 269 private: // METHODS
 270   bool FindNode(const std::string& name, std::unique_ptr<NodeDefinition>** result);
 271
 272 private:                                               // DATA
 273   std::vector<std::unique_ptr<NodeDefinition>> mNodes; // size unknown up front (may discard nodes).
 274   std::vector<Index>                           mRootNodeIds;
 275 };
 276
 277 } // namespace Loader
 278 } // namespace Scene3D
 279 } // namespace Dali
 280
 281 #endif //DALI_SCENE3D_LOADERER_SCENE_DEFINITION_H_