diff mbox

[FFmpeg-devel,24/24] doc: Document hwupload, hwdownload and hwmap filters

Message ID 20170612224041.6750-25-sw@jkqxz.net
State Accepted
Commit 5de38188f82ac21fc645009dbb6c593049eb773d
Headers show

Commit Message

Mark Thompson June 12, 2017, 10:40 p.m. UTC
(cherry picked from commit 66aa9b94dae217a0fc5acfb704490707629d95ed)
 doc/filters.texi | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
diff mbox


diff --git a/doc/filters.texi b/doc/filters.texi
index 023096f4e0..db0bdfe254 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -9040,6 +9040,104 @@  A floating point number which specifies chroma temporal strength. It defaults to
 @end table
+@section hwdownload
+Download hardware frames to system memory.
+The input must be in hardware frames, and the output a non-hardware format.
+Not all formats will be supported on the output - it may be necessary to insert
+an additional @option{format} filter immediately following in the graph to get
+the output in a supported format.
+@section hwmap
+Map hardware frames to system memory or to another device.
+This filter has several different modes of operation; which one is used depends
+on the input and output formats:
+Hardware frame input, normal frame output
+Map the input frames to system memory and pass them to the output.  If the
+original hardware frame is later required (for example, after overlaying
+something else on part of it), the @option{hwmap} filter can be used again
+in the next mode to retrieve it.
+Normal frame input, hardware frame output
+If the input is actually a software-mapped hardware frame, then unmap it -
+that is, return the original hardware frame.
+Otherwise, a device must be provided.  Create new hardware surfaces on that
+device for the output, then map them back to the software format at the input
+and give those frames to the preceding filter.  This will then act like the
+@option{hwupload} filter, but may be able to avoid an additional copy when
+the input is already in a compatible format.
+Hardware frame input and output
+A device must be supplied for the output, either directly or with the
+@option{derive_device} option.  The input and output devices must be of
+different types and compatible - the exact meaning of this is
+system-dependent, but typically it means that they must refer to the same
+underlying hardware context (for example, refer to the same graphics card).
+If the input frames were originally created on the output device, then unmap
+to retrieve the original frames.
+Otherwise, map the frames to the output device - create new hardware frames
+on the output corresponding to the frames on the input.
+@end itemize
+The following additional parameters are accepted:
+@table @option
+@item mode
+Set the frame mapping mode.  Some combination of:
+@table @var
+@item read
+The mapped frame should be readable.
+@item write
+The mapped frame should be writeable.
+@item overwrite
+The mapping will always overwrite the entire frame.
+This may improve performance in some cases, as the original contents of the
+frame need not be loaded.
+@item direct
+The mapping must not involve any copying.
+Indirect mappings to copies of frames are created in some cases where either
+direct mapping is not possible or it would have unexpected properties.
+Setting this flag ensures that the mapping is direct and will fail if that is
+not possible.
+@end table
+Defaults to @var{read+write} if not specified.
+@item derive_device @var{type}
+Rather than using the device supplied at initialisation, instead derive a new
+device of type @var{type} from the device the input frames exist on.
+@item reverse
+In a hardware to hardware mapping, map in reverse - create frames in the sink
+and map them back to the source.  This may be necessary in some cases where
+a mapping in one direction is required but only the opposite direction is
+supported by the devices being used.
+This option is dangerous - it may break the preceding filter in undefined
+ways if there are any additional constraints on that filter's output.
+Do not use it without fully understanding the implications of its use.
+@end table
+@section hwupload
+Upload system memory frames to hardware surfaces.
+The device to upload to must be supplied when the filter is initialised.  If
+using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
 @section hwupload_cuda