Update the README for extensional video post-processingcl_branch

Signed-off-by: Zhao Yakui <yakui.zhao@intel.com>

1 files changed, 92 insertions, 0 deletions

diff --git a/README b/README
index 09ee0b3..c0fab3c 100644
--- a/README
+++ b/README
@@ -37,3 +37,95 @@ Requirements
 ------------
 
 libva >= 1.0.16
+
+------------
+Extensional Video post-processing
+
+Now this supports the extensional video post-processing based on OpenCL. If you
+hope to use the extensional video post-processing, please add the following extra
+configure option:
+   --enable-opencl
+
+As the extensional video post-processing is implemented based on OpenCL, please
+make sure that the following components should be installed:
+	opencl library: 
+	ICD-ocl wrapper library and configuration(/etc/OpenCL/Vendors/intel.icd):
+
+Section 1: How to use the extensional video post-processing
+
+The following will describe how to use the extensional video post-processing.
+Step A. query the filter of VAProcFilterExtVPP to decide whether the extensional
+video post-processing is supported. If the VAProcFilterExtVPP is returned, it
+indicates that the extensional video post-processing is supported.
+
+Step B. Register the customed opencl kernel into the driver and the kernel ID
+is returned for the next step
+        vaRegisterExtVPPShader(display, context, vppext_shader *, &kernel_id);
+        The vppext_shader is defined in the intel_vppext.h
+
+	In order to register the opencl shader, the parameter of kernel should
+follow the rules in src/opencl/opencl_kernel.txt. Otherwise it can't be
+registered/executed as expected.
+	Currently the driver will inline several shaders. And it can be
+queried by using vaQueryVideoInlineExtVPP. The corresponding kernel ID is
+also returned. 
+
+Step C: Call the normal VPP calling sequence to do the extensional VPP
+	>vaBeginPicture
+	>vaRenderPicture
+	>vaEndPicture
+	
+	The parameter for extensional VPP is passed by vaRenderPicture. And it
+is defined libva/va/va_vpp.h(VAProcExtParameterBuffer). The returned kernel ID
+in step B is used for the ocl_ext_typeid of VAProcExtParameterBuffer.
+
+Of course currently the driver provides some demo examples about the
+extensional video post-processing. After the driver is installed with
+extensional VPP supported,we can see the corresponding effect by using 
+mplayer command like the below:
+	mplayer -vo vaapi:scaling=fast -va vaapi XXX
+    And the INTEL_OCL environmental variable can be set to select which effect
+is used.
+      export INTEL_OCL="mirror": It will apply the mirror effect on the decoded image.
+      export INTEL_OCL="blur": It will apply the blur effect on the decoded image.
+      export INTEL_OCL="gray": It will apply the gray effect on the decoded image.
+      export INTEL_OCL="pixelated" : It will apply the pixelated effect on decoded image.
+
+Section 2: Usage note about the some APIs related with extensional VPP
+     Currently the vaRegisterExtVPPShader/vaUnregisterExtVPPShader/
+vaQueryVideoInlineExtVPP is defined as the driver-private API and they should
+be obtained by using vaGetLibFunc().
+The following is the example:
+	The header file of intel_vppext.h is included.
+
+	>vaRegisterExtVPPShader_FUNC vaRegisterExtVPPShader =
+			vaGetLibFunc(dpy,"vaRegisterExtVPPShader");
+	>vaUnregisterExtVPPShader_FUNC vaUnregisterExtVPPShader =
+			vaGetLibFunc(dpy,"vaUnregisterExtVPPShader");
+	>vaQueryVideoInlineExtVPP_FUNC vaQueryVideInlineExtVPP =
+			vaGetLibFunc(dpy,"vaQueryVideoInlineExtVPP");
+
+Section 3: How to add one inline extennsional VPP shader
+
+The following section will describe how to add one inlined extensional VPP
+shader
+       1. Please follow the rules in src/opencl_kernel.txt and develop the
+shader
+       2. Put the shader into the directory of src/opencl/ and edit the
+vpp_kernels array in src/vpp_opencl.c
+       3. Use the vaQueryVideoInlineExtVPP to query the inlined GPU shader
+and then follow the step in the section 1.
+     
+       Of course it also uses the hacked mechanism to check the corresponding
+VPP effect without rewriting the application. 
+	4. Add some code in src/i965_post_processing.c as the following:
+		> if (!strcmp(ocl_test, "XXXX"))
+			ocl_id = xxxx;
+		Recompile the libva driver and install it.
+	5. export INTEL_OCL="XXXX" and then use the corresponding command
+mentioned in section 1 to check the VPP effect.
+
+Cheers
+
+
+