Halide
Halide::BoundaryConditions Namespace Reference

namespace to hold functions for imposing boundary conditions on Halide Funcs. More...

Namespaces

 Internal
 

Functions

EXPORT Func constant_exterior (const Func &source, Tuple value, const std::vector< std::pair< Expr, Expr >> &bounds)
 Impose a boundary condition such that a given expression is returned everywhere outside the boundary. More...
 
EXPORT Func constant_exterior (const Func &source, Expr value, const std::vector< std::pair< Expr, Expr >> &bounds)
 Impose a boundary condition such that a given expression is returned everywhere outside the boundary. More...
 
template<typename T >
NO_INLINE Func constant_exterior (const T &func_like, Tuple value)
 Impose a boundary condition such that a given expression is returned everywhere outside the boundary. More...
 
template<typename T >
NO_INLINE Func constant_exterior (const T &func_like, Expr value)
 Impose a boundary condition such that a given expression is returned everywhere outside the boundary. More...
 
template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func constant_exterior (const T &func_like, Tuple value, Bounds &&... bounds)
 Impose a boundary condition such that a given expression is returned everywhere outside the boundary. More...
 
template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func constant_exterior (const T &func_like, Expr value, Bounds &&... bounds)
 Impose a boundary condition such that a given expression is returned everywhere outside the boundary. More...
 
EXPORT Func repeat_edge (const Func &source, const std::vector< std::pair< Expr, Expr >> &bounds)
 Impose a boundary condition such that the nearest edge sample is returned everywhere outside the given region. More...
 
template<typename T >
NO_INLINE Func repeat_edge (const T &func_like)
 Impose a boundary condition such that the nearest edge sample is returned everywhere outside the given region. More...
 
template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func repeat_edge (const T &func_like, Bounds &&... bounds)
 Impose a boundary condition such that the nearest edge sample is returned everywhere outside the given region. More...
 
EXPORT Func repeat_image (const Func &source, const std::vector< std::pair< Expr, Expr >> &bounds)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other. More...
 
template<typename T >
NO_INLINE Func repeat_image (const T &func_like)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other. More...
 
template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func repeat_image (const T &func_like, Bounds &&... bounds)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other. More...
 
EXPORT Func mirror_image (const Func &source, const std::vector< std::pair< Expr, Expr >> &bounds)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other, but mirror them such that adjacent edges are the same. More...
 
template<typename T >
NO_INLINE Func mirror_image (const T &func_like)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other. More...
 
template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func mirror_image (const T &func_like, Bounds &&... bounds)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other. More...
 
EXPORT Func mirror_interior (const Func &source, const std::vector< std::pair< Expr, Expr >> &bounds)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other, but mirror them such that adjacent edges are the same and then overlap the edges. More...
 
template<typename T >
NO_INLINE Func mirror_interior (const T &func_like)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other, but mirror them such that adjacent edges are the same and then overlap the edges. More...
 
template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func mirror_interior (const T &func_like, Bounds &&... bounds)
 Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other, but mirror them such that adjacent edges are the same and then overlap the edges. More...
 

Detailed Description

namespace to hold functions for imposing boundary conditions on Halide Funcs.

All functions in this namespace transform a source Func to a result Func where the result produces the values of the source within a given region and a different set of values outside the given region. A region is an N dimensional box specified by mins and extents.

Three areas are defined: The image is the entire set of values in the region. The edge is the set of pixels in the image but adjacent to coordinates that are not The interior is the image minus the edge (and is undefined if the extent of any region is 1 or less).

If the source Func has more dimensions than are specified, the extra ones are unmodified. Additionally, passing an undefined (default constructed) 'Expr' for the min and extent of a dimension will keep that dimension unmodified.

Numerous options for specifing the outside area are provided, including replacement with an expression, repeating the edge samples, mirroring over the edge, and repeating or mirroring the entire image.

Using these functions to express your boundary conditions is highly recommended for correctness and performance. Some of these are hard to get right. The versions here are both understood by bounds inference, and also judiciously use the 'likely' intrinsic to minimize runtime overhead.

Function Documentation

◆ constant_exterior() [1/6]

EXPORT Func Halide::BoundaryConditions::constant_exterior ( const Func source,
Tuple  value,
const std::vector< std::pair< Expr, Expr >> &  bounds 
)

Impose a boundary condition such that a given expression is returned everywhere outside the boundary.

