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