Blender V5.3
deriche_gaussian_blur.cc
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#include "BLI_assert.hh"
6#include "BLI_math_vector.hh"
8
9#include "GPU_shader.hh"
10
11#include "COM_context.hh"
12#include "COM_result.hh"
13#include "COM_utilities.hh"
14
16#include "COM_algorithm_pad.hh"
18
19namespace blender::compositor {
20
21#define FILTER_ORDER 4
22
23/* See sum_causal_and_non_causal_results. */
25 const Result &causal_input,
26 const Result &non_causal_input,
28{
29 gpu::Shader *shader = context.get_shader("compositor_deriche_gaussian_blur_sum");
31
32 causal_input.bind_as_texture(shader, "causal_input_tx");
33 non_causal_input.bind_as_texture(shader, "non_causal_input_tx");
34
35 const Domain domain = causal_input.domain();
36 const Domain transposed_domain = domain.transposed();
37 output.allocate_texture(transposed_domain);
38 output.bind_as_image(shader, "output_img");
39
41
43 causal_input.unbind_as_texture();
44 non_causal_input.unbind_as_texture();
45 output.unbind_as_image();
46}
47
48/* See sum_causal_and_non_causal_results. */
49static void sum_causal_and_non_causal_results_cpu(const Result &causal_input,
50 const Result &non_causal_input,
52{
53 const Domain domain = causal_input.domain();
54 const Domain transposed_domain = domain.transposed();
55 output.allocate_texture(transposed_domain);
56
57 parallel_for(domain.data_size, [&](const int2 texel) {
58 /* The Deriche filter is a parallel interconnection filter, meaning its output is the sum of
59 * its causal and non causal filters. */
60 float4 filter_output = float4(causal_input.load_pixel<Color>(texel)) +
61 float4(non_causal_input.load_pixel<Color>(texel));
62
63 /* Write the color using the transposed texel. See the sum_causal_and_non_causal_results method
64 * in the deriche_gaussian_blur.cc file for more information on the rational behind this. */
65 output.store_pixel(int2(texel.y, texel.x), Color(filter_output));
66 });
67}
68
69/* Sum the causal and non causal outputs of the filter and write the sum to the output. This is
70 * because the Deriche filter is a parallel interconnection filter, meaning its output is the sum
71 * of its causal and non causal filters. The output is expected not to be allocated as it will be
72 * allocated internally.
73 *
74 * The output is allocated and written transposed, that is, with a height equivalent to the width
75 * of the input and vice versa. This is done as a performance optimization. The blur pass will
76 * blur the image horizontally and write it to the intermediate output transposed. Then the
77 * vertical pass will execute the same horizontal blur shader, but since its input is transposed,
78 * it will effectively do a vertical blur and write to the output transposed, effectively undoing
79 * the transposition in the horizontal pass. This is done to improve spatial cache locality in the
80 * shader and to avoid having two separate shaders for each blur pass. */
82 const Result &causal_input,
83 const Result &non_causal_input,
85{
86 if (context.use_gpu()) {
87 sum_causal_and_non_causal_results_gpu(context, causal_input, non_causal_input, output);
88 }
89 else {
90 sum_causal_and_non_causal_results_cpu(causal_input, non_causal_input, output);
91 }
92}
93
94static void blur_pass_gpu(Context &context,
95 const Result &input,
96 Result &causal_result,
97 Result &non_causal_result,
98 const float sigma)
99{
100 gpu::Shader *shader = context.get_shader("compositor_deriche_gaussian_blur");
102
103 const DericheGaussianCoefficients &coefficients =
104 context.cache_manager().deriche_gaussian_coefficients.get(context, sigma);
105
107 "causal_feedforward_coefficients",
110 "non_causal_feedforward_coefficients",
113 shader, "feedback_coefficients", float4(coefficients.feedback_coefficients()));
115 shader, "causal_boundary_coefficient", float(coefficients.causal_boundary_coefficient()));
117 "non_causal_boundary_coefficient",
118 float(coefficients.non_causal_boundary_coefficient()));
119
120 input.bind_as_texture(shader, "input_tx");
121
122 const Domain domain = input.domain();
123 causal_result.allocate_texture(domain);
124 non_causal_result.allocate_texture(domain);
125 causal_result.bind_as_image(shader, "causal_output_img");
126 non_causal_result.bind_as_image(shader, "non_causal_output_img");
127
128 /* The second dispatch dimension is two dispatches, one for the causal filter and one for the non
129 * causal one. */
131
133 input.unbind_as_texture();
134 causal_result.unbind_as_image();
135 non_causal_result.unbind_as_image();
136}
137
138static void blur_pass_cpu(Context &context,
139 const Result &input,
140 Result &causal_output,
141 Result &non_causal_output,
142 const float sigma)
143{
144 const DericheGaussianCoefficients &coefficients =
145 context.cache_manager().deriche_gaussian_coefficients.get(context, sigma);
146
147 const float4 causal_feedforward_coefficients = float4(
148 coefficients.causal_feedforward_coefficients());
149 const float4 non_causal_feedforward_coefficients = float4(
151 const float4 feedback_coefficients = float4(coefficients.feedback_coefficients());
152 const float causal_boundary_coefficient = float(coefficients.causal_boundary_coefficient());
153 const float non_causal_boundary_coefficient = float(
154 coefficients.non_causal_boundary_coefficient());
155
156 const Domain domain = input.domain();
157 causal_output.allocate_texture(domain);
158 non_causal_output.allocate_texture(domain);
159
160 /* The first dispatch dimension is two dispatches, one for the causal filter and one for the non
161 * causal one. */
162 const int2 parallel_for_size = int2(2, domain.data_size.y);
163 /* Blur the input horizontally by applying a fourth order IIR filter approximating a Gaussian
164 * filter using Deriche's design method. This is based on the following paper:
165 *
166 * Deriche, Rachid. Recursively implementating the Gaussian and its derivatives. Diss. INRIA,
167 * 1993.
168 *
169 * We run two filters per row in parallel, one for the causal filter and one for the non causal
170 * filter, storing the result of each separately. See the DericheGaussianCoefficients class and
171 * the implementation for more information. */
172 parallel_for(parallel_for_size, [&](const int2 invocation) {
173 /* The code runs parallel across rows but serially across columns. */
174 int y = invocation.y;
175 int width = input.domain().data_size.x;
176
177 /* The second dispatch dimension is two dispatches, one for the causal filter and one for the
178 * non causal one. */
179 bool is_causal = invocation.x == 0;
180 float4 feedforward_coefficients = is_causal ? causal_feedforward_coefficients :
181 non_causal_feedforward_coefficients;
182 float boundary_coefficient = is_causal ? causal_boundary_coefficient :
183 non_causal_boundary_coefficient;
184
185 /* Create an array that holds the last FILTER_ORDER inputs along with the current input. The
186 * current input is at index 0 and the oldest input is at index FILTER_ORDER. We assume Neumann
187 * boundary condition, so we initialize all inputs by the boundary pixel. */
188 int2 boundary_texel = is_causal ? int2(0, y) : int2(width - 1, y);
189 float4 input_boundary = float4(input.load_pixel<Color>(boundary_texel));
190 float4 inputs[FILTER_ORDER + 1] = {
191 input_boundary, input_boundary, input_boundary, input_boundary, input_boundary};
192
193 /* Create an array that holds the last FILTER_ORDER outputs along with the current output. The
194 * current output is at index 0 and the oldest output is at index FILTER_ORDER. We assume
195 * Neumann boundary condition, so we initialize all outputs by the boundary pixel multiplied by
196 * the boundary coefficient. See the DericheGaussianCoefficients class for more information on
197 * the boundary handing. */
198 float4 output_boundary = input_boundary * boundary_coefficient;
199 float4 outputs[FILTER_ORDER + 1] = {
200 output_boundary, output_boundary, output_boundary, output_boundary, output_boundary};
201
202 for (int x = 0; x < width; x++) {
203 /* Run forward across rows for the causal filter and backward for the non causal filter. */
204 int2 texel = is_causal ? int2(x, y) : int2(width - 1 - x, y);
205 inputs[0] = float4(input.load_pixel<Color>(texel));
206
207 /* Compute Equation (28) for the causal filter or Equation (29) for the non causal filter.
208 * The only difference is that the non causal filter ignores the current value and starts
209 * from the previous input, as can be seen in the subscript of the first input term in both
210 * equations. So add one while indexing the non causal inputs. */
211 outputs[0] = float4(0.0f);
212 int first_input_index = is_causal ? 0 : 1;
213 for (int i = 0; i < FILTER_ORDER; i++) {
214 outputs[0] += feedforward_coefficients[i] * inputs[first_input_index + i];
215 outputs[0] -= feedback_coefficients[i] * outputs[i + 1];
216 }
217
218 /* Store the causal and non causal outputs independently, then sum them in a separate shader
219 * dispatch for better parallelism. */
220 if (is_causal) {
221 causal_output.store_pixel(texel, Color(outputs[0]));
222 }
223 else {
224 non_causal_output.store_pixel(texel, Color(outputs[0]));
225 }
226
227 /* Shift the inputs temporally by one. The oldest input is discarded, while the current input
228 * will retain its value but will be overwritten with the new current value in the next
229 * iteration. */
230 for (int i = FILTER_ORDER; i >= 1; i--) {
231 inputs[i] = inputs[i - 1];
232 }
233
234 /* Shift the outputs temporally by one. The oldest output is discarded, while the current
235 * output will retain its value but will be overwritten with the new current value in the
236 * next iteration. */
237 for (int i = FILTER_ORDER; i >= 1; i--) {
238 outputs[i] = outputs[i - 1];
239 }
240 }
241 });
242}
243
244static void blur_pass(Context &context, const Result &input, Result &output, const float sigma)
245{
246 Result causal_result = context.create_result(ResultType::Color);
247 Result non_causal_result = context.create_result(ResultType::Color);
248
249 if (context.use_gpu()) {
250 blur_pass_gpu(context, input, causal_result, non_causal_result, sigma);
251 }
252 else {
253 blur_pass_cpu(context, input, causal_result, non_causal_result, sigma);
254 }
255
256 sum_causal_and_non_causal_results(context, causal_result, non_causal_result, output);
257 causal_result.release();
258 non_causal_result.release();
259}
260
261/* Computes the inverse of compute_sigma_from_radius in recursive_gaussian_blur.cc, see that
262 * function for more information. */
264{
265 return sigma * 3.0f;
266}
267
269 const Result &input,
270 Result &output,
271 const float2 &sigma,
272 const bool extend_bounds)
273{
274 BLI_assert_msg(math::reduce_max(sigma) >= 3.0f,
275 "Deriche filter is slower and less accurate than direct convolution for sigma "
276 "values less 3. Use direct convolution blur instead.");
277 BLI_assert_msg(math::reduce_max(sigma) < 32.0f,
278 "Deriche filter is not accurate nor numerically stable for sigma values larger "
279 "than 32. Use Van Vliet filter instead.");
280
281 if (extend_bounds) {
282 const int2 padding_size = int2(math::ceil(compute_radius_from_sigma(sigma)));
283 Result padded_input = context.create_result(input.type());
284 pad(context, input, padded_input, int2(padding_size.x, 0), PaddingMethod::Zero);
285
286 Result horizontal_pass_result = context.create_result(input.type());
287 blur_pass(context, padded_input, horizontal_pass_result, sigma.x);
288 padded_input.release();
289
290 Result padded_horizontal_pass_result = context.create_result(input.type());
291 pad(context,
292 horizontal_pass_result,
293 padded_horizontal_pass_result,
294 int2(padding_size.y, 0),
296 horizontal_pass_result.release();
297
298 blur_pass(context, padded_horizontal_pass_result, output, sigma.y);
299 padded_horizontal_pass_result.release();
300 }
301 else {
302 Result horizontal_pass_result = context.create_result(input.type());
303 blur_pass(context, input, horizontal_pass_result, sigma.x);
304 blur_pass(context, horizontal_pass_result, output, sigma.y);
305 horizontal_pass_result.release();
306 }
307}
308
309} // namespace blender::compositor
#define BLI_assert_msg(a, msg)
#define output
Domain transposed() const
Definition domain.cc:38
void store_pixel(const int2 &texel, const T &pixel_value)
void allocate_texture(const Domain domain, const bool from_pool=true, const std::optional< ResultStorageType > storage_type=std::nullopt)
Definition result.cc:554
void unbind_as_texture() const
Definition result.cc:964
static ResultType type(gpu::TextureFormat format)
Definition result.cc:337
void bind_as_texture(gpu::Shader *shader, const char *texture_name) const
Definition result.cc:854
T load_pixel(const int2 &texel) const
void unbind_as_image() const
Definition result.cc:990
void bind_as_image(gpu::Shader *shader, const char *image_name, bool read=false) const
Definition result.cc:951
#define FILTER_ORDER
static void sum_causal_and_non_causal_results_cpu(const Result &causal_input, const Result &non_causal_input, Result &output)
void compute_dispatch_threads_at_least(gpu::Shader *shader, int2 threads_range, int2 local_size=int2(16))
Definition utilities.cc:235
static void sum_causal_and_non_causal_results(Context &context, const Result &causal_input, const Result &non_causal_input, Result &output)
static float2 compute_radius_from_sigma(const float2 sigma)
static void blur_pass_cpu(Context &context, const Result &input, Result &causal_output, Result &non_causal_output, const float sigma)
ColorSceneLinear4f< eAlpha::Premultiplied > Color
Definition COM_result.hh:96
void pad(Context &context, const Result &input, Result &output, const int2 size, const PaddingMethod padding_method)
Definition pad.cc:113
void parallel_for(const int2 range, const Function &function)
static void blur_pass_gpu(Context &context, const Result &input, Result &causal_result, Result &non_causal_result, const float sigma)
void deriche_gaussian_blur(Context &context, const Result &input, Result &output, const float2 &sigma, const bool extend_bounds)
static void sum_causal_and_non_causal_results_gpu(Context &context, const Result &causal_input, const Result &non_causal_input, Result &output)
static void blur_pass(Context &context, const Result &input, Result &output, const float sigma)
T reduce_max(const VecBase< T, Size > &a)
T ceil(const T &a)
void GPU_shader_uniform_4fv(gpu::Shader *sh, const char *name, const float data[4])
void GPU_shader_unbind()
void GPU_shader_bind(gpu::Shader *shader, const gpu::shader::SpecializationConstants *constants_state=nullptr)
void GPU_shader_uniform_1f(gpu::Shader *sh, const char *name, float value)
KERNEL_FEATURE_LIGHT_PASSES KERNEL_FEATURE_PATH_GUIDING float