|
HDK
|
#include <texture.h>
Public Member Functions | |
| virtual ImageCache * | imagecache () 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:
Texture-specific settings:
Read-only attributes Additionally, there are some read-only attributes that can be queried with 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
| |
| 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 |
| TextureHandle * | get_texture_handle (const std::wstring &filename, Perthread *thread_info=nullptr) |
| Get a TextureHandle using a UTF-16 encoded wstring filename. More... | |
| virtual bool | good (TextureHandle *texture_handle)=0 |
| virtual ustring | filename_from_handle (TextureHandle *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 ImageSpec * | imagespec (ustring filename, int subimage=0)=0 |
| virtual const ImageSpec * | imagespec (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 |
Methods for UDIM patterns | |
| virtual bool | is_udim (ustring filename)=0 |
| virtual bool | is_udim (TextureHandle *udimfile)=0 |
| virtual TextureHandle * | resolve_udim (ustring udimpattern, float s, float t)=0 |
| virtual TextureHandle * | resolve_udim (TextureHandle *udimfile, Perthread *thread_info, float s, float t)=0 |
| virtual void | inventory_udim (ustring udimpattern, std::vector< ustring > &filenames, int &nutiles, int &nvtiles)=0 |
| virtual void | inventory_udim (TextureHandle *udimfile, Perthread *thread_info, std::vector< ustring > &filenames, int &nutiles, int &nvtiles)=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 bool | has_error () const =0 |
| Is there a pending error message waiting to be retrieved? More... | |
| virtual std::string | geterror (bool clear=true) 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 TextureSystem * | create (bool shared=true, ImageCache *imagecache=nullptr) |
| static void | destroy (TextureSystem *ts, bool teardown_imagecache=false) |
Protected Member Functions | |
| TextureSystem (void) | |
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.
|
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**).
| name | Name of the attribute to set. |
| type | TypeDesc describing the type of the attribute. |
| val | Pointer to the value data. |
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).
|
pure virtual |
Specialized attribute() for setting a single int value.
|
pure virtual |
Specialized attribute() for setting a single float value.
|
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**).
| name | Name of the attribute to set. |
| type | TypeDesc describing the type of the attribute. |
| val | Pointer to the value data. |
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).
|
pure virtual |
Specialized attribute() for setting a single string value.
Close any open file handles associated with a UTF-8 encoded filename, 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.
|
static |
Create a TextureSystem and return a pointer to it. This should only be freed by passing it to TextureSystem::destroy()!
| shared | If 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. |
| imagecache | If 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. |
TextureSystem::destroy().
|
pure virtual |
Create a new Perthread. It is the caller's responsibility to eventually destroy it using destroy_thread_info().
|
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.
| ts | Raw pointer to the TextureSystem to destroy. |
| teardown_imagecache | For 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. |
|
pure virtual |
Destroy a Perthread that was allocated by create_thread_info().
|
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[].
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | Fields within options that are honored for environment lookups include the following:
|
| R | The direction vector to look up. |
| dRdx/dRdy | The differentials of R with respect to image coordinates x and y. |
| nchannels | The 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 | If 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. |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
pure virtual |
Slightly faster version of environment() if the app already has a texture handle and per-thread info.
|
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.
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i]. |
| R | Pointers to the 3D texture coordinates, each as a float[3][BatchWidth]. |
| dRdx/dRdy | The differentials of R relative to canonical directions x and y, each as a float[3][BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
pure virtual |
Slightly faster version of environment() if the app already has a texture handle and per-thread info.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
pure virtual |
Given a handle, return the UTF-8 encoded filename for that texture.
This method was added in OpenImageIO 2.3.
|
pure virtual |
Copy the ImageSpec associated with the named texture (the first subimage by default, or as set by subimage).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| subimage | The subimage to query. (The spec retrieved is for the highest-resolution MIP level of that subimage.) |
| spec | ImageSpec into which will be copied the spec for the requested image. |
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).
|
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.
|
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.
|
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.
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A TextureOpt describing access options, including wrap modes, fill value, and subimage, that will be used when retrieving pixels. |
| miplevel | The MIP level to retrieve pixels from (0 is the highest resolution level). |
| xbegin/xend/ybegin/yend/zbegin/zend | The range of pixels to retrieve. The pixels retrieved include the begin value but not the end value (much like STL begin/end usage). |
| chbegin/chend | Channel range to retrieve. To retrieve all channels, use chbegin = 0, chend = nchannels. |
| format | TypeDesc 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. |
| result | Pointer 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). |
true for success, false for failure.
|
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.
|
pure virtual |
Retrieve an opaque handle for fast texture lookups. The filename is presumed to be UTF-8 encoded. The opaque pointer thread_info is thread-specific information returned by get_perthread_info(). Return nullptr if something has gone horribly wrong.
|
inline |
|
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 readstat: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.| filename | The name of the texture, as a UTF-8 encode ustring. |
| subimage | The subimage to query. (The metadata retrieved is for the highest-resolution MIP level of that subimage.) |
| dataname | The name of the metadata to retrieve. |
| datatype | TypeDesc describing the data type. |
| data | Pointer 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. |
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.
|
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.
|
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.
| name | Name of the attribute to retrieve. |
| type | TypeDesc describing the type of the attribute. |
| val | Pointer where the attribute value should be stored. |
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).
|
pure virtual |
Specialized attribute() for retrieving a single int value.
|
pure virtual |
Specialized attribute() for retrieving a single float value.
|
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**).
| name | Name of the attribute to set. |
| type | TypeDesc describing the type of the attribute. |
| val | Pointer to the value data. |
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).
|
pure virtual |
Specialized attribute() for retrieving a single string value as a char*.
|
pure virtual |
Specialized attribute() for retrieving a single string value as a std::string.
|
pure virtual |
Return the text of all pending error messages issued against this TextureSystem, and clear the pending error message unless clear is false. If no error message is pending, it will return an empty string.
|
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.
|
pure virtual |
Return true if the texture handle (previously returned by get_image_handle()) is a valid texture that can be subsequently read.
|
pure virtual |
Is there a pending error message waiting to be retrieved?
|
pure virtual |
Return an opaque, non-owning pointer to the underlying ImageCache (if there is one).
|
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.
| filename | The name of the texture, as a UTF-8 encode ustring. |
| subimage | The subimage to query. (The spec retrieved is for the highest-resolution MIP level of that subimage.) |
|
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.
Invalidate any cached information about the named file (UTF-8 encoded), 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.
|
pure virtual |
Invalidate all cached data for all textures. This calls ImageCache::invalidate_all(force) on the underlying ImageCache.
|
pure virtual |
Produce a full inventory of the set of concrete files comprising the UDIM set specified by UTF-8 encoded udimpattern. The apparent number of texture atlas tiles in the u and v directions will be written to nutiles and nvtiles, respectively. The vector filenames will be sized to ntiles * nvtiles and filled with the the names of the concrete files comprising the atlas, with an empty ustring corresponding to any unpopulated tiles (the UDIM set is allowed to be sparse). The filename list is indexed as utile + vtile
This method was added in OpenImageIO 2.3.
|
pure virtual |
A more efficient variety of inventory_udim() for cases where you have the TextureHandle* that corresponds to the "virtual" UDIM file and optionally have a Perthread* for the calling thread.
This method was added in OpenImageIO 2.3.
|
pure virtual |
Is the UTF-8 encoded filename a UDIM pattern?
This method was added in OpenImageIO 2.3.
|
pure virtual |
Does the handle refer to a file that's a UDIM pattern?
This method was added in OpenImageIO 2.3.
|
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.
|
pure virtual |
Given possibly-relative 'filename' (UTF-8 encoded), resolve it using the search path rules and return the full resolved filename.
|
pure virtual |
For a UDIM filename pattern (UTF-8 encoded) and texture coordinates, return the TextureHandle pointer for the concrete tile file it refers to, or nullptr if there is no corresponding tile (udim sets are allowed to be sparse).
This method was added in OpenImageIO 2.3.
|
pure virtual |
A more efficient variety of resolve_udim() for cases where you have the TextureHandle* that corresponds to the "virtual" UDIM file and optionally have a Perthread* for the calling thread.
This method was added in OpenImageIO 2.3.
|
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.
| filename | The name of the texture, as a UTF-8 encoded ustring. |
| options | Fields within options that are honored for 2D texture lookups include the following:
|
| s/t | The 2D texture coordinates. |
| dsdx,dtdx,dsdy,dtdy | The 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. |
| nchannels | The 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 | If 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. |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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.
| filename | The name of the texture, as a UTF-8 encoded ustring. |
| options | Fields within options that are honored for 2D texture lookups include the following:
|
| s/t | The 2D texture coordinates. |
| dsdx,dtdx,dsdy,dtdy | The 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. |
| nchannels | The 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 | If 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. |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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.
| filename | The name of the texture, as a UTF-8 encoded ustring. |
| options | Fields within options that are honored for 2D texture lookups include the following:
|
| s/t | The 2D texture coordinates. |
| dsdx,dtdx,dsdy,dtdy | The 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. |
| nchannels | The 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 | If 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. |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
pure virtual |
Slightly faster version of texture() lookup if the app already has a texture handle and per-thread info.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
pure virtual |
Slightly faster version of texture() lookup if the app already has a texture handle and per-thread info.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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.
| filename | The name of the texture, as a UTF-8 encoded ustring. |
| options | Fields within options that are honored for 3D texture lookups include the following:
|
| P | The 2D texture coordinates. |
| dPdx/dPdy/dPdz | The 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. |
| nchannels | The 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/dresultdr | If 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. |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
pure virtual |
Slightly faster version of texture3d() lookup if the app already has a texture handle and per-thread info.
|
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.
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A bit-field designating which "lanes" should be computed: if mask & (1<<i) is nonzero, then results should be computed and stored for result[...][i]. |
| P | Pointers to the 3D texture coordinates, each as a float[3][BatchWidth]. |
| dPdx/dPdy/dPdz | The differentials of P relative to canonical directions x, y, and z, each as a float[3][BatchWidth]. |
| nchannels | The 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/dresultdr | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
pure virtual |
Slightly faster version of texture3d() lookup if the app already has a texture handle and per-thread info.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin.
|
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).
| filename | The name of the texture, as a UTF-8 encode ustring. |
| options | A 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. |
| mask | A 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/t | Pointers to the 2D texture coordinates, each as a float[BatchWidth]. |
| dsdx/dtdx/dsdy/dtdy | The differentials of s and t relative to canonical directions x and y, each as a float[BatchWidth]. |
| nchannels | The 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 | If non-null, these designate storage locations for the derivatives of result, and like result are in SOA layout: float [nchannels][BatchWidth] |
true upon success, or false if the file was not found or could not be opened by any available ImageIO plugin. 
1.8.6