Depsgraph: New dependency graph integration commit
[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  * Public API for Depsgraph
27  */
28
29 #ifndef __DEG_DEPSGRAPH_H__
30 #define __DEG_DEPSGRAPH_H__
31
32 /* Dependency Graph
33  *
34  * The dependency graph tracks relations between various pieces of data in
35  * a Blender file, but mainly just those which make up scene data. It is used
36  * to determine the set of operations need to ensure that all data has been
37  * correctly evaluated in response to changes, based on dependencies and visibility
38  * of affected data.
39  *
40  *
41  * Evaluation Engine
42  *
43  * The evaluation takes the operation-nodes the Depsgraph has tagged for updating, 
44  * and schedules them up for being evaluated/executed such that the all dependency
45  * relationship constraints are satisfied. 
46  */
47
48 /* ************************************************* */
49 /* Forward-defined typedefs for core types
50  * - These are used in all depsgraph code and by all callers of Depsgraph API...
51  */
52
53 /* Dependency Graph */
54 typedef struct Depsgraph Depsgraph;
55
56 /* ------------------------------------------------ */
57
58 struct EvaluationContext;
59 struct Main;
60
61 struct PointerRNA;
62 struct PropertyRNA;
63
64 #ifdef __cplusplus
65 extern "C" {
66 #endif
67
68 bool DEG_depsgraph_use_legacy(void);
69 void DEG_depsgraph_switch_to_legacy(void);
70 void DEG_depsgraph_switch_to_new(void);
71
72 /* ************************************************ */
73 /* Depsgraph API */
74
75 /* CRUD ------------------------------------------- */
76
77 // Get main depsgraph instance from context!
78
79 /* Create new Depsgraph instance */
80 // TODO: what args are needed here? What's the building-graph entry point?
81 Depsgraph *DEG_graph_new(void);
82
83 /* Free Depsgraph itself and all its data */
84 void DEG_graph_free(Depsgraph *graph);
85
86 /* Node Types Registry ---------------------------- */
87
88 /* Register all node types */
89 void DEG_register_node_types(void);
90
91 /* Free node type registry on exit */
92 void DEG_free_node_types(void);
93
94 /* Update Tagging -------------------------------- */
95
96 /* Tag node(s) associated with states such as time and visibility */
97 void DEG_scene_update_flags(Depsgraph *graph, const bool do_time);
98
99 /* Update dependency graph when visible scenes/layers changes. */
100 void DEG_graph_on_visible_update(struct Main *bmain, struct Scene *scene);
101
102 /* Update all dependency graphs when visible scenes/layers changes. */
103 void DEG_on_visible_update(struct Main *bmain, const bool do_time);
104
105 /* Tag node(s) associated with changed data for later updates */
106 void DEG_graph_id_tag_update(struct Main *bmain,
107                              Depsgraph *graph,
108                              struct ID *id);
109 void DEG_graph_data_tag_update(Depsgraph *graph, const struct PointerRNA *ptr);
110 void DEG_graph_property_tag_update(Depsgraph *graph, const struct PointerRNA *ptr, const struct PropertyRNA *prop);
111
112 /* Tag given ID for an update in all the dependency graphs. */
113 void DEG_id_tag_update(struct ID *id, short flag);
114 void DEG_id_tag_update_ex(struct Main *bmain,
115                           struct ID *id,
116                           short flag);
117
118 /* Tag given ID type for update.
119  *
120  * Used by all sort of render engines to quickly check if
121  * IDs of a given type need to be checked for update.
122  */
123 void DEG_id_type_tag(struct Main *bmain, short idtype);
124
125 void DEG_ids_clear_recalc(struct Main *bmain);
126
127 /* Update Flushing ------------------------------- */
128
129 /* Flush updates */
130 void DEG_graph_flush_updates(struct Main *bmain, Depsgraph *graph);
131
132 /* Flush updates for all IDs */
133 void DEG_ids_flush_tagged(struct Main *bmain);
134
135 /* Check if something was changed in the database and inform
136  * editors about this.
137  */
138 void DEG_ids_check_recalc(struct Main *bmain,
139                           struct Scene *scene,
140                           bool time);
141
142 /* Clear all update tags
143  * - For aborted updates, or after successful evaluation
144  */
145 void DEG_graph_clear_tags(Depsgraph *graph);
146
147 /* ************************************************ */
148 /* Evaluation Engine API */
149
150 /* Evaluation Context ---------------------------- */
151
152 /* Create new evaluation context. */
153 struct EvaluationContext *DEG_evaluation_context_new(int mode);
154
155 /* Initialize evaluation context.
156  * Used by the areas which currently overrides the context or doesn't have
157  * access to a proper one.
158  */
159 void DEG_evaluation_context_init(struct EvaluationContext *eval_ctx, int mode);
160
161 /* Free evaluation context. */
162 void DEG_evaluation_context_free(struct EvaluationContext *eval_ctx);
163
164 /* Graph Evaluation  ----------------------------- */
165
166 /* Frame changed recalculation entry point
167  * < context_type: context to perform evaluation for
168  * < ctime: (frame) new frame to evaluate values on
169  */
170 void DEG_evaluate_on_framechange(struct EvaluationContext *eval_ctx,
171                                  struct Main *bmain,
172                                  Depsgraph *graph,
173                                  float ctime,
174                                  const int layer);
175
176 /* Data changed recalculation entry point.
177  * < context_type: context to perform evaluation for
178  * < layers: visible layers bitmask to update the graph for
179  */
180 void DEG_evaluate_on_refresh_ex(struct EvaluationContext *eval_ctx,
181                                 Depsgraph *graph,
182                                 const int layers);
183
184 /* Data changed recalculation entry point.
185  * < context_type: context to perform evaluation for
186  */
187 void DEG_evaluate_on_refresh(struct EvaluationContext *eval_ctx,
188                              Depsgraph *graph,
189                              struct Scene *scene);
190
191 /* Editors Integration  -------------------------- */
192
193 /* Mechanism to allow editors to be informed of depsgraph updates,
194  * to do their own updates based on changes.
195  */
196
197 typedef void (*DEG_EditorUpdateIDCb)(struct Main *bmain, struct ID *id);
198 typedef void (*DEG_EditorUpdateSceneCb)(struct Main *bmain,
199                                         struct Scene *scene,
200                                         int updated);
201
202 /* Set callbacks which are being called when depsgraph changes. */
203 void DEG_editors_set_update_cb(DEG_EditorUpdateIDCb id_func,
204                                DEG_EditorUpdateSceneCb scene_func);
205
206 #ifdef __cplusplus
207 } /* extern "C" */
208 #endif
209
210 #endif  /* __DEG_DEPSGRAPH_H__ */