ni_quadra_pad

The ni_quadra_pad filter works like the FFmpeg software pad filter but uses the hardware to do the padding.

There are a couple of applications for padding. One is to pad an image so that the width and height are aligned as required by an encoder. This is done automatically by the encoder. The other is to change the aspect ratio of an image by letterboxing, i.e. adding black bars to the top and bottom or left and right of an image. The latter application is what the padding filter will normally be used for.

As with scaling, the 2D Engine can pad an image that already contains padding. The ni_quadra_pad filter is supported for yuv420p, yuv420p10le, nv12, rgba, argb, abgr, bgra, bgr0, nv16. The pixel formats yuyv422 and uyvy422 are not supported inputs like the FFmpeg pad filter.

note

The ni_quadra_pad filter only supports limited color range video (also known as “TV range”). While full range (or “PC” range) video is accepted by the filter, it will clamp the video to limited color range video before processing. This clamping will cause a slight color shift in the output video.

Parameters

The following are the ni_quadra_pad parameters:

width, w

height, h

Specify an expression for the size of the output image with the paddings added. If the value for width or height is 0, the corresponding input size is used for the output.

 x / y

Specifies the offsets to place the input image within the padded area, with respect to the top/left border of the output image. The x expression can reference the value set by the y expression, and vice versa. If x or y evaluate to a negative number, they’ll be changed so the input image is centered on the padded area.

Supported Values	-8192 to 8192
Default	0

The value for the width, height, x, and y options are expressions containing the following constants:

• in_w, in_h, iw, ih
  • The input video width and height.
• out_w, out_hw, ow, oh
  • The output video width and height.
• x, y
  • The x and y offsets as specified by the x and y expressions, or NAN if not yet specified.
• a
  • same as iw / ih
• sar
  • input sample aspect ratio
• dar
  • input display aspect ratio, it is the same as (iw / ih) * sar
• hsub, vsub
  • The horizontal and vertical chroma subsample values. For example for the pixel format "yuv422p" hsub is 2 and vsub is 1.

color

Specify the color of the padded area. It can be a color name or a hex value. For example, black is 0x000000. For the complete syntax of this option, check the FFmpeg help: https://ffmpeg.org/ffmpeg-utils.html#color-syntax

Supported Values	https://ffmpeg.org/ffmpeg-utils.html#color-syntax
Default	0

aspect

Pad to aspect ratio instead of a resolution.

is_p2p

Specifies if output buffer of the filter is p2p buffer. When is_p2p is set to 1, the output buffer of the filter is set as p2p buffer and can be read out by p2p read. Else the output buffer is normal and cannot perform p2p.

Supported Values	Bool 0 and 1
Default	0

keep_alive_timeout

Specifies a session keep alive timeout value. This is a periodic request/response between libxcoder and XCoder firmware that when timed out, terminates the session instance in the XCoder firmware.

Supported Values	Integer in the range 1 to 100
Default	4

buffer_limit

Whether to limit the number of output buffers. If enabled, the buffering count of the filter is its buffer pool size(default 4) plus encoding buffering count if its downstream is encoder. It’s enabled by default in FFmpeg-n6.1, FFmpeg-n7.1, FFmpeg-n8.0.1 and FFmpeg-n8.1.

Supported Values	Integer 0 and 1
Default	0

auto_skip

Specifies if to skip the hardware pad when input is the same as the output. When auto-skip is set to 1, frames will pass through the pad filter and no hardware operations will be executed. When auto_skip is set to 0, hardware scale will always be executed regardless of whether the input is the same as the output.

note

auto-skip is only supported with ffmpeg version > 3.4.2. If ffmpeg version < 3.4.2 the hardware operation will always be skipped when the input in the same as output.

Supported Values	Bool 0 and 1
Default	0

The following shows an example using ni_quadra_pad to change the aspect ratio from ntsc 480p (640x480) to 16:9 480p (852x480). The raw YUV420 planar file input640x480 is uploaded to device 0 as a hardware frame using the ni_quadra_hwupload filter. The ni_quadra_pad filter then pads to 852x480 and puts the original frame at position x=106, y=0. The padding is set to black. The encoder is also collocated on device 0 using -enc -1.

ffmpeg -y -hide_banner -f rawvideo -pix_fmt yuv420p -s:v 640x480 -r 60 -i input640x480.yuv -vf "format=yuv420p,ni_quadra_hwupload=0,ni_quadra_pad=852:480:106:0:0x000000" -enc -1 -c:v h265_ni_quadra_enc -xcoder-params "RcEnable=1:bitrate=10000000" output852x480.265