sdk/2.0/docs/man/accessQualifiers.xml

<?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>accessQualifiers</keyword>
        </keywordset>
    </refentryinfo>

    <refmeta>                                    
        <refentrytitle>accessQualifiers</refentrytitle>

        <refmiscinfo>
            <copyright>
                <year>2007-2013</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="accessQualifiers">             
        <refname>Access Qualifiers</refname>

        <refpurpose>
            Access Qualifiers for 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>
__read_only
__write_only
__read_write
read_only
write_only
read_write
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
    </refsect2>

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

    <refsect1 id="description"><title>Description</title>
        <para>
            Image objects specified as arguments to a 
            kernel can be declared to be read-only, write-only or 
            read-write. The <function>__read_only</function>
            (or <function>read_only</function>) and 
            <function>__write_only</function> 
            (or <function>write_only</function>) qualifiers must be used with 
            image object arguments to declare if the image 
            object is being read or written by a kernel. The 
            <function>__read_write</function> (or <function>read_write</function>) 
            qualifier must be used with image object arguments to 
            declare if the image object is being both read and 
            written by a kernel. The default qualifier is 
            <function>read_only</function>.
        </para>

        <para>
            In the following example
        </para>

        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>
<literallayout>kernel void
foo (read_only image2d_t imageA, 
    write_only image2d_t imageB)
{
    ...
}
</literallayout>
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>

        <para>
            <code>imageA</code> is a read-only 2D image object, and 
            <code>imageB</code> is a write-only 2D image object.
        </para>

        <para>
            The sampler-less read image and write image built-ins 
            can be used with image declared with the
            <function>__read_write</function> (or <function>read_write</function>) qualifier. 
            Calls to built-ins that read from an image 
            using a sampler for images declared with the 
            <function>__read_write</function> (or <function>read_write</function>) qualifier 
            will be a compilation error.
        </para>

        <para>
            Pipe objects specified as arguments to a kernel 
            can also use these access qualifiers. Refer to 
            section 6.13.16 for a detailed description on 
            how these access qualifiers can be used with pipes.
        </para>
    </refsect1>

<!-- ================================ NOTES  -->

    <refsect1 id="notes"><title>Notes</title>
        <para>
        The <function>__read_only</function>, <function>__write_only</function>, 
        <function>__read_write</function>, <function>read_only</function>, 
        <function>write_only</function> and <function>read_write</function> names are reserved 
        for use as access qualifiers and shall not be used otherwise.
        </para>
    </refsect1> 

<!-- ================================ EXAMPLE  -->

<!--
    <refsect2 id="example1">
        <title>
            Example
        </title>
    </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="accessQualifiers">OpenCL Specification</olink>
        </para>
    </refsect1>

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

    <refsect1 id="seealso"><title>Also see</title>
        <para>
            <citerefentry><refentrytitle>qualifiers</refentrytitle></citerefentry>,
            <citerefentry href="pipeFunctions"><refentrytitle>pipe 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>

<!-- 11-Dec-2013, rev. 19 -->
</refentry>