[Beignet] [PATCH 2/2] Add document to describe the detials of libva buffer sharing.

[Weng, Chuanbo]

Please ignore this patchset. I'll send out a new version.

-----Original Message-----
From: Weng, Chuanbo 
Sent: Tuesday, December 16, 2014 20:17
To: beignet at lists.freedesktop.org
Cc: Zou, Nanhai; Zhao, Yakui; Li, Jocelyn; Weng, Chuanbo
Subject: [PATCH 2/2] Add document to describe the detials of libva buffer sharing.

This document includes the steps of using libva buffer sharing, the way to build and run corresponding example.

Signed-off-by: Chuanbo Weng <chuanbo.weng at intel.com>
---
 docs/Beignet.mdwn                          |  1 +
 docs/howto/libva-buffer-sharing-howto.mdwn | 66 ++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 docs/howto/libva-buffer-sharing-howto.mdwn

diff --git a/docs/Beignet.mdwn b/docs/Beignet.mdwn index fea56b8..8845ea1 100644
--- a/docs/Beignet.mdwn
+++ b/docs/Beignet.mdwn
@@ -238,6 +238,7 @@ Documents for OpenCL application developers
 -------------------------------------------
 - [[Cross compile|Beignet/howto/cross-compiler-howto]]
 - [[Kernel Optimization Guide|Beignet/optimization-guide]]
+- [[Libva Buffer Sharing|Beignet/howto/libva-buffer-sharing-howto]]
 
 The wiki URL is as below:
 [http://www.freedesktop.org/wiki/Software/Beignet/](http://www.freedesktop.org/wiki/Software/Beignet/)
diff --git a/docs/howto/libva-buffer-sharing-howto.mdwn b/docs/howto/libva-buffer-sharing-howto.mdwn
new file mode 100644
index 0000000..94f1631
--- /dev/null
+++ b/docs/howto/libva-buffer-sharing-howto.mdwn
@@ -0,0 +1,66 @@
+Libva Buffer Sharing HowTo
+==========================
+
+Beignet has extensions 
+(clCreateBufferFromLibvaIntel/clCreateImageFromLibvaIntel)
+to share gpu buffer object with libva. So users can utilize OpenCL to 
+do processing on VASurface or VABuffer without buffer copy.
+
+Prerequisite
+-----------------------------------
+
+Libva api version >= 0.36.0. Please check your libva api version by 
+command `pkg-config --modversion libva`.
+
+Steps
+---------------------------------------------------------
+
+In order to use the extension 
+clCreateBufferFromLibvaIntel/clCreateImageFromLibvaIntel
+in your program, please follow the steps as below (We have added an 
+example of using clCreateImageFromLibvaIntel, please read next section for details):
+
+- Get the address of this extension by the function:
+  clGetExtensionFunctionAddress("clCreateBufferFromLibvaIntel")
+  or clGetExtensionFunctionAddress("clCreateImageFromLibvaIntel")
+
+- Invoke vaAcquireBufferHandle to get VASurface/VABuffer's handle, 
+which you want
+  to do processing by OpenCL.
+
+- Use clCreateBufferFromLibvaIntel/clCreateImageFromLibvaIntel to 
+create corresponding
+  cl memory object from VASurface/VABuffer's handle. You should use 
+clCreateImageFromLibvaIntel
+  to create a cl image object from VASurface, because VASurface is a 
+tiling gpu buffer
+  object. And we suggest use clCreateBufferFromLibvaIntel to create a 
+cl buffer object
+  from VABuffer.
+
+- Use OpenCL to do post-processing.
+
+- Release this cl buffer object by clReleaseMemObject.
+
+- Unlock this VABuffer by vaReleaseBufferHandle.
+
+Sample code
+-------------------------------------------------
+
+We have developed an example of using clCreateImageFromLibvaIntel in 
+examples/libva_buffer_sharing directory. This example read a source nv12 file to a VASurface, and create a target VASurface.
+Then create corresponding cl image objects from them. After using ocl 
+to change this VASurface to a gray image, target VASurface is saved as a file.
+
+- 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-libva_buffer_sharing`
+
+You can use gst-launch-1.0 to see the result(nv12 image). Just install 
+gstreamer1.0-plugins-base, gstreamer1.0-plugins-bad and gstreamer1.0-x 
+by apt on Ubuntu. Then running the following
+command:
+  `> gst-launch-1.0 filesrc location=file_name ! videoparse format=nv12 width=xxx height=xxx \
+   ! imagefreeze ! videoconvert ! video/x-raw, format=BGRx ! 
+ximagesink`
+  
--
1.9.1