sdk/1.0/docs/man/clSetKernelArg.xml - external/github.com/KhronosGroup/OpenCL-Registry - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
 <refentry>
     <refentryinfo>
         <keywordset>
             <keyword>
                 clSetKernelArg
             </keyword>
         </keywordset>
     </refentryinfo>

     <refmeta>
         <refentrytitle>
             clSetKernelArg
         </refentrytitle>

         <refmiscinfo>
             <copyright>
                 <year>2007-2009</year>
                 <holder>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.</holder>
             </copyright>
         </refmiscinfo>
         <manvolnum>2</manvolnum>

     </refmeta>


 <!-- ================================ SYNOPSIS -->

     <refnamediv id="clSetKernelArg">
         <refname>
             clSetKernelArg
         </refname>

         <refpurpose>
             Used to set the argument value for a specific argument of a kernel.
         </refpurpose>
     </refnamediv>

     <refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
         <funcsynopsis>
             <funcprototype>
                 <funcdef>
                     <link xlink:href="scalarDataTypes.html">cl_int</link>
  <function>clSetKernelArg</function>
                 </funcdef>

 				<paramdef><link xlink:href="abstractDataTypes.html">cl_kernel</link><parameter>kernel</parameter></paramdef>
 				<paramdef><link xlink:href="scalarDataTypes.html">cl_uint</link><parameter>arg_index</parameter></paramdef>
 				<paramdef><link xlink:href="scalarDataTypes.html">size_t</link><parameter>arg_size</parameter></paramdef>
 				<paramdef>const <link xlink:href="scalarDataTypes.html">void</link><parameter>*arg_value</parameter></paramdef>
             </funcprototype>
         </funcsynopsis>
     </refsynopsisdiv>


 <!-- ================================ PARAMETERS -->
 <!-- For each <varlistentry />, place the parameter name in <term /><varname />, then the definition in
      <listitem /><para />. When refering to anything
      that has a page in this system, use <citerefentry /><refentrytitle /> to make it a link.
  -->

     <refsect1 id="parameters">
         <title>Parameters</title>
         <variablelist>
             <varlistentry>
                 <term>
                     <varname>kernel</varname>
 				</term>
 				<listitem>
 					<para>
 						A valid kernel object.
 					</para>
 				</listitem>
 			</varlistentry>

             <varlistentry>
                 <term>
                     <varname>arg_index</varname>
 				</term>

 				<listitem>
 					<para>
 						The argument index. Arguments to the kernel are referred by indices that go from 0 for the leftmost argument to <emphasis>n</emphasis> - 1, where <emphasis>n</emphasis> is the total number of arguments declared by a kernel.
 					</para>
 				</listitem>
 			</varlistentry>

             <varlistentry>
                 <term>
                     <varname>arg_value</varname>
 				</term>

 				<listitem>

 					<para>
 					A pointer to data that should be used as the argument value for argument specified
 						by <varname>arg_index</varname>. The argument data pointed to by <varname>arg_value</varname> is copied and the <varname>arg_value</varname> pointer can therefore be reused by the application after <function>clSetKernelArg</function> returns. The argument value specified is the value used by all API calls that enqueue <varname>kernel</varname> (<citerefentry><refentrytitle>clEnqueueNDRangeKernel</refentrytitle></citerefentry> and
 						<citerefentry><refentrytitle>clEnqueueTask</refentrytitle></citerefentry>) until the argument value is changed by a call to <function>clSetKernelArg</function> for <varname>kernel</varname>.
 					</para>

 					<para>
 						If the argument is a memory object (buffer or image), the <varname>arg_value</varname> entry will be a pointer to the appropriate buffer or image object. The memory object must be created with the context
 						associated with the kernel object. A NULL value can also be specified if the argument is a buffer
 						object in which case a NULL value will be used as the value for the argument declared as a
 						pointer to <varname>__global</varname> or <varname>__constant</varname> memory in the kernel. If the argument is declared with the <varname>__local</varname> qualifier, the <varname>arg_value</varname> entry must be NULL. If the argument is of type <varname>sampler_t</varname>, the <varname>arg_value</varname> entry must be a pointer to the sampler object. For all other kernel arguments, the <varname>arg_value</varname> entry must be a pointer to the actual data to be used as argument value.
 					</para>
 					<para>
 						The memory object specified as argument value must be a buffer object (or NULL) if the
 						argument is declared to be a pointer of a built-in or user defined type with the <varname>__global</varname> or
 						<varname>__constant</varname> qualifier. If the argument is declared with the <varname>__constant</varname> qualifier, the size in bytes of the memory object cannot exceed <constant>CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE</constant> and the
 						number of arguments declared with the <varname>__constant</varname> qualifier cannot exceed
 						<constant>CL_DEVICE_MAX_CONSTANT_ARGS</constant>.
 					</para>
 					<para>
 						The memory object specified as argument value must be a 2D image object if the argument is
 						declared to be of type <varname>image2d_t</varname>. The memory object specified as argument value must be a 3D image object if argument is declared to be of type <varname>image3d_t</varname>.
 					</para>

 				</listitem>
 			</varlistentry>
             <varlistentry>
                 <term>
                     <varname>
                        arg_size
 					</varname>
 				</term>

 				<listitem>
 					<para>
 						Specifies the size of the argument value. If the argument is a memory object, the size is
 						the size of the buffer or image object type. For arguments declared with the <varname>__local</varname> qualifier, the size specified will be the size in bytes of the buffer that must be allocated for the <varname>__local</varname>
 						argument. If the argument is of type <varname>sampler_t</varname>, the <varname>arg_size</varname> value must be equal to sizeof(cl_sampler). For all other arguments, the size will be the size of argument type.
 					</para>
 				</listitem>
 			</varlistentry>
         </variablelist>
     </refsect1>


 <!-- ================================ NOTES  -->
 <!-- Use <function /> to refer ONLY to the function that this page describes. All other functions should use
      <citerefentry /><refentrytitle /> to make it a link. Use <varname /> for parameters. Use <constant /> for
      constants (or anything to be set in monospace, non-bold type. -->

 	 <refsect1 id="notes"><title>Notes</title>
         <para>
 			A kernel object does not update the reference count for objects such as memory, sampler
 			objects specified as argument values by <function>clSetKernelArg</function>, Users may not rely on a kernel object
 			to retain objects specified as argument values to the kernel.
 		</para>
 		<para>
 			Implementations shall not allow cl_kernel objects to hold reference counts to cl_kernel arguments, because no
 			mechanism is provided for the user to tell the kernel to release that ownership right. If the kernel holds ownership
 			rights on kernel args, that would make it impossible for the user to tell with certainty when he may safely release
 			user allocated resources associated with OpenCL objects such as the cl_mem backing store used with
 			<constant>CL_MEM_USE_HOST_PTR</constant>.
 		</para>
 	</refsect1>


 <!-- ================================ ERRORS  -->


     <refsect1 id="errors"><title>Errors</title>
         <para>
 			<function>clSetKernelArg</function> returns <errorname>CL_SUCCESS</errorname> if the function is
 			executed successfully. Otherwise, it returns one of the following errors:
 		</para>
 		<itemizedlist mark="disc">
 			<listitem>
 				<errorname>CL_INVALID_KERNEL</errorname> if <varname>kernel</varname> is not a valid kernel object.
 			</listitem>
 			<listitem>
 				<errorname>CL_INVALID_ARG_INDEX</errorname> if <varname>arg_index</varname> is not a valid argument index.
 			</listitem>
 			<listitem>
 				<errorname>CL_INVALID_ARG_VALUE</errorname> if <varname>arg_value</varname> specified is NULL for an argument that is not
 				declared with the <varname>__local</varname> qualifier or vice-versa.
 			</listitem>
 			<listitem>
 				<errorname>CL_INVALID_MEM_OBJECT</errorname> for an argument declared to be a memory object when the
 				specified <varname>arg_value</varname> is not a valid memory object.
 			</listitem>
 			<listitem>
 				<errorname>CL_INVALID_SAMPLER</errorname> for an argument declared to be of type sampler_t when the
 				specified <varname>arg_value</varname> is not a valid sampler object.
 			</listitem>
 			<listitem>
 				<errorname>CL_INVALID_ARG_SIZE</errorname> if <varname>arg_size</varname> does not match the size of the data type for an argument that is not a memory object or if the argument is a memory object and <varname>arg_size</varname> != <constant>sizeof(cl_mem)</constant> or if <varname>arg_size</varname> is zero and the argument is declared with the <citerefentry href="local"><refentrytitle>__local</refentrytitle></citerefentry> qualifier or if the argument is a sampler and <varname>arg_size</varname> != <constant>sizeof(cl_sampler)</constant>.
 			</listitem>
 		</itemizedlist>
 	</refsect1>


 <!-- ================================ EXAMPLE  -->
 <!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
 <!--    -->
     <refsect2 id="example1">
         <title>
             Example
         </title>
         <informaltable frame="none">
             <tgroup cols="1" align="left" colsep="0" rowsep="0">
                 <colspec colname="col1" colnum="1" />
                 <tbody>
                     <row>
                         <entry>
 __kernel void
 image_filter (int n, int m,
           __constant float *filter_weights,
           __read_only image2d_t src_image,
           __write_only image2d_t dst_image)
 {
      ...
 }
                         </entry>
                     </row>
                 </tbody>
             </tgroup>
         </informaltable>
 		<para>
 			Argument index values for <constant>image_filter</constant> will be 0 for n, 1 for m, 2 for
 			<constant>filter_weights</constant>, 3 for <constant>src_image</constant> and 4 for <constant>dst_image</constant>.
 		</para>
     </refsect2>


 <!-- ================================ SPECIFICATION  -->
 <!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
 -->
     <refsect1 id="specification"><title>Specification</title>
         <para>
             <imageobject>
                 <imagedata fileref="pdficon_small1.gif" format="gif" />
             </imageobject>


             <olink uri="clSetKernelArg">OpenCL Specification</olink>
         </para>
     </refsect1>


 <!-- ================================ ALSO SEE  -->


     <refsect1 id="seealso"><title>Also see</title>
         <para>
             <citerefentry><refentrytitle>clCreateKernel</refentrytitle></citerefentry>,
 			<citerefentry><refentrytitle>clCreateKernelsInProgram</refentrytitle></citerefentry>,
 			<citerefentry><refentrytitle>clReleaseKernel</refentrytitle></citerefentry>,
 			<citerefentry><refentrytitle>clRetainKernel</refentrytitle></citerefentry>,
 			<citerefentry><refentrytitle>clGetKernelInfo</refentrytitle></citerefentry>,
 			<citerefentry><refentrytitle>clGetKernelWorkGroupInfo</refentrytitle></citerefentry>
         </para>
     </refsect1>

 <!-- ================================ COPYRIGHT  -->
 <!-- Content included from copyright.inc.xsl -->

     <refsect3 id="Copyright"><title></title>
 		<imageobject>
                 <imagedata fileref="KhronosLogo.jpg" format="jpg" />
         </imageobject>
 		<para />
     </refsect3>

 </refentry>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
	"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
	<refentry>
	<refentryinfo>
	<keywordset>
	<keyword>
	clSetKernelArg
	</keyword>
	</keywordset>
	</refentryinfo>

	<refmeta>
	<refentrytitle>
	clSetKernelArg
	</refentrytitle>

	<refmiscinfo>
	<copyright>
	<year>2007-2009</year>
	<holder>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.</holder>
	</copyright>
	</refmiscinfo>
	<manvolnum>2</manvolnum>

	</refmeta>


	<!-- ================================ SYNOPSIS -->

	<refnamediv id="clSetKernelArg">
	<refname>
	clSetKernelArg
	</refname>

	<refpurpose>
	Used to set the argument value for a specific argument of a kernel.
	</refpurpose>
	</refnamediv>

	<refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
	<funcsynopsis>
	<funcprototype>
	<funcdef>
	<link xlink:href="scalarDataTypes.html">cl_int</link>
	<function>clSetKernelArg</function>
	</funcdef>

	<paramdef><link xlink:href="abstractDataTypes.html">cl_kernel</link><parameter>kernel</parameter></paramdef>
	<paramdef><link xlink:href="scalarDataTypes.html">cl_uint</link><parameter>arg_index</parameter></paramdef>
	<paramdef><link xlink:href="scalarDataTypes.html">size_t</link><parameter>arg_size</parameter></paramdef>
	<paramdef>const <link xlink:href="scalarDataTypes.html">void</link><parameter>*arg_value</parameter></paramdef>
	</funcprototype>
	</funcsynopsis>
	</refsynopsisdiv>


	<!-- ================================ PARAMETERS -->
	<!-- For each <varlistentry />, place the parameter name in <term /><varname />, then the definition in
	<listitem /><para />. When refering to anything
	that has a page in this system, use <citerefentry /><refentrytitle /> to make it a link.
	-->

	<refsect1 id="parameters">
	<title>Parameters</title>
	<variablelist>
	<varlistentry>
	<term>
	<varname>kernel</varname>
	</term>
	<listitem>
	<para>
	A valid kernel object.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>
	<varname>arg_index</varname>
	</term>

	<listitem>
	<para>
	The argument index. Arguments to the kernel are referred by indices that go from 0 for the leftmost argument to <emphasis>n</emphasis> - 1, where <emphasis>n</emphasis> is the total number of arguments declared by a kernel.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>
	<varname>arg_value</varname>
	</term>

	<listitem>

	<para>
	A pointer to data that should be used as the argument value for argument specified
	by <varname>arg_index</varname>. The argument data pointed to by <varname>arg_value</varname> is copied and the <varname>arg_value</varname> pointer can therefore be reused by the application after <function>clSetKernelArg</function> returns. The argument value specified is the value used by all API calls that enqueue <varname>kernel</varname> (<citerefentry><refentrytitle>clEnqueueNDRangeKernel</refentrytitle></citerefentry> and
	<citerefentry><refentrytitle>clEnqueueTask</refentrytitle></citerefentry>) until the argument value is changed by a call to <function>clSetKernelArg</function> for <varname>kernel</varname>.
	</para>

	<para>
	If the argument is a memory object (buffer or image), the <varname>arg_value</varname> entry will be a pointer to the appropriate buffer or image object. The memory object must be created with the context
	associated with the kernel object. A NULL value can also be specified if the argument is a buffer
	object in which case a NULL value will be used as the value for the argument declared as a
	pointer to <varname>__global</varname> or <varname>__constant</varname> memory in the kernel. If the argument is declared with the <varname>__local</varname> qualifier, the <varname>arg_value</varname> entry must be NULL. If the argument is of type <varname>sampler_t</varname>, the <varname>arg_value</varname> entry must be a pointer to the sampler object. For all other kernel arguments, the <varname>arg_value</varname> entry must be a pointer to the actual data to be used as argument value.
	</para>
	<para>
	The memory object specified as argument value must be a buffer object (or NULL) if the
	argument is declared to be a pointer of a built-in or user defined type with the <varname>__global</varname> or
	<varname>__constant</varname> qualifier. If the argument is declared with the <varname>__constant</varname> qualifier, the size in bytes of the memory object cannot exceed <constant>CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE</constant> and the
	number of arguments declared with the <varname>__constant</varname> qualifier cannot exceed
	<constant>CL_DEVICE_MAX_CONSTANT_ARGS</constant>.
	</para>
	<para>
	The memory object specified as argument value must be a 2D image object if the argument is
	declared to be of type <varname>image2d_t</varname>. The memory object specified as argument value must be a 3D image object if argument is declared to be of type <varname>image3d_t</varname>.
	</para>

	</listitem>
	</varlistentry>
	<varlistentry>
	<term>
	<varname>
	arg_size
	</varname>
	</term>

	<listitem>
	<para>
	Specifies the size of the argument value. If the argument is a memory object, the size is
	the size of the buffer or image object type. For arguments declared with the <varname>__local</varname> qualifier, the size specified will be the size in bytes of the buffer that must be allocated for the <varname>__local</varname>
	argument. If the argument is of type <varname>sampler_t</varname>, the <varname>arg_size</varname> value must be equal to sizeof(cl_sampler). For all other arguments, the size will be the size of argument type.
	</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</refsect1>


	<!-- ================================ NOTES -->
	<!-- Use <function /> to refer ONLY to the function that this page describes. All other functions should use
	<citerefentry /><refentrytitle /> to make it a link. Use <varname /> for parameters. Use <constant /> for
	constants (or anything to be set in monospace, non-bold type. -->

	<refsect1 id="notes"><title>Notes</title>
	<para>
	A kernel object does not update the reference count for objects such as memory, sampler
	objects specified as argument values by <function>clSetKernelArg</function>, Users may not rely on a kernel object
	to retain objects specified as argument values to the kernel.
	</para>
	<para>
	Implementations shall not allow cl_kernel objects to hold reference counts to cl_kernel arguments, because no
	mechanism is provided for the user to tell the kernel to release that ownership right. If the kernel holds ownership
	rights on kernel args, that would make it impossible for the user to tell with certainty when he may safely release
	user allocated resources associated with OpenCL objects such as the cl_mem backing store used with
	<constant>CL_MEM_USE_HOST_PTR</constant>.
	</para>
	</refsect1>


	<!-- ================================ ERRORS -->


	<refsect1 id="errors"><title>Errors</title>
	<para>
	<function>clSetKernelArg</function> returns <errorname>CL_SUCCESS</errorname> if the function is
	executed successfully. Otherwise, it returns one of the following errors:
	</para>
	<itemizedlist mark="disc">
	<listitem>
	<errorname>CL_INVALID_KERNEL</errorname> if <varname>kernel</varname> is not a valid kernel object.
	</listitem>
	<listitem>
	<errorname>CL_INVALID_ARG_INDEX</errorname> if <varname>arg_index</varname> is not a valid argument index.
	</listitem>
	<listitem>
	<errorname>CL_INVALID_ARG_VALUE</errorname> if <varname>arg_value</varname> specified is NULL for an argument that is not
	declared with the <varname>__local</varname> qualifier or vice-versa.
	</listitem>
	<listitem>
	<errorname>CL_INVALID_MEM_OBJECT</errorname> for an argument declared to be a memory object when the
	specified <varname>arg_value</varname> is not a valid memory object.
	</listitem>
	<listitem>
	<errorname>CL_INVALID_SAMPLER</errorname> for an argument declared to be of type sampler_t when the
	specified <varname>arg_value</varname> is not a valid sampler object.
	</listitem>
	<listitem>
	<errorname>CL_INVALID_ARG_SIZE</errorname> if <varname>arg_size</varname> does not match the size of the data type for an argument that is not a memory object or if the argument is a memory object and <varname>arg_size</varname> != <constant>sizeof(cl_mem)</constant> or if <varname>arg_size</varname> is zero and the argument is declared with the <citerefentry href="local"><refentrytitle>__local</refentrytitle></citerefentry> qualifier or if the argument is a sampler and <varname>arg_size</varname> != <constant>sizeof(cl_sampler)</constant>.
	</listitem>
	</itemizedlist>
	</refsect1>


	<!-- ================================ EXAMPLE -->
	<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
	<!-- -->
	<refsect2 id="example1">
	<title>
	Example
	</title>
	<informaltable frame="none">
	<tgroup cols="1" align="left" colsep="0" rowsep="0">
	<colspec colname="col1" colnum="1" />
	<tbody>
	<row>
	<entry>
	__kernel void
	image_filter (int n, int m,
	__constant float *filter_weights,
	__read_only image2d_t src_image,
	__write_only image2d_t dst_image)
	{
	...
	}
	</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	<para>
	Argument index values for <constant>image_filter</constant> will be 0 for n, 1 for m, 2 for
	<constant>filter_weights</constant>, 3 for <constant>src_image</constant> and 4 for <constant>dst_image</constant>.
	</para>
	</refsect2>



	<!-- ================================ SPECIFICATION -->
	<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
	-->
	<refsect1 id="specification"><title>Specification</title>
	<para>
	<imageobject>
	<imagedata fileref="pdficon_small1.gif" format="gif" />
	</imageobject>


	<olink uri="clSetKernelArg">OpenCL Specification</olink>
	</para>
	</refsect1>


	<!-- ================================ ALSO SEE -->


	<refsect1 id="seealso"><title>Also see</title>
	<para>
	<citerefentry><refentrytitle>clCreateKernel</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>clCreateKernelsInProgram</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>clReleaseKernel</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>clRetainKernel</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>clGetKernelInfo</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>clGetKernelWorkGroupInfo</refentrytitle></citerefentry>
	</para>
	</refsect1>

	<!-- ================================ COPYRIGHT -->
	<!-- Content included from copyright.inc.xsl -->

	<refsect3 id="Copyright"><title></title>
	<imageobject>
	<imagedata fileref="KhronosLogo.jpg" format="jpg" />
	</imageobject>
	<para />
	</refsect3>

	</refentry>