[Beignet] [PATCH 2/2] Add document of using cl_khr_gl_sharing to do gl buffer sharing.

[Chuanbo Weng]

Signed-off-by: Chuanbo Weng <chuanbo.weng at intel.com>
---
 docs/howto/gl-buffer-sharing-howto.mdwn | 79 +++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 docs/howto/gl-buffer-sharing-howto.mdwn

diff --git a/docs/howto/gl-buffer-sharing-howto.mdwn b/docs/howto/gl-buffer-sharing-howto.mdwn
new file mode 100644
index 0000000..ec75a2d
--- /dev/null
+++ b/docs/howto/gl-buffer-sharing-howto.mdwn
@@ -0,0 +1,79 @@
+GL Buffer Sharing HowTo
+=========================
+
+Beignet now support cl_khr_gl_sharing partially(the most commonly used part), which is an offcial
+extension of Khronos OpenCL. With this extension, Beignet can create memory object from OpenGL/OpenGL
+ES buffer, texture or renderbuffer object with zero-copy. Currently, we just support create memory
+object from GL buffer object or 2d texture(the most common target type). We will support creating
+from other GL target type if necessary.
+
+Prerequisite
+------------
+
+Mesa GL library and Mesa EGL libray are required. Both version should be greater or equal than
+13.0.0.
+
+Steps
+-----
+
+A typical procedure of using cl_khr_gl_sharing is as below:
+
+- Basic egl routine(eglGetDisplay, eglInitialize, eglCreateContext...).
+
+- Create GL 2d texture in normal OpenGL way.
+
+- Check whether cl_khr_gl_sharing is supported by Beignet (Whether cl_khr_gl_sharing is present
+  in CL_DEVICE_EXTENSIONS string).
+
+- Create cl context with following cl_context_properties:
+    cl_context_properties *props=new cl_context_properties[7];
+    int i = 0;
+    props[i++] = CL_CONTEXT_PLATFORM;
+    props[i++] = (cl_context_properties)platform; //Valid OpenCL handle
+    props[i++] = CL_EGL_DISPLAY_KHR;  //We only support CL_EGL_DISPLAY_KHR now
+    props[i++] = (cl_context_properties)eglGetCurrentDisplay(); //EGLDisplay handle of the display
+    props[i++] = CL_GL_CONTEXT_KHR; //We only support CL_GL_CONTEXT_KHR now
+    props[i++] = (cl_context_properties)eglGetCurrentContext(); //EGLContext created by above EGLDisplay
+    props[i++] = 0;
+
+- Create cl image object from GL 2d texture by calling clCreateFromGLTexture.
+
+- Ensure any pending GL operations which access this GL 2d texture have completed by glFinish.
+
+- Acquire cl image object by calling clEnqueueAcquireGLObjects.
+
+- Access this cl image object as an usual cl image object.
+
+- Relase cl image object by calling clEnqueueReleaseGLObjects.
+
+- Ensure any pending OpenCL operations which access this cl image object have completed by clFinish.
+
+- Do other operation on GL 2d texture.
+
+Sample code
+-----------
+
+We have developed an example showing how to utilize cl_khr_gl_sharing in examples/gl_buffer_sharing
+directory. A cl image object is created from a gl 2d texutre and processed by OpenCL kernel, then
+is shown on screen.
+
+Steps to build and run this example:
+
+- Install mesa gl and egl library(version >= 13.0.0). X11 is also required.
+
+- Add option -DBUILD_EXAMPLES=ON to enable building examples when running cmake, such as:
+  `> mkdir build`
+  `> cd build`
+  `> cmake -DBUILD_EXAMPLES=ON ../`
+
+- Build source code:
+  `> make`
+
+- Run:
+  `> cd examples`
+  `> . ../utests/setenv.sh`
+  `> ./example-gl_buffer_sharing`
+
+More references
+---------------
+https://www.khronos.org/registry/OpenCL/specs/opencl-1.2-extensions.pdf
-- 
2.7.4