diff options
Diffstat (limited to 'source/blender/blenkernel/BKE_node.h')
-rw-r--r-- | source/blender/blenkernel/BKE_node.h | 199 |
1 files changed, 187 insertions, 12 deletions
diff --git a/source/blender/blenkernel/BKE_node.h b/source/blender/blenkernel/BKE_node.h index f925834beac..57eab4f76cf 100644 --- a/source/blender/blenkernel/BKE_node.h +++ b/source/blender/blenkernel/BKE_node.h @@ -436,20 +436,44 @@ struct GHashIterator *ntreeTypeGetIterator(void); } \ (void)0 +/** + * Try to initialize all type-info in a node tree. + * + * \note In general undefined type-info is a perfectly valid case, + * the type may just be registered later. + * In that case the update_typeinfo function will set type-info on registration + * and do necessary updates. + */ void ntreeSetTypes(const struct bContext *C, struct bNodeTree *ntree); struct bNodeTree *ntreeAddTree(struct Main *bmain, const char *name, const char *idname); /* copy/free funcs, need to manage ID users */ + +/** + * Free (or release) any data used by this node-tree. + * Does not free the node-tree itself and does no ID user counting. + */ void ntreeFreeTree(struct bNodeTree *ntree); -/* Free tree which is embedded into another datablock. */ +/** + * Free tree which is embedded into another data-block. + */ void ntreeFreeEmbeddedTree(struct bNodeTree *ntree); struct bNodeTree *ntreeCopyTree_ex(const struct bNodeTree *ntree, struct Main *bmain, const bool do_id_user); struct bNodeTree *ntreeCopyTree(struct Main *bmain, const struct bNodeTree *ntree); +/** + * Get address of potential node-tree pointer of given ID. + * + * \warning Using this function directly is potentially dangerous, if you don't know or are not + * sure, please use `ntreeFromID()` instead. + */ struct bNodeTree **BKE_ntree_ptr_from_id(struct ID *id); +/** + * Returns the private NodeTree object of the data-block, if it has one. + */ struct bNodeTree *ntreeFromID(struct ID *id); void ntreeFreeLocalNode(struct bNodeTree *ntree, struct bNode *node); @@ -459,13 +483,17 @@ bool ntreeHasType(const struct bNodeTree *ntree, int type); bool ntreeHasTree(const struct bNodeTree *ntree, const struct bNodeTree *lookup); void ntreeUpdateTree(struct Main *main, struct bNodeTree *ntree); void ntreeUpdateAllNew(struct Main *main); +/** + * \param tree_update_flag: #eNodeTreeUpdate enum. + */ void ntreeUpdateAllUsers(struct Main *main, struct ID *id, int tree_update_flag); void ntreeGetDependencyList(struct bNodeTree *ntree, struct bNode ***r_deplist, int *r_deplist_len); -/* XXX old trees handle output flags automatically based on special output +/** + * XXX: old trees handle output flags automatically based on special output * node types and last active selection. * New tree types have a per-output socket flag to indicate the final output to use explicitly. */ @@ -476,11 +504,31 @@ void ntreeFreeCache(struct bNodeTree *ntree); bool ntreeNodeExists(const struct bNodeTree *ntree, const struct bNode *testnode); bool ntreeOutputExists(const struct bNode *node, const struct bNodeSocket *testsock); void ntreeNodeFlagSet(const bNodeTree *ntree, const int flag, const bool enable); +/** + * Returns localized tree for execution in threads. + */ struct bNodeTree *ntreeLocalize(struct bNodeTree *ntree); +/** + * Sync local composite with real tree. + * The local tree is supposed to be running, be careful moving previews! + * + * Is called by jobs manager, outside threads, so it doesn't happen during draw. + */ void ntreeLocalSync(struct bNodeTree *localtree, struct bNodeTree *ntree); +/** + * Merge local tree results back, and free local tree. + * + * We have to assume the editor already changed completely. + */ void ntreeLocalMerge(struct Main *bmain, struct bNodeTree *localtree, struct bNodeTree *ntree); +/** + * This is only direct data, tree itself should have been written. + */ void ntreeBlendWrite(struct BlendWriter *writer, struct bNodeTree *ntree); +/** + * \note `ntree` itself has been read! + */ void ntreeBlendReadData(struct BlendDataReader *reader, struct bNodeTree *ntree); void ntreeBlendReadLib(struct BlendLibReader *reader, struct bNodeTree *ntree); void ntreeBlendReadExpand(struct BlendExpander *expander, struct bNodeTree *ntree); @@ -614,27 +662,42 @@ void nodeModifySocketTypeStatic( struct bNode *nodeAddNode(const struct bContext *C, struct bNodeTree *ntree, const char *idname); struct bNode *nodeAddStaticNode(const struct bContext *C, struct bNodeTree *ntree, int type); +/** + * \note Goes over entire tree. + */ void nodeUnlinkNode(struct bNodeTree *ntree, struct bNode *node); +/** + * Find the first available, non-duplicate name for a given node. + */ void nodeUniqueName(struct bNodeTree *ntree, struct bNode *node); -/* Delete node, associated animation data and ID user count. */ +/** + * Delete node, associated animation data and ID user count. + */ void nodeRemoveNode(struct Main *bmain, struct bNodeTree *ntree, struct bNode *node, bool do_id_user); +/** + * \param ntree: is the target tree. + * + * \note keep socket list order identical, for copying links. + * \note `unique_name` needs to be true. It's only disabled for speed when doing GPUnodetrees. + */ struct bNode *BKE_node_copy_ex(struct bNodeTree *ntree, const struct bNode *node_src, const int flag, const bool unique_name); -/* Same as BKE_node_copy_ex() but stores pointers to a new node and its sockets in the source - * node. +/** + * Same as #BKE_node_copy_ex but stores pointers to a new node and its sockets in the source node. * * NOTE: DANGER ZONE! * * TODO(sergey): Maybe it's better to make BKE_node_copy_ex() return a mapping from old node and - * sockets to new one. */ + * sockets to new one. + */ struct bNode *BKE_node_copy_store_new_pointers(struct bNodeTree *ntree, struct bNode *node_src, const int flag); @@ -642,6 +705,9 @@ struct bNodeTree *ntreeCopyTree_ex_new_pointers(const struct bNodeTree *ntree, struct Main *bmain, const bool do_id_user); +/** + * Also used via RNA API, so we check for proper input output direction. + */ struct bNodeLink *nodeAddLink(struct bNodeTree *ntree, struct bNode *fromnode, struct bNodeSocket *fromsock, @@ -665,25 +731,62 @@ void nodePositionRelative(struct bNode *from_node, struct bNodeSocket *to_sock); void nodePositionPropagate(struct bNode *node); +/** + * Finds a node based on its name. + */ struct bNode *nodeFindNodebyName(struct bNodeTree *ntree, const char *name); +/** + * Finds a node based on given socket and returns true on success. + */ bool nodeFindNode(struct bNodeTree *ntree, struct bNodeSocket *sock, struct bNode **r_node, int *r_sockindex); +/** + * \note Recursive. + */ struct bNode *nodeFindRootParent(bNode *node); +/** + * \returns true if \a child has \a parent as a parent/grandparent/... etc. + * \note Recursive + */ bool nodeIsChildOf(const bNode *parent, const bNode *child); +/** + * Iterate over a chain of nodes, starting with \a node_start, executing + * \a callback for each node (which can return false to end iterator). + * + * \param reversed: for backwards iteration + * \note Recursive + */ void nodeChainIter(const bNodeTree *ntree, const bNode *node_start, bool (*callback)(bNode *, bNode *, void *, const bool), void *userdata, const bool reversed); +/** + * Iterate over a chain of nodes, starting with \a node_start, executing + * \a callback for each node (which can return false to end iterator). + * + * Faster than nodeChainIter. Iter only once per node. + * Can be called recursively (using another nodeChainIterBackwards) by + * setting the recursion_lvl accordingly. + * + * \note Needs updated socket links (ntreeUpdateTree). + * \note Recursive + */ void nodeChainIterBackwards(const bNodeTree *ntree, const bNode *node_start, bool (*callback)(bNode *, bNode *, void *), void *userdata, int recursion_lvl); +/** + * Iterate over all parents of \a node, executing \a callback for each parent + * (which can return false to end iterator) + * + * \note Recursive + */ void nodeParentsIter(bNode *node, bool (*callback)(bNode *, void *), void *userdata); struct bNodeLink *nodeFindLink(struct bNodeTree *ntree, @@ -692,11 +795,20 @@ struct bNodeLink *nodeFindLink(struct bNodeTree *ntree, int nodeCountSocketLinks(const struct bNodeTree *ntree, const struct bNodeSocket *sock); void nodeSetSelected(struct bNode *node, bool select); +/** + * Two active flags, ID nodes have special flag for buttons display. + */ void nodeSetActive(struct bNodeTree *ntree, struct bNode *node); struct bNode *nodeGetActive(struct bNodeTree *ntree); +/** + * Two active flags, ID nodes have special flag for buttons display. + */ struct bNode *nodeGetActiveID(struct bNodeTree *ntree, short idtype); bool nodeSetActiveID(struct bNodeTree *ntree, short idtype, struct ID *id); void nodeClearActive(struct bNodeTree *ntree); +/** + * Two active flags, ID nodes have special flag for buttons display. + */ void nodeClearActiveID(struct bNodeTree *ntree, short idtype); struct bNode *nodeGetActiveTexture(struct bNodeTree *ntree); @@ -712,14 +824,31 @@ void nodeSetSocketAvailability(struct bNodeTree *ntree, int nodeSocketLinkLimit(const struct bNodeSocket *sock); +/** + * If the node implements a `declare` function, this function makes sure that `node->declaration` + * is up to date. It is expected that the sockets of the node are up to date already. + */ bool nodeDeclarationEnsure(struct bNodeTree *ntree, struct bNode *node); +/** + * Just update `node->declaration` if necessary. This can also be called on nodes that may not be + * up to date (e.g. because the need versioning or are dynamic). + */ bool nodeDeclarationEnsureOnOutdatedNode(struct bNodeTree *ntree, struct bNode *node); +/** + * Update `socket->declaration` for all sockets in the node. This assumes that the node declaration + * and sockets are up to date already. + */ void nodeSocketDeclarationsUpdate(struct bNode *node); -/* Node Clipboard */ +/** + * Node Clipboard. + */ void BKE_node_clipboard_init(const struct bNodeTree *ntree); void BKE_node_clipboard_clear(void); void BKE_node_clipboard_free(void); +/** + * Return false when one or more ID's are lost. + */ bool BKE_node_clipboard_validate(void); void BKE_node_clipboard_add_node(struct bNode *node); void BKE_node_clipboard_add_link(struct bNodeLink *link); @@ -727,7 +856,9 @@ const struct ListBase *BKE_node_clipboard_get_nodes(void); const struct ListBase *BKE_node_clipboard_get_links(void); int BKE_node_clipboard_get_type(void); -/* Node Instance Hash */ +/** + * Node Instance Hash. + */ typedef struct bNodeInstanceHash { /** XXX should be made a direct member, #GHash allocation needs to support it */ GHash *ghash; @@ -735,6 +866,9 @@ typedef struct bNodeInstanceHash { typedef void (*bNodeInstanceValueFP)(void *value); +/** + * Magic number for initial hash key. + */ extern const bNodeInstanceKey NODE_INSTANCE_KEY_BASE; extern const bNodeInstanceKey NODE_INSTANCE_KEY_NONE; @@ -819,6 +953,11 @@ void BKE_node_preview_merge_tree(struct bNodeTree *to_ntree, struct bNodeTree *from_ntree, bool remove_old); +/** + * Hack warning! this function is only used for shader previews, + * and since it gets called multiple times per pixel for Z-transparency we only add the color once. + * Preview gets cleared before it starts render though. + */ void BKE_node_preview_set_pixel( struct bNodePreview *preview, const float col[4], int x, int y, bool do_manage); @@ -829,13 +968,18 @@ void BKE_node_preview_set_pixel( * \{ */ void nodeLabel(struct bNodeTree *ntree, struct bNode *node, char *label, int maxlen); +/** + * Get node socket label if it is set. + */ const char *nodeSocketLabel(const struct bNodeSocket *sock); bool nodeGroupPoll(struct bNodeTree *nodetree, struct bNodeTree *grouptree, const char **r_disabled_hint); -/* Init a new node type struct with default values and callbacks */ +/** + * Initialize a new node type struct with default values and callbacks. + */ void node_type_base(struct bNodeType *ntype, int type, const char *name, short nclass, short flag); void node_type_base_custom( struct bNodeType *ntype, const char *idname, const char *name, short nclass, short flag); @@ -846,6 +990,10 @@ void node_type_size(struct bNodeType *ntype, int width, int minwidth, int maxwid void node_type_size_preset(struct bNodeType *ntype, eNodeSizePreset size); void node_type_init(struct bNodeType *ntype, void (*initfunc)(struct bNodeTree *ntree, struct bNode *node)); +/** + * \warning Nodes defining a storage type _must_ allocate this for new nodes. + * Otherwise nodes will reload as undefined (T46619). + */ void node_type_storage(struct bNodeType *ntype, const char *storagename, void (*freefunc)(struct bNode *node), @@ -1095,8 +1243,18 @@ void BKE_nodetree_remove_layer_n(struct bNodeTree *ntree, struct bNodeTreeExec *ntreeShaderBeginExecTree(struct bNodeTree *ntree); void ntreeShaderEndExecTree(struct bNodeTreeExec *exec); +/** + Find an output node of the shader tree. + * + * \note it will only return output which is NOT in the group, which isn't how + * render engines works but it's how the GPU shader compilation works. This we + * can change in the future and make it a generic function, but for now it stays + * private here. + */ struct bNode *ntreeShaderOutputNode(struct bNodeTree *ntree, int target); - +/** + * This one needs to work on a local tree. + */ void ntreeGPUMaterialNodes(struct bNodeTree *localtree, struct GPUMaterial *mat, bool *has_surface_output, @@ -1288,7 +1446,22 @@ void ntreeCompositExecTree(struct Scene *scene, const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings, const char *view_name); + +/** + * Called from render pipeline, to tag render input and output. + * need to do all scenes, to prevent errors when you re-render 1 scene. + */ void ntreeCompositTagRender(struct Scene *scene); +/** + * Update the outputs of the render layer nodes. + * Since the outputs depend on the render engine, this part is a bit complex: + * - #ntreeCompositUpdateRLayers is called and loops over all render layer nodes. + * - Each render layer node calls the update function of the + * render engine that's used for its scene. + * - The render engine calls RE_engine_register_pass for each pass. + * - #RE_engine_register_pass calls #ntreeCompositRegisterPass, + * which calls #node_cmp_rlayers_register_pass for every render layer node. + */ void ntreeCompositUpdateRLayers(struct bNodeTree *ntree); void ntreeCompositRegisterPass(struct bNodeTree *ntree, struct Scene *scene, @@ -1329,8 +1502,10 @@ void ntreeCompositCryptomatteLayerPrefix(const Scene *scene, const bNode *node, char *r_prefix, size_t prefix_len); -/* Update the runtime layer names with the crypto-matte layer names of the references - * render layer or image. */ +/** + * Update the runtime layer names with the crypto-matte layer names of the references render layer + * or image. + */ void ntreeCompositCryptomatteUpdateLayerNames(const Scene *scene, bNode *node); struct CryptomatteSession *ntreeCompositCryptomatteSession(const Scene *scene, bNode *node); |