0837f14727565fe0946a28cf2cd25be961f25012
[blender-staging.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 EvaluationContext;
64 struct Main;
65
66 struct PointerRNA;
67 struct PropertyRNA;
68
69 #ifdef __cplusplus
70 extern "C" {
71 #endif
72
73 bool DEG_depsgraph_use_legacy(void);
74 void DEG_depsgraph_switch_to_legacy(void);
75 void DEG_depsgraph_switch_to_new(void);
76
77 /* ************************************************ */
78 /* Depsgraph API */
79
80 /* CRUD ------------------------------------------- */
81
82 // Get main depsgraph instance from context!
83
84 /* Create new Depsgraph instance */
85 // TODO: what args are needed here? What's the building-graph entry point?
86 Depsgraph *DEG_graph_new(void);
87
88 /* Free Depsgraph itself and all its data */
89 void DEG_graph_free(Depsgraph *graph);
90
91 /* Node Types Registry ---------------------------- */
92
93 /* Register all node types */
94 void DEG_register_node_types(void);
95
96 /* Free node type registry on exit */
97 void DEG_free_node_types(void);
98
99 /* Update Tagging -------------------------------- */
100
101 /* Tag node(s) associated with states such as time and visibility */
102 void DEG_scene_update_flags(Depsgraph *graph, const bool do_time);
103
104 /* Update dependency graph when visible scenes/layers changes. */
105 void DEG_graph_on_visible_update(struct Main *bmain, struct Scene *scene);
106
107 /* Update all dependency graphs when visible scenes/layers changes. */
108 void DEG_on_visible_update(struct Main *bmain, const bool do_time);
109
110 /* Tag node(s) associated with changed data for later updates */
111 void DEG_graph_id_tag_update(struct Main *bmain,
112                              Depsgraph *graph,
113                              struct ID *id);
114
115 /* Tag given ID for an update in all the dependency graphs. */
116 void DEG_id_tag_update(struct ID *id, short flag);
117 void DEG_id_tag_update_ex(struct Main *bmain,
118                           struct ID *id,
119                           short flag);
120
121 /* Mark a particular datablock type as having changing. This does
122  * not cause any updates but is used by external render engines to detect if for
123  * example a datablock was removed.
124  */
125 void DEG_id_type_tag(struct Main *bmain, short idtype);
126
127 void DEG_ids_clear_recalc(struct Main *bmain);
128
129 /* Update Flushing ------------------------------- */
130
131 /* Flush updates for all IDs */
132 void DEG_ids_flush_tagged(struct Main *bmain);
133
134 /* Flush updates for IDs in a single scene. */
135 void DEG_scene_flush_update(struct Main *bmain, struct Scene *scene);
136
137 /* Check if something was changed in the database and inform
138  * editors about this.
139  */
140 void DEG_ids_check_recalc(struct Main *bmain,
141                           struct Scene *scene,
142                           bool time);
143
144 /* ************************************************ */
145 /* Evaluation Engine API */
146
147 /* Evaluation Context ---------------------------- */
148
149 /* Create new evaluation context. */
150 struct EvaluationContext *DEG_evaluation_context_new(int mode);
151
152 /* Initialize evaluation context.
153  * Used by the areas which currently overrides the context or doesn't have
154  * access to a proper one.
155  */
156 void DEG_evaluation_context_init(struct EvaluationContext *eval_ctx, int mode);
157
158 /* Free evaluation context. */
159 void DEG_evaluation_context_free(struct EvaluationContext *eval_ctx);
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 EvaluationContext *eval_ctx,
168                                  struct Main *bmain,
169                                  Depsgraph *graph,
170                                  float ctime,
171                                  const unsigned int layer);
172
173 /* Data changed recalculation entry point.
174  * < context_type: context to perform evaluation for
175  * < layers: visible layers bitmask to update the graph for
176  */
177 void DEG_evaluate_on_refresh_ex(struct EvaluationContext *eval_ctx,
178                                 Depsgraph *graph,
179                                 const unsigned int layers);
180
181 /* Data changed recalculation entry point.
182  * < context_type: context to perform evaluation for
183  */
184 void DEG_evaluate_on_refresh(struct EvaluationContext *eval_ctx,
185                              Depsgraph *graph,
186                              struct Scene *scene);
187
188 bool DEG_needs_eval(Depsgraph *graph);
189
190 /* Editors Integration  -------------------------- */
191
192 /* Mechanism to allow editors to be informed of depsgraph updates,
193  * to do their own updates based on changes.
194  */
195
196 typedef void (*DEG_EditorUpdateIDCb)(struct Main *bmain, struct ID *id);
197 typedef void (*DEG_EditorUpdateSceneCb)(struct Main *bmain,
198                                         struct Scene *scene,
199                                         int updated);
200 typedef void (*DEG_EditorUpdateScenePreCb)(struct Main *bmain,
201                                            struct Scene *scene,
202                                            bool time);
203
204 /* Set callbacks which are being called when depsgraph changes. */
205 void DEG_editors_set_update_cb(DEG_EditorUpdateIDCb id_func,
206                                DEG_EditorUpdateSceneCb scene_func,
207                                DEG_EditorUpdateScenePreCb scene_pre_func);
208
209 void DEG_editors_update_pre(struct Main *bmain, struct Scene *scene, bool time);
210
211 #ifdef __cplusplus
212 } /* extern "C" */
213 #endif
214
215 #endif  /* __DEG_DEPSGRAPH_H__ */