Blender V5.3
image_cache.h
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2011-2026 Blender Foundation
2 *
3 * SPDX-License-Identifier: Apache-2.0 */
4
5#pragma once
6
7#include "device/device.h"
8#include "device/memory.h"
9
10#include "util/hash.h"
11#include "util/set.h"
13
14#include <span>
15
17
18class DeviceQueue;
19class DeviceScene;
20class ImageLoader;
21class ImageMetaData;
22struct ImageTileStats;
23
24/* Eviction statistics tracking for ImageCache. All public methods are
25 * thread-safe; an internal mutex protects the counters and the evicted mask
26 * so callers can invoke these from parallel tile loaders without holding any
27 * other lock. */
29 /* Per-tile-descriptor flag set when a tile is evicted, to detect reloads. */
31
32 /* Current state. */
35
36 /* Cumulative counters. */
40
43
44 /* Reset all counters and the evicted mask. */
45 void reset();
46
47 /* Ensure the evicted mask can hold at least `size` entries. */
48 void resize(const size_t size);
49
50 /* Clear the evicted mask for a tile descriptor range. */
51 void clear_range(const size_t begin, const size_t end);
52
53 /* Record successful tile load. */
54 void load_tile(const size_t bit_index);
55
56 /* Record a tile eviction. */
57 void evict_tile(const size_t bit_index);
58
59 /* Record tiled memory allocation and free. */
60 void add_tiled_bytes(const size_t bytes);
61 void remove_tiled_bytes(const size_t bytes);
62
63 private:
64 thread_mutex mutex_;
65};
66
68 struct DeviceImageKey {
69 ImageDataType type;
70 InterpolationType interpolation;
71 int tile_size;
72
73 bool operator==(const DeviceImageKey &other) const
74 {
75 return type == other.type && interpolation == other.interpolation &&
76 tile_size == other.tile_size;
77 }
78
79 struct Hash {
80 size_t operator()(const DeviceImageKey &key) const
81 {
82 return hash_uint3(key.type, key.interpolation, key.tile_size);
83 }
84 };
85 };
86
87 /* TODO: doesn't this mutex need to be shared with image manager? */
88 thread_mutex device_mutex;
89
90 /* A device image may either contain a full resolution image, or a set of tiles
91 * from one or images packed together. */
92 struct DeviceImage : public device_image {
94
96
97 DeviceImageKey key() const;
98 };
99
100 static const int TILE_IMAGE_MAX_TILES = 64;
101 static_assert(TILE_IMAGE_MAX_TILES <= sizeof(uint64_t) * 8);
102
103 unique_ptr_vector<DeviceImage> images;
104 unordered_map<DeviceImageKey, size_t, DeviceImageKey::Hash> images_first_free;
105
106 unordered_set<device_image *> deferred_updates;
107
108 public:
110 ~ImageCache();
111
112 /* Image management. */
114 ImageLoader &loader,
115 const ImageMetaData &metadata,
116 const float texture_resolution,
117 KernelImageTexture &tex);
118
119 void load_image_tiled(const ImageMetaData &metadata, KernelImageTexture &tex);
120
122 std::span<KernelImageTexture> image_textures);
123
124 void free_image(DeviceScene &dscene, const KernelImageTexture &tex);
125
126 /* Tile request processing. */
127 void load_requested_tiles(Device &device,
128 DeviceScene &dscene,
129 const KernelImageTexture &tex,
130 ImageLoader &loader,
131 const ImageMetaData &metadata,
132 int miplevel_offset,
133 const uint8_t *access_state);
134
135 void load_requested_tile(Device &device,
136 DeviceScene &dscene,
137 const KernelImageTexture &tex,
138 KernelTileDescriptor &r_tile_descriptor,
139 int miplevel,
140 int x,
141 int y,
142 ImageLoader &loader,
143 const ImageMetaData &metadata,
144 int miplevel_offset);
145
146 /* Copy image cache data to device if modified. Either for all devices, or a single
147 * device whose queue is provided. */
148 void copy_to_device(DeviceScene &dscene);
149 void copy_to_device(DeviceScene &dscene, DeviceQueue &queue);
150
151 /* Collect statistics about image cache. */
152 void collect_statistics(DeviceScene &dscene,
153 const KernelImageTexture &tex,
154 const ImageMetaData &metadata,
155 ImageTileStats &tile_stats);
156
158 {
159 return stats;
160 }
161
162 void evict_unused(const Device &device,
163 DeviceScene &dscene,
164 std::span<KernelImageTexture> image_textures,
165 const uint8_t *access_state);
166
167 size_t memory_size(DeviceScene &dscene) const;
168
169 /* Free image cache device data. */
170 void device_free(DeviceScene &dscene);
171
172 private:
173 /* Full image */
174 device_image &alloc_full(Device &device,
175 const ImageDataType type,
176 const InterpolationType interpolation,
177 const ExtensionType extension,
178 const int64_t width,
179 const int64_t height,
180 uint &image_info_id);
181 void free_full(const uint image_info_id);
182
183 template<TypeDesc::BASETYPE FileFormat, typename StorageType>
184 device_image *load_full(Device &device,
185 ImageLoader &loader,
186 const ImageMetaData &metadata,
187 const InterpolationType interpolation,
188 const ExtensionType extension,
189 const float texture_resolution,
190 uint &image_info_id);
191
192 /* Tile descriptor management. */
193 void free_tiled_image(DeviceScene &dscene, const KernelImageTexture &tex);
194
195 /* Tiled image */
196 device_image &alloc_tile(Device &device,
197 ImageDataType type,
198 InterpolationType interpolation,
199 const int tile_size_padded,
200 KernelTileDescriptor &r_tile_descriptor);
201 void free_tile(const KernelTileDescriptor tile, const bool free_empty_image = true);
202
203 void load_tile(Device &device,
204 DeviceScene &dscene,
205 ImageLoader &loader,
206 const ImageMetaData &metadata,
207 InterpolationType interpolation,
208 ExtensionType extension,
209 int miplevel,
210 int x,
211 int y,
212 const size_t bit_index,
213 KernelTileDescriptor &r_tile_descriptor);
214
215 void copy_images_to_device_no_lock();
216
217 ImageCacheStats stats;
218};
219
long long int int64_t
unsigned long long int uint64_t
void load_requested_tiles(Device &device, DeviceScene &dscene, const KernelImageTexture &tex, ImageLoader &loader, const ImageMetaData &metadata, int miplevel_offset, const uint8_t *access_state)
void device_free(DeviceScene &dscene)
void load_image_tiled_descriptors(DeviceScene &dscene, std::span< KernelImageTexture > image_textures)
const ImageCacheStats & get_stats() const
void load_image_tiled(const ImageMetaData &metadata, KernelImageTexture &tex)
void free_image(DeviceScene &dscene, const KernelImageTexture &tex)
void load_requested_tile(Device &device, DeviceScene &dscene, const KernelImageTexture &tex, KernelTileDescriptor &r_tile_descriptor, int miplevel, int x, int y, ImageLoader &loader, const ImageMetaData &metadata, int miplevel_offset)
void collect_statistics(DeviceScene &dscene, const KernelImageTexture &tex, const ImageMetaData &metadata, ImageTileStats &tile_stats)
void evict_unused(const Device &device, DeviceScene &dscene, std::span< KernelImageTexture > image_textures, const uint8_t *access_state)
device_image * load_image_full(Device &device, ImageLoader &loader, const ImageMetaData &metadata, const float texture_resolution, KernelImageTexture &tex)
size_t memory_size(DeviceScene &dscene) const
void copy_to_device(DeviceScene &dscene)
device_image(Device *device, const char *name, const uint image_info_id, ImageDataType image_data_type, InterpolationType interpolation, ExtensionType extension)
Definition memory.cpp:218
#define CCL_NAMESPACE_END
uint hash_uint3(uint kx, uint ky, uint kz)
const ccl_global KernelWorkTile * tile
ccl_device_inline bool operator==(const float2 a, const float2 b)
void resize(const size_t size)
int64_t current_tiled_bytes
Definition image_cache.h:34
void remove_tiled_bytes(const size_t bytes)
void load_tile(const size_t bit_index)
void evict_tile(const size_t bit_index)
int64_t peak_tiled_bytes
Definition image_cache.h:42
int64_t total_evicted
Definition image_cache.h:38
vector< uint8_t > evicted_mask
Definition image_cache.h:30
int64_t total_reloaded
Definition image_cache.h:39
int64_t current_loaded
Definition image_cache.h:33
int64_t total_loaded
Definition image_cache.h:37
int64_t peak_loaded
Definition image_cache.h:41
void add_tiled_bytes(const size_t bytes)
void clear_range(const size_t begin, const size_t end)
size_t operator()(const DeviceImageKey &key) const
Definition image_cache.h:80
std::mutex thread_mutex
Definition thread.h:27
uint KernelTileDescriptor
ImageDataType
Definition types_image.h:35
InterpolationType
Definition types_image.h:24
ExtensionType
Definition types_image.h:80