Blender V5.3
device/device.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 <cstdlib>
8#include <functional>
9
10#include "bvh/params.h"
11
12#include "device/denoise.h"
13#include "device/memory.h"
14
15#include "util/profiling.h"
16#include "util/stats.h"
17#include "util/string.h"
18#include "util/thread.h"
19#include "util/types.h"
20#include "util/types_image.h"
21#include "util/unique_ptr.h"
22#include "util/vector.h"
23
25
26class BVH;
27class DeviceQueue;
29class Progress;
30class CPUKernels;
31class Scene;
32
33struct OSLGlobals;
35
36/* Device Types */
37
50
60
61#define DEVICE_MASK(type) (DeviceTypeMask)(1 << type)
62
70
78
80 public:
83 /* used for user preferences, should stay fixed with changing hardware config */
84 string id = "CPU";
85 int num = 0;
86 bool display_device = false; /* GPU is used as a display device. */
87 bool has_nanovdb = false; /* Support NanoVDB volumes. */
88 bool has_mnee_ = true; /* Support MNEE. */
89 bool has_osl = false; /* Support Open Shading Language. */
90 bool has_guiding = false; /* Support path guiding. */
91 bool has_profiling = false; /* Supports runtime collection of profiling info. */
92 bool has_peer_memory = false; /* GPU has P2P access to memory of another GPU. */
93 bool has_gpu_queue = false; /* Device supports GPU queue. */
94 bool use_hardware_raytracing = false; /* Use hardware instructions to accelerate ray tracing. */
95 bool use_metalrt_by_default = false; /* Use MetalRT by default. */
96 /* Indicate that device execution has been optimized by Blender or vendor developers.
97 * For LTS versions, this helps communicate that newer versions may have better performance. */
99 /* True if device's driver is above the minimal Blender required version, false otherwise.
100 * Needed for properly communicating this fact back to the user, who then can choose to upgrade
101 * the driver or do nothing.
102 *
103 * Default value is chosen to be true intentionally - assume compliant unless proven otherwise,
104 * especially since CPU devices do not have any minimal versions, as well as some GPU backends,
105 * for example CUDA. */
107
109 KERNEL_OPTIMIZATION_LEVEL_FULL; /* Optimization level applied to path tracing
110 * kernels (Metal only). */
111 DenoiserTypeMask denoisers = DENOISER_NONE; /* Supported denoiser types. */
112 int cpu_threads = 0;
114 string error_msg;
115
116 DeviceInfo() = default;
117
118 bool operator==(const DeviceInfo &info) const
119 {
120 /* Multiple Devices with the same ID would be very bad. */
121 assert(id != info.id ||
122 (type == info.type && num == info.num && description == info.description));
123 return id == info.id && use_hardware_raytracing == info.use_hardware_raytracing &&
125 }
126 bool operator!=(const DeviceInfo &info) const
127 {
128 return !(*this == info);
129 }
130
131 bool has_mnee() const
132 {
133 if (!has_mnee_) {
134 return false;
135 }
136
137 /* Shadow caustics not supported on HIP without hardware ray-tracing, see #160089.
138 * This is a more complex condition that can't be determined in device_hip_info,
139 * so there is a helper for it here. */
141 return false;
142 }
143 for (const DeviceInfo &info : multi_devices) {
144 if (info.type == DEVICE_HIP && !info.use_hardware_raytracing) {
145 return false;
146 }
147 }
148 return true;
149 }
150};
151
152/* Device */
153
154class Device {
155 friend class device_sub_ptr;
156
157 protected:
158 Device(const DeviceInfo &info_, Stats &stats_, Profiler &profiler_, bool headless_)
159 : info(info_), stats(stats_), profiler(profiler_), headless(headless_)
160 {
161 }
162
163 string error_msg;
165
166 virtual device_ptr mem_alloc_sub_ptr(device_memory & /*mem*/, size_t /*offset*/, size_t /*size*/)
167 {
168 /* Only required for devices that implement denoising. */
169 assert(false);
170 return (device_ptr)0;
171 }
172 virtual void mem_free_sub_ptr(device_ptr /*ptr*/){};
173
174 public:
175 /* noexcept needed to silence TBB warning. */
176 virtual ~Device() noexcept(false);
177
178 /* info */
180 virtual const string &error_message()
181 {
182 return error_msg;
183 }
185 {
186 return !error_message().empty();
187 }
188 virtual void set_error(const string &error);
189 virtual BVHLayoutMask get_bvh_layout_mask(uint64_t kernel_features) const = 0;
190
191 /* statistics */
194 bool headless = true;
195
196 /* constant memory */
197 virtual void const_copy_to(const char *name, void *host, const size_t size) = 0;
198
199 /* load/compile kernels, must be called before adding tasks */
200 virtual bool load_kernels(const uint64_t /*kernel_features*/)
201 {
202 return true;
203 }
204
205 virtual bool load_osl_kernels()
206 {
207 return true;
208 }
209
210 /* Request cancellation of any long-running work. */
211 virtual void cancel() {}
212
213 /* Report status and return true if device is ready for rendering. */
214 virtual bool is_ready(string & /*status*/) const
215 {
216 return true;
217 }
218
219 /* GPU device only functions.
220 * These may not be used on CPU or multi-devices. */
221
222 /* Create new queue for executing kernels in. */
224
225 /* CPU device only functions.
226 * These may not be used on GPU or multi-devices. */
227
228 /* Get CPU kernel functions for native instruction set. */
229 static const CPUKernels &get_cpu_kernels();
230 /* Acquire thread globals for CPU kernel execution. Creates them if needed,
231 * and updates all data pointers from the device's kernel globals. */
233 /* Release thread globals, allowing them to be destroyed. */
235 /* Get OpenShadingLanguage memory buffer. */
236 virtual OSLGlobals *get_cpu_osl_memory();
237
238 /* Image Cache. */
250
251 /* Acceleration structure building. */
252 virtual void build_bvh(BVH *bvh, Progress &progress, bool refit);
253 /* Used by Metal and OptiX. */
254 virtual void release_bvh(BVH * /*bvh*/) {}
255
256 /* Inform of BVH limits, return true to force-rebuild all BVHs and kernels. */
257 virtual bool set_bvh_limits(size_t /*instance_count*/, size_t /*max_prim_count*/)
258 {
259 return false;
260 }
261
262 /* multi device */
263 virtual int device_number(Device * /*sub_device*/)
264 {
265 return 0;
266 }
267
268 /* Called after kernel texture setup, and prior to integrator state setup. */
269 virtual void optimize_for_scene(Scene * /*scene*/) {}
270
271 virtual bool is_resident(device_ptr /*key*/, Device *sub_device)
272 {
273 /* Memory is always resident if this is not a multi device, regardless of whether the pointer
274 * is valid or not (since it may not have been allocated yet). */
275 return sub_device == this;
276 }
277
278 /* Return the real device pointer for mem on the given sub_device. */
279 virtual device_ptr mem_device_ptr(const device_memory &mem, Device *sub_device);
280
281 virtual bool check_peer_access(Device * /*peer_device*/)
282 {
283 return false;
284 }
285
286 /* Return true if all devices have unified image memory, where a host write to an image
287 * is immediately visible to the device. */
288 virtual bool has_unified_image_memory_all() const
289 {
290 return false;
291 }
292
293 virtual bool is_shared(const void * /*shared_pointer*/,
294 const device_ptr /*device_pointer*/,
295 Device * /*sub_device*/)
296 {
297 return false;
298 }
299
300 /* Graphics resources interoperability.
301 *
302 * The interoperability comes here by the meaning that the device is capable of computing result
303 * directly into a OpenGL, Vulkan or Metal buffer. */
304
305 /* Check display is to be updated using graphics interoperability.
306 * The interoperability can not be used is it is not supported by the device. But the device
307 * might also force disable the interoperability if it detects that it will be slower than
308 * copying pixels from the render buffer. */
309 virtual bool should_use_graphics_interop(const GraphicsInteropDevice & /*interop_device*/,
310 const bool /*log*/ = false)
311 {
312 return false;
313 }
314
315 /* Returns native buffer handle for device pointer. */
316 virtual void *get_native_buffer(device_ptr /*ptr*/)
317 {
318 return nullptr;
319 }
320
321 /* Guiding */
322
323 /* Returns path guiding device handle. */
324 virtual void *get_guiding_device() const;
325
326 /* Read back a device_memory byte buffer from device and OR values into the host buffer.
327 * The host buffer is not zeroed as part of this. */
328 virtual void mem_or_from_device(device_memory &mem);
329
330 /* Sub-devices */
331
332 /* Run given callback for every individual device which will be handling rendering.
333 * For the single device the callback is called for the device itself. For the multi-device the
334 * callback is only called for the sub-devices. */
335 virtual void foreach_device(const std::function<void(Device *)> &callback)
336 {
337 callback(this);
338 }
339
340 /* static */
342 Stats &stats,
344 bool headless);
345
346 static DeviceType type_from_string(const char *name);
347 static string string_from_type(DeviceType type);
349 static vector<DeviceInfo> available_devices(const uint device_type_mask = DEVICE_MASK_ALL);
350 static DeviceInfo dummy_device(const string &error_msg = "");
351 static string device_capabilities(const uint device_type_mask = DEVICE_MASK_ALL);
352 static DeviceInfo get_multi_device(const vector<DeviceInfo> &subdevices,
353 const int threads,
354 bool background);
355
356 /* Tag devices lists for update. */
357 static void tag_update();
358
359 static void free_memory();
360
361 protected:
362 /* Memory allocation, only accessed through device_memory. */
363 friend class MultiDevice;
364 friend class DeviceServer;
365 friend class device_memory;
366
367 virtual void *host_alloc(const MemoryType type, const size_t size);
368 virtual void host_free(const MemoryType type, void *host_pointer, const size_t size);
369
370 virtual void mem_alloc(device_memory &mem) = 0;
371 virtual void mem_copy_to(device_memory &mem) = 0;
372 virtual void mem_move_to_host(device_memory &mem) = 0;
373 virtual void mem_copy_from(
374 device_memory &mem, const size_t y, size_t w, const size_t h, size_t elem) = 0;
375 virtual void mem_zero(device_memory &mem) = 0;
376 virtual void mem_free(device_memory &mem) = 0;
377
378 private:
379 /* Indicted whether device types and devices lists were initialized. */
380 static bool need_types_update, need_devices_update;
381 static thread_mutex device_mutex;
382 static vector<DeviceInfo> &cuda_devices();
383 static vector<DeviceInfo> &optix_devices();
384 static vector<DeviceInfo> &cpu_devices();
385 static vector<DeviceInfo> &hip_devices();
386 static vector<DeviceInfo> &metal_devices();
387 static vector<DeviceInfo> &oneapi_devices();
388 static uint devices_initialized_mask;
389};
390
391/* Device, which is GPU, with some common functionality for GPU back-ends. */
392class GPUDevice : public Device {
393 protected:
394 GPUDevice(const DeviceInfo &info_, Stats &stats_, Profiler &profiler_, bool headless_)
395 : Device(info_, stats_, profiler_, headless_),
397 {
398 }
399
400 public:
401 ~GPUDevice() noexcept(false) override;
402
403 /* For GPUs that can use bindless textures in some way or another. */
407 bool need_image_info = false;
408 /* Returns true if the image info was copied to the device (meaning, some more
409 * re-initialization might be needed). */
410 virtual bool load_image_info(DeviceQueue *queue);
411
412 protected:
413 /* Memory allocation, only accessed through device_memory. */
414 friend class device_memory;
415
416 bool can_map_host = false;
417 size_t map_host_used = 0;
418 size_t map_host_limit = 0;
421 using texMemObject = unsigned long long;
422 using arrayMemObject = uintptr_t;
423 struct Mem {
424 Mem() = default;
425
428 };
429 using MemMap = map<device_memory *, Mem>;
432
433 virtual void init_host_memory(const size_t preferred_texture_headroom = 0,
434 const size_t preferred_working_headroom = 0);
435 virtual void move_textures_to_host(const size_t size,
436 const size_t headroom,
437 const bool for_texture);
438
439 /* Allocation, deallocation and copy functions, with corresponding
440 * support of device/host allocations. */
441 virtual GPUDevice::Mem *generic_alloc(device_memory &mem, const size_t pitch_padding = 0);
442 virtual void generic_free(device_memory &mem);
443 virtual void generic_copy_to(device_memory &mem);
444
445 /* total - amount of device memory, free - amount of available device memory */
446 virtual void get_device_memory_info(size_t &total, size_t &free) = 0;
447
448 /* Device side memory. */
449 virtual bool alloc_device(void *&device_pointer, const size_t size) = 0;
450 virtual void free_device(void *device_pointer) = 0;
451
452 /* Shared memory. */
453 virtual bool shared_alloc(void *&shared_pointer, const size_t size) = 0;
454 virtual void shared_free(void *shared_pointer, const size_t size) = 0;
455 bool is_shared(const void *shared_pointer,
456 const device_ptr device_pointer,
457 Device *sub_device) override;
458 /* This function should return device pointer corresponding to shared pointer, which
459 * is host buffer, allocated in `shared_alloc`. */
460 virtual void *shared_to_device_pointer(const void *shared_pointer) = 0;
461
462 /* Memory copy. */
463 virtual void copy_host_to_device(void *device_pointer,
464 void *host_pointer,
465 const size_t size) = 0;
466
467 /* Update image info on the host, growing buffer if needed. */
468 void image_info_update(uint image_info_id, const KernelImageInfo &info);
469};
470
unsigned long long int uint64_t
void refit(btStridingMeshInterface *triangles, const btVector3 &aabbMin, const btVector3 &aabbMax)
SIMD_FORCE_INLINE const btScalar & w() const
Return the w value.
Definition btQuadWord.h:119
Definition bvh/bvh.h:67
bool has_mnee() const
bool has_execution_optimization
bool meets_driver_requirement
KernelOptimizationLevel kernel_optimization_level
vector< DeviceInfo > multi_devices
DenoiserTypeMask denoisers
bool operator==(const DeviceInfo &info) const
bool display_device
string error_msg
bool has_peer_memory
bool has_gpu_queue
bool operator!=(const DeviceInfo &info) const
bool use_metalrt_by_default
DeviceInfo()=default
bool has_profiling
DeviceType type
string description
bool use_hardware_raytracing
virtual void host_free(const MemoryType type, void *host_pointer, const size_t size)
virtual void optimize_for_scene(Scene *)
virtual void * get_guiding_device() const
virtual const string & error_message()
virtual bool is_resident(device_ptr, Device *sub_device)
virtual void release_bvh(BVH *)
static void free_memory()
virtual bool is_shared(const void *, const device_ptr, Device *)
static DeviceInfo dummy_device(const string &error_msg="")
Device(const DeviceInfo &info_, Stats &stats_, Profiler &profiler_, bool headless_)
static DeviceInfo get_multi_device(const vector< DeviceInfo > &subdevices, const int threads, bool background)
static void tag_update()
virtual bool is_ready(string &) const
static const CPUKernels & get_cpu_kernels()
virtual bool load_osl_kernels()
friend class device_sub_ptr
virtual void mem_move_to_host(device_memory &mem)=0
virtual void mem_zero(device_memory &mem)=0
string error_msg
void image_load_requested_gpu(DeviceQueue &queue)
virtual BVHLayoutMask get_bvh_layout_mask(uint64_t kernel_features) const =0
KernelImageLoadRequestedGPU image_load_requested_gpu_
virtual void * get_native_buffer(device_ptr)
virtual int device_number(Device *)
friend class MultiDevice
friend class device_memory
virtual ~Device() noexcept(false)
virtual void mem_free_sub_ptr(device_ptr)
virtual unique_ptr< DeviceQueue > gpu_queue_create()
Profiler & profiler
Stats & stats
virtual void const_copy_to(const char *name, void *host, const size_t size)=0
virtual void build_bvh(BVH *bvh, Progress &progress, bool refit)
virtual device_ptr mem_device_ptr(const device_memory &mem, Device *sub_device)
static DeviceType type_from_string(const char *name)
virtual void set_error(const string &error)
bool headless
virtual bool should_use_graphics_interop(const GraphicsInteropDevice &, const bool=false)
virtual bool check_peer_access(Device *)
virtual void mem_free(device_memory &mem)=0
virtual void mem_or_from_device(device_memory &mem)
virtual void mem_copy_from(device_memory &mem, const size_t y, size_t w, const size_t h, size_t elem)=0
virtual bool has_unified_image_memory_all() const
virtual void mem_copy_to(device_memory &mem)=0
virtual void set_image_cache_func(KernelImageLoadRequestedCPU, KernelImageLoadRequestedGPU image_load_requested_gpu)
virtual device_ptr mem_alloc_sub_ptr(device_memory &, size_t, size_t)
virtual vector< ThreadKernelGlobalsCPU > * acquire_cpu_kernel_thread_globals()
friend class DeviceServer
DeviceInfo info
static string device_capabilities(const uint device_type_mask=DEVICE_MASK_ALL)
virtual bool set_bvh_limits(size_t, size_t)
static vector< DeviceType > available_types()
virtual void foreach_device(const std::function< void(Device *)> &callback)
static string string_from_type(DeviceType type)
virtual void mem_alloc(device_memory &mem)=0
virtual OSLGlobals * get_cpu_osl_memory()
static vector< DeviceInfo > available_devices(const uint device_type_mask=DEVICE_MASK_ALL)
static unique_ptr< Device > create(const DeviceInfo &info, Stats &stats, Profiler &profiler, bool headless)
virtual void cancel()
virtual void release_cpu_kernel_thread_globals()
virtual bool load_kernels(const uint64_t)
bool have_error()
virtual void * host_alloc(const MemoryType type, const size_t size)
bool is_shared(const void *shared_pointer, const device_ptr device_pointer, Device *sub_device) override
virtual bool shared_alloc(void *&shared_pointer, const size_t size)=0
virtual bool load_image_info(DeviceQueue *queue)
size_t map_host_used
GPUDevice(const DeviceInfo &info_, Stats &stats_, Profiler &profiler_, bool headless_)
map< device_memory *, Mem > MemMap
unsigned long long texMemObject
bool can_map_host
virtual void get_device_memory_info(size_t &total, size_t &free)=0
virtual bool alloc_device(void *&device_pointer, const size_t size)=0
size_t device_working_headroom
bool need_image_info
friend class device_memory
void image_info_update(uint image_info_id, const KernelImageInfo &info)
virtual void * shared_to_device_pointer(const void *shared_pointer)=0
virtual void generic_copy_to(device_memory &mem)
virtual void move_textures_to_host(const size_t size, const size_t headroom, const bool for_texture)
virtual void shared_free(void *shared_pointer, const size_t size)=0
thread_mutex image_info_mutex
virtual void copy_host_to_device(void *device_pointer, void *host_pointer, const size_t size)=0
device_vector< KernelImageInfo > image_info
size_t map_host_limit
virtual void free_device(void *device_pointer)=0
thread_mutex device_mem_map_mutex
virtual void generic_free(device_memory &mem)
virtual void init_host_memory(const size_t preferred_texture_headroom=0, const size_t preferred_working_headroom=0)
size_t device_image_headroom
uintptr_t arrayMemObject
thread_mutex image_info_resize_mutex
virtual GPUDevice::Mem * generic_alloc(device_memory &mem, const size_t pitch_padding=0)
MemMap device_mem_map
~GPUDevice() noexcept(false) override
Definition scene.h:133
@ MEM_FLAG_NO_HOST_FALLBACK
int DenoiserTypeMask
Definition denoise.h:24
@ DENOISER_NONE
Definition denoise.h:17
#define CCL_NAMESPACE_END
KernelOptimizationLevel
@ KERNEL_OPTIMIZATION_LEVEL_OFF
@ KERNEL_OPTIMIZATION_LEVEL_FULL
@ KERNEL_OPTIMIZATION_LEVEL_INTERSECT
@ KERNEL_OPTIMIZATION_NUM_LEVELS
DeviceTypeMask
@ DEVICE_MASK_OPTIX
@ DEVICE_MASK_CPU
@ DEVICE_MASK_HIP
@ DEVICE_MASK_ALL
@ DEVICE_MASK_CUDA
@ DEVICE_MASK_METAL
@ DEVICE_MASK_ONEAPI
MetalRTSetting
@ METALRT_OFF
@ METALRT_NUM_SETTINGS
@ METALRT_ON
@ METALRT_AUTO
DeviceType
@ DEVICE_DUMMY
@ DEVICE_NONE
@ DEVICE_METAL
@ DEVICE_MULTI
@ DEVICE_CUDA
@ DEVICE_CPU
@ DEVICE_HIPRT
@ DEVICE_OPTIX
@ DEVICE_HIP
@ DEVICE_ONEAPI
#define assert(assertion)
int BVHLayoutMask
Definition params.h:50
texMemObject texobject
Mem()=default
arrayMemObject array
std::mutex thread_mutex
Definition thread.h:27
uint64_t device_ptr
Definition types_base.h:44
std::function< void(size_t, int, int, int, KernelTileDescriptor &tile_descriptor)> KernelImageLoadRequestedCPU
std::function< void(DeviceQueue &)> KernelImageLoadRequestedGPU