Cleanup: remove redundant doxygen \file argument
[blender.git] / source / blender / depsgraph / DEG_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  * Public API for Depsgraph
23  *
24  * Dependency Graph
25  * ================
26  *
27  * The dependency graph tracks relations between various pieces of data in
28  * a Blender file, but mainly just those which make up scene data. It is used
29  * to determine the set of operations need to ensure that all data has been
30  * correctly evaluated in response to changes, based on dependencies and visibility
31  * of affected data.
32  * Evaluation Engine
33  * =================
34  *
35  * The evaluation takes the operation-nodes the Depsgraph has tagged for updating,
36  * and schedules them up for being evaluated/executed such that the all dependency
37  * relationship constraints are satisfied.
38  */
39
40 /* ************************************************* */
41 /* Forward-defined typedefs for core types
42  * - These are used in all depsgraph code and by all callers of Depsgraph API...
43  */
44
45 #ifndef __DEG_DEPSGRAPH_H__
46 #define __DEG_DEPSGRAPH_H__
47
48 #include "DNA_ID.h"
49
50 /* Dependency Graph */
51 typedef struct Depsgraph Depsgraph;
52
53 /* ------------------------------------------------ */
54
55 struct Main;
56
57 struct PointerRNA;
58 struct PropertyRNA;
59 struct RenderEngineType;
60 struct Scene;
61 struct ViewLayer;
62
63 typedef enum eEvaluationMode {
64         DAG_EVAL_VIEWPORT       = 0,    /* evaluate for OpenGL viewport */
65         DAG_EVAL_RENDER         = 1,    /* evaluate for render purposes */
66 } eEvaluationMode;
67
68 /* DagNode->eval_flags */
69 enum {
70         /* Regardless to curve->path animation flag path is to be evaluated anyway,
71          * to meet dependencies with such a things as curve modifier and other guys
72          * who're using curve deform, where_on_path and so. */
73         DAG_EVAL_NEED_CURVE_PATH = (1 << 0),
74         /* A shrinkwrap modifier or constraint targeting this mesh needs information
75          * about non-manifold boundary edges for the Target Normal Project mode. */
76         DAG_EVAL_NEED_SHRINKWRAP_BOUNDARY = (1 << 1),
77 };
78
79 #ifdef __cplusplus
80 extern "C" {
81 #endif
82
83 /* ************************************************ */
84 /* Depsgraph API */
85
86 /* CRUD ------------------------------------------- */
87
88 // Get main depsgraph instance from context!
89
90 /* Create new Depsgraph instance */
91 // TODO: what args are needed here? What's the building-graph entry point?
92 Depsgraph *DEG_graph_new(struct Scene *scene,
93                          struct ViewLayer *view_layer,
94                          eEvaluationMode mode);
95
96 /* Free Depsgraph itself and all its data */
97 void DEG_graph_free(Depsgraph *graph);
98
99 /* Node Types Registry ---------------------------- */
100
101 /* Register all node types */
102 void DEG_register_node_types(void);
103
104 /* Free node type registry on exit */
105 void DEG_free_node_types(void);
106
107 /* Update Tagging -------------------------------- */
108
109 /* Update dependency graph when visible scenes/layers changes. */
110 void DEG_graph_on_visible_update(struct Main *bmain, Depsgraph *depsgraph);
111
112 /* Update all dependency graphs when visible scenes/layers changes. */
113 void DEG_on_visible_update(struct Main *bmain, const bool do_time);
114
115 const char *DEG_update_tag_as_string(IDRecalcFlag flag);
116
117 void DEG_id_tag_update(struct ID *id, int flag);
118 void DEG_id_tag_update_ex(struct Main *bmain, struct ID *id, int flag);
119
120 void DEG_graph_id_tag_update(struct Main *bmain,
121                              struct Depsgraph *depsgraph,
122                              struct ID *id,
123                              int flag);
124
125 /* Mark a particular datablock type as having changing. This does
126  * not cause any updates but is used by external render engines to detect if for
127  * example a datablock was removed. */
128 void DEG_id_type_tag(struct Main *bmain, short id_type);
129
130 void DEG_ids_clear_recalc(struct Main *bmain, Depsgraph *depsgraph);
131
132 /* Update Flushing ------------------------------- */
133
134 /* Flush updates for IDs in a single scene. */
135 void DEG_graph_flush_update(struct Main *bmain, Depsgraph *depsgraph);
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 Depsgraph *depsgraph,
142                           struct Scene *scene,
143                           struct ViewLayer *view_layer,
144                           bool time);
145
146 /* ************************************************ */
147 /* Evaluation Engine API */
148
149 /* Graph Evaluation  ----------------------------- */
150
151 /* Frame changed recalculation entry point
152  * < context_type: context to perform evaluation for
153  * < ctime: (frame) new frame to evaluate values on
154  */
155 void DEG_evaluate_on_framechange(struct Main *bmain,
156                                  Depsgraph *graph,
157                                  float ctime);
158
159 /* Data changed recalculation entry point.
160  * < context_type: context to perform evaluation for
161  */
162 void DEG_evaluate_on_refresh(Depsgraph *graph);
163
164 bool DEG_needs_eval(Depsgraph *graph);
165
166 /* Editors Integration  -------------------------- */
167
168 /* Mechanism to allow editors to be informed of depsgraph updates,
169  * to do their own updates based on changes.
170  */
171
172 typedef struct DEGEditorUpdateContext {
173         struct Main *bmain;
174         struct Depsgraph *depsgraph;
175         struct Scene *scene;
176         struct ViewLayer *view_layer;
177 } DEGEditorUpdateContext;
178
179 typedef void (*DEG_EditorUpdateIDCb)(
180         const DEGEditorUpdateContext *update_ctx,
181         struct ID *id);
182 typedef void (*DEG_EditorUpdateSceneCb)(
183         const DEGEditorUpdateContext *update_ctx, int updated);
184
185 /* Set callbacks which are being called when depsgraph changes. */
186 void DEG_editors_set_update_cb(DEG_EditorUpdateIDCb id_func,
187                                DEG_EditorUpdateSceneCb scene_func);
188
189 /* Evaluation  ----------------------------------- */
190
191 bool DEG_is_active(const struct Depsgraph *depsgraph);
192 void DEG_make_active(struct Depsgraph *depsgraph);
193 void DEG_make_inactive(struct Depsgraph *depsgraph);
194
195 /* Evaluation Debug ------------------------------ */
196
197 bool DEG_debug_is_evaluating(struct Depsgraph *depsgraph);
198
199 void DEG_debug_print_begin(struct Depsgraph *depsgraph);
200
201 void DEG_debug_print_eval(struct Depsgraph *depsgraph,
202                           const char *function_name,
203                           const char *object_name,
204                           const void *object_address);
205
206 void DEG_debug_print_eval_subdata(struct Depsgraph *depsgraph,
207                                   const char *function_name,
208                                   const char *object_name,
209                                   const void *object_address,
210                                   const char *subdata_comment,
211                                   const char *subdata_name,
212                                   const void *subdata_address);
213
214 void DEG_debug_print_eval_subdata_index(struct Depsgraph *depsgraph,
215                                         const char *function_name,
216                                         const char *object_name,
217                                         const void *object_address,
218                                         const char *subdata_comment,
219                                         const char *subdata_name,
220                                         const void *subdata_address,
221                                         const int subdata_index);
222
223 void DEG_debug_print_eval_parent_typed(struct Depsgraph *depsgraph,
224                                        const char *function_name,
225                                        const char *object_name,
226                                        const void *object_address,
227                                        const char *parent_comment,
228                                        const char *parent_name,
229                                        const void *parent_address);
230
231 void DEG_debug_print_eval_time(struct Depsgraph *depsgraph,
232                                const char *function_name,
233                                const char *object_name,
234                                const void *object_address,
235                                float time);
236
237 #ifdef __cplusplus
238 } /* extern "C" */
239 #endif
240
241 #endif  /* __DEG_DEPSGRAPH_H__ */