Merge branch 'master' into blender2.8
[blender.git] / source / blender / depsgraph / DEG_depsgraph.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * The Original Code is Copyright (C) 2013 Blender Foundation.
19  * All rights reserved.
20  *
21  * Original Author: Joshua Leung
22  * Contributor(s): None Yet
23  *
24  * ***** END GPL LICENSE BLOCK *****
25  */
26
27 /** \file blender/depsgraph/DEG_depsgraph.h
28  *  \ingroup depsgraph
29  *
30  * Public API for Depsgraph
31  *
32  * Dependency Graph
33  * ================
34  *
35  * The dependency graph tracks relations between various pieces of data in
36  * a Blender file, but mainly just those which make up scene data. It is used
37  * to determine the set of operations need to ensure that all data has been
38  * correctly evaluated in response to changes, based on dependencies and visibility
39  * of affected data.
40  *
41  *
42  * Evaluation Engine
43  * =================
44  *
45  * The evaluation takes the operation-nodes the Depsgraph has tagged for updating,
46  * and schedules them up for being evaluated/executed such that the all dependency
47  * relationship constraints are satisfied.
48  */
49
50 /* ************************************************* */
51 /* Forward-defined typedefs for core types
52  * - These are used in all depsgraph code and by all callers of Depsgraph API...
53  */
54
55 #ifndef __DEG_DEPSGRAPH_H__
56 #define __DEG_DEPSGRAPH_H__
57
58 /* Dependency Graph */
59 typedef struct Depsgraph Depsgraph;
60
61 /* ------------------------------------------------ */
62
63 struct Main;
64
65 struct PointerRNA;
66 struct PropertyRNA;
67 struct RenderEngineType;
68 struct Scene;
69 struct ViewLayer;
70
71 typedef enum eEvaluationMode {
72         DAG_EVAL_VIEWPORT       = 0,    /* evaluate for OpenGL viewport */
73         DAG_EVAL_RENDER         = 1,    /* evaluate for render purposes */
74 } eEvaluationMode;
75
76 /* DagNode->eval_flags */
77 enum {
78         /* Regardless to curve->path animation flag path is to be evaluated anyway,
79          * to meet dependencies with such a things as curve modifier and other guys
80          * who're using curve deform, where_on_path and so.
81          */
82         DAG_EVAL_NEED_CURVE_PATH = (1 << 0),
83         /* A shrinkwrap modifier or constraint targeting this mesh needs information
84          * about non-manifold boundary edges for the Target Normal Project mode.
85          */
86         DAG_EVAL_NEED_SHRINKWRAP_BOUNDARY = (1 << 1),
87 };
88
89 #ifdef __cplusplus
90 extern "C" {
91 #endif
92
93 /* ************************************************ */
94 /* Depsgraph API */
95
96 /* CRUD ------------------------------------------- */
97
98 // Get main depsgraph instance from context!
99
100 /* Create new Depsgraph instance */
101 // TODO: what args are needed here? What's the building-graph entry point?
102 Depsgraph *DEG_graph_new(struct Scene *scene,
103                          struct ViewLayer *view_layer,
104                          eEvaluationMode mode);
105
106 /* Free Depsgraph itself and all its data */
107 void DEG_graph_free(Depsgraph *graph);
108
109 /* Node Types Registry ---------------------------- */
110
111 /* Register all node types */
112 void DEG_register_node_types(void);
113
114 /* Free node type registry on exit */
115 void DEG_free_node_types(void);
116
117 /* Update Tagging -------------------------------- */
118
119 /* Update dependency graph when visible scenes/layers changes. */
120 void DEG_graph_on_visible_update(struct Main *bmain, Depsgraph *depsgraph);
121
122 /* Update all dependency graphs when visible scenes/layers changes. */
123 void DEG_on_visible_update(struct Main *bmain, const bool do_time);
124
125 /* Tag given ID for an update in all the dependency graphs. */
126 typedef enum eDepsgraph_Tag {
127         /* Object transformation changed, corresponds to OB_RECALC_OB. */
128         DEG_TAG_TRANSFORM   = (1 << 0),
129         /* Object geometry changed, corresponds to OB_RECALC_DATA. */
130         DEG_TAG_GEOMETRY    = (1 << 1),
131         /* Time changed and animation is to be re-evaluated, OB_RECALC_TIME. */
132         DEG_TAG_TIME        = (1 << 2),
133         /* Particle system changed; values are aligned with PSYS_RECALC_xxx. */
134         DEG_TAG_PSYS_REDO   = (1 << 3),
135         DEG_TAG_PSYS_RESET  = (1 << 4),
136         DEG_TAG_PSYS_TYPE   = (1 << 5),
137         DEG_TAG_PSYS_CHILD  = (1 << 6),
138         DEG_TAG_PSYS_PHYS   = (1 << 7),
139         DEG_TAG_PSYS_ALL    = (DEG_TAG_PSYS_REDO |
140                                DEG_TAG_PSYS_RESET |
141                                DEG_TAG_PSYS_TYPE |
142                                DEG_TAG_PSYS_CHILD |
143                                DEG_TAG_PSYS_PHYS),
144         /* Update copy on write component without flushing down the road. */
145         DEG_TAG_COPY_ON_WRITE = (1 << 8),
146         /* Tag shading components for update.
147          * Only parameters of material changed).
148          */
149         DEG_TAG_SHADING_UPDATE       = (1 << 9),
150         DEG_TAG_SELECT_UPDATE        = (1 << 10),
151         DEG_TAG_BASE_FLAGS_UPDATE    = (1 << 11),
152         DEG_TAG_POINT_CACHE_UPDATE   = (1 << 12),
153         /* Only inform editors about the change. Don't modify datablock itself. */
154         DEG_TAG_EDITORS_UPDATE = (1 << 13),
155 } eDepsgraph_Tag;
156
157 const char *DEG_update_tag_as_string(eDepsgraph_Tag flag);
158
159 void DEG_id_tag_update(struct ID *id, int flag);
160 void DEG_id_tag_update_ex(struct Main *bmain, struct ID *id, int flag);
161
162 void DEG_graph_id_tag_update(struct Main *bmain,
163                              struct Depsgraph *depsgraph,
164                              struct ID *id,
165                              int flag);
166
167 /* Mark a particular datablock type as having changing. This does
168  * not cause any updates but is used by external render engines to detect if for
169  * example a datablock was removed.
170  */
171 void DEG_id_type_tag(struct Main *bmain, short id_type);
172
173 void DEG_ids_clear_recalc(struct Main *bmain, Depsgraph *depsgraph);
174
175 /* Update Flushing ------------------------------- */
176
177 /* Flush updates for IDs in a single scene. */
178 void DEG_graph_flush_update(struct Main *bmain, Depsgraph *depsgraph);
179
180 /* Check if something was changed in the database and inform
181  * editors about this.
182  */
183 void DEG_ids_check_recalc(struct Main *bmain,
184                           struct Depsgraph *depsgraph,
185                           struct Scene *scene,
186                           struct ViewLayer *view_layer,
187                           bool time);
188
189 /* ************************************************ */
190 /* Evaluation Engine API */
191
192 /* Graph Evaluation  ----------------------------- */
193
194 /* Frame changed recalculation entry point
195  * < context_type: context to perform evaluation for
196  * < ctime: (frame) new frame to evaluate values on
197  */
198 void DEG_evaluate_on_framechange(struct Main *bmain,
199                                  Depsgraph *graph,
200                                  float ctime);
201
202 /* Data changed recalculation entry point.
203  * < context_type: context to perform evaluation for
204  */
205 void DEG_evaluate_on_refresh(Depsgraph *graph);
206
207 bool DEG_needs_eval(Depsgraph *graph);
208
209 /* Editors Integration  -------------------------- */
210
211 /* Mechanism to allow editors to be informed of depsgraph updates,
212  * to do their own updates based on changes.
213  */
214
215 typedef struct DEGEditorUpdateContext {
216         struct Main *bmain;
217         struct Depsgraph *depsgraph;
218         struct Scene *scene;
219         struct ViewLayer *view_layer;
220 } DEGEditorUpdateContext;
221
222 typedef void (*DEG_EditorUpdateIDCb)(
223         const DEGEditorUpdateContext *update_ctx,
224         struct ID *id);
225 typedef void (*DEG_EditorUpdateSceneCb)(
226         const DEGEditorUpdateContext *update_ctx, int updated);
227
228 /* Set callbacks which are being called when depsgraph changes. */
229 void DEG_editors_set_update_cb(DEG_EditorUpdateIDCb id_func,
230                                DEG_EditorUpdateSceneCb scene_func);
231
232 /* Evaluation  ----------------------------------- */
233
234 bool DEG_is_active(const struct Depsgraph *depsgraph);
235 void DEG_make_active(struct Depsgraph *depsgraph);
236 void DEG_make_inactive(struct Depsgraph *depsgraph);
237
238 /* Evaluation Debug ------------------------------ */
239
240 bool DEG_debug_is_evaluating(struct Depsgraph *depsgraph);
241
242 void DEG_debug_print_begin(struct Depsgraph *depsgraph);
243
244 void DEG_debug_print_eval(struct Depsgraph *depsgraph,
245                           const char *function_name,
246                           const char *object_name,
247                           const void *object_address);
248
249 void DEG_debug_print_eval_subdata(struct Depsgraph *depsgraph,
250                                   const char *function_name,
251                                   const char *object_name,
252                                   const void *object_address,
253                                   const char *subdata_comment,
254                                   const char *subdata_name,
255                                   const void *subdata_address);
256
257 void DEG_debug_print_eval_subdata_index(struct Depsgraph *depsgraph,
258                                         const char *function_name,
259                                         const char *object_name,
260                                         const void *object_address,
261                                         const char *subdata_comment,
262                                         const char *subdata_name,
263                                         const void *subdata_address,
264                                         const int subdata_index);
265
266 void DEG_debug_print_eval_parent_typed(struct Depsgraph *depsgraph,
267                                        const char *function_name,
268                                        const char *object_name,
269                                        const void *object_address,
270                                        const char *parent_comment,
271                                        const char *parent_name,
272                                        const void *parent_address);
273
274 void DEG_debug_print_eval_time(struct Depsgraph *depsgraph,
275                                const char *function_name,
276                                const char *object_name,
277                                const void *object_address,
278                                float time);
279
280 #ifdef __cplusplus
281 } /* extern "C" */
282 #endif
283
284 #endif  /* __DEG_DEPSGRAPH_H__ */