FFmpeg/doc
Kevin Mark 3385989b98 libavfilter/scale2ref: Add constants for the primary input
Variables pertaining to the main video are now available when
using the scale2ref filter. This allows, as an example, scaling a
video with another as a reference point while maintaining the
original aspect ratio of the primary/non-reference video.

Consider the following graph: scale2ref=iw/6:-1 [main][ref]
This will scale [main] to 1/6 the width of [ref] while maintaining
the aspect ratio. This works well when the AR of [ref] is equal to
the AR of [main] only. What the above filter really does is
maintain the AR of [ref] when scaling [main]. So in all non-same-AR
situations [main] will appear stretched or compressed to conform to
the same AR of the reference video. Without doing this calculation
externally there is no way to scale in reference to another input
while maintaining AR in libavfilter.

To make this possible, we introduce eight new constants to be used
in the w and h expressions only in the scale2ref filter:

 * main_w/main_h: width/height of the main input video
 * main_a: aspect ratio of the main input video
 * main_sar: sample aspect ratio of the main input video
 * main_dar: display aspect ratio of the main input video
 * main_hsub/main_vsub: horiz/vert chroma subsample vals of main
 * mdar: a shorthand alias of main_dar

Of course, not all of these constants are needed for maintaining the
AR, but adding additional constants in line of what is available for
in/out allows for other scaling possibilities I have not imagined.

So to now scale a video to 1/6 the size of another video using the
width and maintaining its own aspect ratio you can do this:

scale2ref=iw/6:ow/mdar [main][ref]

This is ideal for picture-in-picture configurations where you could
have a square or 4:3 video overlaid on a corner of a larger 16:9
feed all while keeping the scaled video in the corner at its correct
aspect ratio and always the same size relative to the larger video.

I've tried to re-use as much code as possible. I could not find a way
to avoid duplication of the var_names array. It must now be kept in
sync with the other (the normal one and the scale2ref one) for
everything to work which does not seem ideal. For every new variable
introduced/removed into/from the normal scale filter one must be
added/removed to/from the scale2ref version. Suggestions on how to
avoid var_names duplication are welcome.

var_values has been increased to always be large enough for the
additional scale2ref variables. I do not forsee this being a problem
as the names variable will always be the correct size. From my
understanding of av_expr_parse_and_eval it will stop processing
variables when it runs out of names even though there may be
additional (potentially uninitialized) entries in the values array.
The ideal solution here would be using a variable-length array but
that is unsupported in C90.

This patch does not remove any functionality and is strictly a
feature patch. There are no API changes. Behavior does not change for
any previously valid inputs.

The applicable documentation has also been updated.

