From 6bac55527bffae0cfdd7d9139f735d28155df4fc Mon Sep 17 00:00:00 2001
From: Lynne <dev@lynne.ee>
Date: Sun, 28 May 2023 17:34:29 +0200
Subject: [PATCH] doc/filtering: document some Vulkan filters
This commit documents some of the Vulkan filters. Some of this was
copy-pasted from equivalent OpenCL filters.
---
doc/filters.texi | 262 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 262 insertions(+)
@@ -9089,6 +9089,7 @@ boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chrom
@end example
@end itemize
+@anchor{bwdif}
@section bwdif
Deinterlace the input video ("bwdif" stands for "Bob Weaver
@@ -26356,6 +26357,7 @@ Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 s
@end example
@end itemize
+@anchor{nlmeans_opencl}
@section nlmeans_opencl
Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
@@ -27184,6 +27186,266 @@ See @ref{xstack}.
@c man end VAAPI VIDEO FILTERS
+@chapter Vulkan Video Filters
+@c man begin VULKAN VIDEO FILTERS
+
+Below is a description of the currently available Vulkan video filters.
+
+To enable compilation of these filters you need to configure FFmpeg with
+@code{--enable-vulkan} and either @code{--enable-libglslang} or @code{--enable-libshaderc}.
+
+Running Vulkan filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
+@table @option
+
+@item -init_hw_device vulkan[=@var{name}][:@var{device}[,@var{key=value}...]]
+Initialise a new hardware device of type @var{vulkan} called @var{name}, using the
+given device parameters and options in @var{key=value}.
+If @code{debug=1} is used as an option, the Vulkan validation layer will be enabled.
+
+@item -filter_hw_device @var{name}
+Pass the hardware device called @var{name} to all filters in any filter graph.
+
+@end table
+
+For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
+
+@itemize
+@item
+Example of choosing the first device and running nlmeans_vulkan filter with default parameters on it.
+@example
+-init_hw_device vulkan=vk:0 -filter_hw_device vk -i INPUT -vf "hwupload,nlmeans_vulkan,hwdownload" OUTPUT
+@end example
+@end itemize
+
+As Vulkan filters are not able to access frame data in normal memory, all frame data needs to be uploaded (@ref{hwupload}) to hardware surfaces connected to the appropriate device before being used and then downloaded (@ref{hwdownload}) back to normal memory. Note that @ref{hwupload} will upload to a frame with the same layout as the software frame, so it may be necessary to add a @ref{format} filter immediately before to get the input into the right format and @ref{hwdownload} does not support all formats on the output - it is usually necessary to insert an additional @ref{format} filter immediately following in the graph to get the output in a supported format.
+
+@section avgblur_vulkan
+
+Apply an average blur filter, implemented on the GPU using Vulkan.
+
+The filter accepts the following options:
+
+@table @option
+@item sizeX
+Set horizontal radius size.
+Range is @code{[1, 32]} and default value is @code{3}.
+
+@item sizeY
+Set vertical radius size. Range is @code{[1, 32]} and default value is @code{3}.
+
+@item planes
+Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
+@end table
+
+@section blend_vulkan
+
+Blend two Vulkan frames into each other.
+
+The @code{blend} filter takes two input streams and outputs one
+stream, the first input is the "top" layer and second input is
+"bottom" layer. By default, the output terminates when the longest input terminates.
+
+A description of the accepted options follows.
+
+@table @option
+@item c0_mode
+@item c1_mode
+@item c2_mode
+@item c3_mode
+@item all_mode
+Set blend mode for specific pixel component or all pixel components in case
+of @var{all_mode}. Default value is @code{normal}.
+
+Available values for component modes are:
+@table @samp
+@item normal
+@item multiply
+@end table
+
+@end table
+
+@section bwdif_vulkan
+
+Deinterlacer using @ref{bwdif}, the "Bob Weaver Deinterlacing Filter" algorithm, implemented
+on the GPU using Vulkan.
+
+It accepts the following parameters:
+
+@table @option
+@item mode
+The interlacing mode to adopt. It accepts one of the following values:
+
+@table @option
+@item 0, send_frame
+Output one frame for each frame.
+@item 1, send_field
+Output one frame for each field.
+@end table
+
+The default value is @code{send_field}.
+
+@item parity
+The picture field parity assumed for the input interlaced video. It accepts one
+of the following values:
+
+@table @option
+@item 0, tff
+Assume the top field is first.
+@item 1, bff
+Assume the bottom field is first.
+@item -1, auto
+Enable automatic detection of field parity.
+@end table
+
+The default value is @code{auto}.
+If the interlacing is unknown or the decoder does not export this information,
+top field first will be assumed.
+
+@item deint
+Specify which frames to deinterlace. Accepts one of the following
+values:
+
+@table @option
+@item 0, all
+Deinterlace all frames.
+@item 1, interlaced
+Only deinterlace frames marked as interlaced.
+@end table
+
+The default value is @code{all}.
+@end table
+
+@section color_vulkan
+
+Video source that creates a Vulkan frame of a solid color.
+Useful for benchmarking, or overlaying.
+
+It accepts the following parameters:
+
+@table @option
+@item color
+The color to use. Either a name, or a hexadecimal value.
+The default value is @code{black}.
+
+@item size
+The size of the output frame. Default value is @code{1920x1080}.
+
+@item rate
+The framerate to output at. Default value is @code{60} frames per second.
+
+@item duration
+The video duration. Default value is @code{-0.000001}.
+
+@item sar
+The video signal aspect ratio. Default value is @code{1/1}.
+
+@item format
+The pixel format of the output Vulkan frames. Default value is @code{yuv444p}.
+
+@item out_range
+Set the output YCbCr sample range.
+
+This allows the autodetected value to be overridden as well as allows forcing
+a specific value used for the output and encoder. If not specified, the
+range depends on the pixel format. Possible values:
+
+@table @samp
+@item auto/unknown
+Choose automatically.
+
+@item jpeg/full/pc
+Set full range (0-255 in case of 8-bit luma).
+
+@item mpeg/limited/tv
+Set "MPEG" range (16-235 in case of 8-bit luma).
+@end table
+
+@end table
+
+@section nlmeans_vulkan
+
+Denoise frames using Non-Local Means algorithm, implemented on the GPU using
+Vulkan.
+Supports more pixel formats than @ref{nlmeans} or @ref{nlmeans_opencl}, including
+alpha channel support.
+
+The filter accepts the following options.
+
+@table @option
+@item s
+Set denoising strength for all components. Default is 1.0. Must be in range [1.0, 100.0].
+
+@item p
+Set patch size for all planes. Default is 7. Must be odd number in range [0, 99].
+
+@item r
+Set research size. Default is 15. Must be odd number in range [0, 99].
+
+@item t
+Set parallelism. Default is 36. Must be a number in the range [1, 168].
+Larger values may speed up processing, at the cost of more VRAM.
+Lower values will slow it down, reducing VRAM usage.
+Only supported on GPUs with atomic float operations (RDNA3+, Ampere+).
+
+@item s0
+@item s1
+@item s2
+@item s3
+Set denoising strength for a specific component. Default is @var{1}, equal to @option{s}.
+Must be odd number in range [1, 100].
+
+@item p0
+@item p1
+@item p2
+@item p3
+Set patch size for a specific component. Default is @var{7}, equal to @option{p}.
+Must be odd number in range [0, 99].
+
+@end table
+
+@section transpose_vulkan
+
+Transpose rows with columns in the input video and optionally flip it.
+For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
+
+It accepts the following parameters:
+
+@table @option
+
+@item dir
+Specify the transposition direction.
+
+Can assume the following values:
+@table @samp
+@item cclock_flip
+Rotate by 90 degrees counterclockwise and vertically flip. (default)
+
+@item clock
+Rotate by 90 degrees clockwise.
+
+@item cclock
+Rotate by 90 degrees counterclockwise.
+
+@item clock_flip
+Rotate by 90 degrees clockwise and vertically flip.
+@end table
+
+@item passthrough
+Do not apply the transposition if the input geometry matches the one
+specified by the specified value. It accepts the following values:
+@table @samp
+@item none
+Always apply transposition. (default)
+@item portrait
+Preserve portrait geometry (when @var{height} >= @var{width}).
+@item landscape
+Preserve landscape geometry (when @var{width} >= @var{height}).
+@end table
+
+@end table
+
+@c man end VULKAN VIDEO FILTERS
+
@chapter QSV Video Filters
@c man begin QSV VIDEO FILTERS
--
2.40.1