Generally the expression will be a constant, though the code currently allows accessing the arguments of source.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object. Note that objects are taken by mutable ref. Pipelines capture Buffers via mutable refs, because running a pipeline might alter the Buffer metadata (e.g. device allocation state).

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_BORDER and putting value in the border of the texture.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Referenced by constant_exterior(), and Halide::BoundaryConditions::Internal::func_like_to_func().

◆ constant_exterior() [2/6]

EXPORT Func Halide::BoundaryConditions::constant_exterior ( const Func source,
Expr  value,
const std::vector< std::pair< Expr, Expr >> &  bounds 
)

Impose a boundary condition such that a given expression is returned everywhere outside the boundary.

Generally the expression will be a constant, though the code currently allows accessing the arguments of source.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object. Note that objects are taken by mutable ref. Pipelines capture Buffers via mutable refs, because running a pipeline might alter the Buffer metadata (e.g. device allocation state).

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_BORDER and putting value in the border of the texture.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

◆ constant_exterior() [3/6]

template<typename T >
NO_INLINE Func Halide::BoundaryConditions::constant_exterior ( const T &  func_like,
Tuple  value 
)
inline

Impose a boundary condition such that a given expression is returned everywhere outside the boundary.

Generally the expression will be a constant, though the code currently allows accessing the arguments of source.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object. Note that objects are taken by mutable ref. Pipelines capture Buffers via mutable refs, because running a pipeline might alter the Buffer metadata (e.g. device allocation state).

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_BORDER and putting value in the border of the texture.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 90 of file BoundaryConditions.h.

References constant_exterior(), and Halide::BoundaryConditions::Internal::func_like_to_func().

◆ constant_exterior() [4/6]

template<typename T >
NO_INLINE Func Halide::BoundaryConditions::constant_exterior ( const T &  func_like,
Expr  value 
)
inline

Impose a boundary condition such that a given expression is returned everywhere outside the boundary.

Generally the expression will be a constant, though the code currently allows accessing the arguments of source.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object. Note that objects are taken by mutable ref. Pipelines capture Buffers via mutable refs, because running a pipeline might alter the Buffer metadata (e.g. device allocation state).

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_BORDER and putting value in the border of the texture.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 99 of file BoundaryConditions.h.

References constant_exterior().

◆ constant_exterior() [5/6]

template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func Halide::BoundaryConditions::constant_exterior ( const T &  func_like,
Tuple  value,
Bounds &&...  bounds 
)
inline

Impose a boundary condition such that a given expression is returned everywhere outside the boundary.

Generally the expression will be a constant, though the code currently allows accessing the arguments of source.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object. Note that objects are taken by mutable ref. Pipelines capture Buffers via mutable refs, because running a pipeline might alter the Buffer metadata (e.g. device allocation state).

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_BORDER and putting value in the border of the texture.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 105 of file BoundaryConditions.h.

References Halide::Internal::collect_paired_args(), constant_exterior(), and Halide::BoundaryConditions::Internal::func_like_to_func().

◆ constant_exterior() [6/6]

template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func Halide::BoundaryConditions::constant_exterior ( const T &  func_like,
Expr  value,
Bounds &&...  bounds 
)
inline

Impose a boundary condition such that a given expression is returned everywhere outside the boundary.

Generally the expression will be a constant, though the code currently allows accessing the arguments of source.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object. Note that objects are taken by mutable ref. Pipelines capture Buffers via mutable refs, because running a pipeline might alter the Buffer metadata (e.g. device allocation state).

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_BORDER and putting value in the border of the texture.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 113 of file BoundaryConditions.h.

References constant_exterior(), EXPORT, and repeat_edge().

◆ repeat_edge() [1/3]

EXPORT Func Halide::BoundaryConditions::repeat_edge ( const Func source,
const std::vector< std::pair< Expr, Expr >> &  bounds 
)

Impose a boundary condition such that the nearest edge sample is returned everywhere outside the given region.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_EDGE.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Examples:
tutorial/lesson_09_update_definitions.cpp.

Referenced by constant_exterior(), and repeat_edge().

◆ repeat_edge() [2/3]

template<typename T >
NO_INLINE Func Halide::BoundaryConditions::repeat_edge ( const T &  func_like)
inline

Impose a boundary condition such that the nearest edge sample is returned everywhere outside the given region.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_EDGE.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 136 of file BoundaryConditions.h.

References Halide::BoundaryConditions::Internal::func_like_to_func(), and repeat_edge().

◆ repeat_edge() [3/3]

template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func Halide::BoundaryConditions::repeat_edge ( const T &  func_like,
Bounds &&...  bounds 
)
inline

