Blender V5.3
path_trace.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
7#include <functional>
8
10#include "integrator/guiding.h"
14
15#include "session/buffers.h"
16
17#include "util/guiding.h" // IWYU pragma: keep
18#include "util/thread.h"
19#include "util/unique_ptr.h"
20#include "util/vector.h"
21
23
25class Device;
26class DeviceScene;
27class DisplayDriver;
28class Film;
29class RenderBuffers;
30class RenderScheduler;
31class RenderWork;
33class OutputDriver;
34class Progress;
35class TileManager;
36
37/* PathTrace class takes care of kernel graph and scheduling on a (multi)device. It takes care of
38 * all the common steps of path tracing which are not device-specific. The list of tasks includes
39 * but is not limited to:
40 * - Kernel graph.
41 * - Scheduling logic.
42 * - Queues management.
43 * - Adaptive stopping. */
44class PathTrace {
45 public:
46 /* Render scheduler is used to report timing information and access things like start/finish
47 * sample. */
48 PathTrace(Device *device,
49 Device *denoise_device,
50 Film *film,
51 DeviceScene *device_scene,
52 RenderScheduler &render_scheduler,
53 TileManager &tile_manager);
54 ~PathTrace();
55
56 /* Create devices and load kernels which are created on-demand (for example, denoising devices).
57 * The progress is reported to the currently configure progress object (via `set_progress`). */
58 void load_kernels();
59
60 /* Allocate working memory. This runs after scene memory allocation, so that the number of
61 * path states can take the updated scene into account. Scene memory can be moved back to
62 * the host as part of this allocation, as work memory is not host mapped and allocating
63 * it may request more space to be freed on the GPU. */
64 void alloc_work_memory();
65
66 /* Check whether now it is a good time to reset rendering.
67 * Used to avoid very often resets in the viewport, giving it a chance to draw intermediate
68 * render result. */
69 bool ready_to_reset();
70
71 void reset(const BufferParams &full_params,
72 const BufferParams &big_tile_params,
73 bool reset_rendering);
74
75 void device_free();
76
77 /* Set progress tracker.
78 * Used to communicate details about the progress to the outer world, check whether rendering is
79 * to be canceled.
80 *
81 * The path tracer writes to this object, and then at a convenient moment runs
82 * progress_update_cb() callback. */
83 void set_progress(Progress *progress);
84
85 /* NOTE: This is a blocking call. Meaning, it will not return until given number of samples are
86 * rendered (or until rendering is requested to be canceled). */
87 void render(const RenderWork &render_work);
88
89 /* TODO(sergey): Decide whether denoiser is really a part of path tracer. Currently it is
90 * convenient to have it here because then its easy to access render buffer. But the downside is
91 * that this adds too much of entities which can live separately with some clear API. */
92
93 /* Set denoiser parameters.
94 * Use this to configure the denoiser before rendering any samples. */
95 void set_denoiser_params(const DenoiseParams &params);
96
97 /* Set parameters used for adaptive sampling.
98 * Use this to configure the adaptive sampler before rendering any samples. */
99 void set_adaptive_sampling(const AdaptiveSampling &adaptive_sampling);
100
101 /* Set the parameters for guiding.
102 * Use to setup the guiding structures before each rendering iteration. */
103 void set_guiding_params(const GuidingParams &params, const bool reset);
104
105 /* Sets output driver for render buffer output. */
107
108 /* Set display driver for interactive render buffer display. */
110
111 /* Clear the display buffer by filling it in with all zeroes. */
112 void zero_display();
113
114 /* Perform drawing of the current state of the DisplayDriver. */
115 void draw();
116
117 /* Flush outstanding display commands before ending the render loop. */
118 void flush_display();
119
120 /* Cancel rendering process as soon as possible, without waiting for full tile to be sampled.
121 * Used in cases like reset of render session.
122 *
123 * This is a blocking call, which returns as soon as there is no running `render_samples()` call.
124 */
125 void cancel();
126
127 /* Copy an entire render buffer to/from the path trace. */
128
129 /* Copy happens via CPU side buffer: data will be copied from every device of the path trace, and
130 * the data will be copied to the device of the given render buffers. */
131 void copy_to_render_buffers(RenderBuffers *render_buffers);
132
133 /* Copy happens via CPU side buffer: data will be copied from the device of the given render
134 * buffers and will be copied to all devices of the path trace. */
135 void copy_from_render_buffers(RenderBuffers *render_buffers);
136
137 /* Copy render buffers of the big tile from the device to host.
138 * Return true if all copies are successful. */
140
141 /* Read given full-frame file from disk, perform needed processing and write it to the software
142 * via the write callback. */
143 void process_full_buffer_from_disk(string_view filename);
144
145 /* Get number of samples in the current big tile render buffers. */
146 int get_num_render_tile_samples() const;
147
148 /* Get pass data of the entire big tile.
149 * This call puts pass render result from all devices into the final pixels storage.
150 *
151 * NOTE: Expects buffers to be copied to the host using `copy_render_tile_from_device()`.
152 *
153 * Returns false if any of the accessor's `get_render_tile_pixels()` returned false. */
154 bool get_render_tile_pixels(const PassAccessor &pass_accessor,
155 const PassAccessor::Destination &destination);
156
157 /* Set pass data for baking. */
158 bool set_render_tile_pixels(PassAccessor &pass_accessor, const PassAccessor::Source &source);
159
160 /* Check whether denoiser was run and denoised passes are available. */
161 bool has_denoised_result() const;
162
163 /* Get size and offset (relative to the buffer's full x/y) of the currently rendering tile.
164 * In the case of tiled rendering this will return full-frame after all tiles has been rendered.
165 *
166 * NOTE: If the full-frame buffer processing is in progress, returns parameters of the full-frame
167 * instead. */
170 int2 get_render_size() const;
171
172 /* Get buffer parameters of the current tile.
173 *
174 * NOTE: If the full-frame buffer processing is in progress, returns parameters of the full-frame
175 * instead. */
177
178 /* Generate full multi-line report of the rendering process, including rendering parameters,
179 * times, and so on. */
180 string full_report() const;
181
182 /* Callback which is called to report current rendering progress.
183 *
184 * It is supposed to be cheaper than buffer update/write, hence can be called more often.
185 * Additionally, it might be called form the middle of wavefront (meaning, it is not guaranteed
186 * that the buffer is "uniformly" sampled at the moment of this callback). */
187 std::function<void(void)> progress_update_cb;
188
189 protected:
190 /* Actual implementation of the rendering pipeline.
191 * Calls steps in order, checking for the cancel to be requested in between.
192 *
193 * Is separate from `render()` to simplify dealing with the early outputs and keeping
194 * `render_cancel_` in the consistent state. */
195 void render_pipeline(RenderWork render_work);
196
197 /* Initialize kernel execution on all integrator queues. */
199
200 /* Release kernel execution resources on all integrator queues. */
202
203 /* Make sure both allocated and effective buffer parameters of path tracer works are up to date
204 * with the current big tile parameters, performance-dependent slicing, and resolution divider.
205 */
206 void update_work_buffer_params_if_needed(const RenderWork &render_work);
208 void update_effective_work_buffer_params(const RenderWork &render_work);
209
210 /* Perform various steps of the render work.
211 *
212 * Note that some steps might modify the work, forcing some steps to happen within this iteration
213 * of rendering. */
214 void init_render_buffers(const RenderWork &render_work);
215 void path_trace(RenderWork &render_work);
216 void adaptive_sample(RenderWork &render_work);
217 void denoise(const RenderWork &render_work);
218 void denoise_volume_guiding_buffers(const RenderWork &render_work, const bool has_volume);
219 void cryptomatte_postprocess(const RenderWork &render_work);
220 void update_display(const RenderWork &render_work);
221 void rebalance(const RenderWork &render_work);
222 void write_tile_buffer(const RenderWork &render_work);
223 void finalize_full_buffer_on_disk(const RenderWork &render_work);
224
225 /* Updates/initializes the guiding structures after a rendering iteration.
226 * The structures are updated using the training data/samples generated during the previous
227 * rendering iteration */
229
230 /* Prepares the per-kernel thread related guiding structures (e.g., PathSegmentStorage,
231 * pointers to the global Field and SegmentStorage)*/
233
234 /* Get number of samples in the current state of the render buffers. */
236
237 /* Check whether user requested to cancel rendering, so that path tracing is to be finished as
238 * soon as possible. */
239 bool is_cancel_requested();
240
241 /* Write the big tile render buffer via the write callback. */
242 void tile_buffer_write();
243
244 /* Read the big tile render buffer via the read callback. */
245 void tile_buffer_read();
246
247 /* Write current tile into the file on disk. */
249
250 /* Run the progress_update_cb callback if it is needed. */
251 void progress_update_if_needed(const RenderWork &render_work);
252
253 void progress_set_status(const string &status, const string &substatus = "");
254
255 /* Destroy GPU resources (such as graphics interop) used by work. */
257
258 /* Pointer to a device which is configured to be used for path tracing. If multiple devices
259 * are configured this is a `MultiDevice`. */
260 Device *device_ = nullptr;
261
262 /* Pointer to a device which is configured to be used for denoising. Can be identical
263 * to the device */
265
266 /* CPU device for creating temporary render buffers on the CPU side. */
268
271
274
275 /* Display driver for interactive render buffer display. */
277
278 /* Output driver to write render buffer to. */
280
281 /* Per-compute device descriptors of work which is responsible for path tracing on its configured
282 * device. */
284
285 /* Per-path trace work information needed for multi-device balancing. */
287
288 /* Render buffer parameters of the full frame and current big tile. */
291
292 /* Denoiser which takes care of denoising the big tile. */
294
295 /* Denoiser device descriptor which holds the denoised big tile for multi-device workloads. */
297
298#if defined(WITH_PATH_GUIDING)
299 /* Guiding related attributes */
300 GuidingParams guiding_params_;
301
302 /* The guiding field which holds the representation of the incident radiance field for the
303 * complete scene. */
304 unique_ptr<openpgl::cpp::Field> guiding_field_;
305
306 /* The storage container which holds the training data/samples generated during the last
307 * rendering iteration. */
308 unique_ptr<openpgl::cpp::SampleStorage> guiding_sample_data_storage_;
309
310 /* The number of already performed training iterations for the guiding field. */
311 int guiding_update_count = 0;
312#endif
313
314 /* State which is common for all the steps of the render work.
315 * Is brought up to date in the `render()` call and is accessed from all the steps involved into
316 * rendering the work. */
317 struct {
318 /* Denotes whether render buffers parameters of path trace works are to be reset for the new
319 * value of the big tile parameters. */
320 bool need_reset_params = false;
321
322 /* Divider of the resolution for faster previews.
323 *
324 * Allows to re-use same render buffer, but have less pixels rendered into in it. The way to
325 * think of render buffer in this case is as an over-allocated array: the resolution divider
326 * affects both resolution and stride as visible by the integrator kernels. */
327 float resolution_divider = 0;
328
329 /* Parameters of the big tile with the current resolution divider applied. */
330 BufferParams effective_big_tile_params;
331 BufferParams effective_denoised_big_tile_params;
332
333 /* Denoiser was run and there are denoised versions of the passes in the render buffers. */
334 bool has_denoised_result = false;
335
336 /* Current tile has been written (to either disk or callback.
337 * Indicates that no more work will be done on this tile. */
338 bool tile_written = false;
340
341 /* Progress object which is used to communicate sample progress. */
343
344 /* Fields required for canceling render on demand, as quickly as possible. */
345 struct {
346 /* Indicates whether there is an on-going `render_samples()` call. */
347 bool is_rendering = false;
348
349 /* Indicates whether rendering is requested to be canceled by `cancel()`. */
350 bool is_requested = false;
351
352 /* Synchronization between thread which does `render_samples()` and thread which does
353 * `cancel()`. */
354 thread_mutex mutex;
357
358 /* Indicates whether a render result was drawn after latest session reset.
359 * Used by `ready_to_reset()` to implement logic which feels the most interactive. */
361
362 /* State of the full frame processing and writing to the software. */
363 struct {
364 RenderBuffers *render_buffers = nullptr;
366};
367
Definition film.h:29
void device_free()
Progress * progress_
Definition path_trace.h:342
void render_deinit_kernel_execution()
void denoise(const RenderWork &render_work)
int2 get_render_tile_size() const
void finalize_full_buffer_on_disk(const RenderWork &render_work)
std::function< void(void)> progress_update_cb
Definition path_trace.h:187
void process_full_buffer_from_disk(string_view filename)
void tile_buffer_write()
Device * device_
Definition path_trace.h:260
unique_ptr< Denoiser > denoiser_
Definition path_trace.h:293
void update_effective_work_buffer_params(const RenderWork &render_work)
BufferParams full_params_
Definition path_trace.h:289
void rebalance(const RenderWork &render_work)
bool is_cancel_requested()
void init_render_buffers(const RenderWork &render_work)
void copy_to_render_buffers(RenderBuffers *render_buffers)
void destroy_gpu_resources()
struct PathTrace::@127322252215372354363353156034112366364350337004 full_frame_state_
bool has_denoised_result() const
void set_progress(Progress *progress)
vector< unique_ptr< PathTraceWork > > path_trace_works_
Definition path_trace.h:283
void copy_from_render_buffers(RenderBuffers *render_buffers)
Device * denoise_device_
Definition path_trace.h:264
void set_denoiser_params(const DenoiseParams &params)
void progress_update_if_needed(const RenderWork &render_work)
void update_display(const RenderWork &render_work)
void progress_set_status(const string &status, const string &substatus="")
void set_adaptive_sampling(const AdaptiveSampling &adaptive_sampling)
void set_output_driver(unique_ptr< OutputDriver > driver)
void reset(const BufferParams &full_params, const BufferParams &big_tile_params, bool reset_rendering)
DeviceScene * device_scene_
Definition path_trace.h:270
bool ready_to_reset()
bool get_render_tile_pixels(const PassAccessor &pass_accessor, const PassAccessor::Destination &destination)
void cancel()
void guiding_update_structures()
PathTrace(Device *device, Device *denoise_device, Film *film, DeviceScene *device_scene, RenderScheduler &render_scheduler, TileManager &tile_manager)
void zero_display()
void guiding_prepare_structures()
int2 get_render_tile_offset() const
unique_ptr< Device > cpu_device_
Definition path_trace.h:267
void denoise_volume_guiding_buffers(const RenderWork &render_work, const bool has_volume)
void set_guiding_params(const GuidingParams &params, const bool reset)
void tile_buffer_write_to_disk()
void set_display_driver(unique_ptr< DisplayDriver > driver)
void path_trace(RenderWork &render_work)
void render_pipeline(RenderWork render_work)
unique_ptr< OutputDriver > output_driver_
Definition path_trace.h:279
unique_ptr< PathTraceDisplay > display_
Definition path_trace.h:276
vector< WorkBalanceInfo > work_balance_infos_
Definition path_trace.h:286
bool copy_render_tile_from_device()
struct PathTrace::@173325273166301271234167061230356352223360370066 render_state_
bool did_draw_after_reset_
Definition path_trace.h:360
void render_init_kernel_execution()
int2 get_render_size() const
TileManager & tile_manager_
Definition path_trace.h:273
unique_ptr< PathTraceWork > big_tile_denoise_work_
Definition path_trace.h:296
void update_work_buffer_params_if_needed(const RenderWork &render_work)
void alloc_work_memory()
BufferParams big_tile_params_
Definition path_trace.h:290
void write_tile_buffer(const RenderWork &render_work)
void tile_buffer_read()
bool set_render_tile_pixels(PassAccessor &pass_accessor, const PassAccessor::Source &source)
void render(const RenderWork &render_work)
Film * film_
Definition path_trace.h:269
string full_report() const
void adaptive_sample(RenderWork &render_work)
void load_kernels()
const BufferParams & get_render_tile_params() const
struct PathTrace::@031215327331345151264042216111247320217046075201 render_cancel_
int get_num_render_tile_samples() const
void flush_display()
RenderScheduler & render_scheduler_
Definition path_trace.h:272
int get_num_samples_in_buffer()
void cryptomatte_postprocess(const RenderWork &render_work)
void update_allocated_work_buffer_params()
#define CCL_NAMESPACE_END
#define condition(cond)
std::mutex thread_mutex
Definition thread.h:27
std::condition_variable thread_condition_variable
Definition thread.h:29