Blender V5.3
COM_pixel_operation.hh
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2024 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#pragma once
6
7#include "BKE_node.hh"
8
9#include "BLI_map.hh"
10#include "BLI_string_ref.hh"
11#include "BLI_vector_set.hh"
12
13#include "COM_context.hh"
14#include "COM_operation.hh"
15
16namespace blender {
17class ComputeContext;
18}
19
20namespace blender::compositor {
21
22struct Schedule;
24
25/* A type representing a contiguous subset of the node execution schedule that will be compiled
26 * into a Pixel Operation. */
28
29/* ------------------------------------------------------------------------------------------------
30 * Pixel Operation
31 *
32 * An operation that is evaluated pixel-wise and is compiled from a contiguous subset of the node
33 * execution schedule, whose nodes all represent pixel-wise operations. The subset of the node
34 * execution schedule is called a Pixel Compile Unit and contains nodes that are called Pixel
35 * nodes, see the discussion in COM_node_tree_evaluator.hh for more information. Since the nodes
36 * inside the compile unit are all pixel wise, they can be combined into a single operation that
37 * can be evaluated more efficiently. This is an abstract class that should be implemented to
38 * compile and evaluate the compile unit as needed.
39 *
40 * Consider the following node graph with a node execution schedule denoted by the number on each
41 * node. The compiler may decide to compile a subset of the execution schedule into a pixel
42 * operation if they are all pixel nodes, in this case, the nodes from 3 to 5 were compiled
43 * together into a pixel operation. This subset is called the pixel compile unit. See the
44 * discussion in COM_node_tree_evaluator.hh for more information on the compilation process. Links
45 * that are internal to the pixel operation are established between the input and outputs of the
46 * pixel nodes, for instance, the links between nodes 3 and 4 as well as those between nodes 4
47 * and 5. However, links that cross the boundary of the pixel operation needs special handling.
48 *
49 * Pixel Operation
50 * +------------------------------------------------------+
51 * .------------. | .------------. .------------. .------------. | .------------.
52 * | Node 1 | | | Node 3 | | Node 4 | | Node 5 | | | Node 6 |
53 * | |----|--| |--| |------| |--|--| |
54 * | | .-|--| | | | .---| | | | |
55 * '------------' | | '------------' '------------' | '------------' | '------------'
56 * | +----------------------------------|-------------------+
57 * .------------. | |
58 * | Node 2 | | |
59 * | |--'------------------------------------'
60 * | |
61 * '------------'
62 *
63 * Links from nodes that are not part of the pixel operation to nodes that are part of the pixel
64 * operation are considered inputs of the operation itself and are declared as such. For instance,
65 * the link from node 1 to node 3 is declared as an input to the operation, and the same applies
66 * for the links from node 2 to nodes 3 and 5. Note, however, that only one input is declared for
67 * each distinct output socket, so both links from node 2 share the same input of the operation.
68 *
69 * Links from nodes that are part of the pixel operation to nodes that are not part of the pixel
70 * operation are considered outputs of the operation itself and are declared as such. For instance,
71 * the link from node 5 to node 6 is declared as an output to the operation. */
72class PixelOperation : public Operation {
73 protected:
74 /* The node tree evaluator which currently contains a pixel compile unit that needs to be
75 * compiled into this pixel operation. */
77 /* The compute context where this pixel operation is executing. */
79 /* A map that associates the identifier of each input of the operation with the output socket it
80 * is linked to. This is needed to help the compiler establish links between operations. */
82 /* A map that associates the output socket of a node that is not part of the pixel operation to
83 * the identifier of the input of the operation that was declared for it. */
85 /* A map that associates each of the needed implicit inputs with the identifiers of the inputs of
86 * the operation that were declared for them. */
88 /* A map that associates the identifier of each input of the operation with the number of node
89 * inputs that use it, that is, its reference count. This is needed to correct the reference
90 * counts of results linked to the inputs of the operation, since the results that provide the
91 * inputs aren't aware that multiple of their outgoing links are now part of a single pixel
92 * operation. For instance, if an output is linked to both inputs of a Math node, its computed
93 * reference count would be 2, but the pixel operation of the Math node would only create a
94 * single shared input for it, so from the point of view of the evaluator, the reference count
95 * should actually be 1. So the result's reference count should be corrected by decrementing it
96 * by the internal reference count computed in this map minus 1. */
98 /* A map that associates the output socket that provides the result of an output of the operation
99 * with the identifier of that output. This is needed to help the compiler establish links
100 * between operations. */
102 /* A vector set that stores all output sockets that are used as previews for nodes inside the
103 * pixel operation. */
105 /* A vector set that stores all output sockets that will be logged to the node evaluator log. */
107 /* True if the operation operates on single values, that is, all of its inputs and outputs are
108 * single values. */
110
111 public:
113 NodeTreeEvaluator &node_tree_evaluator,
114 const ComputeContext &compute_context,
115 const bool is_single_value);
116
117 /* Log the values of all inputs and outputs of nodes inside the pixel operation as well as node
118 * previews for all nodes in the pixel operations if the node requires a preview.
119 *
120 * Previews are computed from results that are populated for outputs that are used to compute
121 * previews even if they are internally linked, and those outputs are stored and tracked in the
122 * preview_outputs_ vector set, see the populate_results_for_node method for more information. */
123 void log_data() override;
124
125 /* Get the identifier of the operation output corresponding to the given output socket. This is
126 * called by the compiler to identify the operation output that provides the result for an input
127 * by providing the output socket that the input is linked to. See
128 * output_sockets_to_output_identifiers_map_ for more information. */
130
131 /* Get a reference to the inputs to linked outputs map of the operation. This is called by the
132 * compiler to identify the output that each input of the operation is linked to for correct
133 * input mapping. See inputs_to_linked_outputs_map_ for more information. */
135
136 /* Get a reference to the implicit inputs to input identifiers map of the operation. This is
137 * called by the compiler to link the operations inputs with their corresponding implicit input
138 * results. See implicit_inputs_to_input_identifiers_map_ for more information. */
140
141 /* Returns the internal reference count of the operation input with the given identifier. See the
142 * inputs_to_reference_counts_map_ member for more information. */
143 int get_internal_input_reference_count(const StringRef &identifier);
144
145 /* Compute and set the initial reference counts of all the results of the operation. The node
146 * execution schedule is given as an input. */
147 void compute_results_reference_counts(const Schedule &schedule);
148};
149
150} // namespace blender::compositor
Operation(Context &context)
Definition operation.cc:22
Context & context() const
Definition operation.cc:57
Map< ImplicitInputType, std::string > implicit_inputs_to_input_identifiers_map_
VectorSet< const bNodeSocket * > preview_outputs_
Map< ImplicitInputType, std::string > & get_implicit_inputs_to_input_identifiers_map()
StringRef get_output_identifier_from_output_socket(const bNodeSocket &output_socket)
Map< std::string, const bNodeSocket * > inputs_to_linked_outputs_map_
Map< const bNodeSocket *, std::string > output_sockets_to_output_identifiers_map_
VectorSet< const bNodeSocket * > logged_outputs_
Map< std::string, int > inputs_to_reference_counts_map_
int get_internal_input_reference_count(const StringRef &identifier)
PixelOperation(Context &context, NodeTreeEvaluator &node_tree_evaluator, const ComputeContext &compute_context, const bool is_single_value)
Map< std::string, const bNodeSocket * > & get_inputs_to_linked_outputs_map()
void compute_results_reference_counts(const Schedule &schedule)
Map< const bNodeSocket *, std::string > outputs_to_declared_inputs_map_
VectorSet< const bNode * > PixelCompileUnit
BMesh Iterators.