RslArrayIter< T > Class Template Reference

#include <RslPlugin.h>

Public Member Functions
	RslArrayIter (const RslArg *arg)
	Construct an array iterator from an argument.
	RslArrayIter (const T *data, int length, const RslContext *ctx)
T &	operator[] (int x)
RslArrayIter< T > &	operator++ ()
RslArrayIter< T >	operator++ (int)
void	Reset (int index=0)
bool	IsVarying () const
int	GetLength () const
	Returns the array length.
int	GetCapacity () const
	Returns the array capacity.
int	GetStride () const
	Returns the array element stride.
template<>
RslArrayIter< RtMatrix > &	operator++ ()

Detailed Description

template<typename T>
class RslArrayIter< T >

An iterator for array arguments. The length of an array is always uniform, and it can be obtained either from the iterator or the RslArg.

We recommend indexing an array iterator using operator[] rather than dereferencing the iterator. Dereferencing the iterator returns a pointer to the first array element, and indexing errors can arise if that pointer is not declared with the correct type. Also in API version 6, the layout of array data in memory has been transposed for improved cache performance. To avoid runtime errors in existing code, the dereference operator for array iterators has been conditionally disabled. It can be re-enabled by defining the RSL_ALLOW_ARRAY_DEREF flag.

Here is an example that demonstrates how arrays are typically used. It is a plugin function that computes the average value in an array of colors. Note the colors might be varying, so a doubly nested loop is required.

RSLEXPORT 
int averageColor(RslContext* rslContext, int argc, const RslArg** argv) {
    assert(argv[0]->IsColor());
    assert(argv[1]->IsColor() && argv[1]->IsArray());
    RslColorIter result(argv[0]);
    RslColorArrayIter colors(argv[1]);
    int numColors = colors.GetLength();

    int n = argv[0]->NumValues();
    for (int i = 0; i < n; ++i) {
        RtColor avg = {0.0f, 0.0f, 0.0f};
        for (int j = 0; j < numColors; ++j) {
            // Note that we index the array iterator using operator[].
            RtColor& c = colors[j];
            avg[0] += c[0];
            avg[1] += c[1];
            avg[2] += c[2];
        }
        (*result)[0] = avg[0] / numColors;
        (*result)[1] = avg[1] / numColors;
        (*result)[2] = avg[2] / numColors;

        // Increment iterators
        ++result;
        ++colors;
    }
    return 0;
}

Constructor & Destructor Documentation

template<typename T>

RslArrayIter< T >::RslArrayIter ( const T *  data, int  length, const RslContext *  ctx  )

inline

Construct a uniform array iterator for user-provided data. This is useful for optional arguments with default values.

Member Function Documentation

template<typename T>

bool RslArrayIter< T >::IsVarying ( ) const

inline

Returns true if the iterator is varying. Note that uniform iterators need not be incremented (although it does no harm).

template<typename T>

RslArrayIter<T>& RslArrayIter< T >::operator++ ( )

inline

Increment this iterator to point to the next active point of the current array element. An internal acceleration structure makes this a constant-time operation.

template<typename T>

RslArrayIter<T> RslArrayIter< T >::operator++ ( int  )

inline

Post-increment this iterator. Returns a copy of the iterator prior to incrementing, so it's not terribly efficient. The dummy integer argument is the standard C++ way of distinguishing between pre- and post-increment operators.

template<typename T>

T& RslArrayIter< T >::operator[] ( int  x)

inline

The array index operator can be used to access individual array members.

template<typename T>

void RslArrayIter< T >::Reset ( int  index = 0)

inline

Reset the iterator to point at the first active point. By default reset the the first array element. Optionally reset to the first active point of a given array index.

---

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

• RslPlugin.h