HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
imagecache.h
Go to the documentation of this file.
1 /*
2  Copyright 2008 Larry Gritz and the other authors and contributors.
3  All Rights Reserved.
4 
5  Redistribution and use in source and binary forms, with or without
6  modification, are permitted provided that the following conditions are
7  met:
8  * Redistributions of source code must retain the above copyright
9  notice, this list of conditions and the following disclaimer.
10  * Redistributions in binary form must reproduce the above copyright
11  notice, this list of conditions and the following disclaimer in the
12  documentation and/or other materials provided with the distribution.
13  * Neither the name of the software's owners nor the names of its
14  contributors may be used to endorse or promote products derived from
15  this software without specific prior written permission.
16  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 
28  (This is the Modified BSD License)
29 */
30 
31 // clang-format off
32 
33 /// \file
34 /// An API for accessing images via a system that
35 /// automatically manages a cache of resident image data.
36 
37 
38 #pragma once
39 
40 #include <OpenImageIO/imageio.h>
41 #include <OpenImageIO/ustring.h>
42 
43 
44 // Define symbols that let client applications determine if newly added
45 // features are supported.
46 #define OIIO_IMAGECACHE_SUPPORTS_CLOSE 1
47 
48 
49 
51 
52 struct ROI;
53 
54 namespace pvt {
55 // Forward declaration
56 class ImageCacheImpl;
57 class ImageCacheFile;
58 class ImageCachePerThreadInfo;
59 }; // namespace pvt
60 
61 
62 
63 /// Define an API to an abstract class that manages image files,
64 /// caches of open file handles as well as tiles of pixels so that truly
65 /// huge amounts of image data may be accessed by an application with low
66 /// memory footprint.
68 public:
69  /// Create a ImageCache and return a pointer. This should only be
70  /// freed by passing it to ImageCache::destroy()!
71  ///
72  /// If shared==true, it's intended to be shared with other like-minded
73  /// owners in the same process who also ask for a shared cache. If
74  /// false, a private image cache will be created.
75  static ImageCache* create(bool shared = true);
76 
77  /// Destroy an ImageCache that was created using ImageCache::create(),
78  /// unless it's recognized that this is the global "shared" ImageCache,
79  /// in which case it will stay active.
80  /// However, if 'teardown' is true, it will fully destroy the IC even
81  /// if it's the shared one (use with caution).
82  static void destroy(ImageCache* x, bool teardown = false);
83 
84  ImageCache(void) {}
85  virtual ~ImageCache() {}
86 
87  /// Set an attribute controlling the image cache. Return true
88  /// if the name and type were recognized and the attrib was set.
89  /// Documented attributes:
90  /// int max_open_files : maximum number of file handles held open
91  /// float max_memory_MB : maximum tile cache size, in MB
92  /// string searchpath : colon-separated search path for images
93  /// string plugin_searchpath : colon-separated search path for plugins
94  /// int autotile : if >0, tile size to emulate for non-tiled images
95  /// int autoscanline : autotile using full width tiles
96  /// int automip : if nonzero, emulate mipmap on the fly
97  /// int accept_untiled : if nonzero, accept untiled images, but
98  /// if zero, reject untiled images (default=1)
99  /// int accept_unmipped : if nonzero, accept unmipped images (def=1)
100  /// int statistics:level : verbosity of statistics auto-printed.
101  /// int forcefloat : if nonzero, convert all to float.
102  /// int failure_retries : number of times to retry a read before fail.
103  /// int deduplicate : if nonzero, detect duplicate textures (default=1)
104  /// string substitute_image : uses the named image in place of all
105  /// texture and image references.
106  /// int unassociatedalpha : if nonzero, keep unassociated alpha images
107  /// int max_errors_per_file : Limits how many errors to issue for
108  /// issue for each (default: 100)
109  ///
110  virtual bool attribute (string_view name, TypeDesc type,
111  const void *val) = 0;
112  // Shortcuts for common types
113  virtual bool attribute (string_view name, int val) = 0;
114  virtual bool attribute (string_view name, float val) = 0;
115  virtual bool attribute (string_view name, double val) = 0;
116  virtual bool attribute (string_view name, string_view val) = 0;
117 
118  /// Get the named attribute, store it in *val. All of the attributes
119  /// that may be set with the attribute() call may also be queried with
120  /// getattribute().
121  ///
122  /// Additionally, there are some read-only attributes that can be
123  /// queried with getattribute():
124  /// int total_files : the total number of unique files referenced by
125  /// calls to the ImageCache.
126  /// string[] all_filenames : an array that will be filled with the
127  /// list of the names of all files referenced by calls to
128  /// the ImageCache. (The array is of ustrings or char*'s.)
129  /// stat:* : a variety of statistics (see full docs for details).
130  ///
131  virtual bool getattribute (string_view name, TypeDesc type,
132  void *val) const = 0;
133  // Shortcuts for common types
134  virtual bool getattribute (string_view name, int &val) const = 0;
135  virtual bool getattribute (string_view name, float &val) const = 0;
136  virtual bool getattribute (string_view name, double &val) const = 0;
137  virtual bool getattribute (string_view name, char **val) const = 0;
138  virtual bool getattribute (string_view name, std::string &val) const = 0;
139 
140  /// Define an opaque data type that allows us to have a pointer
141  /// to certain per-thread information that the ImageCache maintains.
142  /// Any given one of these should NEVER be shared between running
143  /// threads.
144  typedef pvt::ImageCachePerThreadInfo Perthread;
145 
146  /// Retrieve a Perthread, unique to the calling thread. This is a
147  /// thread-specific pointer that will always return the Perthread for a
148  /// thread, which will also be automatically destroyed when the thread
149  /// terminates.
150  ///
151  /// Applications that want to manage their own Perthread pointers (with
152  /// create_thread_info and destroy_thread_info) should still call this,
153  /// but passing in their managed pointer. If the passed-in thread_info
154  /// is not NULL, it won't create a new one or retrieve a TSP, but it
155  /// will do other necessary housekeeping on the Perthread information.
156  virtual Perthread* get_perthread_info(Perthread* thread_info = NULL) = 0;
157 
158  /// Create a new Perthread. It is the caller's responsibility to
159  /// eventually destroy it using destroy_thread_info().
160  virtual Perthread* create_thread_info() = 0;
161 
162  /// Destroy a Perthread that was allocated by create_thread_info().
163  virtual void destroy_thread_info(Perthread* thread_info) = 0;
164 
165  /// Define an opaque data type that allows us to have a handle to an
166  /// image (already having its name resolved) but without exposing
167  /// any internals.
168  typedef pvt::ImageCacheFile ImageHandle;
169 
170  /// Retrieve an opaque handle for fast image lookups. The opaque
171  /// pointer thread_info is thread-specific information returned by
172  /// get_perthread_info(). Return NULL if something has gone
173  /// horribly wrong.
174  virtual ImageHandle * get_image_handle (ustring filename,
175  Perthread *thread_info=NULL) = 0;
176 
177  /// Return true if the image handle (previously returned by
178  /// get_image_handle()) is a valid image that can be subsequently read.
179  virtual bool good(ImageHandle* file) = 0;
180 
181  /// Given possibly-relative 'filename', resolve it using the search
182  /// path rules and return the full resolved filename.
183  virtual std::string resolve_filename(const std::string& filename) const = 0;
184 
185  /// Get information about the named image. Return true if found
186  /// and the data has been put in *data. Return false if the image
187  /// doesn't exist, doesn't have the requested data, if the data
188  /// doesn't match the type requested. or some other failure.
189  virtual bool get_image_info (ustring filename, int subimage, int miplevel,
190  ustring dataname, TypeDesc datatype, void *data) = 0;
191  virtual bool get_image_info (ImageHandle *file, Perthread *thread_info,
192  int subimage, int miplevel,
193  ustring dataname, TypeDesc datatype, void *data) = 0;
194 
195  /// Get the ImageSpec associated with the named image (the first
196  /// subimage & miplevel by default, or as set by 'subimage' and
197  /// 'miplevel'). If the file is found and is an image format that
198  /// can be read, store a copy of its specification in spec and
199  /// return true. Return false if the file was not found or could
200  /// not be opened as an image file by any available ImageIO plugin.
201  virtual bool get_imagespec (ustring filename, ImageSpec &spec,
202  int subimage=0, int miplevel=0,
203  bool native=false) = 0;
204  virtual bool get_imagespec (ImageHandle *file, Perthread *thread_info,
205  ImageSpec &spec,
206  int subimage=0, int miplevel=0,
207  bool native=false) = 0;
208 
209  /// Return a pointer to an ImageSpec associated with the named image
210  /// (the first subimage & miplevel by default, or as set by
211  /// 'subimage' and 'miplevel') if the file is found and is an image
212  /// format that can be read, otherwise return NULL.
213  ///
214  /// This method is much more efficient than get_imagespec(), since
215  /// it just returns a pointer to the spec held internally by the
216  /// ImageCache (rather than copying the spec to the user's memory).
217  /// However, the caller must beware that the pointer is only valid
218  /// as long as nobody (even other threads) calls invalidate() on the
219  /// file, or invalidate_all(), or destroys the ImageCache.
220  virtual const ImageSpec *imagespec (ustring filename, int subimage=0,
221  int miplevel=0, bool native=false) = 0;
222  virtual const ImageSpec *imagespec (ImageHandle *file,
223  Perthread *thread_info,
224  int subimage=0, int miplevel=0,
225  bool native=false) = 0;
226 
227  /// Retrieve the rectangle of pixels spanning [xbegin..xend) X
228  /// [ybegin..yend) X [zbegin..zend), with "exclusive end" a la STL,
229  /// specified as integer pixel coordinates in the designated
230  /// subimage & miplevel, storing the pixel values beginning at the
231  /// address specified by result. The pixel values will be converted
232  /// to the type specified by format. It is up to the caller to
233  /// ensure that result points to an area of memory big enough to
234  /// accommodate the requested rectangle (taking into consideration
235  /// its dimensions, number of channels, and data format). Requested
236  /// pixels outside the valid pixel data region will be filled in
237  /// with 0 values.
238  ///
239  /// Return true if the file is found and could be opened by an
240  /// available ImageIO plugin, otherwise return false.
241  virtual bool get_pixels (ustring filename, int subimage, int miplevel,
242  int xbegin, int xend, int ybegin, int yend,
243  int zbegin, int zend,
244  TypeDesc format, void *result) = 0;
245  virtual bool get_pixels (ImageHandle *file, Perthread *thread_info,
246  int subimage, int miplevel,
247  int xbegin, int xend, int ybegin, int yend,
248  int zbegin, int zend,
249  TypeDesc format, void *result) = 0;
250 
251  /// Retrieve the rectangle of pixels spanning [xbegin..xend) X
252  /// [ybegin..yend) X [zbegin..zend), channels [chbegin..chend),
253  /// with "exclusive end" a la STL, specified as integer pixel
254  /// coordinates in the designated subimage & miplevel, storing the
255  /// pixel values beginning at the address specified by result and
256  /// with the given x, y, and z strides (in bytes). The pixel values
257  /// will be converted to the type specified by format. If the
258  /// strides are set to AutoStride, they will be automatically
259  /// computed assuming a contiguous data layout. It is up to the
260  /// caller to ensure that result points to an area of memory big
261  /// enough to accommodate the requested rectangle (taking into
262  /// consideration its dimensions, number of channels, and data
263  /// format). Requested pixels outside the valid pixel data region
264  /// will be filled in with 0 values. The optional cache_chbegin and
265  /// cache_chend hint as to which range of channels should be cached
266  /// (which by default will be all channels of the file).
267  ///
268  /// Return true if the file is found and could be opened by an
269  /// available ImageIO plugin, otherwise return false.
270  virtual bool get_pixels (ustring filename,
271  int subimage, int miplevel, int xbegin, int xend,
272  int ybegin, int yend, int zbegin, int zend,
273  int chbegin, int chend, TypeDesc format, void *result,
274  stride_t xstride=AutoStride, stride_t ystride=AutoStride,
275  stride_t zstride=AutoStride,
276  int cache_chbegin = 0, int cache_chend = -1) = 0;
277  virtual bool get_pixels (ImageHandle *file, Perthread *thread_info,
278  int subimage, int miplevel, int xbegin, int xend,
279  int ybegin, int yend, int zbegin, int zend,
280  int chbegin, int chend, TypeDesc format, void *result,
281  stride_t xstride=AutoStride, stride_t ystride=AutoStride,
282  stride_t zstride=AutoStride,
283  int cache_chbegin = 0, int cache_chend = -1) = 0;
284 
285  /// Define an opaque data type that allows us to have a pointer
286  /// to a tile but without exposing any internals.
287  class Tile;
288 
289  /// Find a tile given by an image filename, subimage & miplevel, channel
290  /// range, and pixel coordinates. An opaque pointer to the tile will be
291  /// returned, or NULL if no such file (or tile within the file) exists
292  /// or can be read. The tile will not be purged from the cache until
293  /// after release_tile() is called on the tile pointer the same number
294  /// of times that get_tile() was called (refcnt). This is thread-safe!
295  /// If chend < chbegin, it will retrieve a tile containing all channels
296  /// in the file.
297  virtual Tile * get_tile (ustring filename, int subimage, int miplevel,
298  int x, int y, int z,
299  int chbegin = 0, int chend = -1) = 0;
300  virtual Tile * get_tile (ImageHandle *file, Perthread *thread_info,
301  int subimage, int miplevel,
302  int x, int y, int z,
303  int chbegin = 0, int chend = -1) = 0;
304 
305  /// After finishing with a tile, release_tile will allow it to
306  /// once again be purged from the tile cache if required.
307  virtual void release_tile(Tile* tile) const = 0;
308 
309  /// Retrieve the data type of the pixels stored in the tile, which may
310  /// be different than the type of the pixels in the disk file.
311  virtual TypeDesc tile_format(const Tile* tile) const = 0;
312 
313  /// Retrieve the ROI describing the pixels and channels stored in the
314  /// tile.
315  virtual ROI tile_roi(const Tile* tile) const = 0;
316 
317  /// For a tile retrived by get_tile(), return a pointer to the
318  /// pixel data itself, and also store in 'format' the data type that
319  /// the pixels are internally stored in (which may be different than
320  /// the data type of the pixels in the disk file).
321  virtual const void* tile_pixels(Tile* tile, TypeDesc& format) const = 0;
322 
323  /// The add_file() call causes a file to be opened or added to the
324  /// cache. There is no reason to use this method unless you are
325  /// supplying a custom creator, or configuration, or both.
326  ///
327  /// If creator is not NULL, it points to an ImageInput::Creator that
328  /// will be used rather than the default ImageInput::create(), thus
329  /// instead of reading from disk, creates and uses a custom ImageInput
330  /// to generate the image. The 'creator' is a factory that creates the
331  /// custom ImageInput and will be called like this:
332  /// std::unique_ptr<ImageInput> in (creator());
333  /// Once created, the ImageCache owns the ImageInput and is responsible
334  /// for destroying it when done. Custom ImageInputs allow "procedural"
335  /// images, among other things. Also, this is the method you use to set
336  /// up a "writeable" ImageCache images (perhaps with a type of
337  /// ImageInput that's just a stub that does as little as possible).
338  ///
339  /// If config is not NULL, it points to an ImageSpec with configuration
340  /// options/hints that will be passed to the underlying
341  /// ImageInput::open() call. Thus, this can be used to ensure that the
342  /// ImageCache opens a call with special configuration options.
343  ///
344  /// This call (including any custom creator or configuration hints) will
345  /// have no effect if there's already an image by the same name in the
346  /// cache. Custom creators or configurations only "work" the FIRST time
347  /// a particular filename is referenced in the lifetime of the
348  /// ImageCache. But if replace is true, any existing entry will be
349  /// invalidated, closed and overwritten. So any subsequent access will see
350  /// the new file. Existing texture handles will still be valid.
351  virtual bool add_file (ustring filename, ImageInput::Creator creator=nullptr,
352  const ImageSpec *config=nullptr,
353  bool replace = false) = 0;
354 
355  /// Preemptively add a tile corresponding to the named image, at the
356  /// given subimage, MIP level, and channel range. The tile added is the
357  /// one whose corner is (x,y,z), and buffer points to the pixels (in the
358  /// given format, with supplied strides) which will be copied and
359  /// inserted into the cache and made available for future lookups.
360  /// If chend < chbegin, it will add a tile containing the full set of
361  /// channels for the image. Note that if the 'copy' flag is false, the
362  /// data is assumed to be in some kind of persistent storage and will
363  /// not be copied, nor will its pixels take up additional memory in the
364  /// cache.
365  virtual bool add_tile (ustring filename, int subimage, int miplevel,
366  int x, int y, int z, int chbegin, int chend,
367  TypeDesc format, const void *buffer,
368  stride_t xstride=AutoStride, stride_t ystride=AutoStride,
369  stride_t zstride=AutoStride, bool copy = true) = 0;
370 
371  /// If any of the API routines returned false indicating an error,
372  /// this routine will return the error string (and clear any error
373  /// flags). If no error has occurred since the last time geterror()
374  /// was called, it will return an empty string.
375  virtual std::string geterror() const = 0;
376 
377  /// Return the statistics output as a huge string.
378  ///
379  virtual std::string getstats(int level = 1) const = 0;
380 
381  /// Reset most statistics to be as they were with a fresh
382  /// ImageCache. Caveat emptor: this does not flush the cache itelf,
383  /// so the resulting statistics from the next set of texture
384  /// requests will not match the number of tile reads, etc., that
385  /// would have resulted from a new ImageCache.
386  virtual void reset_stats() = 0;
387 
388  /// Invalidate any loaded tiles or open file handles associated with
389  /// the filename, so that any subsequent queries will be forced to
390  /// re-open the file or re-load any tiles (even those that were
391  /// previously loaded and would ordinarily be reused). A client
392  /// might do this if, for example, they are aware that an image
393  /// being held in the cache has been updated on disk. This is safe
394  /// to do even if other procedures are currently holding
395  /// reference-counted tile pointers from the named image, but those
396  /// procedures will not get updated pixels until they release the
397  /// tiles they are holding.
398  virtual void invalidate(ustring filename) = 0;
399 
400  /// Invalidate all loaded tiles and open file handles. This is safe
401  /// to do even if other procedures are currently holding
402  /// reference-counted tile pointers from the named image, but those
403  /// procedures will not get updated pixels until they release the
404  /// tiles they are holding. If force is true, everything will be
405  /// invalidated, no matter how wasteful it is, but if force is
406  /// false, in actuality files will only be invalidated if their
407  /// modification times have been changed since they were first
408  /// opened.
409  virtual void invalidate_all(bool force = false) = 0;
410 
411  /// Close any open file handles associated with a named file, or for all
412  /// files, but do not invalidate any image spec information or pixels
413  /// associated with the files. A client might do this in order to
414  /// release OS file handle resources, or to make it safe for other
415  /// processes to modify cached files.
416  virtual void close (ustring filename) = 0;
417  virtual void close_all () = 0;
418 
419 private:
420  // Make delete private and unimplemented in order to prevent apps
421  // from calling it. Instead, they should call ImageCache::destroy().
422  void operator delete(void* /*todel*/) {}
423 };
424 
425 
GT_API const UT_StringHolder filename
GLuint const GLchar * name
Definition: glew.h:1814
pvt::ImageCacheFile ImageHandle
Definition: imagecache.h:168
GLuint const GLfloat * val
Definition: glew.h:2794
ImageCache(void)
Definition: imagecache.h:84
ImageInput *(* Creator)()
Call signature of a function that creates and returns an ImageInput*.
Definition: imageio.h:1156
OIIO_API std::string geterror()
GLdouble GLdouble z
Definition: glew.h:1559
GLint GLint GLint GLint GLint x
Definition: glew.h:1252
GLint GLint GLint GLint GLint GLint y
Definition: glew.h:1252
std::string OIIO_API replace(string_view str, string_view pattern, string_view replacement, bool global=false)
GLuint buffer
Definition: glew.h:1680
GLint GLenum GLsizei GLint GLsizei const void * data
Definition: glew.h:1379
ptrdiff_t stride_t
Definition: imageio.h:69
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
GLsizei const GLchar *const * string
Definition: glew.h:1844
Definition: imageio.h:115
OIIO_API bool getattribute(string_view name, TypeDesc type, void *val)
const stride_t AutoStride
Definition: imageio.h:92
virtual void close()
GLint GLint GLsizei GLsizei GLsizei GLint GLenum format
Definition: glew.h:1254
OIIO_API bool copy(string_view from, string_view to, std::string &err)
OIIO_API bool attribute(string_view name, TypeDesc type, const void *val)
pvt::ImageCachePerThreadInfo Perthread
Definition: imagecache.h:144
GLuint64EXT * result
Definition: glew.h:14007
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:66
virtual ~ImageCache()
Definition: imagecache.h:85
GLint level
Definition: glew.h:1252
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:65
#define OIIO_API
Definition: export.h:91