'\" t
.\" Title: sampler_t
.\" Author: The Khronos Group
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 01/14/2021
.\" Manual: OpenCL Manual
.\" Source: The Khronos Group
.\" Language: English
.\"
.TH "SAMPLER_T" "3clc" "01/14/2021" "The Khronos Group" "OpenCL Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sampler_t \- A type used to control how elements of an image object are read by read_image{f|i|ui}\&.
.SS ""
.TS
tab(:);
l.
T{
const sampler_t =
constant sampler_t =
__constant sampler_t =
T}
.TE
.sp 1
.SH "DESCRIPTION"
.PP
The image read functions take a sampler argument\&. The sampler can be passed as an argument to the kernel using
\fBclSetKernelArg\fR(3clc), or can be declared in the outermost scope of
kernel
functions, or it can be a constant variable of type
\fBsampler_t\fR
declared in the program source\&.
.PP
Sampler variables in a program are declared to be of type
\fBsampler_t\fR\&. A variable of
\fBsampler_t\fR
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:
.PP
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Addressing Mode
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Filter Mode
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Normalized Coordinates
.RE
.PP
These properties control how elements of an image object are read by
\fBimageFunctions\fR(3clc)\&.
.PP
Samplers can also be declared as global constants in the program source using the syntax shown at the top of this page\&.
.PP
The sampler fields are described in the table below:
.PP
.TS
allbox tab(:);
lB lB.
T{
Sampler State
T}:T{
Description
T}
.T&
l l
l l
l l.
T{
.PP
\fB\fR
T}:T{
.PP
Specifies whether the
\fIx\fR,
\fIy\fR
and
\fIz\fR
coordinates are passed in as normalized or unnormalized values\&. This must be a literal value and can be one of the following predefined enums:
.PP
.if n \{\
.RS 4
.\}
.nf
\fBCLK_NORMALIZED_COORDS_TRUE\fR or
\fBCLK_NORMALIZED_COORDS_FALSE\fR\&.
.fi
.if n \{\
.RE
.\}
.sp
.PP
The samplers used with an image in multiple calls to
\fBimageFunctions\fR(3clc){f|i|ui} declared in a kernel must use the same value for
\fB\fR\&.
T}
T{
.PP
\fB\fR
T}:T{
.PP
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:
.PP
\fBCLK_ADDRESS_MIRRORED_REPEAT\fR
\- 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\&.
.PP
\fBCLK_ADDRESS_REPEAT\fR
\- out\-of\-range image coordinates are wrapped to the valid range\&. This
\fBaddress mode\fR
can only be used with normalized coordinates\&. If normalized coordinates are not used, this addressing mode may generate image coordinates that are undefined\&.
.PP
\fBCLK_ADDRESS_CLAMP_TO_EDGE\fR
\- out\-of\-range image coordinates are clamped to the extent\&.
.PP
\fBCLK_ADDRESS_CLAMP\fR
\- out\-of\-range image coordinates will return a border color\&. This is similar to the
\fBGL_ADDRESS_CLAMP_TO_BORDER\fR
addressing mode\&.
.PP
\fBCLK_ADDRESS_NONE\fR
\- 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\&.
.PP
For 1D and 2D image arrays, the addressing mode applies only to the x and
\fI(x, y)\fR
coordinates\&. The addressing mode for the coordinate which specifies the array index is always
\fBCLK_ADDRESS_CLAMP_TO_EDGE\fR
T}
T{
.PP
\fB\fR
T}:T{
.PP
Specifies the filtering mode to use\&. This must be a literal value and can be one of the following predefined enums:
\fBCLK_FILTER_NEAREST\fR
or
\fBCLK_FILTER_LINEAR\fR\&. Refer to section 8\&.2 for a description of these filter modes\&.
T}
.TE
.sp 1
.SH "NOTES"
.PP
Note that samplers declared using the
constant
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\&.
\fBCL_DEVICE_MAX_CONSTANT_ARGS\fR
and
\fBCL_DEVICE_MAX_CONSTANT_BUFFER_SIZE\fR
as described in table 4\&.3)\&.
.PP
The maximum number of samplers that can be declared in a kernel can be queried using the
\fBCL_DEVICE_MAX_SAMPLERS\fR
token in
\fBclGetDeviceInfo\fR(3clc)\&.
.PP
If
in sampler is
\fBCLK_ADDRESS_CLAMP\fR, 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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If the image channel order is
\fBCL_A\fR,
\fBCL_INTENSITY\fR,
\fBCL_Rx\fR,
\fBCL_RA\fR,
\fBCL_RGx\fR,
\fBCL_RGBx\fR,
\fBCL_ARGB\fR,
\fBCL_BGRA\fR, or
\fBCL_RGBA\fR, the border color is (0\&.0f, 0\&.0f,0\&.0f, 0\&.0f)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If the image channel order is
\fBCL_R\fR,
\fBCL_RG\fR,
\fBCL_RGB\fR, or
\fBCL_LUMINANCE\fR, the border color is (0\&.0f, 0\&.0f, 0\&.0f, 1\&.0f)
.RE
.PP
A kernel that uses a sampler with the
\fBCL_ADDRESS_CLAMP\fR
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
\fBimageFunctions\fR(3clc), 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
\fBCL_DEVICE_MAX_SAMPLERS\fR\&. Enqueuing a kernel that requires more samplers than the implementation can support will result in a
\fBCL_OUT_OF_RESOURCES\fR
error being returned\&.
.SS "Example"
.TS
tab(:);
l.
T{
const sampler_t samplerA = CLK_NORMALIZED_COORDS_TRUE |
CLK_ADDRESS_REPEAT |
CLK_FILTER_NEAREST;
T}
.TE
.sp 1
.PP
samplerA specifies a sampler that uses normalized coordinates, the repeat addressing mode and a nearest filter\&.
.SH "SPECIFICATION"
.PP
\m[blue]\fBOpenCL Specification\fR\m[]\&\s-2\u[1]\d\s+2
.SH "SEE ALSO"
.PP
\fBotherDataTypes\fR(3clc),
\fBimageFunctions\fR(3clc),
\fBclassDiagram\fR(3clc)
.SH "AUTHORS"
.PP
\fBThe Khronos Group\fR
.SH "COPYRIGHT"
.br
Copyright \(co 2007-2011 The Khronos Group Inc.
.br
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.
.sp
.SH "NOTES"
.IP " 1." 4
OpenCL Specification
.RS 4
\%page 292, section 6.12.14.1 - Samplers
.RE