--field: remove the b-adapt restriction, add tests, and document --field and --interlace

[Akilan-Sivakumar]

Summary

Follow-up to the --field work. This PR has three commits:

Commit	Origin	File(s)
Remove the b-adapt restriction for --field	reported by @danielcamposramos in the review of #986	source/common/param.cpp
test: add --field regression tests	#981, #982	source/test/regression-tests.txt
doc: update --field and --interlace documentation	#982	doc/reST/cli.rst, source/x265cli.cpp, source/x265.h

Issues and root cause

1. --field rejected with --b-adapt 0 and the ultrafast to fast presets (from #986)

While testing --frame-packing with --field in #986, @danielcamposramos noticed that --field only works with a nonzero --b-adapt (comment). The regression line added in #986 (--preset veryfast with --field) fails for the same reason, and I agreed to look at the check separately.

x265_check_params has this check, added with --field in 7521fc9 and unchanged since:

CHECK( (param->bFrameAdaptive==0), "Adaptive B-frame decision method should be closed for field feature.\n" );

The condition and the message contradict each other. CHECK fails when b-adapt is 0, but the message says adaptive B-frame decision should be disabled ("closed"). Neither direction is needed: b-adapt only affects the lookahead, which doesn't depend on field coding, and --interlace without --field already encodes fields with b-adapt 0 (ultrafast, superfast, veryfast, faster and fast all set b-adapt 0). As a result, --field failed at startup with those presets for no reason.

2. No regression test covered --field (#981, #982)

None of the CI, smoke or regression tests used --field. That's why the frame skipping and hang in #981, and the pic_struct and bff field order problems in #982, went unnoticed.

3. --field and --interlace were unclear (#982)

The --field documentation only said "Enable or disable field coding". The two options describe different input layouts, and the docs didn't explain that:

• --interlace: the input is already fields (field height, field rate);
• --interlace --field: the input is interlaced frames (both fields woven together), and the CLI splits each frame into its two fields.

The difference came up in the #982 discussion, where it was suggested that --field was redundant with --interlace.

Fix

1. Remove the b-adapt check. --field now works with every preset.

2. Add regression tests using real interlaced content:

   • washdc_422_ntsc.y4m and vtc1nw_422_ntsc.y4m: BFF, 4:2:2.
   • cut_fox_1920x1080_30.yuv: TFF, 4:2:0.

   They cover fast and slow presets, plus --bframes 0:

   # regression-tests.txt
   washdc_422_ntsc.y4m,--preset medium --interlace bff --field
   vtc1nw_422_ntsc.y4m,--preset ultrafast --interlace bff --field
   cut_fox_1920x1080_30.yuv,--preset slow --interlace tff --field
   cut_fox_1920x1080_30.yuv,--preset fast --interlace tff --field --bframes 0
   

3. Document both input layouts in cli.rst, in the --help text of --interlace and --field, and in the x265.h comments for bField and fieldNum. The library-side behaviour is also described: applications pass fields and set fieldNum.

Testing and results

b-adapt check removal. --interlace X --field with the check removed is bit-identical (apart from the options SEI) to --interlace X --no-field on the same frames split into fields with ffmpeg (setfield=X,separatefields):

Content	--b-adapt 0	--preset ultrafast
cut_fox 1080i, TFF, 100 frames	identical, 200 fields	identical, 200 fields
washdc_422_ntsc, BFF, 100 frames	identical, 200 fields	identical, 200 fields

pic_struct is 1/2 with the correct parity in all cases. Before this change, the same commands failed with "Adaptive B-frame decision method should be closed for field feature".

New regression test lines, all 4 run on this branch:

Test	Result
regression: washdc, medium, bff	exit 0, 720 fields, pic_struct 360 × 1 / 360 × 2
regression: vtc1nw, ultrafast, bff	exit 0, 720 fields, pic_struct 360 × 1 / 360 × 2
regression: cut_fox, slow, tff	exit 0, 200 fields, pic_struct 100 × 1 / 100 × 2
regression: cut_fox, fast, --bframes 0, tff	exit 0, 200 fields, pic_struct 100 × 1 / 100 × 2

Build: clean (0 warnings). The doc change only touches comments and help strings.

Related: #981, #982, #986