Cleanup: remove redundant doxygen \file argument
[blender.git] / source / blender / depsgraph / intern / depsgraph.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2013 Blender Foundation.
17  * All rights reserved.
18  */
19
20 /** \file \ingroup depsgraph
21  *
22  * Datatypes for internal use in the Depsgraph
23  *
24  * All of these datatypes are only really used within the "core" depsgraph.
25  * In particular, node types declared here form the structure of operations
26  * in the graph.
27  */
28
29 #pragma once
30
31 #include <stdlib.h>
32
33 #include "DNA_ID.h" /* for ID_Type */
34
35 #include "BKE_main.h" /* for MAX_LIBARRAY */
36
37 #include "BLI_threads.h"  /* for SpinLock */
38
39 #include "DEG_depsgraph.h"
40 #include "DEG_depsgraph_physics.h"
41
42 #include "intern/depsgraph_type.h"
43
44 struct GHash;
45 struct GSet;
46 struct ID;
47 struct Main;
48 struct PointerRNA;
49 struct PropertyRNA;
50 struct Scene;
51 struct ViewLayer;
52
53 namespace DEG {
54
55 struct ComponentNode;
56 struct Node;
57 struct IDNode;
58 struct OperationNode;
59 struct TimeSourceNode;
60
61 /* *************************** */
62 /* Relationships Between Nodes */
63
64 /* Settings/Tags on Relationship.
65  * NOTE: Is a bitmask, allowing accumulation. */
66 enum RelationFlag {
67         /* "cyclic" link - when detecting cycles, this relationship was the one
68          * which triggers a cyclic relationship to exist in the graph. */
69         RELATION_FLAG_CYCLIC               = (1 << 0),
70         /* Update flush will not go through this relation. */
71         RELATION_FLAG_NO_FLUSH             = (1 << 1),
72         /* Only flush along the relation is update comes from a node which was
73          * affected by user input. */
74         RELATION_FLAG_FLUSH_USER_EDIT_ONLY = (1 << 2),
75         /* The relation can not be killed by the cyclic dependencies solver. */
76         RELATION_FLAG_GODMODE              = (1 << 3),
77         /* Relation will check existance before being added. */
78         RELATION_CHECK_BEFORE_ADD          = (1 << 4),
79 };
80
81 /* B depends on A (A -> B) */
82 struct Relation {
83         Relation(Node *from, Node *to, const char *description);
84         ~Relation();
85
86         void unlink();
87
88         /* the nodes in the relationship (since this is shared between the nodes) */
89         Node *from;               /* A */
90         Node *to;                 /* B */
91
92         /* relationship attributes */
93         const char *name;             /* label for debugging */
94         int flag;                     /* Bitmask of RelationFlag) */
95 };
96
97 /* For queries which gives operation node or key defines whether we are
98  * interested in a result of the given property or whether we are linking some
99  * dependency to that property. */
100 enum class RNAPointerSource {
101         /* Query will return pointer to an entry operation of component which is
102          * responsible for evaluation of the given property. */
103         ENTRY,
104         /* Query will return pointer to an exit operation of component which is
105          * responsible for evaluation of the given property.
106          * More precisely, it will return operation at which the property is known
107          * to be evaluated. */
108         EXIT,
109 };
110
111 /* ********* */
112 /* Depsgraph */
113
114 /* Dependency Graph object */
115 struct Depsgraph {
116         // TODO(sergey): Go away from C++ container and use some native BLI.
117         typedef vector<OperationNode *> OperationNodes;
118         typedef vector<IDNode *> IDDepsNodes;
119
120         Depsgraph(Scene *scene,
121                   ViewLayer *view_layer,
122                   eEvaluationMode mode);
123         ~Depsgraph();
124
125         /**
126          * Convenience wrapper to find node given just pointer + property.
127          *
128          * \param ptr: pointer to the data that node will represent
129          * \param prop: optional property affected - providing this effectively
130          *              results in inner nodes being returned
131          *
132          * \return A node matching the required characteristics if it exists
133          * or NULL if no such node exists in the graph */
134         Node *find_node_from_pointer(const PointerRNA *ptr,
135                                          const PropertyRNA *prop,
136                                          RNAPointerSource source) const;
137
138         TimeSourceNode *add_time_source();
139         TimeSourceNode *find_time_source() const;
140
141         IDNode *find_id_node(const ID *id) const;
142         IDNode *add_id_node(ID *id, ID *id_cow_hint = NULL);
143         void clear_id_nodes();
144         void clear_id_nodes_conditional(const std::function <bool (ID_Type id_type)>& filter);
145
146         /* Add new relationship between two nodes. */
147         Relation *add_new_relation(Node *from,
148                                    Node *to,
149                                    const char *description,
150                                    int flags = 0);
151
152         /* Check whether two nodes are connected by relation with given
153          * description. Description might be NULL to check ANY relation between
154          * given nodes. */
155         Relation *check_nodes_connected(const Node *from,
156                                         const Node *to,
157                                         const char *description);
158
159         /* Tag a specific node as needing updates. */
160         void add_entry_tag(OperationNode *node);
161
162         /* Clear storage used by all nodes. */
163         void clear_all_nodes();
164
165         /* Copy-on-Write Functionality ........ */
166
167         /* For given original ID get ID which is created by CoW system. */
168         ID *get_cow_id(const ID *id_orig) const;
169
170         /* Core Graph Functionality ........... */
171
172         /* <ID : IDNode> mapping from ID blocks to nodes representing these
173          * blocks, used for quick lookups. */
174         GHash *id_hash;
175
176         /* Ordered list of ID nodes, order matches ID allocation order.
177          * Used for faster iteration, especially for areas which are critical to
178          * keep exact order of iteration. */
179         IDDepsNodes id_nodes;
180
181         /* Top-level time source node. */
182         TimeSourceNode *time_source;
183
184         /* Indicates whether relations needs to be updated. */
185         bool need_update;
186
187         /* Indicates which ID types were updated. */
188         char id_type_updated[MAX_LIBARRAY];
189
190         /* Quick-Access Temp Data ............. */
191
192         /* Nodes which have been tagged as "directly modified". */
193         GSet *entry_tags;
194
195         /* Convenience Data ................... */
196
197         /* XXX: should be collected after building (if actually needed?) */
198         /* All operation nodes, sorted in order of single-thread traversal order. */
199         OperationNodes operations;
200
201         /* Spin lock for threading-critical operations.
202          * Mainly used by graph evaluation. */
203         SpinLock lock;
204
205         /* Scene, layer, mode this dependency graph is built for. */
206         Scene *scene;
207         ViewLayer *view_layer;
208         eEvaluationMode mode;
209
210         /* Time at which dependency graph is being or was last evaluated. */
211         float ctime;
212
213         /* Evaluated version of datablocks we access a lot.
214          * Stored here to save us form doing hash lookup. */
215         Scene *scene_cow;
216
217         /* Active dependency graph is a dependency graph which is used by the
218          * currently active window. When dependency graph is active, it is allowed
219          * for evaluation functions to write animation f-curve result, drivers
220          * result and other selective things (object matrix?) to original object.
221          *
222          * This way we simplify operators, which don't need to worry about where
223          * to read stuff from. */
224         bool is_active;
225
226         /* NOTE: Corresponds to G_DEBUG_DEPSGRAPH_* flags. */
227         int debug_flags;
228         string debug_name;
229
230         bool debug_is_evaluating;
231
232         /* Cached list of colliders/effectors for collections and the scene
233          * created along with relations, for fast lookup during evaluation. */
234         GHash *physics_relations[DEG_PHYSICS_RELATIONS_NUM];
235 };
236
237 }  // namespace DEG