RenderManAPI  24.0
Classes | Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
RixTexture Class Referenceabstract

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...
 

Detailed Description

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.

Member Enumeration Documentation

◆ ErrType

enum RixTexture::ErrType
Enumerator
Ok 
FileNotFound 
PartNotFound 
InvalidFaceIndex 
TextureAccessErr 
InvalidDerivatives 
InvalidFilter 
InvalidFile 

◆ TxAtlasStyle

enum RixTexture::TxAtlasStyle
Enumerator
AtlasNone 
AtlasUdim 
AtlasUvTile1 
AtlasUvTile0 

◆ Type

enum RixInterface::Type
inherited
Enumerator
k_Float 
k_Integer 
k_StringV 
k_Color 
k_Normal 
k_Vector 
k_Point 
k_HPoint 
k_MPoint 
k_Matrix 

Constructor & Destructor Documentation

◆ RixTexture()

RixTexture::RixTexture ( )
inlineprotected

constructor for internal use only

Member Function Documentation

◆ AcquireTexture()

virtual int RixTexture::AcquireTexture ( RtUString const  fileName,
TxAtlasStyle const  atlasStyle,
TxProperties &  txProperties 
)
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().

◆ AcquireTexturePart()

virtual int RixTexture::AcquireTexturePart ( int  partIndex,
TxProperties const &  txProperties,
TxProperties &  partProperties 
)
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.

◆ GetLastError()

virtual const ErrType* RixTexture::GetLastError ( )
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:

  • after any call to AcquireTexture
  • after a call to Texture and TextureDerivatives using a non-atlas texture handle
  • after any call to Ptexture and PtextureDerivatives

◆ GetProperty()

virtual int RixTexture::GetProperty ( TxProperties const &  txProperties,
RtUString const  propertyName,
void *  result,
int  resultLen,
Type *  resultType,
int *  resultCount 
)
pure virtual

◆ GetVersion()

virtual int RixInterface::GetVersion ( ) const
inlinevirtualinherited

Get the version number of this interface.

Different interfaces might have different version numbers in a given release.

References RixInterface::m_version.

◆ Ptexture()

virtual int RixTexture::Ptexture ( TxProperties const &  txProperties,
TxParams const &  txParams,
int  nPoints,
RtFloat2 const *  uv,
float const *  uWidth,
float const *  vWidth,
float *  result,
int *  runFlags = NULL 
)
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.

◆ PtextureDerivatives()

virtual int RixTexture::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 
)
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.

◆ ReleaseTexture()

virtual int RixTexture::ReleaseTexture ( TxProperties const &  txProperties)
pure virtual

All texture access should release a texture as soon as it is finished looking up values.

Referenced by RixIES::ReadIESProfile().

◆ Texture() [1/2]

virtual int RixTexture::Texture ( TxProperties const &  txProperties,
TxParams const &  txParams,
int  nPoints,
RtFloat2 const *  st,
float const *  stRadius,
float *  result,
int *  runFlags = NULL 
)
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.

◆ Texture() [2/2]

virtual int RixTexture::Texture ( TxProperties const &  txProperties,
TxParams const &  txParams,
int  nPoints,
RtFloat3 const *  st,
float const *  stRadius,
float *  result,
int *  runFlags = NULL 
)
pure virtual

◆ TextureData()

virtual int RixTexture::TextureData ( TxProperties const &  txProperties,
TxParams const &  txParams,
int  mipLevel,
int  cubeFace,
void *  result 
)
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().

◆ TextureDerivatives() [1/2]

virtual int RixTexture::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 
)
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.

◆ TextureDerivatives() [2/2]

virtual int RixTexture::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 
)
pure virtual

Member Data Documentation

◆ m_version

int RixInterface::m_version
protectedinherited

Version number of this interface.

Referenced by RixInterface::GetVersion().

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