blob: 2b0cc2a242b8b199f3e97975a11eae4adf3ebabf [file] [log] [blame]
Name Strings
cl_qcom_android_native_buffer_host_ptr
Contributors
Hossein Mohtasham, Qualcomm Technologies, Inc.
Sushmita Susheelendra, Qualcomm Innovation Center, Inc.
Balaji Calidas, Qualcomm Technologies, Inc.
Contact
bcalidas at qti dot qualcomm dot com
Version
Version 6, 2018/01/19
Number
OpenCL Extension #32
Status
Shipping
Extension Type
OpenCL device extension
Dependencies
OpenCL 1.1 or later is required.
cl_qcom_ext_host_ptr is required.
Android OS is required.
This extension is written against the OpenCL 1.1 specification. This
extension provides functionality, beyond and above the cl_qcom_ion_host_ptr
extension, to create buffers and images directly from Android native
buffers.
If present, cl_qcom_ext_host_ptr_iocoherent extends the functionality
of this extension.
Overview
This extension extends the functionality provided by clCreateBuffer,
clCreateImage2D, and clCreateImage. It allows applications to pass an
Android ANativeWindowBuffer (ANB), aka graphics buffer, that is based on
ION memory allocator to these functions so that it can be mapped to the
device's address space. Using this extension, we can avoid having to copy
data back and forth between the graphic buffer and the device. This
extension is for 2D images only; clCreateImage will fail out with
CL_INVALID_VALUE if anything other than a 2D image is specified.
Header File
cl_ext.h
New Tokens
Accepted by the <host_ptr> argument of clCreateBuffer, clCreateImage2D:
typedef struct _cl_mem_android_native_buffer_host_ptr
{
// Type of external memory allocation.
// Must be CL_MEM_ANB_HOST_PTR_QCOM for Android Native Buffers.
cl_mem_ext_host_ptr ext_host_ptr;
// Host pointer to the Android Native Buffer (ANativeBuffer*)
void* anb_ptr;
} cl_mem_android_native_buffer_host_ptr;
Used together with CL_MEM_EXT_HOST_PTR_QCOM:
CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM 0x40C6
Additions to Chapter 5.2.1 of the OpenCL 1.1 Specification
(Creating Buffer Objects)
When CL_MEM_EXT_HOST_PTR_QCOM is enabled in the <flags> argument, then
<host_ptr> is interpreted as a pointer to cl_mem_ext_host_ptr. When
<host_ptr>->allocation_type is equal to
CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM then <host_ptr> can also be
interpreted as a pointer to cl_mem_android_native_buffer_host_ptr.
In addition to that, the application must also initialize the following
struct fields:
* <host_ptr>->host_cache_policy should be set as follows - If the
Graphic Buffer was created as cached and
cl_mem_ext_host_ptr_iocoherent is present,
<host_ptr>->host_cache_policy can be set to either
CL_MEM_HOST_WRITEBACK_QCOM or CL_MEM_HOST_IOCOHERENT_QCOM. If the
Graphic Buffer was created as cached and
cl_mem_ext_host_ptr_iocoherent is not present,
<host_ptr>->host_cache_policy should be set to
CL_MEM_HOST_WRITEBACK_QCOM. It must be equal to
CL_MEM_HOST_UNCACHED_QCOM otherwise.
* <host_ptr>->anb_ptr must be the host virtual pointer associated with
the ANativeBuffer.
The caching policy provided in ext_host_ptr.host_cache_policy must be
the same policy the GraphicBuffer is created with. Any mismatch will
result in undefined behavior.
Only Buffers and 2D images are supported. Use of other image types will
result in undefined behavior.
The application is responsible for maintaining the consistency of image
attributes, i.e. format, width, height, and pitch, between the OpenCL
image and the Android native buffer (aka graphics buffer). Also, if an
OpenCL buffer is created from a native buffer, the application is
responsible for making sure that the size of the buffer matches the
actual linear size of the native buffer; creating a buffer with a size
different than the passed-in native buffer will result in undefined
behavior.
The application is responsible for ensuring that the underlying native
buffer is not released while the cl object is in use. Proper
synchronization between different APIs that share the underlying buffer
is to be handled by the application.
Sample Code
1) Using the extension for CL buffer objects
cl_mem buffer_object = NULL;
size_t buffer_size_in_bytes = 0;
cl_mem_android_native_buffer_host_ptr myANBmem = {0};
// Create an OpenCL buffer object that uses myANBmem as its data store.
myANBmem.ext_host_ptr.allocation_type =
CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM;
myANBmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_UNCACHED_QCOM;
myANBmem.anb_ptr = gb->getNativeBuffer(); // gb is Android GraphicBuffer
// The stride returned is in pixels, so we have to factor in pixel_size
// (4 for RGBA) when calculating buffer_size_in_bytes
buffer_size_in_bytes = gb->getHeight() * gb->getStride() * 4;
buffer_object = clCreateBuffer(context,
CL_MEM_USE_HOST_PTR | CL_MEM_EXT_HOST_PTR_QCOM,
buffer_size_in_bytes, &myANBmem, &errcode);
2) Using the extension for CL image objects
cl_mem image_object = NULL;
cl_mem_android_native_buffer_host_ptr myANBmem = {0};
// Create an OpenCL image object that uses myANBmem as its data store.
myANBmem.ext_host_ptr.allocation_type =
CL_MEM_ANDROID_NATIVE_BUFFER_HOST_PTR_QCOM;
myANBmem.ext_host_ptr.host_cache_policy = CL_MEM_HOST_WRITEBACK_QCOM;
myANBmem.anb_ptr = gb->getNativeBuffer(); // gb is Android GraphicBuffer
imgw = gb->getWidth();
imgh = gb->getHeight();
// The stride returned is in pixels, so we have to factor in pixel_size
// (4 for RGBA) when calculating row_pitch
row_pitch = gb->getStride() * 4;
// pick any CL format as long as it is consistent with graphic buffer
// width and stride.
image_format = {CL_RGBA, CL_UNSIGNED_INT8};
image_object = clCreateImage2D(context,
CL_MEM_USE_HOST_PTR|CL_MEM_EXT_HOST_PTR_QCOM, &image_fmt, imgw,
imgh, row_pitch, &myANBmem, &errcode);
Revision History
Revision 1, 2014/06/05: Initial version.
Revision 2, 2017/06/16: Clean up. No functional changes.
Revision 3, 2017/10/24: Updated sample code.
Revision 4, 2017/11/13: Clean up. No functional changes.
Revision 5, 2018/01/03: Add reference to cl_qcom_ext_host_ptr_iocoherent.
Revision 6, 2018/01/19: Formatting and misc changes. No functional changes.