Impose a boundary condition such that the nearest edge sample is returned everywhere outside the given region.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_CLAMP_TO_EDGE.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 148 of file BoundaryConditions.h.

References Halide::Internal::collect_paired_args(), EXPORT, Halide::BoundaryConditions::Internal::func_like_to_func(), repeat_edge(), and repeat_image().

◆ repeat_image() [1/3]

EXPORT Func Halide::BoundaryConditions::repeat_image ( const Func source,
const std::vector< std::pair< Expr, Expr >> &  bounds 
)

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_REPEAT.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Referenced by repeat_edge(), and repeat_image().

◆ repeat_image() [2/3]

template<typename T >
NO_INLINE Func Halide::BoundaryConditions::repeat_image ( const T &  func_like)
inline

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_REPEAT.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 172 of file BoundaryConditions.h.

References Halide::BoundaryConditions::Internal::func_like_to_func(), and repeat_image().

◆ repeat_image() [3/3]

template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func Halide::BoundaryConditions::repeat_image ( const T &  func_like,
Bounds &&...  bounds 
)
inline

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_REPEAT.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 183 of file BoundaryConditions.h.

References Halide::Internal::collect_paired_args(), EXPORT, Halide::BoundaryConditions::Internal::func_like_to_func(), mirror_image(), and repeat_image().

◆ mirror_image() [1/3]

EXPORT Func Halide::BoundaryConditions::mirror_image ( const Func source,
const std::vector< std::pair< Expr, Expr >> &  bounds 
)

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other, but mirror them such that adjacent edges are the same.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_MIRRORED_REPEAT.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Referenced by mirror_image(), and repeat_image().

◆ mirror_image() [2/3]

template<typename T >
NO_INLINE Func Halide::BoundaryConditions::mirror_image ( const T &  func_like)
inline

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_REPEAT.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 207 of file BoundaryConditions.h.

References Halide::BoundaryConditions::Internal::func_like_to_func(), and mirror_image().

◆ mirror_image() [3/3]

template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func Halide::BoundaryConditions::mirror_image ( const T &  func_like,
Bounds &&...  bounds 
)
inline

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other.

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(This is similar to setting GL_TEXTURE_WRAP_* to GL_REPEAT.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 218 of file BoundaryConditions.h.

References Halide::Internal::collect_paired_args(), EXPORT, Halide::BoundaryConditions::Internal::func_like_to_func(), mirror_image(), and mirror_interior().

◆ mirror_interior() [1/3]

EXPORT Func Halide::BoundaryConditions::mirror_interior ( const Func source,
const std::vector< std::pair< Expr, Expr >> &  bounds 
)

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other, but mirror them such that adjacent edges are the same and then overlap the edges.

This produces an error if any extent is 1 or less. (TODO: check this.)

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(I do not believe there is a direct GL_TEXTURE_WRAP_* equivalent for this.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Referenced by mirror_image(), and mirror_interior().

◆ mirror_interior() [2/3]

template<typename T >
NO_INLINE Func Halide::BoundaryConditions::mirror_interior ( const T &  func_like)
inline

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other, but mirror them such that adjacent edges are the same and then overlap the edges.

This produces an error if any extent is 1 or less. (TODO: check this.)

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(I do not believe there is a direct GL_TEXTURE_WRAP_* equivalent for this.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 245 of file BoundaryConditions.h.

References Halide::BoundaryConditions::Internal::func_like_to_func(), and mirror_interior().

◆ mirror_interior() [3/3]

template<typename T , typename ... Bounds, typename std::enable_if< Halide::Internal::all_are_convertible< Expr, Bounds... >::value >::type * = nullptr>
NO_INLINE Func Halide::BoundaryConditions::mirror_interior ( const T &  func_like,
Bounds &&...  bounds 
)
inline

Impose a boundary condition such that the entire coordinate space is tiled with copies of the image abutted against each other, but mirror them such that adjacent edges are the same and then overlap the edges.

This produces an error if any extent is 1 or less. (TODO: check this.)

An ImageParam, Buffer<T>, or similar can be passed instead of a Func. If this is done and no bounds are given, the boundaries will be taken from the min and extent methods of the passed object.

(I do not believe there is a direct GL_TEXTURE_WRAP_* equivalent for this.)

You may pass undefined Exprs for dimensions that you do not wish to bound.

Definition at line 256 of file BoundaryConditions.h.

References Halide::Internal::collect_paired_args(), Halide::BoundaryConditions::Internal::func_like_to_func(), and mirror_interior().