Fixed SVACE and related issues in dali-scene-loader.
[platform/core/uifw/dali-toolkit.git] / dali-scene-loader / public-api / scene-definition.h
1 #ifndef DALI_SCENE_LOADER_SCENE_DEFINITION_H_
2 #define DALI_SCENE_LOADER_SCENE_DEFINITION_H_
3 /*
4  * Copyright (c) 2020 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-scene-loader/public-api/customization.h"
22 #include "dali-scene-loader/public-api/utils.h"
23 #include "dali-scene-loader/public-api/node-definition.h"
24 #include "dali-scene-loader/public-api/string-callback.h"
25
26 // EXTERNAL INCLUDES
27 #include "dali/public-api/math/quaternion.h"
28 #include "dali/public-api/math/matrix.h"
29 #include "dali/public-api/math/vector4.h"
30 #include "dali/public-api/actors/actor.h"
31 #include <string>
32 #include <memory>
33
34 namespace Dali
35 {
36 namespace SceneLoader
37 {
38
39 class MatrixStack;
40
41 /*
42  * @brief Intermediate representation of a scene with functionality required to
43  *  create DALi objects (Actors, Renderers) from it.
44  */
45 class DALI_SCENE_LOADER_API SceneDefinition
46 {
47 public:  // TYPES
48   using NodePredicate = std::function<bool(const NodeDefinition&)>;
49   using NodeConsumer = std::function<void(NodeDefinition&)>;
50   using ConstNodeConsumer = std::function<void(const NodeDefinition&)>;
51
52 public: // METHODS
53   SceneDefinition();
54   SceneDefinition(SceneDefinition&& other);
55   ~SceneDefinition();
56
57   /*
58    * @brief Registers a scene root node.
59    * @return The index of the scene root node *registration*.
60    */
61   Index AddRootNode(Index iNode);
62
63   /*
64    * @return the list of scene root node IDs in the order of their loading.
65    */
66   const std::vector<Index>& GetRoots() const;
67
68   /*
69    * @brief Removes scene root registration at the given index @a iRoot.
70    * @note @a iRoot is the index of the registration (i.e. into the vector returned by GetRoots()),
71    *  not of the node.
72    */
73   void RemoveRootNode(Index iRoot);
74
75   /*
76    * @return The number of node( definition)s in the scene.
77    */
78   uint32_t GetNodeCount() const;
79
80   /*
81    * @return Const pointer to the node (definition) at the given index.
82    */
83   const NodeDefinition* GetNode(Index iNode) const;
84
85   /*
86    * @return Pointer to the node (definition) at the given index.
87    */
88   NodeDefinition* GetNode(Index iNode);
89
90   /*
91    * @brief Traverses the scene starting from the node at the given index into
92    *  nodes, using the given customization @a choices and the visitor @a v.
93    */
94   void Visit(Index iNode, const Customization::Choices& choices, NodeDefinition::IVisitor& v);
95
96   /*
97    * @brief Traverses the scene starting from the node at the given index into
98    *  nodes, using the given customization @a choices and the visitor @a v.
99    */
100   void Visit(Index iNode, const Customization::Choices& choices, NodeDefinition::IConstVisitor& v) const;
101
102   /*
103    * @brief Counts the references to meshes, shaders, materials that nodes in
104    *  the scene are holding, writing the results into @a refCounts.
105    * @note @a refCounts' entries must have the correct size. Use ResourceBundle::GetRefCounter().
106    */
107   void CountResourceRefs(Index iNode, const Customization::Choices& choices, ResourceRefCounts& refCounts) const;
108
109   /*
110    * @brief Given a bundle of @a resources that are loaded, and customization
111    *  @a choices, this method traverses the scene, creating the actors and renderers
112    *  from node definitions.
113    * @return Handle to the root actor.
114    */
115   Actor CreateNodes(Index iNode, const Customization::Choices& choices,
116     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, std::vector<SkinningShaderConfigurationRequest>&& requests) const;
244
245   /*
246    * @brief Ensures there is no two meshes with blend shapes sharing the same shader.
247    */
248   void EnsureUniqueBlendShapeShaderInstances(ResourceBundle& resources) const;
249
250   /**
251    * @brief Performs the configuration of the given blend shapes.
252    *
253    * For each node with blend shapes it registers into the actor the weights properties for each morph target
254    * and some needed uniforms into the shader.
255    * 
256    * @param[in] root The root actor.
257    * @param[in] requests The requests to configure blend shapes.
258    * @param[in] resources The resources bundle. Meshes need to be accessed to configure the blend shapes.
259    * @param[in] onError The error callback.
260    */
261   bool ConfigureBlendshapeShaders(const ResourceBundle& resources,
262     Actor root, std::vector<BlendshapeShaderConfigurationRequest>&& requests,
263     StringCallback onError = DefaultErrorCallback) const;
264
265   SceneDefinition& operator=(SceneDefinition&& other);
266
267 private: // METHODS
268   bool FindNode(const std::string& name, std::unique_ptr<NodeDefinition>** result);
269
270 private: // DATA
271   std::vector<std::unique_ptr<NodeDefinition>> mNodes;  // size unknown up front (may discard nodes).
272   std::vector<Index> mRootNodeIds;
273 };
274
275 }
276 }
277
278 #endif //DALI_SCENE_LOADER_SCENE_DEFINITION_H_