RslArg Class Reference

An array of RslArg pointers is passed to the RSL plugin function. More...

#include <RslPlugin.h>

Inherits RslArg_v3.

List of all members.

Public Member Functions
virtual bool	IsStruct () const =0
	Returns true if this argument is a struct (or struct array).
virtual const char *	GetName () const =0
	Get the name of this argument, which is not guaranteed to be sensible.
virtual bool	IsResizable () const =0
	Returns true if this argument is a resizable array.
virtual class RslResizer *	GetResizer () const =0
	Get resizer for this argument (returns NULL if not resizable).
virtual	~RslArg ()
	Virtual destructor.
virtual bool	IsNormal () const =0
	Returns true if this argument is a normal (or normal array).
virtual bool	IsWriteable () const =0
	Returns true if this argument is writeable.
virtual bool	IsFloat () const =0
	Returns true if this argument is a float (or float array).
virtual bool	IsPoint () const =0
	Returns true if this argument is a point (or point array).
virtual bool	IsVector () const =0
	Returns true if this argument is a vector (or vector array).
virtual bool	IsColor () const =0
	Returns true if this argument is a color (or color array).
virtual bool	IsString () const =0
	Returns true if this argument is a string (or string array).
virtual bool	IsMatrix () const =0
	Returns true if this argument is a matrix (or matrix array).
virtual bool	IsArray () const =0
	Returns true if this argument is an array.
virtual bool	IsVarying () const =0
	Returns true if this argument is varying.
virtual int	GetArrayLength () const =0
	Get the length of an array argument.
virtual unsigned int	NumValues () const =0
	Get the number of values for this argument.
virtual void	GetData (float **data, int *stride) const =0
	Get the raw data pointer for this argument from the given context, along with the stride, which specifies how much to increment the pointer on each iteration.
Static Public Member Functions
static unsigned int	NumValues (int argc, const class RslArg **argv)
	Get the maximum number of values for the given arguments.
Friends
class	RslStruct
class	RslStructArray
class	RslArrayIter

---

Detailed Description

An array of RslArg pointers is passed to the RSL plugin function.

The result parameter is always the zeroth argument (even in a void function).

Various methods can be used to query the type of an RslArg (e.g. IsFloat(), IsArray()), its detail (IsVarying()), and other information (GetArrayLength(), IsWriteable()).

An iterator (RslIter) must be constructed to access the data represented by an RslArg. The type of iterator depends on the underlying data type. For example:

       assert(argv[0].IsFloat());
       assert(argv[1].IsArray() && argv[1].IsColor());
       RslFloatIter num(argv[0]);
       RslColorArrayIter colors(argv[1]);

If an argument might be varying, the NumValues() method is used to determine the number of iterations required to process it. Any arguments that are varying require the same number of iterations. If the function returns a result (i.e. does not have a void return type), the shader compiler guarantees that the result argument (argv[0]) is varying whenever any of the other arguments are varying. It's usually sufficient to use "argv[0]->NumValues()" as the required number of iterations. For example:

        int n = argv[0]->NumValues();
        for (int i = 0; i < n; ++i) {
            *a = *b + *c;
            ++a; ++b; ++c;
        }

Void plugin functions must take the detail of all the arguments into account, however:

       int n = RslArg::NumValues(argc, argv);

Note that incrementing an iterator for a uniform argument has no effect. Also, the number of iterations might be one if all the arguments are uniform. In our experience, it is usually not worth optimizing for such cases. If performance is a concern, overloading can be used to define a specialized plugin function that operates on all uniform arguments. (Beware: the uniform function prototype should follow the varying one in the RslFunctionTable, because overloading resolution prevers the "most recent" function when more than one candidate matches.)

---

Constructor & Destructor Documentation

virtual RslArg::~RslArg (   )  [inline, virtual]

Virtual destructor.

---

Member Function Documentation

virtual int RslArg_v2::GetArrayLength (   )  const [pure virtual, inherited]

Get the length of an array argument. The result is undefined if this argument is not an array (call IsArray() first).

virtual void RslArg_v2::GetData (  float **  data, int *  stride )  const [pure virtual, inherited]

Get the raw data pointer for this argument from the given context, along with the stride, which specifies how much to increment the pointer on each iteration. (The stride is zero if the argument is uniform.) Use with caution! Do not read or modify values for inactive points. Use RslContext::GetRunflags to determine which points are active.

virtual const char* RslArg::GetName (   )  const [pure virtual]

Get the name of this argument, which is not guaranteed to be sensible. Useful for error messages and struct member handling.

virtual class RslResizer* RslArg::GetResizer (   )  const [pure virtual]

Get resizer for this argument (returns NULL if not resizable).

virtual bool RslArg_v2::IsArray (   )  const [pure virtual, inherited]

Returns true if this argument is an array.

virtual bool RslArg_v2::IsColor (   )  const [pure virtual, inherited]

Returns true if this argument is a color (or color array).

virtual bool RslArg_v2::IsFloat (   )  const [pure virtual, inherited]

Returns true if this argument is a float (or float array).

virtual bool RslArg_v2::IsMatrix (   )  const [pure virtual, inherited]

Returns true if this argument is a matrix (or matrix array).

virtual bool RslArg_v3::IsNormal (   )  const [pure virtual, inherited]

Returns true if this argument is a normal (or normal array).

virtual bool RslArg_v2::IsPoint (   )  const [pure virtual, inherited]

Returns true if this argument is a point (or point array).

virtual bool RslArg::IsResizable (   )  const [pure virtual]

Returns true if this argument is a resizable array.

virtual bool RslArg_v2::IsString (   )  const [pure virtual, inherited]

Returns true if this argument is a string (or string array).

virtual bool RslArg::IsStruct (   )  const [pure virtual]

Returns true if this argument is a struct (or struct array).

virtual bool RslArg_v2::IsVarying (   )  const [pure virtual, inherited]

Returns true if this argument is varying.

virtual bool RslArg_v2::IsVector (   )  const [pure virtual, inherited]

Returns true if this argument is a vector (or vector array).

virtual bool RslArg_v3::IsWriteable (   )  const [pure virtual, inherited]

Returns true if this argument is writeable. This is useful in varargs plugin functions to verify that output arguments are valid. An argument is writeable if it's a local variable, a shader output parameter, or a global variable (e.g. P, N).

static unsigned int RslArg_v2::NumValues (  int  argc, const class RslArg **  argv )  [static, inherited]

Get the maximum number of values for the given arguments. This method should be used to determine the number of iterations when a plugin function returns values via output arguments.

virtual unsigned int RslArg_v2::NumValues (   )  const [pure virtual, inherited]

Get the number of values for this argument. Returns 1 if the argument is uniform. Otherwise it returns the number of points in the context.

---

Friends And Related Function Documentation

friend class RslArrayIter [friend]

Reimplemented from RslArg_v2.

friend class RslStruct [friend]

friend class RslStructArray [friend]

---

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

• RslPlugin.h