blob: f48604d4db37659fdb3467648afa4b29aa201886 [file] [log] [blame]
<!-- imageMipmapFunctionsInc -->
<bridgehead>Mipmap read image functions:</bridgehead>
<para>
For the forms that take an <type>image1d_t</type> object,
use the coordinate <emphasis>coord</emphasis> to
do an element lookup in the mip-level specified by
<varname>lod</varname> in the 1D image object specified
by <varname>image</varname>.
</para>
<para>
For the forms that use gradients, use the gradients to compute
the lod and coordinate <emphasis>coord</emphasis> to do an
element lookup in
the mip-level specified by the computed lod in
the 1D image object specified by <varname>image</varname>.
</para>
<para>
For the forms that take an <type>image1d_array_t</type> object,
use the coordinate <emphasis>coord.x</emphasis> to
do an element lookup in the 1D image identified by
<emphasis>coord.x</emphasis> and mip-level specified by
<varname>lod</varname> in the 1D image object specified
by <varname>image</varname>.
</para>
<para>
When a multisample image is accessed in a kernel,
the access takes one vector of
integers describing which pixel to fetch and an
integer corresponding to the sample numbers
describing which sample within the pixel to fetch.
sample identifies the sample position in the
multi-sample image.
</para>
<para>
For best performance, we recommend that <varname>sample</varname>
be a literal value so it is known at
compile time and the OpenCL compiler can perform appropriate
optimizationsfor multisample reads on the device.
</para>
<para>
NOTE: <constant>CL_SAMPLER_NORMALIZED_COORDS</constant>
must be <constant>CL_TRUE</constant> for built-in functions
described in the table above that read from a
mip-mapped image; otherwise the behavior is
undefined. The value specified in the
<varname>lod</varname> argument is clamped to the minimum of (actual
number of mip-levels - 1) in the image or value
specified for <constant>CL_SAMPLER_LOD_MAX_KHR</constant>.
</para>
<!-- 4-Nov-2015, API ver 2.1 rev 19; Ext ver 2.1 rev 10 -->