Blender V5.3
cached_image.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2023 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#include <cstdint>
6#include <memory>
7#include <string>
8
9#include "BLI_hash.hh"
10#include "BLI_listbase.hh"
11#include "BLI_math_matrix.hh"
13#include "BLI_string.hh"
14#include "BLI_string_ref.hh"
15
16#include "RE_pipeline.h"
17
18#include "GPU_texture.hh"
19
21#include "IMB_imbuf.hh"
22#include "IMB_imbuf_types.hh"
23#include "IMB_metadata.hh"
24
25#include "BKE_cryptomatte.hh"
26#include "BKE_image.hh"
27#include "BKE_lib_id.hh"
28
29#include "DNA_ID.h"
30#include "DNA_image_types.h"
31
32#include "COM_cached_image.hh"
33#include "COM_context.hh"
34#include "COM_result.hh"
35#include "COM_utilities.hh"
36
37namespace blender::compositor {
38
39/* --------------------------------------------------------------------
40 * Cached Image Key.
41 */
42
44 const std::string pass_name,
45 const std::string view_name,
46 const int frame)
48{
49}
50
52{
53 return get_default_hash(this->layer_index, this->view_name, this->pass_name, this->frame);
54}
55
57{
58 return a.layer_index == b.layer_index && a.pass_name == b.pass_name &&
59 a.view_name == b.view_name && a.frame == b.frame;
60}
61
62/* --------------------------------------------------------------------
63 * Cached Image.
64 */
65
66/* Get the render layer in the given render result specified by the given image user. Returns
67 * nullptr if not found. */
68static RenderLayer *get_render_layer(const RenderResult *render_result,
69 const ImageUser &image_user)
70{
71 const ListBaseT<RenderLayer> *layers = &render_result->layers;
72 return static_cast<RenderLayer *>(BLI_findlink(layers, image_user.layer));
73}
74
75/* Get the index of the pass with the given name in the render layer specified by the given image
76 * user in the given render result. Returns -1 if not found. */
77static int get_pass_index(const RenderResult *render_result,
78 const ImageUser &image_user,
79 const char *name)
80{
81 const RenderLayer *render_layer = get_render_layer(render_result, image_user);
82 if (!render_layer) {
83 return -1;
84 }
85 return BLI_findstringindex(&render_layer->passes, name, offsetof(RenderPass, name));
86}
87
88/* Get the render pass in the given render layer specified by the given image user. */
89static RenderPass *get_render_pass(const RenderLayer *render_layer, const ImageUser &image_user)
90{
91 return static_cast<RenderPass *>(BLI_findlink(&render_layer->passes, image_user.pass));
92}
93
94/* Get the render pass in the given render result specified by the given image user. */
95static RenderPass *get_render_pass(const RenderResult *render_result, const ImageUser &image_user)
96{
97 if (!render_result) {
98 return nullptr;
99 }
100
101 const RenderLayer *render_layer = get_render_layer(render_result, image_user);
102 if (!render_layer) {
103 return nullptr;
104 }
105
106 return get_render_pass(render_layer, image_user);
107}
108
109/* Get the index of the view selected in the image user. If the image is not a multi-view image
110 * or only has a single view, then zero is returned. Otherwise, if the image is a multi-view
111 * image, the index of the selected view is returned. However, note that the value of the view
112 * member of the image user is not the actual index of the view. More specifically, the index 0
113 * is reserved to denote the special mode of operation "All", which dynamically selects the view
114 * whose name matches the view currently being rendered. It follows that the views are then
115 * indexed starting from 1. So for non zero view values, the actual index of the view is the
116 * value of the view member of the image user minus 1. */
117static int get_view_index(const Context &context,
118 const RenderResult *render_result,
119 const ImageUser &image_user)
120{
121 /* The image is not a multi-view image, so just return zero. */
122 if (!render_result) {
123 return 0;
124 }
125
126 const ListBaseT<RenderView> *views = &render_result->views;
127 /* There is only one view and its index is 0. */
128 if (BLI_listbase_count_at_most(views, 2) < 2) {
129 return 0;
130 }
131
132 const int view = image_user.view;
133 /* The view is not zero, which means it is manually specified and the actual index is then the
134 * view value minus 1. */
135 if (view != 0) {
136 return view - 1;
137 }
138
139 /* Otherwise, the view value is zero, denoting the special mode of operation "All", which finds
140 * the index of the view whose name matches the view currently being rendered. */
141 const char *view_name = context.get_view_name().data();
142 const int matched_view = BLI_findstringindex(views, view_name, offsetof(RenderView, name));
143
144 /* No view matches the view currently being rendered, so fallback to the first view. */
145 if (matched_view == -1) {
146 return 0;
147 }
148
149 return matched_view;
150}
151
152/* Get a copy of the image user that is appropriate to retrieve the needed image buffer from the
153 * image. This essentially sets the appropriate frame, pass, and view that corresponds to the
154 * given context and pass name. If the image is a multi-layer image, then the render_result
155 * argument should be set, otherwise, it is ignored. The image user will have a pass index of -1 if
156 * the pass/later were not found in the image for multi-layer images. */
158 const Image &image,
159 const RenderResult *render_result,
160 const ImageUser &image_user,
161 const char *pass_name)
162{
163 ImageUser image_user_for_pass = image_user;
164
165 /* Set the needed view. */
166 image_user_for_pass.view = get_view_index(context, render_result, image_user_for_pass);
167
168 /* Set the needed pass. */
170 image_user_for_pass.pass = get_pass_index(render_result, image_user_for_pass, pass_name);
171 BKE_image_multilayer_index(const_cast<RenderResult *>(render_result), &image_user_for_pass);
172 }
173 else {
174 BKE_image_multiview_index(&image, &image_user_for_pass);
175 }
176
177 return image_user_for_pass;
178}
179
180/* The image buffer might be stored as an sRGB 8-bit image, while the compositor expects linear
181 * float images, so compute a linear float buffer for the image buffer. This will also do linear
182 * space conversion and alpha pre-multiplication as needed. We could store those images in sRGB GPU
183 * textures and let the GPU do the linear space conversion, but the issues is that we don't control
184 * how the GPU does the conversion and so we get tiny differences across CPU and GPU compositing,
185 * and potentially even across GPUs/Drivers. Further, if alpha pre-multiplication is needed, we
186 * would need to do it ourself, which means alpha pre-multiplication will happen before linear
187 * space conversion, which would produce yet another difference. So we just do everything on the
188 * CPU, since this is already a cached resource.
189 *
190 * To avoid conflicts with other threads, create a new image buffer and assign all the necessary
191 * information to it, with IB_DO_NOT_TAKE_OWNERSHIP for buffers since a deep copy is not needed.
192 *
193 * The caller should free the returned image buffer. */
194static ImBuf *compute_linear_buffer(ImBuf *image_buffer)
195{
196 /* Do not pass the flags to the allocation function to avoid buffer allocation, but assign them
197 * after to retain important information like precision and alpha mode. */
198 ImBuf *linear_image_buffer = IMB_allocImBuf(image_buffer->x, image_buffer->y, ImBufFlags::Zero);
199 linear_image_buffer->color_mode = image_buffer->color_mode;
200 linear_image_buffer->flags = image_buffer->flags;
201
202 /* Assign the float buffer if it exists, as well as its number of channels. */
203 linear_image_buffer->float_buffer = image_buffer->float_buffer;
204 linear_image_buffer->channels = image_buffer->channels;
205
206 /* If no float buffer exists, assign it then compute a float buffer from it. This is the main
207 * call of this function. */
208 if (!linear_image_buffer->float_data()) {
209 linear_image_buffer->byte_buffer = image_buffer->byte_buffer;
210 IMB_float_from_byte(linear_image_buffer);
211 }
212
213 /* If the image buffer contained compressed data, assign them as well, but only if the color
214 * space of the buffer is linear or data, since we need linear data and can't preprocess the
215 * compressed buffer. If not, we fallback to the float buffer already assigned, which is
216 * guaranteed to exist as a fallback for compressed textures. */
217 const bool is_suitable_compressed_color_space =
220 if (image_buffer->ftype == IMB_FTYPE_DDS && is_suitable_compressed_color_space) {
221 linear_image_buffer->ftype = IMB_FTYPE_DDS;
222 linear_image_buffer->filepath = image_buffer->filepath;
223 }
224
225 return linear_image_buffer;
226}
227
228/* Returns the float type of a result given the channels count. */
229static ResultType float_type(const int channels_count)
230{
231 switch (channels_count) {
232 case 1:
233 return ResultType::Float;
234 case 2:
235 return ResultType::Float2;
236 case 3:
237 return ResultType::Float3;
238 case 4:
239 return ResultType::Color;
240 default:
241 break;
242 }
243
245 return ResultType::Color;
246}
247
248/* Returns the appropriate result type for the given render pass. The type is determined based on
249 * the channels count of the buffer for simple images, while channel IDs are also considered for
250 * multi-layer images since 3-channel passes can be RGB without alpha and 4-channel passes can be
251 * XYZW 4D vectors. */
252static ResultType get_pass_type(const RenderPass *render_pass)
253{
254 switch (render_pass->channels) {
255 case 1:
256 return ResultType::Float;
257 case 2:
258 return ResultType::Float2;
259 case 3:
260 if (STR_ELEM(render_pass->chan_id, "RGB", "rgb")) {
261 return ResultType::Color;
262 }
263 else {
264 return ResultType::Float3;
265 }
266 case 4:
267 if (STR_ELEM(render_pass->chan_id, "RGBA", "rgba")) {
268 return ResultType::Color;
269 }
270 else {
271 return ResultType::Float4;
272 }
273 default:
274 break;
275 }
276
278 return ResultType::Float;
279}
280
282 Image &image,
283 ImageUser &image_user,
284 const char *pass_name)
285 : result(context)
286{
287 /* We can't retrieve the needed image buffer yet, because we still need to assign the pass index
288 * to the image user in order to acquire the image buffer corresponding to the given pass name.
289 * However, in order to compute the pass index, we need the render result structure of the image
290 * to be initialized. So we first acquire a dummy image buffer since it initializes the image
291 * render result as a side effect. We also use that as a mean of validation, since we can early
292 * exit if the returned image buffer is nullptr. This image buffer can be immediately released.
293 * Since it carries no important information. */
294 ImBuf *initial_image_buffer = BKE_image_acquire_ibuf(&image, &image_user, nullptr);
295 BKE_image_release_ibuf(&image, initial_image_buffer, nullptr);
296 if (!initial_image_buffer) {
297 return;
298 }
299
300 RenderResult *render_result = BKE_image_acquire_renderresult(nullptr, &image);
301
302 ImageUser image_user_for_pass = compute_image_user_for_pass(
303 context, image, render_result, image_user, pass_name);
304
305 /* Pass or layer were not found. */
306 if (BKE_image_is_multilayer(&image) && image_user_for_pass.pass == -1) {
307 BKE_image_release_renderresult(nullptr, &image, render_result);
308 return;
309 }
310
312 const RenderPass *render_pass = get_render_pass(render_result, image_user_for_pass);
313 this->result.set_type(get_pass_type(render_pass));
314 }
315
316 this->populate_cryptomatte_meta_data(render_result, image_user_for_pass);
317
318 BKE_image_release_renderresult(nullptr, &image, render_result);
319
320 ImBuf *image_buffer = BKE_image_acquire_ibuf(&image, &image_user_for_pass, nullptr);
321 ImBuf *linear_image_buffer = compute_linear_buffer(image_buffer);
322
323 this->populate_meta_data(image_buffer);
324
325 const bool use_half_float = linear_image_buffer->foptions.flag & OPENEXR_HALF;
328 this->result.set_type(float_type(linear_image_buffer->channels));
329 }
330
331 /* For GPU, we wrap the texture returned by IMB module and free it ourselves in destructor. For
332 * CPU, we allocate the result and copy to it from the image buffer. */
333 if (context.use_gpu()) {
336 texture_ = IMB_create_gpu_texture("Image Texture", linear_image_buffer, flags);
337 this->result.share_data(texture_);
338 }
339 else {
340 const int2 size = int2(image_buffer->x, image_buffer->y);
341 if (linear_image_buffer->channels == 3 && this->result.type() == ResultType::Color) {
342 /* Color passes with no alpha could be stored in a Float3 type. */
343 Result buffer_result(context, float_type(image_buffer->channels), ResultPrecision::Full);
344 buffer_result.share_data(linear_image_buffer->float_buffer.data,
345 size,
346 linear_image_buffer->float_buffer.sharing_info);
347 this->result.allocate_texture(size);
348 parallel_for(size, [&](const int2 texel) {
349 this->result.store_pixel(texel,
350 Color(float4(buffer_result.load_pixel<float3>(texel), 1.0f)));
351 });
352 buffer_result.release();
353 }
354 else {
355 this->result.share_data(linear_image_buffer->float_buffer.data,
356 size,
357 linear_image_buffer->float_buffer.sharing_info);
358 }
359 }
360
361 if (flag_is_set(image_buffer->flags, ImBufFlags::HasDisplayWindow)) {
362 this->result.domain().display_size = int2(image_buffer->display_size);
363 this->result.domain().data_offset = int2(image_buffer->data_offset);
364 this->result.transform(
366 }
367
368 IMB_freeImBuf(linear_image_buffer);
369 BKE_image_release_ibuf(&image, image_buffer, nullptr);
370}
371
372void CachedImage::populate_cryptomatte_meta_data(const RenderResult *render_result,
373 const ImageUser &image_user)
374{
375 if (!render_result) {
376 return;
377 }
378
379 const RenderLayer *render_layer = get_render_layer(render_result, image_user);
380 if (!render_layer) {
381 return;
382 }
383
384 const RenderPass *render_pass = get_render_pass(render_layer, image_user);
385 if (!render_pass) {
386 return;
387 }
388
389 /* We assume the given pass is a Cryptomatte pass and retrieve its full name. If it wasn't a
390 * Cryptomatte pass, the checks below will fail anyways. */
391 const bool is_named_layer = render_layer->name[0] != '\0';
392 const std::string layer_prefix = is_named_layer ? std::string(render_layer->name) + "." : "";
393 const std::string combined_pass_name = layer_prefix + render_pass->name;
394 StringRef cryptomatte_layer_name = bke::cryptomatte::BKE_cryptomatte_extract_layer_name(
395 combined_pass_name);
396
397 struct StampCallbackData {
398 std::string cryptomatte_layer_name;
399 compositor::MetaData *meta_data;
400 };
401
402 /* Go over the stamp data and add any Cryptomatte related meta data. */
403 StampCallbackData callback_data = {cryptomatte_layer_name, &this->result.meta_data};
405 &callback_data,
406 render_result->stamp_data,
407 [](void *user_data, const char *key, char *value, int /*value_length*/) {
408 StampCallbackData *data = static_cast<StampCallbackData *>(user_data);
409
410 const std::string manifest_key = bke::cryptomatte::BKE_cryptomatte_meta_data_key(
411 data->cryptomatte_layer_name, "manifest");
412 if (key == manifest_key) {
413 data->meta_data->cryptomatte.manifest = value;
414 }
415
417 data->cryptomatte_layer_name, "hash");
418 if (key == hash_key) {
419 data->meta_data->cryptomatte.hash = value;
420 }
421
422 const std::string conversion_key = bke::cryptomatte::BKE_cryptomatte_meta_data_key(
423 data->cryptomatte_layer_name, "conversion");
424 if (key == conversion_key) {
425 data->meta_data->cryptomatte.conversion = value;
426 }
427 },
428 false);
429}
430
431void CachedImage::populate_meta_data(const ImBuf *image_buffer)
432{
434 image_buffer,
435 [](const char *key, const char *value, void *user_data) {
436 compositor::MetaData *meta_data = static_cast<compositor::MetaData *>(user_data);
437 meta_data->fields.add(key, value);
438 },
439 &this->result.meta_data);
440}
441
443{
444 this->result.release();
445 GPU_TEXTURE_FREE_SAFE(texture_);
446}
447
448/* --------------------------------------------------------------------
449 * Cached Image Container.
450 */
451
453{
454 /* First, delete all cached images that are no longer needed. */
455 for (auto &cached_images_for_id : map_.values()) {
456 cached_images_for_id.remove_if([](auto item) { return !item.value->needed; });
457 }
458 map_.remove_if([](auto item) { return item.value.is_empty(); });
459 update_counts_.remove_if([&](auto item) { return !map_.contains(item.key); });
460
461 /* Second, reset the needed status of the remaining cached images to false to ready them to
462 * track their needed status for the next evaluation. */
463 for (auto &cached_images_for_id : map_.values()) {
464 for (auto &value : cached_images_for_id.values()) {
465 value->needed = false;
466 }
467 }
468}
469
471 Image &image,
472 const ImageUser &image_user,
473 const char *pass_name)
474{
475 /* Compute the effective frame number of the image if it was animated. */
476 ImageUser image_user_for_frame = image_user;
477 BKE_image_user_frame_calc(&image, &image_user_for_frame, context.get_frame_number());
478
479 /* A view of 0 is a special value that means the current view being rendered so use the context
480 * view name. For other values, just convert the view index into a string and use it as the name,
481 * while this is not correct it works as the cache key and is very fast compared to reading the
482 * views from file and finding out their name. */
483 const std::string view_name = image_user.view == 0 ? std::string(context.get_view_name()) :
484 std::to_string(image_user.view);
485
486 const CachedImageKey key(image_user.layer, pass_name, view_name, image_user_for_frame.framenr);
487
488 const std::string library_key = image.id.lib ? image.id.lib->id.name : "";
489 const std::string id_key = std::string(image.id.name) + library_key;
490 auto &cached_images_for_id = map_.lookup_or_add_default(id_key);
491
492 /* Invalidate the cache for that image if it was changed since it was cached. */
493 if (!cached_images_for_id.is_empty() &&
494 image.runtime->update_count != update_counts_.lookup(id_key))
495 {
496 cached_images_for_id.clear();
497 }
498
499 auto &cached_image = *cached_images_for_id.lookup_or_add_cb(key, [&]() {
500 return std::make_unique<CachedImage>(context, image, image_user_for_frame, pass_name);
501 });
502
503 /* Store the current update count to later compare to and check if the image changed. */
504 update_counts_.add_overwrite(id_key, image.runtime->update_count);
505
506 cached_image.needed = true;
507 return cached_image.result;
508}
509
510} // namespace blender::compositor
#define STR_ELEM(...)
ID and Library types, which are fundamental for SDNA.
#define GPU_TEXTURE_FREE_SAFE(texture)
#define BLI_assert_unreachable()
bool add(const Key &key, const Value &value)
Definition BLI_map.hh:295
Result & get(Context &context, Image &image, const ImageUser &image_user, const char *pass_name)
CachedImageKey(const int layer_index, const std::string pass_name, const std::string view_name, const int frame)
CachedImage(Context &context, Image &image, ImageUser &image_user, const char *pass_name)
void share_data(const Result &source)
Definition result.cc:996
void store_pixel(const int2 &texel, const T &pixel_value)
void allocate_texture(const Domain domain, const bool from_pool=true, const std::optional< ResultStorageType > storage_type=std::nullopt)
Definition result.cc:554
void set_precision(ResultPrecision precision)
Definition result.cc:1154
void transform(const float3x3 &transformation)
Definition result.cc:1064
T load_pixel(const int2 &texel) const
void set_type(ResultType type)
Definition result.cc:1147
#define offsetof(t, d)
#define OPENEXR_HALF
if(state< num_states)
StringRef BKE_cryptomatte_extract_layer_name(StringRef render_pass_name)
std::string BKE_cryptomatte_meta_data_key(StringRef layer_name, StringRefNull key_name)
static ImageUser compute_image_user_for_pass(const Context &context, const Image &image, const RenderResult *render_result, const ImageUser &image_user, const char *pass_name)
static ResultType float_type(const int channels_count)
ColorSceneLinear4f< eAlpha::Premultiplied > Color
Definition COM_result.hh:96
bool operator==(const BokehKernelKey &a, const BokehKernelKey &b)
static ImBuf * compute_linear_buffer(ImBuf *image_buffer)
static ResultType get_pass_type(const RenderPass *render_pass)
static int get_pass_index(const RenderResult *render_result, const ImageUser &image_user, const char *name)
static RenderPass * get_render_pass(const RenderLayer *render_layer, const ImageUser &image_user)
static int get_view_index(const Context &context, const RenderResult *render_result, const ImageUser &image_user)
static RenderLayer * get_render_layer(const RenderResult *render_result, const ImageUser &image_user)
void parallel_for(const int2 range, const Function &function)
MatT from_location(const typename MatT::loc_type &location)
void BKE_image_user_frame_calc(Image *ima, ImageUser *iuser, int cfra)
RenderResult * BKE_image_acquire_renderresult(Scene *scene, Image *ima)
unsigned __int64 uint64_t
Definition BKE_text.h:91
void BKE_image_multiview_index(const Image *ima, ImageUser *iuser)
GPUTextureCreateFlags
Definition IMB_imbuf.hh:611
void BKE_image_release_renderresult(Scene *scene, Image *ima, RenderResult *render_result)
void IMB_float_from_byte(ImBuf *ibuf)
void * BLI_findlink(const ListBase *listbase, int number) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1)
Definition listbase.cc:541
bool IMB_colormanagement_space_is_scene_linear(const ColorSpace *colorspace)
int BLI_findstringindex(const ListBase *listbase, const char *id, int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1)
Definition listbase.cc:794
void IMB_freeImBuf(ImBuf *ibuf)
RenderPass * BKE_image_multilayer_index(RenderResult *rr, ImageUser *iuser)
BMesh const char void * data
int BLI_listbase_count_at_most(const ListBase *listbase, int count_max) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1)
Definition listbase.cc:518
uint32_t hash_key
ImBuf * IMB_allocImBuf(unsigned int x, unsigned int y, ImBufFlags flags)
ImBuf * BKE_image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock)
bool IMB_colormanagement_space_is_data(const ColorSpace *colorspace)
void BKE_stamp_info_callback(void *data, StampData *stamp_data, StampCallback callback, bool noskip)
gpu::Texture * IMB_create_gpu_texture(const char *name, ImBuf *ibuf, GPUTextureCreateFlags flags)
Definition util_gpu.cc:452
void IMB_metadata_foreach(const ImBuf *ibuf, IMBMetadataForeachCb callback, void *userdata)
constexpr uint64_t get_default_hash(const T &v, const Args &...args)
Definition BLI_hash.hh:252
bool BKE_image_is_multilayer(const Image *ima)
void BKE_image_release_ibuf(Image *ima, ImBuf *ibuf, void *lock)
const ColorSpace * colorspace
ImplicitSharingPtr sharing_info
ImbFormatOptions foptions
ImBufFloatBuffer float_buffer
ImBufByteBuffer byte_buffer
const float * float_data() const
std::string filepath
ImColorMode color_mode
eImbFileType ftype
ListBaseT< RenderPass > passes
Definition RE_pipeline.h:99
char name[RE_MAXNAME]
Definition RE_pipeline.h:94
struct StampData * stamp_data
ListBaseT< RenderView > views
ListBaseT< RenderLayer > layers
Map< std::string, std::string > fields