Signed-off-by: Kevin Mark <kmark937@gmail.com>
Signed-off-by: Michael Niedermayer <michael@niedermayer.cc>
2017-06-01 22:56:08 +02:00
..
doxy Merge commit '257f00ec1ab06a2a161f535036c6512f3fc8e801' 2016-06-22 11:28:51 +02:00
examples examples/encode_video: slightly improve error reporting 2017-05-31 15:46:19 +02:00
.gitignore Merge commit '257f00ec1ab06a2a161f535036c6512f3fc8e801' 2016-06-22 11:28:51 +02:00
APIchanges videotoolbox: add hwcontext support 2017-05-15 11:30:36 +02:00
authors.texi
bitstream_filters.texi Merge commit '03a80925effc2698d21dc0b00290eecf42dd9e68' 2017-04-22 23:27:05 -03:00
bootstrap.min.css
build_system.txt doc/build_system: Document how to build decoder fuzzer 2017-05-08 17:02:02 +02:00
codecs.texi doc/codecs: Change common boolean parameters listed to "bool" 2017-05-10 14:00:20 +02:00
decoders.texi cosmetics: fix some misspelled words 2016-07-17 13:10:27 -03:00
default.css
demuxers.texi doc: Add muxers/demuxers list option 2017-02-11 02:59:32 +01:00
developer.texi doc/developer: Add terse documentation of assumed C implementation defined behavior 2017-05-01 17:59:10 +02:00
devices.texi
doxy-wrapper.sh
Doxyfile doc: fix spelling errors 2016-10-21 23:58:47 +02:00
encoders.texi libvpxenc: allow aq-mode 4 (equator360) 2017-04-28 17:56:09 -07:00
errno.txt
faq.texi faq: use relative links to own documentation 2016-10-23 11:55:53 +02:00
fate_config.sh.template Merge commit '35d1f726eb9fdd376ab900587fb02122b72f2b9a' 2017-05-05 09:27:18 +02:00
fate.texi Merge commit '963b3ab11f98fcc4a311f0dc7b268890c5675da2' 2017-03-19 18:34:48 +01:00
ffmpeg-bitstream-filters.texi
ffmpeg-codecs.texi
ffmpeg-devices.texi
ffmpeg-filters.texi
ffmpeg-formats.texi
ffmpeg-protocols.texi
ffmpeg-resampler.texi
ffmpeg-scaler.texi
ffmpeg-utils.texi
ffmpeg.texi ffmpeg: add enc_time_base option 2017-05-10 14:00:20 +02:00
ffmpeg.txt
ffplay.texi ffplay: allow borderless playback windows 2017-02-01 22:03:26 +01:00
ffprobe.texi doc/ffprobe: add -show_log option 2017-03-28 00:13:47 +02:00
ffprobe.xsd ffprobe.xsd: add frame log data 2017-03-28 00:13:47 +02:00
ffserver.conf lavc: remove libfaac wrapper 2016-10-01 19:58:04 +01:00
ffserver.texi
fftools-common-opts.texi doc/fftools-common-opts: Fixed a typo in the common arguments list 2017-04-18 02:50:06 +02:00
filter_design.txt
filters.texi libavfilter/scale2ref: Add constants for the primary input 2017-06-01 22:56:08 +02:00
formats.texi avformat: Add max_streams option 2016-12-08 18:25:30 +01:00
general.texi lavc: remove libschroedinger encoding and decoding wrappers 2017-05-29 20:15:58 +01:00
git-howto.texi Merge commit '41ed7ab45fc693f7d7fc35664c0233f4c32d69bb' 2016-06-21 21:55:34 +02:00
indevs.texi avdevice/decklink: new option 'format_code' to set video format by fourCC 2017-03-22 02:07:50 +01:00
issue_tracker.txt
lexicon doc: add a lexicon 2017-02-03 15:03:44 +01:00
libav-merge.txt doc/libav-merge: remove lines about AVFrame crop fields 2017-05-26 11:22:23 -03:00
libavcodec.texi
libavdevice.texi
libavfilter.texi
libavformat.texi
libavutil.texi
libswresample.texi
libswscale.texi
Makefile Merge commit '11a9320de54759340531177c9f2b1e31e6112cc2' 2017-05-03 16:49:12 +02:00
metadata.texi
mips.txt
multithreading.txt
muxers.texi avformat/hlsenc: add hls encrypt options 2017-04-14 23:30:29 +08:00
nut.texi Merge commit '41ed7ab45fc693f7d7fc35664c0233f4c32d69bb' 2016-06-21 21:55:34 +02:00
optimization.txt Merge commit '2ec9fa5ec60dcd10e1cb10d8b4e4437e634ea428' 2017-03-21 14:29:52 -03:00
outdevs.texi avdevice/decklink_enc: add support to specify field order 2017-02-26 22:47:33 +01:00
patchwork doc/patchwork: Document the patchwork states 2016-10-26 19:46:00 +02:00
platform.texi lavc: remove libschroedinger encoding and decoding wrappers 2017-05-29 20:15:58 +01:00
print_options.c Merge commit '2025d3787158ba272a1b8fbc0493fa20dd7a8484' 2017-03-29 15:20:10 +02:00
protocols.texi doc/protocols: add option usage description 2017-02-13 12:23:03 -09:00
rate_distortion.txt
resampler.texi swresample/options: enable linear_interp and exact_rational by default 2017-03-17 00:08:03 +07:00
scaler.texi doc/scaler: mention default scaling algorithm 2017-01-09 12:58:25 -09:00
snow.txt
style.min.css
swresample.txt
swscale.txt
t2h.init doc/t2h: use container 2016-10-03 00:16:27 +01:00
t2h.pm doc/t2h: use container 2016-10-03 00:16:27 +01:00
tablegen.txt
texi2pod.pl doc: escape left brace in texi2pod.pl regex 2016-07-10 13:34:57 +02:00
texidep.pl
utils.texi avutil/eval: add atan2 function 2017-01-30 11:04:31 +01:00
writing_filters.txt Merge commit '11a9320de54759340531177c9f2b1e31e6112cc2' 2017-05-03 16:49:12 +02:00