<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- saved from url=(0013)about:internet -->
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" xmlns:xlink="http://www.w3.org/1999/xlink" pref:renderer="mathplayer-dl">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <style xmlns="" type="text/css">
    /* This style sets a margin around the entire page */
        html, body {
            margin: 10px;
        }

        p {
            font: normal 16px verdana, sans-serif;
            margin: 0;
            padding-bottom:12px;
        }

        h1 {
            font: bold 25px verdana, sans-serif;
            margin-top: 0;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        h2 {
            font: bold 19px verdana, sans-serif;
            margin-top: 28px;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        h3 {
            font: bold 19px verdana, sans-serif !important;
            margin-top: 28px;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        li {
            font: normal 16px verdana, sans-serif;
            margin-top: 0;
            margin-bottom: 18px;
            padding-top: 0;
            padding-bottom: 0;
        }

        .pdparam {
            font: italic 16px verdana, sans-serif;
        }

                .term {
                        font: italic 16px verdana, sans-serif;
                        font-weight: normal;
                }

                .type {
                        font: normal 16px verdana, sans-serif !important;
                }

                .parameter {
                        font-style: italic;
                        }

        a:link, a:visited {
            color: blue;
            text-decoration: none;
            font: normal 16px;
        }

        a:hover {
            background-color: #FFFF99;
            font: normal 16px;
        }

        div.funcsynopsis {
            text-align: left;
            background-color: #e6e6e6;
            font: normal 16px verdana, sans-serif;
                        padding-top: 10px;
                        padding-bottom: 10px;
        }

        div.funcsynopsis table {
            border-collapse: separate;
            font: normal 16px verdana, sans-serif;
        }

        div.funcsynopsis td {
            background-color: #e6e6e6;
            border: 0 solid #000;
            padding: 1px;
            font: normal 16px verdana, sans-serif;
        }

        div.refsect1 {
            font-family: verdana, sans-serif;
            font-size: 16px;
        }

        code.constant {
            font: normal 16px courier new, monospace !important;
        }

                span.errorname {
            font: normal 16px verdana, sans-serif !important;
        }

        code.function {
            font: bold 16px verdana, sans-serif !important;
        }

        b.fsfunc {
            font: bold 16px verdana, sans-serif !important;
        }

        code.varname {
            font: italic 16px verdana, sans-serif;
        }

        code.replaceable {
            font: italic 16px courier new, monospace;
        }

        code.funcdef {
            font: normal 16px verdana, sans-serif !important;
        }

        .citerefentry {
            font: normal 16px verdana, sans-serif !important;
        }

        .parameter {
            font-style: italic;
        }

        code.fsfunc {
            font: normal 16px verdana, sans-serif !important;
        }

        /* PARAMETER: This style controls spacing between the terms in Parameter section */
        dt {
            margin-top: 15px;
        }

        /* TABLES: These styles apply to all tables OTHER than the Synopsis and Example tables */
        div.refsect1 table {
            width: 100%;
                        margin-top: 10px;
            background-color: #FFF;
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
                        font: normal 16px verdana, sans-serif;
        }

        div.refsect1 th {
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
            font: bold 16px verdana, sans-serif;
        }

        div.refsect1 td {
            background-color: #FFF;
            padding: 5px;
            vertical-align: text-top;
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
            font: normal 16px verdana, sans-serif;
        }

                  div.refsect1 p{
            font: normal 16px verdana, sans-serif;
            margin-top: 8px;
            margin-bottom: 8px;
            padding-top: 0;
            padding-bottom: 0;
        }


        /* EXAMPLE: These styles apply only to the Example section */
        div.refsect2 {
            font: normal 16px courier new, monospace !important;
        }

        div.refsect2 table {
            margin-top: 0;
            background-color: #e6e6e6;
            width: 100%;
            border: 0 solid #000;
            padding: 2px;
            font: normal 16px courier new, monospace !important;
        }

        div.refsect2 td {
            background-color: #e6e6e6;
            font: normal 16px courier new, monospace !important;
                        white-space:pre;
        }

        /* COPYRIGHT: This style formats the text of the copyright statement at the bottom of the page */
        div.refsect3 {
            font: normal 11px verdana, sans-serif;
            margin-top: 50px;
            margin-bottom: 20px;
            padding-top: 0;
            padding-bottom: 0;
        }

</style>
    <title>sampler_t</title>
    <meta name="generator" content="DocBook XSL Stylesheets V1.79.1" />
    <meta name="keywords" content="sampler_t" />
  </head>
  <body>
    <div class="refentry">
      <a id="id-1"></a>
      <div class="titlepage"></div>
      <div xmlns="" class="refnamediv">
        <a xmlns="http://www.w3.org/1999/xhtml" id="sampler_t"></a>
        <h1> sampler_t</h1>
        <p>
            A type used to control how elements of an image object are read by
            read_image{f<a xmlns="http://www.w3.org/1999/xhtml" class="citerefentry" href="imageFunctions.html"><span class="citerefentry"><span class="refentrytitle">|</span></span></a>i|ui}.
        </p>
      </div>
      <div class="refsect2">
        <a id="synopsis"></a>
        <h3>
        </h3>
        <div class="informaltable">
          <table class="informaltable" border="0">
            <colgroup>
              <col align="left" class="col1" />
            </colgroup>
            <tbody>
              <tr>
                <td align="left">
const sampler_t &lt;sampler name&gt; = &lt;value&gt;
constant sampler_t &lt;sampler name&gt; = &lt;value&gt;
__constant sampler_t &lt;sampler name&gt; = &lt;value&gt;
                        </td>
              </tr>
            </tbody>
          </table>
        </div>
      </div>
      <div class="refsect1">
        <a id="description"></a>
        <h2>Description</h2>
        <p>
          The image read functions take a sampler argument. The
          sampler can be passed as an argument to the kernel using
          <a class="citerefentry" href="clSetKernelArg.html"><span class="citerefentry"><span class="refentrytitle">clSetKernelArg</span></span></a>, or can
          be declared in the outermost scope of <code class="code">kernel</code> functions, or it can be a
          constant variable of type <span class="type">sampler_t</span> declared in the program source.
        </p>
        <p>
          Sampler variables in a program are declared to be of type <span class="type">sampler_t</span>. A
          variable of <span class="type">sampler_t</span> type declared in the program source must be
          initialized with a 32-bit unsigned integer constant, which is interpreted as a
          bit-field specifiying the following properties:
        </p>
        <p>
          </p>
        <div class="itemizedlist">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem">
              <p> Addressing Mode </p>
            </li>
            <li class="listitem">
              <p> Filter Mode </p>
            </li>
            <li class="listitem">
              <p> Normalized Coordinates </p>
            </li>
          </ul>
        </div>
        <p>
        </p>
        <p>
          These properties control how elements of an image object are read by <a class="citerefentry" href="imageFunctions.html"><span class="citerefentry"><span class="refentrytitle">read_image{f|i|ui}</span></span></a>.
        </p>
        <p>
          Samplers can also be declared as global constants in the program source using the
          syntax shown at the top of this page.
        </p>
        <p>
          The sampler fields are described in the table below:
        </p>
        <p>
          </p>
        <div class="informaltable">
          <table class="informaltable" border="1">
            <colgroup>
              <col align="left" class="col1" />
              <col align="left" class="col2" />
            </colgroup>
            <thead>
              <tr>
                <th align="left">Sampler State</th>
                <th align="left">Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td align="left">
                    <p>
                      <code class="constant">&lt;normalized coords&gt;</code>
                    </p>
                  </td>
                <td align="left">
                    <p>
                      Specifies whether the <code class="varname">x</code>, <code class="varname">y</code>
                      and <code class="varname">z</code> coordinates are passed in as normalized or
                      unnormalized values. This must be a literal value and can be one of the
                      following predefined enums:
                    </p>

                    <p>
</p><div class="literallayout"><p><code class="constant">CLK_NORMALIZED_COORDS_TRUE</code> or<br />
<code class="constant">CLK_NORMALIZED_COORDS_FALSE</code>.</p></div><p>
                    </p>

                    <p>
                      The samplers used with an image in multiple calls to <a class="citerefentry" href="imageFunctions.html"><span class="citerefentry"><span class="refentrytitle">read_image</span></span></a>{f|i|ui}
                      declared in a kernel must use the same value for <code class="constant">&lt;normalized
                      coords&gt;</code>.
                    </p>
                  </td>
              </tr>
              <tr>
                <td align="left">
                    <p>
                      <code class="constant">&lt;addressing mode&gt;</code>
                    </p>
                  </td>
                <td align="left">
                    <p>
                      Specifies the image addressing-mode i.e. how out-of-range image coordinates
                      are handled. This must be a literal value and can be one of the following
                      predefined enums:
                    </p>

                    <p>
                      <code class="constant">CLK_ADDRESS_MIRRORED_REPEAT</code> - Flip the image
                      coordinate at every integer junction. This addressing mode can only be used
                      with normalized coordinates. If normalized coordinates are not used,
                      this addressing mode may generate image coordinates that are undefined.
                    </p>

                    <p>
                      <code class="constant">CLK_ADDRESS_REPEAT</code> - out-of-range image coordinates
                      are wrapped to the valid range. This <code class="constant">address mode</code>
                      can only be used with normalized coordinates. If normalized coordinates
                      are not used, this addressing mode may generate image coordinates that
                      are undefined.
                    </p>

                    <p>
                      <code class="constant">CLK_ADDRESS_CLAMP_TO_EDGE</code> - out-of-range image
                      coordinates are clamped to the extent.
                    </p>

                    <p>
                      <code class="constant">CLK_ADDRESS_CLAMP</code> - out-of-range image coordinates
                      will return a border color. This is similar to the
                      <code class="constant">GL_ADDRESS_CLAMP_TO_BORDER</code> addressing mode.
                    </p>

                    <p>
                      <code class="constant">CLK_ADDRESS_NONE</code> - for this addressing mode the programmer
                      guarantees that the image coordinates used to sample elements of the image
                      refer to a location inside the image; otherwise the results are undefined.
                    </p>

                    <p>
                      For 1D and 2D image arrays, the addressing mode applies only to
                      the x and <span class="emphasis"><em>(x, y)</em></span> coordinates. The addressing
                      mode for the coordinate which specifies the array index is always
                      <code class="constant">CLK_ADDRESS_CLAMP_TO_EDGE</code>
                    </p>
                  </td>
              </tr>
              <tr>
                <td align="left">
                    <p>
                      <code class="constant">&lt;filter mode&gt;</code>
                    </p>
                  </td>
                <td align="left">
                    <p>
                      Specifies the filtering mode to use. This must
                      be a literal value and can be one of the following
                      predefined enums: <code class="constant">CLK_FILTER_NEAREST</code> or
                      <code class="constant">CLK_FILTER_LINEAR</code>. Refer to section 8.2 for a
                      description of these filter modes.
                    </p>
                  </td>
              </tr>
            </tbody>
          </table>
        </div>
        <p>
      </p>
      </div>
      <div class="refsect1">
        <a id="notes"></a>
        <h2>Notes</h2>
        <p>
            The sampler_t type is only
            defined if the device supports images i.e. 
            <code class="constant">CL_DEVICE_IMAGE_SUPPORT</code> as described in table
            4.3 is <code class="constant">CL_TRUE</code>.
        </p>
        <p>
           Note that samplers declared using the 
          <code class="code">constant</code> qualifier are not counted towards the maximum number of arguments 
          pointing to the constant address space or the maximum size of the constant address space
          allowed per device (i.e. <code class="constant">CL_DEVICE_MAX_CONSTANT_ARGS</code> and
          <code class="constant">CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE</code> as described in table 4.3).
        </p>
        <p>
          The maximum number of samplers that can be declared in a
          kernel can be queried using the <code class="constant">CL_DEVICE_MAX_SAMPLERS</code> token in
          <a class="citerefentry" href="clGetDeviceInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetDeviceInfo</span></span></a>.
        </p>
        <p>
          
          If <code class="code">&lt;addressing mode&gt;</code> in sampler is
          <code class="constant">CLK_ADDRESS_CLAMP</code>, then out-of-range image coordinates return
          the border color. The border color selected depends on the image channel order and
          can be one of the following values:
        </p>
        <div class="itemizedlist">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem" style="list-style-type: disc">
              <p>
              If the image channel order is <code class="constant">CL_A</code>,
              <code class="constant">CL_INTENSITY</code>, <code class="constant">CL_Rx</code>,
              <code class="constant">CL_RA</code>, <code class="constant">CL_RGx</code>,
              <code class="constant">CL_RGBx</code>, <code class="constant">CL_sRGBx</code>, <code class="constant">CL_ARGB</code>,
              <code class="constant">CL_BGRA</code>, <code class="constant">CL_ABGR</code>, <code class="constant">CL_RGBA</code>, 
              <code class="constant">CL_sRGBA</code> or <code class="constant">CL_sBGRA</code>, the border color
              is (0.0f, 0.0f,0.0f, 0.0f).
            </p>
            </li>
            <li class="listitem" style="list-style-type: disc">
              <p>
              If the image channel order is <code class="constant">CL_R</code>,
              <code class="constant">CL_RG</code>, <code class="constant">CL_RGB</code>, or
              <code class="constant">CL_LUMINANCE</code>, the border color is (0.0f, 0.0f, 0.0f, 1.0f)
            </p>
            </li>
            <li class="listitem" style="list-style-type: disc">
              <p>
              If the image channel order is <code class="constant">CL_DEPTH</code>,
              the border value is 0.0f.
            </p>
            </li>
          </ul>
        </div>
        <p>
           A kernel that uses a
          sampler with the <code class="constant">CL_ADDRESS_CLAMP</code> 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 <a class="citerefentry" href="imageFunctions.html"><span class="citerefentry"><span class="refentrytitle">read_image{f|i|ui}</span></span></a>,
          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 <code class="constant">CL_DEVICE_MAX_SAMPLERS</code>. Enqueuing a kernel that
          requires more samplers than the implementation can support will result in a
          <code class="constant">CL_OUT_OF_RESOURCES</code> error being returned.
        </p>
        <p>
            The sampler type (sampler_t) can only be used as the type of a function argument or a
            variable declared in the program scope or the outermost scope of a kernel function. The
            behavior of a sampler variable declared in a non-outermost scope of a kernel function is
            implementation-defined. A sampler argument or variable cannot be modified.
        </p>
        <p>
            The sampler type cannot be used to declare a structure or union field, an array of
            samplers, a pointer to a sampler, or the return type of a function. The sampler type
            cannot be used with the <code class="code">__local</code> and 
            <code class="code">__global</code> address space qualifiers.
        </p>
      </div>
      <div class="refsect2">
        <a id="example1"></a>
        <h3>
            Example
        </h3>
        <div class="informaltable">
          <table class="informaltable" border="0">
            <colgroup>
              <col align="left" class="col1" />
            </colgroup>
            <tbody>
              <tr>
                <td align="left">
const sampler_t samplerA = CLK_NORMALIZED_COORDS_TRUE |
                           CLK_ADDRESS_REPEAT         |
                           CLK_FILTER_NEAREST;
                        </td>
              </tr>
            </tbody>
          </table>
        </div>
        <p>
          samplerA specifies a sampler that uses normalized coordinates, the repeat addressing
          mode and a nearest filter.
        </p>
      </div>
      <div class="refsect1">
        <a id="specification"></a>
        <h2>Specification</h2>
        <p>
            <img src="pdficon_small1.gif" />

            <a href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#namedest=sampler_t" target="OpenCL Spec">OpenCL Specification</a>
        </p>
      </div>
      <div class="refsect1">
        <a id="seealso"></a>
        <h2>Also see</h2>
        <p>
            <a class="citerefentry" href="otherDataTypes.html"><span class="citerefentry"><span class="refentrytitle">Other Data Types</span></span></a>,
            <a class="citerefentry" href="imageFunctions.html"><span class="citerefentry"><span class="refentrytitle">Image Read and Write Functions</span></span></a>,
            <a class="citerefentry" href="classDiagram.html"><span class="citerefentry"><span class="refentrytitle">Cardinality Diagram</span></span></a>
        </p>
      </div>
      <div xmlns="" class="refsect3" lang="en" xml:lang="en"><a xmlns="http://www.w3.org/1999/xhtml" id="Copyright"></a><h4 xmlns="http://www.w3.org/1999/xhtml"></h4><img xmlns="http://www.w3.org/1999/xhtml" src="KhronosLogo.jpg" /><p xmlns="http://www.w3.org/1999/xhtml"></p>Copyright © 2007-2015 The Khronos Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the condition that this copyright notice and permission notice shall be included
in all copies or substantial portions of the Materials.
</div>
    </div>
  </body>
</html>