doc: Document hwupload, hwdownload and hwmap filters

This commit is contained in:
Mark Thompson 2017-04-30 22:11:54 +01:00
parent 7c35bee025
commit 66aa9b94da
1 changed files with 98 additions and 0 deletions

View File

@ -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.