410f555406984a89e272d6c553e5ff337c67ab8a
[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 #include "DNA_ID.h"
59
60 /* Dependency Graph */
61 typedef struct Depsgraph Depsgraph;
62
63 /* ------------------------------------------------ */
64
65 struct Main;
66
67 struct PointerRNA;
68 struct PropertyRNA;
69 struct RenderEngineType;
70 struct Scene;
71 struct ViewLayer;
72
73 typedef enum eEvaluationMode {
74         DAG_EVAL_VIEWPORT       = 0,    /* evaluate for OpenGL viewport */
75         DAG_EVAL_RENDER         = 1,    /* evaluate for render purposes */
76 } eEvaluationMode;
77
78 /* DagNode->eval_flags */
79 enum {
80         /* Regardless to curve->path animation flag path is to be evaluated anyway,
81          * to meet dependencies with such a things as curve modifier and other guys
82          * who're using curve deform, where_on_path and so.
83          */
84         DAG_EVAL_NEED_CURVE_PATH = (1 << 0),
85         /* A shrinkwrap modifier or constraint targeting this mesh needs information
86          * about non-manifold boundary edges for the Target Normal Project mode.
87          */
88         DAG_EVAL_NEED_SHRINKWRAP_BOUNDARY = (1 << 1),
89 };
90
91 #ifdef __cplusplus
92 extern "C" {
93 #endif
94
95 /* ************************************************ */
96 /* Depsgraph API */
97
98 /* CRUD ------------------------------------------- */
99
100 // Get main depsgraph instance from context!
101
102 /* Create new Depsgraph instance */
103 // TODO: what args are needed here? What's the building-graph entry point?
104 Depsgraph *DEG_graph_new(struct Scene *scene,
105                          struct ViewLayer *view_layer,
106                          eEvaluationMode mode);
107
108 /* Free Depsgraph itself and all its data */
109 void DEG_graph_free(Depsgraph *graph);
110
111 /* Node Types Registry ---------------------------- */
112
113 /* Register all node types */
114 void DEG_register_node_types(void);
115
116 /* Free node type registry on exit */
117 void DEG_free_node_types(void);
118
119 /* Update Tagging -------------------------------- */
120
121 /* Update dependency graph when visible scenes/layers changes. */
122 void DEG_graph_on_visible_update(struct Main *bmain, Depsgraph *depsgraph);
123
124 /* Update all dependency graphs when visible scenes/layers changes. */
125 void DEG_on_visible_update(struct Main *bmain, const bool do_time);
126
127 const char *DEG_update_tag_as_string(IDRecalcFlag flag);
128
129 void DEG_id_tag_update(struct ID *id, int flag);
130 void DEG_id_tag_update_ex(struct Main *bmain, struct ID *id, int flag);
131
132 void DEG_graph_id_tag_update(struct Main *bmain,
133                              struct Depsgraph *depsgraph,
134                              struct ID *id,
135                              int flag);
136
137 /* Mark a particular datablock type as having changing. This does
138  * not cause any updates but is used by external render engines to detect if for
139  * example a datablock was removed. */
140 void DEG_id_type_tag(struct Main *bmain, short id_type);
141
142 void DEG_ids_clear_recalc(struct Main *bmain, Depsgraph *depsgraph);
143
144 /* Update Flushing ------------------------------- */
145
146 /* Flush updates for IDs in a single scene. */
147 void DEG_graph_flush_update(struct Main *bmain, Depsgraph *depsgraph);
148
149 /* Check if something was changed in the database and inform
150  * editors about this.
151  */
152 void DEG_ids_check_recalc(struct Main *bmain,
153                           struct Depsgraph *depsgraph,
154                           struct Scene *scene,
155                           struct ViewLayer *view_layer,
156                           bool time);
157
158 /* ************************************************ */
159 /* Evaluation Engine API */
160
161 /* Graph Evaluation  ----------------------------- */
162
163 /* Frame changed recalculation entry point
164  * < context_type: context to perform evaluation for
165  * < ctime: (frame) new frame to evaluate values on
166  */
167 void DEG_evaluate_on_framechange(struct Main *bmain,
168                                  Depsgraph *graph,
169                                  float ctime);
170
171 /* Data changed recalculation entry point.
172  * < context_type: context to perform evaluation for
173  */
174 void DEG_evaluate_on_refresh(Depsgraph *graph);
175
176 bool DEG_needs_eval(Depsgraph *graph);
177
178 /* Editors Integration  -------------------------- */
179
180 /* Mechanism to allow editors to be informed of depsgraph updates,
181  * to do their own updates based on changes.
182  */
183
184 typedef struct DEGEditorUpdateContext {
185         struct Main *bmain;
186         struct Depsgraph *depsgraph;
187         struct Scene *scene;
188         struct ViewLayer *view_layer;
189 } DEGEditorUpdateContext;
190
191 typedef void (*DEG_EditorUpdateIDCb)(
192         const DEGEditorUpdateContext *update_ctx,
193         struct ID *id);
194 typedef void (*DEG_EditorUpdateSceneCb)(
195         const DEGEditorUpdateContext *update_ctx, int updated);
196
197 /* Set callbacks which are being called when depsgraph changes. */
198 void DEG_editors_set_update_cb(DEG_EditorUpdateIDCb id_func,
199                                DEG_EditorUpdateSceneCb scene_func);
200
201 /* Evaluation  ----------------------------------- */
202
203 bool DEG_is_active(const struct Depsgraph *depsgraph);
204 void DEG_make_active(struct Depsgraph *depsgraph);
205 void DEG_make_inactive(struct Depsgraph *depsgraph);
206
207 /* Evaluation Debug ------------------------------ */
208
209 bool DEG_debug_is_evaluating(struct Depsgraph *depsgraph);
210
211 void DEG_debug_print_begin(struct Depsgraph *depsgraph);
212
213 void DEG_debug_print_eval(struct Depsgraph *depsgraph,
214                           const char *function_name,
215                           const char *object_name,
216                           const void *object_address);
217
218 void DEG_debug_print_eval_subdata(struct Depsgraph *depsgraph,
219                                   const char *function_name,
220                                   const char *object_name,
221                                   const void *object_address,
222                                   const char *subdata_comment,
223                                   const char *subdata_name,
224                                   const void *subdata_address);
225
226 void DEG_debug_print_eval_subdata_index(struct Depsgraph *depsgraph,
227                                         const char *function_name,
228                                         const char *object_name,
229                                         const void *object_address,
230                                         const char *subdata_comment,
231                                         const char *subdata_name,
232                                         const void *subdata_address,
233                                         const int subdata_index);
234
235 void DEG_debug_print_eval_parent_typed(struct Depsgraph *depsgraph,
236                                        const char *function_name,
237                                        const char *object_name,
238                                        const void *object_address,
239                                        const char *parent_comment,
240                                        const char *parent_name,
241                                        const void *parent_address);
242
243 void DEG_debug_print_eval_time(struct Depsgraph *depsgraph,
244                                const char *function_name,
245                                const char *object_name,
246                                const void *object_address,
247                                float time);
248
249 #ifdef __cplusplus
250 } /* extern "C" */
251 #endif
252
253 #endif  /* __DEG_DEPSGRAPH_H__ */