Blender V5.3
render_scheduler.h
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2011-2022 Blender Foundation
2 *
3 * SPDX-License-Identifier: Apache-2.0 */
4
5#pragma once
6
9
10#include "session/buffers.h"
11
12#include "util/string.h"
13
15
16class SessionParams;
17class TileManager;
18
20 public:
23
24 /* Initialize render buffers.
25 * Includes steps like zeroing the buffer on the device, and optional reading of pixels from the
26 * baking target. */
27 bool init_render_buffers = false;
28
29 /* Path tracing samples information. */
30 struct {
31 int start_sample = 0;
32 int num_samples = 0;
33 int sample_offset = 0;
35
36 struct {
37 /* Check for convergency and filter the mask. */
38 bool filter = false;
39
40 float threshold = 0.0f;
41
42 /* Reset convergency flag when filtering, forcing a re-check of whether pixel did converge. */
43 bool reset = false;
45
46 struct {
47 bool postprocess = false;
49
50 /* Work related on the current tile. */
51 struct {
52 /* Write render buffers of the current tile.
53 *
54 * It is up to the path trace to decide whether writing should happen via user-provided
55 * callback into the rendering software, or via tile manager into a partial file. */
56 bool write = false;
57
58 bool denoise = false;
60
61 /* Work related on the full-frame render buffer. */
62 struct {
63 /* Write full render result.
64 * Implies reading the partial file from disk. */
65 bool write = false;
67
68 /* Display which is used to visualize render result. */
69 struct {
70 /* Display needs to be updated for the new render. */
71 bool update = false;
72
73 /* Display can use denoised result if available. */
74 bool use_denoised_result = true;
76
77 /* Re-balance multi-device scheduling after rendering this work.
78 * Note that the scheduler does not know anything about devices, so if there is only a single
79 * device used, then it is up for the PathTracer to ignore the balancing. */
80 bool rebalance = false;
81
82 /* Perform volume guiding buffer denoise. */
84
85 /* Conversion to bool, to simplify checks about whether there is anything to be done for this
86 * work. */
87 operator bool() const
88 {
89 return path_trace.num_samples || adaptive_sampling.filter || display.update || tile.denoise ||
90 tile.write || full.write;
91 }
92};
93
95 public:
96 RenderScheduler(TileManager &tile_manager, const SessionParams &params);
97
98 /* Specify whether cryptomatte-related works are to be scheduled. */
99 void set_need_schedule_cryptomatte(bool need_schedule_cryptomatte);
100
101 /* Allows to disable work re-balancing works, allowing to schedule as much to a single device
102 * as possible. */
103 void set_need_schedule_rebalance(bool need_schedule_rebalance);
104
105 bool is_background() const;
106
107 void set_denoiser_params(const DenoiseParams &params);
108 bool is_denoiser_gpu_used() const;
109
110 /* Check whether a real-time denoiser like DLSS is active. */
111 bool is_denoiser_interactive() const;
112
113 void set_adaptive_sampling(const AdaptiveSampling &adaptive_sampling);
114 bool is_adaptive_sampling_used() const;
115
116 /* Setup parameters defining the sampling range.
117 *
118 * It is a single function setting up multiple parameters because there are inter-dependencies
119 * between these parameters.
120 *
121 * In simple cases the subset is not used and the given num_samples samples is rendered, and the
122 * subset length and offset are ignored.
123 *
124 * It is possible to render a subset of the overall samples. This is typically used to distribute
125 * rendering of a single frame across multiple computers. This subset rendering is enabled by
126 * setting use_sample_subset=true, and giving the desired offset and length of the subset. The
127 * subset offset is a 0-based sample index to start sampling from, and the length is the number
128 * of samples to render in this subset.
129 *
130 * When the subset rendering is enabled, num_samples is expected to be set to the overall number
131 * of samples to be rendered, and it is internally used to clamp the number of samples rendered
132 * by a subset. */
133 void set_sample_params(const int num_samples,
134 const bool use_sample_subset,
135 const int sample_subset_offset,
136 const int sample_subset_length);
137
138 /* Number of samples to render, starting from start sample.
139 * The scheduler will schedule work in the range of
140 * [start_sample, start_sample + num_samples - 1], inclusively. */
141 int get_num_samples() const;
142
143 /* For sample subset rendering, extra offset to be added to sample index
144 * for the sampling pattern to be shifted. */
145 int get_sample_offset() const;
146
147 /* Time limit for the path tracing tasks, in minutes.
148 * Zero disables the limit. */
149 void set_time_limit(const double time_limit);
150 double get_time_limit() const;
151
152 /* Get sample up to which rendering has been done.
153 * This is an absolute 0-based value.
154 *
155 * For example, if start sample is 10 and 5 samples were rendered, then this call will
156 * return 14.
157 *
158 * If there were no samples rendered, then the behavior is undefined. */
159 int get_rendered_sample() const;
160
161 /* Get number of samples rendered within the current scheduling session.
162 *
163 * For example, if start sample is 10 and 5 samples were rendered, then this call will
164 * return 5.
165 *
166 * Note that this is based on the scheduling information. In practice this means that if someone
167 * requested for work to render the scheduler considers the work done. */
168 int get_num_rendered_samples() const;
169
170 /* Get total number of samples rendered since the last scheduling reset, including all rendered
171 * samples across frames with an active real-time denoiser. */
172 int get_total_rendered_samples() const;
173
174 /* Reset scheduler, indicating that rendering will happen from scratch.
175 * Resets current rendered state, as well as scheduling information. */
176 void reset(const BufferParams &buffer_params);
177
178 /* Reset scheduler upon switching to a next tile.
179 * Will keep the same number of samples and full-frame render parameters, but will reset progress
180 * and allow schedule renders works from the beginning of the new tile. */
181 void reset_for_next_tile();
182
183 /* Reschedule adaptive sampling work when all pixels did converge.
184 * If there is nothing else to be done for the adaptive sampling (pixels did converge to the
185 * final threshold) then false is returned and the render scheduler will stop scheduling path
186 * tracing works. Otherwise will modify the work's adaptive sampling settings to continue with
187 * a lower threshold. */
189
190 /* Reschedule adaptive sampling work when the device is mostly on idle, but not all pixels yet
191 * converged.
192 * If re-scheduling is not possible (adaptive sampling is happening with the final threshold, and
193 * the path tracer is to finish the current pixels) then false is returned. */
195
196 /* Reschedule work when rendering has been requested to cancel.
197 *
198 * Will skip all work which is not needed anymore because no more samples will be added (for
199 * example, adaptive sampling filtering and convergence check will be skipped).
200 * Will enable all work needed to make sure all passes are communicated to the software.
201 *
202 * NOTE: Should be used before passing work to `PathTrace::render_samples()`. */
204
206
207 /* Report that the path tracer started to work, after scene update and loading kernels. */
208 void report_work_begin(const RenderWork &render_work);
209
210 /* Report time (in seconds) which corresponding part of work took. */
211 void report_path_trace_time(const RenderWork &render_work, const double time, bool is_cancelled);
212 void report_path_trace_occupancy(const RenderWork &render_work, const float occupancy);
213 void report_adaptive_filter_time(const RenderWork &render_work,
214 const double time,
215 bool is_cancelled);
216 void report_denoise_time(const RenderWork &render_work, const double time);
217 void report_display_update_time(const RenderWork &render_work, const double time);
218 void report_rebalance_time(const RenderWork &render_work,
219 const double time,
220 bool balance_changed);
221 void report_volume_guiding_denoise_time(const RenderWork &render_work, const double time);
222
223 /* Generate full multi-line report of the rendering process, including rendering parameters,
224 * times, and so on. */
225 string full_report() const;
226
227 void set_limit_samples_per_update(const int limit_samples);
228
229 protected:
230 /* Check whether all work has been scheduled and time limit was not exceeded.
231 *
232 * NOTE: Tricky bit: if the time limit was reached the done() is considered to be true, but some
233 * extra work needs to be scheduled to denoise and write final result. */
234 bool done() const;
235
236 /* Update scheduling state for a newly scheduled work.
237 * Takes care of things like checking whether work was ever denoised, tile was written and states
238 * like that. */
239 void update_state_for_render_work(const RenderWork &render_work);
240
241 /* Returns true if any work was scheduled. */
242 bool set_postprocess_render_work(RenderWork *render_work);
243
244 /* Set work which is to be performed after all tiles has been rendered. */
245 void set_full_frame_render_work(RenderWork *render_work);
246
247 /* Update start resolution divider based on the accumulated timing information, preserving nice
248 * feeling navigation feel. */
250
251 /* Calculate desired update interval in seconds based on the current timings and settings.
252 * Will give an interval which provides good feeling updates during viewport navigation. */
254
255 /* Check whether denoising is active during interactive update while resolution divider is not
256 * unit. */
258
259 /* Heuristic which aims to give perceptually pleasant update of display interval in a way that at
260 * lower samples and near the beginning of rendering, updates happen more often, but with higher
261 * number of samples and later in the render, updates happen less often but device occupancy
262 * goes higher. */
265 const int num_rendered_samples) const;
267 int num_rendered_samples) const;
268
269 /* Calculate number of samples which can be rendered within current desired update interval which
270 * is calculated by `guess_update_interval_in_seconds()`. */
272
273 /* Get start sample and the number of samples which are to be path traces in the current work. */
276
277 /* Calculate how many samples there are to be rendered for the very first path trace after reset.
278 */
279 int get_num_samples_during_navigation(const int resolution_divider) const;
280
281 /* Whether adaptive sampling convergence check and filter is to happen. */
282 bool work_need_adaptive_filter() const;
283
284 /* Calculate threshold for adaptive sampling. */
285 float work_adaptive_threshold() const;
286
287 /* Check whether current work needs denoising.
288 * Denoising is not needed if the denoiser is not configured, or when denoising is happening too
289 * often.
290 *
291 * The delayed will be true when the denoiser is configured for use, but it was delayed for a
292 * later sample, to reduce overhead.
293 *
294 * ready_to_display will be false if we may have a denoised result that is outdated due to
295 * increased samples. */
296 bool work_need_denoise(bool &delayed, bool &ready_to_display);
297
298 /* Check whether current work need to update display.
299 *
300 * The `denoiser_delayed` is what `work_need_denoise()` returned as delayed denoiser flag. */
301 bool work_need_update_display(const bool denoiser_delayed);
302
303 /* Check whether it is time to perform rebalancing for the render work, */
304 bool work_need_rebalance();
305
306 /* Check whether timing of the given work are usable to store timings in the `first_render_time_`
307 * for the resolution divider calculation. */
309
310 /* Check whether timing report about the given work need to reset accumulated average time. */
311 bool work_report_reset_average(const RenderWork &render_work);
312
313 /* Check whether render time limit has been reached (or exceeded), and if so store related
314 * information in the state so that rendering is considered finished, and is possible to report
315 * average render time information. */
317
318 /* Helper class to keep track of task timing.
319 *
320 * Contains two parts: wall time and average. The wall time is an actual wall time of how long it
321 * took to complete all tasks of a type. Is always advanced when PathTracer reports time update.
322 *
323 * The average time is used for scheduling purposes. It is estimated to be a time of how long it
324 * takes to perform task on the final resolution. */
326 public:
327 void reset()
328 {
329 total_wall_time_ = 0.0;
330
333
334 last_sample_time_ = 0.0;
335 }
336
337 void add_wall(const double time)
338 {
339 total_wall_time_ += time;
340 }
341
342 void add_average(const double time, const int num_measurements = 1)
343 {
345 num_average_times_ += num_measurements;
346 last_sample_time_ = time / num_measurements;
347 }
348
349 double get_wall() const
350 {
351 return total_wall_time_;
352 }
353
354 double get_average() const
355 {
356 if (num_average_times_ == 0) {
357 return 0;
358 }
360 }
361
362 double get_last_sample_time() const
363 {
364 return last_sample_time_;
365 }
366
368 {
371 }
372
373 protected:
374 double total_wall_time_ = 0.0;
375
378
379 double last_sample_time_ = 0.0;
380 };
381
382 struct {
383 bool user_is_navigating = false;
384
385 int resolution_divider = 1;
386
387 /* Number of rendered samples on top of the start sample. */
388 int num_rendered_samples = 0;
389 /* Total number of rendered samples since the last scheduling reset. */
390 int total_rendered_samples = 0;
391
392 /* Point in time the latest PathTraceDisplay work has been scheduled. */
393 double last_display_update_time = 0.0;
394 /* Value of -1 means display was never updated. */
395 int last_display_update_sample = -1;
396
397 /* Point in time at which last rebalance has been performed. */
398 double last_rebalance_time = 0.0;
399
400 /* Number of rebalance works which has been requested to be performed.
401 * The path tracer might ignore the work if there is a single device rendering. */
402 int num_rebalance_requested = 0;
403
404 /* Number of rebalance works handled which did change balance across devices. */
405 int num_rebalance_changes = 0;
406
407 bool need_rebalance_at_next_work = false;
408
409 /* Denotes whether the latest performed rebalance work cause an actual rebalance of work across
410 * devices. */
411 bool last_rebalance_changed = false;
412
413 /* Threshold for adaptive sampling which will be scheduled to work when not using progressive
414 * noise floor. */
415 float adaptive_sampling_threshold = 0.0f;
416
417 bool last_work_tile_was_denoised = false;
418 bool tile_result_was_written = false;
419 bool postprocess_work_scheduled = false;
420 bool full_frame_work_scheduled = false;
421 bool full_frame_was_written = false;
422
423 bool path_trace_finished = false;
424 bool time_limit_reached = false;
425
426 /* Time at which rendering started and finished. */
427 double start_render_time = 0.0;
428 double end_render_time = 0.0;
429
430 /* Measured occupancy of the render devices measured normalized to the number of samples.
431 *
432 * In a way it is "trailing": when scheduling new work this occupancy is measured when the
433 * previous work was rendered. */
434 int occupancy_num_samples = 0;
435 float occupancy = 1.0f;
437
438 /* Timing of tasks which were performed at the very first render work at 100% of the
439 * resolution. This timing information is used to estimate resolution divider for fats
440 * navigation. */
441 struct {
442 double path_trace_per_sample;
443 double denoise_time;
444 double display_update_time;
446
453
454 /* Whether cryptomatte-related work will be scheduled. */
456
457 /* Whether to schedule device load rebalance works.
458 * Rebalancing requires some special treatment for update intervals and such, so if it's known
459 * that the rebalance will be ignored (due to single-device rendering i.e.) is better to fully
460 * ignore rebalancing logic. */
462
463 /* Path tracing work will be scheduled for samples from within
464 * [sample_offset_, sample_offset_ + num_samples_ - 1] range, inclusively. */
467
468 /* Limit in seconds for how long path tracing is allowed to happen.
469 * Zero means no limit is applied. */
470 double time_limit_ = 0.0;
471
472 /* Headless rendering without interface. */
474
475 /* Background (offline) rendering. */
477
478 /* Pixel size is used to force lower resolution render for final pass. Useful for retina or other
479 * types of hi-dpi displays. */
480 int pixel_size_ = 1;
481
483
486
488
489 /* Progressively lower adaptive sampling threshold level, keeping the image at a uniform noise
490 * level. */
492
493 /* Default value for the resolution divider which will be used when there is no render time
494 * information available yet.
495 * It is also what defines the upper limit of the automatically calculated resolution divider. */
497
498 /* Initial resolution divider which will be used on render scheduler reset. */
500
501 /* Calculate smallest resolution divider which will bring down actual rendering time below the
502 * desired one. This call assumes linear dependency of render time from number of pixels
503 * (quadratic dependency from the resolution divider): resolution divider of 2 brings render time
504 * down by a factor of 4. */
505 int calculate_resolution_divider_for_time(const double desired_time, const double actual_time);
506
507 /* If the number of samples per rendering progression should be limited because of path guiding
508 * being activated or is still inside its training phase */
510};
511
513 const int height,
514 const int resolution);
515
516int calculate_resolution_for_divider(const int width,
517 const int height,
518 const int resolution_divider);
519
void add_average(const double time, const int num_measurements=1)
void add_wall(const double time)
AdaptiveSampling adaptive_sampling_
DenoiseParams denoiser_params_
void set_time_limit(const double time_limit)
void update_state_for_render_work(const RenderWork &render_work)
void report_path_trace_occupancy(const RenderWork &render_work, const float occupancy)
double guess_display_update_interval_in_seconds_for_num_samples(const int num_rendered_samples) const
float work_adaptive_threshold() const
int calculate_num_samples_per_update() const
int get_rendered_sample() const
void report_adaptive_filter_time(const RenderWork &render_work, const double time, bool is_cancelled)
bool work_need_update_display(const bool denoiser_delayed)
BufferParams buffer_params_
void set_need_schedule_rebalance(bool need_schedule_rebalance)
double guess_display_update_interval_in_seconds() const
bool work_need_denoise(bool &delayed, bool &ready_to_display)
bool work_need_adaptive_filter() const
int get_num_rendered_samples() const
string full_report() const
bool need_schedule_rebalance_works_
bool is_denoise_active_during_update() const
void report_denoise_time(const RenderWork &render_work, const double time)
bool set_postprocess_render_work(RenderWork *render_work)
double get_time_limit() const
double guess_display_update_interval_in_seconds_for_num_samples_no_limit(int num_rendered_samples) const
bool work_is_usable_for_first_render_estimation(const RenderWork &render_work)
int calculate_resolution_divider_for_time(const double desired_time, const double actual_time)
TimeWithAverage volume_guiding_denoise_time_
bool is_adaptive_sampling_used() const
void set_denoiser_params(const DenoiseParams &params)
bool is_denoiser_interactive() const
int get_total_rendered_samples() const
struct RenderScheduler::@152371007237337307247005247137000032232276335003 first_render_time_
bool render_work_reschedule_on_idle(RenderWork &render_work)
int get_num_samples() const
TimeWithAverage adaptive_filter_time_
void report_display_update_time(const RenderWork &render_work, const double time)
TimeWithAverage rebalance_time_
void set_sample_params(const int num_samples, const bool use_sample_subset, const int sample_subset_offset, const int sample_subset_length)
int get_sample_offset() const
int default_start_resolution_divider_
bool is_denoiser_gpu_used() const
TimeWithAverage display_update_time_
void reset(const BufferParams &buffer_params)
void set_full_frame_render_work(RenderWork *render_work)
double guess_viewport_navigation_update_interval_in_seconds() const
void update_start_resolution_divider()
void report_path_trace_time(const RenderWork &render_work, const double time, bool is_cancelled)
void set_adaptive_sampling(const AdaptiveSampling &adaptive_sampling)
int get_num_samples_during_navigation(const int resolution_divider) const
bool render_work_reschedule_on_converge(RenderWork &render_work)
TileManager & tile_manager_
bool work_report_reset_average(const RenderWork &render_work)
TimeWithAverage path_trace_time_
int get_start_sample_to_path_trace() const
int get_num_samples_to_path_trace() const
void render_work_reschedule_on_cancel(RenderWork &render_work)
void report_work_begin(const RenderWork &render_work)
TimeWithAverage denoise_time_
void set_need_schedule_cryptomatte(bool need_schedule_cryptomatte)
void report_rebalance_time(const RenderWork &render_work, const double time, bool balance_changed)
void set_limit_samples_per_update(const int limit_samples)
RenderWork get_render_work()
RenderScheduler(TileManager &tile_manager, const SessionParams &params)
struct RenderScheduler::@161253332237067242016063160144242156123242025211 state_
bool is_background() const
void report_volume_guiding_denoise_time(const RenderWork &render_work, const double time)
float resolution_divider
bool volume_guiding_denoise
bool init_render_buffers
struct RenderWork::@062144024112073257370032340252251130221344035014 tile
struct RenderWork::@045110325327334210271225251376000202010073303033 adaptive_sampling
struct RenderWork::@103345022157251202112140335355011252273171271005 path_trace
struct RenderWork::@310313166116170111017300246342343006316141322247 display
struct RenderWork::@026114172320136364120000247117121135046160342264 cryptomatte
struct RenderWork::@075102241252202025353112266176333317356231366323 full
float denoised_resolution_divider
#define CCL_NAMESPACE_END
const ccl_global KernelWorkTile * tile
int calculate_resolution_divider_for_resolution(int width, int height, const int resolution)
int calculate_resolution_for_divider(const int width, const int height, const int resolution_divider)