HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TextureSystem Class Referenceabstract

#include <texture.h>

Public Member Functions

virtual ImageCacheimagecache () const =0
 
virtual ~TextureSystem ()
 
Setting options and limits for the texture system

These are the list of attributes that can bet set or queried by attribute/getattribute:

All attributes ordinarily recognized by ImageCache are accepted and passed through to the underlying ImageCache. These include:

  • int max_open_files : Maximum number of file handles held open.
  • float max_memory_MB : Maximum tile cache size, in MB.
  • string searchpath : Colon-separated search path for texture files.
  • string plugin_searchpath : Colon-separated search path for plugins.
  • int autotile : If >0, tile size to emulate for non-tiled images.
  • int autoscanline : If nonzero, autotile using full width tiles.
  • int automip : If nonzero, emulate mipmap on the fly.
  • int accept_untiled : If nonzero, accept untiled images.
  • int accept_unmipped : If nonzero, accept unmipped images.
  • int failure_retries : How many times to retry a read failure.
  • int deduplicate : If nonzero, detect duplicate textures (default=1).
  • string substitute_image : If supplied, an image to substatute for all texture references.
  • int max_errors_per_file : Limits how many errors to issue for each file. (default: 100)

Texture-specific settings:

  • matrix44 worldtocommon / matrix44 commontoworld : The 4x4 matrices that provide the spatial transformation from "world" to a "common" coordinate system and back. This is mainly used for shadow map lookups, in which the shadow map itself encodes the world coordinate system, but positions passed to shadow() are expressed in "common" coordinates. You do not need to set commontoworld and worldtocommon separately; just setting either one will implicitly set the other, since each is the inverse of the other.
  • int gray_to_rgb : If set to nonzero, texture lookups of single-channel (grayscale) images will replicate the sole channel's values into the next two channels, making it behave like an RGB image that happens to have all three channels with identical pixel values. (Channels beyond the third will get the "fill" value.) The default value of zero means that all missing channels will get the "fill" color.
  • int max_tile_channels : The maximum number of color channels in a texture file for which all channels will be loaded as a single cached tile. Files with more than this number of color channels will have only the requested subset loaded, in order to save cache space (but at the possible wasted expense of separate tiles that overlap their channel ranges). The default is 5.
  • int max_mip_res : NEW 2.1 Sets the maximum MIP-map resolution for filtered texture lookups. The MIP levels used will be clamped to those having fewer than this number of pixels in each dimension. This can be helpful as a way to limit disk I/O when doing fast preview renders (with the tradeoff that you may see some texture more blurry than they would ideally be). The default is 1 << 30, a value so large that no such clamping will be performed.
  • string latlong_up : The default "up" direction for latlong environment maps (only applies if the map itself doesn't specify a format or is in a format that explicitly requires a particular orientation). The default is "y". (Currently any other value will result in z being "up.")
  • int flip_t : If nonzero, t coordinates will be flipped 1-t for all texture lookups. The default is 0.
  • string options This catch-all is simply a comma-separated list of name=value settings of named options, which will be parsed and individually set.

    ic->attribute ("options", "max_memory_MB=512.0,autotile=1");
    

    Note that if an option takes a string value that must itself contain a comma, it is permissible to enclose the value in either single \' or double " quotes.

Read-only attributes

Additionally, there are some read-only attributes that can be queried with getattribute() even though they cannot be set via attribute():

The following member functions of TextureSystem allow you to set (and in some cases retrieve) options that control the overall behavior of the texture system:

virtual bool attribute (string_view name, TypeDesc type, const void *val)=0
 
virtual bool attribute (string_view name, int val)=0
 Specialized attribute() for setting a single int value. More...
 
virtual bool attribute (string_view name, float val)=0
 Specialized attribute() for setting a single float value. More...
 
virtual bool attribute (string_view name, double val)=0
 
virtual bool attribute (string_view name, string_view val)=0
 Specialized attribute() for setting a single string value. More...
 
virtual bool getattribute (string_view name, TypeDesc type, void *val) const =0
 
virtual bool getattribute (string_view name, int &val) const =0
 Specialized attribute() for retrieving a single int value. More...
 
virtual bool getattribute (string_view name, float &val) const =0
 Specialized attribute() for retrieving a single float value. More...
 
virtual bool getattribute (string_view name, double &val) const =0
 
virtual bool getattribute (string_view name, char **val) const =0
 
virtual bool getattribute (string_view name, std::string &val) const =0
 
Opaque data for performance lookups

The TextureSystem implementation needs to maintain certain per-thread state, and some methods take an opaque Perthread pointer to this record. There are three options for how to deal with it:

  1. Don't worry about it at all: don't use the methods that want Perthread pointers, or always pass nullptr for any `Perthread*1 arguments, and ImageCache will do thread-specific-pointer retrieval as necessary (though at some small cost).
  2. If your app already stores per-thread information of its own, you may call get_perthread_info(nullptr) to retrieve it for that thread, and then pass it into the functions that allow it (thus sparing them the need and expense of retrieving the thread-specific pointer). However, it is crucial that this pointer not be shared between multiple threads. In this case, the ImageCache manages the storage, which will automatically be released when the thread terminates.
  3. If your app also wants to manage the storage of the Perthread, it can explicitly create one with create_perthread_info(), pass it around, and eventually be responsible for destroying it with destroy_perthread_info(). When managing the storage, the app may reuse the Perthread for another thread after the first is terminated, but still may not use the same Perthread for two threads running concurrently.
virtual Perthread * get_perthread_info (Perthread *thread_info=nullptr)=0
 
virtual Perthread * create_thread_info ()=0
 
virtual void destroy_thread_info (Perthread *threadinfo)=0
 Destroy a Perthread that was allocated by create_thread_info(). More...
 
virtual TextureHandle * get_texture_handle (ustring filename, Perthread *thread_info=nullptr)=0
 
virtual bool good (TextureHandle *texture_handle)=0
 
Texture lookups
virtual bool texture (ustring filename, TextureOpt &options, float s, float t, float dsdx, float dtdx, float dsdy, float dtdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool texture (TextureHandle *texture_handle, Perthread *thread_info, TextureOpt &options, float s, float t, float dsdx, float dtdx, float dsdy, float dtdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool texture3d (ustring filename, TextureOpt &options, const Imath::V3f &P, const Imath::V3f &dPdx, const Imath::V3f &dPdy, const Imath::V3f &dPdz, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr, float *dresultdr=nullptr)=0
 
virtual bool texture3d (TextureHandle *texture_handle, Perthread *thread_info, TextureOpt &options, const Imath::V3f &P, const Imath::V3f &dPdx, const Imath::V3f &dPdy, const Imath::V3f &dPdz, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr, float *dresultdr=nullptr)=0
 
virtual bool shadow (ustring filename, TextureOpt &options, const Imath::V3f &P, const Imath::V3f &dPdx, const Imath::V3f &dPdy, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info, TextureOpt &options, const Imath::V3f &P, const Imath::V3f &dPdx, const Imath::V3f &dPdy, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool environment (ustring filename, TextureOpt &options, const Imath::V3f &R, const Imath::V3f &dRdx, const Imath::V3f &dRdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool environment (TextureHandle *texture_handle, Perthread *thread_info, TextureOpt &options, const Imath::V3f &R, const Imath::V3f &dRdx, const Imath::V3f &dRdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
Batched texture lookups
virtual bool texture (ustring filename, TextureOptBatch &options, Tex::RunMask mask, const float *s, const float *t, const float *dsdx, const float *dtdx, const float *dsdy, const float *dtdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool texture (TextureHandle *texture_handle, Perthread *thread_info, TextureOptBatch &options, Tex::RunMask mask, const float *s, const float *t, const float *dsdx, const float *dtdx, const float *dsdy, const float *dtdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool texture (ustring filename, TextureOptions &options, Runflag *runflags, int beginactive, int endactive, VaryingRef< float > s, VaryingRef< float > t, VaryingRef< float > dsdx, VaryingRef< float > dtdx, VaryingRef< float > dsdy, VaryingRef< float > dtdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool texture (TextureHandle *texture_handle, Perthread *thread_info, TextureOptions &options, Runflag *runflags, int beginactive, int endactive, VaryingRef< float > s, VaryingRef< float > t, VaryingRef< float > dsdx, VaryingRef< float > dtdx, VaryingRef< float > dsdy, VaryingRef< float > dtdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool texture3d (ustring filename, TextureOptBatch &options, Tex::RunMask mask, const float *P, const float *dPdx, const float *dPdy, const float *dPdz, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr, float *dresultdr=nullptr)=0
 
virtual bool texture3d (TextureHandle *texture_handle, Perthread *thread_info, TextureOptBatch &options, Tex::RunMask mask, const float *P, const float *dPdx, const float *dPdy, const float *dPdz, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr, float *dresultdr=nullptr)=0
 
virtual bool texture3d (ustring filename, TextureOptions &options, Runflag *runflags, int beginactive, int endactive, VaryingRef< Imath::V3f > P, VaryingRef< Imath::V3f > dPdx, VaryingRef< Imath::V3f > dPdy, VaryingRef< Imath::V3f > dPdz, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr, float *dresultdr=nullptr)=0
 
virtual bool texture3d (TextureHandle *texture_handle, Perthread *thread_info, TextureOptions &options, Runflag *runflags, int beginactive, int endactive, VaryingRef< Imath::V3f > P, VaryingRef< Imath::V3f > dPdx, VaryingRef< Imath::V3f > dPdy, VaryingRef< Imath::V3f > dPdz, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr, float *dresultdr=nullptr)=0
 
virtual bool environment (ustring filename, TextureOptBatch &options, Tex::RunMask mask, const float *R, const float *dRdx, const float *dRdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool environment (TextureHandle *texture_handle, Perthread *thread_info, TextureOptBatch &options, Tex::RunMask mask, const float *R, const float *dRdx, const float *dRdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool environment (ustring filename, TextureOptions &options, Runflag *runflags, int beginactive, int endactive, VaryingRef< Imath::V3f > R, VaryingRef< Imath::V3f > dRdx, VaryingRef< Imath::V3f > dRdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool environment (TextureHandle *texture_handle, Perthread *thread_info, TextureOptions &options, Runflag *runflags, int beginactive, int endactive, VaryingRef< Imath::V3f > R, VaryingRef< Imath::V3f > dRdx, VaryingRef< Imath::V3f > dRdy, int nchannels, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool shadow (ustring filename, TextureOptBatch &options, Tex::RunMask mask, const float *P, const float *dPdx, const float *dPdy, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info, TextureOptBatch &options, Tex::RunMask mask, const float *P, const float *dPdx, const float *dPdy, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool shadow (ustring filename, TextureOptions &options, Runflag *runflags, int beginactive, int endactive, VaryingRef< Imath::V3f > P, VaryingRef< Imath::V3f > dPdx, VaryingRef< Imath::V3f > dPdy, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
virtual bool shadow (TextureHandle *texture_handle, Perthread *thread_info, TextureOptions &options, Runflag *runflags, int beginactive, int endactive, VaryingRef< Imath::V3f > P, VaryingRef< Imath::V3f > dPdx, VaryingRef< Imath::V3f > dPdy, float *result, float *dresultds=nullptr, float *dresultdt=nullptr)=0
 
Texture metadata and raw texels
virtual std::string resolve_filename (const std::string &filename) const =0
 
virtual bool get_texture_info (ustring filename, int subimage, ustring dataname, TypeDesc datatype, void *data)=0
 
virtual bool get_texture_info (TextureHandle *texture_handle, Perthread *thread_info, int subimage, ustring dataname, TypeDesc datatype, void *data)=0
 
virtual bool get_imagespec (ustring filename, int subimage, ImageSpec &spec)=0
 
virtual bool get_imagespec (TextureHandle *texture_handle, Perthread *thread_info, int subimage, ImageSpec &spec)=0
 
virtual const ImageSpecimagespec (ustring filename, int subimage=0)=0
 
virtual const ImageSpecimagespec (TextureHandle *texture_handle, Perthread *thread_info=nullptr, int subimage=0)=0
 
virtual bool get_texels (ustring filename, TextureOpt &options, int miplevel, int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, TypeDesc format, void *result)=0
 
virtual bool get_texels (TextureHandle *texture_handle, Perthread *thread_info, TextureOpt &options, int miplevel, int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, TypeDesc format, void *result)=0
 
Controlling the cache
virtual void invalidate (ustring filename, bool force=true)=0
 
virtual void invalidate_all (bool force=false)=0
 
virtual void close (ustring filename)=0
 
virtual void close_all ()=0
 close() all files known to the cache. More...
 
Errors and statistics
virtual std::string geterror () const =0
 
virtual std::string getstats (int level=1, bool icstats=true) const =0
 
virtual void reset_stats ()=0
 

Static Public Member Functions

Creating and destroying a texture system

TextureSystem is an abstract API described as a pure virtual class. The actual internal implementation is not exposed through the external API of OpenImageIO. Because of this, you cannot construct or destroy the concrete implementation, so two static methods of TextureSystem are provided:

static TextureSystemcreate (bool shared=true, ImageCache *imagecache=nullptr)
 
static void destroy (TextureSystem *ts, bool teardown_imagecache=false)
 

Protected Member Functions

 TextureSystem (void)
 

Detailed Description

Define an API to an abstract class that that manages texture files, caches of open file handles as well as tiles of texels so that truly huge amounts of texture may be accessed by an application with low memory footprint, and ways to perform antialiased texture, shadow map, and environment map lookups.

Definition at line 430 of file texture.h.

Constructor & Destructor Documentation

virtual TextureSystem::~TextureSystem ( )
inlinevirtual

Definition at line 1706 of file texture.h.

TextureSystem::TextureSystem ( void  )
inlineprotected

Definition at line 1711 of file texture.h.

Member Function Documentation

virtual bool TextureSystem::attribute ( string_view  name,
TypeDesc  type,
const void val 
)
pure virtual

Set a named attribute (i.e., a property or option) of the TextureSystem.

Example:

TextureSystem *ts;
...
int maxfiles = 50;
ts->attribute ("max_open_files", TypeDesc::INT, &maxfiles);

const char *path = "/my/path";
ts->attribute ("searchpath", TypeDesc::STRING, &path);

// There are specialized versions for retrieving a single int,
// float, or string without needing types or pointers:
ts->getattribute ("max_open_files", 50);
ic->attribute ("max_memory_MB", 4000.0f);
ic->attribute ("searchpath", "/my/path");

Note: When passing a string, you need to pass a pointer to the char*, not a pointer to the first character. (Rationale: for an int attribute, you pass the address of the int. So for a string, which is a char*, you need to pass the address of the string, i.e., a char**).

Parameters
nameName of the attribute to set.
typeTypeDesc describing the type of the attribute.
valPointer to the value data.
Returns
true if the name and type were recognized and the attribute was set, or false upon failure (including it being an unrecognized attribute or not of the correct type).
virtual bool TextureSystem::attribute ( string_view  name,
int  val 
)
pure virtual

Specialized attribute() for setting a single int value.

virtual bool TextureSystem::attribute ( string_view  name,
float  val 
)
pure virtual

Specialized attribute() for setting a single float value.

virtual bool TextureSystem::attribute ( string_view  name,
double  val 
)
pure virtual

Set a named attribute (i.e., a property or option) of the TextureSystem.

Example:

TextureSystem *ts;
...
int maxfiles = 50;
ts->attribute ("max_open_files", TypeDesc::INT, &maxfiles);

const char *path = "/my/path";
ts->attribute ("searchpath", TypeDesc::STRING, &path);

// There are specialized versions for retrieving a single int,
// float, or string without needing types or pointers:
ts->getattribute ("max_open_files", 50);
ic->attribute ("max_memory_MB", 4000.0f);
ic->attribute ("searchpath", "/my/path");

Note: When passing a string, you need to pass a pointer to the char*, not a pointer to the first character. (Rationale: for an int attribute, you pass the address of the int. So for a string, which is a char*, you need to pass the address of the string, i.e., a char**).

Parameters
nameName of the attribute to set.
typeTypeDesc describing the type of the attribute.
valPointer to the value data.
Returns
true if the name and type were recognized and the attribute was set, or false upon failure (including it being an unrecognized attribute or not of the correct type).
virtual bool TextureSystem::attribute ( string_view  name,
string_view  val 
)
pure virtual

Specialized attribute() for setting a single string value.

virtual void TextureSystem::close ( ustring  filename)
pure virtual

Close any open file handles associated with a named file, but do not invalidate any image spec information or pixels associated with the files. A client might do this in order to release OS file handle resources, or to make it safe for other processes to modify textures on disk. This calls ImageCache::close(force) on the underlying ImageCache.

virtual void TextureSystem::close_all ( )
pure virtual

close() all files known to the cache.

static TextureSystem* TextureSystem::create ( bool  shared = true,
ImageCache imagecache = nullptr 
)
static

Create a TextureSystem and return a pointer to it. This should only be freed by passing it to TextureSystem::destroy()!

Parameters
sharedIf shared is true, the pointer returned will be a shared TextureSystem, (so that multiple parts of an application that request a TextureSystem will all end up with the same one, and the same underlying ImageCache). If shared is false, a completely unique TextureCache will be created and returned.
imagecacheIf shared is false and imagecache is not nullptr, the TextureSystem will use this as its underlying ImageCache. In that case, it is the caller who is responsible for eventually freeing the ImageCache after the TextureSystem is destroyed. If shared is false and imagecache is nullptr, then a custom ImageCache will be created, owned by the TextureSystem, and automatically freed when the TS destroys.
Returns
A raw pointer to a TextureSystem, which can only be freed with TextureSystem::destroy().
See Also
TextureSystem::destroy
virtual Perthread* TextureSystem::create_thread_info ( )
pure virtual

Create a new Perthread. It is the caller's responsibility to eventually destroy it using destroy_thread_info().

static void TextureSystem::destroy ( TextureSystem ts,
bool  teardown_imagecache = false 
)
static

Destroy an allocated TextureSystem, including freeing all system resources that it holds.

It is safe to destroy even a shared TextureSystem, as the implementation of destroy() will recognize a shared one and only truly release its resources if it has been requested to be destroyed as many times as shared TextureSystem's were created.

Parameters
tsRaw pointer to the TextureSystem to destroy.
teardown_imagecacheFor a shared TextureSystem, if the teardown_imagecache parameter is true, it will try to truly destroy the shared cache if nobody else is still holding a reference (otherwise, it will leave it intact). This parameter has no effect if ts was not the single globally shared TextureSystem.
virtual void TextureSystem::destroy_thread_info ( Perthread *  threadinfo)
pure virtual

Destroy a Perthread that was allocated by create_thread_info().

virtual bool TextureSystem::environment ( ustring  filename,
TextureOpt options,
const Imath::V3f R,
const Imath::V3f dRdx,
const Imath::V3f dRdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform a filtered directional environment map lookup in the direction of vector R, from the texture identified by filename, and using relevant texture options. The filtered results will be stored in result[].

Parameters
filenameThe name of the texture.
optionsFields within options that are honored for environment lookups include the following:
  • int firstchannel : The index of the first channel to look up from the texture.
  • int subimage / ustring subimagename : The subimage or face within the file, specified by either by name (if non-empty) or index. This will be ignored if the file does not have multiple subimages or separate per-face textures.
  • float swidth, twidth : For each direction, gives a multiplier for the derivatives.
  • float sblur, tblur : For each direction, specifies an additional amount of pre-blur to apply to the texture (after derivatives are taken into account), expressed as a portion of the width of the texture.
  • float fill : Specifies the value that will be used for any color channels that are requested but not found in the file. For example, if you perform a 4-channel lookup on a 3-channel texture, the last channel will get the fill value. (Note: this behavior is affected by the "gray_to_rgb" TextureSystem attribute.
  • const float *missingcolor : If not nullptr, specifies the color that will be returned for missing or broken textures (rather than being an error).
RThe direction vector to look up.
dRdx/dRdyThe differentials of R with respect to image coordinates x and y.
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed into result[0..nchannels-1].
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, i.e., the rate of change per unit s and t, respectively, of the filtered texture. If supplied, they must allow for nchannels of storage.
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::environment ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOpt options,
const Imath::V3f R,
const Imath::V3f dRdx,
const Imath::V3f dRdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Slightly faster version of environment() if the app already has a texture handle and per-thread info.

virtual bool TextureSystem::environment ( ustring  filename,
TextureOptBatch options,
Tex::RunMask  mask,
const float *  R,
const float *  dRdx,
const float *  dRdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered directional environment map lookups on a batch of directions from the same texture, all at once. The "point-like" parameters R, dRdx, and dRdy are each a pointers to arrays of float value[3][BatchWidth] (or alternately like Imath::Vec3<FloatWide>). That is, each one points to all the x values for the batch, immediately followed by all the y values, followed by the z values. The mask determines which of those array elements to actually compute.

The various results arrays are also arranged as arrays that behave as if they were declared float result[channels][BatchWidth], where all the batch values for channel 0 are adjacent, followed by all the batch values for channel 1, etc.

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
RPointers to the 3D texture coordinates, each as a float[3][BatchWidth].
dRdx/dRdyThe differentials of R relative to canonical directions x and y, each as a float[3][BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::environment ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOptBatch options,
Tex::RunMask  mask,
const float *  R,
const float *  dRdx,
const float *  dRdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Slightly faster version of environment() if the app already has a texture handle and per-thread info.

virtual bool TextureSystem::environment ( ustring  filename,
TextureOptions options,
Runflag runflags,
int  beginactive,
int  endactive,
VaryingRef< Imath::V3f R,
VaryingRef< Imath::V3f dRdx,
VaryingRef< Imath::V3f dRdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::environment ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOptions options,
Runflag runflags,
int  beginactive,
int  endactive,
VaryingRef< Imath::V3f R,
VaryingRef< Imath::V3f dRdx,
VaryingRef< Imath::V3f dRdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::get_imagespec ( ustring  filename,
int  subimage,
ImageSpec spec 
)
pure virtual

Copy the ImageSpec associated with the named texture (the first subimage by default, or as set by subimage).

Parameters
filenameThe name of the image.
subimageThe subimage to query. (The spec retrieved is for the highest-resolution MIP level of that subimage.)
specImageSpec into which will be copied the spec for the requested image.
Returns
true upon success, false upon failure failure (such as being unable to find, open, or read the file, or if it does not contain the designated subimage or MIP level).
virtual bool TextureSystem::get_imagespec ( TextureHandle *  texture_handle,
Perthread *  thread_info,
int  subimage,
ImageSpec spec 
)
pure virtual

A more efficient variety of get_imagespec() for cases where you can use a TextureHandle* to specify the image and optionally have a Perthread* for the calling thread.

virtual Perthread* TextureSystem::get_perthread_info ( Perthread *  thread_info = nullptr)
pure virtual

Retrieve a Perthread, unique to the calling thread. This is a thread-specific pointer that will always return the Perthread for a thread, which will also be automatically destroyed when the thread terminates.

Applications that want to manage their own Perthread pointers (with create_thread_info and destroy_thread_info) should still call this, but passing in their managed pointer. If the passed-in thread_info is not nullptr, it won't create a new one or retrieve a TSP, but it will do other necessary housekeeping on the Perthread information.

virtual bool TextureSystem::get_texels ( ustring  filename,
TextureOpt options,
int  miplevel,
int  xbegin,
int  xend,
int  ybegin,
int  yend,
int  zbegin,
int  zend,
int  chbegin,
int  chend,
TypeDesc  format,
void result 
)
pure virtual

For a texture specified by name, retrieve the rectangle of raw unfiltered texels from the subimage specified in options and at the designated miplevel, storing the pixel values beginning at the address specified by result. The pixel values will be converted to the data type specified by format. The rectangular region to be retrieved includes begin but does not include end (much like STL begin/end usage). Requested pixels that are not part of the valid pixel data region of the image file will be filled with zero values. Channels requested but not present in the file will get the options.fill value.

Parameters
filenameThe name of the image.
optionsA TextureOpt describing access options, including wrap modes, fill value, and subimage, that will be used when retrieving pixels.
miplevelThe MIP level to retrieve pixels from (0 is the highest resolution level).
xbegin/xend/ybegin/yend/zbegin/zendThe range of pixels to retrieve. The pixels retrieved include the begin value but not the end value (much like STL begin/end usage).
chbegin/chendChannel range to retrieve. To retrieve all channels, use chbegin = 0, chend = nchannels.
formatTypeDesc describing the data type of the values you want to retrieve into result. The pixel values will be converted to this type regardless of how they were stored in the file or in the cache.
resultPointer to the memory where the pixel values should be stored. It is up to the caller to ensure that result points to an area of memory big enough to accommodate the requested rectangle (taking into consideration its dimensions, number of channels, and data format).
Returns
true for success, false for failure.
virtual bool TextureSystem::get_texels ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOpt options,
int  miplevel,
int  xbegin,
int  xend,
int  ybegin,
int  yend,
int  zbegin,
int  zend,
int  chbegin,
int  chend,
TypeDesc  format,
void result 
)
pure virtual

A more efficient variety of get_texels() for cases where you can use a TextureHandle* to specify the image and optionally have a Perthread* for the calling thread.

virtual TextureHandle* TextureSystem::get_texture_handle ( ustring  filename,
Perthread *  thread_info = nullptr 
)
pure virtual

Retrieve an opaque handle for fast texture lookups. The opaque pointer thread_info is thread-specific information returned by get_perthread_info(). Return nullptr if something has gone horribly wrong.

virtual bool TextureSystem::get_texture_info ( ustring  filename,
int  subimage,
ustring  dataname,
TypeDesc  datatype,
void data 
)
pure virtual

Get information or metadata about the named texture and store it in *data.

Data names may include any of the following:

  • exists (int): Stores the value 1 if the file exists and is an image format that OpenImageIO can read, or 0 if the file does not exist, or could not be properly read as a texture. Note that unlike all other queries, this query will "succeed" (return true) even if the file does not exist.
  • udim (int) : Stores the value 1 if the file is a "virtual UDIM" or texture atlas file (as described in Section :ref:sec-texturesys-udim) or 0 otherwise.
  • subimages (int) : The number of subimages/faces in the file, as an integer.
  • resolution (int[2] or int[3]): The resolution of the texture file, if an array of 2 integers (described as TypeDesc(INT,2)), or the 3D resolution of the texture file, which is an array of 3 integers (described as TypeDesc(INT,3)) The third value will be 1 unless it's a volumetric (3D) image.
  • miplevels (int) : The number of MIPmap levels for the specified subimage (an integer).
  • texturetype (string) : A string describing the type of texture of the given file, which describes how the texture may be used (also which texture API call is probably the right one for it). This currently may return one of: "unknown", "Plain Texture", "Volume Texture", "Shadow", or "Environment".
  • textureformat (string) : A string describing the format of the given file, which describes the kind of texture stored in the file. This currently may return one of: "unknown", "Plain Texture", "Volume Texture", "Shadow", "CubeFace Shadow", "Volume Shadow", "LatLong Environment", or "CubeFace Environment". Note that there are several kinds of shadows and environment maps, all accessible through the same API calls.
  • channels (int) : The number of color channels in the file.
  • format (int) : The native data format of the pixels in the file (an integer, giving the TypeDesc::BASETYPE of the data). Note that this is not necessarily the same as the data format stored in the image cache.
  • cachedformat (int) : The native data format of the pixels as stored in the image cache (an integer, giving the TypeDesc::BASETYPE of the data). Note that this is not necessarily the same as the native data format of the file.
  • datawindow (int[4] or int[6]): Returns the pixel data window of the image, which is either an array of 4 integers (returning xmin, ymin, xmax, ymax) or an array of 6 integers (returning xmin, ymin, zmin, xmax, ymax, zmax). The z values may be useful for 3D/volumetric images; for 2D images they will be 0).
  • displaywindow (matrix) : Returns the display (a.k.a. full) window of the image, which is either an array of 4 integers (returning xmin, ymin, xmax, ymax) or an array of 6 integers (returning xmin, ymin, zmin, xmax, ymax, zmax). The z values may be useful for 3D/volumetric images; for 2D images they will be 0).
  • worldtocamera (matrix) : The viewing matrix, which is a 4x4 matrix (an Imath::M44f, described as TypeMatrix44) giving the world-to-camera 3D transformation matrix that was used when the image was created. Generally, only rendered images will have this.
  • worldtoscreen (matrix) : The projection matrix, which is a 4x4 matrix (an Imath::M44f, described as TypeMatrix44) giving the matrix that projected points from world space into a 2D screen coordinate system where x and y range from -1 to +1. Generally, only rendered images will have this.
  • worldtoNDC (matrix) : The projection matrix, which is a 4x4 matrix (an Imath::M44f, described as TypeMatrix44) giving the matrix that projected points from world space into a 2D screen coordinate system where x and y range from 0 to +1. Generally, only rendered images will have this.
  • averagecolor (float[nchannels]) : If available in the metadata (generally only for files that have been processed by maketx), this will return the average color of the texture (into an array of floats).
  • averagealpha (float) : If available in the metadata (generally only for files that have been processed by maketx), this will return the average alpha value of the texture (into a float).
  • constantcolor (float[nchannels]) : If the metadata (generally only for files that have been processed by maketx) indicates that the texture has the same values for all pixels in the texture, this will retrieve the constant color of the texture (into an array of floats). A non-constant image (or one that does not have the special metadata tag identifying it as a constant texture) will fail this query (return false).
  • constantalpha (float) : If the metadata indicates that the texture has the same values for all pixels in the texture, this will retrieve the constant alpha value of the texture. A non-constant image (or one that does not have the special metadata tag identifying it as a constant texture) will fail this query (return false).
  • stat:tilesread (int64) : Number of tiles read from this file.
  • stat:bytesread (int64) : Number of bytes of uncompressed pixel data read
  • stat:redundant_tiles (int64) : Number of times a tile was read, where the same tile had been rad before.
  • stat:redundant_bytesread (int64) : Number of bytes (of uncompressed pixel data) in tiles that were read redundantly.
  • stat:redundant_bytesread (int) : Number of tiles read from this file.
  • stat:timesopened (int) : Number of times this file was opened.
  • stat:iotime (float) : Time (in seconds) spent on all I/O for this file.
  • stat:mipsused (int) : Stores 1 if any MIP levels beyond the highest resolution were accessed, otherwise 0.
  • stat:is_duplicate (int) : Stores 1 if this file was a duplicate of another image, otherwise 0.
  • Anything else : For all other data names, the the metadata of the image file will be searched for an item that matches both the name and data type.
Parameters
filenameThe name of the texture.
subimageThe subimage to query. (The metadata retrieved is for the highest-resolution MIP level of that subimage.)
datanameThe name of the metadata to retrieve.
datatypeTypeDesc describing the data type.
dataPointer to the caller-owned memory where the values should be stored. It is the caller's responsibility to ensure that data points to a large enough storage area to accommodate the datatype requested.
Returns
true if get_textureinfo() is able to find the requested dataname for the texture and it matched the requested datatype. If the requested data was not found or was not of the right data type, return false. Except for the "exists" query, a file that does not exist or could not be read properly as an image also constitutes a query failure that will return false.
virtual bool TextureSystem::get_texture_info ( TextureHandle *  texture_handle,
Perthread *  thread_info,
int  subimage,
ustring  dataname,
TypeDesc  datatype,
void data 
)
pure virtual

A more efficient variety of get_texture_info() for cases where you can use a TextureHandle* to specify the image and optionally have a Perthread* for the calling thread.

virtual bool TextureSystem::getattribute ( string_view  name,
TypeDesc  type,
void val 
) const
pure virtual

Get the named attribute of the texture system, store it in *val. All of the attributes that may be set with the attribute() call may also be queried with getattribute().

Examples:

TextureSystem *ic;
...
int maxfiles;
ts->getattribute ("max_open_files", TypeDesc::INT, &maxfiles);

const char *path;
ts->getattribute ("searchpath", TypeDesc::STRING, &path);

// There are specialized versions for retrieving a single int,
// float, or string without needing types or pointers:
int maxfiles;
ts->getattribute ("max_open_files", maxfiles);
const char *path;
ts->getattribute ("searchpath", &path);

Note: When retrieving a string, you need to pass a pointer to the char*, not a pointer to the first character. Also, the char* will end up pointing to characters owned by the ImageCache; the caller does not need to ever free the memory that contains the characters.

Parameters
nameName of the attribute to retrieve.
typeTypeDesc describing the type of the attribute.
valPointer where the attribute value should be stored.
Returns
true if the name and type were recognized and the attribute was retrieved, or false upon failure (including it being an unrecognized attribute or not of the correct type).
virtual bool TextureSystem::getattribute ( string_view  name,
int val 
) const
pure virtual

Specialized attribute() for retrieving a single int value.

virtual bool TextureSystem::getattribute ( string_view  name,
float &  val 
) const
pure virtual

Specialized attribute() for retrieving a single float value.

virtual bool TextureSystem::getattribute ( string_view  name,
double &  val 
) const
pure virtual

Set a named attribute (i.e., a property or option) of the TextureSystem.

Example:

TextureSystem *ts;
...
int maxfiles = 50;
ts->attribute ("max_open_files", TypeDesc::INT, &maxfiles);

const char *path = "/my/path";
ts->attribute ("searchpath", TypeDesc::STRING, &path);

// There are specialized versions for retrieving a single int,
// float, or string without needing types or pointers:
ts->getattribute ("max_open_files", 50);
ic->attribute ("max_memory_MB", 4000.0f);
ic->attribute ("searchpath", "/my/path");

Note: When passing a string, you need to pass a pointer to the char*, not a pointer to the first character. (Rationale: for an int attribute, you pass the address of the int. So for a string, which is a char*, you need to pass the address of the string, i.e., a char**).

Parameters
nameName of the attribute to set.
typeTypeDesc describing the type of the attribute.
valPointer to the value data.
Returns
true if the name and type were recognized and the attribute was set, or false upon failure (including it being an unrecognized attribute or not of the correct type).
virtual bool TextureSystem::getattribute ( string_view  name,
char **  val 
) const
pure virtual

Specialized attribute() for retrieving a single string value as a char*.

virtual bool TextureSystem::getattribute ( string_view  name,
std::string val 
) const
pure virtual

Specialized attribute() for retrieving a single string value as a std::string.

virtual std::string TextureSystem::geterror ( ) const
pure virtual

If any of the API routines returned false indicating an error, this routine will return the error string (and clear any error flags). If no error has occurred since the last time geterror() was called, it will return an empty string.

virtual std::string TextureSystem::getstats ( int  level = 1,
bool  icstats = true 
) const
pure virtual

Returns a big string containing useful statistics about the TextureSystem operations, suitable for saving to a file or outputting to the terminal. The level indicates the amount of detail in the statistics, with higher numbers (up to a maximum of 5) yielding more and more esoteric information. If icstats is true, the returned string will also contain all the statistics of the underlying ImageCache, but if false will only contain texture-specific statistics.

virtual bool TextureSystem::good ( TextureHandle *  texture_handle)
pure virtual

Return true if the texture handle (previously returned by get_image_handle()) is a valid texture that can be subsequently read.

virtual ImageCache* TextureSystem::imagecache ( ) const
pure virtual

Return an opaque, non-owning pointer to the underlying ImageCache (if there is one).

virtual const ImageSpec* TextureSystem::imagespec ( ustring  filename,
int  subimage = 0 
)
pure virtual

Return a pointer to an ImageSpec associated with the named texture if the file is found and is an image format that can be read, otherwise return nullptr.

This method is much more efficient than get_imagespec(), since it just returns a pointer to the spec held internally by the TextureSystem (rather than copying the spec to the user's memory). However, the caller must beware that the pointer is only valid as long as nobody (even other threads) calls invalidate() on the file, or invalidate_all(), or destroys the TextureSystem and its underlying ImageCache.

Parameters
filenameThe name of the image.
subimageThe subimage to query. (The spec retrieved is for the highest-resolution MIP level of that subimage.)
Returns
A pointer to the spec, if the image is found and able to be opened and read by an available image format plugin, and the designated subimage exists.
virtual const ImageSpec* TextureSystem::imagespec ( TextureHandle *  texture_handle,
Perthread *  thread_info = nullptr,
int  subimage = 0 
)
pure virtual

A more efficient variety of imagespec() for cases where you can use a TextureHandle* to specify the image and optionally have a Perthread* for the calling thread.

virtual void TextureSystem::invalidate ( ustring  filename,
bool  force = true 
)
pure virtual

Invalidate any cached information about the named file, including loaded texture tiles from that texture, and close any open file handle associated with the file. This calls ImageCache::invalidate(filename,force) on the underlying ImageCache.

virtual void TextureSystem::invalidate_all ( bool  force = false)
pure virtual

Invalidate all cached data for all textures. This calls ImageCache::invalidate_all(force) on the underlying ImageCache.

virtual void TextureSystem::reset_stats ( )
pure virtual

Reset most statistics to be as they were with a fresh TextureSystem. Caveat emptor: this does not flush the cache itself, so the resulting statistics from the next set of texture requests will not match the number of tile reads, etc., that would have resulted from a new TextureSystem.

virtual std::string TextureSystem::resolve_filename ( const std::string filename) const
pure virtual

Given possibly-relative 'filename', resolve it using the search path rules and return the full resolved filename.

virtual bool TextureSystem::shadow ( ustring  filename,
TextureOpt options,
const Imath::V3f P,
const Imath::V3f dPdx,
const Imath::V3f dPdy,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform a filtered 2D texture lookup on a position centered at 2D coordinates (s, t) from the texture identified by filename, and using relevant texture options. The nchannels parameter determines the number of channels to retrieve (e.g., 1 for a single value, 3 for an RGB triple, etc.). The filtered results will be stored in result[0..nchannels-1].

We assume that this lookup will be part of an image that has pixel coordinates x and y. By knowing how s and t change from pixel to pixel in the final image, we can properly filter or antialias the texture lookups. This information is given via derivatives dsdx and dtdx that define the change in s and t per unit of x, and dsdy and dtdy that define the change in s and t per unit of y. If it is impossible to know the derivatives, you may pass 0 for them, but in that case you will not receive an antialiased texture lookup.

Parameters
filenameThe name of the texture.
optionsFields within options that are honored for 2D texture lookups include the following:
  • int firstchannel : The index of the first channel to look up from the texture.
  • int subimage / ustring subimagename : The subimage or face within the file, specified by either by name (if non-empty) or index. This will be ignored if the file does not have multiple subimages or separate per-face textures.
  • Wrap swrap, twrap : Specify the wrap mode for each direction, one of: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror, or WrapDefault.
  • float swidth, twidth : For each direction, gives a multiplier for the derivatives.
  • float sblur, tblur : For each direction, specifies an additional amount of pre-blur to apply to the texture (after derivatives are taken into account), expressed as a portion of the width of the texture.
  • float fill : Specifies the value that will be used for any color channels that are requested but not found in the file. For example, if you perform a 4-channel lookup on a 3-channel texture, the last channel will get the fill value. (Note: this behavior is affected by the "gray_to_rgb" TextureSystem attribute.
  • const float *missingcolor : If not nullptr, specifies the color that will be returned for missing or broken textures (rather than being an error).
s/tThe 2D texture coordinates.
dsdx,dtdx,dsdy,dtdyThe differentials of s and t relative to canonical directions x and y. The choice of x and y are not important to the implementation; it can be any imposed 2D coordinates, such as pixels in screen space, adjacent samples in parameter space on a surface, etc. The st derivatives determine the size and shape of the ellipsoid over which the texture lookup is filtered.
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed into result[0..nchannels-1].
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, i.e., the rate of change per unit s and t, respectively, of the filtered texture. If supplied, they must allow for nchannels of storage.
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::shadow ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOpt options,
const Imath::V3f P,
const Imath::V3f dPdx,
const Imath::V3f dPdy,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform a filtered 2D texture lookup on a position centered at 2D coordinates (s, t) from the texture identified by filename, and using relevant texture options. The nchannels parameter determines the number of channels to retrieve (e.g., 1 for a single value, 3 for an RGB triple, etc.). The filtered results will be stored in result[0..nchannels-1].

We assume that this lookup will be part of an image that has pixel coordinates x and y. By knowing how s and t change from pixel to pixel in the final image, we can properly filter or antialias the texture lookups. This information is given via derivatives dsdx and dtdx that define the change in s and t per unit of x, and dsdy and dtdy that define the change in s and t per unit of y. If it is impossible to know the derivatives, you may pass 0 for them, but in that case you will not receive an antialiased texture lookup.

Parameters
filenameThe name of the texture.
optionsFields within options that are honored for 2D texture lookups include the following:
  • int firstchannel : The index of the first channel to look up from the texture.
  • int subimage / ustring subimagename : The subimage or face within the file, specified by either by name (if non-empty) or index. This will be ignored if the file does not have multiple subimages or separate per-face textures.
  • Wrap swrap, twrap : Specify the wrap mode for each direction, one of: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror, or WrapDefault.
  • float swidth, twidth : For each direction, gives a multiplier for the derivatives.
  • float sblur, tblur : For each direction, specifies an additional amount of pre-blur to apply to the texture (after derivatives are taken into account), expressed as a portion of the width of the texture.
  • float fill : Specifies the value that will be used for any color channels that are requested but not found in the file. For example, if you perform a 4-channel lookup on a 3-channel texture, the last channel will get the fill value. (Note: this behavior is affected by the "gray_to_rgb" TextureSystem attribute.
  • const float *missingcolor : If not nullptr, specifies the color that will be returned for missing or broken textures (rather than being an error).
s/tThe 2D texture coordinates.
dsdx,dtdx,dsdy,dtdyThe differentials of s and t relative to canonical directions x and y. The choice of x and y are not important to the implementation; it can be any imposed 2D coordinates, such as pixels in screen space, adjacent samples in parameter space on a surface, etc. The st derivatives determine the size and shape of the ellipsoid over which the texture lookup is filtered.
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed into result[0..nchannels-1].
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, i.e., the rate of change per unit s and t, respectively, of the filtered texture. If supplied, they must allow for nchannels of storage.
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::shadow ( ustring  filename,
TextureOptBatch options,
Tex::RunMask  mask,
const float *  P,
const float *  dPdx,
const float *  dPdy,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::shadow ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOptBatch options,
Tex::RunMask  mask,
const float *  P,
const float *  dPdx,
const float *  dPdy,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::shadow ( ustring  filename,
TextureOptions options,
Runflag runflags,
int  beginactive,
int  endactive,
VaryingRef< Imath::V3f P,
VaryingRef< Imath::V3f dPdx,
VaryingRef< Imath::V3f dPdy,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::shadow ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOptions options,
Runflag runflags,
int  beginactive,
int  endactive,
VaryingRef< Imath::V3f P,
VaryingRef< Imath::V3f dPdx,
VaryingRef< Imath::V3f dPdy,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::texture ( ustring  filename,
TextureOpt options,
float  s,
float  t,
float  dsdx,
float  dtdx,
float  dsdy,
float  dtdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform a filtered 2D texture lookup on a position centered at 2D coordinates (s, t) from the texture identified by filename, and using relevant texture options. The nchannels parameter determines the number of channels to retrieve (e.g., 1 for a single value, 3 for an RGB triple, etc.). The filtered results will be stored in result[0..nchannels-1].

We assume that this lookup will be part of an image that has pixel coordinates x and y. By knowing how s and t change from pixel to pixel in the final image, we can properly filter or antialias the texture lookups. This information is given via derivatives dsdx and dtdx that define the change in s and t per unit of x, and dsdy and dtdy that define the change in s and t per unit of y. If it is impossible to know the derivatives, you may pass 0 for them, but in that case you will not receive an antialiased texture lookup.

Parameters
filenameThe name of the texture.
optionsFields within options that are honored for 2D texture lookups include the following:
  • int firstchannel : The index of the first channel to look up from the texture.
  • int subimage / ustring subimagename : The subimage or face within the file, specified by either by name (if non-empty) or index. This will be ignored if the file does not have multiple subimages or separate per-face textures.
  • Wrap swrap, twrap : Specify the wrap mode for each direction, one of: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror, or WrapDefault.
  • float swidth, twidth : For each direction, gives a multiplier for the derivatives.
  • float sblur, tblur : For each direction, specifies an additional amount of pre-blur to apply to the texture (after derivatives are taken into account), expressed as a portion of the width of the texture.
  • float fill : Specifies the value that will be used for any color channels that are requested but not found in the file. For example, if you perform a 4-channel lookup on a 3-channel texture, the last channel will get the fill value. (Note: this behavior is affected by the "gray_to_rgb" TextureSystem attribute.
  • const float *missingcolor : If not nullptr, specifies the color that will be returned for missing or broken textures (rather than being an error).
s/tThe 2D texture coordinates.
dsdx,dtdx,dsdy,dtdyThe differentials of s and t relative to canonical directions x and y. The choice of x and y are not important to the implementation; it can be any imposed 2D coordinates, such as pixels in screen space, adjacent samples in parameter space on a surface, etc. The st derivatives determine the size and shape of the ellipsoid over which the texture lookup is filtered.
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed into result[0..nchannels-1].
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, i.e., the rate of change per unit s and t, respectively, of the filtered texture. If supplied, they must allow for nchannels of storage.
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::texture ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOpt options,
float  s,
float  t,
float  dsdx,
float  dtdx,
float  dsdy,
float  dtdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Slightly faster version of texture() lookup if the app already has a texture handle and per-thread info.

virtual bool TextureSystem::texture ( ustring  filename,
TextureOptBatch options,
Tex::RunMask  mask,
const float *  s,
const float *  t,
const float *  dsdx,
const float *  dtdx,
const float *  dsdy,
const float *  dtdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::texture ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOptBatch options,
Tex::RunMask  mask,
const float *  s,
const float *  t,
const float *  dsdx,
const float *  dtdx,
const float *  dsdy,
const float *  dtdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Slightly faster version of texture() lookup if the app already has a texture handle and per-thread info.

virtual bool TextureSystem::texture ( ustring  filename,
TextureOptions options,
Runflag runflags,
int  beginactive,
int  endactive,
VaryingRef< float >  s,
VaryingRef< float >  t,
VaryingRef< float >  dsdx,
VaryingRef< float >  dtdx,
VaryingRef< float >  dsdy,
VaryingRef< float >  dtdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::texture ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOptions options,
Runflag runflags,
int  beginactive,
int  endactive,
VaryingRef< float >  s,
VaryingRef< float >  t,
VaryingRef< float >  dsdx,
VaryingRef< float >  dtdx,
VaryingRef< float >  dsdy,
VaryingRef< float >  dtdy,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::texture3d ( ustring  filename,
TextureOpt options,
const Imath::V3f P,
const Imath::V3f dPdx,
const Imath::V3f dPdy,
const Imath::V3f dPdz,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr,
float *  dresultdr = nullptr 
)
pure virtual

Perform a filtered 3D volumetric texture lookup on a position centered at 3D position P (with given differentials) from the texture identified by filename, and using relevant texture options. The filtered results will be stored in result[0..nchannels-1].

The P coordinate and dPdx, dPdy, and dPdz derivatives are assumed to be in some kind of common global coordinate system (usually "world" space) and will be automatically transformed into volume local coordinates, if such a transformation is specified in the volume file itself.

Parameters
filenameThe name of the texture.
optionsFields within options that are honored for 3D texture lookups include the following:
  • int firstchannel : The index of the first channel to look up from the texture.
  • int subimage / ustring subimagename : The subimage or field within the volume, specified by either by name (if non-empty) or index. This will be ignored if the file does not have multiple subimages or separate per-face textures.
  • Wrap swrap, twrap, rwrap : Specify the wrap mode for each direction, one of: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror, or WrapDefault.
  • float swidth, twidth, rwidth : For each direction, gives a multiplier for the derivatives.
  • float sblur, tblur, rblur : For each direction, specifies an additional amount of pre-blur to apply to the texture (after derivatives are taken into account), expressed as a portion of the width of the texture.
  • float fill : Specifies the value that will be used for any color channels that are requested but not found in the file. For example, if you perform a 4-channel lookup on a 3-channel texture, the last channel will get the fill value. (Note: this behavior is affected by the "gray_to_rgb" TextureSystem attribute.
  • const float *missingcolor : If not nullptr, specifies the color that will be returned for missing or broken textures (rather than being an error).
  • float time : A time value to use if the volume texture specifies a time-varying local transformation (default: 0).
PThe 2D texture coordinates.
dPdx/dPdy/dPdzThe differentials of P. We assume that this lookup will be part of an image that has pixel coordinates x and y and depth z. By knowing how P changes from pixel to pixel in the final image, and as we step in z depth, we can properly filter or antialias the texture lookups. This information is given via derivatives dPdx, dPdy, and dPdz that define the changes in P per unit of x, y, and z, respectively. If it is impossible to know the derivatives, you may pass 0 for them, but in that case you will not receive an antialiased texture lookup.
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed into result[0..nchannels-1].
dresultds/dresultdt/dresultdrIf non-null, these designate storage locations for the derivatives of result, i.e., the rate of change per unit s, t, and r, respectively, of the filtered texture. If supplied, they must allow for nchannels of storage.
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::texture3d ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOpt options,
const Imath::V3f P,
const Imath::V3f dPdx,
const Imath::V3f dPdy,
const Imath::V3f dPdz,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr,
float *  dresultdr = nullptr 
)
pure virtual

Slightly faster version of texture3d() lookup if the app already has a texture handle and per-thread info.

virtual bool TextureSystem::texture3d ( ustring  filename,
TextureOptBatch options,
Tex::RunMask  mask,
const float *  P,
const float *  dPdx,
const float *  dPdy,
const float *  dPdz,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr,
float *  dresultdr = nullptr 
)
pure virtual

Perform filtered 3D volumetric texture lookups on a batch of positions from the same texture, all at once. The "point-like" parameters P, dPdx, dPdy, and dPdz are each a pointers to arrays of float value[3][BatchWidth] (or alternately like Imath::Vec3<FloatWide>). That is, each one points to all the x values for the batch, immediately followed by all the y values, followed by the z values. The mask determines which of those array elements to actually compute.

The various results arrays are also arranged as arrays that behave as if they were declared float result[channels][BatchWidth], where all the batch values for channel 0 are adjacent, followed by all the batch values for channel 1, etc.

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
PPointers to the 3D texture coordinates, each as a float[3][BatchWidth].
dPdx/dPdy/dPdzThe differentials of P relative to canonical directions x, y, and z, each as a float[3][BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdt/dresultdrIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::texture3d ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOptBatch options,
Tex::RunMask  mask,
const float *  P,
const float *  dPdx,
const float *  dPdy,
const float *  dPdz,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr,
float *  dresultdr = nullptr 
)
pure virtual

Slightly faster version of texture3d() lookup if the app already has a texture handle and per-thread info.

virtual bool TextureSystem::texture3d ( ustring  filename,
TextureOptions options,
Runflag runflags,
int  beginactive,
int  endactive,
VaryingRef< Imath::V3f P,
VaryingRef< Imath::V3f dPdx,
VaryingRef< Imath::V3f dPdy,
VaryingRef< Imath::V3f dPdz,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr,
float *  dresultdr = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
virtual bool TextureSystem::texture3d ( TextureHandle *  texture_handle,
Perthread *  thread_info,
TextureOptions options,
Runflag runflags,
int  beginactive,
int  endactive,
VaryingRef< Imath::V3f P,
VaryingRef< Imath::V3f dPdx,
VaryingRef< Imath::V3f dPdy,
VaryingRef< Imath::V3f dPdz,
int  nchannels,
float *  result,
float *  dresultds = nullptr,
float *  dresultdt = nullptr,
float *  dresultdr = nullptr 
)
pure virtual

Perform filtered 2D texture lookups on a batch of positions from the same texture, all at once. The parameters s, t, dsdx, dtdx, and dsdy, dtdy are each a pointer to [BatchWidth] values. The mask determines which of those array elements to actually compute.

The float* results act like float[nchannels][BatchWidth], so that effectively result[0..BatchWidth-1] are the "red" result for each lane, result[BatchWidth..2*BatchWidth-1] are the "green" results, etc. The dresultds and dresultdt should either both be provided, or else both be nullptr (meaning no derivative results are required).

Parameters
filenameThe name of the texture.
optionsA TextureOptBatch containing texture lookup options. This is conceptually the same as a TextureOpt, but the following fields are arrays of [BatchWidth] elements: sblur, tblur, swidth, twidth. The other fields are, as with TextureOpt, ordinary scalar values.
maskA bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i].
s/tPointers to the 2D texture coordinates, each as a float[BatchWidth].
dsdx/dtdx/dsdy/dtdyThe differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth].
nchannelsThe number of channels of data to retrieve into result (e.g., 1 for a single value, 3 for an RGB triple, etc.).
result[]The result of the filtered texture lookup will be placed here, as float [nchannels][BatchWidth]. (Note the "SOA" data layout.)
dresultds/dresultdtIf non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth]
Returns
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.

The documentation for this class was generated from the following file: