lavfi: Add coreimage filter for GPU based image filtering on OSX.

1 files changed, 166 insertions, 0 deletions

diff --git a/doc/filters.texi b/doc/filters.texi
index e6ffbed65a..528e0f8012 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -4955,6 +4955,111 @@ convolution="-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 -
 Copy the input source unchanged to the output. This is mainly useful for
 testing purposes.
 
+@anchor{coreimage}
+@section coreimage
+Video filtering on GPU using Apple's CoreImage API on OSX.
+
+Hardware acceleration is based on an OpenGL context. Usually, this means it is
+processed by video hardware. However, software-based OpenGL implementations
+exist which means there is no guarantee for hardware processing. It depends on
+the respective OSX.
+
+There are many filters and image generators provided by Apple that come with a
+large variety of options. The filter has to be referenced by its name along
+with its options.
+
+The coreimage filter accepts the following options:
+@table @option
+@item list_filters
+List all available filters and generators along with all their respective
+options as well as possible minimum and maximum values along with the default
+values.
+@example
+list_filters=true
+@end example
+
+@item filter
+Specify all filters by their respective name and options.
+Use @var{list_filters} to determine all valid filter names and options.
+Numerical options are specified by a float value and are automatically clamped
+to their respective value range.  Vector and color options have to be specified
+by a list of space separated float values. Character escaping has to be done.
+A special option name @code{default} is available to use default options for a
+filter.
+
+It is required to specify either @code{default} or at least one of the filter options.
+All omitted options are used with their default values.
+The syntax of the filter string is as follows:
+@example
+filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
+@end example
+
+@item output_rect
+Specify a rectangle where the output of the filter chain is copied into the
+input image. It is given by a list of space separated float values:
+@example
+output_rect=x\ y\ width\ height
+@end example
+If not given, the output rectangle equals the dimensions of the input image.
+The output rectangle is automatically cropped at the borders of the input
+image. Negative values are valid for each component.
+@example
+output_rect=25\ 25\ 100\ 100
+@end example
+@end table
+
+Several filters can be chained for successive processing without GPU-HOST
+transfers allowing for fast processing of complex filter chains.
+Currently, only filters with zero (generators) or exactly one (filters) input
+image and one output image are supported. Also, transition filters are not yet
+usable as intended.
+
+Some filters generate output images with additional padding depending on the
+respective filter kernel. The padding is automatically removed to ensure the
+filter output has the same size as the input image.
+
+For image generators, the size of the output image is determined by the
+previous output image of the filter chain or the input image of the whole
+filterchain, respectively. The generators do not use the pixel information of
+this image to generate their output. However, the generated output is
+blended onto this image, resulting in partial or complete coverage of the
+output image.
+
+The @ref{coreimagesrc} video source can be used for generating input images
+which are directly fed into the filter chain. By using it, providing input
+images by another video source or an input video is not required.
+
+@subsection Examples
+
+@itemize
+
+@item
+List all filters available:
+@example
+coreimage=list_filters=true
+@end example
+
+@item
+Use the CIBoxBlur filter with default options to blur an image:
+@example
+coreimage=filter=CIBoxBlur@@default
+@end example
+
+@item
+Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
+its center at 100x100 and a radius of 50 pixels:
+@example
+coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
+@end example
+
+@item
+Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
+given as complete and escaped command-line for Apple's standard bash shell:
+@example
+ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
+@end example
+@end itemize
+
 @section crop
 
 Crop the input video to given dimensions.
@@ -13798,6 +13903,67 @@ cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
 
 @end itemize
 
+@anchor{coreimagesrc}
+@section coreimagesrc
+Video source generated on GPU using Apple's CoreImage API on OSX.
+
+This video source is a specialized version of the @ref{coreimage} video filter.
+Use a core image generator at the beginning of the applied filterchain to
+generate the content.
+
+The coreimagesrc video source accepts the following options:
+@table @option
+@item list_generators
+List all available generators along with all their respective options as well as
+possible minimum and maximum values along with the default values.
+@example
+list_generators=true
+@end example
+
+@item size, s
+Specify the size of the sourced video. For the syntax of this option, check the
+@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
+The default value is @code{320x240}.
+
+@item rate, r
+Specify the frame rate of the sourced video, as the number of frames
+generated per second. It has to be a string in the format
+@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
+number or a valid video frame rate abbreviation. The default value is
+"25".
+
+@item sar
+Set the sample aspect ratio of the sourced video.
+
+@item duration, d
+Set the duration of the sourced video. See
+@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
+for the accepted syntax.
+
+If not specified, or the expressed duration is negative, the video is
+supposed to be generated forever.
+@end table
+
+Additionally, all options of the @ref{coreimage} video filter are accepted.
+A complete filterchain can be used for further processing of the
+generated input without CPU-HOST transfer. See @ref{coreimage} documentation
+and examples for details.
+
+@subsection Examples
+
+@itemize
+
+@item
+Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
+given as complete and escaped command-line for Apple's standard bash shell:
+@example
+ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
+@end example
+This example is equivalent to the QRCode example of @ref{coreimage} without the
+need for a nullsrc video source.
+@end itemize
+
+
 @section mandelbrot
 
 Generate a Mandelbrot set fractal, and progressively zoom towards the