Scroll to navigation

SAMPLER_T(3clc) OpenCL Manual SAMPLER_T(3clc)

NAME

sampler_t - A type used to control how elements of an image object are read by read_image{f|i|ui}.

const sampler_t <sampler name> = <value> constant sampler_t <sampler name> = <value> __constant sampler_t <sampler name> = <value>

DESCRIPTION

The image read functions take a sampler argument. The sampler can be passed as an argument to the kernel using clSetKernelArg(3clc), or can be declared in the outermost scope of kernel functions, or it can be a constant variable of type sampler_t declared in the program source.

Sampler variables in a program are declared to be of type sampler_t. A variable of sampler_t 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:

•Addressing Mode

•Filter Mode

•Normalized Coordinates

These properties control how elements of an image object are read by imageFunctions(3clc).

Samplers can also be declared as global constants in the program source using the syntax shown at the top of this page.

The sampler fields are described in the table below:

Sampler State Description
<normalized coords> Specifies whether the x, y and z coordinates are passed in as normalized or unnormalized values. This must be a literal value and can be one of the following predefined enums: CLK_NORMALIZED_COORDS_TRUE or CLK_NORMALIZED_COORDS_FALSE. The samplers used with an image in multiple calls to imageFunctions(3clc){f|i|ui} declared in a kernel must use the same value for <normalized coords>. 





  

     <addressing mode>
     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: CLK_ADDRESS_MIRRORED_REPEAT - 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. CLK_ADDRESS_REPEAT - out-of-range image coordinates are
      wrapped to the valid range. This address mode can only be used with
      normalized coordinates. If normalized coordinates are not used, this
      addressing mode may generate image coordinates that are undefined.
      CLK_ADDRESS_CLAMP_TO_EDGE - out-of-range image coordinates are
      clamped to the extent. CLK_ADDRESS_CLAMP - out-of-range image
      coordinates will return a border color. This is similar to the
      GL_ADDRESS_CLAMP_TO_BORDER addressing mode. CLK_ADDRESS_NONE
      - 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. For 1D and 2D image
      arrays, the addressing mode applies only to the x and (x, y)
      coordinates. The addressing mode for the coordinate which specifies the
      array index is always CLK_ADDRESS_CLAMP_TO_EDGE
  

  

     <filter mode>
     Specifies the filtering mode to use. This must be a literal value and
      can be one of the following predefined enums: CLK_FILTER_NEAREST or
      CLK_FILTER_LINEAR. Refer to section 8.2 for a description of these
      filter modes.
  










NOTES

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.
  CL_DEVICE_MAX_CONSTANT_ARGS and
  CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE as described in table 4.3).

The maximum number of samplers that can be declared in a kernel
    can be queried using the CL_DEVICE_MAX_SAMPLERS token in
    clGetDeviceInfo(3clc).


If <addressing mode> in sampler is CLK_ADDRESS_CLAMP,
    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:




•If the image channel order is CL_A,
  CL_INTENSITY, CL_Rx, CL_RA, CL_RGx,
  CL_RGBx, CL_ARGB, CL_BGRA, or CL_RGBA, the border
  color is (0.0f, 0.0f,0.0f, 0.0f).




•If the image channel order is CL_R,
  CL_RG, CL_RGB, or CL_LUMINANCE, the border color is
  (0.0f, 0.0f, 0.0f, 1.0f)


A kernel that uses a sampler with the CL_ADDRESS_CLAMP
    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 imageFunctions(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
    CL_DEVICE_MAX_SAMPLERS. Enqueuing a kernel that requires more
    samplers than the implementation can support will result in a
    CL_OUT_OF_RESOURCES error being returned.




Example



  

    const sampler_t samplerA = CLK_NORMALIZED_COORDS_TRUE |
      CLK_ADDRESS_REPEAT | CLK_FILTER_NEAREST;
  






samplerA specifies a sampler that uses normalized coordinates, the
    repeat addressing mode and a nearest filter.








SPECIFICATION

OpenCL Specification[1]





SEE ALSO

otherDataTypes(3clc), imageFunctions(3clc),
  classDiagram(3clc)





AUTHORS

The Khronos Group





COPYRIGHT

Copyright © 2007-2011 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.







NOTES



  
 1.

  
OpenCL Specification




page 292, section 6.12.14.1 - Samplers







  

    02/03/2019
    The Khronos Group