Blender V5.3
COM_domain.hh
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2023 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#pragma once
6
7#include <cstdint>
8
11#include "BLI_string_ref.hh"
12
13#include "GPU_texture.hh"
14
15namespace blender::compositor {
16
17/* Possible interpolations to use when realizing an input result of some domain on another domain.
18 * See the RealizationOptions struct for more information. */
25
26/* Possible extensions when computing samples in the domain's exterior. */
27enum class Extension : uint8_t {
28 /* Areas outside of the image are filled with the closest boundary pixel in the image. */
29 Extend,
30 /* Areas outside of the image are filled with repetitions of the image. */
31 Repeat,
32 /* Areas outside of the image are filled with zero. */
34};
35
36/* ------------------------------------------------------------------------------------------------
37 * Realization Options
38 *
39 * The options that describe how an input result prefer to be realized on some other domain. This
40 * is used by the Realize On Domain and Transform algorithms to identify the appropriate method of
41 * realization. See the Domain class for more information. */
43 /* The interpolation method that should be used when performing realization. Since realizing a
44 * result involves projecting it on a different domain, which in turn, involves sampling the
45 * result at arbitrary locations, the interpolation identifies the method used for computing the
46 * value at those arbitrary locations. */
48 /* The extend mode for the x-axis. Defaults to Zero padding. */
50 /* The extend mode for the y-axis. Defaults to Zero padding. */
52};
53
54/* ------------------------------------------------------------------------------------------------
55 * Domain
56 *
57 * The compositor is designed in such a way as to allow compositing in an infinite virtual
58 * compositing space. Consequently, any result of an operation is not only represented by its image
59 * pixel data, but also by its transformation in that virtual space, both of which are stored and
60 * represented by a Domain. In the figure below, two results of different domains are illustrated
61 * on the virtual compositing space. One of the results is centered in space with an image
62 * dimension of 800px x 600px, and the other result is scaled down and translated such that it lies
63 * in the upper right quadrant of the space with an image dimension of 800px × 400px. The position
64 * of the domain is in pixel space, and the domain is considered centered if it has an identity
65 * transformation. Note that both results have the same resolution, but occupy different areas of
66 * the virtual compositing space.
67 *
68 * y
69 * ^
70 * 800px x 600px |
71 * .---------------------|---------------------.
72 * | | 800px x 600px |
73 * | | .-------------. |
74 * | | | | |
75 * | | '-------------' |
76 * ------|---------------------|---------------------|------> x
77 * | | |
78 * | | |
79 * | | |
80 * | | |
81 * '---------------------|---------------------'
82 * |
83 *
84 * Additionally, the image might not have pixel data defined everywhere or might have data that
85 * extends outside of boundary of the image, the latter is typically known as over-scan. Therefore,
86 * the domain stores the image information as:
87 *
88 * - data_size: Which is the size of the data that actually exists in pixels.
89 * - display_size: Which is the conceptual and visual size of the image in pixels.
90 * - data_offset: Which is the offset from the lower left corner of the display region to the data
91 * region in pixels. See the member documentation for more information.
92 *
93 * See the EXR Data/Display Window specification for more information on this formulation. The only
94 * deviation from EXR is that we store the offset of the display window as the translation of the
95 * transformation, which works better in practice.
96 *
97 * By default, results have domains of identity transformations, that is, they are centered in
98 * space, but a transformation operation like the rotate, translate, or transform operations will
99 * adjust the transformation to make the result reside somewhere different in space. The domain of
100 * a single value result is irrelevant and always set to an identity domain.
101 *
102 * An operation is typically only concerned about a subset of the virtual compositing space, this
103 * subset is represented by a domain which is called the Operation Domain. It follows that before
104 * the operation itself is executed, inputs will typically be realized on the operation domain to
105 * be in the same domain and have the same dimension as that of the operation domain. This process
106 * is called Domain Realization and is implemented using an operation called the Realize On Domain
107 * Operation. Realization involves projecting the result onto the target domain, copying the area
108 * of the result that intersects the target domain, and filling the rest with zeros or repetitions
109 * of the result depending on the realization options that can be set by the user. Consequently,
110 * operations can generally expect their inputs to have the same dimension and can operate on them
111 * directly and transparently. For instance, if an operation takes both results illustrated in
112 * the figure above, and the operation has an operation domain that matches the bigger domain, the
113 * result with the bigger domain will not need to be realized because it already has a domain that
114 * matches that of the operation domain, but the result with the smaller domain will have to be
115 * realized into a new result that has the same domain as the domain of the bigger result. Assuming
116 * no repetition, the output of the realization will be an all zeros image with dimension 800px ×
117 * 600px with a small scaled version of the smaller result copied into the upper right quadrant of
118 * the image. The following figure illustrates the realization process on a different set of
119 * results
120 *
121 * Realized Result
122 * +-------------+ +-------------+
123 * | Operation | | |
124 * | Domain | | Zeros |
125 * | | ----> | |
126 * +-----|-----+ | |-----+ |
127 * | | C | | | C | |
128 * | +-----|-------+ +-----'-------+
129 * | Domain Of |
130 * | Input |
131 * +-----------+
132 *
133 * An operation can operate in an arbitrary operation domain, but in most cases, the operation
134 * domain is inferred from the inputs of the operation. In particular, one of the inputs is said to
135 * be the Domain Input of the operation and the operation domain is inferred from its domain. It
136 * follows that this particular input will not need realization, because it already has the correct
137 * domain. The domain input selection mechanism is as follows. Each of the inputs are assigned a
138 * value by the developer called the Domain Priority, the domain input is then chosen as the
139 * non-single value input with the highest domain priority, zero being the highest priority. See
140 * Operation::compute_domain for more information.
141 *
142 * The aforementioned logic for operation domain computation is only a default that works for most
143 * cases, but an operation can override the compute_domain method to implement a different logic.
144 * For instance, output nodes have an operation domain the same size as the viewport and with an
145 * identity transformation, their operation domain doesn't depend on the inputs at all.
146 *
147 * For instance, a filter operation has two inputs, a factor and a color, the latter of which is
148 * assigned a domain priority of 0 and the former is assigned a domain priority of 1. If the color
149 * input is not a single value input, then the color input is considered to be the domain input of
150 * the operation and the operation domain is computed to be the same domain as the color input,
151 * because it has the highest priority. It follows that if the factor input has a different domain
152 * than the computed domain of the operation, it will be projected and realized on it to have the
153 * same domain as described above. On the other hand, if the color input is a single value input,
154 * then the factor input is considered to be the domain input and the operation domain will be the
155 * same as the domain of the factor input, because it has the second highest domain priority.
156 * Finally, if both inputs are single value inputs, the operation domain will be an identity domain
157 * and is irrelevant, because the output will be a domain-less single value. */
158class Domain {
159 public:
160 /* The size of the data that actually exists in pixels. */
162 /* The conceptual/visual size or of the image in pixels. */
164 /* The offset from the display region to the data region. A positive data offset means the data
165 * only covers a portion of the display, while a negative data offset means that the data extends
166 * past the boundary of the display, that is, over-scan exists. */
168 /* The 2D transformation of the domain defining its translation in pixels, rotation, and scale in
169 * the virtual compositing space. */
171 /* The options that describe how this domain prefer to be realized on some other domain. See the
172 * RealizationOptions struct for more information. */
174
175 /* A size only constructor that sets the transformation to identity. */
176 Domain(const int2 &size);
177
178 Domain(const int2 &size, const float3x3 &transformation);
179
180 /* Transform the domain by the given transformation. This effectively pre-multiply the given
181 * transformation by the current transformation of the domain. */
182 void transform(const float3x3 &input_transformation);
183
184 /* Returns a transposed version of itself, that is, with the x and y sizes swapped. */
185 Domain transposed() const;
186
187 /* Compute a domain from this potential transformed domain such that its rotation and scale
188 * become identity and the size of the domain is increased/reduced to adapt to the new
189 * transformation. For instance, if the domain is rotated, the returned domain will have zero
190 * rotation but expanded size to account for the bounding box of the domain after rotation.
191 * Similarly, if the realize_translation argument is true, translation will be set to zero,
192 * though this will not affect the size of the domain in any way. */
193 Domain realize_transformation(const bool realize_translation = false) const;
194
195 /* Returns a domain of size 1x1 and an identity transformation. */
196 static Domain identity();
197
198 /* Compare the size and transformation of the domain. Transformations are compared within the
199 * given epsilon. The realization_options are not compared because they only describe the method
200 * of realization on another domain, which is not technically a property of the domain itself. */
201 static bool is_equal(const Domain &a, const Domain &b, const float epsilon = 10e-6f);
202};
203
204/* Identical to the is_equal static method with zero epsilon. */
205bool operator==(const Domain &a, const Domain &b);
206bool operator!=(const Domain &a, const Domain &b);
207
208StringRefNull to_string(const Interpolation &interpolation);
209StringRefNull to_string(const Extension &extension);
211
212} // namespace blender::compositor
Domain realize_transformation(const bool realize_translation=false) const
Definition domain.cc:59
Domain(const int2 &size)
Definition domain.cc:20
static bool is_equal(const Domain &a, const Domain &b, const float epsilon=10e-6f)
Definition domain.cc:52
Domain transposed() const
Definition domain.cc:38
void transform(const float3x3 &input_transformation)
Definition domain.cc:33
RealizationOptions realization_options
static Domain identity()
Definition domain.cc:47
StringRefNull to_string(const Interpolation &interpolation)
Definition domain.cc:112
bool operator==(const BokehKernelKey &a, const BokehKernelKey &b)
GPUSamplerExtendMode map_extension_mode_to_extend_mode(const Extension &mode)
Definition domain.cc:144
bool operator!=(const Domain &a, const Domain &b)
Definition domain.cc:107
unsigned char uint8_t
Definition BKE_text.h:79