Blender V5.3
session/display_driver.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
7#include "util/half.h"
8#include "util/math_int2.h"
9#include "util/types.h"
10#include "util/vector.h"
11
13
14/* Info about the display device that will be used for graphics interop, so it
15 * can be verified if interop is compatible with the rendering device. */
28
29/* Handle to a native graphics API pixel buffer. If supported, the rendering device
30 * may write directly to this buffer instead of calling map_texture_buffer() and
31 * unmap_texture_buffer().
32 *
33 * This must be a pixel buffer with the specified with and height, and half float
34 * with RGBA channels. */
36 public:
39
44
45 /* Display Driver API. */
46
47 /* Assign handle. For Vulkan, this transfers ownership of the handle. */
48 void assign(GraphicsInteropDevice::Type type, int64_t handle, size_t size);
49 /* Is a handle assigned? */
50 bool is_empty() const;
51 /* Zero memory. */
52 void zero();
53 /* Clear handle. */
54 void clear();
55
56 /* Device graphics interop API. */
57
58 /* Get type of handle. */
60 /* Get size of buffer. */
61 size_t get_size() const;
62
63 /* Is there a new handle to take ownership of? */
64 bool has_new_handle() const;
65 /* Take ownership of the handle. */
67
68 /* Take ownership of zeroing the buffer. */
69 bool take_zero();
70
71 protected:
72 /* The handle is expected to be:
73 * - OpenGL: pixel buffer object ID.
74 * - Vulkan on Windows: opaque handle for VkBuffer.
75 * - Vulkan on Unix: opaque file descriptor for VkBuffer.
76 * - Metal: MTLBuffer with unified memory. */
79 bool own_handle_ = false;
80
81 /* Actual size of the memory, which must be `>= width * height * sizeof(half4)`. */
82 size_t size_ = 0;
83
84 /* Clear the entire buffer before doing partial write to it. */
85 bool need_zero_ = false;
86};
87
88/* Display driver for efficient interactive display of renders.
89 *
90 * Host applications implement this interface for viewport rendering. For best performance, we
91 * recommend:
92 * - Allocating a texture on the GPU to be interactively updated
93 * - Using the graphics interop mechanism to avoid CPU-GPU copying overhead
94 * - Using a dedicated or thread-safe graphics API context for updates, to avoid
95 * blocking the host application.
96 */
98 public:
99 DisplayDriver() = default;
100 virtual ~DisplayDriver() = default;
101
102 /* Render buffer parameters. */
103 struct Params {
104 public:
105 /* Render resolution, ignoring progressive resolution changes.
106 * The texture buffer should be allocated with this size. */
108
109 /* For border rendering, the full resolution of the render, and the offset within that larger
110 * render. */
113
114 bool modified(const Params &other) const
115 {
116 return !(full_offset == other.full_offset && full_size == other.full_size &&
117 size == other.size);
118 }
119 };
120
121 virtual void reset() {}
122 virtual void next_tile_begin() = 0;
123
124 /* Update the render from the rendering thread.
125 *
126 * Cycles periodically updates the render to be displayed. For multithreaded updates with
127 * potentially multiple rendering devices, it will call these methods as follows.
128 *
129 * if (driver.update_begin(params, width, height)) {
130 * parallel_for_each(rendering_device) {
131 * buffer = driver.map_texture_buffer();
132 * if (buffer) {
133 * fill(buffer);
134 * driver.unmap_texture_buffer();
135 * }
136 * }
137 * driver.update_end();
138 * }
139 *
140 * The parameters may dynamically change due to camera changes in the scene, and resources should
141 * be re-allocated accordingly.
142 *
143 * The width and height passed to update_begin() are the effective render resolution taking into
144 * account progressive resolution changes, which may be equal to or smaller than the params.size.
145 * For efficiency, changes in this resolution should be handled without re-allocating resources,
146 * but rather by using a subset of the full resolution buffer. */
147 virtual bool update_begin(const Params &params, const int width, const int height) = 0;
148 virtual void update_end() = 0;
149
150 /* Optionally flush outstanding display commands before ending the render loop. */
151 virtual void flush() {};
152
153 virtual half4 *map_texture_buffer() = 0;
154 virtual void unmap_texture_buffer() = 0;
155
157
158 /* Graphics interop to avoid CPU - GPU transfer. See GraphicsInteropBuffer for details. */
163
165
170
171 /* (De)activate graphics context required for editing or deleting the graphics interop
172 * object.
173 *
174 * For example, destruction of the CUDA object associated with an OpenGL requires the
175 * OpenGL context to be active. */
176 virtual void graphics_interop_activate() {};
178
179 /* Clear the display buffer by filling it with zeros. */
180 virtual void zero() = 0;
181
182 /* Draw the render using the native graphics API.
183 *
184 * Note that this may be called in parallel to updates. The implementation is responsible for
185 * mutex locking or other mechanisms to avoid conflicts.
186 *
187 * The parameters may have changed since the last update. The implementation is responsible for
188 * deciding to skip or adjust render display for such changes.
189 *
190 * Host application drawing the render buffer should use Session.draw(), which will
191 * call this method. */
192 virtual void draw(const Params &params) = 0;
193};
194
long long int int64_t
virtual void update_end()=0
virtual void next_tile_begin()=0
virtual void graphics_interop_update_buffer()
virtual void zero()=0
virtual void draw(const Params &params)=0
DisplayDriver()=default
virtual half4 * map_texture_buffer()=0
virtual ~DisplayDriver()=default
GraphicsInteropBuffer graphics_interop_buffer_
virtual bool update_begin(const Params &params, const int width, const int height)=0
virtual GraphicsInteropDevice graphics_interop_get_device()
virtual void unmap_texture_buffer()=0
virtual void graphics_interop_activate()
GraphicsInteropBuffer & graphics_interop_get_buffer()
virtual void graphics_interop_deactivate()
GraphicsInteropBuffer(const GraphicsInteropBuffer &other)=delete
GraphicsInteropBuffer()=default
void assign(GraphicsInteropDevice::Type type, int64_t handle, size_t size)
GraphicsInteropBuffer & operator=(const GraphicsInteropBuffer &other)=delete
GraphicsInteropDevice::Type type_
GraphicsInteropBuffer & operator=(GraphicsInteropBuffer &&other)=delete
GraphicsInteropDevice::Type get_type() const
GraphicsInteropBuffer(GraphicsInteropBuffer &&other)=delete
#define CCL_NAMESPACE_END
ccl_device_forceinline int2 make_int2(const int x, const int y)
bool modified(const Params &other) const
Definition half.h:53