RenderManAPI
24.0
|
RixTexture performs filtered texture map lookups using a texture coordinate and a region over which to filter. More...
#include <RixInterfaces.h>
Inherits RixInterface.
Classes | |
struct | TxParams |
class | TxProperties |
Public Types | |
enum | ErrType { Ok = 0, FileNotFound, PartNotFound, InvalidFaceIndex, TextureAccessErr, InvalidDerivatives, InvalidFilter, InvalidFile } |
enum | TxAtlasStyle { AtlasNone =0, AtlasUdim, AtlasUvTile1, AtlasUvTile0 } |
enum | Type { k_Float, k_Integer, k_StringV, k_Color, k_Normal, k_Vector, k_Point, k_HPoint, k_MPoint, k_Matrix } |
Public Member Functions | |
virtual int | AcquireTexture (RtUString const fileName, TxAtlasStyle const atlasStyle, TxProperties &txProperties)=0 |
All texture access must acquire a texture first. More... | |
virtual int | AcquireTexturePart (int partIndex, TxProperties const &txProperties, TxProperties &partProperties)=0 |
Once a texture has been acquired, we can then acquire a part by part index, the partProperties will reflect the properties of the multi-part texture. More... | |
virtual int | ReleaseTexture (TxProperties const &txProperties)=0 |
All texture access should release a texture as soon as it is finished looking up values. More... | |
virtual int | Texture (TxProperties const &txProperties, TxParams const &txParams, int nPoints, RtFloat2 const *st, float const *stRadius, float *result, int *runFlags=NULL)=0 |
Lookup filtered texture results over nPoints from a texture obtained with AcquireTexture(). More... | |
virtual int | Texture (TxProperties const &txProperties, TxParams const &txParams, int nPoints, RtFloat3 const *st, float const *stRadius, float *result, int *runFlags=NULL)=0 |
virtual int | TextureDerivatives (TxProperties const &txProperties, TxParams const &txParams, int nPoints, RtFloat2 const *st, float const *dsdu, float const *dtdu, float const *dsdv, float const *dtdv, float const *dufp, float const *dvfp, float *result, float *dresultds, float *dresultdt, int *runFlags=NULL)=0 |
Lookup filtered texture results over nPoints from a texture obtained with AcquireTexture(). More... | |
virtual int | TextureDerivatives (TxProperties const &txProperties, TxParams const &txParams, int nPoints, RtFloat3 const *st, float const *dsdu, float const *dtdu, float const *dsdv, float const *dtdv, float const *dufp, float const *dvfp, float *result, float *dresultds, float *dresultdt, int *runFlags=NULL)=0 |
virtual int | Ptexture (TxProperties const &txProperties, TxParams const &txParams, int nPoints, RtFloat2 const *uv, float const *uWidth, float const *vWidth, float *result, int *runFlags=NULL)=0 |
Lookup filtered ptexture results over nPoints from a ptexture obtained with AcquireTexture(). More... | |
virtual int | PtextureDerivatives (TxProperties const &txProperties, TxParams const &txParams, int nPoints, RtFloat2 const *st, float const *dsdu, float const *dtdu, float const *dsdv, float const *dtdv, float *result, float *dresultds, float *dresultdt, int *runFlags=NULL)=0 |
Lookup filtered texture results over nPoints from a ptexture obtained with AcquireTexture(). More... | |
virtual int | TextureData (TxProperties const &txProperties, TxParams const &txParams, int mipLevel, int cubeFace, void *result)=0 |
Read the whole texture into a buffer at a given MIP level. More... | |
virtual int | GetProperty (TxProperties const &txProperties, RtUString const propertyName, void *result, int resultLen, Type *resultType, int *resultCount)=0 |
virtual const ErrType * | GetLastError ()=0 |
GetLastError Returns a per-point error. More... | |
virtual int | GetVersion () const |
Get the version number of this interface. More... | |
Protected Member Functions | |
RixTexture () | |
constructor for internal use only More... | |
Protected Attributes | |
int | m_version |
Version number of this interface. More... | |
RixTexture performs filtered texture map lookups using a texture coordinate and a region over which to filter.
This interface is ideally suited for use with path tracing.
The data pointers for input and results (including derivative results) should be interleaved.
This interface also provides the ability to obtain the derivatives at a given texture lookup, which is useful for bump mapping.
NOTE: Currently only FilterType::Bilinear and FilterType::Bspline supports the derivative capability.
enum RixTexture::ErrType |
|
inherited |
|
inlineprotected |
constructor for internal use only
|
pure virtual |
All texture access must acquire a texture first.
A non-zero return code means the texture specified by filename could not be acquired. NOTE: The filename string storage must be persistent. If it is not, the call will create a persistent string. If the filename is persistent ( e.g: from a GetToken() call), then true can be used to make this call more efficient. If atlasStyle is set to textureatlas then this function fills in txProperties for the entire atlas. The members that refer to a particular texture file in this case are retrieved from the first texture file in the atlas that the system encounters (and the system does not guarantee any order for the texture files in the atlas).
Referenced by RixIES::ReadIESProfile().
|
pure virtual |
Once a texture has been acquired, we can then acquire a part by part index, the partProperties will reflect the properties of the multi-part texture.
|
pure virtual |
GetLastError Returns a per-point error.
When calling Texture and TextureDerivatives, with a handle to a texture atlas, the returned error code only refers to the first error encountered and does not specify on which points the error occurred. In this case, it is possible to retrieve a per-point error code by making a call to GetLastError.
The error codes array is reset on every call to AcquireTexture (GetLastError will return a nullptr).
The function returns a pointer to internal memory that is guaranteed to be an array of size at least the number of points used in the last call to Texture or TextureDerivatives. The memory is only guaranteed to be valid until the next call to Texture, TextureDerivatives or AquireTexture.
Note that GetLastError will return nullptr:
|
pure virtual |
|
inlinevirtualinherited |
Get the version number of this interface.
Different interfaces might have different version numbers in a given release.
References RixInterface::m_version.
|
pure virtual |
Lookup filtered ptexture results over nPoints from a ptexture obtained with AcquireTexture().
The lookup point is provided by stIn. The radius of the texture filter at the lookup point is provided by uRadius and vRadius. The results are placed in result.
An optional runFlags array can be used to prevent lookups at a given point by setting the value of the flag at a given point to 0.
The call cannot be used to obtain s/t style texture results; the Texture() or TextureDerivatives() call must be used instead.
The result buffer should be preinitialized in case the call can write no valid data to it. A non-zero return code, specified by ErrType, is returned on some errors but not others; in particular, if an invalid face index is provided, the result buffer will remain untouched, but no error will be generated.
|
pure virtual |
Lookup filtered texture results over nPoints from a ptexture obtained with AcquireTexture().
The lookup point is provided by stIn. The derivatives of the texture results can be obtained by passing non-NULL pointers for dresultds and dresultdt. The result derivatives are computed via multiple texture lookups, so the additional cost can be significant, and is only incurred when non-NULL pointers are provided.
The filter radius is computed from the bi-variate derivatives provided by the caller.
An optional runFlags array can be used to prevent lookups at a given point by setting the value of the flag at a given point to 0.
The call cannot be used to obtain s/t style texture results; the Texture() or TextureDerivatives() call must be used instead.
The result buffer should be preinitialized in case the call can write no valid data to it. A non-zero return code, specified by ErrType, is returned on some errors but not others; in particular, if an invalid face index is provided, the result buffer will remain untouched, but no error will be generated.
|
pure virtual |
All texture access should release a texture as soon as it is finished looking up values.
Referenced by RixIES::ReadIESProfile().
|
pure virtual |
Lookup filtered texture results over nPoints from a texture obtained with AcquireTexture().
The lookup point is provided by stIn. The radius of the texture filter at the lookup point is provided by stRadius. The results are placed in result.
An optional runFlags array can be used to prevent lookups at a given point by setting the value of the flag at a given point to 0.
There are two overloads here. One accepts an RtFloat2 as the st coords and the other accepts an RtFloat3. Note that it is expected that the RtFloat3 version still only contains two floating point values for st that must be stored in the first and second element respectively.
A non-zero return code, specified by ErrType, is returned on error.
|
pure virtual |
|
pure virtual |
Read the whole texture into a buffer at a given MIP level.
The user of the API must provide the appropriately allocated buffer to place the results into.
Referenced by RixIES::ReadIESProfile().
|
pure virtual |
Lookup filtered texture results over nPoints from a texture obtained with AcquireTexture().
The lookup point is provided by stIn. The derivatives of the texture results can be obtained by passing non-NULL pointers for dresultds and dresultdt. The filter radius is computed from the bi-variate derivatives provided by the caller. (And then usually scaled by du/dv before being passed to this call).
An optional runFlags array can be used to prevent lookups at a given point by setting the value of the flag at a given point to 0.
There are two overloads here. One accepts an RtFloat2 as the st coords and the other accepts an RtFloat3. Note that it is expected that the RtFloat3 version still only contains two floating point values for st that must be stored in the first and second element respectively. A non-zero return code, specified by ErrType, is returned on error.
NOTE: Currently only the Bspline and Bilinear filters provide support for derivatives results.
|
pure virtual |
|
protectedinherited |
Version number of this interface.
Referenced by RixInterface::GetVersion().