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

[Yang, Rong R]

LGTM, pushed, thanks.

> -----Original Message-----
> From: Beignet [mailto:beignet-bounces at lists.freedesktop.org] On Behalf Of
> Chuanbo Weng
> Sent: Friday, February 10, 2017 15:48
> To: beignet at lists.freedesktop.org
> Cc: Weng, Chuanbo <chuanbo.weng at intel.com>
> Subject: [Beignet] [PATCH v2 2/2] Add document of using cl_khr_gl_sharing
> to do gl buffer sharing.
> 
> v2:
>   1. Change description of cl_khr_gl_sharing in README.md
>   2. Add display hint in gl-buffer-sharing-howto.mdwn
> 
> Signed-off-by: Chuanbo Weng <chuanbo.weng at intel.com>
> ---
>  docs/Beignet.mdwn                       |  7 ++-
>  docs/howto/gl-buffer-sharing-howto.mdwn | 82
> +++++++++++++++++++++++++++++++++
>  2 files changed, 85 insertions(+), 4 deletions(-)  create mode 100644
> docs/howto/gl-buffer-sharing-howto.mdwn
> 
> diff --git a/docs/Beignet.mdwn b/docs/Beignet.mdwn index
> 5c62b4c..709d7c8 100644
> --- a/docs/Beignet.mdwn
> +++ b/docs/Beignet.mdwn
> @@ -222,10 +222,8 @@ Known Issues
>    This loses some precision but gains performance.
> 
>  * cl\_khr\_gl\_sharing.
> -  This extension highly depends on mesa support. It seems that mesa would
> not provide
> -  such type of extensions, we may have to hack with mesa source code to
> support this
> -  extension. This feature used to work with a previous mesa git version. But
> now, it's
> -  simply broken.
> +  This extension is partially implemented(the most commonly used part),
> + and we will implement  other parts based on requirement.
> 
>  Project repository
>  ------------------
> @@ -283,6 +281,7 @@ Documents for OpenCL application developers
>  - [[Kernel Optimization Guide|Beignet/optimization-guide]]
>  - [[Libva Buffer Sharing|Beignet/howto/libva-buffer-sharing-howto]]
>  - [[V4l2 Buffer Sharing|Beignet/howto/v4l2-buffer-sharing-howto]]
> +- [[OpenGL Buffer Sharing|Beignet/howto/gl-buffer-sharing-howto]]
>  - [[Video Motion Estimation|Beignet/howto/video-motion-estimation-
> howto]]
>  - [[Stand Alone Unit Test|Beignet/howto/stand-alone-utest-howto]]
>  - [[Android build|Beignet/android-build-howto]]
> diff --git a/docs/howto/gl-buffer-sharing-howto.mdwn b/docs/howto/gl-
> buffer-sharing-howto.mdwn
> new file mode 100644
> index 0000000..6b3a751
> --- /dev/null
> +++ b/docs/howto/gl-buffer-sharing-howto.mdwn
> @@ -0,0 +1,82 @@
> +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`
> +
> +- Export your X Display (if you login to your machine by ssh):
> +  `> export DISPLAY=:0.0`
> +
> +- Run:
> +  `> cd examples`
> +  `> . ../utests/setenv.sh`
> +  `> ./example-gl_buffer_sharing`
> +
> +More references
> +---------------
> +https://www.khronos.org/registry/OpenCL/specs/opencl-1.2-
> extensions.pdf
> --
> 1.9.1
> 
> _______________________________________________
> Beignet mailing list
> Beignet at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/beignet