#include <RixInterfaces.h>

Inheritance diagram for RixTexture:

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 }

Public Types inherited from RixInterface
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

virtual int	AcquireTexturePart (int partIndex, TxProperties const &txProperties, TxProperties &partProperties)=0

virtual int	ReleaseTexture (TxProperties const &txProperties)=0

virtual int	Texture (TxProperties const &txProperties, TxParams const &txParams, int nPoints, RtFloat2 const st, float const stRadius, float result, int runFlags=NULL)=0

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

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

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

virtual int	TextureData (TxProperties const &txProperties, TxParams const &txParams, int mipLevel, int cubeFace, void *result)=0

virtual int	GetProperty (TxProperties const &txProperties, RtUString const propertyName, void result, int resultLen, Type resultType, int *resultCount)=0

virtual const ErrType *	GetLastError ()=0

Public Member Functions inherited from RixInterface
virtual int	GetVersion () const

Protected Member Functions
	RixTexture ()
	constructor for internal use only More...

Protected Member Functions inherited from RixInterface
	RixInterface (int version)
	Interfaces should not be constructed by users. More...

virtual	~RixInterface ()
	Interfaces should not be deleted by users. More...

Additional Inherited Members
Protected Attributes inherited from RixInterface
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.

Definition at line 287 of file RixInterfaces.h.

Member Enumeration Documentation

◆ ErrType

enum RixTexture::ErrType

Enumerator
Ok
FileNotFound
PartNotFound
InvalidFaceIndex
TextureAccessErr
InvalidDerivatives
InvalidFilter
InvalidFile

Definition at line 290 of file RixInterfaces.h.

◆ TxAtlasStyle

enum RixTexture::TxAtlasStyle

Enumerator
AtlasNone
AtlasUdim
AtlasUvTile1
AtlasUvTile0

Definition at line 347 of file RixInterfaces.h.

Constructor & Destructor Documentation

◆ RixTexture()

RixTexture::RixTexture ( )

inlineprotected

constructor for internal use only

Definition at line 625 of file RixInterfaces.h.

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

◆ 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

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

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

◆ 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

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

E:/include/RixInterfaces.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ErrType

◆ TxAtlasStyle

Constructor & Destructor Documentation

◆ RixTexture()

Member Function Documentation

◆ AcquireTexture()

◆ AcquireTexturePart()

◆ GetLastError()

◆ GetProperty()

◆ Ptexture()

◆ PtextureDerivatives()

◆ ReleaseTexture()

◆ Texture() [1/2]

◆ Texture() [2/2]

◆ TextureData()

◆ TextureDerivatives() [1/2]

◆ TextureDerivatives() [2/2]