196 lines
6.9 KiB
C++
196 lines
6.9 KiB
C++
/*
|
|
* ***** BEGIN GPL LICENSE BLOCK *****
|
|
*
|
|
* This program is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License
|
|
* as published by the Free Software Foundation; either version 2
|
|
* of the License, or (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
*
|
|
* The Original Code is Copyright (C) 2013 Blender Foundation.
|
|
* All rights reserved.
|
|
*
|
|
* Original Author: Joshua Leung
|
|
* Contributor(s): None Yet
|
|
*
|
|
* ***** END GPL LICENSE BLOCK *****
|
|
*/
|
|
|
|
/** \file blender/depsgraph/DEG_depsgraph_query.h
|
|
* \ingroup depsgraph
|
|
*
|
|
* Public API for Querying and Filtering Depsgraph.
|
|
*/
|
|
|
|
#ifndef __DEG_DEPSGRAPH_QUERY_H__
|
|
#define __DEG_DEPSGRAPH_QUERY_H__
|
|
|
|
struct ListBase;
|
|
struct ID;
|
|
|
|
struct Depsgraph;
|
|
struct DepsNode;
|
|
struct DepsRelation;
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* ************************************************ */
|
|
/* Type Defines */
|
|
|
|
/* FilterPredicate Callback
|
|
*
|
|
* Defines a callback function which can be supplied to check whether a
|
|
* node is relevant or not.
|
|
*
|
|
* < graph: Depsgraph that we're traversing
|
|
* < node: The node to check
|
|
* < userdata: FilterPredicate state data (as needed)
|
|
* > returns: True if node is relevant
|
|
*/
|
|
typedef bool (*DEG_FilterPredicate)(const struct Depsgraph *graph, const struct DepsNode *node, void *userdata);
|
|
|
|
|
|
/* Node Operation
|
|
*
|
|
* Performs some action on the given node, provided that the node was
|
|
* deemed to be relevant to operate on.
|
|
*
|
|
* < graph: Depsgraph that we're traversing
|
|
* < node: The node to perform operation on/with
|
|
* < userdata: Node Operation's state data (as needed)
|
|
* > returns: True if traversal should be aborted at this point
|
|
*/
|
|
typedef bool (*DEG_NodeOperation)(const struct Depsgraph *graph, struct DepsNode *node, void *userdata);
|
|
|
|
/* ************************************************ */
|
|
/* Low-Level Filtering API */
|
|
|
|
/* Create a filtered copy of the given graph which contains only the
|
|
* nodes which fulfill the criteria specified using the FilterPredicate
|
|
* passed in.
|
|
*
|
|
* < graph: The graph to be copied and filtered
|
|
* < filter: FilterPredicate used to check which nodes should be included
|
|
* (If null, full graph is copied as-is)
|
|
* < userdata: State data for filter (as necessary)
|
|
*
|
|
* > returns: a full copy of all the relevant nodes - the matching subgraph
|
|
*/
|
|
// XXX: is there any need for extra settings/options for how the filtering goes?
|
|
Depsgraph *DEG_graph_filter(const struct Depsgraph *graph, DEG_FilterPredicate *filter, void *userdata);
|
|
|
|
|
|
/* Traverse nodes in graph which are deemed relevant,
|
|
* performing the provided operation on the nodes.
|
|
*
|
|
* < graph: The graph to perform operations on
|
|
* < filter: FilterPredicate used to check which nodes should be included
|
|
* (If null, all nodes are considered valid targets)
|
|
* < filter_data: Custom state data for FilterPredicate
|
|
* (Note: This can be the same as op_data, where appropriate)
|
|
* < op: NodeOperation to perform on each node
|
|
* (If null, no graph traversal is performed for efficiency)
|
|
* < op_data: Custom state data for NodeOperation
|
|
* (Note: This can be the same as filter_data, where appropriate)
|
|
*/
|
|
void DEG_graph_traverse(const struct Depsgraph *graph,
|
|
DEG_FilterPredicate *filter, void *filter_data,
|
|
DEG_NodeOperation *op, void *op_data);
|
|
|
|
/* ************************************************ */
|
|
/* Node-Based Operations */
|
|
// XXX: do we want to be able to attach conditional requirements here?
|
|
|
|
/* Find an (outer) node matching given conditions
|
|
* ! Assumes that there will only be one such node, or that only the first one matters
|
|
*
|
|
* < graph: a dependency graph which may or may not contain a node matching these requirements
|
|
* < query: query conditions for the criteria that the node must satisfy
|
|
*/
|
|
//DepsNode *DEG_node_find(const Depsgraph *graph, DEG_QueryConditions *query);
|
|
|
|
/* Topology Queries (Direct) ---------------------- */
|
|
|
|
/* Get list of nodes which directly depend on given node
|
|
*
|
|
* > result: list to write results to
|
|
* < node: the node to find the children/dependents of
|
|
*/
|
|
void DEG_node_get_children(struct ListBase *result, const struct DepsNode *node);
|
|
|
|
|
|
/* Get list of nodes which given node directly depends on
|
|
*
|
|
* > result: list to write results to
|
|
* < node: the node to find the dependencies of
|
|
*/
|
|
void DEG_node_get_dependencies(struct ListBase *result, const struct DepsNode *node);
|
|
|
|
|
|
/* Topology Queries (Subgraph) -------------------- */
|
|
// XXX: given that subgraphs potentially involve many interconnected nodes, we currently
|
|
// just spit out a copy of the subgraph which matches. This works well for the cases
|
|
// where these are used - mostly for efficient updating of subsets of the nodes.
|
|
|
|
// XXX: allow supplying a filter predicate to provide further filtering/pruning?
|
|
|
|
|
|
/* Get all descendants of a node
|
|
*
|
|
* That is, get the subgraph / subset of nodes which are dependent
|
|
* on the results of the given node.
|
|
*/
|
|
Depsgraph *DEG_node_get_descendants(const struct Depsgraph *graph, const struct DepsNode *node);
|
|
|
|
|
|
/* Get all ancestors of a node
|
|
*
|
|
* That is, get the subgraph / subset of nodes which the given node
|
|
* is dependent on in order to be evaluated.
|
|
*/
|
|
Depsgraph *DEG_node_get_ancestors(const struct Depsgraph *graph, const struct DepsNode *node);
|
|
|
|
/* ************************************************ */
|
|
/* Higher-Level Queries */
|
|
|
|
/* Get ID-blocks which would be affected if specified ID is modified
|
|
* < only_direct: True = Only ID-blocks with direct relationships to ID-block will be returned
|
|
*
|
|
* > result: (LinkData : ID) a list of ID-blocks matching the specified criteria
|
|
* > returns: number of matching ID-blocks
|
|
*/
|
|
size_t DEG_query_affected_ids(struct ListBase *result, const struct ID *id, const bool only_direct);
|
|
|
|
|
|
/* Get ID-blocks which are needed to update/evaluate specified ID
|
|
* < only_direct: True = Only ID-blocks with direct relationships to ID-block will be returned
|
|
*
|
|
* > result: (LinkData : ID) a list of ID-blocks matching the specified criteria
|
|
* > returns: number of matching ID-blocks
|
|
*/
|
|
size_t DEG_query_required_ids(struct ListBase *result, const struct ID *id, const bool only_direct);
|
|
|
|
/* ************************************************ */
|
|
|
|
/* Check if given ID type was tagged for update. */
|
|
bool DEG_id_type_tagged(struct Main *bmain, short idtype);
|
|
|
|
/* Get additional evaluation flags for the given ID. */
|
|
short DEG_get_eval_flags_for_id(struct Depsgraph *graph, struct ID *id);
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|
|
|
|
#endif /* __DEG_DEPSGRAPH_QUERY_H__ */
|