HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
texture.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/blob/master/LICENSE.md
4 
5 // clang-format off
6 
7 /// \file
8 /// An API for accessing filtered texture lookups via a system that
9 /// automatically manages a cache of resident texture.
10 
11 #pragma once
12 
13 #include <OpenImageIO/imageio.h>
14 #include <OpenImageIO/simd.h>
15 #include <OpenImageIO/ustring.h>
16 #include <OpenImageIO/varyingref.h>
17 
18 
19 // Define symbols that let client applications determine if newly added
20 // features are supported.
21 #define OIIO_TEXTURESYSTEM_SUPPORTS_CLOSE 1
22 
23 
24 
26 
27 // Forward declarations
28 
29 class ImageCache;
30 
31 
32 namespace pvt {
33 
34 class TextureSystemImpl;
35 
36 // Used internally by TextureSystem. Unfortunately, this is the only
37 // clean place to store it. Sorry, users, this isn't really for you.
38 enum TexFormat {
48 };
49 
50 enum EnvLayout {
51  LayoutTexture = 0 /* ordinary texture - no special env wrap */,
56 };
57 
58 } // namespace pvt
59 
60 
61 
62 namespace Tex {
63 
64 /// Wrap mode describes what happens when texture coordinates describe
65 /// a value outside the usual [0,1] range where a texture is defined.
66 enum class Wrap {
67  Default, ///< Use the default found in the file
68  Black, ///< Black outside [0..1]
69  Clamp, ///< Clamp to [0..1]
70  Periodic, ///< Periodic mod 1
71  Mirror, ///< Mirror the image
72  PeriodicPow2, ///< Periodic, but only for powers of 2!!!
73  PeriodicSharedBorder, ///< Periodic with shared border (env)
74  Last ///< Mark the end -- don't use this!
75 };
76 
77 /// Utility: Return the Wrap enum corresponding to a wrap name:
78 /// "default", "black", "clamp", "periodic", "mirror".
79 OIIO_API Wrap decode_wrapmode (const char *name);
81 
82 /// Utility: Parse a single wrap mode (e.g., "periodic") or a
83 /// comma-separated wrap modes string (e.g., "black,clamp") into
84 /// separate Wrap enums for s and t.
85 OIIO_API void parse_wrapmodes (const char *wrapmodes,
86  Wrap &swrapcode, Wrap &twrapcode);
87 
88 
89 /// Mip mode determines if/how we use mipmaps
90 ///
91 enum class MipMode {
92  Default, ///< Default high-quality lookup
93  NoMIP, ///< Just use highest-res image, no MIP mapping
94  OneLevel, ///< Use just one mipmap level
95  Trilinear, ///< Use two MIPmap levels (trilinear)
96  Aniso ///< Use two MIPmap levels w/ anisotropic
97 };
98 
99 /// Interp mode determines how we sample within a mipmap level
100 ///
101 enum class InterpMode {
102  Closest, ///< Force closest texel
103  Bilinear, ///< Force bilinear lookup within a mip level
104  Bicubic, ///< Force cubic lookup within a mip level
105  SmartBicubic ///< Bicubic when maxifying, else bilinear
106 };
107 
108 
109 /// Fixed width for SIMD batching texture lookups.
110 /// May be changed for experimentation or future expansion.
111 #ifndef OIIO_TEXTURE_SIMD_BATCH_WIDTH
112 # define OIIO_TEXTURE_SIMD_BATCH_WIDTH 16
113 #endif
114 
115 /// The SIMD width for batched texturing operations. This is fixed within
116 /// any release of OpenImageIO, but may change from release to release and
117 /// also may be overridden at build time. A typical batch size is 16.
118 static constexpr int BatchWidth = OIIO_TEXTURE_SIMD_BATCH_WIDTH;
119 static constexpr int BatchAlign = BatchWidth * sizeof(float);
120 
121 /// A type alias for a SIMD vector of floats with the batch width.
123 
124 /// A type alias for a SIMD vector of ints with the batch width.
126 
127 /// `RunMask` is defined to be an integer large enough to hold at least
128 /// `BatchWidth` bits. The least significant bit corresponds to the first
129 /// (i.e., `[0]`) position of all batch arrays. For each position `i` in the
130 /// batch, the bit identified by `(1 << i)` controls whether that position
131 /// will be computed.
132 typedef uint64_t RunMask;
133 
134 
135 // The defined constant `RunMaskOn` contains the value with all bits
136 // `0..BatchWidth-1` set to 1.
137 #if OIIO_TEXTURE_SIMD_BATCH_WIDTH == 4
138 static constexpr RunMask RunMaskOn = 0xf;
139 #elif OIIO_TEXTURE_SIMD_BATCH_WIDTH == 8
140 static constexpr RunMask RunMaskOn = 0xff;
141 #elif OIIO_TEXTURE_SIMD_BATCH_WIDTH == 16
142 static constexpr RunMask RunMaskOn = 0xffff;
143 #elif OIIO_TEXTURE_SIMD_BATCH_WIDTH == 32
144 static constexpr RunMask RunMaskOn = 0xffffffff;
145 #elif OIIO_TEXTURE_SIMD_BATCH_WIDTH == 64
146 static constexpr RunMask RunMaskOn = 0xffffffffffffffffULL;
147 #else
148 # error "Not a valid OIIO_TEXTURE_SIMD_BATCH_WIDTH choice"
149 #endif
150 
151 } // namespace Tex
152 
153 
154 /// Data type for flags that indicate on a point-by-point basis whether
155 /// we want computations to be performed.
156 typedef unsigned char Runflag;
157 
158 /// Pre-defined values for Runflag's.
159 ///
160 enum RunFlagVal { RunFlagOff = 0, RunFlagOn = 255 };
161 
162 class TextureOptions; // forward declaration
163 
164 
165 
166 /// TextureOpt is a structure that holds many options controlling
167 /// single-point texture lookups. Because each texture lookup API call
168 /// takes a reference to a TextureOpt, the call signatures remain
169 /// uncluttered rather than having an ever-growing list of parameters, most
170 /// of which will never vary from their defaults.
172 public:
173  /// Wrap mode describes what happens when texture coordinates describe
174  /// a value outside the usual [0,1] range where a texture is defined.
175  enum Wrap {
176  WrapDefault, ///< Use the default found in the file
177  WrapBlack, ///< Black outside [0..1]
178  WrapClamp, ///< Clamp to [0..1]
179  WrapPeriodic, ///< Periodic mod 1
180  WrapMirror, ///< Mirror the image
181  WrapPeriodicPow2, // Periodic, but only for powers of 2!!!
182  WrapPeriodicSharedBorder, // Periodic with shared border (env)
183  WrapLast // Mark the end -- don't use this!
184  };
185 
186  /// Mip mode determines if/how we use mipmaps
187  ///
188  enum MipMode {
189  MipModeDefault, ///< Default high-quality lookup
190  MipModeNoMIP, ///< Just use highest-res image, no MIP mapping
191  MipModeOneLevel, ///< Use just one mipmap level
192  MipModeTrilinear, ///< Use two MIPmap levels (trilinear)
193  MipModeAniso ///< Use two MIPmap levels w/ anisotropic
194  };
195 
196  /// Interp mode determines how we sample within a mipmap level
197  ///
198  enum InterpMode {
199  InterpClosest, ///< Force closest texel
200  InterpBilinear, ///< Force bilinear lookup within a mip level
201  InterpBicubic, ///< Force cubic lookup within a mip level
202  InterpSmartBicubic ///< Bicubic when maxifying, else bilinear
203  };
204 
205 
206  /// Create a TextureOpt with all fields initialized to reasonable
207  /// defaults.
209  : firstchannel(0), subimage(0),
210  swrap(WrapDefault), twrap(WrapDefault),
211  mipmode(MipModeDefault), interpmode(InterpSmartBicubic),
212  anisotropic(32), conservative_filter(true),
213  sblur(0.0f), tblur(0.0f), swidth(1.0f), twidth(1.0f),
214  fill(0.0f), missingcolor(nullptr),
215  // dresultds(nullptr), dresultdt(nullptr),
216  time(0.0f), bias(0.0f), samples(1),
217  rwrap(WrapDefault), rblur(0.0f), rwidth(1.0f), // dresultdr(nullptr),
218  // actualchannels(0),
219  envlayout(0)
220  { }
221 
222  /// Convert a TextureOptions for one index into a TextureOpt.
223  ///
224  TextureOpt(const TextureOptions& opt, int index);
225 
226  int firstchannel; ///< First channel of the lookup
227  int subimage; ///< Subimage or face ID
228  ustring subimagename; ///< Subimage name
229  Wrap swrap; ///< Wrap mode in the s direction
230  Wrap twrap; ///< Wrap mode in the t direction
231  MipMode mipmode; ///< Mip mode
232  InterpMode interpmode; ///< Interpolation mode
233  int anisotropic; ///< Maximum anisotropic ratio
234  bool conservative_filter; ///< True == over-blur rather than alias
235  float sblur, tblur; ///< Blur amount
236  float swidth, twidth; ///< Multiplier for derivatives
237  float fill; ///< Fill value for missing channels
238  const float* missingcolor; ///< Color for missing texture
239  float time; ///< Time (for time-dependent texture lookups)
240  float bias; ///< Bias for shadows
241  int samples; ///< Number of samples for shadows
242 
243  // For 3D volume texture lookups only:
244  Wrap rwrap; ///< Wrap mode in the r direction
245  float rblur; ///< Blur amount in the r direction
246  float rwidth; ///< Multiplier for derivatives in r direction
247 
248  /// Utility: Return the Wrap enum corresponding to a wrap name:
249  /// "default", "black", "clamp", "periodic", "mirror".
250  static Wrap decode_wrapmode(const char* name)
251  {
252  return (Wrap)Tex::decode_wrapmode(name);
253  }
255  {
256  return (Wrap)Tex::decode_wrapmode(name);
257  }
258 
259  /// Utility: Parse a single wrap mode (e.g., "periodic") or a
260  /// comma-separated wrap modes string (e.g., "black,clamp") into
261  /// separate Wrap enums for s and t.
262  static void parse_wrapmodes(const char* wrapmodes,
263  TextureOpt::Wrap& swrapcode,
264  TextureOpt::Wrap& twrapcode)
265  {
266  Tex::parse_wrapmodes(wrapmodes, *(Tex::Wrap*)&swrapcode,
267  *(Tex::Wrap*)&twrapcode);
268  }
269 
270 private:
271  // Options set INTERNALLY by libtexture after the options are passed
272  // by the user. Users should not attempt to alter these!
273  int envlayout; // Layout for environment wrap
274  friend class pvt::TextureSystemImpl;
275 };
276 
277 
278 
279 /// Texture options for a batch of Tex::BatchWidth points and run mask.
281 public:
282  /// Create a TextureOptBatch with all fields initialized to reasonable
283  /// defaults.
284  TextureOptBatch () {} // use inline initializers
285 
286  // Options that may be different for each point we're texturing
287  alignas(Tex::BatchAlign) float sblur[Tex::BatchWidth]; ///< Blur amount
288  alignas(Tex::BatchAlign) float tblur[Tex::BatchWidth];
289  alignas(Tex::BatchAlign) float rblur[Tex::BatchWidth];
290  alignas(Tex::BatchAlign) float swidth[Tex::BatchWidth]; ///< Multiplier for derivatives
291  alignas(Tex::BatchAlign) float twidth[Tex::BatchWidth];
292  alignas(Tex::BatchAlign) float rwidth[Tex::BatchWidth];
293  // Note: rblur,rwidth only used for volumetric lookups
294 
295  // Options that must be the same for all points we're texturing at once
296  int firstchannel = 0; ///< First channel of the lookup
297  int subimage = 0; ///< Subimage or face ID
298  ustring subimagename; ///< Subimage name
299  Tex::Wrap swrap = Tex::Wrap::Default; ///< Wrap mode in the s direction
300  Tex::Wrap twrap = Tex::Wrap::Default; ///< Wrap mode in the t direction
301  Tex::Wrap rwrap = Tex::Wrap::Default; ///< Wrap mode in the r direction (volumetric)
302  Tex::MipMode mipmode = Tex::MipMode::Default; ///< Mip mode
303  Tex::InterpMode interpmode = Tex::InterpMode::SmartBicubic; ///< Interpolation mode
304  int anisotropic = 32; ///< Maximum anisotropic ratio
305  int conservative_filter = 1; ///< True: over-blur rather than alias
306  float fill = 0.0f; ///< Fill value for missing channels
307  const float *missingcolor = nullptr; ///< Color for missing texture
308 
309 private:
310  // Options set INTERNALLY by libtexture after the options are passed
311  // by the user. Users should not attempt to alter these!
312  int envlayout = 0; // Layout for environment wrap
313 
314  friend class pvt::TextureSystemImpl;
315 };
316 
317 
318 
319 /// DEPRECATED(1.8)
320 /// Encapsulate all the options needed for texture lookups. Making
321 /// these options all separate parameters to the texture API routines is
322 /// very ugly and also a big pain whenever we think of new options to
323 /// add. So instead we collect all those little options into one
324 /// structure that can just be passed by reference to the texture API
325 /// routines.
327 public:
328  /// Wrap mode describes what happens when texture coordinates describe
329  /// a value outside the usual [0,1] range where a texture is defined.
330  enum Wrap {
331  WrapDefault, ///< Use the default found in the file
332  WrapBlack, ///< Black outside [0..1]
333  WrapClamp, ///< Clamp to [0..1]
334  WrapPeriodic, ///< Periodic mod 1
335  WrapMirror, ///< Mirror the image
336  WrapPeriodicPow2, ///< Periodic, but only for powers of 2!!!
337  WrapPeriodicSharedBorder, ///< Periodic with shared border (env)
338  WrapLast ///< Mark the end -- don't use this!
339  };
340 
341  /// Mip mode determines if/how we use mipmaps
342  ///
343  enum MipMode {
344  MipModeDefault, ///< Default high-quality lookup
345  MipModeNoMIP, ///< Just use highest-res image, no MIP mapping
346  MipModeOneLevel, ///< Use just one mipmap level
347  MipModeTrilinear, ///< Use two MIPmap levels (trilinear)
348  MipModeAniso ///< Use two MIPmap levels w/ anisotropic
349  };
350 
351  /// Interp mode determines how we sample within a mipmap level
352  ///
353  enum InterpMode {
354  InterpClosest, ///< Force closest texel
355  InterpBilinear, ///< Force bilinear lookup within a mip level
356  InterpBicubic, ///< Force cubic lookup within a mip level
357  InterpSmartBicubic ///< Bicubic when maxifying, else bilinear
358  };
359 
360  /// Create a TextureOptions with all fields initialized to reasonable
361  /// defaults.
362  TextureOptions();
363 
364  /// Convert a TextureOpt for one point into a TextureOptions with
365  /// uniform values.
366  TextureOptions(const TextureOpt& opt);
367 
368  // Options that must be the same for all points we're texturing at once
369  int firstchannel; ///< First channel of the lookup
370  int subimage; ///< Subimage or face ID
371  ustring subimagename; ///< Subimage name
372  Wrap swrap; ///< Wrap mode in the s direction
373  Wrap twrap; ///< Wrap mode in the t direction
374  MipMode mipmode; ///< Mip mode
375  InterpMode interpmode; ///< Interpolation mode
376  int anisotropic; ///< Maximum anisotropic ratio
377  bool conservative_filter; ///< True == over-blur rather than alias
378 
379  // Options that may be different for each point we're texturing
380  VaryingRef<float> sblur, tblur; ///< Blur amount
381  VaryingRef<float> swidth, twidth; ///< Multiplier for derivatives
384  VaryingRef<float> fill; ///< Fill value for missing channels
385  VaryingRef<float> missingcolor; ///< Color for missing texture
386  VaryingRef<int> samples; ///< Number of samples
387 
388  // For 3D volume texture lookups only:
389  Wrap rwrap; ///< Wrap mode in the r direction
390  VaryingRef<float> rblur; ///< Blur amount in the r direction
391  VaryingRef<float> rwidth; ///< Multiplier for derivatives in r direction
392 
393  /// Utility: Return the Wrap enum corresponding to a wrap name:
394  /// "default", "black", "clamp", "periodic", "mirror".
395  static Wrap decode_wrapmode(const char* name)
396  {
397  return (Wrap)Tex::decode_wrapmode(name);
398  }
400  {
401  return (Wrap)Tex::decode_wrapmode(name);
402  }
403 
404  /// Utility: Parse a single wrap mode (e.g., "periodic") or a
405  /// comma-separated wrap modes string (e.g., "black,clamp") into
406  /// separate Wrap enums for s and t.
407  static void parse_wrapmodes(const char* wrapmodes,
408  TextureOptions::Wrap& swrapcode,
409  TextureOptions::Wrap& twrapcode)
410  {
411  Tex::parse_wrapmodes(wrapmodes, *(Tex::Wrap*)&swrapcode,
412  *(Tex::Wrap*)&twrapcode);
413  }
414 
415 private:
416  // Options set INTERNALLY by libtexture after the options are passed
417  // by the user. Users should not attempt to alter these!
418  friend class pvt::TextureSystemImpl;
419  friend class TextureOpt;
420 };
421 
422 
423 
424 
425 /// Define an API to an abstract class that that manages texture files,
426 /// caches of open file handles as well as tiles of texels so that truly
427 /// huge amounts of texture may be accessed by an application with low
428 /// memory footprint, and ways to perform antialiased texture, shadow
429 /// map, and environment map lookups.
431 public:
432  /// @{
433  /// @name Creating and destroying a texture system
434  ///
435  /// TextureSystem is an abstract API described as a pure virtual class.
436  /// The actual internal implementation is not exposed through the
437  /// external API of OpenImageIO. Because of this, you cannot construct
438  /// or destroy the concrete implementation, so two static methods of
439  /// TextureSystem are provided:
440 
441  /// Create a TextureSystem and return a pointer to it. This should only
442  /// be freed by passing it to TextureSystem::destroy()!
443  ///
444  /// @param shared
445  /// If `shared` is `true`, the pointer returned will be a shared
446  /// TextureSystem, (so that multiple parts of an application that
447  /// request a TextureSystem will all end up with the same one, and
448  /// the same underlying ImageCache). If `shared` is `false`, a
449  /// completely unique TextureCache will be created and returned.
450  ///
451  /// @param imagecache
452  /// If `shared` is `false` and `imagecache` is not `nullptr`, the
453  /// TextureSystem will use this as its underlying ImageCache. In
454  /// that case, it is the caller who is responsible for eventually
455  /// freeing the ImageCache after the TextureSystem is destroyed. If
456  /// `shared` is `false` and `imagecache` is `nullptr`, then a custom
457  /// ImageCache will be created, owned by the TextureSystem, and
458  /// automatically freed when the TS destroys.
459  ///
460  /// @returns
461  /// A raw pointer to a TextureSystem, which can only be freed with
462  /// `TextureSystem::destroy()`.
463  ///
464  /// @see TextureSystem::destroy
465  static TextureSystem *create (bool shared=true,
466  ImageCache *imagecache=nullptr);
467 
468  /// Destroy an allocated TextureSystem, including freeing all system
469  /// resources that it holds.
470  ///
471  /// It is safe to destroy even a shared TextureSystem, as the
472  /// implementation of `destroy()` will recognize a shared one and only
473  /// truly release its resources if it has been requested to be destroyed
474  /// as many times as shared TextureSystem's were created.
475  ///
476  /// @param ts
477  /// Raw pointer to the TextureSystem to destroy.
478  ///
479  /// @param teardown_imagecache
480  /// For a shared TextureSystem, if the `teardown_imagecache`
481  /// parameter is `true`, it will try to truly destroy the shared
482  /// cache if nobody else is still holding a reference (otherwise, it
483  /// will leave it intact). This parameter has no effect if `ts` was
484  /// not the single globally shared TextureSystem.
485  static void destroy (TextureSystem *ts,
486  bool teardown_imagecache = false);
487 
488  /// @}
489 
490 
491  /// @{
492  /// @name Setting options and limits for the texture system
493  ///
494  /// These are the list of attributes that can bet set or queried by
495  /// attribute/getattribute:
496  ///
497  /// All attributes ordinarily recognized by ImageCache are accepted and
498  /// passed through to the underlying ImageCache. These include:
499  /// - `int max_open_files` :
500  /// Maximum number of file handles held open.
501  /// - `float max_memory_MB` :
502  /// Maximum tile cache size, in MB.
503  /// - `string searchpath` :
504  /// Colon-separated search path for texture files.
505  /// - `string plugin_searchpath` :
506  /// Colon-separated search path for plugins.
507  /// - `int autotile` :
508  /// If >0, tile size to emulate for non-tiled images.
509  /// - `int autoscanline` :
510  /// If nonzero, autotile using full width tiles.
511  /// - `int automip` :
512  /// If nonzero, emulate mipmap on the fly.
513  /// - `int accept_untiled` :
514  /// If nonzero, accept untiled images.
515  /// - `int accept_unmipped` :
516  /// If nonzero, accept unmipped images.
517  /// - `int failure_retries` :
518  /// How many times to retry a read failure.
519  /// - `int deduplicate` :
520  /// If nonzero, detect duplicate textures (default=1).
521  /// - `string substitute_image` :
522  /// If supplied, an image to substatute for all texture
523  /// references.
524  /// - `int max_errors_per_file` :
525  /// Limits how many errors to issue for each file. (default:
526  /// 100)
527  ///
528  /// Texture-specific settings:
529  /// - `matrix44 worldtocommon` / `matrix44 commontoworld` :
530  /// The 4x4 matrices that provide the spatial transformation
531  /// from "world" to a "common" coordinate system and back.
532  /// This is mainly used for shadow map lookups, in which the
533  /// shadow map itself encodes the world coordinate system,
534  /// but positions passed to `shadow()` are expressed in
535  /// "common" coordinates. You do not need to set
536  /// `commontoworld` and `worldtocommon` separately; just
537  /// setting either one will implicitly set the other, since
538  /// each is the inverse of the other.
539  /// - `int gray_to_rgb` :
540  /// If set to nonzero, texture lookups of single-channel
541  /// (grayscale) images will replicate the sole channel's
542  /// values into the next two channels, making it behave like
543  /// an RGB image that happens to have all three channels
544  /// with identical pixel values. (Channels beyond the third
545  /// will get the "fill" value.) The default value of zero
546  /// means that all missing channels will get the "fill"
547  /// color.
548  /// - `int max_tile_channels` :
549  /// The maximum number of color channels in a texture file
550  /// for which all channels will be loaded as a single cached
551  /// tile. Files with more than this number of color channels
552  /// will have only the requested subset loaded, in order to
553  /// save cache space (but at the possible wasted expense of
554  /// separate tiles that overlap their channel ranges). The
555  /// default is 5.
556  /// - `int max_mip_res` :
557  /// **NEW 2.1** Sets the maximum MIP-map resolution for
558  /// filtered texture lookups. The MIP levels used will be
559  /// clamped to those having fewer than this number of pixels
560  /// in each dimension. This can be helpful as a way to limit
561  /// disk I/O when doing fast preview renders (with the
562  /// tradeoff that you may see some texture more blurry than
563  /// they would ideally be). The default is `1 << 30`, a
564  /// value so large that no such clamping will be performed.
565  /// - `string latlong_up` :
566  /// The default "up" direction for latlong environment maps
567  /// (only applies if the map itself doesn't specify a format
568  /// or is in a format that explicitly requires a particular
569  /// orientation). The default is `"y"`. (Currently any
570  /// other value will result in *z* being "up.")
571  /// - `int flip_t` :
572  /// If nonzero, `t` coordinates will be flipped `1-t` for
573  /// all texture lookups. The default is 0.
574  ///
575  /// - `string options`
576  /// This catch-all is simply a comma-separated list of
577  /// `name=value` settings of named options, which will be
578  /// parsed and individually set.
579  ///
580  /// ic->attribute ("options", "max_memory_MB=512.0,autotile=1");
581  ///
582  /// Note that if an option takes a string value that must
583  /// itself contain a comma, it is permissible to enclose the
584  /// value in either single `\'` or double `"` quotes.
585  ///
586  /// **Read-only attributes**
587  ///
588  /// Additionally, there are some read-only attributes that can be
589  /// queried with `getattribute()` even though they cannot be set via
590  /// `attribute()`:
591  ///
592  ///
593  /// The following member functions of TextureSystem allow you to set
594  /// (and in some cases retrieve) options that control the overall
595  /// behavior of the texture system:
596 
597  /// Set a named attribute (i.e., a property or option) of the
598  /// TextureSystem.
599  ///
600  /// Example:
601  ///
602  /// TextureSystem *ts;
603  /// ...
604  /// int maxfiles = 50;
605  /// ts->attribute ("max_open_files", TypeDesc::INT, &maxfiles);
606  ///
607  /// const char *path = "/my/path";
608  /// ts->attribute ("searchpath", TypeDesc::STRING, &path);
609  ///
610  /// // There are specialized versions for retrieving a single int,
611  /// // float, or string without needing types or pointers:
612  /// ts->getattribute ("max_open_files", 50);
613  /// ic->attribute ("max_memory_MB", 4000.0f);
614  /// ic->attribute ("searchpath", "/my/path");
615  ///
616  /// Note: When passing a string, you need to pass a pointer to the
617  /// `char*`, not a pointer to the first character. (Rationale: for an
618  /// `int` attribute, you pass the address of the `int`. So for a
619  /// string, which is a `char*`, you need to pass the address of the
620  /// string, i.e., a `char**`).
621  ///
622  /// @param name Name of the attribute to set.
623  /// @param type TypeDesc describing the type of the attribute.
624  /// @param val Pointer to the value data.
625  /// @returns `true` if the name and type were recognized and the
626  /// attribute was set, or `false` upon failure
627  /// (including it being an unrecognized attribute or not
628  /// of the correct type).
629  ///
630  virtual bool attribute (string_view name, TypeDesc type, const void *val) = 0;
631 
632  /// Specialized `attribute()` for setting a single `int` value.
633  virtual bool attribute (string_view name, int val) = 0;
634  /// Specialized `attribute()` for setting a single `float` value.
635  virtual bool attribute (string_view name, float val) = 0;
636  virtual bool attribute (string_view name, double val) = 0;
637  /// Specialized `attribute()` for setting a single string value.
638  virtual bool attribute (string_view name, string_view val) = 0;
639 
640  /// Get the named attribute of the texture system, store it in `*val`.
641  /// All of the attributes that may be set with the `attribute() call`
642  /// may also be queried with `getattribute()`.
643  ///
644  /// Examples:
645  ///
646  /// TextureSystem *ic;
647  /// ...
648  /// int maxfiles;
649  /// ts->getattribute ("max_open_files", TypeDesc::INT, &maxfiles);
650  ///
651  /// const char *path;
652  /// ts->getattribute ("searchpath", TypeDesc::STRING, &path);
653  ///
654  /// // There are specialized versions for retrieving a single int,
655  /// // float, or string without needing types or pointers:
656  /// int maxfiles;
657  /// ts->getattribute ("max_open_files", maxfiles);
658  /// const char *path;
659  /// ts->getattribute ("searchpath", &path);
660  ///
661  /// Note: When retrieving a string, you need to pass a pointer to the
662  /// `char*`, not a pointer to the first character. Also, the `char*`
663  /// will end up pointing to characters owned by the ImageCache; the
664  /// caller does not need to ever free the memory that contains the
665  /// characters.
666  ///
667  /// @param name Name of the attribute to retrieve.
668  /// @param type TypeDesc describing the type of the attribute.
669  /// @param val Pointer where the attribute value should be stored.
670  /// @returns `true` if the name and type were recognized and the
671  /// attribute was retrieved, or `false` upon failure
672  /// (including it being an unrecognized attribute or not
673  /// of the correct type).
674  virtual bool getattribute (string_view name,
675  TypeDesc type, void *val) const = 0;
676 
677  /// Specialized `attribute()` for retrieving a single `int` value.
678  virtual bool getattribute(string_view name, int& val) const = 0;
679  /// Specialized `attribute()` for retrieving a single `float` value.
680  virtual bool getattribute(string_view name, float& val) const = 0;
681  virtual bool getattribute(string_view name, double& val) const = 0;
682  /// Specialized `attribute()` for retrieving a single `string` value
683  /// as a `char*`.
684  virtual bool getattribute(string_view name, char** val) const = 0;
685  /// Specialized `attribute()` for retrieving a single `string` value
686  /// as a `std::string`.
687  virtual bool getattribute(string_view name, std::string& val) const = 0;
688 
689  /// @}
690 
691  /// @{
692  /// @name Opaque data for performance lookups
693  ///
694  /// The TextureSystem implementation needs to maintain certain
695  /// per-thread state, and some methods take an opaque `Perthread`
696  /// pointer to this record. There are three options for how to deal with
697  /// it:
698  ///
699  /// 1. Don't worry about it at all: don't use the methods that want
700  /// `Perthread` pointers, or always pass `nullptr` for any
701  /// `Perthread*1 arguments, and ImageCache will do
702  /// thread-specific-pointer retrieval as necessary (though at some
703  /// small cost).
704  ///
705  /// 2. If your app already stores per-thread information of its own, you
706  /// may call `get_perthread_info(nullptr)` to retrieve it for that
707  /// thread, and then pass it into the functions that allow it (thus
708  /// sparing them the need and expense of retrieving the
709  /// thread-specific pointer). However, it is crucial that this
710  /// pointer not be shared between multiple threads. In this case, the
711  /// ImageCache manages the storage, which will automatically be
712  /// released when the thread terminates.
713  ///
714  /// 3. If your app also wants to manage the storage of the `Perthread`,
715  /// it can explicitly create one with `create_perthread_info()`, pass
716  /// it around, and eventually be responsible for destroying it with
717  /// `destroy_perthread_info()`. When managing the storage, the app
718  /// may reuse the `Perthread` for another thread after the first is
719  /// terminated, but still may not use the same `Perthread` for two
720  /// threads running concurrently.
721 
722  /// Define an opaque data type that allows us to have a pointer to
723  /// certain per-thread information that the TextureSystem maintains. Any
724  /// given one of these should NEVER be shared between running threads.
725  class Perthread;
726 
727  /// Retrieve a Perthread, unique to the calling thread. This is a
728  /// thread-specific pointer that will always return the Perthread for a
729  /// thread, which will also be automatically destroyed when the thread
730  /// terminates.
731  ///
732  /// Applications that want to manage their own Perthread pointers (with
733  /// `create_thread_info` and `destroy_thread_info`) should still call
734  /// this, but passing in their managed pointer. If the passed-in
735  /// thread_info is not nullptr, it won't create a new one or retrieve a
736  /// TSP, but it will do other necessary housekeeping on the Perthread
737  /// information.
738  virtual Perthread* get_perthread_info(Perthread* thread_info = nullptr) = 0;
739 
740  /// Create a new Perthread. It is the caller's responsibility to
741  /// eventually destroy it using `destroy_thread_info()`.
742  virtual Perthread* create_thread_info() = 0;
743 
744  /// Destroy a Perthread that was allocated by `create_thread_info()`.
745  virtual void destroy_thread_info(Perthread* threadinfo) = 0;
746 
747  /// Define an opaque data type that allows us to have a handle to a
748  /// texture (already having its name resolved) but without exposing
749  /// any internals.
750  class TextureHandle;
751 
752  /// Retrieve an opaque handle for fast texture lookups. The opaque
753  /// pointer `thread_info` is thread-specific information returned by
754  /// `get_perthread_info()`. Return nullptr if something has gone
755  /// horribly wrong.
756  virtual TextureHandle * get_texture_handle (ustring filename,
757  Perthread *thread_info=nullptr) = 0;
758 
759  /// Return true if the texture handle (previously returned by
760  /// `get_image_handle()`) is a valid texture that can be subsequently
761  /// read.
762  virtual bool good(TextureHandle* texture_handle) = 0;
763 
764  /// @}
765 
766  /// @{
767  /// @name Texture lookups
768  ///
769 
770  /// Perform a filtered 2D texture lookup on a position centered at 2D
771  /// coordinates (`s`, `t`) from the texture identified by `filename`,
772  /// and using relevant texture `options`. The `nchannels` parameter
773  /// determines the number of channels to retrieve (e.g., 1 for a single
774  /// value, 3 for an RGB triple, etc.). The filtered results will be
775  /// stored in `result[0..nchannels-1]`.
776  ///
777  /// We assume that this lookup will be part of an image that has pixel
778  /// coordinates `x` and `y`. By knowing how `s` and `t` change from
779  /// pixel to pixel in the final image, we can properly *filter* or
780  /// antialias the texture lookups. This information is given via
781  /// derivatives `dsdx` and `dtdx` that define the change in `s` and `t`
782  /// per unit of `x`, and `dsdy` and `dtdy` that define the change in `s`
783  /// and `t` per unit of `y`. If it is impossible to know the
784  /// derivatives, you may pass 0 for them, but in that case you will not
785  /// receive an antialiased texture lookup.
786  ///
787  /// @param filename
788  /// The name of the texture.
789  /// @param options
790  /// Fields within `options` that are honored for 2D texture lookups
791  /// include the following:
792  /// - `int firstchannel` :
793  /// The index of the first channel to look up from the texture.
794  /// - `int subimage / ustring subimagename` :
795  /// The subimage or face within the file, specified by
796  /// either by name (if non-empty) or index. This will be
797  /// ignored if the file does not have multiple subimages or
798  /// separate per-face textures.
799  /// - `Wrap swrap, twrap` :
800  /// Specify the *wrap mode* for each direction, one of:
801  /// `WrapBlack`, `WrapClamp`, `WrapPeriodic`, `WrapMirror`,
802  /// or `WrapDefault`.
803  /// - `float swidth, twidth` :
804  /// For each direction, gives a multiplier for the derivatives.
805  /// - `float sblur, tblur` :
806  /// For each direction, specifies an additional amount of
807  /// pre-blur to apply to the texture (*after* derivatives
808  /// are taken into account), expressed as a portion of the
809  /// width of the texture.
810  /// - `float fill` :
811  /// Specifies the value that will be used for any color
812  /// channels that are requested but not found in the file.
813  /// For example, if you perform a 4-channel lookup on a
814  /// 3-channel texture, the last channel will get the fill
815  /// value. (Note: this behavior is affected by the
816  /// `"gray_to_rgb"` TextureSystem attribute.
817  /// - `const float *missingcolor` :
818  /// If not `nullptr`, specifies the color that will be
819  /// returned for missing or broken textures (rather than
820  /// being an error).
821  /// @param s/t
822  /// The 2D texture coordinates.
823  /// @param dsdx,dtdx,dsdy,dtdy
824  /// The differentials of s and t relative to canonical
825  /// directions x and y. The choice of x and y are not
826  /// important to the implementation; it can be any imposed
827  /// 2D coordinates, such as pixels in screen space, adjacent
828  /// samples in parameter space on a surface, etc. The st
829  /// derivatives determine the size and shape of the
830  /// ellipsoid over which the texture lookup is filtered.
831  /// @param nchannels
832  /// The number of channels of data to retrieve into `result`
833  /// (e.g., 1 for a single value, 3 for an RGB triple, etc.).
834  /// @param result[]
835  /// The result of the filtered texture lookup will be placed
836  /// into `result[0..nchannels-1]`.
837  /// @param dresultds/dresultdt
838  /// If non-null, these designate storage locations for the
839  /// derivatives of result, i.e., the rate of change per unit
840  /// s and t, respectively, of the filtered texture. If
841  /// supplied, they must allow for `nchannels` of storage.
842  /// @returns
843  /// `true` upon success, or `false` if the file was not
844  /// found or could not be opened by any available ImageIO
845  /// plugin.
846  ///
847  virtual bool texture (ustring filename, TextureOpt &options,
848  float s, float t, float dsdx, float dtdx,
849  float dsdy, float dtdy,
850  int nchannels, float *result,
851  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
852 
853  /// Slightly faster version of texture() lookup if the app already has a
854  /// texture handle and per-thread info.
855  virtual bool texture (TextureHandle *texture_handle,
856  Perthread *thread_info, TextureOpt &options,
857  float s, float t, float dsdx, float dtdx,
858  float dsdy, float dtdy,
859  int nchannels, float *result,
860  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
861 
862 
863  /// Perform a filtered 3D volumetric texture lookup on a position
864  /// centered at 3D position `P` (with given differentials) from the
865  /// texture identified by `filename`, and using relevant texture
866  /// `options`. The filtered results will be stored in
867  /// `result[0..nchannels-1]`.
868  ///
869  /// The `P` coordinate and `dPdx`, `dPdy`, and `dPdz` derivatives are
870  /// assumed to be in some kind of common global coordinate system
871  /// (usually "world" space) and will be automatically transformed into
872  /// volume local coordinates, if such a transformation is specified in
873  /// the volume file itself.
874  ///
875  /// @param filename
876  /// The name of the texture.
877  /// @param options
878  /// Fields within `options` that are honored for 3D texture lookups
879  /// include the following:
880  /// - `int firstchannel` :
881  /// The index of the first channel to look up from the texture.
882  /// - `int subimage / ustring subimagename` :
883  /// The subimage or field within the volume, specified by
884  /// either by name (if non-empty) or index. This will be
885  /// ignored if the file does not have multiple subimages or
886  /// separate per-face textures.
887  /// - `Wrap swrap, twrap, rwrap` :
888  /// Specify the *wrap mode* for each direction, one of:
889  /// `WrapBlack`, `WrapClamp`, `WrapPeriodic`, `WrapMirror`,
890  /// or `WrapDefault`.
891  /// - `float swidth, twidth, rwidth` :
892  /// For each direction, gives a multiplier for the derivatives.
893  /// - `float sblur, tblur, rblur` :
894  /// For each direction, specifies an additional amount of
895  /// pre-blur to apply to the texture (*after* derivatives
896  /// are taken into account), expressed as a portion of the
897  /// width of the texture.
898  /// - `float fill` :
899  /// Specifies the value that will be used for any color
900  /// channels that are requested but not found in the file.
901  /// For example, if you perform a 4-channel lookup on a
902  /// 3-channel texture, the last channel will get the fill
903  /// value. (Note: this behavior is affected by the
904  /// `"gray_to_rgb"` TextureSystem attribute.
905  /// - `const float *missingcolor` :
906  /// If not `nullptr`, specifies the color that will be
907  /// returned for missing or broken textures (rather than
908  /// being an error).
909  /// - `float time` :
910  /// A time value to use if the volume texture specifies a
911  /// time-varying local transformation (default: 0).
912  /// @param P
913  /// The 2D texture coordinates.
914  /// @param dPdx/dPdy/dPdz
915  /// The differentials of `P`. We assume that this lookup
916  /// will be part of an image that has pixel coordinates `x`
917  /// and `y` and depth `z`. By knowing how `P` changes from
918  /// pixel to pixel in the final image, and as we step in *z*
919  /// depth, we can properly *filter* or antialias the texture
920  /// lookups. This information is given via derivatives
921  /// `dPdx`, `dPdy`, and `dPdz` that define the changes in
922  /// `P` per unit of `x`, `y`, and `z`, respectively. If it
923  /// is impossible to know the derivatives, you may pass 0
924  /// for them, but in that case you will not receive an
925  /// antialiased texture lookup.
926  /// @param nchannels
927  /// The number of channels of data to retrieve into `result`
928  /// (e.g., 1 for a single value, 3 for an RGB triple, etc.).
929  /// @param result[]
930  /// The result of the filtered texture lookup will be placed
931  /// into `result[0..nchannels-1]`.
932  /// @param dresultds/dresultdt/dresultdr
933  /// If non-null, these designate storage locations for the
934  /// derivatives of result, i.e., the rate of change per unit
935  /// s, t, and r, respectively, of the filtered texture. If
936  /// supplied, they must allow for `nchannels` of storage.
937  /// @returns
938  /// `true` upon success, or `false` if the file was not
939  /// found or could not be opened by any available ImageIO
940  /// plugin.
941  ///
942  virtual bool texture3d (ustring filename, TextureOpt &options,
943  const Imath::V3f &P, const Imath::V3f &dPdx,
944  const Imath::V3f &dPdy, const Imath::V3f &dPdz,
945  int nchannels, float *result,
946  float *dresultds=nullptr, float *dresultdt=nullptr,
947  float *dresultdr=nullptr) = 0;
948 
949  /// Slightly faster version of texture3d() lookup if the app already has
950  /// a texture handle and per-thread info.
951  virtual bool texture3d (TextureHandle *texture_handle,
952  Perthread *thread_info, TextureOpt &options,
953  const Imath::V3f &P, const Imath::V3f &dPdx,
954  const Imath::V3f &dPdy, const Imath::V3f &dPdz,
955  int nchannels, float *result,
956  float *dresultds=nullptr, float *dresultdt=nullptr,
957  float *dresultdr=nullptr) = 0;
958 
959 
960  // Retrieve a shadow lookup for a single position P.
961  //
962  // Return true if the file is found and could be opened by an
963  // available ImageIO plugin, otherwise return false.
964  virtual bool shadow (ustring filename, TextureOpt &options,
965  const Imath::V3f &P, const Imath::V3f &dPdx,
966  const Imath::V3f &dPdy, float *result,
967  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
968 
969  // Slightly faster version of texture3d() lookup if the app already
970  // has a texture handle and per-thread info.
971  virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info,
972  TextureOpt &options,
973  const Imath::V3f &P, const Imath::V3f &dPdx,
974  const Imath::V3f &dPdy, float *result,
975  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
976 
977  /// Perform a filtered directional environment map lookup in the
978  /// direction of vector `R`, from the texture identified by `filename`,
979  /// and using relevant texture `options`. The filtered results will be
980  /// stored in `result[]`.
981  ///
982  /// @param filename
983  /// The name of the texture.
984  /// @param options
985  /// Fields within `options` that are honored for environment lookups
986  /// include the following:
987  /// - `int firstchannel` :
988  /// The index of the first channel to look up from the texture.
989  /// - `int subimage / ustring subimagename` :
990  /// The subimage or face within the file, specified by
991  /// either by name (if non-empty) or index. This will be
992  /// ignored if the file does not have multiple subimages or
993  /// separate per-face textures.
994  /// - `float swidth, twidth` :
995  /// For each direction, gives a multiplier for the
996  /// derivatives.
997  /// - `float sblur, tblur` :
998  /// For each direction, specifies an additional amount of
999  /// pre-blur to apply to the texture (*after* derivatives
1000  /// are taken into account), expressed as a portion of the
1001  /// width of the texture.
1002  /// - `float fill` :
1003  /// Specifies the value that will be used for any color
1004  /// channels that are requested but not found in the file.
1005  /// For example, if you perform a 4-channel lookup on a
1006  /// 3-channel texture, the last channel will get the fill
1007  /// value. (Note: this behavior is affected by the
1008  /// `"gray_to_rgb"` TextureSystem attribute.
1009  /// - `const float *missingcolor` :
1010  /// If not `nullptr`, specifies the color that will be
1011  /// returned for missing or broken textures (rather than
1012  /// being an error).
1013  /// @param R
1014  /// The direction vector to look up.
1015  /// @param dRdx/dRdy
1016  /// The differentials of `R` with respect to image
1017  /// coordinates x and y.
1018  /// @param nchannels
1019  /// The number of channels of data to retrieve into `result`
1020  /// (e.g., 1 for a single value, 3 for an RGB triple, etc.).
1021  /// @param result[]
1022  /// The result of the filtered texture lookup will be placed
1023  /// into `result[0..nchannels-1]`.
1024  /// @param dresultds/dresultdt
1025  /// If non-null, these designate storage locations for the
1026  /// derivatives of result, i.e., the rate of change per unit
1027  /// s and t, respectively, of the filtered texture. If
1028  /// supplied, they must allow for `nchannels` of storage.
1029  /// @returns
1030  /// `true` upon success, or `false` if the file was not
1031  /// found or could not be opened by any available ImageIO
1032  /// plugin.
1033  virtual bool environment (ustring filename, TextureOpt &options,
1034  const Imath::V3f &R, const Imath::V3f &dRdx,
1035  const Imath::V3f &dRdy, int nchannels, float *result,
1036  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1037 
1038  /// Slightly faster version of environment() if the app already has a
1039  /// texture handle and per-thread info.
1040  virtual bool environment (TextureHandle *texture_handle,
1041  Perthread *thread_info, TextureOpt &options,
1042  const Imath::V3f &R, const Imath::V3f &dRdx,
1043  const Imath::V3f &dRdy, int nchannels, float *result,
1044  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1045 
1046  /// @}
1047 
1048  /// @{
1049  /// @name Batched texture lookups
1050  ///
1051 
1052  /// Perform filtered 2D texture lookups on a batch of positions from the
1053  /// same texture, all at once. The parameters `s`, `t`, `dsdx`, `dtdx`,
1054  /// and `dsdy`, `dtdy` are each a pointer to `[BatchWidth]` values. The
1055  /// `mask` determines which of those array elements to actually compute.
1056  ///
1057  /// The float* results act like `float[nchannels][BatchWidth]`, so that
1058  /// effectively `result[0..BatchWidth-1]` are the "red" result for each
1059  /// lane, `result[BatchWidth..2*BatchWidth-1]` are the "green" results,
1060  /// etc. The `dresultds` and `dresultdt` should either both be provided,
1061  /// or else both be nullptr (meaning no derivative results are
1062  /// required).
1063  ///
1064  /// @param filename
1065  /// The name of the texture.
1066  /// @param options
1067  /// A TextureOptBatch containing texture lookup options.
1068  /// This is conceptually the same as a TextureOpt, but the
1069  /// following fields are arrays of `[BatchWidth]` elements:
1070  /// sblur, tblur, swidth, twidth. The other fields are, as
1071  /// with TextureOpt, ordinary scalar values.
1072  /// @param mask
1073  /// A bit-field designating which "lanes" should be
1074  /// computed: if `mask & (1<<i)` is nonzero, then results
1075  /// should be computed and stored for `result[...][i]`.
1076  /// @param s/t
1077  /// Pointers to the 2D texture coordinates, each as a
1078  /// `float[BatchWidth]`.
1079  /// @param dsdx/dtdx/dsdy/dtdy
1080  /// The differentials of s and t relative to canonical
1081  /// directions x and y, each as a `float[BatchWidth]`.
1082  /// @param nchannels
1083  /// The number of channels of data to retrieve into `result`
1084  /// (e.g., 1 for a single value, 3 for an RGB triple, etc.).
1085  /// @param result[]
1086  /// The result of the filtered texture lookup will be placed
1087  /// here, as `float [nchannels][BatchWidth]`. (Note the
1088  /// "SOA" data layout.)
1089  /// @param dresultds/dresultdt
1090  /// If non-null, these designate storage locations for the
1091  /// derivatives of result, and like `result` are in SOA
1092  /// layout: `float [nchannels][BatchWidth]`
1093  /// @returns
1094  /// `true` upon success, or `false` if the file was not
1095  /// found or could not be opened by any available ImageIO
1096  /// plugin.
1097  ///
1098  virtual bool texture (ustring filename, TextureOptBatch &options,
1099  Tex::RunMask mask, const float *s, const float *t,
1100  const float *dsdx, const float *dtdx,
1101  const float *dsdy, const float *dtdy,
1102  int nchannels, float *result,
1103  float *dresultds=nullptr,
1104  float *dresultdt=nullptr) = 0;
1105  /// Slightly faster version of texture() lookup if the app already has a
1106  /// texture handle and per-thread info.
1107  virtual bool texture (TextureHandle *texture_handle,
1108  Perthread *thread_info, TextureOptBatch &options,
1109  Tex::RunMask mask, const float *s, const float *t,
1110  const float *dsdx, const float *dtdx,
1111  const float *dsdy, const float *dtdy,
1112  int nchannels, float *result,
1113  float *dresultds=nullptr,
1114  float *dresultdt=nullptr) = 0;
1115 
1116  // Old multi-point API call.
1117  // DEPRECATED (1.8)
1118  virtual bool texture (ustring filename, TextureOptions &options,
1119  Runflag *runflags, int beginactive, int endactive,
1123  int nchannels, float *result,
1124  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1125  virtual bool texture (TextureHandle *texture_handle,
1126  Perthread *thread_info, TextureOptions &options,
1127  Runflag *runflags, int beginactive, int endactive,
1131  int nchannels, float *result,
1132  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1133 
1134  /// Perform filtered 3D volumetric texture lookups on a batch of
1135  /// positions from the same texture, all at once. The "point-like"
1136  /// parameters `P`, `dPdx`, `dPdy`, and `dPdz` are each a pointers to
1137  /// arrays of `float value[3][BatchWidth]` (or alternately like
1138  /// `Imath::Vec3<FloatWide>`). That is, each one points to all the *x*
1139  /// values for the batch, immediately followed by all the *y* values,
1140  /// followed by the *z* values. The `mask` determines which of those
1141  /// array elements to actually compute.
1142  ///
1143  /// The various results arrays are also arranged as arrays that behave
1144  /// as if they were declared `float result[channels][BatchWidth]`, where
1145  /// all the batch values for channel 0 are adjacent, followed by all the
1146  /// batch values for channel 1, etc.
1147  ///
1148  /// @param filename
1149  /// The name of the texture.
1150  /// @param options
1151  /// A TextureOptBatch containing texture lookup options.
1152  /// This is conceptually the same as a TextureOpt, but the
1153  /// following fields are arrays of `[BatchWidth]` elements:
1154  /// sblur, tblur, swidth, twidth. The other fields are, as
1155  /// with TextureOpt, ordinary scalar values.
1156  /// @param mask
1157  /// A bit-field designating which "lanes" should be
1158  /// computed: if `mask & (1<<i)` is nonzero, then results
1159  /// should be computed and stored for `result[...][i]`.
1160  /// @param P
1161  /// Pointers to the 3D texture coordinates, each as a
1162  /// `float[3][BatchWidth]`.
1163  /// @param dPdx/dPdy/dPdz
1164  /// The differentials of P relative to canonical directions
1165  /// x, y, and z, each as a `float[3][BatchWidth]`.
1166  /// @param nchannels
1167  /// The number of channels of data to retrieve into `result`
1168  /// (e.g., 1 for a single value, 3 for an RGB triple, etc.).
1169  /// @param result[]
1170  /// The result of the filtered texture lookup will be placed
1171  /// here, as `float [nchannels][BatchWidth]`. (Note the
1172  /// "SOA" data layout.)
1173  /// @param dresultds/dresultdt/dresultdr
1174  /// If non-null, these designate storage locations for the
1175  /// derivatives of result, and like `result` are in SOA
1176  /// layout: `float [nchannels][BatchWidth]`
1177  /// @returns
1178  /// `true` upon success, or `false` if the file was not
1179  /// found or could not be opened by any available ImageIO
1180  /// plugin.
1181  ///
1182  virtual bool texture3d (ustring filename,
1183  TextureOptBatch &options, Tex::RunMask mask,
1184  const float *P, const float *dPdx,
1185  const float *dPdy, const float *dPdz,
1186  int nchannels, float *result,
1187  float *dresultds=nullptr, float *dresultdt=nullptr,
1188  float *dresultdr=nullptr) = 0;
1189  /// Slightly faster version of texture3d() lookup if the app already
1190  /// has a texture handle and per-thread info.
1191  virtual bool texture3d (TextureHandle *texture_handle,
1192  Perthread *thread_info,
1193  TextureOptBatch &options, Tex::RunMask mask,
1194  const float *P, const float *dPdx,
1195  const float *dPdy, const float *dPdz,
1196  int nchannels, float *result,
1197  float *dresultds=nullptr, float *dresultdt=nullptr,
1198  float *dresultdr=nullptr) = 0;
1199 
1200  // Retrieve a 3D texture lookup at many points at once.
1201  // DEPRECATED(1.8)
1202  virtual bool texture3d (ustring filename, TextureOptions &options,
1203  Runflag *runflags, int beginactive, int endactive,
1208  int nchannels, float *result,
1209  float *dresultds=nullptr, float *dresultdt=nullptr,
1210  float *dresultdr=nullptr) = 0;
1211  virtual bool texture3d (TextureHandle *texture_handle,
1212  Perthread *thread_info, TextureOptions &options,
1213  Runflag *runflags, int beginactive, int endactive,
1218  int nchannels, float *result,
1219  float *dresultds=nullptr, float *dresultdt=nullptr,
1220  float *dresultdr=nullptr) = 0;
1221 
1222  /// Perform filtered directional environment map lookups on a batch of
1223  /// directions from the same texture, all at once. The "point-like"
1224  /// parameters `R`, `dRdx`, and `dRdy` are each a pointers to arrays of
1225  /// `float value[3][BatchWidth]` (or alternately like
1226  /// `Imath::Vec3<FloatWide>`). That is, each one points to all the *x*
1227  /// values for the batch, immediately followed by all the *y* values,
1228  /// followed by the *z* values. The `mask` determines which of those
1229  /// array elements to actually compute.
1230  ///
1231  /// The various results arrays are also arranged as arrays that behave
1232  /// as if they were declared `float result[channels][BatchWidth]`, where
1233  /// all the batch values for channel 0 are adjacent, followed by all the
1234  /// batch values for channel 1, etc.
1235  ///
1236  /// @param filename
1237  /// The name of the texture.
1238  /// @param options
1239  /// A TextureOptBatch containing texture lookup options.
1240  /// This is conceptually the same as a TextureOpt, but the
1241  /// following fields are arrays of `[BatchWidth]` elements:
1242  /// sblur, tblur, swidth, twidth. The other fields are, as
1243  /// with TextureOpt, ordinary scalar values.
1244  /// @param mask
1245  /// A bit-field designating which "lanes" should be
1246  /// computed: if `mask & (1<<i)` is nonzero, then results
1247  /// should be computed and stored for `result[...][i]`.
1248  /// @param R
1249  /// Pointers to the 3D texture coordinates, each as a
1250  /// `float[3][BatchWidth]`.
1251  /// @param dRdx/dRdy
1252  /// The differentials of R relative to canonical directions
1253  /// x and y, each as a `float[3][BatchWidth]`.
1254  /// @param nchannels
1255  /// The number of channels of data to retrieve into `result`
1256  /// (e.g., 1 for a single value, 3 for an RGB triple, etc.).
1257  /// @param result[]
1258  /// The result of the filtered texture lookup will be placed
1259  /// here, as `float [nchannels][BatchWidth]`. (Note the
1260  /// "SOA" data layout.)
1261  /// @param dresultds/dresultdt
1262  /// If non-null, these designate storage locations for the
1263  /// derivatives of result, and like `result` are in SOA
1264  /// layout: `float [nchannels][BatchWidth]`
1265  /// @returns
1266  /// `true` upon success, or `false` if the file was not
1267  /// found or could not be opened by any available ImageIO
1268  /// plugin.
1269  ///
1270  virtual bool environment (ustring filename,
1271  TextureOptBatch &options, Tex::RunMask mask,
1272  const float *R, const float *dRdx, const float *dRdy,
1273  int nchannels, float *result,
1274  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1275  /// Slightly faster version of environment() if the app already has a
1276  /// texture handle and per-thread info.
1277  virtual bool environment (TextureHandle *texture_handle, Perthread *thread_info,
1278  TextureOptBatch &options, Tex::RunMask mask,
1279  const float *R, const float *dRdx, const float *dRdy,
1280  int nchannels, float *result,
1281  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1282 
1283  // Retrieve an environment map lookup for direction R, for many
1284  // points at once.
1285  // DEPRECATED(1.8)
1286  virtual bool environment (ustring filename, TextureOptions &options,
1287  Runflag *runflags, int beginactive, int endactive,
1291  int nchannels, float *result,
1292  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1293  virtual bool environment (TextureHandle *texture_handle,
1294  Perthread *thread_info, TextureOptions &options,
1295  Runflag *runflags, int beginactive, int endactive,
1299  int nchannels, float *result,
1300  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1301 
1302  // Batched shadow lookups
1303  virtual bool shadow (ustring filename,
1304  TextureOptBatch &options, Tex::RunMask mask,
1305  const float *P, const float *dPdx, const float *dPdy,
1306  float *result, float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1307  virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info,
1308  TextureOptBatch &options, Tex::RunMask mask,
1309  const float *P, const float *dPdx, const float *dPdy,
1310  float *result, float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1311 
1312  // Retrieve a shadow lookup for position P at many points at once.
1313  // DEPRECATED(1.8)
1314  virtual bool shadow (ustring filename, TextureOptions &options,
1315  Runflag *runflags, int beginactive, int endactive,
1319  float *result,
1320  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1321  virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info,
1322  TextureOptions &options,
1323  Runflag *runflags, int beginactive, int endactive,
1327  float *result,
1328  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
1329 
1330  /// @}
1331 
1332 
1333  /// @{
1334  /// @name Texture metadata and raw texels
1335  ///
1336 
1337  /// Given possibly-relative 'filename', resolve it using the search
1338  /// path rules and return the full resolved filename.
1339  virtual std::string resolve_filename (const std::string &filename) const=0;
1340 
1341  /// Get information or metadata about the named texture and store it in
1342  /// `*data`.
1343  ///
1344  /// Data names may include any of the following:
1345  ///
1346  /// - `exists` (int):
1347  /// Stores the value 1 if the file exists and is an image format
1348  /// that OpenImageIO can read, or 0 if the file does not exist,
1349  /// or could not be properly read as a texture. Note that unlike
1350  /// all other queries, this query will "succeed" (return `true`)
1351  /// even if the file does not exist.
1352  ///
1353  /// - `udim` (int) :
1354  /// Stores the value 1 if the file is a "virtual UDIM" or
1355  /// texture atlas file (as described in Section
1356  /// :ref:`sec-texturesys-udim`) or 0 otherwise.
1357  ///
1358  /// - `subimages` (int) :
1359  /// The number of subimages/faces in the file, as an integer.
1360  ///
1361  /// - `resolution` (int[2] or int[3]):
1362  /// The resolution of the texture file, if an array of 2
1363  /// integers (described as `TypeDesc(INT,2)`), or the 3D
1364  /// resolution of the texture file, which is an array of 3
1365  /// integers (described as `TypeDesc(INT,3)`) The third value
1366  /// will be 1 unless it's a volumetric (3D) image.
1367  ///
1368  /// - `miplevels` (int) :
1369  /// The number of MIPmap levels for the specified
1370  /// subimage (an integer).
1371  ///
1372  /// - `texturetype` (string) :
1373  /// A string describing the type of texture of the given file,
1374  /// which describes how the texture may be used (also which
1375  /// texture API call is probably the right one for it). This
1376  /// currently may return one of: "unknown", "Plain Texture",
1377  /// "Volume Texture", "Shadow", or "Environment".
1378  ///
1379  /// - `textureformat` (string) :
1380  /// A string describing the format of the given file, which
1381  /// describes the kind of texture stored in the file. This
1382  /// currently may return one of: "unknown", "Plain Texture",
1383  /// "Volume Texture", "Shadow", "CubeFace Shadow", "Volume
1384  /// Shadow", "LatLong Environment", or "CubeFace Environment".
1385  /// Note that there are several kinds of shadows and environment
1386  /// maps, all accessible through the same API calls.
1387  ///
1388  /// - `channels` (int) :
1389  /// The number of color channels in the file.
1390  ///
1391  /// - `format` (int) :
1392  /// The native data format of the pixels in the file (an
1393  /// integer, giving the `TypeDesc::BASETYPE` of the data). Note
1394  /// that this is not necessarily the same as the data format
1395  /// stored in the image cache.
1396  ///
1397  /// - `cachedformat` (int) :
1398  /// The native data format of the pixels as stored in the image
1399  /// cache (an integer, giving the `TypeDesc::BASETYPE` of the
1400  /// data). Note that this is not necessarily the same as the
1401  /// native data format of the file.
1402  ///
1403  /// - `datawindow` (int[4] or int[6]):
1404  /// Returns the pixel data window of the image, which is either
1405  /// an array of 4 integers (returning xmin, ymin, xmax, ymax) or
1406  /// an array of 6 integers (returning xmin, ymin, zmin, xmax,
1407  /// ymax, zmax). The z values may be useful for 3D/volumetric
1408  /// images; for 2D images they will be 0).
1409  ///
1410  /// - `displaywindow` (matrix) :
1411  /// Returns the display (a.k.a. full) window of the image, which
1412  /// is either an array of 4 integers (returning xmin, ymin,
1413  /// xmax, ymax) or an array of 6 integers (returning xmin, ymin,
1414  /// zmin, xmax, ymax, zmax). The z values may be useful for
1415  /// 3D/volumetric images; for 2D images they will be 0).
1416  ///
1417  /// - `worldtocamera` (matrix) :
1418  /// The viewing matrix, which is a 4x4 matrix (an `Imath::M44f`,
1419  /// described as `TypeMatrix44`) giving the world-to-camera 3D
1420  /// transformation matrix that was used when the image was
1421  /// created. Generally, only rendered images will have this.
1422  ///
1423  /// - `worldtoscreen` (matrix) :
1424  /// The projection matrix, which is a 4x4 matrix (an
1425  /// `Imath::M44f`, described as `TypeMatrix44`) giving the
1426  /// matrix that projected points from world space into a 2D
1427  /// screen coordinate system where *x* and *y* range from -1 to
1428  /// +1. Generally, only rendered images will have this.
1429  ///
1430  /// - `worldtoNDC` (matrix) :
1431  /// The projection matrix, which is a 4x4 matrix (an
1432  /// `Imath::M44f`, described as `TypeMatrix44`) giving the
1433  /// matrix that projected points from world space into a 2D
1434  /// screen coordinate system where *x* and *y* range from 0 to
1435  /// +1. Generally, only rendered images will have this.
1436  ///
1437  /// - `averagecolor` (float[nchannels]) :
1438  /// If available in the metadata (generally only for files that
1439  /// have been processed by `maketx`), this will return the
1440  /// average color of the texture (into an array of floats).
1441  ///
1442  /// - `averagealpha` (float) :
1443  /// If available in the metadata (generally only for files that
1444  /// have been processed by `maketx`), this will return the
1445  /// average alpha value of the texture (into a float).
1446  ///
1447  /// - `constantcolor` (float[nchannels]) :
1448  /// If the metadata (generally only for files that have been
1449  /// processed by `maketx`) indicates that the texture has the
1450  /// same values for all pixels in the texture, this will
1451  /// retrieve the constant color of the texture (into an array of
1452  /// floats). A non-constant image (or one that does not have the
1453  /// special metadata tag identifying it as a constant texture)
1454  /// will fail this query (return false).
1455  ///
1456  /// - `constantalpha` (float) :
1457  /// If the metadata indicates that the texture has the same
1458  /// values for all pixels in the texture, this will retrieve the
1459  /// constant alpha value of the texture. A non-constant image
1460  /// (or one that does not have the special metadata tag
1461  /// identifying it as a constant texture) will fail this query
1462  /// (return false).
1463  ///
1464  /// - `stat:tilesread` (int64) :
1465  /// Number of tiles read from this file.
1466  ///
1467  /// - `stat:bytesread` (int64) :
1468  /// Number of bytes of uncompressed pixel data read
1469  ///
1470  /// - `stat:redundant_tiles` (int64) :
1471  /// Number of times a tile was read, where the same tile had
1472  /// been rad before.
1473  ///
1474  /// - `stat:redundant_bytesread` (int64) :
1475  /// Number of bytes (of uncompressed pixel data) in tiles that
1476  /// were read redundantly.
1477  ///
1478  /// - `stat:redundant_bytesread` (int) :
1479  /// Number of tiles read from this file.
1480  ///
1481  /// - `stat:timesopened` (int) :
1482  /// Number of times this file was opened.
1483  ///
1484  /// - `stat:iotime` (float) :
1485  /// Time (in seconds) spent on all I/O for this file.
1486  ///
1487  /// - `stat:mipsused` (int) :
1488  /// Stores 1 if any MIP levels beyond the highest resolution
1489  /// were accessed, otherwise 0.
1490  ///
1491  /// - `stat:is_duplicate` (int) :
1492  /// Stores 1 if this file was a duplicate of another image,
1493  /// otherwise 0.
1494  ///
1495  /// - *Anything else* :
1496  /// For all other data names, the the metadata of the image file
1497  /// will be searched for an item that matches both the name and
1498  /// data type.
1499  ///
1500  ///
1501  /// @param filename
1502  /// The name of the texture.
1503  /// @param subimage
1504  /// The subimage to query. (The metadata retrieved is for
1505  /// the highest-resolution MIP level of that subimage.)
1506  /// @param dataname
1507  /// The name of the metadata to retrieve.
1508  /// @param datatype
1509  /// TypeDesc describing the data type.
1510  /// @param data
1511  /// Pointer to the caller-owned memory where the values
1512  /// should be stored. It is the caller's responsibility to
1513  /// ensure that `data` points to a large enough storage area
1514  /// to accommodate the `datatype` requested.
1515  ///
1516  /// @returns
1517  /// `true` if `get_textureinfo()` is able to find the
1518  /// requested `dataname` for the texture and it matched the
1519  /// requested `datatype`. If the requested data was not
1520  /// found or was not of the right data type, return `false`.
1521  /// Except for the `"exists"` query, a file that does not
1522  /// exist or could not be read properly as an image also
1523  /// constitutes a query failure that will return `false`.
1524  virtual bool get_texture_info (ustring filename, int subimage,
1525  ustring dataname, TypeDesc datatype, void *data) = 0;
1526 
1527  /// A more efficient variety of `get_texture_info()` for cases where you
1528  /// can use a `TextureHandle*` to specify the image and optionally have
1529  /// a `Perthread*` for the calling thread.
1530  virtual bool get_texture_info (TextureHandle *texture_handle,
1531  Perthread *thread_info, int subimage,
1532  ustring dataname, TypeDesc datatype, void *data) = 0;
1533 
1534  /// Copy the ImageSpec associated with the named texture (the first
1535  /// subimage by default, or as set by `subimage`).
1536  ///
1537  /// @param filename
1538  /// The name of the image.
1539  /// @param subimage
1540  /// The subimage to query. (The spec retrieved is for the
1541  /// highest-resolution MIP level of that subimage.)
1542  /// @param spec
1543  /// ImageSpec into which will be copied the spec for the
1544  /// requested image.
1545  /// @returns
1546  /// `true` upon success, `false` upon failure failure (such
1547  /// as being unable to find, open, or read the file, or if
1548  /// it does not contain the designated subimage or MIP
1549  /// level).
1550  virtual bool get_imagespec (ustring filename, int subimage,
1551  ImageSpec &spec) = 0;
1552  /// A more efficient variety of `get_imagespec()` for cases where you
1553  /// can use a `TextureHandle*` to specify the image and optionally have
1554  /// a `Perthread*` for the calling thread.
1555  virtual bool get_imagespec (TextureHandle *texture_handle,
1556  Perthread *thread_info, int subimage,
1557  ImageSpec &spec) = 0;
1558 
1559  /// Return a pointer to an ImageSpec associated with the named texture
1560  /// if the file is found and is an image format that can be read,
1561  /// otherwise return `nullptr`.
1562  ///
1563  /// This method is much more efficient than `get_imagespec()`, since it
1564  /// just returns a pointer to the spec held internally by the
1565  /// TextureSystem (rather than copying the spec to the user's memory).
1566  /// However, the caller must beware that the pointer is only valid as
1567  /// long as nobody (even other threads) calls `invalidate()` on the
1568  /// file, or `invalidate_all()`, or destroys the TextureSystem and its
1569  /// underlying ImageCache.
1570  ///
1571  /// @param filename
1572  /// The name of the image.
1573  /// @param subimage
1574  /// The subimage to query. (The spec retrieved is for the
1575  /// highest-resolution MIP level of that subimage.)
1576  /// @returns
1577  /// A pointer to the spec, if the image is found and able to
1578  /// be opened and read by an available image format plugin,
1579  /// and the designated subimage exists.
1580  virtual const ImageSpec *imagespec (ustring filename, int subimage=0) = 0;
1581  /// A more efficient variety of `imagespec()` for cases where you can
1582  /// use a `TextureHandle*` to specify the image and optionally have a
1583  /// `Perthread*` for the calling thread.
1584  virtual const ImageSpec *imagespec (TextureHandle *texture_handle,
1585  Perthread *thread_info = nullptr,
1586  int subimage=0) = 0;
1587 
1588  /// For a texture specified by name, retrieve the rectangle of raw
1589  /// unfiltered texels from the subimage specified in `options` and at
1590  /// the designated `miplevel`, storing the pixel values beginning at the
1591  /// address specified by `result`. The pixel values will be converted
1592  /// to the data type specified by `format`. The rectangular region to be
1593  /// retrieved includes `begin` but does not include `end` (much like STL
1594  /// begin/end usage). Requested pixels that are not part of the valid
1595  /// pixel data region of the image file will be filled with zero values.
1596  /// Channels requested but not present in the file will get the
1597  /// `options.fill` value.
1598  ///
1599  /// @param filename
1600  /// The name of the image.
1601  /// @param options
1602  /// A TextureOpt describing access options, including wrap
1603  /// modes, fill value, and subimage, that will be used when
1604  /// retrieving pixels.
1605  /// @param miplevel
1606  /// The MIP level to retrieve pixels from (0 is the highest
1607  /// resolution level).
1608  /// @param xbegin/xend/ybegin/yend/zbegin/zend
1609  /// The range of pixels to retrieve. The pixels retrieved
1610  /// include the begin value but not the end value (much like
1611  /// STL begin/end usage).
1612  /// @param chbegin/chend
1613  /// Channel range to retrieve. To retrieve all channels, use
1614  /// `chbegin = 0`, `chend = nchannels`.
1615  /// @param format
1616  /// TypeDesc describing the data type of the values you want
1617  /// to retrieve into `result`. The pixel values will be
1618  /// converted to this type regardless of how they were
1619  /// stored in the file or in the cache.
1620  /// @param result
1621  /// Pointer to the memory where the pixel values should be
1622  /// stored. It is up to the caller to ensure that `result`
1623  /// points to an area of memory big enough to accommodate
1624  /// the requested rectangle (taking into consideration its
1625  /// dimensions, number of channels, and data format).
1626  ///
1627  /// @returns
1628  /// `true` for success, `false` for failure.
1629  virtual bool get_texels (ustring filename, TextureOpt &options,
1630  int miplevel, int xbegin, int xend,
1631  int ybegin, int yend, int zbegin, int zend,
1632  int chbegin, int chend,
1633  TypeDesc format, void *result) = 0;
1634  /// A more efficient variety of `get_texels()` for cases where you can
1635  /// use a `TextureHandle*` to specify the image and optionally have a
1636  /// `Perthread*` for the calling thread.
1637  virtual bool get_texels (TextureHandle *texture_handle,
1638  Perthread *thread_info, TextureOpt &options,
1639  int miplevel, int xbegin, int xend,
1640  int ybegin, int yend, int zbegin, int zend,
1641  int chbegin, int chend,
1642  TypeDesc format, void *result) = 0;
1643 
1644  /// @}
1645 
1646  /// @{
1647  /// @name Controlling the cache
1648  ///
1649 
1650  /// Invalidate any cached information about the named file, including
1651  /// loaded texture tiles from that texture, and close any open file
1652  /// handle associated with the file. This calls
1653  /// `ImageCache::invalidate(filename,force)` on the underlying
1654  /// ImageCache.
1655  virtual void invalidate (ustring filename, bool force = true) = 0;
1656 
1657  /// Invalidate all cached data for all textures. This calls
1658  /// `ImageCache::invalidate_all(force)` on the underlying ImageCache.
1659  virtual void invalidate_all (bool force=false) = 0;
1660 
1661  /// Close any open file handles associated with a named file, but do not
1662  /// invalidate any image spec information or pixels associated with the
1663  /// files. A client might do this in order to release OS file handle
1664  /// resources, or to make it safe for other processes to modify textures
1665  /// on disk. This calls `ImageCache::close(force)` on the underlying
1666  /// ImageCache.
1667  virtual void close (ustring filename) = 0;
1668 
1669  /// `close()` all files known to the cache.
1670  virtual void close_all () = 0;
1671 
1672  /// @}
1673 
1674  /// @{
1675  /// @name Errors and statistics
1676 
1677  /// If any of the API routines returned false indicating an error,
1678  /// this routine will return the error string (and clear any error
1679  /// flags). If no error has occurred since the last time geterror()
1680  /// was called, it will return an empty string.
1681  virtual std::string geterror () const = 0;
1682 
1683  /// Returns a big string containing useful statistics about the
1684  /// TextureSystem operations, suitable for saving to a file or
1685  /// outputting to the terminal. The `level` indicates the amount of
1686  /// detail in the statistics, with higher numbers (up to a maximum of 5)
1687  /// yielding more and more esoteric information. If `icstats` is true,
1688  /// the returned string will also contain all the statistics of the
1689  /// underlying ImageCache, but if false will only contain
1690  /// texture-specific statistics.
1691  virtual std::string getstats (int level=1, bool icstats=true) const = 0;
1692 
1693  /// Reset most statistics to be as they were with a fresh TextureSystem.
1694  /// Caveat emptor: this does not flush the cache itself, so the resulting
1695  /// statistics from the next set of texture requests will not match the
1696  /// number of tile reads, etc., that would have resulted from a new
1697  /// TextureSystem.
1698  virtual void reset_stats () = 0;
1699 
1700  /// @}
1701 
1702  /// Return an opaque, non-owning pointer to the underlying ImageCache
1703  /// (if there is one).
1704  virtual ImageCache *imagecache () const = 0;
1705 
1706  virtual ~TextureSystem () { }
1707 
1708 protected:
1709  // User code should never directly construct or destruct a TextureSystem.
1710  // Always use TextureSystem::create() and TextureSystem::destroy().
1711  TextureSystem (void) { }
1712 private:
1713  // Make delete private and unimplemented in order to prevent apps
1714  // from calling it. Instead, they should call TextureSystem::destroy().
1715  void operator delete(void* /*todel*/) {}
1716 };
1717 
1718 
Use just one mipmap level.
Definition: texture.h:191
Periodic, but only for powers of 2!!!
MipMode
Definition: texture.h:91
Clamp to [0..1].
Definition: texture.h:178
GT_API const UT_StringHolder filename
float twidth
Multiplier for derivatives.
Definition: texture.h:236
RunFlagVal
Definition: texture.h:160
float tblur
Blur amount.
Definition: texture.h:235
Wrap
Definition: texture.h:66
GT_API const UT_StringHolder time
int samples
Number of samples for shadows.
Definition: texture.h:241
int subimage
Subimage or face ID.
Definition: texture.h:227
static void parse_wrapmodes(const char *wrapmodes, TextureOpt::Wrap &swrapcode, TextureOpt::Wrap &twrapcode)
Definition: texture.h:262
Force bilinear lookup within a mip level.
GLint level
Definition: glcorearb.h:107
Use two MIPmap levels w/ anisotropic.
virtual ~TextureSystem()
Definition: texture.h:1706
unsigned char Runflag
Definition: texture.h:156
VaryingRef< float > fill
Fill value for missing channels.
Definition: texture.h:384
Force closest texel.
int anisotropic
Maximum anisotropic ratio.
Definition: texture.h:233
Use two MIPmap levels (trilinear)
GLuint const GLchar * name
Definition: glcorearb.h:785
Periodic mod 1.
void close() override
static Wrap decode_wrapmode(const char *name)
Definition: texture.h:250
int subimage
Subimage or face ID.
Definition: texture.h:370
Wrap swrap
Wrap mode in the s direction.
Definition: texture.h:229
Force cubic lookup within a mip level.
Definition: texture.h:201
GLdouble GLdouble t
Definition: glew.h:1403
Clamp to [0..1].
VaryingRef< float > tblur
Blur amount.
Definition: texture.h:380
simd::VecType< int, OIIO_TEXTURE_SIMD_BATCH_WIDTH >::type IntWide
A type alias for a SIMD vector of ints with the batch width.
Definition: texture.h:125
Periodic mod 1.
Definition: texture.h:179
MipMode mipmode
Mip mode.
Definition: texture.h:374
Default high-quality lookup.
Definition: texture.h:189
OIIO_API std::string geterror()
GLsizei samples
Definition: glcorearb.h:1297
MipMode mipmode
Mip mode.
Definition: texture.h:231
bool conservative_filter
True == over-blur rather than alias.
Definition: texture.h:377
VaryingRef< float > rblur
Blur amount in the r direction.
Definition: texture.h:390
uint64_t RunMask
Definition: texture.h:132
Periodic mod 1.
Definition: texture.h:334
Mirror the image.
Definition: texture.h:335
GLuint64EXT * result
Definition: glew.h:14311
GLfloat bias
Definition: glew.h:10316
Wrap twrap
Wrap mode in the t direction.
Definition: texture.h:230
OIIO_API void parse_wrapmodes(const char *wrapmodes, Wrap &swrapcode, Wrap &twrapcode)
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
static Wrap decode_wrapmode(const char *name)
Definition: texture.h:395
Mirror the image.
Definition: texture.h:180
Periodic with shared border (env)
Definition: texture.h:337
#define OIIO_TEXTURE_SIMD_BATCH_WIDTH
Definition: texture.h:112
GLint GLuint mask
Definition: glcorearb.h:123
int firstchannel
First channel of the lookup.
Definition: texture.h:226
Just use highest-res image, no MIP mapping.
Use two MIPmap levels (trilinear)
Definition: texture.h:192
float fill
Fill value for missing channels.
Definition: texture.h:237
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
Black outside [0..1].
Definition: texture.h:177
static void parse_wrapmodes(const char *wrapmodes, TextureOptions::Wrap &swrapcode, TextureOptions::Wrap &twrapcode)
Definition: texture.h:407
Default high-quality lookup.
InterpMode interpmode
Interpolation mode.
Definition: texture.h:375
simd::VecType< float, OIIO_TEXTURE_SIMD_BATCH_WIDTH >::type FloatWide
A type alias for a SIMD vector of floats with the batch width.
Definition: texture.h:122
Mark the end – don't use this!
int firstchannel
First channel of the lookup.
Definition: texture.h:369
Force bilinear lookup within a mip level.
Definition: texture.h:200
TextureSystem(void)
Definition: texture.h:1711
int anisotropic
Maximum anisotropic ratio.
Definition: texture.h:376
ustring subimagename
Subimage name.
Definition: texture.h:228
InterpMode interpmode
Interpolation mode.
Definition: texture.h:232
float rblur
Blur amount in the r direction.
Definition: texture.h:245
Mirror the image.
float rwidth
Multiplier for derivatives in r direction.
Definition: texture.h:246
GLboolean * data
Definition: glcorearb.h:130
Default high-quality lookup.
Definition: texture.h:344
Force cubic lookup within a mip level.
Definition: texture.h:356
Wrap rwrap
Wrap mode in the r direction.
Definition: texture.h:244
VaryingRef< int > samples
Number of samples.
Definition: texture.h:386
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:107
Use two MIPmap levels (trilinear)
Definition: texture.h:347
GLuint GLfloat * val
Definition: glcorearb.h:1607
Vec3< float > V3f
Definition: ImathVec.h:693
Force bilinear lookup within a mip level.
Definition: texture.h:355
OIIO_API bool getattribute(string_view name, TypeDesc type, void *val)
Bicubic when maxifying, else bilinear.
Just use highest-res image, no MIP mapping.
Definition: texture.h:190
const float * missingcolor
Color for missing texture.
Definition: texture.h:238
Texture options for a batch of Tex::BatchWidth points and run mask.
Definition: texture.h:280
Force closest texel.
Definition: texture.h:354
InterpMode
Definition: texture.h:101
Clamp to [0..1].
Definition: texture.h:333
float bias
Bias for shadows.
Definition: texture.h:240
GLuint index
Definition: glcorearb.h:785
Wrap rwrap
Wrap mode in the r direction.
Definition: texture.h:389
static Wrap decode_wrapmode(ustring name)
Definition: texture.h:254
bool conservative_filter
True == over-blur rather than alias.
Definition: texture.h:234
Force cubic lookup within a mip level.
VaryingRef< float > twidth
Multiplier for derivatives.
Definition: texture.h:381
OIIO_API bool attribute(string_view name, TypeDesc type, const void *val)
GLfloat f
Definition: glcorearb.h:1925
Use the default found in the file.
Definition: texture.h:331
GLuint texture
Definition: glcorearb.h:414
TextureOpt()
Definition: texture.h:208
Wrap twrap
Wrap mode in the t direction.
Definition: texture.h:373
Black outside [0..1].
Definition: texture.h:332
EnvLayout
Definition: texture.h:50
Periodic, but only for powers of 2!!!
Definition: texture.h:336
VaryingRef< float > time
Time.
Definition: texture.h:382
Force closest texel.
Definition: texture.h:199
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:94
float time
Time (for time-dependent texture lookups)
Definition: texture.h:239
Use just one mipmap level.
Classes for SIMD processing.
VaryingRef< float > bias
Bias.
Definition: texture.h:383
TexFormat
Definition: texture.h:38
Black outside [0..1].
GLdouble s
Definition: glew.h:1395
VaryingRef< float > rwidth
Multiplier for derivatives in r direction.
Definition: texture.h:391
static Wrap decode_wrapmode(ustring name)
Definition: texture.h:399
ustring subimagename
Subimage name.
Definition: texture.h:298
VaryingRef< float > missingcolor
Color for missing texture.
Definition: texture.h:385
Periodic with shared border (env)
Wrap swrap
Wrap mode in the s direction.
Definition: texture.h:372
OIIO_API Wrap decode_wrapmode(const char *name)
Use the default found in the file.
Definition: texture.h:176
ustring subimagename
Subimage name.
Definition: texture.h:371
Use the default found in the file.
Use just one mipmap level.
Definition: texture.h:346
Just use highest-res image, no MIP mapping.
Definition: texture.h:345
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:93
#define OIIO_API
Definition: export.h:65
FMT_NOINLINE OutputIt fill(OutputIt it, size_t n, const fill_t< Char > &fill)
Definition: format.h:1483