sdk/1.2/docs/man/accessMappedInc.xml

<!-- include from 5.4.3 accessMappedInc.xml  -->
<bridgehead>Accessing mapped regions of a memory object</bridgehead>
    <para>
      This section describes the behavior of OpenCL commands that access 
      mapped regions of a memory object.
    </para>
    <para>
        The contents of the region of a memory object and associated memory objects 
        (sub-buffer objects or 1D image buffer objects that overlap this region) mapped 
        for writing (i.e. <constant>CL_MAP_WRITE</constant> or 
        <constant>CL_MAP_WRITE_INVALIDATE_REGION</constant> is set in <varname>map_flags</varname> 
        argument to <citerefentry><refentrytitle>clEnqueueMapBuffer</refentrytitle></citerefentry> 
        or <citerefentry><refentrytitle>clEnqueueMapImage</refentrytitle></citerefentry>) are 
        considered to be undefined until this region is unmapped.
    </para>
    <para>
        Multiple commands in command-queues can map a region or overlapping regions of a memory
        object and associated memory objects (sub-buffer objects or 1D image buffer objects that
        overlap this region) for reading (i.e. <varname>map_flags</varname> = <constant>CL_MAP_READ</constant>). 
        The contents of the regions of a memory object mapped for reading can also be read by kernels 
        and other OpenCL commands (such as 
        <citerefentry><refentrytitle>clEnqueueCopyBuffer</refentrytitle></citerefentry>) executing on a device(s).
    </para>
    <para>
        Mapping (and unmapping) overlapped regions in a memory object and/or associated memory
        objects (sub-buffer objects or 1D image buffer objects that overlap this region) for writing 
        is an error and will result in <constant>CL_INVALID_OPERATION</constant> error returned by 
        <citerefentry><refentrytitle>clEnqueueMapBuffer</refentrytitle></citerefentry> 
        or <citerefentry><refentrytitle>clEnqueueMapImage</refentrytitle></citerefentry>.
    </para>
    <para>
        If a memory object is currently mapped for writing, the application must ensure that the memory
        object is unmapped before any enqueued kernels or commands that read from or write to this
        memory object or any of its associated memory objects (sub-buffer or 1D image buffer objects)
        or its parent object (if the memory object is a sub-buffer or 1D image buffer object) begin
        execution; otherwise the behavior is undefined.
    </para>
    <para>
        If a memory object is currently mapped for reading, the application must ensure that the memory
        object is unmapped before any enqueued kernels or commands that write to this memory object
        or any of its associated memory objects (sub-buffer or 1D image buffer objects) or its parent
        object (if the memory object is a sub-buffer or 1D image buffer object) begin execution;
        otherwise the behavior is undefined.
    </para>
    <para>
        Accessing the contents of the memory region referred to by the mapped pointer that has 
        been unmapped is undefined.
    </para>
    <para>
        The mapped pointer returned by 
        <citerefentry><refentrytitle>clEnqueueMapBuffer</refentrytitle></citerefentry> 
        or <citerefentry><refentrytitle>clEnqueueMapImage</refentrytitle></citerefentry> can be used as
        <varname>ptr</varname> argument value to 
        <citerefentry><refentrytitle>clEnqueueReadBuffer</refentrytitle></citerefentry>, 
        <citerefentry><refentrytitle>clEnqueueWriteBuffer</refentrytitle></citerefentry>, 
        <citerefentry><refentrytitle>clEnqueueReadBufferRect</refentrytitle></citerefentry>, 
        <citerefentry><refentrytitle>clEnqueueWriteBufferRect</refentrytitle></citerefentry>,
        <citerefentry><refentrytitle>clEnqueueReadImage</refentrytitle></citerefentry>, and 
        <citerefentry><refentrytitle>clEnqueueWriteImage</refentrytitle></citerefentry>, 
        provided the rules described above are adhered to.
    </para>
      
      

<!-- 15-Oct-11 -->