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