Halide

A multidimensional domain over which to iterate. More...
#include <RDom.h>
Public Member Functions  
EXPORT  RDom () 
Construct an undefined reduction domain. More...  
EXPORT  RDom (Internal::ReductionDomain d) 
Construct a reduction domain that wraps an Internal ReductionDomain object. More...  
Internal::ReductionDomain  domain () const 
Get at the internal reduction domain object that this wraps. More...  
bool  defined () const 
Check if this reduction domain is nonnull. More...  
bool  same_as (const RDom &other) const 
Compare two reduction domains for equality of reference. More...  
EXPORT int  dimensions () const 
Get the dimensionality of a reduction domain. More...  
EXPORT RVar  operator[] (int) const 
Get at one of the dimensions of the reduction domain. More...  
EXPORT  operator RVar () const 
Singledimensional reduction domains can be used as RVars directly. More...  
EXPORT  operator Expr () const 
Singledimensional reduction domains can be also be used as Exprs directly. More...  
EXPORT void  where (Expr predicate) 
Add a predicate to the RDom. More...  
NO_INLINE  RDom (const std::vector< std::pair< Expr, Expr >> &ranges, std::string name="") 
Construct a multidimensional reduction domain with the given name. More...  
template<typename... Args>  
NO_INLINE  RDom (Expr min, Expr extent, Args &&...args) 
Construct a multidimensional reduction domain with the given name. More...  
EXPORT  RDom (const Buffer<> &) 
Construct a reduction domain that iterates over all points in a given Buffer or ImageParam. More...  
EXPORT  RDom (ImageParam) 
Construct a reduction domain that iterates over all points in a given Buffer or ImageParam. More...  
template<typename T >  
NO_INLINE  RDom (const Buffer< T > &im) 
Construct a reduction domain that iterates over all points in a given Buffer or ImageParam. More...  
Public Attributes  
RVar  x 
Direct access to the first four dimensions of the reduction domain. More...  
RVar  y 
Direct access to the first four dimensions of the reduction domain. More...  
RVar  z 
Direct access to the first four dimensions of the reduction domain. More...  
RVar  w 
Direct access to the first four dimensions of the reduction domain. More...  
A multidimensional domain over which to iterate.
Used when defining functions with update definitions.
An reduction is a function with a twopart definition. It has an initial value, which looks much like a pure function, and an update definition, which may refer to some RDom. Evaluating such a function first initializes it over the required domain (which is inferred based on usage), and then runs update rule for all points in the RDom. For example:
This function creates a singledimensional buffer of size 10, in which element x contains the value x*2. Internally, first the initialization rule fills in x at every site, and then the update definition doubles every site.
One use of reductions is to build a function recursively (pure functions in halide cannot be recursive). For example, this function fills in an array with the first 20 fibonacci numbers:
Another use of reductions is to perform scattering operations, as unlike a pure function declaration, the lefthandside of an update definition may contain general expressions:
An update definition may also be multidimensional. This example computes a summedarea table by first summing horizontally and then vertically:
You can also mix pure dimensions with reduction variables. In the previous example, note that there's no need for the y coordinate in sum_x to be traversed serially. The sum within each row is entirely independent. The rows could be computed in parallel, or in a different order, without changing the meaning. Therefore, we can instead write this definition as follows:
This lets us schedule it more flexibly. You can now parallelize the update step of sum_x over y by calling:
Note that calling sum_x.parallel(y) only parallelizes the initialization step, and not the update step! Scheduling the update step of a reduction must be done using the handle returned by Func::update(). This code parallelizes both the initialization step and the update step:
When you mix reduction variables and pure dimensions, the reduction domain is traversed outermost. That is, for each point in the reduction domain, the inferred pure domain is traversed in its entirety. For the above example, this means that sum_x walks down the columns, and sum_y walks along the rows. This may not be cachecoherent. You may try reordering these dimensions using the schedule, but Halide will return an error if it decides that this risks changing the meaning of your function. The solution lies in clever scheduling. If we say:
Then the sum in x is computed only as necessary for each scanline of the sum in y. This not only results in sum_x walking along the rows, it also improves the locality of the entire pipeline.

inline 
Construct a reduction domain that iterates over all points in a given Buffer or ImageParam.
Has the same dimensionality as the argument.
EXPORT Halide::RDom::RDom  (  ImageParam  ) 
Construct a reduction domain that iterates over all points in a given Buffer or ImageParam.
Has the same dimensionality as the argument.
Construct a reduction domain that iterates over all points in a given Buffer or ImageParam.
Has the same dimensionality as the argument.
EXPORT Halide::RDom::RDom  (  Internal::ReductionDomain  d  ) 
Construct a reduction domain that wraps an Internal ReductionDomain object.

inline 

inline 
Check if this reduction domain is nonnull.
Definition at line 229 of file RDom.h.
References Halide::Internal::ReductionDomain::defined().

inline 
Compare two reduction domains for equality of reference.
Definition at line 232 of file RDom.h.
References Halide::Internal::ReductionDomain::same_as().
EXPORT int Halide::RDom::dimensions  (  )  const 
Get the dimensionality of a reduction domain.
Get at one of the dimensions of the reduction domain.
Singledimensional reduction domains can be used as RVars directly.
Singledimensional reduction domains can be also be used as Exprs directly.
Add a predicate to the RDom.
An RDom may have multiple predicates associated with it. An update definition that uses an RDom only iterates over the subset points in the domain for which all of its predicates are true. The predicate expression obeys the same rules as the expressions used on the righthandside of the corresponding update definition. It may refer to the RDom's variables and free variables in the Func's update definition. It may include calls to other Funcs, or make recursive calls to the same Func. This permits iteration over nonrectangular domains, or domains with sizes that vary with some free variable, or domains with shapes determined by some other Func.
Note that once RDom is used in the update definition of some Func, no new predicates can be added to the RDom.
Consider a simple example:
This is equivalent to:
Where possible Halide restricts the range of the containing for loops to avoid the cases where the predicate is false so that the if statement can be removed entirely. The case above would be further simplified into:
In general, the predicates that we can simplify away by restricting loop ranges are inequalities that compare an inner Var or RVar to some expression in outer Vars or RVars.
You can also pack multiple conditions into one predicate like so:
RVar Halide::RDom::x 
Direct access to the first four dimensions of the reduction domain.
Some of these variables may be undefined if the reduction domain has fewer than four dimensions.
RVar Halide::RDom::y 
Direct access to the first four dimensions of the reduction domain.
Some of these variables may be undefined if the reduction domain has fewer than four dimensions.
RVar Halide::RDom::z 
RVar Halide::RDom::w 