sdk/1.1/docs/man/cl_khr_3d_image_writes.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>cl_khr_3d_image_writes</keyword>
         </keywordset>
     </refentryinfo>

     <refmeta>
         <refentrytitle>cl_khr_3d_image_writes</refentrytitle>

         <refmiscinfo>
             <copyright>
                 <year>2007-2010</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>3</manvolnum>
     </refmeta>

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

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

         <refpurpose>
             Extension to enable writes to 3D image memory objects.
         </refpurpose>
     </refnamediv>


     <!-- ALTERNATIVE SYNTAX SYNOPSIS (NON-FUNCTION) -->
     <refsect2 id="synopsis">
         <title>
         </title>

         <informaltable frame="none">
             <tgroup cols="1" align="left" colsep="0" rowsep="0">
                 <colspec colname="col1" colnum="1" />
                 <tbody>
                     <row>
                         <entry>
 #pragma OPENCL EXTENSION cl_khr_3d_image_writes : enable
                         </entry>
                     </row>
                 </tbody>
             </tgroup>
         </informaltable>
     </refsect2>


 <!-- ================================ DESCRIPTION  -->


     <refsect1 id="description" xmlns:xlink="http://www.w3.org/1999/xlink"><title>Description</title>
         <para>
 OpenCL 1.0 supports 2D image memory objects that can be read or written by kernels. Reads
 and writes to the same 2D image memory object are not supported in a kernel. OpenCL 1.0 also
 supports reads to 3D image memory objects in kernels. Writes to a 3D image memory object is
 not allowed. The <function>cl_khr_3d_image_writes</function> extension implements writes to 3D image memory objects. Reads and writes to the same 3D image memory object are not allowed in a
 kernel.
         </para>

         <para>
 An application that wants to use this extension to write to 3D image memory objects will need to
 include the <function>#pragma OPENCL EXTENSION cl_khr_3d_image_writes : enable</function>
 directive in the OpenCL program source.
         </para>

         <para>
 The built-in functions implemented by the <function>cl_khr_3d_image_writes</function> extension are described in the table below.
         </para>

         <informaltable frame="all">
             <tgroup cols="2" align="left" colsep="1" rowsep="1">
                 <colspec colname="col1" colnum="1" />
                 <colspec colname="col2" colnum="2" />

                 <thead>
                     <row>
                         <entry>Function</entry>
                         <entry>Description</entry>
                     </row>
                 </thead>

                 <tbody>

                     <row>
                         <entry>
 <para>
     <literallayout>
 <type><link xlink:href="scalarDataTypes.html">void</link></type> <function>write_imagef</function> (<link xlink:href="otherDataTypes.html">image3d_t</link> <varname>image</varname>,
                    <link xlink:href="vectorDataTypes.html">int4</link> <varname>coord</varname>,
                    <link xlink:href="vectorDataTypes.html">float4</link> <varname>color</varname>)

 <type><link xlink:href="scalarDataTypes.html">void</link></type> <function>write_imagei</function> (<link xlink:href="otherDataTypes.html">image3d_t</link> <varname>image</varname>,
                    <link xlink:href="vectorDataTypes.html">int4</link> <varname>coord</varname>,
                    <link xlink:href="vectorDataTypes.html">int4</link> <varname>color</varname>)

 <type><link xlink:href="scalarDataTypes.html">void</link></type> <function>write_imageui</function> (<link xlink:href="otherDataTypes.html">image3d_t</link> <varname>image</varname>,
                     <link xlink:href="vectorDataTypes.html">int4</link> <varname>coord</varname>,
                     <link xlink:href="vectorDataTypes.html">uint4</link> <varname>color</varname>)</literallayout>
 </para>
                         </entry>

                         <entry>
 <para>
 Write <varname>color</varname> value to location specified by coordinate (<varname>x</varname>,
 <varname>y</varname>, <varname>z</varname>) in the
 3D image object specified by <varname>image</varname>.
 Appropriate data format conversion to the specified
 image format is done before writing the color value.
 <varname>coord.x</varname>, <varname>coord.y</varname>, and
 <varname>coord.z</varname> are considered to be
 unnormalized coordinates and must be in the range 0 ... image
 stream width - 1, 0 ... image stream height - 1
 and 0 ... image stream depth - 1.
 </para>

 <para>
 <function>write_imagef</function> can only be used with image objects
 created with <varname>image_channel_data_type</varname> set to one of the
 pre-defined packed formats or set to <constant>CL_SNORM_INT8</constant>,
 <constant>CL_UNORM_INT8</constant>, <constant>CL_SNORM_INT16</constant>,
 <constant>CL_UNORM_INT16</constant>, <constant>CL_HALF_FLOAT</constant> or
 <constant>CL_FLOAT</constant>.
 Appropriate data format conversion will be done to
 convert channel data from a floating-point value to
 actual data format in which the channels are stored.
 </para>

 <para>
 <function>write_imagei</function> can only be used with image objects
 created with <varname>image_channel_data_type</varname> set to one of the
 following values:
     <literallayout>CL_SIGNED_INT8,
 CL_SIGNED_INT16, and
 CL_SIGNED_INT32.</literallayout>
 </para>

 <para>
 <function>write_imageui</function> can only be used with image objects
 created with <varname>image_channel_data_type</varname> set to one of the
 following values:
     <literallayout>CL_UNSIGNED_INT8,
 CL_UNSIGNED_INT16, and
 CL_UNSIGNED_INT32.</literallayout>
 </para>

 <para>
 The behavior of <function>write_imagef</function>, <function>write_imagei</function> and
 <function>write_imageui</function> for image objects with
 <varname>image_channel_data_type</varname> values not specified in the
 description above or with (<varname>x</varname>, <varname>y</varname>, <varname>z</varname>)
 coordinate values that
 are not in the range (0... image width  1, 0... image
 height  1, 0... image depth   1) respectively is
 undefined.
 </para>
                         </entry>
                     </row>

                 </tbody>
             </tgroup>
         </informaltable>
 <para>
 </para>
     </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>
                             Example goes here - it will be set in "code" type with white space preserved.
                         </entry>
                     </row>
                 </tbody>
             </tgroup>
         </informaltable>
     </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="cl_khr_3d_image_writes">OpenCL Specification</olink>
         </para>
     </refsect1>


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

     <refsect1 id="seealso"><title>Also see</title>
         <para>
             <citerefentry><refentrytitle>EXTENSION</refentrytitle></citerefentry>,
             <citerefentry><refentrytitle>cl_image_format</refentrytitle></citerefentry>,
             <citerefentry href="imageFunctions"><refentrytitle>Image Functions</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>cl_khr_3d_image_writes</keyword>
	</keywordset>
	</refentryinfo>

	<refmeta>
	<refentrytitle>cl_khr_3d_image_writes</refentrytitle>

	<refmiscinfo>
	<copyright>
	<year>2007-2010</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>3</manvolnum>
	</refmeta>

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

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

	<refpurpose>
	Extension to enable writes to 3D image memory objects.
	</refpurpose>
	</refnamediv>


	<!-- ALTERNATIVE SYNTAX SYNOPSIS (NON-FUNCTION) -->
	<refsect2 id="synopsis">
	<title>
	</title>

	<informaltable frame="none">
	<tgroup cols="1" align="left" colsep="0" rowsep="0">
	<colspec colname="col1" colnum="1" />
	<tbody>
	<row>
	<entry>
	#pragma OPENCL EXTENSION cl_khr_3d_image_writes : enable
	</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</refsect2>


	<!-- ================================ DESCRIPTION -->


	<refsect1 id="description" xmlns:xlink="http://www.w3.org/1999/xlink"><title>Description</title>
	<para>
	OpenCL 1.0 supports 2D image memory objects that can be read or written by kernels. Reads
	and writes to the same 2D image memory object are not supported in a kernel. OpenCL 1.0 also
	supports reads to 3D image memory objects in kernels. Writes to a 3D image memory object is
	not allowed. The <function>cl_khr_3d_image_writes</function> extension implements writes to 3D image memory objects. Reads and writes to the same 3D image memory object are not allowed in a
	kernel.
	</para>

	<para>
	An application that wants to use this extension to write to 3D image memory objects will need to
	include the <function>#pragma OPENCL EXTENSION cl_khr_3d_image_writes : enable</function>
	directive in the OpenCL program source.
	</para>

	<para>
	The built-in functions implemented by the <function>cl_khr_3d_image_writes</function> extension are described in the table below.
	</para>

	<informaltable frame="all">
	<tgroup cols="2" align="left" colsep="1" rowsep="1">
	<colspec colname="col1" colnum="1" />
	<colspec colname="col2" colnum="2" />

	<thead>
	<row>
	<entry>Function</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>

	<row>
	<entry>
	<para>
	<literallayout>
	<type><link xlink:href="scalarDataTypes.html">void</link></type> <function>write_imagef</function> (<link xlink:href="otherDataTypes.html">image3d_t</link> <varname>image</varname>,
	<link xlink:href="vectorDataTypes.html">int4</link> <varname>coord</varname>,
	<link xlink:href="vectorDataTypes.html">float4</link> <varname>color</varname>)

	<type><link xlink:href="scalarDataTypes.html">void</link></type> <function>write_imagei</function> (<link xlink:href="otherDataTypes.html">image3d_t</link> <varname>image</varname>,
	<link xlink:href="vectorDataTypes.html">int4</link> <varname>coord</varname>,
	<link xlink:href="vectorDataTypes.html">int4</link> <varname>color</varname>)

	<type><link xlink:href="scalarDataTypes.html">void</link></type> <function>write_imageui</function> (<link xlink:href="otherDataTypes.html">image3d_t</link> <varname>image</varname>,
	<link xlink:href="vectorDataTypes.html">int4</link> <varname>coord</varname>,
	<link xlink:href="vectorDataTypes.html">uint4</link> <varname>color</varname>)</literallayout>
	</para>
	</entry>

	<entry>
	<para>
	Write <varname>color</varname> value to location specified by coordinate (<varname>x</varname>,
	<varname>y</varname>, <varname>z</varname>) in the
	3D image object specified by <varname>image</varname>.
	Appropriate data format conversion to the specified
	image format is done before writing the color value.
	<varname>coord.x</varname>, <varname>coord.y</varname>, and
	<varname>coord.z</varname> are considered to be
	unnormalized coordinates and must be in the range 0 ... image
	stream width - 1, 0 ... image stream height - 1
	and 0 ... image stream depth - 1.
	</para>

	<para>
	<function>write_imagef</function> can only be used with image objects
	created with <varname>image_channel_data_type</varname> set to one of the
	pre-defined packed formats or set to <constant>CL_SNORM_INT8</constant>,
	<constant>CL_UNORM_INT8</constant>, <constant>CL_SNORM_INT16</constant>,
	<constant>CL_UNORM_INT16</constant>, <constant>CL_HALF_FLOAT</constant> or
	<constant>CL_FLOAT</constant>.
	Appropriate data format conversion will be done to
	convert channel data from a floating-point value to
	actual data format in which the channels are stored.
	</para>

	<para>
	<function>write_imagei</function> can only be used with image objects
	created with <varname>image_channel_data_type</varname> set to one of the
	following values:
	<literallayout>CL_SIGNED_INT8,
	CL_SIGNED_INT16, and
	CL_SIGNED_INT32.</literallayout>
	</para>

	<para>
	<function>write_imageui</function> can only be used with image objects
	created with <varname>image_channel_data_type</varname> set to one of the
	following values:
	<literallayout>CL_UNSIGNED_INT8,
	CL_UNSIGNED_INT16, and
	CL_UNSIGNED_INT32.</literallayout>
	</para>

	<para>
	The behavior of <function>write_imagef</function>, <function>write_imagei</function> and
	<function>write_imageui</function> for image objects with
	<varname>image_channel_data_type</varname> values not specified in the
	description above or with (<varname>x</varname>, <varname>y</varname>, <varname>z</varname>)
	coordinate values that
	are not in the range (0... image width 1, 0... image
	height 1, 0... image depth 1) respectively is
	undefined.
	</para>
	</entry>
	</row>

	</tbody>
	</tgroup>
	</informaltable>
	<para>
	</para>
	</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>
	Example goes here - it will be set in "code" type with white space preserved.
	</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</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="cl_khr_3d_image_writes">OpenCL Specification</olink>
	</para>
	</refsect1>


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

	<refsect1 id="seealso"><title>Also see</title>
	<para>
	<citerefentry><refentrytitle>EXTENSION</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>cl_image_format</refentrytitle></citerefentry>,
	<citerefentry href="imageFunctions"><refentrytitle>Image Functions</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>