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 <[email protected]> --- 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 [email protected] https://lists.freedesktop.org/mailman/listinfo/beignet
