blob: 1fc9c39987946243d44b6654a3a93a7a0646d460 [file] [log] [blame]
<?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>