Halide
Halide::ImageParam Class Reference

An Image parameter to a halide pipeline. More...

#include <ImageParam.h>

Inherits Halide::OutputImageParam.

Public Member Functions

 ImageParam ()=default
 Construct a nullptr image parameter handle. More...
 
 ImageParam (Type t, int d)
 Construct an image parameter of the given type and dimensionality, with an auto-generated unique name. More...
 
 ImageParam (Type t, int d, const std::string &n)
 Construct an image parameter of the given type and dimensionality, with the given name. More...
 
void set (const Buffer<> &im)
 Bind an Image to this ImageParam. More...
 
Buffer get () const
 Get a reference to the Buffer bound to this ImageParam. More...
 
void reset ()
 Unbind any bound Buffer. More...
 
template<typename... Args>
HALIDE_NO_USER_CODE_INLINE Expr operator() (Args &&... args) const
 Construct an expression which loads from this image parameter. More...
 
Expr operator() (std::vector< Expr >) const
 
Expr operator() (std::vector< Var >) const
 
 operator Func () const
 Return the intrinsic Func representation of this ImageParam. More...
 
Func in (const Func &f)
 Creates and returns a new Func that wraps this ImageParam. More...
 
Func in (const std::vector< Func > &fs)
 
Func in ()
 
void trace_loads ()
 Trace all loads from this ImageParam by emitting calls to halide_trace. More...
 
ImageParamadd_trace_tag (const std::string &trace_tag)
 Add a trace tag to this ImageParam's Func. More...
 
- Public Member Functions inherited from Halide::OutputImageParam
 OutputImageParam ()
 Construct a null image parameter handle. More...
 
const std::string & name () const
 Get the name of this Param. More...
 
Type type () const
 Get the type of the image data this Param refers to. More...
 
bool defined () const
 Is this parameter handle non-nullptr. More...
 
Internal::Dimension dim (int i)
 Get a handle on one of the dimensions for the purposes of inspecting or constraining its min, extent, or stride. More...
 
const Internal::Dimension dim (int i) const
 Get a handle on one of the dimensions for the purposes of inspecting its min, extent, or stride. More...
 
int host_alignment () const
 Get the alignment of the host pointer in bytes. More...
 
OutputImageParamset_host_alignment (int)
 Set the expected alignment of the host pointer in bytes. More...
 
int dimensions () const
 Get the dimensionality of this image parameter. More...
 
Expr left () const
 Get an expression giving the minimum coordinate in dimension 0, which by convention is the coordinate of the left edge of the image. More...
 
Expr right () const
 Get an expression giving the maximum coordinate in dimension 0, which by convention is the coordinate of the right edge of the image. More...
 
Expr top () const
 Get an expression giving the minimum coordinate in dimension 1, which by convention is the top of the image. More...
 
Expr bottom () const
 Get an expression giving the maximum coordinate in dimension 1, which by convention is the bottom of the image. More...
 
Expr width () const
 Get an expression giving the extent in dimension 0, which by convention is the width of the image. More...
 
Expr height () const
 Get an expression giving the extent in dimension 1, which by convention is the height of the image. More...
 
Expr channels () const
 Get an expression giving the extent in dimension 2, which by convention is the channel-count of the image. More...
 
Internal::Parameter parameter () const
 Get at the internal parameter object representing this ImageParam. More...
 
 operator Argument () const
 Construct the appropriate argument matching this parameter, for the purpose of generating the right type signature when statically compiling halide pipelines. More...
 
 operator ExternFuncArgument () const
 Using a param as the argument to an external stage treats it as an Expr. More...
 
OutputImageParamset_estimates (const Region &estimates)
 Set (min, extent) estimates for all dimensions in the ImageParam at once; this is equivalent to calling dim(n).set_estimate(min, extent) repeatedly, but slightly terser. More...
 

Additional Inherited Members

- Protected Member Functions inherited from Halide::OutputImageParam
void add_implicit_args_if_placeholder (std::vector< Expr > &args, Expr last_arg, int total_args, bool *placeholder_seen) const
 
 OutputImageParam (const Internal::Parameter &p, Argument::Kind k, Func f)
 Construct an OutputImageParam that wraps an Internal Parameter object. More...
 
- Protected Attributes inherited from Halide::OutputImageParam
Internal::Parameter param
 A reference-counted handle on the internal parameter object. More...
 
Argument::Kind kind
 Is this an input or an output? OutputImageParam is the base class for both. More...
 
Func func
 If Input: Func representation of the ImageParam. More...
 

Detailed Description

An Image parameter to a halide pipeline.

E.g., the input image.

