[FFmpeg-devel] doc/filters: add documentation to all existing OpenCL filters, except tonemap filter

Add documentation to all existing OpenCL filters, except tonemap filter.

---
Creation of the seperate section for OpenCL filters is motivated by developing support for Vulkan and CUDA and it is easier to show the capabilities of each platform by adding new sections.

 doc/filters.texi | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 193 insertions(+)

On Tue, Jul 3, 2018 at 10:51 AM Danil Iashchenko <danyaschenko@gmail.com> wrote:
>
> Add documentation to all existing OpenCL filters, except tonemap filter.
>
> ---
> Creation of the seperate section for OpenCL filters is motivated by developing support for Vulkan and CUDA and it is easier to show the capabilities of each platform by adding new sections.
>
>  doc/filters.texi | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 193 insertions(+)
>
> diff --git a/doc/filters.texi b/doc/filters.texi
> index fb5f3ee..3e18e5c 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -5423,6 +5423,7 @@ number in range [5, 129].
>  Set what planes of frame filter will use for averaging. Default is all.
>  @end table
>
> +@anchor{avgblur}
>  @section avgblur
>
>  Apply average blur filter.
> @@ -5715,6 +5716,7 @@ tblend=all_mode=grainextract
>  @end example
>  @end itemize
>
> +@anchor{boxblur}
>  @section boxblur
>
>  Apply a boxblur algorithm to the input video.
> @@ -6551,6 +6553,7 @@ For example to convert the input to SMPTE-240M, use the command:
>  colorspace=smpte240m
>  @end example
>
> +@anchor{convolution}
>  @section convolution
>
>  Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
> @@ -12900,6 +12903,7 @@ By default value 0xf, all planes will be processed.
>  Do not require 2nd input for processing, instead use alpha plane from input stream.
>  @end table
>
> +@anchor{prewitt}
>  @section prewitt
>  Apply prewitt operator to input video stream.
>
> @@ -13591,6 +13595,7 @@ trim=end=5,reverse
>  @end example
>  @end itemize
>
> +@anchor{roberts}
>  @section roberts
>  Apply roberts cross operator to input video stream.
>
> @@ -15176,6 +15181,7 @@ asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
>  @end example
>  @end itemize
>
> +@anchor{sobel}
>  @section sobel
>  Apply sobel operator to input video stream.
>
> @@ -17422,6 +17428,193 @@ pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
>
>  @c man end VIDEO FILTERS
>
> +@chapter OpenCL Video Filters
> +@c man begin OPENCL VIDEO FILTERS
> +
> +Below is a description of the currently available OpenCL video filters.
> +
> +To enable compilation of these filters you need to configure FFmpeg with
> +@code{--enable-opencl}.
> +
> +@section avgblur_opencl
> +
> +Apply average blur filter.
> +
> +Works like existing @ref{avgblur} filter.
> +
> +@subsection Example
> +
> +@itemize
> +@item
> +Apply average blur filter with sizeX and sizeY set to 3
> +@example
> +-i INPUT -filter_complex "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
> +@end example
> +@end itemize
> +
> +@section boxblur_opencl
> +
> +Apply a boxblur algorithm to the input video.
> +
> +Works like existing @ref{boxblur} filter.
> +
> +@subsection Examples
> +
> +@itemize
> +@item
> +Apply a boxblur filter with the luma, chroma, and alpha radius
> +set to 2:
> +@example
> +-i INPUT -filter_complex "hwupload, boxblur_opencl=luma_radius=2:luma_power=1, hwdownload" OUTPUT
> +-i INPUT -filter_complex "hwupload, boxblur_opencl=2:1, hwdownload" OUTPUT
> +@end example
> +
> +@item
> +Set the luma radius to 2, and alpha and chroma radius to 0:
> +@example
> +-i INPUT -filter_complex "hwupload, boxblur_opencl=2:1:cr=0:ar=0, hwdownload" OUTPUT
> +@end example
> +
> +@item
> +Set the luma and chroma radius to a fraction of the video dimension:
> +@example
> +-i INPUT -filter_complex "hwupload, boxblur_opencl=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1, hwdownload" OUTPUT
> +@end example
> +@end itemize
> +
> +@section convolution_opencl
> +
> +Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
> +
> +Works like existing @ref{convolution} filter.
> +
> +@subsection Examples
> +
> +@itemize
> +@item
> +Apply sharpen:
> +@example
> +-i INPUT -filter_complex "hwupload, convolution_opencl=0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0, hwdownload" OUTPUT
> +@end example
> +
> +@item
> +Apply blur:
> +@example
> +-i INPUT -filter_complex "hwupload, convolution_opencl=1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9, hwdownload" OUTPUT
> +@end example
> +
> +@item
> +Apply edge enhance:
> +@example
> +-i INPUT -filter_complex "hwupload, convolution_opencl=0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128, hwdownload" OUTPUT
> +@end example
> +
> +@item
> +Apply edge detect:
> +@example
> +-i INPUT -filter_complex "hwupload, convolution_opencl=0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128, hwdownload" OUTPUT
> +@end example
> +
> +@item
> +Apply laplacian edge detector which includes diagonals:
> +@example
> +-i INPUT -filter_complex "hwupload, convolution_opencl=1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0, hwdownload" OUTPUT
> +@end example
> +
> +@item
> +Apply emboss:
> +@example
> +-i INPUT -filter_complex "hwupload, convolution_opencl=-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2, hwdownload" OUTPUT
> +@end example
> +@end itemize
> +
> +@section overlay_opencl
> +
> +Overlay one video on top of another.
> +
> +Works like existing @ref{overlay} filter.
> +
> +@subsection Example
> +
> +@itemize
> +@item
> +Insert a transparent PNG logo in the bottom left corner of the input
> +@example
> +-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a],[1:v]hwupload[b], [a][b]overlay_opencl[out],[out]hwdownload" OUTPUT
> +@end example
> +@end itemize
> +
> +@section prewitt_opencl
> +
> +Apply prewitt operator to input video stream.
> +
> +Works like existing @ref{prewitt} filter.
> +
> +@subsection Example
> +
> +@itemize
> +@item
> +Apply prewitt operator with scale set to 2 and delta set to 10
> +@example
> +-i INPUT -filter_complex "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
> +@end example
> +@end itemize
> +
> +@section roberts_opencl
> +Apply roberts cross operator to input video stream.
> +
> +Works like existing @ref{roberts} filter.
> +
> +@subsection Example
> +
> +@itemize
> +@item
> +Apply roberts cross operator with scale set to 2 and delta set to 10
> +@example
> +-i INPUT -filter_complex "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
> +@end example
> +@end itemize
> +
> +@section sobel_opencl
> +
> +Apply sobel operator to input video stream.
> +
> +Works like existing @ref{sobel} filter.
> +
> +@subsection Example
> +
> +@itemize
> +@item
> +Apply sobel operator with scale set to 2 and delta set to 10
> +@example
> +-i INPUT -filter_complex "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
> +@end example
> +@end itemize
> +
> +@section unsharp_opencl
> +
> +Sharpen or blur the input video.
> +
> +Works like existing @ref{unsharp} filter.
> +
> +@subsection Examples
> +
> +@itemize
> +@item
> +Apply strong luma sharpen effect:
> +@example
> +-i INPUT -filter_complex "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
> +@end example
> +
> +@item
> +Apply a strong blur of both luma and chroma parameters:
> +@example
> +-i INPUT -filter_complex "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
> +@end example
> +@end itemize
> +
> +@c man end OPENCL VIDEO FILTERS
> +
>  @chapter Video Sources
>  @c man begin VIDEO SOURCES
>
> --
> 2.7.4
>
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel@ffmpeg.org
> http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

I like this patch, the other thing, is it have any plan to update
openCL part like VAAPI (https://trac.ffmpeg.org/wiki/Hardware/VAAPI)
in https://trac.ffmpeg.org/wiki/HWAccelIntro, thanks.

On 03-07-2018 08:20 AM, Danil Iashchenko wrote:
> Add documentation to all existing OpenCL filters, except tonemap filter.

Why not for tonemap_opencl?

> +@section avgblur_opencl
> +
> +Apply average blur filter.
> +
> +Works like existing @ref{avgblur} filter.

Since these filters are distinct, please list options as well, since 
their software counterparts could conceivably change. Option entries 
should include default value, range, and semantic.

> +@subsection Example
> +
> +@itemize
> +@item
> +Apply average blur filter with sizeX and sizeY set to 3
> +@example
> +-i INPUT -filter_complex "hwupload, avgblur_opencl=3, hwdownload" OUTPUT

Why are all examples of filters, that operate upon a single stream, 
shown within -filter_complex? '-vf' is preferred.

Thanks,
Gyan

P.S. Once this new section is created, program_opencl entry should be 
shifted there, in a separate patch.