blob: 6ef283454e4ce03d665daf49c7cb055eb3f8c66c [file] [log] [blame]
<bridgehead>Mapping image channels to color values</bridgehead>
<para>
<!-- section 6.13.14.7 --> The following table describes the mapping
of the number of channels of an image element to the appropriate components in the
<type>float4</type>, <type>int4</type> or <type>uint4</type> vector data type for
the color values returned by <function>read_image{f|i|ui}</function> or supplied
to <function>write_image{f|i|ui}</function>. The unmapped components will be set
to <constant>0.0</constant> for red, green and blue channels and will be set to
<constant>1.0</constant> for the alpha channel.
</para>
<para>
<informaltable frame="all">
<tgroup cols="2" align="center" colsep="1" rowsep="1">
<colspec colname="col1" colnum="1" />
<colspec colname="col2" colnum="2" />
<thead>
<row>
<entry>Channel Order</entry>
<entry><type>float4</type>, <type>int4</type> or <type>uint4</type> components of channel data</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>CL_R</constant>, <constant>CL_Rx</constant></entry>
<entry><constant>(r, 0.0, 0.0, 1.0)</constant></entry>
</row>
<row>
<entry><constant>CL_A</constant></entry>
<entry><constant>(0.0, 0.0, 0.0, a)</constant></entry>
</row>
<row>
<entry><constant>CL_RG</constant>, <constant>CL_RGx</constant></entry>
<entry><constant>(r, g, 0.0, 1.0)</constant></entry>
</row>
<row>
<entry><constant>CL_RA</constant></entry>
<entry><constant>(r, 0.0, 0.0, a)</constant></entry>
</row>
<row>
<entry>
<constant>CL_RGB</constant>,
<constant>CL_RGBx</constant>,
<constant>CL_sRGB</constant>,
<constant>CL_sRGBx</constant>
</entry>
<entry><constant>(r, g, b, 1.0)</constant></entry>
</row>
<row>
<entry><constant>CL_RGBA, CL_BGRA, CL_ARGB, CL_ABGR, CL_sRGBA, CL_sBGRA</constant></entry>
<entry><constant>(r, g, b, a)</constant></entry>
</row>
<row>
<entry><constant>CL_INTENSITY</constant></entry>
<entry><constant>(I, I, I, I)</constant></entry>
</row>
<row>
<entry><constant>CL_LUMINANCE</constant></entry>
<entry><constant>(L, L, L, 1.0)</constant></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
For <constant>CL_DEPTH</constant> images, a scalar value is
returned by <function>read_imagef</function> or supplied to
<function>write_imagef</function>.
</para>
<para>
A kernel that uses a sampler with the <constant>CL_ADDRESS_CLAMP</constant> addressing
mode with multiple images may result in additional samplers being used internally
by an implementation. If the same sampler is used with multiple images called via
<function>read_image{f|i|ui}</function>, then it is possible that an implementation may
need to allocate an additional sampler to handle the different border color values that
may be needed depending on the image formats being used. These implementation allocated
samplers will count against the maximum sampler values supported by the device and given by
<constant>CL_DEVICE_MAX_SAMPLERS</constant>. Enqueuing a kernel that requires more samplers
than the implementation can support will result in a <constant>CL_OUT_OF_RESOURCES</constant>
error being returned.
</para>
<para>
<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>
<!-- 17-Dec-2013, rev. 19 -->