doxygen: corrections/updates
[blender.git] / source / blender / depsgraph / DEG_depsgraph_query.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_query.h
28  *  \ingroup depsgraph
29  *
30  * Public API for Querying and Filtering Depsgraph.
31  */
32
33 #ifndef __DEG_DEPSGRAPH_QUERY_H__
34 #define __DEG_DEPSGRAPH_QUERY_H__
35
36 struct ListBase;
37 struct ID;
38
39 struct Depsgraph;
40 struct DepsNode;
41 struct DepsRelation;
42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 /* ************************************************ */
48 /* Type Defines */
49
50 /* FilterPredicate Callback 
51  *
52  * Defines a callback function which can be supplied to check whether a 
53  * node is relevant or not.
54  *
55  * < graph: Depsgraph that we're traversing
56  * < node: The node to check
57  * < userdata: FilterPredicate state data (as needed)
58  * > returns: True if node is relevant
59  */
60 typedef bool (*DEG_FilterPredicate)(const struct Depsgraph *graph, const struct DepsNode *node, void *userdata);
61
62
63 /* Node Operation 
64  *
65  * Performs some action on the given node, provided that the node was
66  * deemed to be relevant to operate on.
67  *
68  * < graph: Depsgraph that we're traversing
69  * < node: The node to perform operation on/with
70  * < userdata: Node Operation's state data (as needed)
71  * > returns: True if traversal should be aborted at this point
72  */
73 typedef bool (*DEG_NodeOperation)(const struct Depsgraph *graph, struct DepsNode *node, void *userdata);
74
75 /* ************************************************ */
76 /* Low-Level Filtering API */
77
78 /* Create a filtered copy of the given graph which contains only the
79  * nodes which fulfill the criteria specified using the FilterPredicate
80  * passed in.
81  *
82  * < graph: The graph to be copied and filtered
83  * < filter: FilterPredicate used to check which nodes should be included
84  *           (If null, full graph is copied as-is)
85  * < userdata: State data for filter (as necessary)
86  *
87  * > returns: a full copy of all the relevant nodes - the matching subgraph
88  */
89 // XXX: is there any need for extra settings/options for how the filtering goes?
90 Depsgraph *DEG_graph_filter(const struct Depsgraph *graph, DEG_FilterPredicate *filter, void *userdata);
91
92
93 /* Traverse nodes in graph which are deemed relevant,
94  * performing the provided operation on the nodes.
95  *
96  * < graph: The graph to perform operations on
97  * < filter: FilterPredicate used to check which nodes should be included
98  *           (If null, all nodes are considered valid targets)
99  * < filter_data: Custom state data for FilterPredicate
100  *                (Note: This can be the same as op_data, where appropriate)
101  * < op: NodeOperation to perform on each node
102  *       (If null, no graph traversal is performed for efficiency)
103  * < op_data: Custom state data for NodeOperation
104  *            (Note: This can be the same as filter_data, where appropriate)
105  */
106 void DEG_graph_traverse(const struct Depsgraph *graph,
107                         DEG_FilterPredicate *filter, void *filter_data,
108                         DEG_NodeOperation *op, void *op_data);
109
110 /* ************************************************ */
111 /* Node-Based Operations */
112 // XXX: do we want to be able to attach conditional requirements here?
113
114 /* Find an (outer) node matching given conditions 
115  * ! Assumes that there will only be one such node, or that only the first one matters
116  *
117  * < graph: a dependency graph which may or may not contain a node matching these requirements
118  * < query: query conditions for the criteria that the node must satisfy 
119  */
120 //DepsNode *DEG_node_find(const Depsgraph *graph, DEG_QueryConditions *query);
121
122 /* Topology Queries (Direct) ---------------------- */
123
124 /* Get list of nodes which directly depend on given node  
125  *
126  * > result: list to write results to
127  * < node: the node to find the children/dependents of
128  */
129 void DEG_node_get_children(struct ListBase *result, const struct DepsNode *node);
130
131
132 /* Get list of nodes which given node directly depends on 
133  *
134  * > result: list to write results to
135  * < node: the node to find the dependencies of
136  */
137 void DEG_node_get_dependencies(struct ListBase *result, const struct DepsNode *node);
138
139
140 /* Topology Queries (Subgraph) -------------------- */
141 // XXX: given that subgraphs potentially involve many interconnected nodes, we currently
142 //      just spit out a copy of the subgraph which matches. This works well for the cases
143 //      where these are used - mostly for efficient updating of subsets of the nodes.
144
145 // XXX: allow supplying a filter predicate to provide further filtering/pruning?
146
147
148 /* Get all descendants of a node
149  *
150  * That is, get the subgraph / subset of nodes which are dependent
151  * on the results of the given node.
152  */
153 Depsgraph *DEG_node_get_descendants(const struct Depsgraph *graph, const struct DepsNode *node);
154
155
156 /* Get all ancestors of a node 
157  *
158  * That is, get the subgraph / subset of nodes which the given node
159  * is dependent on in order to be evaluated.
160  */
161 Depsgraph *DEG_node_get_ancestors(const struct Depsgraph *graph, const struct DepsNode *node);
162
163 /* ************************************************ */
164 /* Higher-Level Queries */
165
166 /* Get ID-blocks which would be affected if specified ID is modified 
167  * < only_direct: True = Only ID-blocks with direct relationships to ID-block will be returned
168  *
169  * > result: (LinkData : ID) a list of ID-blocks matching the specified criteria
170  * > returns: number of matching ID-blocks
171  */
172 size_t DEG_query_affected_ids(struct ListBase *result, const struct ID *id, const bool only_direct);
173
174
175 /* Get ID-blocks which are needed to update/evaluate specified ID 
176  * < only_direct: True = Only ID-blocks with direct relationships to ID-block will be returned
177  *
178  * > result: (LinkData : ID) a list of ID-blocks matching the specified criteria
179  * > returns: number of matching ID-blocks
180  */
181 size_t DEG_query_required_ids(struct ListBase *result, const struct ID *id, const bool only_direct);
182
183 /* ************************************************ */
184
185 /* Check if given ID type was tagged for update. */
186 bool DEG_id_type_tagged(struct Main *bmain, short idtype);
187
188 /* Get additional evaluation flags for the given ID. */
189 short DEG_get_eval_flags_for_id(struct Depsgraph *graph, struct ID *id);
190
191 #ifdef __cplusplus
192 } /* extern "C" */
193 #endif
194
195 #endif  /* __DEG_DEPSGRAPH_QUERY_H__ */