From 66aa9b94dae217a0fc5acfb704490707629d95ed Mon Sep 17 00:00:00 2001 From: Mark Thompson Date: Sun, 30 Apr 2017 22:11:54 +0100 Subject: [PATCH] doc: Document hwupload, hwdownload and hwmap filters --- doc/filters.texi | 98 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/doc/filters.texi b/doc/filters.texi index 947fd7915c..bd2205a9bd 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -1657,6 +1657,104 @@ A floating point number which specifies chroma temporal strength. It defaults to @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. @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: +@itemize +@item +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. +@item +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. +@item +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 avconv, select the appropriate device with the @option{-filter_hw_device} +option. + @section hwupload_cuda Upload system memory frames to a CUDA device.