diff options
1 files changed, 67 insertions, 0 deletions
diff --git a/Software/Beignet/howto/libva-buffer-sharing-howto.mdwn b/Software/Beignet/howto/libva-buffer-sharing-howto.mdwn
new file mode 100644
index 00000000..fe64d73a
--- /dev/null
+++ b/Software/Beignet/howto/libva-buffer-sharing-howto.mdwn
@@ -0,0 +1,67 @@
+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.
+Libva api version >= 0.36.0. Please check your libva api version by command
+`pkg-config --modversion libva`.
+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. If you create a normal VASurface,
+ you should use clCreateImageFromLibvaIntel to create a cl image object from VASurface,
+ because VASurface is a tiling gpu buffer object. The only case you should use
+ clCreateBufferFromLibvaIntel to create a cl buffer object from VASurface is that: The
+ VASurface is created from an external untiling gpu buffer object. And You should 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 do a mirror effect
+post-processing on this source surface, target VASurface is shown on screen by default.
+- 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/`
+ `> ./example-libva_buffer_sharing`
+In addition, you can choose to save the result as a nv12 file. You can use gst-launch-1.0 to see
+the result. 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`