Blender V5.3
path_trace_display.h
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2021-2022 Blender Foundation
2 *
3 * SPDX-License-Identifier: Apache-2.0 */
4
5#pragma once
6
8
9#include "util/half.h"
10#include "util/thread.h"
11#include "util/unique_ptr.h"
12
14
15class BufferParams;
16
17/* PathTraceDisplay is used for efficient render buffer display.
18 *
19 * The host applications implements a DisplayDriver, storing a render pass in a GPU-side
20 * textures. This texture is continuously updated by the path tracer and drawn by the host
21 * application.
22 *
23 * PathTraceDisplay is a wrapper around the DisplayDriver, adding thread safety, state tracking
24 * and error checking. */
25
27 public:
29 virtual ~PathTraceDisplay() = default;
30
31 /* Reset the display update pending state. Is called from the main thread immediately when
32 * requesting a session reset. */
33 void reset();
34 /* Reset the display for the new state of render session. Is called whenever session is reset,
35 * which happens on changes like viewport navigation or viewport dimension change.
36 *
37 * This call will configure parameters for a changed buffer and reset the texture state.
38 *
39 * When the `reset_rendering` a complete display reset happens. When it is false reset happens
40 * for a new state of the buffer parameters which is assumed to correspond to the next tile. */
41 void reset(const BufferParams &buffer_params, bool reset_rendering);
42
43 /* --------------------------------------------------------------------
44 * Update procedure.
45 *
46 * These calls indicates a desire of the caller to update content of the displayed texture. */
47
48 /* Returns true when update is ready. Update should be finished with update_end().
49 *
50 * If false is returned then no update is possible, and no update_end() call is needed.
51 *
52 * The texture width and height denotes an actual resolution of the underlying render result. */
53 bool update_begin(const int texture_width, const int texture_height);
54
55 void update_end();
56
57 /* Get currently configured texture size of the display (as configured by `update_begin()`. */
58 int2 get_texture_size() const;
59
60 /* --------------------------------------------------------------------
61 * Texture update from CPU buffer.
62 *
63 * NOTE: The PathTraceDisplay should be marked for an update being in process with
64 * `update_begin()`.
65 *
66 * Most portable implementation, which must be supported by all platforms. Might not be the most
67 * efficient one.
68 */
69
70 /* Copy buffer of rendered pixels of a given size into a given position of the texture.
71 *
72 * This function does not acquire a lock. The reason for this is to allow use of this function
73 * for partial updates from different devices. In this case the caller will acquire the lock
74 * once, update all the slices and release
75 * the lock once. This will ensure that draw() will never use partially updated texture. */
76 void copy_pixels_to_texture(const half4 *rgba_pixels,
77 const int texture_x,
78 const int texture_y,
79 const int pixels_width,
80 const int pixels_height);
81
82 /* --------------------------------------------------------------------
83 * Texture buffer mapping.
84 *
85 * This functionality is used to update GPU-side texture content without need to maintain CPU
86 * side buffer on the caller.
87 *
88 * NOTE: The PathTraceDisplay should be marked for an update being in process with
89 * `update_begin()`.
90 *
91 * NOTE: Texture buffer can not be mapped while graphics interoperability is active. This means
92 * that `map_texture_buffer()` is not allowed between `graphics_interop_begin()` and
93 * `graphics_interop_end()` calls.
94 */
95
96 /* Map pixels memory form texture to a buffer available for write from CPU. Width and height will
97 * define a requested size of the texture to write to.
98 * Upon success a non-null pointer is returned and the texture buffer is to be unmapped.
99 * If an error happens during mapping, or if mapping is not supported by this GPU display a
100 * null pointer is returned and the buffer is NOT to be unmapped.
101 *
102 * NOTE: Usually the implementation will rely on a GPU context of some sort, and the GPU context
103 * is often can not be bound to two threads simultaneously, and can not be released from a
104 * different thread. This means that the mapping API should be used from the single thread only,
105 */
108
109 /* --------------------------------------------------------------------
110 * Graphics interoperability.
111 *
112 * A special code path which allows to update texture content directly from the GPU compute
113 * device. Complementary part of DeviceGraphicsInterop.
114 *
115 * NOTE: Graphics interoperability can not be used while the texture buffer is mapped. This means
116 * that `graphics_interop_get_buffer()` is not allowed between `map_texture_buffer()` and
117 * `unmap_texture_buffer()` calls. */
118
119 /* Get PathTraceDisplay graphics interoperability information which acts as a destination for the
120 * device API. */
123
124 /* (De)activate GPU display for graphics interoperability outside of regular display update
125 * routines. */
128
129 /* --------------------------------------------------------------------
130 * Drawing.
131 */
132
133 /* Clear the texture by filling it with all zeroes.
134 *
135 * This call might happen in parallel with draw, but can never happen in parallel with the
136 * update.
137 *
138 * The actual zeroing can be deferred to a later moment. What is important is that after clear
139 * and before pixels update the drawing texture will be fully empty, and that partial update
140 * after clear will write new pixel values for an updating area, leaving everything else zeroed.
141 *
142 * If the GPU display supports graphics interoperability then the zeroing the display is to be
143 * delegated to the device via the `GraphicsInterop`. */
144 void zero();
145
146 /* Draw the current state of the texture.
147 *
148 * Returns true if this call did draw an updated state of the texture. */
149 bool draw();
150
151 /* Flush outstanding display commands before ending the render loop. */
152 void flush();
153
154 private:
155 /* Display driver implemented by the host application. */
157
158 /* Current display parameters */
159 thread_mutex mutex_;
160 DisplayDriver::Params params_;
161
162 /* Mark texture as its content has been updated.
163 * Used from places which knows that the texture content has been brought up-to-date, so that the
164 * drawing knows whether it can be performed, and whether drawing happened with an up-to-date
165 * texture state. */
166 void mark_texture_updated();
167
168 /* State of the update process. */
169 struct {
170 /* True when update is in process, indicated by `update_begin()` / `update_end()`. */
171 bool is_active = false;
172 } update_state_;
173
174 /* State of the texture, which is needed for an integration with render session and interactive
175 * updates and navigation. */
176 struct {
177 /* Texture is considered outdated after `reset()` until the next call of
178 * `copy_pixels_to_texture()`. */
179 bool is_outdated = true;
180
181 /* Texture size in pixels. */
182 int2 size = make_int2(0, 0);
183 } texture_state_;
184
185 /* State of the texture buffer. Is tracked to perform sanity checks. */
186 struct {
187 /* True when the texture buffer is mapped with `map_texture_buffer()`. */
188 bool is_mapped = false;
189 } texture_buffer_state_;
190};
191
static DBVT_INLINE btScalar size(const btDbvtVolume &a)
Definition btDbvt.cpp:52
virtual ~PathTraceDisplay()=default
int2 get_texture_size() const
PathTraceDisplay(unique_ptr< DisplayDriver > driver)
bool update_begin(const int texture_width, const int texture_height)
void copy_pixels_to_texture(const half4 *rgba_pixels, const int texture_x, const int texture_y, const int pixels_width, const int pixels_height)
GraphicsInteropBuffer & graphics_interop_get_buffer()
GraphicsInteropDevice graphics_interop_get_device()
#define CCL_NAMESPACE_END
ccl_device_forceinline int2 make_int2(const int x, const int y)
Definition half.h:53
std::mutex thread_mutex
Definition thread.h:27