HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
texture.h
Go to the documentation of this file.
1 /*
2  Copyright 2008 Larry Gritz and the other authors and contributors.
3  All Rights Reserved.
4 
5  Redistribution and use in source and binary forms, with or without
6  modification, are permitted provided that the following conditions are
7  met:
8  * Redistributions of source code must retain the above copyright
9  notice, this list of conditions and the following disclaimer.
10  * Redistributions in binary form must reproduce the above copyright
11  notice, this list of conditions and the following disclaimer in the
12  documentation and/or other materials provided with the distribution.
13  * Neither the name of the software's owners nor the names of its
14  contributors may be used to endorse or promote products derived from
15  this software without specific prior written permission.
16  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 
28  (This is the Modified BSD License)
29 */
30 
31 // clang-format off
32 
33 /// \file
34 /// An API for accessing filtered texture lookups via a system that
35 /// automatically manages a cache of resident texture.
36 
37 #pragma once
38 
39 #include <OpenImageIO/imageio.h>
40 #include <OpenImageIO/ustring.h>
41 #include <OpenImageIO/varyingref.h>
42 
43 #include <OpenEXR/ImathVec.h> /* because we need V3f */
44 
45 
46 // Define symbols that let client applications determine if newly added
47 // features are supported.
48 #define OIIO_TEXTURESYSTEM_SUPPORTS_CLOSE 1
49 
50 
51 
53 
54 // Forward declarations
55 
56 class ImageCache;
57 
58 
59 namespace pvt {
60 
61 class TextureSystemImpl;
62 
63 // Used internally by TextureSystem. Unfortunately, this is the only
64 // clean place to store it. Sorry, users, this isn't really for you.
65 enum TexFormat {
75 };
76 
77 enum EnvLayout {
78  LayoutTexture = 0 /* ordinary texture - no special env wrap */,
83 };
84 
85 } // namespace pvt
86 
87 
88 
89 namespace Tex {
90 
91 /// Wrap mode describes what happens when texture coordinates describe
92 /// a value outside the usual [0,1] range where a texture is defined.
93 enum class Wrap {
94  Default, ///< Use the default found in the file
95  Black, ///< Black outside [0..1]
96  Clamp, ///< Clamp to [0..1]
97  Periodic, ///< Periodic mod 1
98  Mirror, ///< Mirror the image
99  PeriodicPow2, ///< Periodic, but only for powers of 2!!!
100  PeriodicSharedBorder, ///< Periodic with shared border (env)
101  Last ///< Mark the end -- don't use this!
102 };
103 
104 /// Utility: Return the Wrap enum corresponding to a wrap name:
105 /// "default", "black", "clamp", "periodic", "mirror".
106 OIIO_API Wrap decode_wrapmode (const char *name);
108 
109 /// Utility: Parse a single wrap mode (e.g., "periodic") or a
110 /// comma-separated wrap modes string (e.g., "black,clamp") into
111 /// separate Wrap enums for s and t.
112 OIIO_API void parse_wrapmodes (const char *wrapmodes,
113  Wrap &swrapcode, Wrap &twrapcode);
114 
115 
116 /// Mip mode determines if/how we use mipmaps
117 ///
118 enum class MipMode {
119  Default, ///< Default high-quality lookup
120  NoMIP, ///< Just use highest-res image, no MIP mapping
121  OneLevel, ///< Use just one mipmap level
122  Trilinear, ///< Use two MIPmap levels (trilinear)
123  Aniso ///< Use two MIPmap levels w/ anisotropic
124 };
125 
126 /// Interp mode determines how we sample within a mipmap level
127 ///
128 enum class InterpMode {
129  Closest, ///< Force closest texel
130  Bilinear, ///< Force bilinear lookup within a mip level
131  Bicubic, ///< Force cubic lookup within a mip level
132  SmartBicubic ///< Bicubic when maxifying, else bilinear
133 };
134 
135 
136 /// Fixed width for SIMD batching texture lookups.
137 /// May be changed for experimentation or future expansion.
138 #ifndef OIIO_TEXTURE_SIMD_BATCH_WIDTH
139 # define OIIO_TEXTURE_SIMD_BATCH_WIDTH 16
140 #endif
141 
142 static constexpr int BatchWidth = OIIO_TEXTURE_SIMD_BATCH_WIDTH;
143 static constexpr int BatchAlign = BatchWidth * sizeof(float);
144 
147 typedef uint64_t RunMask;
148 
149 #if OIIO_TEXTURE_SIMD_BATCH_WIDTH == 4
150 static constexpr RunMask RunMaskOn = 0xf;
151 #elif OIIO_TEXTURE_SIMD_BATCH_WIDTH == 8
152 static constexpr RunMask RunMaskOn = 0xff;
153 #elif OIIO_TEXTURE_SIMD_BATCH_WIDTH == 16
154 static constexpr RunMask RunMaskOn = 0xffff;
155 #elif OIIO_TEXTURE_SIMD_BATCH_WIDTH == 32
156 static constexpr RunMask RunMaskOn = 0xffffffff;
157 #elif OIIO_TEXTURE_SIMD_BATCH_WIDTH == 64
158 static constexpr RunMask RunMaskOn = 0xffffffffffffffffULL;
159 #else
160 # error "Not a valid OIIO_TEXTURE_SIMD_BATCH_WIDTH choice"
161 #endif
162 
163 } // namespace Tex
164 
165 
166 /// Data type for flags that indicate on a point-by-point basis whether
167 /// we want computations to be performed.
168 typedef unsigned char Runflag;
169 
170 /// Pre-defined values for Runflag's.
171 ///
172 enum RunFlagVal { RunFlagOff = 0, RunFlagOn = 255 };
173 
174 class TextureOptions; // forward declaration
175 
176 
177 
178 /// Encapsulate all the options needed for texture lookups. Making
179 /// these options all separate parameters to the texture API routines is
180 /// very ugly and also a big pain whenever we think of new options to
181 /// add. So instead we collect all those little options into one
182 /// structure that can just be passed by reference to the texture API
183 /// routines.
185 public:
186  /// Wrap mode describes what happens when texture coordinates describe
187  /// a value outside the usual [0,1] range where a texture is defined.
188  enum Wrap {
189  WrapDefault, ///< Use the default found in the file
190  WrapBlack, ///< Black outside [0..1]
191  WrapClamp, ///< Clamp to [0..1]
192  WrapPeriodic, ///< Periodic mod 1
193  WrapMirror, ///< Mirror the image
194  WrapPeriodicPow2, ///< Periodic, but only for powers of 2!!!
195  WrapPeriodicSharedBorder, ///< Periodic with shared border (env)
196  WrapLast ///< Mark the end -- don't use this!
197  };
198 
199  /// Mip mode determines if/how we use mipmaps
200  ///
201  enum MipMode {
202  MipModeDefault, ///< Default high-quality lookup
203  MipModeNoMIP, ///< Just use highest-res image, no MIP mapping
204  MipModeOneLevel, ///< Use just one mipmap level
205  MipModeTrilinear, ///< Use two MIPmap levels (trilinear)
206  MipModeAniso ///< Use two MIPmap levels w/ anisotropic
207  };
208 
209  /// Interp mode determines how we sample within a mipmap level
210  ///
211  enum InterpMode {
212  InterpClosest, ///< Force closest texel
213  InterpBilinear, ///< Force bilinear lookup within a mip level
214  InterpBicubic, ///< Force cubic lookup within a mip level
215  InterpSmartBicubic ///< Bicubic when maxifying, else bilinear
216  };
217 
218 
219  /// Create a TextureOpt with all fields initialized to reasonable
220  /// defaults.
222  : firstchannel(0), subimage(0),
223  swrap(WrapDefault), twrap(WrapDefault),
224  mipmode(MipModeDefault), interpmode(InterpSmartBicubic),
225  anisotropic(32), conservative_filter(true),
226  sblur(0.0f), tblur(0.0f), swidth(1.0f), twidth(1.0f),
227  fill(0.0f), missingcolor(NULL),
228  // dresultds(NULL), dresultdt(NULL),
229  time(0.0f), bias(0.0f), samples(1),
230  rwrap(WrapDefault), rblur(0.0f), rwidth(1.0f), // dresultdr(NULL),
231  // actualchannels(0),
232  envlayout(0)
233  { }
234 
235  /// Convert a TextureOptions for one index into a TextureOpt.
236  ///
237  TextureOpt(const TextureOptions& opt, int index);
238 
239  int firstchannel; ///< First channel of the lookup
240  int subimage; ///< Subimage or face ID
241  ustring subimagename; ///< Subimage name
242  Wrap swrap; ///< Wrap mode in the s direction
243  Wrap twrap; ///< Wrap mode in the t direction
244  MipMode mipmode; ///< Mip mode
245  InterpMode interpmode; ///< Interpolation mode
246  int anisotropic; ///< Maximum anisotropic ratio
247  bool conservative_filter; ///< True == over-blur rather than alias
248  float sblur, tblur; ///< Blur amount
249  float swidth, twidth; ///< Multiplier for derivatives
250  float fill; ///< Fill value for missing channels
251  const float* missingcolor; ///< Color for missing texture
252  float time; ///< Time (for time-dependent texture lookups)
253  float bias; ///< Bias for shadows
254  int samples; ///< Number of samples for shadows
255 
256  // For 3D volume texture lookups only:
257  Wrap rwrap; ///< Wrap mode in the r direction
258  float rblur; ///< Blur amount in the r direction
259  float rwidth; ///< Multiplier for derivatives in r direction
260 
261  /// Utility: Return the Wrap enum corresponding to a wrap name:
262  /// "default", "black", "clamp", "periodic", "mirror".
263  static Wrap decode_wrapmode(const char* name)
264  {
265  return (Wrap)Tex::decode_wrapmode(name);
266  }
268  {
269  return (Wrap)Tex::decode_wrapmode(name);
270  }
271 
272  /// Utility: Parse a single wrap mode (e.g., "periodic") or a
273  /// comma-separated wrap modes string (e.g., "black,clamp") into
274  /// separate Wrap enums for s and t.
275  static void parse_wrapmodes(const char* wrapmodes,
276  TextureOpt::Wrap& swrapcode,
277  TextureOpt::Wrap& twrapcode)
278  {
279  Tex::parse_wrapmodes(wrapmodes, *(Tex::Wrap*)&swrapcode,
280  *(Tex::Wrap*)&twrapcode);
281  }
282 
283 private:
284  // Options set INTERNALLY by libtexture after the options are passed
285  // by the user. Users should not attempt to alter these!
286  int envlayout; // Layout for environment wrap
287  friend class pvt::TextureSystemImpl;
288 };
289 
290 
291 
292 /// Texture options for a batch of Tex::BatchWidth points and run mask.
294 public:
295  /// Create a TextureOptBatch with all fields initialized to reasonable
296  /// defaults.
297  TextureOptBatch () {} // use inline initializers
298 
299  // Options that may be different for each point we're texturing
300  alignas(Tex::BatchAlign) float sblur[Tex::BatchWidth]; ///< Blur amount
301  alignas(Tex::BatchAlign) float tblur[Tex::BatchWidth];
302  alignas(Tex::BatchAlign) float rblur[Tex::BatchWidth];
303  alignas(Tex::BatchAlign) float swidth[Tex::BatchWidth]; ///< Multiplier for derivatives
304  alignas(Tex::BatchAlign) float twidth[Tex::BatchWidth];
305  alignas(Tex::BatchAlign) float rwidth[Tex::BatchWidth];
306  // Note: rblur,rwidth only used for volumetric lookups
307 
308  // Options that must be the same for all points we're texturing at once
309  int firstchannel = 0; ///< First channel of the lookup
310  int subimage = 0; ///< Subimage or face ID
311  ustring subimagename; ///< Subimage name
312  Tex::Wrap swrap = Tex::Wrap::Default; ///< Wrap mode in the s direction
313  Tex::Wrap twrap = Tex::Wrap::Default; ///< Wrap mode in the t direction
314  Tex::Wrap rwrap = Tex::Wrap::Default; ///< Wrap mode in the r direction (volumetric)
315  Tex::MipMode mipmode = Tex::MipMode::Default; ///< Mip mode
316  Tex::InterpMode interpmode = Tex::InterpMode::SmartBicubic; ///< Interpolation mode
317  int anisotropic = 32; ///< Maximum anisotropic ratio
318  int conservative_filter = 1; ///< True: over-blur rather than alias
319  float fill = 0.0f; ///< Fill value for missing channels
320  const float *missingcolor = nullptr; ///< Color for missing texture
321 
322 private:
323  // Options set INTERNALLY by libtexture after the options are passed
324  // by the user. Users should not attempt to alter these!
325  int envlayout = 0; // Layout for environment wrap
326 
327  friend class pvt::TextureSystemImpl;
328 };
329 
330 
331 
332 /// DEPRECATED(1.8)
333 /// Encapsulate all the options needed for texture lookups. Making
334 /// these options all separate parameters to the texture API routines is
335 /// very ugly and also a big pain whenever we think of new options to
336 /// add. So instead we collect all those little options into one
337 /// structure that can just be passed by reference to the texture API
338 /// routines.
340 public:
341  /// Wrap mode describes what happens when texture coordinates describe
342  /// a value outside the usual [0,1] range where a texture is defined.
343  enum Wrap {
344  WrapDefault, ///< Use the default found in the file
345  WrapBlack, ///< Black outside [0..1]
346  WrapClamp, ///< Clamp to [0..1]
347  WrapPeriodic, ///< Periodic mod 1
348  WrapMirror, ///< Mirror the image
349  WrapPeriodicPow2, ///< Periodic, but only for powers of 2!!!
350  WrapPeriodicSharedBorder, ///< Periodic with shared border (env)
351  WrapLast ///< Mark the end -- don't use this!
352  };
353 
354  /// Mip mode determines if/how we use mipmaps
355  ///
356  enum MipMode {
357  MipModeDefault, ///< Default high-quality lookup
358  MipModeNoMIP, ///< Just use highest-res image, no MIP mapping
359  MipModeOneLevel, ///< Use just one mipmap level
360  MipModeTrilinear, ///< Use two MIPmap levels (trilinear)
361  MipModeAniso ///< Use two MIPmap levels w/ anisotropic
362  };
363 
364  /// Interp mode determines how we sample within a mipmap level
365  ///
366  enum InterpMode {
367  InterpClosest, ///< Force closest texel
368  InterpBilinear, ///< Force bilinear lookup within a mip level
369  InterpBicubic, ///< Force cubic lookup within a mip level
370  InterpSmartBicubic ///< Bicubic when maxifying, else bilinear
371  };
372 
373  /// Create a TextureOptions with all fields initialized to reasonable
374  /// defaults.
375  TextureOptions();
376 
377  /// Convert a TextureOpt for one point into a TextureOptions with
378  /// uninform values.
379  TextureOptions(const TextureOpt& opt);
380 
381  // Options that must be the same for all points we're texturing at once
382  int firstchannel; ///< First channel of the lookup
383  int subimage; ///< Subimage or face ID
384  ustring subimagename; ///< Subimage name
385  Wrap swrap; ///< Wrap mode in the s direction
386  Wrap twrap; ///< Wrap mode in the t direction
387  MipMode mipmode; ///< Mip mode
388  InterpMode interpmode; ///< Interpolation mode
389  int anisotropic; ///< Maximum anisotropic ratio
390  bool conservative_filter; ///< True == over-blur rather than alias
391 
392  // Options that may be different for each point we're texturing
393  VaryingRef<float> sblur, tblur; ///< Blur amount
394  VaryingRef<float> swidth, twidth; ///< Multiplier for derivatives
397  VaryingRef<float> fill; ///< Fill value for missing channels
398  VaryingRef<float> missingcolor; ///< Color for missing texture
399  VaryingRef<int> samples; ///< Number of samples
400 
401  // For 3D volume texture lookups only:
402  Wrap rwrap; ///< Wrap mode in the r direction
403  VaryingRef<float> rblur; ///< Blur amount in the r direction
404  VaryingRef<float> rwidth; ///< Multiplier for derivatives in r direction
405 
406  /// Utility: Return the Wrap enum corresponding to a wrap name:
407  /// "default", "black", "clamp", "periodic", "mirror".
408  static Wrap decode_wrapmode(const char* name)
409  {
410  return (Wrap)Tex::decode_wrapmode(name);
411  }
413  {
414  return (Wrap)Tex::decode_wrapmode(name);
415  }
416 
417  /// Utility: Parse a single wrap mode (e.g., "periodic") or a
418  /// comma-separated wrap modes string (e.g., "black,clamp") into
419  /// separate Wrap enums for s and t.
420  static void parse_wrapmodes(const char* wrapmodes,
421  TextureOptions::Wrap& swrapcode,
422  TextureOptions::Wrap& twrapcode)
423  {
424  Tex::parse_wrapmodes(wrapmodes, *(Tex::Wrap*)&swrapcode,
425  *(Tex::Wrap*)&twrapcode);
426  }
427 
428 private:
429  // Options set INTERNALLY by libtexture after the options are passed
430  // by the user. Users should not attempt to alter these!
431  friend class pvt::TextureSystemImpl;
432  friend class TextureOpt;
433 };
434 
435 
436 
437 
438 /// Define an API to an abstract class that that manages texture files,
439 /// caches of open file handles as well as tiles of texels so that truly
440 /// huge amounts of texture may be accessed by an application with low
441 /// memory footprint, and ways to perform antialiased texture, shadow
442 /// map, and environment map lookups.
444 public:
445  /// Create a TextureSystem and return a pointer. This should only be
446  /// freed by passing it to TextureSystem::destroy()!
447  ///
448  /// If shared==true, the TextureSystem is intended to be shared with
449  /// other like-minded owners in the same process who also ask for a
450  /// shared texture system. The shared TS also has a globally shared
451  /// ImageCache.
452  ///
453  /// If shared==false, a private texture system will be created. In that
454  /// case, the `imagecache` pointer optionally supplies an existing
455  /// ImageCache, which is owned by the caller (responsible for keeping it
456  /// alive for the lifetime of the TextureSystem, and destroying it when
457  /// no longer needed). If shared==false and imagecache==nullptr, then
458  /// a custom ImageCache will be created, owned by the TextureSystem, and
459  /// automatically freed when the TS destroys.
460  static TextureSystem *create (bool shared=true,
461  ImageCache *imagecache=nullptr);
462 
463  /// Destroy a TextureSystem that was created using
464  /// TextureSystem::create(). If teardown_imagecache parameter is true,
465  /// it will cause the underlying ImageCache to be fully destroyed even
466  /// if it's the "shared" ImageCache (use with caution)
467  static void destroy (TextureSystem *x, bool teardown_imagecache=false);
468 
469  TextureSystem (void) { }
470  virtual ~TextureSystem () { }
471 
472  /// Set an attribute controlling the texture system. Return true
473  /// if the name and type were recognized and the attrib was set.
474  /// Documented attributes:
475  /// int max_open_files : maximum number of file handles held open
476  /// float max_memory_MB : maximum tile cache size, in MB
477  /// string searchpath : colon-separated search path for texture files
478  /// string plugin_searchpath : colon-separated search path for plugins
479  /// matrix44 worldtocommon : the world-to-common transformation
480  /// matrix44 commontoworld : the common-to-world transformation
481  /// int autotile : if >0, tile size to emulate for non-tiled images
482  /// int autoscanline : autotile using full width tiles
483  /// int automip : if nonzero, emulate mipmap on the fly
484  /// int accept_untiled : if nonzero, accept untiled images
485  /// int accept_unmipped : if nonzero, accept unmipped images
486  /// int failure_retries : how many times to retry a read failure
487  /// int deduplicate : if nonzero, detect duplicate textures (default=1)
488  /// int gray_to_rgb : make 1-channel images fill RGB lookups
489  /// int max_tile_channels : max channels to store all chans in a tile
490  /// string latlong_up : default "up" direction for latlong ("y")
491  /// int flip_t : flip v coord for texture lookups?
492  /// int max_errors_per_file : Limits how many errors to issue for
493  /// issue for each (default: 100)
494  ///
495  virtual bool attribute (string_view name, TypeDesc type, const void *val) = 0;
496  // Shortcuts for common types
497  virtual bool attribute (string_view name, int val) = 0;
498  virtual bool attribute (string_view name, float val) = 0;
499  virtual bool attribute (string_view name, double val) = 0;
500  virtual bool attribute (string_view name, string_view val) = 0;
501 
502  /// Get the named attribute, store it in value.
503  virtual bool getattribute (string_view name,
504  TypeDesc type, void *val) const = 0;
505  // Shortcuts for common types
506  virtual bool getattribute(string_view name, int& val) const = 0;
507  virtual bool getattribute(string_view name, float& val) const = 0;
508  virtual bool getattribute(string_view name, double& val) const = 0;
509  virtual bool getattribute(string_view name, char** val) const = 0;
510  virtual bool getattribute(string_view name, std::string& val) const = 0;
511 
512  /// Define an opaque data type that allows us to have a pointer
513  /// to certain per-thread information that the TextureSystem maintains.
514  /// Any given one of these should NEVER be shared between running
515  /// threads.
516  class Perthread;
517 
518  /// Retrieve a Perthread, unique to the calling thread. This is a
519  /// thread-specific pointer that will always return the Perthread for a
520  /// thread, which will also be automatically destroyed when the thread
521  /// terminates.
522  ///
523  /// Applications that want to manage their own Perthread pointers (with
524  /// create_thread_info and destroy_thread_info) should still call this,
525  /// but passing in their managed pointer. If the passed-in threadinfo is
526  /// not NULL, it won't create a new one or retrieve a TSP, but it will
527  /// do other necessary housekeeping on the Perthread information.
528  virtual Perthread* get_perthread_info(Perthread* thread_info = NULL) = 0;
529 
530  /// Create a new Perthread. It is the caller's responsibility to
531  /// eventually destroy it using destroy_thread_info().
532  virtual Perthread* create_thread_info() = 0;
533 
534  /// Destroy a Perthread that was allocated by create_thread_info().
535  virtual void destroy_thread_info(Perthread* threadinfo) = 0;
536 
537  /// Define an opaque data type that allows us to have a handle to a
538  /// texture (already having its name resolved) but without exposing
539  /// any internals.
540  class TextureHandle;
541 
542  /// Retrieve an opaque handle for fast texture lookups. The opaque
543  /// pointer thread_info is thread-specific information returned by
544  /// get_perthread_info(). Return NULL if something has gone
545  /// horribly wrong.
546  virtual TextureHandle * get_texture_handle (ustring filename,
547  Perthread *thread_info=NULL) = 0;
548 
549  /// Return true if the texture handle (previously returned by
550  /// get_texture_handle()) is a valid texture that can be subsequently
551  /// read or sampled.
552  virtual bool good(TextureHandle* texture_handle) = 0;
553 
554  /// Filtered 2D texture lookup for a single point.
555  ///
556  /// s,t are the texture coordinates; dsdx, dtdx, dsdy, and dtdy are
557  /// the differentials of s and t change in some canonical directions
558  /// x and y. The choice of x and y are not important to the
559  /// implementation; it can be any imposed 2D coordinates, such as
560  /// pixels in screen space, adjacent samples in parameter space on a
561  /// surface, etc.
562  ///
563  /// The result is placed in result[0..nchannels-1]. If dresuls and
564  /// dresultdt are non-NULL, then they [0..nchannels-1] will get the
565  /// texture gradients, i.e., the rate of change per unit s and t,
566  /// respectively, of the texture.
567  ///
568  /// Return true if the file is found and could be opened by an
569  /// available ImageIO plugin, otherwise return false.
570  virtual bool texture (ustring filename, TextureOpt &options,
571  float s, float t, float dsdx, float dtdx,
572  float dsdy, float dtdy,
573  int nchannels, float *result,
574  float *dresultds=NULL, float *dresultdt=NULL) = 0;
575 
576  /// Version that takes nchannels and derivatives explicitly, if the app
577  /// already has a texture handle and per-thread info.
578  virtual bool texture (TextureHandle *texture_handle,
579  Perthread *thread_info, TextureOpt &options,
580  float s, float t, float dsdx, float dtdx,
581  float dsdy, float dtdy,
582  int nchannels, float *result,
583  float *dresultds=NULL, float *dresultdt=NULL) = 0;
584 
585  /// Retrieve filtered (possibly anisotropic) texture lookups for
586  /// an entire batch of points. The mask is a bitfield giving the
587  /// lanes to compute.
588  ///
589  /// Return true if the file is found and could be opened by an
590  /// available ImageIO plugin, otherwise return false.
591  ///
592  /// The float* inputs are each pointing to an array of float[BatchWidth]
593  /// giving one float value for each batch lane.
594  ///
595  /// The float* results act like float[nchannels][BatchWidth], so that
596  /// effectively result[0..BatchWidth-1] are the "red" result for each
597  /// lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc.
598  /// The dresultds and dresultdt should either both be provided, or else
599  /// both be nullptr (meaning no derivative results are required).
600  virtual bool texture (ustring filename, TextureOptBatch &options,
601  Tex::RunMask mask, const float *s, const float *t,
602  const float *dsdx, const float *dtdx,
603  const float *dsdy, const float *dtdy,
604  int nchannels, float *result,
605  float *dresultds=nullptr,
606  float *dresultdt=nullptr) = 0;
607  virtual bool texture (TextureHandle *texture_handle,
608  Perthread *thread_info, TextureOptBatch &options,
609  Tex::RunMask mask, const float *s, const float *t,
610  const float *dsdx, const float *dtdx,
611  const float *dsdy, const float *dtdy,
612  int nchannels, float *result,
613  float *dresultds=nullptr,
614  float *dresultdt=nullptr) = 0;
615 
616  /// Old multi-point API call.
617  /// DEPRECATED (1.8)
618  virtual bool texture (ustring filename, TextureOptions &options,
619  Runflag *runflags, int beginactive, int endactive,
623  int nchannels, float *result,
624  float *dresultds=NULL, float *dresultdt=NULL) = 0;
625  virtual bool texture (TextureHandle *texture_handle,
626  Perthread *thread_info, TextureOptions &options,
627  Runflag *runflags, int beginactive, int endactive,
631  int nchannels, float *result,
632  float *dresultds=NULL, float *dresultdt=NULL) = 0;
633 
634  /// Retrieve a 3D texture lookup at a single point.
635  ///
636  /// Return true if the file is found and could be opened by an
637  /// available ImageIO plugin, otherwise return false.
638  virtual bool texture3d (ustring filename, TextureOpt &options,
639  const Imath::V3f &P, const Imath::V3f &dPdx,
640  const Imath::V3f &dPdy, const Imath::V3f &dPdz,
641  int nchannels, float *result,
642  float *dresultds=NULL, float *dresultdt=NULL,
643  float *dresultdr=NULL) = 0;
644 
645  /// Slightly faster version of texture3d() lookup if the app already
646  /// has a texture handle and per-thread info.
647  virtual bool texture3d (TextureHandle *texture_handle,
648  Perthread *thread_info, TextureOpt &options,
649  const Imath::V3f &P, const Imath::V3f &dPdx,
650  const Imath::V3f &dPdy, const Imath::V3f &dPdz,
651  int nchannels, float *result,
652  float *dresultds=NULL, float *dresultdt=NULL,
653  float *dresultdr=NULL) = 0;
654 
655  /// Batched 3D (volumetric) texture lookup.
656  ///
657  /// The inputs P, dPdx, dPdy, dPdz are pointers to arrays that look like:
658  /// float P[3][BatchWidth], or alternately like Imath::Vec3<FloatWide>.
659  /// The mask is a bitfield giving the lanes to compute.
660  ///
661  /// The float* results act like float[nchannels][BatchWidth], so that
662  /// effectively result[0..BatchWidth-1] are the "red" result for each
663  /// lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc.
664  /// The dresultds and dresultdt should either both be provided, or else
665  /// both be nullptr (meaning no derivative results are required).
666  ///
667  /// Return true if the file is found and could be opened by an
668  /// available ImageIO plugin, otherwise return false.
669  virtual bool texture3d (ustring filename,
671  const float *P, const float *dPdx,
672  const float *dPdy, const float *dPdz,
673  int nchannels, float *result,
674  float *dresultds=nullptr, float *dresultdt=nullptr,
675  float *dresultdr=nullptr) = 0;
676  virtual bool texture3d (TextureHandle *texture_handle,
677  Perthread *thread_info,
679  const float *P, const float *dPdx,
680  const float *dPdy, const float *dPdz,
681  int nchannels, float *result,
682  float *dresultds=nullptr, float *dresultdt=nullptr,
683  float *dresultdr=nullptr) = 0;
684 
685  /// Retrieve a 3D texture lookup at many points at once.
686  /// DEPRECATED(1.8)
687  virtual bool texture3d (ustring filename, TextureOptions &options,
688  Runflag *runflags, int beginactive, int endactive,
693  int nchannels, float *result,
694  float *dresultds=NULL, float *dresultdt=NULL,
695  float *dresultdr=NULL) = 0;
696  virtual bool texture3d (TextureHandle *texture_handle,
697  Perthread *thread_info, TextureOptions &options,
698  Runflag *runflags, int beginactive, int endactive,
703  int nchannels, float *result,
704  float *dresultds=NULL, float *dresultdt=NULL,
705  float *dresultdr=NULL) = 0;
706 
707  /// Retrieve a shadow lookup for a single position P.
708  ///
709  /// Return true if the file is found and could be opened by an
710  /// available ImageIO plugin, otherwise return false.
711  virtual bool shadow (ustring filename, TextureOpt &options,
712  const Imath::V3f &P, const Imath::V3f &dPdx,
713  const Imath::V3f &dPdy, float *result,
714  float *dresultds=NULL, float *dresultdt=NULL) = 0;
715 
716  /// Slightly faster version of shadow() lookup if the app already
717  /// has a texture handle and per-thread info.
718  virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info,
719  TextureOpt &options,
720  const Imath::V3f &P, const Imath::V3f &dPdx,
721  const Imath::V3f &dPdy, float *result,
722  float *dresultds=NULL, float *dresultdt=NULL) = 0;
723 
724  /// Batched shadow lookups
725  virtual bool shadow (ustring filename,
727  const float *P, const float *dPdx, const float *dPdy,
728  float *result, float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
729  virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info,
731  const float *P, const float *dPdx, const float *dPdy,
732  float *result, float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
733 
734  /// Retrieve a shadow lookup for position P at many points at once.
735  /// DEPRECATED(1.8)
736  virtual bool shadow (ustring filename, TextureOptions &options,
737  Runflag *runflags, int beginactive, int endactive,
741  float *result,
742  float *dresultds=NULL, float *dresultdt=NULL) = 0;
743  virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info,
744  TextureOptions &options,
745  Runflag *runflags, int beginactive, int endactive,
749  float *result,
750  float *dresultds=NULL, float *dresultdt=NULL) = 0;
751 
752  /// Retrieve an environment map lookup for direction R.
753  ///
754  /// Return true if the file is found and could be opened by an
755  /// available ImageIO plugin, otherwise return false.
756  virtual bool environment (ustring filename, TextureOpt &options,
757  const Imath::V3f &R, const Imath::V3f &dRdx,
758  const Imath::V3f &dRdy, int nchannels, float *result,
759  float *dresultds=NULL, float *dresultdt=NULL) = 0;
760 
761  /// Slightly faster version of environment() lookup if the app already
762  /// has a texture handle and per-thread info.
763  virtual bool environment (TextureHandle *texture_handle,
764  Perthread *thread_info, TextureOpt &options,
765  const Imath::V3f &R, const Imath::V3f &dRdx,
766  const Imath::V3f &dRdy, int nchannels, float *result,
767  float *dresultds=NULL, float *dresultdt=NULL) = 0;
768 
769  /// Batched environment looksups.
770  ///
771  /// The inputs R, dRdx, dRdy are pointers to arrays that look like:
772  /// float R[3][BatchWidth], or alternately like Imath::Vec3<FloatWide>.
773  /// The mask is a bitfield giving the lanes to compute.
774  ///
775  /// The float* results act like float[nchannels][BatchWidth], so that
776  /// effectively result[0..BatchWidth-1] are the "red" result for each
777  /// lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc.
778  /// The dresultds and dresultdt should either both be provided, or else
779  /// both be nullptr (meaning no derivative results are required).
780  ///
781  /// Return true if the file is found and could be opened by an
782  /// available ImageIO plugin, otherwise return false.
783  virtual bool environment (ustring filename,
785  const float *R, const float *dRdx, const float *dRdy,
786  int nchannels, float *result,
787  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
788  virtual bool environment (TextureHandle *texture_handle, Perthread *thread_info,
790  const float *R, const float *dRdx, const float *dRdy,
791  int nchannels, float *result,
792  float *dresultds=nullptr, float *dresultdt=nullptr) = 0;
793 
794  /// Retrieve an environment map lookup for direction R, for many
795  /// points at once.
796  /// DEPRECATED(1.8)
797  virtual bool environment (ustring filename, TextureOptions &options,
798  Runflag *runflags, int beginactive, int endactive,
802  int nchannels, float *result,
803  float *dresultds=NULL, float *dresultdt=NULL) = 0;
804  virtual bool environment (TextureHandle *texture_handle,
805  Perthread *thread_info, TextureOptions &options,
806  Runflag *runflags, int beginactive, int endactive,
810  int nchannels, float *result,
811  float *dresultds=NULL, float *dresultdt=NULL) = 0;
812 
813  /// Given possibly-relative 'filename', resolve it using the search
814  /// path rules and return the full resolved filename.
815  virtual std::string resolve_filename (const std::string &filename) const=0;
816 
817  /// Get information about the given texture. Return true if found
818  /// and the data has been put in *data. Return false if the texture
819  /// doesn't exist, doesn't have the requested data, if the data
820  /// doesn't match the type requested. or some other failure.
821  virtual bool get_texture_info (ustring filename, int subimage,
822  ustring dataname, TypeDesc datatype, void *data) = 0;
823  virtual bool get_texture_info (TextureHandle *texture_handle,
824  Perthread *thread_info, int subimage,
825  ustring dataname, TypeDesc datatype, void *data) = 0;
826 
827  /// Get the ImageSpec associated with the named texture
828  /// (specifically, the first MIP-map level). If the file is found
829  /// and is an image format that can be read, store a copy of its
830  /// specification in spec and return true. Return false if the file
831  /// was not found or could not be opened as an image file by any
832  /// available ImageIO plugin.
833  virtual bool get_imagespec (ustring filename, int subimage,
834  ImageSpec &spec) = 0;
835  virtual bool get_imagespec (TextureHandle *texture_handle,
836  Perthread *thread_info, int subimage,
837  ImageSpec &spec) = 0;
838 
839  /// Return a pointer to an ImageSpec associated with the named
840  /// texture (specifically, the first MIP-map level) if the file is
841  /// found and is an image format that can be read, otherwise return
842  /// NULL.
843  ///
844  /// This method is much more efficient than get_imagespec(), since
845  /// it just returns a pointer to the spec held internally by the
846  /// underlying ImageCache (rather than copying the spec to the
847  /// user's memory). However, the caller must beware that the
848  /// pointer is only valid as long as nobody (even other threads)
849  /// calls invalidate() on the file, or invalidate_all(), or destroys
850  /// the TextureSystem.
851  virtual const ImageSpec *imagespec (ustring filename, int subimage=0) = 0;
852  virtual const ImageSpec *imagespec (TextureHandle *texture_handle,
853  Perthread *thread_info = NULL,
854  int subimage=0) = 0;
855 
856  /// Retrieve the rectangle of raw unfiltered texels spanning
857  /// [xbegin..xend) X [ybegin..yend) X [zbegin..zend), with
858  /// "exclusive end" a la STL, specified as integer pixel coordinates
859  /// in the designated MIP-map level, storing the texel values
860  /// beginning at the address specified by result.
861  /// The texel values will be converted to the type specified by
862  /// format. It is up to the caller to ensure that result points to
863  /// an area of memory big enough to accommodate the requested
864  /// rectangle (taking into consideration its dimensions, number of
865  /// channels, and data format). Requested pixels outside
866  /// the valid pixel data region will be filled in with 0 values.
867  ///
868  /// Return true if the file is found and could be opened by an
869  /// available ImageIO plugin, otherwise return false.
870  virtual bool get_texels (ustring filename, TextureOpt &options,
871  int miplevel, int xbegin, int xend,
872  int ybegin, int yend, int zbegin, int zend,
873  int chbegin, int chend,
874  TypeDesc format, void *result) = 0;
875  virtual bool get_texels (TextureHandle *texture_handle,
876  Perthread *thread_info, TextureOpt &options,
877  int miplevel, int xbegin, int xend,
878  int ybegin, int yend, int zbegin, int zend,
879  int chbegin, int chend,
880  TypeDesc format, void *result) = 0;
881 
882  /// If any of the API routines returned false indicating an error,
883  /// this routine will return the error string (and clear any error
884  /// flags). If no error has occurred since the last time geterror()
885  /// was called, it will return an empty string.
886  virtual std::string geterror () const = 0;
887 
888  /// Return the statistics output as a huge string.
889  ///
890  virtual std::string getstats (int level=1, bool icstats=true) const = 0;
891 
892  /// Invalidate any cached information about the named file. A client
893  /// might do this if, for example, they are aware that an image
894  /// being held in the cache has been updated on disk.
895  virtual void invalidate (ustring filename) = 0;
896 
897  /// Invalidate all cached data for all textures. If force is true,
898  /// everything will be invalidated, no matter how wasteful it is,
899  /// but if force is false, in actuality files will only be
900  /// invalidated if their modification times have been changed since
901  /// they were first opened.
902  virtual void invalidate_all (bool force=false) = 0;
903 
904  /// Reset most statistics to be as they were with a fresh
905  /// TextureSystem. Caveat emptor: this does not flush the cache
906  /// itelf, so the resulting statistics from the next set of texture
907  /// requests will not match the number of tile reads, etc., that
908  /// would have resulted from a new TextureSystem.
909  virtual void reset_stats () = 0;
910 
911  /// Close any open file handles associated with a named file, or for all
912  /// files, but do not invalidate any image spec information or pixels
913  /// associated with the files. A client might do this in order to
914  /// release OS file handle resources, or to make it safe for other
915  /// processes to modify cached files.
916  virtual void close (ustring filename) = 0;
917  virtual void close_all () = 0;
918 
919  /// Return an opaque, non-owning pointer to the underlying ImageCache
920  /// (if there is one).
921  virtual ImageCache *imagecache () const = 0;
922 
923 private:
924  // Make delete private and unimplemented in order to prevent apps
925  // from calling it. Instead, they should call TextureSystem::destroy().
926  void operator delete(void* /*todel*/) {}
927 };
928 
929 
Use just one mipmap level.
Definition: texture.h:204
GLdouble s
Definition: glew.h:1390
Periodic, but only for powers of 2!!!
MipMode
Definition: texture.h:118
Clamp to [0..1].
Definition: texture.h:191
GT_API const UT_StringHolder filename
float twidth
Multiplier for derivatives.
Definition: texture.h:249
GLuint const GLchar * name
Definition: glew.h:1814
RunFlagVal
Definition: texture.h:172
float tblur
Blur amount.
Definition: texture.h:248
Wrap
Definition: texture.h:93
GT_API const UT_StringHolder time
int samples
Number of samples for shadows.
Definition: texture.h:254
GLuint index
Definition: glew.h:1814
int subimage
Subimage or face ID.
Definition: texture.h:240
static void parse_wrapmodes(const char *wrapmodes, TextureOpt::Wrap &swrapcode, TextureOpt::Wrap &twrapcode)
Definition: texture.h:275
ImageBuf OIIO_API fill(cspan< float > values, ROI roi, int nthreads=0)
GLuint const GLfloat * val
Definition: glew.h:2794
Force bilinear lookup within a mip level.
Use two MIPmap levels w/ anisotropic.
virtual ~TextureSystem()
Definition: texture.h:470
unsigned char Runflag
Definition: texture.h:168
GLint GLint GLsizei GLsizei GLsizei GLint GLenum format
Definition: glew.h:1254
VaryingRef< float > fill
Fill value for missing channels.
Definition: texture.h:397
Force closest texel.
int anisotropic
Maximum anisotropic ratio.
Definition: texture.h:246
Use two MIPmap levels (trilinear)
Periodic mod 1.
GLenum GLint GLuint mask
Definition: glew.h:1845
void close() override
static Wrap decode_wrapmode(const char *name)
Definition: texture.h:263
int subimage
Subimage or face ID.
Definition: texture.h:383
Wrap swrap
Wrap mode in the s direction.
Definition: texture.h:242
Force cubic lookup within a mip level.
Definition: texture.h:214
Clamp to [0..1].
VaryingRef< float > tblur
Blur amount.
Definition: texture.h:393
simd::VecType< int, OIIO_TEXTURE_SIMD_BATCH_WIDTH >::type IntWide
Definition: texture.h:146
Periodic mod 1.
Definition: texture.h:192
MipMode mipmode
Mip mode.
Definition: texture.h:387
Default high-quality lookup.
Definition: texture.h:202
OIIO_API std::string geterror()
MipMode mipmode
Mip mode.
Definition: texture.h:244
bool conservative_filter
True == over-blur rather than alias.
Definition: texture.h:390
VaryingRef< float > rblur
Blur amount in the r direction.
Definition: texture.h:403
uint64_t RunMask
Definition: texture.h:147
Periodic mod 1.
Definition: texture.h:347
Mirror the image.
Definition: texture.h:348
Wrap twrap
Wrap mode in the t direction.
Definition: texture.h:243
OIIO_API void parse_wrapmodes(const char *wrapmodes, Wrap &swrapcode, Wrap &twrapcode)
static Wrap decode_wrapmode(const char *name)
Definition: texture.h:408
Mirror the image.
Definition: texture.h:193
Periodic with shared border (env)
Definition: texture.h:350
GLclampf f
Definition: glew.h:3499
GLint GLint GLint GLint GLint x
Definition: glew.h:1252
#define OIIO_TEXTURE_SIMD_BATCH_WIDTH
Definition: texture.h:139
GLint GLenum GLsizei GLint GLsizei const void * data
Definition: glew.h:1379
int firstchannel
First channel of the lookup.
Definition: texture.h:239
Just use highest-res image, no MIP mapping.
Use two MIPmap levels (trilinear)
Definition: texture.h:205
float fill
Fill value for missing channels.
Definition: texture.h:250
Black outside [0..1].
Definition: texture.h:190
static void parse_wrapmodes(const char *wrapmodes, TextureOptions::Wrap &swrapcode, TextureOptions::Wrap &twrapcode)
Definition: texture.h:420
Default high-quality lookup.
InterpMode interpmode
Interpolation mode.
Definition: texture.h:388
simd::VecType< float, OIIO_TEXTURE_SIMD_BATCH_WIDTH >::type FloatWide
Definition: texture.h:145
Mark the end – don't use this!
Periodic, but only for powers of 2!!!
Definition: texture.h:194
int firstchannel
First channel of the lookup.
Definition: texture.h:382
GLfloat bias
Definition: glew.h:10274
Force bilinear lookup within a mip level.
Definition: texture.h:213
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
TextureSystem(void)
Definition: texture.h:469
int anisotropic
Maximum anisotropic ratio.
Definition: texture.h:389
ustring subimagename
Subimage name.
Definition: texture.h:241
InterpMode interpmode
Interpolation mode.
Definition: texture.h:245
float rblur
Blur amount in the r direction.
Definition: texture.h:258
Mirror the image.
float rwidth
Multiplier for derivatives in r direction.
Definition: texture.h:259
Default high-quality lookup.
Definition: texture.h:357
Force cubic lookup within a mip level.
Definition: texture.h:369
Wrap rwrap
Wrap mode in the r direction.
Definition: texture.h:257
VaryingRef< int > samples
Number of samples.
Definition: texture.h:399
Use two MIPmap levels (trilinear)
Definition: texture.h:360
Vec3< float > V3f
Definition: ImathVec.h:693
GLsizei const GLchar *const * string
Definition: glew.h:1844
Force bilinear lookup within a mip level.
Definition: texture.h:368
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:203
const float * missingcolor
Color for missing texture.
Definition: texture.h:251
Texture options for a batch of Tex::BatchWidth points and run mask.
Definition: texture.h:293
Force closest texel.
Definition: texture.h:367
InterpMode
Definition: texture.h:128
Clamp to [0..1].
Definition: texture.h:346
float bias
Bias for shadows.
Definition: texture.h:253
GLenum GLuint texture
Definition: glew.h:2361
Wrap rwrap
Wrap mode in the r direction.
Definition: texture.h:402
static Wrap decode_wrapmode(ustring name)
Definition: texture.h:267
bool conservative_filter
True == over-blur rather than alias.
Definition: texture.h:247
Force cubic lookup within a mip level.
VaryingRef< float > twidth
Multiplier for derivatives.
Definition: texture.h:394
OIIO_API bool attribute(string_view name, TypeDesc type, const void *val)
Use the default found in the file.
Definition: texture.h:344
GLuint64EXT * result
Definition: glew.h:14007
TextureOpt()
Definition: texture.h:221
Wrap twrap
Wrap mode in the t direction.
Definition: texture.h:386
Black outside [0..1].
Definition: texture.h:345
EnvLayout
Definition: texture.h:77
Periodic, but only for powers of 2!!!
Definition: texture.h:349
VaryingRef< float > time
Time.
Definition: texture.h:395
Force closest texel.
Definition: texture.h:212
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:66
float time
Time (for time-dependent texture lookups)
Definition: texture.h:252
GLsizei samples
Definition: glew.h:2998
Use just one mipmap level.
VaryingRef< float > bias
Bias.
Definition: texture.h:396
TexFormat
Definition: texture.h:65
Black outside [0..1].
Periodic with shared border (env)
Definition: texture.h:195
VaryingRef< float > rwidth
Multiplier for derivatives in r direction.
Definition: texture.h:404
static Wrap decode_wrapmode(ustring name)
Definition: texture.h:412
GLint level
Definition: glew.h:1252
GLdouble GLdouble t
Definition: glew.h:1398
ustring subimagename
Subimage name.
Definition: texture.h:311
VaryingRef< float > missingcolor
Color for missing texture.
Definition: texture.h:398
Periodic with shared border (env)
Wrap swrap
Wrap mode in the s direction.
Definition: texture.h:385
OIIO_API Wrap decode_wrapmode(const char *name)
Use the default found in the file.
Definition: texture.h:189
ustring subimagename
Subimage name.
Definition: texture.h:384
Use the default found in the file.
Use just one mipmap level.
Definition: texture.h:359
Just use highest-res image, no MIP mapping.
Definition: texture.h:358
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:65
#define OIIO_API
Definition: export.h:91