Halide
ImageParam.h
Go to the documentation of this file.
1 #ifndef HALIDE_IMAGE_PARAM_H
2 #define HALIDE_IMAGE_PARAM_H
3 
4 /** \file
5  *
6  * Classes for declaring image parameters to halide pipelines
7  */
8 
9 #include <utility>
10 
11 #include "Func.h"
12 #include "OutputImageParam.h"
13 #include "Var.h"
14 
15 namespace Halide {
16 
17 namespace Internal {
18 template<typename T2>
19 class GeneratorInput_Buffer;
20 }
21 
22 /** An Image parameter to a halide pipeline. E.g., the input image. */
23 class ImageParam : public OutputImageParam {
24  template<typename T2>
25  friend class ::Halide::Internal::GeneratorInput_Buffer;
26 
27  // Only for use of Generator
29  : OutputImageParam(p, Argument::InputBuffer, std::move(f)) {
30  }
31 
32  /** Helper function to initialize the Func representation of this ImageParam. */
33  Func create_func() const;
34 
35 public:
36  /** Construct a nullptr image parameter handle. */
37  ImageParam() = default;
38 
39  /** Construct an image parameter of the given type and
40  * dimensionality, with an auto-generated unique name. */
41  ImageParam(Type t, int d);
42 
43  /** Construct an image parameter of the given type and
44  * dimensionality, with the given name */
45  ImageParam(Type t, int d, const std::string &n);
46 
47  /** Bind an Image to this ImageParam. Only relevant for jitting */
48  // @{
49  void set(const Buffer<> &im);
50  // @}
51 
52  /** Get a reference to the Buffer bound to this ImageParam. Only relevant for jitting. */
53  // @{
54  Buffer<> get() const;
55  // @}
56 
57  /** Unbind any bound Buffer */
58  void reset();
59 
60  /** Construct an expression which loads from this image
61  * parameter. The location is extended with enough implicit
62  * variables to match the dimensionality of the image
63  * (see \ref Var::implicit)
64  */
65  // @{
66  template<typename... Args>
67  HALIDE_NO_USER_CODE_INLINE Expr operator()(Args &&... args) const {
68  return func(std::forward<Args>(args)...);
69  }
70  Expr operator()(std::vector<Expr>) const;
71  Expr operator()(std::vector<Var>) const;
72  // @}
73 
74  /** Return the intrinsic Func representation of this ImageParam. This allows
75  * an ImageParam to be implicitly converted to a Func.
76  *
77  * Note that we use implicit vars to name the dimensions of Funcs associated
78  * with the ImageParam: both its internal Func representation and wrappers
79  * (See \ref ImageParam::in). For example, to unroll the first and second
80  * dimensions of the associated Func by a factor of 2, we would do the following:
81  \code
82  func.unroll(_0, 2).unroll(_1, 2);
83  \endcode
84  * '_0' represents the first dimension of the Func, while _1 represents the
85  * second dimension of the Func.
86  */
87  operator Func() const;
88 
89  /** Creates and returns a new Func that wraps this ImageParam. During
90  * compilation, Halide will replace calls to this ImageParam with calls
91  * to the wrapper as appropriate. If this ImageParam is already wrapped
92  * for use in some Func, it will return the existing wrapper.
93  *
94  * For example, img.in(g) would rewrite a pipeline like this:
95  \code
96  ImageParam img(Int(32), 2);
97  Func g;
98  g(x, y) = ... img(x, y) ...
99  \endcode
100  * into a pipeline like this:
101  \code
102  ImageParam img(Int(32), 2);
103  Func img_wrap, g;
104  img_wrap(x, y) = img(x, y);
105  g(x, y) = ... img_wrap(x, y) ...
106  \endcode
107  *
108  * This has a variety of uses. One use case is to stage loads from an
109  * ImageParam via some intermediate buffer (e.g. on the stack or in shared
110  * GPU memory).
111  *
112  * The following example illustrates how you would use the 'in()' directive
113  * to stage loads from an ImageParam into the GPU shared memory:
114  \code
115  ImageParam img(Int(32), 2);
116  output(x, y) = img(y, x);
117  Var tx, ty;
118  output.compute_root().gpu_tile(x, y, tx, ty, 8, 8);
119  img.in().compute_at(output, x).unroll(_0, 2).unroll(_1, 2).gpu_threads(_0, _1);
120  \endcode
121  *
122  * Note that we use implicit vars to name the dimensions of the wrapper Func.
123  * See \ref Func::in for more possible use cases of the 'in()' directive.
124  */
125  // @{
126  Func in(const Func &f);
127  Func in(const std::vector<Func> &fs);
128  Func in();
129  // @}
130 
131  /** Trace all loads from this ImageParam by emitting calls to halide_trace. */
132  void trace_loads();
133 
134  /** Add a trace tag to this ImageParam's Func. */
135  ImageParam &add_trace_tag(const std::string &trace_tag);
136 };
137 
138 } // namespace Halide
139 
140 #endif
Halide::ImageParam::operator()
HALIDE_NO_USER_CODE_INLINE Expr operator()(Args &&... args) const
Construct an expression which loads from this image parameter.
Definition: ImageParam.h:67
Halide::Internal::Parameter
A reference-counted handle to a parameter to a halide pipeline.
Definition: Parameter.h:28
Halide::OutputImageParam::Func
friend class Func
Definition: OutputImageParam.h:21
Halide::ImageParam::add_trace_tag
ImageParam & add_trace_tag(const std::string &trace_tag)
Add a trace tag to this ImageParam's Func.
Halide::OutputImageParam::func
Func func
If Input: Func representation of the ImageParam.
Definition: OutputImageParam.h:32
Halide::Argument
A struct representing an argument to a halide-generated function.
Definition: Argument.h:37
Halide::ImageParam
An Image parameter to a halide pipeline.
Definition: ImageParam.h:23
Halide::ImageParam::set
void set(const Buffer<> &im)
Bind an Image to this ImageParam.
Var.h
Halide::Type
Types in the halide type system.
Definition: Type.h:269
Halide
This file defines the class FunctionDAG, which is our representation of a Halide pipeline,...
Definition: AddAtomicMutex.h:21
Halide::LinkageType::Internal
@ Internal
Not visible externally, similar to 'static' linkage in C.
Func.h
Halide::Buffer<>
Halide::ImageParam::reset
void reset()
Unbind any bound Buffer.
Halide::ImageParam::in
Func in()
Halide::ImageParam::ImageParam
ImageParam()=default
Construct a nullptr image parameter handle.
Halide::OutputImageParam
A handle on the output buffer of a pipeline.
Definition: OutputImageParam.h:19
Halide::ImageParam::trace_loads
void trace_loads()
Trace all loads from this ImageParam by emitting calls to halide_trace.
Halide::Func
A halide function.
Definition: Func.h:667
HALIDE_NO_USER_CODE_INLINE
#define HALIDE_NO_USER_CODE_INLINE
Definition: Util.h:44
Halide::ImageParam::get
Buffer get() const
Get a reference to the Buffer bound to this ImageParam.
Halide::Expr
A fragment of Halide syntax.
Definition: Expr.h:256
OutputImageParam.h