HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
imagecache.h
Go to the documentation of this file.
1 // Copyright 2008-present Contributors to the OpenImageIO project.
2 // SPDX-License-Identifier: BSD-3-Clause
3 // https://github.com/OpenImageIO/oiio
4 
5 // clang-format off
6 
7 
8 
9 #pragma once
10 
11 #include <OpenImageIO/imageio.h>
12 #include <OpenImageIO/ustring.h>
13 
14 
15 // Define symbols that let client applications determine if newly added
16 // features are supported.
17 
18 // Is the close() method present?
19 #define OIIO_IMAGECACHE_SUPPORTS_CLOSE 1
20 
21 // Does invalidate() support the optional `force` flag?
22 #define OIIO_IMAGECACHE_INVALIDATE_FORCE 1
23 
24 
25 
27 
28 namespace pvt {
29 // Forward declaration
30 class ImageCacheImpl;
31 class ImageCacheFile;
32 class ImageCacheTile;
33 class ImageCachePerThreadInfo;
34 }; // namespace pvt
35 
36 
37 
38 /// Define an API to an abstract class that manages image files,
39 /// caches of open file handles as well as tiles of pixels so that truly
40 /// huge amounts of image data may be accessed by an application with low
41 /// memory footprint.
43 public:
44  /// @{
45  /// @name Creating and destroying an image cache
46  ///
47  /// ImageCache is an abstract API described as a pure virtual class.
48  /// The actual internal implementation is not exposed through the
49  /// external API of OpenImageIO. Because of this, you cannot construct
50  /// or destroy the concrete implementation, so two static methods of
51  /// ImageCache are provided:
52 
53  /// Create a ImageCache and return a raw pointer to it. This should
54  /// only be freed by passing it to `ImageCache::destroy()`!
55  ///
56  /// @param shared
57  /// If `true`, the pointer returned will be a shared ImageCache (so
58  /// that multiple parts of an application that request an ImageCache
59  /// will all end up with the same one). If `shared` is `false`, a
60  /// completely unique ImageCache will be created and returned.
61  ///
62  /// @returns
63  /// A raw pointer to an ImageCache, which can only be freed with
64  /// `ImageCache::destroy()`.
65  ///
66  /// @see ImageCache::destroy
67  static ImageCache* create(bool shared = true);
68 
69  /// Destroy an allocated ImageCache, including freeing all system
70  /// resources that it holds.
71  ///
72  /// It is safe to destroy even a shared ImageCache, as the implementation
73  /// of `destroy()` will recognize a shared one and only truly release
74  /// its resources if it has been requested to be destroyed as many times as
75  /// shared ImageCache's were created.
76  ///
77  /// @param cache
78  /// Raw pointer to the ImageCache to destroy.
79  ///
80  /// @param teardown
81  /// For a shared ImageCache, if the `teardown` parameter is
82  /// `true`, it will try to truly destroy the shared cache if
83  /// nobody else is still holding a reference (otherwise, it will
84  /// leave it intact). This parameter has no effect if `cache` was
85  /// not the single globally shared ImageCache.
86  static void destroy(ImageCache* cache, bool teardown = false);
87 
88  /// @}
89 
90 
91  /// @{
92  /// @name Setting options and limits for the image cache
93  ///
94  /// These are the list of attributes that can bet set or queried by
95  /// attribute/getattribute:
96  ///
97  /// - `int max_open_files` :
98  /// The maximum number of file handles that the image cache
99  /// will hold open simultaneously. (Default = 100)
100  /// - `float max_memory_MB` :
101  /// The maximum amount of memory (measured in MB) used for the
102  /// internal "tile cache." (Default: 256.0 MB)
103  /// - `string searchpath` :
104  /// The search path for images: a colon-separated list of
105  /// directories that will be searched in order for any image
106  /// filename that is not specified as an absolute path.
107  /// (Default: "")
108  /// - `string plugin_searchpath` :
109  /// The search path for plugins: a colon-separated list of
110  /// directories that will be searched in order for any OIIO
111  /// plugins, if not found in OIIO's `lib` directory.
112  /// (Default: "")
113  /// - `int autotile` ,
114  /// `int autoscanline` :
115  /// These attributes control how the image cache deals with
116  /// images that are not "tiled" (i.e., are stored as
117  /// scanlines).
118  ///
119  /// If `autotile` is set to 0 (the default), an untiled image
120  /// will be treated as if it were a single tile of the
121  /// resolution of the whole image. This is simple and fast,
122  /// but can lead to poor cache behavior if you are
123  /// simultaneously accessing many large untiled images.
124  ///
125  /// If `autotile` is nonzero (e.g., 64 is a good recommended
126  /// value), any untiled images will be read and cached as if
127  /// they were constructed in tiles of size:
128  ///
129  /// - `autotile * autotile`
130  /// if `autoscanline` is 0
131  /// - `width * autotile`
132  /// if `autoscanline` is nonzero.
133  ///
134  /// In both cases, this should lead more efficient caching.
135  /// The `autoscanline` determines whether the "virtual tiles"
136  /// in the cache are square (if `autoscanline` is 0, the
137  /// default) or if they will be as wide as the image (but only
138  /// `autotile` scanlines high). You should try in your
139  /// application to see which leads to higher performance.
140  /// - `int autoscanline` :
141  /// autotile using full width tiles
142  /// - `int automip` :
143  /// If 0 (the default), an untiled single-subimage file will
144  /// only be able to utilize that single subimage.
145  /// If nonzero, any untiled, single-subimage (un-MIP-mapped)
146  /// images will have lower-resolution MIP-map levels generated
147  /// on-demand if pixels are requested from the lower-res
148  /// subimages (that don't really exist). Essentially this
149  /// makes the ImageCache pretend that the file is MIP-mapped
150  /// even if it isn't.
151  /// - `int accept_untiled` :
152  /// When nonzero, ImageCache accepts untiled images as usual.
153  /// When zero, ImageCache will reject untiled images with an
154  /// error condition, as if the file could not be properly
155  /// read. This is sometimes helpful for applications that want
156  /// to enforce use of tiled images only. (default=1)
157  /// - `int accept_unmipped` :
158  /// When nonzero, ImageCache accepts un-MIPmapped images as
159  /// usual. When set to zero, ImageCache will reject
160  /// un-MIPmapped images with an error condition, as if the
161  /// file could not be properly read. This is sometimes helpful
162  /// for applications that want to enforce use of MIP-mapped
163  /// images only. (Default: 1)
164  /// - `int statistics:level` :
165  /// verbosity of statistics auto-printed.
166  /// - `int forcefloat` :
167  /// If set to nonzero, all image tiles will be converted to
168  /// `float` type when stored in the image cache. This can be
169  /// helpful especially for users of ImageBuf who want to
170  /// simplify their image manipulations to only need to
171  /// consider `float` data. The default is zero, meaning that
172  /// image pixels are not forced to be `float` when in cache.
173  /// - `int failure_retries` :
174  /// When an image file is opened or a tile/scanline is read but
175  /// a file error occurs, if this attribute is nonzero, it will
176  /// try the operation again up to this many times before giving
177  /// up and reporting a failure. Setting this to a small nonzero
178  /// number (like 3) may help make an application more robust to
179  /// occasional spurious networking or other glitches that would
180  /// otherwise cause the entire long-running application to fail
181  /// upon a single transient error. (Default: 0)
182  /// - `int deduplicate` :
183  /// When nonzero, the ImageCache will notice duplicate images
184  /// under different names if their headers contain a SHA-1
185  /// fingerprint (as is done with `maketx`-produced textures)
186  /// and handle them more efficiently by avoiding redundant
187  /// reads. The default is 1 (de-duplication turned on). The
188  /// only reason to set it to 0 is if you specifically want to
189  /// disable the de-duplication optimization.
190  /// - `string substitute_image` :
191  /// When set to anything other than the empty string, the
192  /// ImageCache will use the named image in place of *all*
193  /// other images. This allows you to run an app using OIIO
194  /// and (if you can manage to get this option set)
195  /// automagically substitute a grid, zone plate, or other
196  /// special debugging image for all image/texture use.
197  /// - `int unassociatedalpha` :
198  /// When nonzero, will request that image format readers try
199  /// to leave input images with unassociated alpha as they are,
200  /// rather than automatically converting to associated alpha
201  /// upon reading the pixels. The default is 0, meaning that
202  /// the automatic conversion will take place.
203  /// - `int max_errors_per_file` :
204  /// The maximum number of errors that will be printed for each
205  /// file. The default is 100. If your output is cluttered with
206  /// error messages and after the first few for each file you
207  /// aren't getting any helpful additional information, this
208  /// can cut down on the clutter and the runtime. (default:
209  /// 100)
210  /// - `int trust_file_extensions` :
211  /// When nonzero, assume that the file extensions of any
212  /// texture requests correctly indicates the file format (when
213  /// enabled, this reduces the number of file opens, at the
214  /// expense of not being able to open files if their format do
215  /// not actually match their filename extension). Default: 0
216  ///
217  /// - `string options`
218  /// This catch-all is simply a comma-separated list of
219  /// `name=value` settings of named options, which will be
220  /// parsed and individually set. Example:
221  ///
222  /// ic->attribute ("options", "max_memory_MB=512.0,autotile=1");
223  ///
224  /// Note that if an option takes a string value that must
225  /// itself contain a comma, it is permissible to enclose the
226  /// value in either single (` ' ' `) or double (` " " `) quotes.
227  ///
228  /// **Read-only attributes**
229  ///
230  /// Additionally, there are some read-only attributes that can be
231  /// queried with `getattribute()` even though they cannot be set via
232  /// `attribute()`:
233  ///
234  /// - `int total_files` :
235  /// The total number of unique file names referenced by calls
236  /// to the ImageCache.
237  ///
238  /// - `string[] all_filenames` :
239  /// An array that will be filled with the list of the names of
240  /// all files referenced by calls to the ImageCache. (The
241  /// array is of `ustring` or `char*`.)
242  ///
243  /// - `int64 stat:cache_memory_used` :
244  /// Total bytes used by tile cache.
245  ///
246  /// - `int stat:tiles_created` ,
247  /// `int stat:tiles_current` ,
248  /// `int stat:tiles_peak` :
249  /// Total times created, still allocated (at the time of the
250  /// query), and the peak number of tiles in memory at any
251  /// time.
252  ///
253  /// - `int stat:open_files_created` ,
254  /// `int stat:open_files_current` ,
255  /// `int stat:open_files_peak` :
256  /// Total number of times a file was opened, number still
257  /// opened (at the time of the query), and the peak number of
258  /// files opened at any time.
259  ///
260  /// - `int stat:find_tile_calls` :
261  /// Number of times a filename was looked up in the file cache.
262  ///
263  /// - `int64 stat:image_size` :
264  /// Total size (uncompressed bytes of pixel data) of all
265  /// images referenced by the ImageCache. (Note: Prior to 1.7,
266  /// this was called `stat:files_totalsize`.)
267  ///
268  /// - `int64 stat:file_size` :
269  /// Total size of all files (as on disk, possibly compressed)
270  /// of all images referenced by the ImageCache.
271  ///
272  /// - `int64 stat:bytes_read` :
273  /// Total size (uncompressed bytes of pixel data) read.
274  ///
275  /// - `int stat:unique_files` :
276  /// Number of unique files opened.
277  ///
278  /// - `float stat:fileio_time` :
279  /// Total I/O-related time (seconds).
280  ///
281  /// - `float stat:fileopen_time` :
282  /// I/O time related to opening and reading headers (but not
283  /// pixel I/O).
284  ///
285  /// - `float stat:file_locking_time` :
286  /// Total time (across all threads) that threads blocked
287  /// waiting for access to the file data structures.
288  ///
289  /// - `float stat:tile_locking_time` :
290  /// Total time (across all threads) that threads blocked
291  /// waiting for access to the tile cache data structures.
292  ///
293  /// - `float stat:find_file_time` :
294  /// Total time (across all threads) that threads spent looking
295  /// up files by name.
296  ///
297  /// - `float stat:find_tile_time` :
298  /// Total time (across all threads) that threads spent looking
299  /// up individual tiles.
300  ///
301  /// The following member functions of ImageCache allow you to set (and
302  /// in some cases retrieve) options that control the overall behavior of
303  /// the image cache:
304 
305  /// Set a named attribute (i.e., a property or option) of the
306  /// ImageCache.
307  ///
308  /// Example:
309  ///
310  /// ImageCache *ic;
311  /// ...
312  /// int maxfiles = 50;
313  /// ic->attribute ("max_open_files", TypeDesc::INT, &maxfiles);
314  ///
315  /// const char *path = "/my/path";
316  /// ic->attribute ("searchpath", TypeDesc::STRING, &path);
317  ///
318  /// // There are specialized versions for setting a single int,
319  /// // float, or string without needing types or pointers:
320  /// ic->attribute ("max_open_files", 50);
321  /// ic->attribute ("max_memory_MB", 4000.0f);
322  /// ic->attribute ("searchpath", "/my/path");
323  ///
324  /// Note: When passing a string, you need to pass a pointer to the
325  /// `char*`, not a pointer to the first character. (Rationale: for an
326  /// `int` attribute, you pass the address of the `int`. So for a
327  /// string, which is a `char*`, you need to pass the address of the
328  /// string, i.e., a `char**`).
329  ///
330  /// @param name Name of the attribute to set.
331  /// @param type TypeDesc describing the type of the attribute.
332  /// @param val Pointer to the value data.
333  /// @returns `true` if the name and type were recognized and the
334  /// attribute was set, or `false` upon failure
335  /// (including it being an unrecognized attribute or not
336  /// of the correct type).
337  ///
338  virtual bool attribute (string_view name, TypeDesc type,
339  const void *val) = 0;
340 
341  /// Specialized `attribute()` for setting a single `int` value.
342  virtual bool attribute (string_view name, int val) = 0;
343  /// Specialized `attribute()` for setting a single `float` value.
344  virtual bool attribute (string_view name, float val) = 0;
345  virtual bool attribute (string_view name, double val) = 0;
346  /// Specialized `attribute()` for setting a single string value.
347  virtual bool attribute (string_view name, string_view val) = 0;
348 
349  /// Get the named attribute, store it in `*val`. All of the attributes
350  /// that may be set with the `attribute() call` may also be queried with
351  /// `getattribute()`.
352  ///
353  /// Examples:
354  ///
355  /// ImageCache *ic;
356  /// ...
357  /// int maxfiles;
358  /// ic->getattribute ("max_open_files", TypeDesc::INT, &maxfiles);
359  ///
360  /// const char *path;
361  /// ic->getattribute ("searchpath", TypeDesc::STRING, &path);
362  ///
363  /// // There are specialized versions for retrieving a single int,
364  /// // float, or string without needing types or pointers:
365  /// int maxfiles;
366  /// ic->getattribute ("max_open_files", maxfiles);
367  /// const char *path;
368  /// ic->getattribute ("searchpath", &path);
369  ///
370  /// Note: When retrieving a string, you need to pass a pointer to the
371  /// `char*`, not a pointer to the first character. Also, the `char*`
372  /// will end up pointing to characters owned by the ImageCache; the
373  /// caller does not need to ever free the memory that contains the
374  /// characters.
375  ///
376  /// @param name Name of the attribute to retrieve.
377  /// @param type TypeDesc describing the type of the attribute.
378  /// @param val Pointer where the attribute value should be stored.
379  /// @returns `true` if the name and type were recognized and the
380  /// attribute was retrieved, or `false` upon failure
381  /// (including it being an unrecognized attribute or not
382  /// of the correct type).
383  virtual bool getattribute (string_view name, TypeDesc type,
384  void *val) const = 0;
385 
386  /// Specialized `attribute()` for retrieving a single `int` value.
387  virtual bool getattribute (string_view name, int &val) const = 0;
388  /// Specialized `attribute()` for retrieving a single `float` value.
389  virtual bool getattribute (string_view name, float &val) const = 0;
390  virtual bool getattribute (string_view name, double &val) const = 0;
391  /// Specialized `attribute()` for retrieving a single `string` value
392  /// as a `char*`.
393  virtual bool getattribute (string_view name, char **val) const = 0;
394  /// Specialized `attribute()` for retrieving a single `string` value
395  /// as a `std::string`.
396  virtual bool getattribute (string_view name, std::string &val) const = 0;
397 
398  /// @}
399 
400 
401  /// @{
402  /// @name Opaque data for performance lookups
403  ///
404  /// The ImageCache implementation needs to maintain certain per-thread
405  /// state, and some methods take an opaque `Perthread` pointer to this
406  /// record. There are three options for how to deal with it:
407  ///
408  /// 1. Don't worry about it at all: don't use the methods that want
409  /// `Perthread` pointers, or always pass `nullptr` for any
410  /// `Perthread*1 arguments, and ImageCache will do
411  /// thread-specific-pointer retrieval as necessary (though at some
412  /// small cost).
413  ///
414  /// 2. If your app already stores per-thread information of its own, you
415  /// may call `get_perthread_info(nullptr)` to retrieve it for that
416  /// thread, and then pass it into the functions that allow it (thus
417  /// sparing them the need and expense of retrieving the
418  /// thread-specific pointer). However, it is crucial that this
419  /// pointer not be shared between multiple threads. In this case, the
420  /// ImageCache manages the storage, which will automatically be
421  /// released when the thread terminates.
422  ///
423  /// 3. If your app also wants to manage the storage of the `Perthread`,
424  /// it can explicitly create one with `create_perthread_info()`, pass
425  /// it around, and eventually be responsible for destroying it with
426  /// `destroy_perthread_info()`. When managing the storage, the app
427  /// may reuse the `Perthread` for another thread after the first is
428  /// terminated, but still may not use the same `Perthread` for two
429  /// threads running concurrently.
430 
431  /// Define an opaque data type that allows us to have a pointer to
432  /// certain per-thread information that the ImageCache maintains. Any
433  /// given one of these should NEVER be shared between running threads.
434  typedef pvt::ImageCachePerThreadInfo Perthread;
435 
436  /// Retrieve a Perthread, unique to the calling thread. This is a
437  /// thread-specific pointer that will always return the Perthread for a
438  /// thread, which will also be automatically destroyed when the thread
439  /// terminates.
440  ///
441  /// Applications that want to manage their own Perthread pointers (with
442  /// `create_thread_info` and `destroy_thread_info`) should still call
443  /// this, but passing in their managed pointer. If the passed-in
444  /// thread_info is not NULL, it won't create a new one or retrieve a
445  /// TSP, but it will do other necessary housekeeping on the Perthread
446  /// information.
447  virtual Perthread* get_perthread_info(Perthread* thread_info = NULL) = 0;
448 
449  /// Create a new Perthread. It is the caller's responsibility to
450  /// eventually destroy it using `destroy_thread_info()`.
451  virtual Perthread* create_thread_info() = 0;
452 
453  /// Destroy a Perthread that was allocated by `create_thread_info()`.
454  virtual void destroy_thread_info(Perthread* thread_info) = 0;
455 
456  /// Define an opaque data type that allows us to have a handle to an
457  /// image (already having its name resolved) but without exposing any
458  /// internals.
459  typedef pvt::ImageCacheFile ImageHandle;
460 
461  /// Retrieve an opaque handle for fast image lookups. The filename is
462  /// presumed to be UTF-8 encoded. The opaque `pointer thread_info` is
463  /// thread-specific information returned by `get_perthread_info()`.
464  /// Return NULL if something has gone horribly wrong.
465  virtual ImageHandle* get_image_handle (ustring filename,
466  Perthread *thread_info=NULL) = 0;
467 
468  /// Get an ImageHandle using a UTF-16 encoded wstring filename.
469  ImageHandle* get_image_handle (const std::wstring& filename,
470  Perthread *thread_info=NULL) {
471  return get_image_handle (ustring(Strutil::utf16_to_utf8(filename)),
472  thread_info);
473  }
474 
475  /// Return true if the image handle (previously returned by
476  /// `get_image_handle()`) is a valid image that can be subsequently read.
477  virtual bool good(ImageHandle* file) = 0;
478 
479  /// Given a handle, return the filename for that image.
480  ///
481  /// This method was added in OpenImageIO 2.3.
482  virtual ustring filename_from_handle(ImageHandle* handle) = 0;
483 
484  /// @}
485 
486 
487  /// @{
488  /// @name Getting information about images
489  ///
490 
491  /// Given possibly-relative `filename` (UTF-8 encoded), resolve it and use
492  /// the true path to the file, with searchpath logic applied.
493  virtual std::string resolve_filename(const std::string& filename) const = 0;
494 
495  /// Get information or metadata about the named image and store it in
496  /// `*data`.
497  ///
498  /// Data names may include any of the following:
499  ///
500  /// - `"exists"` : Stores the value 1 (as an `int`) if the file exists and
501  /// is an image format that OpenImageIO can read, or 0 if the file
502  /// does not exist, or could not be properly read as an image. Note
503  /// that unlike all other queries, this query will "succeed" (return
504  /// `true`) even if the file does not exist.
505  ///
506  /// - `"udim"` : Stores the value 1 (as an `int`) if the file is a
507  /// "virtual UDIM" or texture atlas file (as described in
508  /// :ref:`sec-texturesys-udim`) or 0 otherwise.
509  ///
510  /// - `"subimages"` : The number of subimages in the file, as an `int`.
511  ///
512  /// - `"resolution"` : The resolution of the image file, which is an
513  /// array of 2 integers (described as `TypeDesc(INT,2)`).
514  ///
515  /// - `"miplevels"` : The number of MIPmap levels for the specified
516  /// subimage (an integer).
517  ///
518  /// - `"texturetype"` : A string describing the type of texture of the
519  /// given file, which describes how the texture may be used (also
520  /// which texture API call is probably the right one for it). This
521  /// currently may return one of: `"unknown"`, `"Plain Texture"`,
522  /// `"Volume Texture"`, `"Shadow"`, or `"Environment"`.
523  ///
524  /// - `"textureformat"` : A string describing the format of the given
525  /// file, which describes the kind of texture stored in the file. This
526  /// currently may return one of: `"unknown"`, `"Plain Texture"`,
527  /// `"Volume Texture"`, `"Shadow"`, `"CubeFace Shadow"`,
528  /// `"Volume Shadow"`, `"LatLong Environment"`, or
529  /// `"CubeFace Environment"`. Note that there are several kinds of
530  /// shadows and environment maps, all accessible through the same API
531  /// calls.
532  ///
533  /// - `"channels"` : The number of color channels in the file (an
534  /// `int`).
535  ///
536  /// - `"format"` : The native data format of the pixels in the file (an
537  /// integer, giving the `TypeDesc::BASETYPE` of the data). Note that
538  /// this is not necessarily the same as the data format stored in the
539  /// image cache.
540  ///
541  /// - `"cachedformat"` : The native data format of the pixels as stored
542  /// in the image cache (an integer, giving the `TypeDesc::BASETYPE` of
543  /// the data). Note that this is not necessarily the same as the
544  /// native data format of the file.
545  ///
546  /// - `"datawindow"` : Returns the pixel data window of the image, which
547  /// is either an array of 4 integers (returning xmin, ymin, xmax,
548  /// ymax) or an array of 6 integers (returning xmin, ymin, zmin, xmax,
549  /// ymax, zmax). The z values may be useful for 3D/volumetric images;
550  /// for 2D images they will be 0).
551  ///
552  /// - `"displaywindow"` : Returns the display (a.k.a. "full") window of
553  /// the image, which is either an array of 4 integers (returning xmin,
554  /// ymin, xmax, ymax) or an array of 6 integers (returning xmin, ymin,
555  /// zmin, xmax, ymax, zmax). The z values may be useful for
556  /// 3D/volumetric images; for 2D images they will be 0).
557  ///
558  /// - `"worldtocamera"` : The viewing matrix, which is a 4x4 matrix (an
559  /// `Imath::M44f`, described as `TypeDesc(FLOAT,MATRIX)`), giving the
560  /// world-to-camera 3D transformation matrix that was used when the
561  /// image was created. Generally, only rendered images will have this.
562  ///
563  /// - `"worldtoscreen"` : The projection matrix, which is a 4x4 matrix
564  /// (an `Imath::M44f`, described as `TypeDesc(FLOAT,MATRIX)`), giving
565  /// the matrix that projected points from world space into a 2D screen
566  /// coordinate system where $x$ and $y$ range from -1 to +1.
567  /// Generally, only rendered images will have this.
568  ///
569  /// - `"worldtoNDC"` : The projection matrix, which is a 4x4 matrix
570  /// (an `Imath::M44f`, described as `TypeDesc(FLOAT,MATRIX)`), giving
571  /// the matrix that projected points from world space into a 2D NDC
572  /// coordinate system where $x$ and $y$ range from 0 to +1. Generally,
573  /// only rendered images will have this.
574  ///
575  /// - `"averagecolor"` : If available in the metadata (generally only
576  /// for files that have been processed by `maketx`), this will return
577  /// the average color of the texture (into an array of `float`).
578  ///
579  /// - `"averagealpha"` : If available in the metadata (generally only
580  /// for files that have been processed by `maketx`), this will return
581  /// the average alpha value of the texture (into a `float`).
582  ///
583  /// - `"constantcolor"` : If the metadata (generally only for files that
584  /// have been processed by `maketx`) indicates that the texture has
585  /// the same values for all pixels in the texture, this will retrieve
586  /// the constant color of the texture (into an array of floats). A
587  /// non-constant image (or one that does not have the special metadata
588  /// tag identifying it as a constant texture) will fail this query
589  /// (return `false`).
590  ///
591  /// - `"constantalpha"` : If the metadata indicates that the texture has
592  /// the same values for all pixels in the texture, this will retrieve
593  /// the constant alpha value of the texture (into a float). A
594  /// non-constant image (or one that does not have the special metadata
595  /// tag identifying it as a constant texture) will fail this query
596  /// (return `false`).
597  ///
598  /// - `"stat:tilesread"` : Number of tiles read from this file
599  /// (`int64`).
600  ///
601  /// - `"stat:bytesread"` : Number of bytes of uncompressed pixel data
602  /// read from this file (`int64`).
603  ///
604  /// - `"stat:redundant_tiles"` : Number of times a tile was read, where
605  /// the same tile had been rad before. (`int64`).
606  ///
607  /// - `"stat:redundant_bytesread"` : Number of bytes (of uncompressed
608  /// pixel data) in tiles that were read redundantly. (`int64`).
609  ///
610  /// - `"stat:redundant_bytesread"` : Number of tiles read from this file (`int`).
611  ///
612  /// - `"stat:image_size"` : Size of the uncompressed image pixel data
613  /// of this image, in bytes (`int64`).
614  ///
615  /// - `"stat:file_size"` : Size of the disk file (possibly compressed)
616  /// for this image, in bytes (`int64`).
617  ///
618  /// - `"stat:timesopened"` : Number of times this file was opened
619  /// (`int`).
620  ///
621  /// - `"stat:iotime"` : Time (in seconds) spent on all I/O for this file
622  /// (`float`).
623  ///
624  /// - `"stat:mipsused"` : Stores 1 if any MIP levels beyond the highest
625  /// resolution were accessed, otherwise 0. (`int`)
626  ///
627  /// - `"stat:is_duplicate"` : Stores 1 if this file was a duplicate of
628  /// another image, otherwise 0. (`int`)
629  ///
630  /// - *Anything else* : For all other data names, the the metadata of
631  /// the image file will be searched for an item that matches both the
632  /// name and data type.
633  ///
634  ///
635  ///
636  /// @param filename
637  /// The name of the image, as a UTF-8 encoded ustring.
638  /// @param subimage/miplevel
639  /// The subimage and MIP level to query.
640  /// @param dataname
641  /// The name of the metadata to retrieve.
642  /// @param datatype
643  /// TypeDesc describing the data type.
644  /// @param data
645  /// Pointer to the caller-owned memory where the values
646  /// should be stored. It is the caller's responsibility to
647  /// ensure that `data` points to a large enough storage area
648  /// to accommodate the `datatype` requested.
649  ///
650  /// @returns
651  /// `true` if `get_image_info()` is able to find the
652  /// requested `dataname` for the image and it matched the
653  /// requested `datatype`. If the requested data was not
654  /// found or was not of the right data type, return `false`.
655  /// Except for the `"exists"` query, a file that does not
656  /// exist or could not be read properly as an image also
657  /// constitutes a query failure that will return `false`.
658  virtual bool get_image_info (ustring filename, int subimage, int miplevel,
659  ustring dataname, TypeDesc datatype, void *data) = 0;
660  /// A more efficient variety of `get_image_info()` for cases where you
661  /// can use an `ImageHandle*` to specify the image and optionally have a
662  /// `Perthread*` for the calling thread.
663  virtual bool get_image_info (ImageHandle *file, Perthread *thread_info,
664  int subimage, int miplevel,
665  ustring dataname, TypeDesc datatype, void *data) = 0;
666 
667  /// Copy the ImageSpec associated with the named image (the first
668  /// subimage & miplevel by default, or as set by `subimage` and
669  /// `miplevel`).
670  ///
671  /// @param filename
672  /// The name of the image, as a UTF-8 encoded ustring.
673  /// @param spec
674  /// ImageSpec into which will be copied the spec for the
675  /// requested image.
676  /// @param subimage/miplevel
677  /// The subimage and MIP level to query.
678  /// @param native
679  /// If `false` (the default), then the spec retrieved will
680  /// accurately describe the image stored internally in the
681  /// cache, whereas if `native` is `true`, the spec retrieved
682  /// will reflect the contents of the original file. These
683  /// may differ due to use of certain ImageCache settings
684  /// such as `"forcefloat"` or `"autotile"`.
685  /// @returns
686  /// `true` upon success, `false` upon failure failure (such
687  /// as being unable to find, open, or read the file, or if
688  /// it does not contain the designated subimage or MIP
689  /// level).
690  virtual bool get_imagespec (ustring filename, ImageSpec &spec,
691  int subimage=0, int miplevel=0,
692  bool native=false) = 0;
693  /// A more efficient variety of `get_imagespec()` for cases where you
694  /// can use an `ImageHandle*` to specify the image and optionally have a
695  /// `Perthread*` for the calling thread.
696  virtual bool get_imagespec (ImageHandle *file, Perthread *thread_info,
697  ImageSpec &spec,
698  int subimage=0, int miplevel=0,
699  bool native=false) = 0;
700 
701  /// Return a pointer to an ImageSpec associated with the named image
702  /// (the first subimage & MIP level by default, or as set by `subimage`
703  /// and `miplevel`) if the file is found and is an image format that can
704  /// be read, otherwise return `nullptr`.
705  ///
706  /// This method is much more efficient than `get_imagespec()`, since it
707  /// just returns a pointer to the spec held internally by the ImageCache
708  /// (rather than copying the spec to the user's memory). However, the
709  /// caller must beware that the pointer is only valid as long as nobody
710  /// (even other threads) calls `invalidate()` on the file, or
711  /// `invalidate_all()`, or destroys the ImageCache.
712  ///
713  /// @param filename
714  /// The name of the image, as a UTF-8 encoded ustring.
715  /// @param subimage/miplevel
716  /// The subimage and MIP level to query.
717  /// @param native
718  /// If `false` (the default), then the spec retrieved will
719  /// accurately describe the image stored internally in the
720  /// cache, whereas if `native` is `true`, the spec retrieved
721  /// will reflect the contents of the original file. These
722  /// may differ due to use of certain ImageCache settings
723  /// such as `"forcefloat"` or `"autotile"`.
724  /// @returns
725  /// A pointer to the spec, if the image is found and able to
726  /// be opened and read by an available image format plugin,
727  /// and the designated subimage and MIP level exists.
728  virtual const ImageSpec *imagespec (ustring filename, int subimage=0,
729  int miplevel=0, bool native=false) = 0;
730  /// A more efficient variety of `imagespec()` for cases where you can
731  /// use an `ImageHandle*` to specify the image and optionally have a
732  /// `Perthread*` for the calling thread.
733  virtual const ImageSpec *imagespec (ImageHandle *file,
734  Perthread *thread_info,
735  int subimage=0, int miplevel=0,
736  bool native=false) = 0;
737 
738  /// Copy into `thumbnail` any associated thumbnail associated with this
739  /// image (for the first subimage by default, or as set by `subimage`).
740  ///
741  /// @param filename
742  /// The name of the image, as a UTF-8 encoded ustring.
743  /// @param thumbnail
744  /// ImageBuf into which will be copied the thumbnail, if it
745  /// exists. If no thumbnail can be retrieved, `thumb` will
746  /// be reset to an uninitialized (empty) ImageBuf.
747  /// @param subimage
748  /// The subimage to query.
749  /// @returns
750  /// `true` upon success, `false` upon failure failure (such
751  /// as being unable to find, open, or read the file, or if
752  /// it does not contain a thumbnail).
753  virtual bool get_thumbnail (ustring filename, ImageBuf& thumbnail,
754  int subimage=0) = 0;
755  /// A more efficient variety of `get_thumbnail()` for cases where you
756  /// can use an `ImageHandle*` to specify the image and optionally have a
757  /// `Perthread*` for the calling thread.
758  virtual bool get_thumbnail (ImageHandle *file, Perthread *thread_info,
759  ImageBuf& thumbnail, int subimage=0) = 0;
760  /// @}
761 
762  /// @{
763  /// @name Getting Pixels
764 
765  /// For an image specified by name, retrieve the rectangle of pixels
766  /// from the designated subimage and MIP level, storing the pixel values
767  /// beginning at the address specified by `result` and with the given
768  /// strides. The pixel values will be converted to the data type
769  /// specified by `format`. The rectangular region to be retrieved
770  /// includes `begin` but does not include `end` (much like STL begin/end
771  /// usage). Requested pixels that are not part of the valid pixel data
772  /// region of the image file will be filled with zero values.
773  ///
774  /// @param filename
775  /// The name of the image, as a UTF-8 encoded ustring.
776  /// @param subimage/miplevel
777  /// The subimage and MIP level to retrieve pixels from.
778  /// @param xbegin/xend/ybegin/yend/zbegin/zend
779  /// The range of pixels to retrieve. The pixels retrieved
780  /// include the begin value but not the end value (much like
781  /// STL begin/end usage).
782  /// @param chbegin/chend
783  /// Channel range to retrieve. To retrieve all channels, use
784  /// `chbegin = 0`, `chend = nchannels`.
785  /// @param format
786  /// TypeDesc describing the data type of the values you want
787  /// to retrieve into `result`. The pixel values will be
788  /// converted to this type regardless of how they were
789  /// stored in the file.
790  /// @param result
791  /// Pointer to the memory where the pixel values should be
792  /// stored. It is up to the caller to ensure that `result`
793  /// points to an area of memory big enough to accommodate
794  /// the requested rectangle (taking into consideration its
795  /// dimensions, number of channels, and data format).
796  /// @param xstride/ystride/zstride
797  /// The number of bytes between the beginning of successive
798  /// pixels, scanlines, and image planes, respectively. Any
799  /// stride values set to `AutoStride` will be assumed to
800  /// indicate a contiguous data layout in that dimension.
801  /// @param cache_chbegin/cache_chend These parameters can be used to
802  /// tell the ImageCache to read and cache a subset of
803  /// channels (if not specified or if they denote a
804  /// non-positive range, all the channels of the file will be
805  /// stored in the cached tile).
806  ///
807  /// @returns
808  /// `true` for success, `false` for failure.
809  virtual bool get_pixels (ustring filename,
810  int subimage, int miplevel, int xbegin, int xend,
811  int ybegin, int yend, int zbegin, int zend,
812  int chbegin, int chend, TypeDesc format, void *result,
813  stride_t xstride=AutoStride, stride_t ystride=AutoStride,
814  stride_t zstride=AutoStride,
815  int cache_chbegin = 0, int cache_chend = -1) = 0;
816  /// A more efficient variety of `get_pixels()` for cases where you can
817  /// use an `ImageHandle*` to specify the image and optionally have a
818  /// `Perthread*` for the calling thread.
819  virtual bool get_pixels (ImageHandle *file, Perthread *thread_info,
820  int subimage, int miplevel, int xbegin, int xend,
821  int ybegin, int yend, int zbegin, int zend,
822  int chbegin, int chend, TypeDesc format, void *result,
823  stride_t xstride=AutoStride, stride_t ystride=AutoStride,
824  stride_t zstride=AutoStride,
825  int cache_chbegin = 0, int cache_chend = -1) = 0;
826 
827  /// A simplified `get_pixels()` where all channels are retrieved,
828  /// strides are assumed to be contiguous.
829  virtual bool get_pixels (ustring filename, int subimage, int miplevel,
830  int xbegin, int xend, int ybegin, int yend,
831  int zbegin, int zend,
832  TypeDesc format, void *result) = 0;
833  /// A more efficient variety of `get_pixels()` for cases where you can
834  /// use an `ImageHandle*` to specify the image and optionally have a
835  /// `Perthread*` for the calling thread.
836  virtual bool get_pixels (ImageHandle *file, Perthread *thread_info,
837  int subimage, int miplevel,
838  int xbegin, int xend, int ybegin, int yend,
839  int zbegin, int zend,
840  TypeDesc format, void *result) = 0;
841  /// @}
842 
843  /// @{
844  /// @name Controlling the cache
845  ///
846 
847  /// Invalidate any loaded tiles or open file handles associated with the
848  /// filename (UTF-8 encoded), so that any subsequent queries will be
849  /// forced to re-open the file or re-load any tiles (even those that were
850  /// previously loaded and would ordinarily be reused). A client might do
851  /// this if, for example, they are aware that an image being held in the
852  /// cache has been updated on disk. This is safe to do even if other
853  /// procedures are currently holding reference-counted tile pointers from
854  /// the named image, but those procedures will not get updated pixels
855  /// until they release the tiles they are holding.
856  ///
857  /// If `force` is true, this invalidation will happen unconditionally; if
858  /// false, the file will only be invalidated if it has been changed since
859  /// it was first opened by the ImageCache.
860  virtual void invalidate(ustring filename, bool force = true) = 0;
861 
862  /// A more efficient variety of `invalidate()` for cases where you
863  /// already have an `ImageHandle*` for the file you want to invalidate.
864  virtual void invalidate(ImageHandle* file, bool force = true) = 0;
865 
866  /// Invalidate all loaded tiles and close open file handles. This is
867  /// safe to do even if other procedures are currently holding
868  /// reference-counted tile pointers from the named image, but those
869  /// procedures will not get updated pixels (if the images change) until
870  /// they release the tiles they are holding.
871  ///
872  /// If `force` is true, everything will be invalidated, no matter how
873  /// wasteful it is, but if `force` is false, in actuality files will
874  /// only be invalidated if their modification times have been changed
875  /// since they were first opened.
876  virtual void invalidate_all(bool force = false) = 0;
877 
878  /// Close any open file handles associated with a named file (UTF-8
879  /// encoded), but do not invalidate any image spec information or pixels
880  /// associated with the files. A client might do this in order to release
881  /// OS file handle resources, or to make it safe for other processes to
882  /// modify image files on disk.
883  virtual void close (ustring filename) = 0;
884 
885  /// `close()` all files known to the cache.
886  virtual void close_all () = 0;
887 
888  /// An opaque data type that allows us to have a pointer to a tile but
889  /// without exposing any internals.
890  typedef pvt::ImageCacheTile Tile;
891 
892  /// Find the tile specified by an image filename (UTF-8 encoded), subimage
893  /// & miplevel, the coordinates of a pixel, and optionally a channel
894  /// range. An opaque pointer to the tile will be returned, or `nullptr`
895  /// if no such file (or tile within the file) exists or can be read. The
896  /// tile will not be purged from the cache until after `release_tile()` is
897  /// called on the tile pointer the same number of times that `get_tile()`
898  /// was called (reference counting). This is thread-safe! If `chend <
899  /// chbegin`, it will retrieve a tile containing all channels in the file.
900  virtual Tile * get_tile (ustring filename, int subimage, int miplevel,
901  int x, int y, int z,
902  int chbegin = 0, int chend = -1) = 0;
903  /// A slightly more efficient variety of `get_tile()` for cases where
904  /// you can use an `ImageHandle*` to specify the image and optionally
905  /// have a `Perthread*` for the calling thread.
906  ///
907  /// @see `get_pixels()`
908  virtual Tile * get_tile (ImageHandle *file, Perthread *thread_info,
909  int subimage, int miplevel,
910  int x, int y, int z,
911  int chbegin = 0, int chend = -1) = 0;
912 
913  /// After finishing with a tile, release_tile will allow it to
914  /// once again be purged from the tile cache if required.
915  virtual void release_tile(Tile* tile) const = 0;
916 
917  /// Retrieve the data type of the pixels stored in the tile, which may
918  /// be different than the type of the pixels in the disk file.
919  virtual TypeDesc tile_format(const Tile* tile) const = 0;
920 
921  /// Retrieve the ROI describing the pixels and channels stored in the
922  /// tile.
923  virtual ROI tile_roi(const Tile* tile) const = 0;
924 
925  /// For a tile retrived by `get_tile()`, return a pointer to the pixel
926  /// data itself, and also store in `format` the data type that the
927  /// pixels are internally stored in (which may be different than the
928  /// data type of the pixels in the disk file). This method should only
929  /// be called on a tile that has been requested by `get_tile()` but has
930  /// not yet been released with `release_tile()`.
931  virtual const void* tile_pixels(Tile* tile, TypeDesc& format) const = 0;
932 
933  /// The add_file() call causes a file to be opened or added to the
934  /// cache. There is no reason to use this method unless you are
935  /// supplying a custom creator, or configuration, or both.
936  ///
937  /// If creator is not NULL, it points to an ImageInput::Creator that
938  /// will be used rather than the default ImageInput::create(), thus
939  /// instead of reading from disk, creates and uses a custom ImageInput
940  /// to generate the image. The 'creator' is a factory that creates the
941  /// custom ImageInput and will be called like this:
942  ///
943  /// std::unique_ptr<ImageInput> in (creator());
944  ///
945  /// Once created, the ImageCache owns the ImageInput and is responsible
946  /// for destroying it when done. Custom ImageInputs allow "procedural"
947  /// images, among other things. Also, this is the method you use to set
948  /// up a "writable" ImageCache images (perhaps with a type of ImageInput
949  /// that's just a stub that does as little as possible).
950  ///
951  /// If `config` is not NULL, it points to an ImageSpec with configuration
952  /// options/hints that will be passed to the underlying
953  /// ImageInput::open() call. Thus, this can be used to ensure that the
954  /// ImageCache opens a call with special configuration options.
955  ///
956  /// This call (including any custom creator or configuration hints) will
957  /// have no effect if there's already an image by the same name in the
958  /// cache. Custom creators or configurations only "work" the FIRST time
959  /// a particular filename is referenced in the lifetime of the
960  /// ImageCache. But if replace is true, any existing entry will be
961  /// invalidated, closed and overwritten. So any subsequent access will
962  /// see the new file. Existing texture handles will still be valid.
963  virtual bool add_file (ustring filename, ImageInput::Creator creator=nullptr,
964  const ImageSpec *config=nullptr,
965  bool replace = false) = 0;
966 
967  /// Preemptively add a tile corresponding to the named image, at the
968  /// given subimage, MIP level, and channel range. The tile added is the
969  /// one whose corner is (x,y,z), and buffer points to the pixels (in the
970  /// given format, with supplied strides) which will be copied and
971  /// inserted into the cache and made available for future lookups.
972  /// If chend < chbegin, it will add a tile containing the full set of
973  /// channels for the image. Note that if the 'copy' flag is false, the
974  /// data is assumed to be in some kind of persistent storage and will
975  /// not be copied, nor will its pixels take up additional memory in the
976  /// cache.
977  virtual bool add_tile (ustring filename, int subimage, int miplevel,
978  int x, int y, int z, int chbegin, int chend,
979  TypeDesc format, const void *buffer,
980  stride_t xstride=AutoStride, stride_t ystride=AutoStride,
981  stride_t zstride=AutoStride, bool copy = true) = 0;
982 
983  /// @}
984 
985  /// @{
986  /// @name Errors and statistics
987 
988  /// Is there a pending error message waiting to be retrieved?
989  virtual bool has_error() const = 0;
990 
991  /// Return the text of all pending error messages issued against this
992  /// ImageCache, and clear the pending error message unless `clear` is
993  /// false. If no error message is pending, it will return an empty
994  /// string.
995  virtual std::string geterror(bool clear = true) const = 0;
996 
997  /// Returns a big string containing useful statistics about the
998  /// ImageCache operations, suitable for saving to a file or outputting
999  /// to the terminal. The `level` indicates the amount of detail in
1000  /// the statistics, with higher numbers (up to a maximum of 5) yielding
1001  /// more and more esoteric information.
1002  virtual std::string getstats(int level = 1) const = 0;
1003 
1004  /// Reset most statistics to be as they were with a fresh ImageCache.
1005  /// Caveat emptor: this does not flush the cache itelf, so the resulting
1006  /// statistics from the next set of texture requests will not match the
1007  /// number of tile reads, etc., that would have resulted from a new
1008  /// ImageCache.
1009  virtual void reset_stats() = 0;
1010 
1011  /// @}
1012 
1013  virtual ~ImageCache() {}
1014 
1015 protected:
1016  // User code should never directly construct or destruct an ImageCache.
1017  // Always use ImageCache::create() and ImageCache::destroy().
1018  ImageCache(void) {}
1019 private:
1020  // Make delete private and unimplemented in order to prevent apps
1021  // from calling it. Instead, they should call ImageCache::destroy().
1022  void operator delete(void* /*todel*/) {}
1023 };
1024 
1025 
OIIO_API std::string geterror(bool clear=true)
OIIO_API bool has_error()
Is there a pending global error message waiting to be retrieved?
int64_t stride_t
Definition: imageio.h:48
GT_API const UT_StringHolder filename
OIIO_UTIL_API bool copy(string_view from, string_view to, std::string &err)
pvt::ImageCacheFile ImageHandle
Definition: imagecache.h:459
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
GLdouble GLdouble GLdouble z
Definition: glcorearb.h:848
GLint level
Definition: glcorearb.h:108
ImageCache(void)
Definition: imagecache.h:1018
GLint y
Definition: glcorearb.h:103
**But if you need a result
Definition: thread.h:613
void close() override
ImageInput *(* Creator)()
Definition: imageio.h:1739
Definition: core.h:760
std::string OIIO_UTIL_API replace(string_view str, string_view pattern, string_view replacement, bool global=false)
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
GLuint const GLchar * name
Definition: glcorearb.h:786
GLint GLenum GLint x
Definition: glcorearb.h:409
pvt::ImageCacheTile Tile
Definition: imagecache.h:890
Definition: imageio.h:85
OIIO_API bool getattribute(string_view name, TypeDesc type, void *val)
SIM_API const UT_StringHolder force
const stride_t AutoStride
Definition: imageio.h:56
GLuint GLfloat * val
Definition: glcorearb.h:1608
OIIO_API bool attribute(string_view name, TypeDesc type, const void *val)
pvt::ImageCachePerThreadInfo Perthread
Definition: imagecache.h:434
ImageHandle * get_image_handle(const std::wstring &filename, Perthread *thread_info=NULL)
Get an ImageHandle using a UTF-16 encoded wstring filename.
Definition: imagecache.h:469
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:94
virtual ~ImageCache()
Definition: imagecache.h:1013
std::string OIIO_UTIL_API utf16_to_utf8(const std::wstring &utf16str) noexcept
type
Definition: core.h:1059
Definition: format.h:895
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:93
#define OIIO_API
Definition: export.h:65