Examples
tutorial/lesson_10_aot_compilation_generate.cpp, and tutorial/lesson_11_cross_compilation.cpp.

Definition at line 23 of file ImageParam.h.

Constructor & Destructor Documentation

◆ ImageParam() [1/3]

Halide::ImageParam::ImageParam ( )
default

Construct a nullptr image parameter handle.

◆ ImageParam() [2/3]

Halide::ImageParam::ImageParam ( Type  t,
int  d 
)

Construct an image parameter of the given type and dimensionality, with an auto-generated unique name.

◆ ImageParam() [3/3]

Halide::ImageParam::ImageParam ( Type  t,
int  d,
const std::string &  n 
)

Construct an image parameter of the given type and dimensionality, with the given name.

Member Function Documentation

◆ set()

void Halide::ImageParam::set ( const Buffer<> &  im)

Bind an Image to this ImageParam.

Only relevant for jitting

◆ get()

Buffer Halide::ImageParam::get ( ) const

Get a reference to the Buffer bound to this ImageParam.

Only relevant for jitting.

◆ reset()

void Halide::ImageParam::reset ( )

Unbind any bound Buffer.

◆ operator()() [1/3]

template<typename... Args>
HALIDE_NO_USER_CODE_INLINE Expr Halide::ImageParam::operator() ( Args &&...  args) const
inline

Construct an expression which loads from this image parameter.

The location is extended with enough implicit variables to match the dimensionality of the image (see Var::implicit)

Definition at line 67 of file ImageParam.h.

References Halide::OutputImageParam::func.

◆ operator()() [2/3]

Expr Halide::ImageParam::operator() ( std::vector< Expr ) const

◆ operator()() [3/3]

Expr Halide::ImageParam::operator() ( std::vector< Var ) const

◆ operator Func()

Halide::ImageParam::operator Func ( ) const

Return the intrinsic Func representation of this ImageParam.

This allows an ImageParam to be implicitly converted to a Func.

Note that we use implicit vars to name the dimensions of Funcs associated with the ImageParam: both its internal Func representation and wrappers (See ImageParam::in). For example, to unroll the first and second dimensions of the associated Func by a factor of 2, we would do the following:

func.unroll(_0, 2).unroll(_1, 2);

'_0' represents the first dimension of the Func, while _1 represents the second dimension of the Func.

◆ in() [1/3]

Func Halide::ImageParam::in ( const Func f)

Creates and returns a new Func that wraps this ImageParam.

During compilation, Halide will replace calls to this ImageParam with calls to the wrapper as appropriate. If this ImageParam is already wrapped for use in some Func, it will return the existing wrapper.

For example, img.in(g) would rewrite a pipeline like this:

ImageParam img(Int(32), 2);
Func g;
g(x, y) = ... img(x, y) ...

into a pipeline like this:

ImageParam img(Int(32), 2);
Func img_wrap, g;
img_wrap(x, y) = img(x, y);
g(x, y) = ... img_wrap(x, y) ...

This has a variety of uses. One use case is to stage loads from an ImageParam via some intermediate buffer (e.g. on the stack or in shared GPU memory).

The following example illustrates how you would use the 'in()' directive to stage loads from an ImageParam into the GPU shared memory:

ImageParam img(Int(32), 2);
output(x, y) = img(y, x);
Var tx, ty;
output.compute_root().gpu_tile(x, y, tx, ty, 8, 8);
img.in().compute_at(output, x).unroll(_0, 2).unroll(_1, 2).gpu_threads(_0, _1);

Note that we use implicit vars to name the dimensions of the wrapper Func. See Func::in for more possible use cases of the 'in()' directive.

◆ in() [2/3]

Func Halide::ImageParam::in ( const std::vector< Func > &  fs)

◆ in() [3/3]

Func Halide::ImageParam::in ( )

◆ trace_loads()

void Halide::ImageParam::trace_loads ( )

Trace all loads from this ImageParam by emitting calls to halide_trace.

◆ add_trace_tag()

ImageParam& Halide::ImageParam::add_trace_tag ( const std::string &  trace_tag)

Add a trace tag to this ImageParam's Func.


The documentation for this class was generated from the following file:
Halide::OutputImageParam::Func
friend class Func
Definition: OutputImageParam.h:21
Halide::OutputImageParam::func
Func func
If Input: Func representation of the ImageParam.
Definition: OutputImageParam.h:32
Halide::ImageParam::ImageParam
ImageParam()=default
Construct a nullptr image parameter handle.
Halide::Func::unroll
Func & unroll(const VarOrRVar &var)
Mark a dimension to be completely unrolled.
Halide::Int
Type Int(int bits, int lanes=1)
Constructing a signed integer type.
Definition: Type.h:472