diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2019-03-09 14:45:54 -0800 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2019-03-09 14:45:54 -0800 |
| commit | 96a6de1a541c86e9e67b9c310c14db4099bd1cbc (patch) | |
| tree | e77eb0e998e996f53dd0709611bd8cdd8776ee70 /Documentation | |
| parent | 36011ddc78395b59a8a418c37f20bcc18828f1ef (diff) | |
| parent | 15d90a6ae98e6d2c68497b44a491cb9efbb98ab1 (diff) | |
| download | linux-96a6de1a541c86e9e67b9c310c14db4099bd1cbc.tar.bz2 | |
Merge tag 'media/v5.1-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab:
- remove sensor drivers that got converted from soc_camera
- remaining soc_camera drivers got moved to staging
- some documentation cleanups and improvements
- the imx staging driver now supports imx7
- the ov9640, mt9m001 and mt9m111 got converted from soc_camera
- the vim2m driver now does what a m2m convert driver expects to do
- epoll() fixes on media subsystems
- several drivers fixes, typos, cleanups and improvements
* tag 'media/v5.1-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (346 commits)
media: dvb/earth-pt1: fix wrong initialization for demod blocks
media: vim2m: Address some coding style issues
media: vim2m: don't use BUG()
media: vim2m: speedup passthrough copy
media: vim2m: add an horizontal scaler
media: vim2m: don't accept YUYV anymore as output format
media: vim2m: add vertical linear scaler
media: vim2m: better handle cap/out buffers with different sizes
media: vim2m: use different framesizes for bayer formats
media: vim2m: add support for VIDIOC_ENUM_FRAMESIZES
media: vim2m: ensure that width is multiple of two
media: vim2m: improve debug messages
media: vim2m: add bayer capture formats
media: a few more typos at staging, pci, platform, radio and usb
media: Documentation: fix several typos
media: staging: fix several typos
media: include: fix several typos
media: common: fix several typos
media: v4l2-core: fix several typos
media: usb: fix several typos
...
Diffstat (limited to 'Documentation')
64 files changed, 4920 insertions, 4201 deletions
diff --git a/Documentation/devicetree/bindings/media/i2c/adv748x.txt b/Documentation/devicetree/bindings/media/i2c/adv748x.txt index 5dddc95f9cc4..4f91686e54a6 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv748x.txt +++ b/Documentation/devicetree/bindings/media/i2c/adv748x.txt @@ -48,7 +48,16 @@ are numbered as follows. TXA source 10 TXB source 11 -The digital output port nodes must contain at least one endpoint. +The digital output port nodes, when present, shall contain at least one +endpoint. Each of those endpoints shall contain the data-lanes property as +described in video-interfaces.txt. + +Required source endpoint properties: + - data-lanes: an array of physical data lane indexes + The accepted value(s) for this property depends on which of the two + sources are described. For TXA 1, 2 or 4 data lanes can be described + while for TXB only 1 data lane is valid. See video-interfaces.txt + for detailed description. Ports are optional if they are not connected to anything at the hardware level. diff --git a/Documentation/devicetree/bindings/media/i2c/melexis,mlx90640.txt b/Documentation/devicetree/bindings/media/i2c/melexis,mlx90640.txt new file mode 100644 index 000000000000..060d2b7a5893 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/melexis,mlx90640.txt @@ -0,0 +1,20 @@ +* Melexis MLX90640 FIR Sensor + +Melexis MLX90640 FIR sensor support which allows recording of thermal data +with 32x24 resolution excluding 2 lines of coefficient data that is used by +userspace to render processed frames. + +Required Properties: + - compatible : Must be "melexis,mlx90640" + - reg : i2c address of the device + +Example: + + i2c0@1c22000 { + ... + mlx90640@33 { + compatible = "melexis,mlx90640"; + reg = <0x33>; + }; + ... + }; diff --git a/Documentation/devicetree/bindings/media/i2c/mt9m001.txt b/Documentation/devicetree/bindings/media/i2c/mt9m001.txt new file mode 100644 index 000000000000..c920552b03ef --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/mt9m001.txt @@ -0,0 +1,38 @@ +MT9M001: 1/2-Inch Megapixel Digital Image Sensor + +The MT9M001 is an SXGA-format with a 1/2-inch CMOS active-pixel digital +image sensor. It is programmable through I2C interface. + +Required Properties: + +- compatible: shall be "onnn,mt9m001". +- clocks: reference to the master clock into sensor + +Optional Properties: + +- reset-gpios: GPIO handle which is connected to the reset pin of the chip. + Active low. +- standby-gpios: GPIO handle which is connected to the standby pin of the chip. + Active high. + +The device node must contain one 'port' child node with one 'endpoint' child +sub-node for its digital output video port, in accordance with the video +interface bindings defined in: +Documentation/devicetree/bindings/media/video-interfaces.txt + +Example: + + &i2c1 { + camera-sensor@5d { + compatible = "onnn,mt9m001"; + reg = <0x5d>; + reset-gpios = <&gpio0 0 GPIO_ACTIVE_LOW>; + standby-gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>; + clocks = <&camera_clk>; + port { + mt9m001_out: endpoint { + remote-endpoint = <&vcap_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/ov5645.txt b/Documentation/devicetree/bindings/media/i2c/ov5645.txt index fd7aec9f8e24..72ad992f77be 100644 --- a/Documentation/devicetree/bindings/media/i2c/ov5645.txt +++ b/Documentation/devicetree/bindings/media/i2c/ov5645.txt @@ -26,9 +26,9 @@ Example: &i2c1 { ... - ov5645: ov5645@78 { + ov5645: ov5645@3c { compatible = "ovti,ov5645"; - reg = <0x78>; + reg = <0x3c>; enable-gpios = <&gpio1 6 GPIO_ACTIVE_HIGH>; reset-gpios = <&gpio5 20 GPIO_ACTIVE_LOW>; @@ -37,7 +37,7 @@ Example: clocks = <&clks 200>; clock-names = "xclk"; - clock-frequency = <23880000>; + clock-frequency = <24000000>; vdddo-supply = <&camera_dovdd_1v8>; vdda-supply = <&camera_avdd_2v8>; diff --git a/Documentation/devicetree/bindings/media/imx7-csi.txt b/Documentation/devicetree/bindings/media/imx7-csi.txt new file mode 100644 index 000000000000..3c07bc676bc3 --- /dev/null +++ b/Documentation/devicetree/bindings/media/imx7-csi.txt @@ -0,0 +1,45 @@ +Freescale i.MX7 CMOS Sensor Interface +===================================== + +csi node +-------- + +This is device node for the CMOS Sensor Interface (CSI) which enables the chip +to connect directly to external CMOS image sensors. + +Required properties: + +- compatible : "fsl,imx7-csi"; +- reg : base address and length of the register set for the device; +- interrupts : should contain CSI interrupt; +- clocks : list of clock specifiers, see + Documentation/devicetree/bindings/clock/clock-bindings.txt for details; +- clock-names : must contain "axi", "mclk" and "dcic" entries, matching + entries in the clock property; + +The device node shall contain one 'port' child node with one child 'endpoint' +node, according to the bindings defined in: +Documentation/devicetree/bindings/media/video-interfaces.txt. + +In the following example a remote endpoint is a video multiplexer. + +example: + + csi: csi@30710000 { + #address-cells = <1>; + #size-cells = <0>; + + compatible = "fsl,imx7-csi"; + reg = <0x30710000 0x10000>; + interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX7D_CLK_DUMMY>, + <&clks IMX7D_CSI_MCLK_ROOT_CLK>, + <&clks IMX7D_CLK_DUMMY>; + clock-names = "axi", "mclk", "dcic"; + + port { + csi_from_csi_mux: endpoint { + remote-endpoint = <&csi_mux_to_csi>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt b/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt new file mode 100644 index 000000000000..71fd74ed3ec8 --- /dev/null +++ b/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt @@ -0,0 +1,90 @@ +Freescale i.MX7 Mipi CSI2 +========================= + +mipi_csi2 node +-------------- + +This is the device node for the MIPI CSI-2 receiver core in i.MX7 SoC. It is +compatible with previous version of Samsung D-phy. + +Required properties: + +- compatible : "fsl,imx7-mipi-csi2"; +- reg : base address and length of the register set for the device; +- interrupts : should contain MIPI CSIS interrupt; +- clocks : list of clock specifiers, see + Documentation/devicetree/bindings/clock/clock-bindings.txt for details; +- clock-names : must contain "pclk", "wrap" and "phy" entries, matching + entries in the clock property; +- power-domains : a phandle to the power domain, see + Documentation/devicetree/bindings/power/power_domain.txt for details. +- reset-names : should include following entry "mrst"; +- resets : a list of phandle, should contain reset entry of + reset-names; +- phy-supply : from the generic phy bindings, a phandle to a regulator that + provides power to MIPI CSIS core; + +Optional properties: + +- clock-frequency : The IP's main (system bus) clock frequency in Hz, default + value when this property is not specified is 166 MHz; +- fsl,csis-hs-settle : differential receiver (HS-RX) settle time; + +The device node should contain two 'port' child nodes with one child 'endpoint' +node, according to the bindings defined in: + Documentation/devicetree/bindings/ media/video-interfaces.txt. + The following are properties specific to those nodes. + +port node +--------- + +- reg : (required) can take the values 0 or 1, where 0 shall be + related to the sink port and port 1 shall be the source + one; + +endpoint node +------------- + +- data-lanes : (required) an array specifying active physical MIPI-CSI2 + data input lanes and their mapping to logical lanes; this + shall only be applied to port 0 (sink port), the array's + content is unused only its length is meaningful, + in this case the maximum length supported is 2; + +example: + + mipi_csi: mipi-csi@30750000 { + #address-cells = <1>; + #size-cells = <0>; + + compatible = "fsl,imx7-mipi-csi2"; + reg = <0x30750000 0x10000>; + interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX7D_IPG_ROOT_CLK>, + <&clks IMX7D_MIPI_CSI_ROOT_CLK>, + <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; + clock-names = "pclk", "wrap", "phy"; + clock-frequency = <166000000>; + power-domains = <&pgc_mipi_phy>; + phy-supply = <®_1p0d>; + resets = <&src IMX7_RESET_MIPI_PHY_MRST>; + reset-names = "mrst"; + fsl,csis-hs-settle = <3>; + + port@0 { + reg = <0>; + + mipi_from_sensor: endpoint { + remote-endpoint = <&ov2680_to_mipi>; + data-lanes = <1>; + }; + }; + + port@1 { + reg = <1>; + + mipi_vc0_to_csi_mux: endpoint { + remote-endpoint = <&csi_mux_from_mipi_vc0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt index 2a615d84a682..b6b5dde6abd8 100644 --- a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt +++ b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt @@ -66,6 +66,15 @@ vcodec_dec: vcodec@16000000 { "vencpll", "venc_lt_sel", "vdec_bus_clk_src"; + assigned-clocks = <&topckgen CLK_TOP_VENC_LT_SEL>, + <&topckgen CLK_TOP_CCI400_SEL>, + <&topckgen CLK_TOP_VDEC_SEL>, + <&apmixedsys CLK_APMIXED_VCODECPLL>, + <&apmixedsys CLK_APMIXED_VENCPLL>; + assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL_370P5>, + <&topckgen CLK_TOP_UNIVPLL_D2>, + <&topckgen CLK_TOP_VCODECPLL>; + assigned-clock-rates = <0>, <0>, <0>, <1482000000>, <800000000>; }; vcodec_enc: vcodec@18002000 { @@ -105,4 +114,8 @@ vcodec_dec: vcodec@16000000 { "venc_sel", "venc_lt_sel_src", "venc_lt_sel"; + assigned-clocks = <&topckgen CLK_TOP_VENC_SEL>, + <&topckgen CLK_TOP_VENC_LT_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_VENCPLL_D2>, + <&topckgen CLK_TOP_UNIVPLL1_D2>; }; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index 0dd84a183ca7..224a4615b418 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -7,12 +7,13 @@ family of devices. Each VIN instance has a single parallel input that supports RGB and YUV video, with both external synchronization and BT.656 synchronization for the latter. Depending on the instance the VIN input is connected to external SoC pins, or -on Gen3 platforms to a CSI-2 receiver. +on Gen3 and RZ/G2 platforms to a CSI-2 receiver. - compatible: Must be one or more of the following - "renesas,vin-r8a7743" for the R8A7743 device - "renesas,vin-r8a7744" for the R8A7744 device - "renesas,vin-r8a7745" for the R8A7745 device + - "renesas,vin-r8a774c0" for the R8A774C0 device - "renesas,vin-r8a7778" for the R8A7778 device - "renesas,vin-r8a7779" for the R8A7779 device - "renesas,vin-r8a7790" for the R8A7790 device @@ -61,10 +62,10 @@ The per-board settings Gen2 platforms: - data-enable-active: polarity of CLKENB signal, see [1] for description. Default is active high. -The per-board settings Gen3 platforms: +The per-board settings Gen3 and RZ/G2 platforms: -Gen3 platforms can support both a single connected parallel input source -from external SoC pins (port@0) and/or multiple parallel input sources +Gen3 and RZ/G2 platforms can support both a single connected parallel input +source from external SoC pins (port@0) and/or multiple parallel input sources from local SoC CSI-2 receivers (port@1) depending on SoC. - renesas,id - ID number of the VIN, VINx in the documentation. diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.txt b/Documentation/devicetree/bindings/media/renesas,fcp.txt index 3ec91803ba58..79c37395b396 100644 --- a/Documentation/devicetree/bindings/media/renesas,fcp.txt +++ b/Documentation/devicetree/bindings/media/renesas,fcp.txt @@ -2,8 +2,9 @@ Renesas R-Car Frame Compression Processor (FCP) ----------------------------------------------- The FCP is a companion module of video processing modules in the Renesas R-Car -Gen3 SoCs. It provides data compression and decompression, data caching, and -conversion of AXI transactions in order to reduce the memory bandwidth. +Gen3 and RZ/G2 SoCs. It provides data compression and decompression, data +caching, and conversion of AXI transactions in order to reduce the memory +bandwidth. There are three types of FCP: FCP for Codec (FCPC), FCP for VSP (FCPV) and FCP for FDP (FCPF). Their configuration and behaviour depend on the module they diff --git a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt b/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt index 541d936b62e8..d63275e17afd 100644 --- a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt +++ b/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt @@ -2,12 +2,13 @@ Renesas R-Car MIPI CSI-2 ------------------------ The R-Car CSI-2 receiver device provides MIPI CSI-2 capabilities for the -Renesas R-Car family of devices. It is used in conjunction with the +Renesas R-Car and RZ/G2 family of devices. It is used in conjunction with the R-Car VIN module, which provides the video capture capabilities. Mandatory properties -------------------- - compatible: Must be one or more of the following + - "renesas,r8a774c0-csi2" for the R8A774C0 device. - "renesas,r8a7795-csi2" for the R8A7795 device. - "renesas,r8a7796-csi2" for the R8A7796 device. - "renesas,r8a77965-csi2" for the R8A77965 device. diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.txt b/Documentation/devicetree/bindings/media/renesas,vsp1.txt index 16427017cb45..cd5a955b2ea0 100644 --- a/Documentation/devicetree/bindings/media/renesas,vsp1.txt +++ b/Documentation/devicetree/bindings/media/renesas,vsp1.txt @@ -2,13 +2,13 @@ The VSP is a video processing engine that supports up-/down-scaling, alpha blending, color space conversion and various other image processing features. -It can be found in the Renesas R-Car second generation SoCs. +It can be found in the Renesas R-Car Gen2, R-Car Gen3, RZ/G1, and RZ/G2 SoCs. Required properties: - compatible: Must contain one of the following values - - "renesas,vsp1" for the R-Car Gen2 VSP1 - - "renesas,vsp2" for the R-Car Gen3 VSP2 + - "renesas,vsp1" for the R-Car Gen2 and RZ/G1 VSP1 + - "renesas,vsp2" for the R-Car Gen3 and RZ/G2 VSP2 - reg: Base address and length of the registers block for the VSP. - interrupts: VSP interrupt specifier. diff --git a/Documentation/devicetree/bindings/media/si470x.txt b/Documentation/devicetree/bindings/media/si470x.txt new file mode 100644 index 000000000000..a9403558362e --- /dev/null +++ b/Documentation/devicetree/bindings/media/si470x.txt @@ -0,0 +1,26 @@ +* Silicon Labs FM Radio receiver + +The Silicon Labs Si470x is family of FM radio receivers with receive power scan +supporting 76-108 MHz, programmable through an I2C interface. +Some of them includes an RDS encoder. + +Required Properties: +- compatible: Should contain "silabs,si470x" +- reg: the I2C address of the device + +Optional Properties: +- interrupts : The interrupt number +- reset-gpios: GPIO specifier for the chips reset line + +Example: + +&i2c2 { + si470x@63 { + compatible = "silabs,si470x"; + reg = <0x63>; + + interrupt-parent = <&gpj2>; + interrupts = <4 IRQ_TYPE_EDGE_FALLING>; + reset-gpios = <&gpj2 5 GPIO_ACTIVE_HIGH>; + }; +}; diff --git a/Documentation/devicetree/bindings/media/sun6i-csi.txt b/Documentation/devicetree/bindings/media/sun6i-csi.txt index d4ab34f2240c..0dd540bb03db 100644 --- a/Documentation/devicetree/bindings/media/sun6i-csi.txt +++ b/Documentation/devicetree/bindings/media/sun6i-csi.txt @@ -6,8 +6,9 @@ Allwinner V3s SoC features a CSI module(CSI1) with parallel interface. Required properties: - compatible: value must be one of: * "allwinner,sun6i-a31-csi" - * "allwinner,sun8i-h3-csi", "allwinner,sun6i-a31-csi" + * "allwinner,sun8i-h3-csi" * "allwinner,sun8i-v3s-csi" + * "allwinner,sun50i-a64-csi" - reg: base address and size of the memory-mapped region. - interrupts: interrupt associated to this IP - clocks: phandles to the clocks feeding the CSI diff --git a/Documentation/media/dvb-drivers/dvb-usb.rst b/Documentation/media/dvb-drivers/dvb-usb.rst index 6679191819aa..b2d5d9e62b30 100644 --- a/Documentation/media/dvb-drivers/dvb-usb.rst +++ b/Documentation/media/dvb-drivers/dvb-usb.rst @@ -125,7 +125,7 @@ https://linuxtv.org/wiki/index.php/DVB_USB 2004-12-26 - - refactored the dibusb-driver, splitted into separate files + - refactored the dibusb-driver, split into separate files - i2c-probing enabled 2004-12-06 diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst index 17454a2cf6b0..ac005b46f23e 100644 --- a/Documentation/media/kapi/dtv-core.rst +++ b/Documentation/media/kapi/dtv-core.rst @@ -12,7 +12,7 @@ Digital TV devices are implemented by several different drivers: - Frontend drivers that are usually implemented as two separate drivers: - A tuner driver that implements the logic with commands the part of the - hardware with is reponsible to tune into a digital TV transponder or + hardware with is responsible to tune into a digital TV transponder or physical channel. The output of a tuner is usually a baseband or Intermediate Frequency (IF) signal; diff --git a/Documentation/media/kapi/dtv-frontend.rst b/Documentation/media/kapi/dtv-frontend.rst index 8ea64742c7ba..fbc5517c8d5a 100644 --- a/Documentation/media/kapi/dtv-frontend.rst +++ b/Documentation/media/kapi/dtv-frontend.rst @@ -328,7 +328,7 @@ Statistics collect On almost all frontend hardware, the bit and byte counts are stored by the hardware after a certain amount of time or after the total bit/block -counter reaches a certain value (usually programable), for example, on +counter reaches a certain value (usually programmable), for example, on every 1000 ms or after receiving 1,000,000 bits. So, if you read the registers too soon, you'll end by reading the same diff --git a/Documentation/media/kapi/mc-core.rst b/Documentation/media/kapi/mc-core.rst index 0bcfeadbc52d..f930725e0d6b 100644 --- a/Documentation/media/kapi/mc-core.rst +++ b/Documentation/media/kapi/mc-core.rst @@ -60,7 +60,7 @@ Drivers initialize entity pads by calling Drivers register entities with a media device by calling :c:func:`media_device_register_entity()` -and unregistred by calling +and unregistered by calling :c:func:`media_device_unregister_entity()`. Interfaces diff --git a/Documentation/media/kapi/v4l2-device.rst b/Documentation/media/kapi/v4l2-device.rst index c4311f0421be..5e25bf182c18 100644 --- a/Documentation/media/kapi/v4l2-device.rst +++ b/Documentation/media/kapi/v4l2-device.rst @@ -93,7 +93,7 @@ You can iterate over all registered devices as follows: int err; /* Find driver 'ivtv' on the PCI bus. - pci_bus_type is a global. For USB busses use usb_bus_type. */ + pci_bus_type is a global. For USB buses use usb_bus_type. */ drv = driver_find("ivtv", &pci_bus_type); /* iterate over all ivtv device instances */ err = driver_for_each_device(drv, NULL, p, callback); diff --git a/Documentation/media/kapi/v4l2-intro.rst b/Documentation/media/kapi/v4l2-intro.rst index cea3e263e48b..4d54fa9d7a12 100644 --- a/Documentation/media/kapi/v4l2-intro.rst +++ b/Documentation/media/kapi/v4l2-intro.rst @@ -11,7 +11,7 @@ hardware: most devices have multiple ICs, export multiple device nodes in Especially the fact that V4L2 drivers have to setup supporting ICs to do audio/video muxing/encoding/decoding makes it more complex than most. Usually these ICs are connected to the main bridge driver through one or -more I2C busses, but other busses can also be used. Such devices are +more I2C buses, but other buses can also be used. Such devices are called 'sub-devices'. For a long time the framework was limited to the video_device struct for diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst index be4970909f40..29e07e23f888 100644 --- a/Documentation/media/kapi/v4l2-subdev.rst +++ b/Documentation/media/kapi/v4l2-subdev.rst @@ -23,7 +23,7 @@ device data. You also need a way to go from the low-level struct to :c:type:`v4l2_subdev`. For the common i2c_client struct the i2c_set_clientdata() call is used to store -a :c:type:`v4l2_subdev` pointer, for other busses you may have to use other +a :c:type:`v4l2_subdev` pointer, for other buses you may have to use other methods. Bridges might also need to store per-subdev private data, such as a pointer to @@ -33,7 +33,7 @@ provides host private data for that purpose that can be accessed with From the bridge driver perspective, you load the sub-device module and somehow obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call -``i2c_get_clientdata()``. For other busses something similar needs to be done. +``i2c_get_clientdata()``. For other buses something similar needs to be done. Helper functions exists for sub-devices on an I2C bus that do most of this tricky work for you. diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions index 379b9e7df5d0..7a8b8ff4f076 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -60,6 +60,9 @@ ignore symbol RC_PROTO_SHARP ignore symbol RC_PROTO_XMP ignore symbol RC_PROTO_CEC ignore symbol RC_PROTO_IMON +ignore symbol RC_PROTO_RCMM12 +ignore symbol RC_PROTO_RCMM24 +ignore symbol RC_PROTO_RCMM32 # Undocumented macros diff --git a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst b/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst index d537da90acf5..d68f05d48d12 100644 --- a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst +++ b/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst @@ -57,7 +57,7 @@ Description This ioctl call asks the Audio Device to bypass the Audio decoder and forward the stream without decoding. This mode shall be used if streams -that can’t be handled by the Digial TV system shall be decoded. Dolby +that can’t be handled by the Digital TV system shall be decoded. Dolby DigitalTM streams are automatically forwarded by the Digital TV subsystem if the hardware can handle it. diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst b/Documentation/media/uapi/dvb/ca-set-descr.rst index 22c8b8f94c7e..d36464ba2317 100644 --- a/Documentation/media/uapi/dvb/ca-set-descr.rst +++ b/Documentation/media/uapi/dvb/ca-set-descr.rst @@ -39,7 +39,7 @@ Description ----------- CA_SET_DESCR is used for feeding descrambler CA slots with descrambling -keys (refered as control words). +keys (referred as control words). Return Value ------------ diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst b/Documentation/media/uapi/dvb/dmx-qbuf.rst index 9a1d85147c25..9dc845daa59d 100644 --- a/Documentation/media/uapi/dvb/dmx-qbuf.rst +++ b/Documentation/media/uapi/dvb/dmx-qbuf.rst @@ -61,7 +61,7 @@ the device is closed. Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled (capturing) buffer from the driver's outgoing queue. -They just set the ``index`` field withe the buffer ID to be queued. +They just set the ``index`` field with the buffer ID to be queued. When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, the driver fills the remaining fields or returns an error code. diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst index 371c72bb9419..0c4f5598f2be 100644 --- a/Documentation/media/uapi/dvb/dvbproperty.rst +++ b/Documentation/media/uapi/dvb/dvbproperty.rst @@ -44,7 +44,7 @@ with supports all digital TV delivery systems. struct :c:type:`dvb_frontend_parameters`. 2. Don't use DVB API version 3 calls on hardware with supports - newer standards. Such API provides no suport or a very limited + newer standards. Such API provides no support or a very limited support to new standards and/or new hardware. 3. Nowadays, most frontends support multiple delivery systems. diff --git a/Documentation/media/uapi/dvb/video_types.rst b/Documentation/media/uapi/dvb/video_types.rst index 2ed8aad84003..479942ce6fb8 100644 --- a/Documentation/media/uapi/dvb/video_types.rst +++ b/Documentation/media/uapi/dvb/video_types.rst @@ -202,7 +202,7 @@ If video_blank is set video will be blanked out if the channel is changed or if playback is stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is currently frozen, stopped, or being played back. The stream_source corresponds to the -seleted source for the video stream. It can come either from the +selected source for the video stream. It can come either from the demultiplexer or from memory. The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently played video stream. Finally, display_format corresponds to the selected cropping mode in diff --git a/Documentation/media/uapi/fdl-appendix.rst b/Documentation/media/uapi/fdl-appendix.rst index f8dc85d3939c..9316b8617502 100644 --- a/Documentation/media/uapi/fdl-appendix.rst +++ b/Documentation/media/uapi/fdl-appendix.rst @@ -363,7 +363,7 @@ various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. -You may extract a single document from such a collection, and dispbibute +You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst index 8627587b7075..3af6a414b501 100644 --- a/Documentation/media/uapi/mediactl/media-types.rst +++ b/Documentation/media/uapi/mediactl/media-types.rst @@ -164,7 +164,7 @@ Types and flags used to represent the media graph elements * - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV`` - Video pixel encoding converter. An entity capable of pixel - enconding conversion must have at least one sink pad and one + encoding conversion must have at least one sink pad and one source pad, and convert the encoding of pixels received on its sink pad(s) to a different encoding output on its source pad(s). Pixel encoding conversion includes but isn't limited diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst index 4b25ad03f45a..1ad631e549fe 100644 --- a/Documentation/media/uapi/mediactl/request-api.rst +++ b/Documentation/media/uapi/mediactl/request-api.rst @@ -91,7 +91,7 @@ A request must contain at least one buffer, otherwise ``ENOENT`` is returned. A queued request cannot be modified anymore. .. caution:: - For :ref:`memory-to-memory devices <codec>` you can use requests only for + For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for output buffers, not for capture buffers. Attempting to add a capture buffer to a request will result in an ``EACCES`` error. @@ -152,7 +152,7 @@ if it had just been allocated. Example for a Codec Device -------------------------- -For use-cases such as :ref:`codecs <codec>`, the request API can be used +For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used to associate specific controls to be applied by the driver for the OUTPUT buffer, allowing user-space to queue many such buffers in advance. It can also take advantage of requests' diff --git a/Documentation/media/uapi/rc/rc-tables.rst b/Documentation/media/uapi/rc/rc-tables.rst index cb670d10998b..f460031d8531 100644 --- a/Documentation/media/uapi/rc/rc-tables.rst +++ b/Documentation/media/uapi/rc/rc-tables.rst @@ -385,7 +385,7 @@ the remote via /dev/input/event devices. - ``KEY_CHANNELDOWN`` - - Decrease channel sequencially + - Decrease channel sequentially - CHANNEL - / CHANNEL DOWN / DOWN @@ -393,7 +393,7 @@ the remote via /dev/input/event devices. - ``KEY_CHANNELUP`` - - Increase channel sequencially + - Increase channel sequentially - CHANNEL + / CHANNEL UP / UP diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst index 86878bb0087f..81ffdcb89057 100644 --- a/Documentation/media/uapi/v4l/buffer.rst +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -230,8 +230,7 @@ struct v4l2_buffer * - struct :c:type:`v4l2_timecode` - ``timecode`` - - - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the - ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this + - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this structure contains a frame timecode. In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and bottom field contain the same timecode. Timecodes are intended to @@ -714,10 +713,10 @@ enum v4l2_memory Timecodes ========= -The struct :c:type:`v4l2_timecode` structure is designed to hold a -:ref:`smpte12m` or similar timecode. (struct -struct :c:type:`timeval` timestamps are stored in struct -:c:type:`v4l2_buffer` field ``timestamp``.) +The :c:type:`v4l2_buffer_timecode` structure is designed to hold a +:ref:`smpte12m` or similar timecode. +(struct :c:type:`timeval` timestamps are stored in the struct +:c:type:`v4l2_buffer` ``timestamp`` field.) .. c:type:: v4l2_timecode diff --git a/Documentation/media/uapi/v4l/common.rst b/Documentation/media/uapi/v4l/common.rst index 889f2f2632a1..5e87ae24e4b4 100644 --- a/Documentation/media/uapi/v4l/common.rst +++ b/Documentation/media/uapi/v4l/common.rst @@ -46,6 +46,17 @@ applicable to all devices. dv-timings control extended-controls + ext-ctrls-camera + ext-ctrls-flash + ext-ctrls-image-source + ext-ctrls-image-process + ext-ctrls-codec + ext-ctrls-jpeg + ext-ctrls-dv + ext-ctrls-rf-tuner + ext-ctrls-fm-tx + ext-ctrls-fm-rx + ext-ctrls-detect format planar-apis selection-api diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst index 0d46526b5935..71417bba028c 100644 --- a/Documentation/media/uapi/v4l/control.rst +++ b/Documentation/media/uapi/v4l/control.rst @@ -499,7 +499,7 @@ Example: Changing controls .. [#f1] The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different - controls. This makes it hard to programatically set such controls + controls. This makes it hard to programmatically set such controls since the meaning of the control with that ID is driver dependent. In order to resolve this drivers use unique IDs and the ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the diff --git a/Documentation/media/uapi/v4l/dev-effect.rst b/Documentation/media/uapi/v4l/dev-effect.rst deleted file mode 100644 index b165e2c20910..000000000000 --- a/Documentation/media/uapi/v4l/dev-effect.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _effect: - -************************ -Effect Devices Interface -************************ - -.. note:: - This interface has been be suspended from the V4L2 API. - The implementation for such effects should be done - via mem2mem devices. - -A V4L2 video effect device can do image effects, filtering, or combine -two or more images or image streams. For example video transitions or -wipes. Applications send data to be processed and receive the result -data either with :ref:`read() <func-read>` and -:ref:`write() <func-write>` functions, or through the streaming I/O -mechanism. - -[to do] diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst index b5e017c17834..67a980818dc8 100644 --- a/Documentation/media/uapi/v4l/dev-codec.rst +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst @@ -7,37 +7,36 @@ .. .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections -.. _codec: +.. _mem2mem: -*************** -Codec Interface -*************** +******************************** +Video Memory-To-Memory Interface +******************************** -A V4L2 codec can compress, decompress, transform, or otherwise convert -video data from one format into another format, in memory. Typically -such devices are memory-to-memory devices (i.e. devices with the -``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set). +A V4L2 memory-to-memory device can compress, decompress, transform, or +otherwise convert video data from one format into another format, in memory. +Such memory-to-memory devices set the ``V4L2_CAP_VIDEO_M2M`` or +``V4L2_CAP_VIDEO_M2M_MPLANE`` capability. Examples of memory-to-memory +devices are codecs, scalers, deinterlacers or format converters (i.e. +converting from YUV to RGB). A memory-to-memory video node acts just like a normal video node, but it -supports both output (sending frames from memory to the codec hardware) -and capture (receiving the processed frames from the codec hardware into +supports both output (sending frames from memory to the hardware) +and capture (receiving the processed frames from the hardware into memory) stream I/O. An application will have to setup the stream I/O for both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` -for both capture and output to start the codec. - -Video compression codecs use the MPEG controls to setup their codec -parameters - -.. note:: - - The MPEG controls actually support many more codecs than - just MPEG. See :ref:`mpeg-controls`. +for both capture and output to start the hardware. Memory-to-memory devices function as a shared resource: you can open the video node multiple times, each application setting up their -own codec properties that are local to the file handle, and each can use +own properties that are local to the file handle, and each can use it independently from the others. The driver will arbitrate access to -the codec and reprogram it whenever another file handler gets access. +the hardware and reprogram it whenever another file handler gets access. This is different from the usual video node behavior where the video properties are global to the device (i.e. changing something through one file handle is visible through another file handle). + +One of the most common memory-to-memory device is the codec. Codecs +are more complicated than most and require additional setup for +their codec parameters. This is done through codec controls. +See :ref:`mpeg-controls`. diff --git a/Documentation/media/uapi/v4l/dev-teletext.rst b/Documentation/media/uapi/v4l/dev-teletext.rst deleted file mode 100644 index 35e8c4b35458..000000000000 --- a/Documentation/media/uapi/v4l/dev-teletext.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ttx: - -****************** -Teletext Interface -****************** - -This interface was aimed at devices receiving and demodulating Teletext -data [:ref:`ets300706`, :ref:`itu653`], evaluating the Teletext -packages and storing formatted pages in cache memory. Such devices are -usually implemented as microcontrollers with serial interface -(I\ :sup:`2`\ C) and could be found on old TV cards, dedicated Teletext -decoding cards and home-brew devices connected to the PC parallel port. - -The Teletext API was designed by Martin Buck. It was defined in the -kernel header file ``linux/videotext.h``, the specification is available -from -`ftp://ftp.gwdg.de/pub/linux/misc/videotext/ <ftp://ftp.gwdg.de/pub/linux/misc/videotext/>`__. -(Videotext is the name of the German public television Teletext -service.) - -Eventually the Teletext API was integrated into the V4L API with -character device file names ``/dev/vtx0`` to ``/dev/vtx31``, device -major number 81, minor numbers 192 to 223. - -However, teletext decoders were quickly replaced by more generic VBI -demodulators and those dedicated teletext decoders no longer exist. For -many years the vtx devices were still around, even though nobody used -them. So the decision was made to finally remove support for the -Teletext API in kernel 2.6.37. - -Modern devices all use the :ref:`raw <raw-vbi>` or -:ref:`sliced` VBI API. diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst index 5dbe9d13b6e6..07f8d047662b 100644 --- a/Documentation/media/uapi/v4l/devices.rst +++ b/Documentation/media/uapi/v4l/devices.rst @@ -21,11 +21,9 @@ Interfaces dev-overlay dev-output dev-osd - dev-codec - dev-effect + dev-mem2mem dev-raw-vbi dev-sliced-vbi - dev-teletext dev-radio dev-rds dev-sdr diff --git a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst new file mode 100644 index 000000000000..d3a553cd86c9 --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst @@ -0,0 +1,508 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _camera-controls: + +************************ +Camera Control Reference +************************ + +The Camera class includes controls for mechanical (or equivalent +digital) features of a device such as controllable lenses or sensors. + + +.. _camera-control-id: + +Camera Control IDs +================== + +``V4L2_CID_CAMERA_CLASS (class)`` + The Camera class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +.. _v4l2-exposure-auto-type: + +``V4L2_CID_EXPOSURE_AUTO`` + (enum) + +enum v4l2_exposure_auto_type - + Enables automatic adjustments of the exposure time and/or iris + aperture. The effect of manual changes of the exposure time or iris + aperture while these features are enabled is undefined, drivers + should ignore such requests. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_EXPOSURE_AUTO`` + - Automatic exposure time, automatic iris aperture. + * - ``V4L2_EXPOSURE_MANUAL`` + - Manual exposure time, manual iris. + * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY`` + - Manual exposure time, auto iris. + * - ``V4L2_EXPOSURE_APERTURE_PRIORITY`` + - Auto exposure time, manual iris. + + + +``V4L2_CID_EXPOSURE_ABSOLUTE (integer)`` + Determines the exposure time of the camera sensor. The exposure time + is limited by the frame interval. Drivers should interpret the + values as 100 µs units, where the value 1 stands for 1/10000th of a + second, 10000 for 1 second and 100000 for 10 seconds. + +``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)`` + When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or + ``APERTURE_PRIORITY``, this control determines if the device may + dynamically vary the frame rate. By default this feature is disabled + (0) and the frame rate must remain constant. + +``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)`` + Determines the automatic exposure compensation, it is effective only + when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``, + ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in + terms of EV, drivers should interpret the values as 0.001 EV units, + where the value 1000 stands for +1 EV. + + Increasing the exposure compensation value is equivalent to + decreasing the exposure value (EV) and will increase the amount of + light at the image sensor. The camera performs the exposure + compensation by adjusting absolute exposure time and/or aperture. + +.. _v4l2-exposure-metering: + +``V4L2_CID_EXPOSURE_METERING`` + (enum) + +enum v4l2_exposure_metering - + Determines how the camera measures the amount of light available for + the frame exposure. Possible values are: + +.. tabularcolumns:: |p{8.5cm}|p{9.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_EXPOSURE_METERING_AVERAGE`` + - Use the light information coming from the entire frame and average + giving no weighting to any particular portion of the metered area. + * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED`` + - Average the light information coming from the entire frame giving + priority to the center of the metered area. + * - ``V4L2_EXPOSURE_METERING_SPOT`` + - Measure only very small area at the center of the frame. + * - ``V4L2_EXPOSURE_METERING_MATRIX`` + - A multi-zone metering. The light intensity is measured in several + points of the frame and the results are combined. The algorithm of + the zones selection and their significance in calculating the + final value is device dependent. + + + +``V4L2_CID_PAN_RELATIVE (integer)`` + This control turns the camera horizontally by the specified amount. + The unit is undefined. A positive value moves the camera to the + right (clockwise when viewed from above), a negative value to the + left. A value of zero does not cause motion. This is a write-only + control. + +``V4L2_CID_TILT_RELATIVE (integer)`` + This control turns the camera vertically by the specified amount. + The unit is undefined. A positive value moves the camera up, a + negative value down. A value of zero does not cause motion. This is + a write-only control. + +``V4L2_CID_PAN_RESET (button)`` + When this control is set, the camera moves horizontally to the + default position. + +``V4L2_CID_TILT_RESET (button)`` + When this control is set, the camera moves vertically to the default + position. + +``V4L2_CID_PAN_ABSOLUTE (integer)`` + This control turns the camera horizontally to the specified + position. Positive values move the camera to the right (clockwise + when viewed from above), negative values to the left. Drivers should + interpret the values as arc seconds, with valid values between -180 + * 3600 and +180 * 3600 inclusive. + +``V4L2_CID_TILT_ABSOLUTE (integer)`` + This control turns the camera vertically to the specified position. + Positive values move the camera up, negative values down. Drivers + should interpret the values as arc seconds, with valid values + between -180 * 3600 and +180 * 3600 inclusive. + +``V4L2_CID_FOCUS_ABSOLUTE (integer)`` + This control sets the focal point of the camera to the specified + position. The unit is undefined. Positive values set the focus + closer to the camera, negative values towards infinity. + +``V4L2_CID_FOCUS_RELATIVE (integer)`` + This control moves the focal point of the camera by the specified + amount. The unit is undefined. Positive values move the focus closer + to the camera, negative values towards infinity. This is a + write-only control. + +``V4L2_CID_FOCUS_AUTO (boolean)`` + Enables continuous automatic focus adjustments. The effect of manual + focus adjustments while this feature is enabled is undefined, + drivers should ignore such requests. + +``V4L2_CID_AUTO_FOCUS_START (button)`` + Starts single auto focus process. The effect of setting this control + when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined, + drivers should ignore such requests. + +``V4L2_CID_AUTO_FOCUS_STOP (button)`` + Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START`` + control. It is effective only when the continuous autofocus is + disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to + ``FALSE`` (0). + +.. _v4l2-auto-focus-status: + +``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)`` + The automatic focus status. This is a read-only control. + + Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK`` + control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS`` + control value. + +.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_AUTO_FOCUS_STATUS_IDLE`` + - Automatic focus is not active. + * - ``V4L2_AUTO_FOCUS_STATUS_BUSY`` + - Automatic focusing is in progress. + * - ``V4L2_AUTO_FOCUS_STATUS_REACHED`` + - Focus has been reached. + * - ``V4L2_AUTO_FOCUS_STATUS_FAILED`` + - Automatic focus has failed, the driver will not transition from + this state until another action is performed by an application. + + + +.. _v4l2-auto-focus-range: + +``V4L2_CID_AUTO_FOCUS_RANGE`` + (enum) + +enum v4l2_auto_focus_range - + Determines auto focus distance range for which lens may be adjusted. + +.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_AUTO_FOCUS_RANGE_AUTO`` + - The camera automatically selects the focus range. + * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL`` + - Normal distance range, limited for best automatic focus + performance. + * - ``V4L2_AUTO_FOCUS_RANGE_MACRO`` + - Macro (close-up) auto focus. The camera will use its minimum + possible distance for auto focus. + * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY`` + - The lens is set to focus on an object at infinite distance. + + + +``V4L2_CID_ZOOM_ABSOLUTE (integer)`` + Specify the objective lens focal length as an absolute value. The + zoom unit is driver-specific and its value should be a positive + integer. + +``V4L2_CID_ZOOM_RELATIVE (integer)`` + Specify the objective lens focal length relatively to the current + value. Positive values move the zoom lens group towards the + telephoto direction, negative values towards the wide-angle + direction. The zoom unit is driver-specific. This is a write-only + control. + +``V4L2_CID_ZOOM_CONTINUOUS (integer)`` + Move the objective lens group at the specified speed until it + reaches physical device limits or until an explicit request to stop + the movement. A positive value moves the zoom lens group towards the + telephoto direction. A value of zero stops the zoom lens group + movement. A negative value moves the zoom lens group towards the + wide-angle direction. The zoom speed unit is driver-specific. + +``V4L2_CID_IRIS_ABSOLUTE (integer)`` + This control sets the camera's aperture to the specified value. The + unit is undefined. Larger values open the iris wider, smaller values + close it. + +``V4L2_CID_IRIS_RELATIVE (integer)`` + This control modifies the camera's aperture by the specified amount. + The unit is undefined. Positive values open the iris one step + further, negative values close it one step further. This is a + write-only control. + +``V4L2_CID_PRIVACY (boolean)`` + Prevent video from being acquired by the camera. When this control + is set to ``TRUE`` (1), no image can be captured by the camera. + Common means to enforce privacy are mechanical obturation of the + sensor and firmware image processing, but the device is not + restricted to these methods. Devices that implement the privacy + control must support read access and may support write access. + +``V4L2_CID_BAND_STOP_FILTER (integer)`` + Switch the band-stop filter of a camera sensor on or off, or specify + its strength. Such band-stop filters can be used, for example, to + filter out the fluorescent light component. + +.. _v4l2-auto-n-preset-white-balance: + +``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE`` + (enum) + +enum v4l2_auto_n_preset_white_balance - + Sets white balance to automatic, manual or a preset. The presets + determine color temperature of the light as a hint to the camera for + white balance adjustments resulting in most accurate color + representation. The following white balance presets are listed in + order of increasing color temperature. + +.. tabularcolumns:: |p{7.0 cm}|p{10.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_WHITE_BALANCE_MANUAL`` + - Manual white balance. + * - ``V4L2_WHITE_BALANCE_AUTO`` + - Automatic white balance adjustments. + * - ``V4L2_WHITE_BALANCE_INCANDESCENT`` + - White balance setting for incandescent (tungsten) lighting. It + generally cools down the colors and corresponds approximately to + 2500...3500 K color temperature range. + * - ``V4L2_WHITE_BALANCE_FLUORESCENT`` + - White balance preset for fluorescent lighting. It corresponds + approximately to 4000...5000 K color temperature. + * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H`` + - With this setting the camera will compensate for fluorescent H + lighting. + * - ``V4L2_WHITE_BALANCE_HORIZON`` + - White balance setting for horizon daylight. It corresponds + approximately to 5000 K color temperature. + * - ``V4L2_WHITE_BALANCE_DAYLIGHT`` + - White balance preset for daylight (with clear sky). It corresponds + approximately to 5000...6500 K color temperature. + * - ``V4L2_WHITE_BALANCE_FLASH`` + - With this setting the camera will compensate for the flash light. + It slightly warms up the colors and corresponds roughly to + 5000...5500 K color temperature. + * - ``V4L2_WHITE_BALANCE_CLOUDY`` + - White balance preset for moderately overcast sky. This option + corresponds approximately to 6500...8000 K color temperature + range. + * - ``V4L2_WHITE_BALANCE_SHADE`` + - White balance preset for shade or heavily overcast sky. It + corresponds approximately to 9000...10000 K color temperature. + + + +.. _v4l2-wide-dynamic-range: + +``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)`` + Enables or disables the camera's wide dynamic range feature. This + feature allows to obtain clear images in situations where intensity + of the illumination varies significantly throughout the scene, i.e. + there are simultaneously very dark and very bright areas. It is most + commonly realized in cameras by combining two subsequent frames with + different exposure times. [#f1]_ + +.. _v4l2-image-stabilization: + +``V4L2_CID_IMAGE_STABILIZATION (boolean)`` + Enables or disables image stabilization. + +``V4L2_CID_ISO_SENSITIVITY (integer menu)`` + Determines ISO equivalent of an image sensor indicating the sensor's + sensitivity to light. The numbers are expressed in arithmetic scale, + as per :ref:`iso12232` standard, where doubling the sensor + sensitivity is represented by doubling the numerical ISO value. + Applications should interpret the values as standard ISO values + multiplied by 1000, e.g. control value 800 stands for ISO 0.8. + Drivers will usually support only a subset of standard ISO values. + The effect of setting this control while the + ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other + than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers + should ignore such requests. + +.. _v4l2-iso-sensitivity-auto-type: + +``V4L2_CID_ISO_SENSITIVITY_AUTO`` + (enum) + +enum v4l2_iso_sensitivity_type - + Enables or disables automatic ISO sensitivity adjustments. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` + - Manual ISO sensitivity. + * - ``V4L2_CID_ISO_SENSITIVITY_AUTO`` + - Automatic ISO sensitivity adjustments. + + + +.. _v4l2-scene-mode: + +``V4L2_CID_SCENE_MODE`` + (enum) + +enum v4l2_scene_mode - + This control allows to select scene programs as the camera automatic + modes optimized for common shooting scenes. Within these modes the + camera determines best exposure, aperture, focusing, light metering, + white balance and equivalent sensitivity. The controls of those + parameters are influenced by the scene mode control. An exact + behavior in each mode is subject to the camera specification. + + When the scene mode feature is not used, this control should be set + to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related + controls are accessible. The following scene programs are defined: + +.. tabularcolumns:: |p{6.0cm}|p{11.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_SCENE_MODE_NONE`` + - The scene mode feature is disabled. + * - ``V4L2_SCENE_MODE_BACKLIGHT`` + - Backlight. Compensates for dark shadows when light is coming from + behind a subject, also by automatically turning on the flash. + * - ``V4L2_SCENE_MODE_BEACH_SNOW`` + - Beach and snow. This mode compensates for all-white or bright + scenes, which tend to look gray and low contrast, when camera's + automatic exposure is based on an average scene brightness. To + compensate, this mode automatically slightly overexposes the + frames. The white balance may also be adjusted to compensate for + the fact that reflected snow looks bluish rather than white. + * - ``V4L2_SCENE_MODE_CANDLELIGHT`` + - Candle light. The camera generally raises the ISO sensitivity and + lowers the shutter speed. This mode compensates for relatively + close subject in the scene. The flash is disabled in order to + preserve the ambiance of the light. + * - ``V4L2_SCENE_MODE_DAWN_DUSK`` + - Dawn and dusk. Preserves the colors seen in low natural light + before dusk and after down. The camera may turn off the flash, and + automatically focus at infinity. It will usually boost saturation + and lower the shutter speed. + * - ``V4L2_SCENE_MODE_FALL_COLORS`` + - Fall colors. Increases saturation and adjusts white balance for + color enhancement. Pictures of autumn leaves get saturated reds + and yellows. + * - ``V4L2_SCENE_MODE_FIREWORKS`` + - Fireworks. Long exposure times are used to capture the expanding + burst of light from a firework. The camera may invoke image + stabilization. + * - ``V4L2_SCENE_MODE_LANDSCAPE`` + - Landscape. The camera may choose a small aperture to provide deep + depth of field and long exposure duration to help capture detail + in dim light conditions. The focus is fixed at infinity. Suitable + for distant and wide scenery. + * - ``V4L2_SCENE_MODE_NIGHT`` + - Night, also known as Night Landscape. Designed for low light + conditions, it preserves detail in the dark areas without blowing + out bright objects. The camera generally sets itself to a + medium-to-high ISO sensitivity, with a relatively long exposure + time, and turns flash off. As such, there will be increased image + noise and the possibility of blurred image. + * - ``V4L2_SCENE_MODE_PARTY_INDOOR`` + - Party and indoor. Designed to capture indoor scenes that are lit + by indoor background lighting as well as the flash. The camera + usually increases ISO sensitivity, and adjusts exposure for the + low light conditions. + * - ``V4L2_SCENE_MODE_PORTRAIT`` + - Portrait. The camera adjusts the aperture so that the depth of + field is reduced, which helps to isolate the subject against a + smooth background. Most cameras recognize the presence of faces in + the scene and focus on them. The color hue is adjusted to enhance + skin tones. The intensity of the flash is often reduced. + * - ``V4L2_SCENE_MODE_SPORTS`` + - Sports. Significantly increases ISO and uses a fast shutter speed + to freeze motion of rapidly-moving subjects. Increased image noise + may be seen in this mode. + * - ``V4L2_SCENE_MODE_SUNSET`` + - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps + up the saturation. + * - ``V4L2_SCENE_MODE_TEXT`` + - Text. It applies extra contrast and sharpness, it is typically a + black-and-white mode optimized for readability. Automatic focus + may be switched to close-up mode and this setting may also involve + some lens-distortion correction. + + + +``V4L2_CID_3A_LOCK (bitmask)`` + This control locks or unlocks the automatic focus, exposure and + white balance. The automatic adjustments can be paused independently + by setting the corresponding lock bit to 1. The camera then retains + the settings until the lock bit is cleared. The following lock bits + are defined: + + When a given algorithm is not enabled, drivers should ignore + requests to lock it and should return no error. An example might be + an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the + ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The + value of this control may be changed by exposure, white balance or + focus controls. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_LOCK_EXPOSURE`` + - Automatic exposure adjustments lock. + * - ``V4L2_LOCK_WHITE_BALANCE`` + - Automatic white balance adjustments lock. + * - ``V4L2_LOCK_FOCUS`` + - Automatic focus lock. + + + +``V4L2_CID_PAN_SPEED (integer)`` + This control turns the camera horizontally at the specific speed. + The unit is undefined. A positive value moves the camera to the + right (clockwise when viewed from above), a negative value to the + left. A value of zero stops the motion if one is in progress and has + no effect otherwise. + +``V4L2_CID_TILT_SPEED (integer)`` + This control turns the camera vertically at the specified speed. The + unit is undefined. A positive value moves the camera up, a negative + value down. A value of zero stops the motion if one is in progress + and has no effect otherwise. + +.. [#f1] + This control may be changed to a menu control in the future, if more + options are required. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst new file mode 100644 index 000000000000..c97fb7923be5 --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst @@ -0,0 +1,2451 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _mpeg-controls: + +*********************** +Codec Control Reference +*********************** + +Below all controls within the Codec control class are described. First +the generic controls, then controls specific for certain hardware. + +.. note:: + + These controls are applicable to all codecs and not just MPEG. The + defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls + were originally made for MPEG codecs and later extended to cover all + encoding formats. + + +Generic Codec Controls +====================== + + +.. _mpeg-control-id: + +Codec Control IDs +----------------- + +``V4L2_CID_MPEG_CLASS (class)`` + The Codec class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. This description can be + used as the caption of a Tab page in a GUI, for example. + +.. _v4l2-mpeg-stream-type: + +``V4L2_CID_MPEG_STREAM_TYPE`` + (enum) + +enum v4l2_mpeg_stream_type - + The MPEG-1, -2 or -4 output stream type. One cannot assume anything + here. Each hardware MPEG encoder tends to support different subsets + of the available MPEG stream types. This control is specific to + multiplexed MPEG streams. The currently defined stream types are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS`` + - MPEG-2 program stream + * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS`` + - MPEG-2 transport stream + * - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS`` + - MPEG-1 system stream + * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD`` + - MPEG-2 DVD-compatible stream + * - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD`` + - MPEG-1 VCD-compatible stream + * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD`` + - MPEG-2 SVCD-compatible stream + + + +``V4L2_CID_MPEG_STREAM_PID_PMT (integer)`` + Program Map Table Packet ID for the MPEG transport stream (default + 16) + +``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)`` + Audio Packet ID for the MPEG transport stream (default 256) + +``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)`` + Video Packet ID for the MPEG transport stream (default 260) + +``V4L2_CID_MPEG_STREAM_PID_PCR (integer)`` + Packet ID for the MPEG transport stream carrying PCR fields (default + 259) + +``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)`` + Audio ID for MPEG PES + +``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)`` + Video ID for MPEG PES + +.. _v4l2-mpeg-stream-vbi-fmt: + +``V4L2_CID_MPEG_STREAM_VBI_FMT`` + (enum) + +enum v4l2_mpeg_stream_vbi_fmt - + Some cards can embed VBI data (e. g. Closed Caption, Teletext) into + the MPEG stream. This control selects whether VBI data should be + embedded, and if so, what embedding method should be used. The list + of possible VBI formats depends on the driver. The currently defined + VBI format types are: + + + +.. tabularcolumns:: |p{6 cm}|p{11.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_STREAM_VBI_FMT_NONE`` + - No VBI in the MPEG stream + * - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV`` + - VBI in private packets, IVTV format (documented in the kernel + sources in the file + ``Documentation/media/v4l-drivers/cx2341x.rst``) + + + +.. _v4l2-mpeg-audio-sampling-freq: + +``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ`` + (enum) + +enum v4l2_mpeg_audio_sampling_freq - + MPEG Audio sampling frequency. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100`` + - 44.1 kHz + * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000`` + - 48 kHz + * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000`` + - 32 kHz + + + +.. _v4l2-mpeg-audio-encoding: + +``V4L2_CID_MPEG_AUDIO_ENCODING`` + (enum) + +enum v4l2_mpeg_audio_encoding - + MPEG Audio encoding. This control is specific to multiplexed MPEG + streams. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1`` + - MPEG-1/2 Layer I encoding + * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2`` + - MPEG-1/2 Layer II encoding + * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3`` + - MPEG-1/2 Layer III encoding + * - ``V4L2_MPEG_AUDIO_ENCODING_AAC`` + - MPEG-2/4 AAC (Advanced Audio Coding) + * - ``V4L2_MPEG_AUDIO_ENCODING_AC3`` + - AC-3 aka ATSC A/52 encoding + + + +.. _v4l2-mpeg-audio-l1-bitrate: + +``V4L2_CID_MPEG_AUDIO_L1_BITRATE`` + (enum) + +enum v4l2_mpeg_audio_l1_bitrate - + MPEG-1/2 Layer I bitrate. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K`` + - 32 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K`` + - 64 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K`` + - 96 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K`` + - 128 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K`` + - 160 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K`` + - 192 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K`` + - 224 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K`` + - 256 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K`` + - 288 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K`` + - 320 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K`` + - 352 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K`` + - 384 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K`` + - 416 kbit/s + * - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K`` + - 448 kbit/s + + + +.. _v4l2-mpeg-audio-l2-bitrate: + +``V4L2_CID_MPEG_AUDIO_L2_BITRATE`` + (enum) + +enum v4l2_mpeg_audio_l2_bitrate - + MPEG-1/2 Layer II bitrate. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K`` + - 32 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K`` + - 48 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K`` + - 56 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K`` + - 64 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K`` + - 80 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K`` + - 96 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K`` + - 112 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K`` + - 128 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K`` + - 160 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K`` + - 192 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K`` + - 224 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K`` + - 256 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K`` + - 320 kbit/s + * - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K`` + - 384 kbit/s + + + +.. _v4l2-mpeg-audio-l3-bitrate: + +``V4L2_CID_MPEG_AUDIO_L3_BITRATE`` + (enum) + +enum v4l2_mpeg_audio_l3_bitrate - + MPEG-1/2 Layer III bitrate. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K`` + - 32 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K`` + - 40 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K`` + - 48 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K`` + - 56 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K`` + - 64 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K`` + - 80 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K`` + - 96 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K`` + - 112 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K`` + - 128 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K`` + - 160 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K`` + - 192 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K`` + - 224 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K`` + - 256 kbit/s + * - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K`` + - 320 kbit/s + + + +``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)`` + AAC bitrate in bits per second. + +.. _v4l2-mpeg-audio-ac3-bitrate: + +``V4L2_CID_MPEG_AUDIO_AC3_BITRATE`` + (enum) + +enum v4l2_mpeg_audio_ac3_bitrate - + AC-3 bitrate. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K`` + - 32 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K`` + - 40 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K`` + - 48 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K`` + - 56 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K`` + - 64 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K`` + - 80 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K`` + - 96 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K`` + - 112 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K`` + - 128 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K`` + - 160 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K`` + - 192 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K`` + - 224 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K`` + - 256 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K`` + - 320 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K`` + - 384 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K`` + - 448 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K`` + - 512 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K`` + - 576 kbit/s + * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K`` + - 640 kbit/s + + + +.. _v4l2-mpeg-audio-mode: + +``V4L2_CID_MPEG_AUDIO_MODE`` + (enum) + +enum v4l2_mpeg_audio_mode - + MPEG Audio mode. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_MODE_STEREO`` + - Stereo + * - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO`` + - Joint Stereo + * - ``V4L2_MPEG_AUDIO_MODE_DUAL`` + - Bilingual + * - ``V4L2_MPEG_AUDIO_MODE_MONO`` + - Mono + + + +.. _v4l2-mpeg-audio-mode-extension: + +``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION`` + (enum) + +enum v4l2_mpeg_audio_mode_extension - + Joint Stereo audio mode extension. In Layer I and II they indicate + which subbands are in intensity stereo. All other subbands are coded + in stereo. Layer III is not (yet) supported. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4`` + - Subbands 4-31 in intensity stereo + * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8`` + - Subbands 8-31 in intensity stereo + * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12`` + - Subbands 12-31 in intensity stereo + * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16`` + - Subbands 16-31 in intensity stereo + + + +.. _v4l2-mpeg-audio-emphasis: + +``V4L2_CID_MPEG_AUDIO_EMPHASIS`` + (enum) + +enum v4l2_mpeg_audio_emphasis - + Audio Emphasis. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE`` + - None + * - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS`` + - 50/15 microsecond emphasis + * - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17`` + - CCITT J.17 + + + +.. _v4l2-mpeg-audio-crc: + +``V4L2_CID_MPEG_AUDIO_CRC`` + (enum) + +enum v4l2_mpeg_audio_crc - + CRC method. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_CRC_NONE`` + - None + * - ``V4L2_MPEG_AUDIO_CRC_CRC16`` + - 16 bit parity check + + + +``V4L2_CID_MPEG_AUDIO_MUTE (boolean)`` + Mutes the audio when capturing. This is not done by muting audio + hardware, which can still produce a slight hiss, but in the encoder + itself, guaranteeing a fixed and reproducible audio bitstream. 0 = + unmuted, 1 = muted. + +.. _v4l2-mpeg-audio-dec-playback: + +``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` + (enum) + +enum v4l2_mpeg_audio_dec_playback - + Determines how monolingual audio should be played back. Possible + values are: + + + +.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO`` + - Automatically determines the best playback mode. + * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO`` + - Stereo playback. + * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT`` + - Left channel playback. + * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT`` + - Right channel playback. + * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO`` + - Mono playback. + * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO`` + - Stereo playback with swapped left and right channels. + + + +.. _v4l2-mpeg-audio-dec-multilingual-playback: + +``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` + (enum) + +enum v4l2_mpeg_audio_dec_playback - + Determines how multilingual audio should be played back. + +.. _v4l2-mpeg-video-encoding: + +``V4L2_CID_MPEG_VIDEO_ENCODING`` + (enum) + +enum v4l2_mpeg_video_encoding - + MPEG Video encoding method. This control is specific to multiplexed + MPEG streams. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1`` + - MPEG-1 Video encoding + * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2`` + - MPEG-2 Video encoding + * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` + - MPEG-4 AVC (H.264) Video encoding + + + +.. _v4l2-mpeg-video-aspect: + +``V4L2_CID_MPEG_VIDEO_ASPECT`` + (enum) + +enum v4l2_mpeg_video_aspect - + Video aspect. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_ASPECT_1x1`` + * - ``V4L2_MPEG_VIDEO_ASPECT_4x3`` + * - ``V4L2_MPEG_VIDEO_ASPECT_16x9`` + * - ``V4L2_MPEG_VIDEO_ASPECT_221x100`` + + + +``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)`` + Number of B-Frames (default 2) + +``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)`` + GOP size (default 12) + +``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)`` + GOP closure (default 1) + +``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)`` + Enable 3:2 pulldown (default 0) + +.. _v4l2-mpeg-video-bitrate-mode: + +``V4L2_CID_MPEG_VIDEO_BITRATE_MODE`` + (enum) + +enum v4l2_mpeg_video_bitrate_mode - + Video bitrate mode. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR`` + - Variable bitrate + * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR`` + - Constant bitrate + + + +``V4L2_CID_MPEG_VIDEO_BITRATE (integer)`` + Video bitrate in bits per second. + +``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)`` + Peak video bitrate in bits per second. Must be larger or equal to + the average video bitrate. It is ignored if the video bitrate mode + is set to constant bitrate. + +``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)`` + For every captured frame, skip this many subsequent frames (default + 0). + +``V4L2_CID_MPEG_VIDEO_MUTE (boolean)`` + "Mutes" the video to a fixed color when capturing. This is useful + for testing, to produce a fixed video bitstream. 0 = unmuted, 1 = + muted. + +``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)`` + Sets the "mute" color of the video. The supplied 32-bit integer is + interpreted as follows (bit 0 = least significant bit): + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - Bit 0:7 + - V chrominance information + * - Bit 8:15 + - U chrominance information + * - Bit 16:23 + - Y luminance information + * - Bit 24:31 + - Must be zero. + + + +.. _v4l2-mpeg-video-dec-pts: + +``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)`` + This read-only control returns the 33-bit video Presentation Time + Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the + currently displayed frame. This is the same PTS as is used in + :ref:`VIDIOC_DECODER_CMD`. + +.. _v4l2-mpeg-video-dec-frame: + +``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)`` + This read-only control returns the frame counter of the frame that + is currently displayed (decoded). This value is reset to 0 whenever + the decoder is started. + +``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)`` + If enabled the decoder expects to receive a single slice per buffer, + otherwise the decoder expects a single frame in per buffer. + Applicable to the decoder, all codecs. + +``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)`` + Enable writing sample aspect ratio in the Video Usability + Information. Applicable to the H264 encoder. + +.. _v4l2-mpeg-video-h264-vui-sar-idc: + +``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC`` + (enum) + +enum v4l2_mpeg_video_h264_vui_sar_idc - + VUI sample aspect ratio indicator for H.264 encoding. The value is + defined in the table E-1 in the standard. Applicable to the H264 + encoder. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED`` + - Unspecified + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1`` + - 1x1 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11`` + - 12x11 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11`` + - 10x11 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11`` + - 16x11 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33`` + - 40x33 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11`` + - 24x11 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11`` + - 20x11 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11`` + - 32x11 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33`` + - 80x33 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11`` + - 18x11 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11`` + - 15x11 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33`` + - 64x33 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99`` + - 160x99 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3`` + - 4x3 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2`` + - 3x2 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1`` + - 2x1 + * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED`` + - Extended SAR + + + +``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)`` + Extended sample aspect ratio width for H.264 VUI encoding. + Applicable to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)`` + Extended sample aspect ratio height for H.264 VUI encoding. + Applicable to the H264 encoder. + +.. _v4l2-mpeg-video-h264-level: + +``V4L2_CID_MPEG_VIDEO_H264_LEVEL`` + (enum) + +enum v4l2_mpeg_video_h264_level - + The level information for the H264 video elementary stream. + Applicable to the H264 encoder. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0`` + - Level 1.0 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B`` + - Level 1B + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1`` + - Level 1.1 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2`` + - Level 1.2 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3`` + - Level 1.3 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0`` + - Level 2.0 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1`` + - Level 2.1 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2`` + - Level 2.2 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0`` + - Level 3.0 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1`` + - Level 3.1 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2`` + - Level 3.2 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0`` + - Level 4.0 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1`` + - Level 4.1 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2`` + - Level 4.2 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0`` + - Level 5.0 + * - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1`` + - Level 5.1 + + + +.. _v4l2-mpeg-video-mpeg4-level: + +``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL`` + (enum) + +enum v4l2_mpeg_video_mpeg4_level - + The level information for the MPEG4 elementary stream. Applicable to + the MPEG4 encoder. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_0`` + - Level 0 + * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_0B`` + - Level 0b + * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_1`` + - Level 1 + * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_2`` + - Level 2 + * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_3`` + - Level 3 + * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_3B`` + - Level 3b + * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_4`` + - Level 4 + * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_5`` + - Level 5 + + + +.. _v4l2-mpeg-video-h264-profile: + +``V4L2_CID_MPEG_VIDEO_H264_PROFILE`` + (enum) + +enum v4l2_mpeg_video_h264_profile - + The profile information for H264. Applicable to the H264 encoder. + Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE`` + - Baseline profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE`` + - Constrained Baseline profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN`` + - Main profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED`` + - Extended profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH`` + - High profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10`` + - High 10 profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422`` + - High 422 profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE`` + - High 444 Predictive profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA`` + - High 10 Intra profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA`` + - High 422 Intra profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA`` + - High 444 Intra profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA`` + - CAVLC 444 Intra profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE`` + - Scalable Baseline profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH`` + - Scalable High profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA`` + - Scalable High Intra profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH`` + - Stereo High profile + * - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH`` + - Multiview High profile + + + +.. _v4l2-mpeg-video-mpeg4-profile: + +``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE`` + (enum) + +enum v4l2_mpeg_video_mpeg4_profile - + The profile information for MPEG4. Applicable to the MPEG4 encoder. + Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE`` + - Simple profile + * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_SIMPLE`` + - Advanced Simple profile + * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_CORE`` + - Core profile + * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE_SCALABLE`` + - Simple Scalable profile + * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY`` + - + + + +``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)`` + The maximum number of reference pictures used for encoding. + Applicable to the encoder. + +.. _v4l2-mpeg-video-multi-slice-mode: + +``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` + (enum) + +enum v4l2_mpeg_video_multi_slice_mode - + Determines how the encoder should handle division of frame into + slices. Applicable to the encoder. Possible values are: + + + +.. tabularcolumns:: |p{8.7cm}|p{8.8cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE`` + - Single slice per frame. + * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB`` + - Multiple slices with set maximum number of macroblocks per slice. + * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES`` + - Multiple slice with set maximum size in bytes per slice. + + + +``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)`` + The maximum number of macroblocks in a slice. Used when + ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to + ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the + encoder. + +``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)`` + The maximum size of a slice in bytes. Used when + ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to + ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the + encoder. + +.. _v4l2-mpeg-video-h264-loop-filter-mode: + +``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE`` + (enum) + +enum v4l2_mpeg_video_h264_loop_filter_mode - + Loop filter mode for H264 encoder. Possible values are: + + + +.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED`` + - Loop filter is enabled. + * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED`` + - Loop filter is disabled. + * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY`` + - Loop filter is disabled at the slice boundary. + + + +``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)`` + Loop filter alpha coefficient, defined in the H264 standard. + This value corresponds to the slice_alpha_c0_offset_div2 slice header + field, and should be in the range of -6 to +6, inclusive. The actual alpha + offset FilterOffsetA is twice this value. + Applicable to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)`` + Loop filter beta coefficient, defined in the H264 standard. + This corresponds to the slice_beta_offset_div2 slice header field, and + should be in the range of -6 to +6, inclusive. The actual beta offset + FilterOffsetB is twice this value. + Applicable to the H264 encoder. + +.. _v4l2-mpeg-video-h264-entropy-mode: + +``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE`` + (enum) + +enum v4l2_mpeg_video_h264_entropy_mode - + Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264 + encoder. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC`` + - Use CAVLC entropy coding. + * - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC`` + - Use CABAC entropy coding. + + + +``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)`` + Enable 8X8 transform for H264. Applicable to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_CONSTRAINED_INTRA_PREDICTION (boolean)`` + Enable constrained intra prediction for H264. Applicable to the H264 + encoder. + +``V4L2_CID_MPEG_VIDEO_H264_CHROMA_QP_INDEX_OFFSET (integer)`` + Specify the offset that should be added to the luma quantization + parameter to determine the chroma quantization parameter. Applicable + to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)`` + Cyclic intra macroblock refresh. This is the number of continuous + macroblocks refreshed every frame. Each frame a successive set of + macroblocks is refreshed until the cycle completes and starts from + the top of the frame. Applicable to H264, H263 and MPEG4 encoder. + +``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)`` + Frame level rate control enable. If this control is disabled then + the quantization parameter for each frame type is constant and set + with appropriate controls (e.g. + ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is + enabled then quantization parameter is adjusted to meet the chosen + bitrate. Minimum and maximum value for the quantization parameter + can be set with appropriate controls (e.g. + ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders. + +``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)`` + Macroblock level rate control enable. Applicable to the MPEG4 and + H264 encoders. + +``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)`` + Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4 + encoder. + +``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)`` + Quantization parameter for an I frame for H263. Valid range: from 1 + to 31. + +``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)`` + Minimum quantization parameter for H263. Valid range: from 1 to 31. + +``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)`` + Maximum quantization parameter for H263. Valid range: from 1 to 31. + +``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)`` + Quantization parameter for an P frame for H263. Valid range: from 1 + to 31. + +``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)`` + Quantization parameter for an B frame for H263. Valid range: from 1 + to 31. + +``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)`` + Quantization parameter for an I frame for H264. Valid range: from 0 + to 51. + +``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)`` + Minimum quantization parameter for H264. Valid range: from 0 to 51. + +``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)`` + Maximum quantization parameter for H264. Valid range: from 0 to 51. + +``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)`` + Quantization parameter for an P frame for H264. Valid range: from 0 + to 51. + +``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)`` + Quantization parameter for an B frame for H264. Valid range: from 0 + to 51. + +``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)`` + Quantization parameter for an I frame for MPEG4. Valid range: from 1 + to 31. + +``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)`` + Minimum quantization parameter for MPEG4. Valid range: from 1 to 31. + +``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)`` + Maximum quantization parameter for MPEG4. Valid range: from 1 to 31. + +``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)`` + Quantization parameter for an P frame for MPEG4. Valid range: from 1 + to 31. + +``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)`` + Quantization parameter for an B frame for MPEG4. Valid range: from 1 + to 31. + +``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)`` + The Video Buffer Verifier size in kilobytes, it is used as a + limitation of frame skip. The VBV is defined in the standard as a + mean to verify that the produced stream will be successfully + decoded. The standard describes it as "Part of a hypothetical + decoder that is conceptually connected to the output of the encoder. + Its purpose is to provide a constraint on the variability of the + data rate that an encoder or editing process may produce.". + Applicable to the MPEG1, MPEG2, MPEG4 encoders. + +.. _v4l2-mpeg-video-vbv-delay: + +``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)`` + Sets the initial delay in milliseconds for VBV buffer control. + +.. _v4l2-mpeg-video-hor-search-range: + +``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)`` + Horizontal search range defines maximum horizontal search area in + pixels to search and match for the present Macroblock (MB) in the + reference picture. This V4L2 control macro is used to set horizontal + search range for motion estimation module in video encoder. + +.. _v4l2-mpeg-video-vert-search-range: + +``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)`` + Vertical search range defines maximum vertical search area in pixels + to search and match for the present Macroblock (MB) in the reference + picture. This V4L2 control macro is used to set vertical search + range for motion estimation module in video encoder. + +.. _v4l2-mpeg-video-force-key-frame: + +``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)`` + Force a key frame for the next queued buffer. Applicable to + encoders. This is a general, codec-agnostic keyframe control. + +``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)`` + The Coded Picture Buffer size in kilobytes, it is used as a + limitation of frame skip. The CPB is defined in the H264 standard as + a mean to verify that the produced stream will be successfully + decoded. Applicable to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)`` + Period between I-frames in the open GOP for H264. In case of an open + GOP this is the period between two I-frames. The period between IDR + (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE + control. An IDR frame, which stands for Instantaneous Decoding + Refresh is an I-frame after which no prior frames are referenced. + This means that a stream can be restarted from an IDR frame without + the need to store or decode any previous frames. Applicable to the + H264 encoder. + +.. _v4l2-mpeg-video-header-mode: + +``V4L2_CID_MPEG_VIDEO_HEADER_MODE`` + (enum) + +enum v4l2_mpeg_video_header_mode - + Determines whether the header is returned as the first buffer or is + it returned together with the first frame. Applicable to encoders. + Possible values are: + + + +.. tabularcolumns:: |p{10.3cm}|p{7.2cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE`` + - The stream header is returned separately in the first buffer. + * - ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME`` + - The stream header is returned together with the first encoded + frame. + + + +``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)`` + Repeat the video sequence headers. Repeating these headers makes + random access to the video stream easier. Applicable to the MPEG1, 2 + and 4 encoder. + +``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)`` + Enabled the deblocking post processing filter for MPEG4 decoder. + Applicable to the MPEG4 decoder. + +``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)`` + vop_time_increment_resolution value for MPEG4. Applicable to the + MPEG4 encoder. + +``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)`` + vop_time_increment value for MPEG4. Applicable to the MPEG4 + encoder. + +``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)`` + Enable generation of frame packing supplemental enhancement + information in the encoded bitstream. The frame packing SEI message + contains the arrangement of L and R planes for 3D viewing. + Applicable to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)`` + Sets current frame as frame0 in frame packing SEI. Applicable to the + H264 encoder. + +.. _v4l2-mpeg-video-h264-sei-fp-arrangement-type: + +``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE`` + (enum) + +enum v4l2_mpeg_video_h264_sei_fp_arrangement_type - + Frame packing arrangement type for H264 SEI. Applicable to the H264 + encoder. Possible values are: + +.. tabularcolumns:: |p{12cm}|p{5.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD`` + - Pixels are alternatively from L and R. + * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN`` + - L and R are interlaced by column. + * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW`` + - L and R are interlaced by row. + * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE`` + - L is on the left, R on the right. + * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM`` + - L is on top, R on bottom. + * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL`` + - One view per frame. + + + +``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)`` + Enables flexible macroblock ordering in the encoded bitstream. It is + a technique used for restructuring the ordering of macroblocks in + pictures. Applicable to the H264 encoder. + +.. _v4l2-mpeg-video-h264-fmo-map-type: + +``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE`` + (enum) + +enum v4l2_mpeg_video_h264_fmo_map_type - + When using FMO, the map type divides the image in different scan + patterns of macroblocks. Applicable to the H264 encoder. Possible + values are: + +.. tabularcolumns:: |p{12.5cm}|p{5.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES`` + - Slices are interleaved one after other with macroblocks in run + length order. + * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES`` + - Scatters the macroblocks based on a mathematical function known to + both encoder and decoder. + * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER`` + - Macroblocks arranged in rectangular areas or regions of interest. + * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT`` + - Slice groups grow in a cyclic way from centre to outwards. + * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN`` + - Slice groups grow in raster scan pattern from left to right. + * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN`` + - Slice groups grow in wipe scan pattern from top to bottom. + * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT`` + - User defined map type. + + + +``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)`` + Number of slice groups in FMO. Applicable to the H264 encoder. + +.. _v4l2-mpeg-video-h264-fmo-change-direction: + +``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION`` + (enum) + +enum v4l2_mpeg_video_h264_fmo_change_dir - + Specifies a direction of the slice group change for raster and wipe + maps. Applicable to the H264 encoder. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT`` + - Raster scan or wipe right. + * - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT`` + - Reverse raster scan or wipe left. + + + +``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)`` + Specifies the size of the first slice group for raster and wipe map. + Applicable to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)`` + Specifies the number of consecutive macroblocks for the interleaved + map. Applicable to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)`` + Enables arbitrary slice ordering in encoded bitstream. Applicable to + the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)`` + Specifies the slice order in ASO. Applicable to the H264 encoder. + The supplied 32-bit integer is interpreted as follows (bit 0 = least + significant bit): + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - Bit 0:15 + - Slice ID + * - Bit 16:32 + - Slice position or order + + + +``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)`` + Enables H264 hierarchical coding. Applicable to the H264 encoder. + +.. _v4l2-mpeg-video-h264-hierarchical-coding-type: + +``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE`` + (enum) + +enum v4l2_mpeg_video_h264_hierarchical_coding_type - + Specifies the hierarchical coding type. Applicable to the H264 + encoder. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B`` + - Hierarchical B coding. + * - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P`` + - Hierarchical P coding. + + + +``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)`` + Specifies the number of hierarchical coding layers. Applicable to + the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)`` + Specifies a user defined QP for each layer. Applicable to the H264 + encoder. The supplied 32-bit integer is interpreted as follows (bit + 0 = least significant bit): + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - Bit 0:15 + - QP value + * - Bit 16:32 + - Layer number + + + +.. _v4l2-mpeg-mpeg2: + +``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)`` + Specifies the slice parameters (as extracted from the bitstream) for the + associated MPEG-2 slice data. This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for MPEG-2. + The bitstream parameters are defined according to :ref:`mpeg2part2`. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_mpeg2_slice_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_mpeg2_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``bit_size`` + - Size (in bits) of the current slice data. + * - __u32 + - ``data_bit_offset`` + - Offset (in bits) to the video data in the current slice data. + * - struct :c:type:`v4l2_mpeg2_sequence` + - ``sequence`` + - Structure with MPEG-2 sequence metadata, merging relevant fields from + the sequence header and sequence extension parts of the bitstream. + * - struct :c:type:`v4l2_mpeg2_picture` + - ``picture`` + - Structure with MPEG-2 picture metadata, merging relevant fields from + the picture header and picture coding extension parts of the bitstream. + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``forward_ref_ts`` + - Timestamp for the V4L2 capture buffer to use as forward reference, used + with B-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u32 + - ``quantiser_scale_code`` + - Code used to determine the quantization scale to use for the IDCT. + +.. c:type:: v4l2_mpeg2_sequence + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_mpeg2_sequence + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``horizontal_size`` + - The width of the displayable part of the frame's luminance component. + * - __u16 + - ``vertical_size`` + - The height of the displayable part of the frame's luminance component. + * - __u32 + - ``vbv_buffer_size`` + - Used to calculate the required size of the video buffering verifier, + defined (in bits) as: 16 * 1024 * vbv_buffer_size. + * - __u16 + - ``profile_and_level_indication`` + - The current profile and level indication as extracted from the + bitstream. + * - __u8 + - ``progressive_sequence`` + - Indication that all the frames for the sequence are progressive instead + of interlaced. + * - __u8 + - ``chroma_format`` + - The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4). + +.. c:type:: v4l2_mpeg2_picture + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_mpeg2_picture + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``picture_coding_type`` + - Picture coding type for the frame covered by the current slice + (V4L2_MPEG2_PICTURE_CODING_TYPE_I, V4L2_MPEG2_PICTURE_CODING_TYPE_P or + V4L2_MPEG2_PICTURE_CODING_TYPE_B). + * - __u8 + - ``f_code[2][2]`` + - Motion vector codes. + * - __u8 + - ``intra_dc_precision`` + - Precision of Discrete Cosine transform (0: 8 bits precision, + 1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision). + * - __u8 + - ``picture_structure`` + - Picture structure (1: interlaced top field, 2: interlaced bottom field, + 3: progressive frame). + * - __u8 + - ``top_field_first`` + - If set to 1 and interlaced stream, top field is output first. + * - __u8 + - ``frame_pred_frame_dct`` + - If set to 1, only frame-DCT and frame prediction are used. + * - __u8 + - ``concealment_motion_vectors`` + - If set to 1, motion vectors are coded for intra macroblocks. + * - __u8 + - ``q_scale_type`` + - This flag affects the inverse quantization process. + * - __u8 + - ``intra_vlc_format`` + - This flag affects the decoding of transform coefficient data. + * - __u8 + - ``alternate_scan`` + - This flag affects the decoding of transform coefficient data. + * - __u8 + - ``repeat_first_field`` + - This flag affects the decoding process of progressive frames. + * - __u16 + - ``progressive_frame`` + - Indicates whether the current frame is progressive. + +``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION (struct)`` + Specifies quantization matrices (as extracted from the bitstream) for the + associated MPEG-2 slice data. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_mpeg2_quantization + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_mpeg2_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``load_intra_quantiser_matrix`` + - One bit to indicate whether to load the ``intra_quantiser_matrix`` data. + * - __u8 + - ``load_non_intra_quantiser_matrix`` + - One bit to indicate whether to load the ``non_intra_quantiser_matrix`` + data. + * - __u8 + - ``load_chroma_intra_quantiser_matrix`` + - One bit to indicate whether to load the + ``chroma_intra_quantiser_matrix`` data, only relevant for non-4:2:0 YUV + formats. + * - __u8 + - ``load_chroma_non_intra_quantiser_matrix`` + - One bit to indicate whether to load the + ``chroma_non_intra_quantiser_matrix`` data, only relevant for non-4:2:0 + YUV formats. + * - __u8 + - ``intra_quantiser_matrix[64]`` + - The quantization matrix coefficients for intra-coded frames, in zigzag + scanning order. It is relevant for both luma and chroma components, + although it can be superseded by the chroma-specific matrix for + non-4:2:0 YUV formats. + * - __u8 + - ``non_intra_quantiser_matrix[64]`` + - The quantization matrix coefficients for non-intra-coded frames, in + zigzag scanning order. It is relevant for both luma and chroma + components, although it can be superseded by the chroma-specific matrix + for non-4:2:0 YUV formats. + * - __u8 + - ``chroma_intra_quantiser_matrix[64]`` + - The quantization matrix coefficients for the chominance component of + intra-coded frames, in zigzag scanning order. Only relevant for + non-4:2:0 YUV formats. + * - __u8 + - ``chroma_non_intra_quantiser_matrix[64]`` + - The quantization matrix coefficients for the chrominance component of + non-intra-coded frames, in zigzag scanning order. Only relevant for + non-4:2:0 YUV formats. + +MFC 5.1 MPEG Controls +===================== + +The following MPEG class controls deal with MPEG decoding and encoding +settings that are specific to the Multi Format Codec 5.1 device present +in the S5P family of SoCs by Samsung. + + +.. _mfc51-control-id: + +MFC 5.1 Control IDs +------------------- + +``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE (boolean)`` + If the display delay is enabled then the decoder is forced to return + a CAPTURE buffer (decoded frame) after processing a certain number + of OUTPUT buffers. The delay can be set through + ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This + feature can be used for example for generating thumbnails of videos. + Applicable to the H264 decoder. + +``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)`` + Display delay value for H264 decoder. The decoder is forced to + return a decoded frame after the set 'display delay' number of + frames. If this number is low it may result in frames returned out + of display order, in addition the hardware may still be using the + returned buffer as a reference picture for subsequent frames. + +``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)`` + The number of reference pictures used for encoding a P picture. + Applicable to the H264 encoder. + +``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)`` + Padding enable in the encoder - use a color instead of repeating + border pixels. Applicable to encoders. + +``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)`` + Padding color in the encoder. Applicable to encoders. The supplied + 32-bit integer is interpreted as follows (bit 0 = least significant + bit): + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - Bit 0:7 + - V chrominance information + * - Bit 8:15 + - U chrominance information + * - Bit 16:23 + - Y luminance information + * - Bit 24:31 + - Must be zero. + + + +``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)`` + Reaction coefficient for MFC rate control. Applicable to encoders. + + .. note:: + + #. Valid only when the frame level RC is enabled. + + #. For tight CBR, this field must be small (ex. 2 ~ 10). For + VBR, this field must be large (ex. 100 ~ 1000). + + #. It is not recommended to use the greater number than + FRAME_RATE * (10^9 / BIT_RATE). + +``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)`` + Adaptive rate control for dark region. Valid only when H.264 and + macroblock level RC is enabled + (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264 + encoder. + +``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)`` + Adaptive rate control for smooth region. Valid only when H.264 and + macroblock level RC is enabled + (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264 + encoder. + +``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)`` + Adaptive rate control for static region. Valid only when H.264 and + macroblock level RC is enabled + (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264 + encoder. + +``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)`` + Adaptive rate control for activity region. Valid only when H.264 and + macroblock level RC is enabled + (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264 + encoder. + +.. _v4l2-mpeg-mfc51-video-frame-skip-mode: + +``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE`` + (enum) + +enum v4l2_mpeg_mfc51_video_frame_skip_mode - + Indicates in what conditions the encoder should skip frames. If + encoding a frame would cause the encoded stream to be larger then a + chosen data limit then the frame will be skipped. Possible values + are: + + +.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED`` + - Frame skip mode is disabled. + * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT`` + - Frame skip mode enabled and buffer limit is set by the chosen + level and is defined by the standard. + * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT`` + - Frame skip mode enabled and buffer limit is set by the VBV + (MPEG1/2/4) or CPB (H264) buffer size control. + + + +``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)`` + Enable rate-control with fixed target bit. If this setting is + enabled, then the rate control logic of the encoder will calculate + the average bitrate for a GOP and keep it below or equal the set + bitrate target. Otherwise the rate control logic calculates the + overall average bitrate for the stream and keeps it below or equal + to the set bitrate. In the first case the average bitrate for the + whole stream will be smaller then the set bitrate. This is caused + because the average is calculated for smaller number of frames, on + the other hand enabling this setting will ensure that the stream + will meet tight bandwidth constraints. Applicable to encoders. + +.. _v4l2-mpeg-mfc51-video-force-frame-type: + +``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE`` + (enum) + +enum v4l2_mpeg_mfc51_video_force_frame_type - + Force a frame type for the next queued buffer. Applicable to + encoders. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED`` + - Forcing a specific frame type disabled. + * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME`` + - Force an I-frame. + * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED`` + - Force a non-coded frame. + + + + +CX2341x MPEG Controls +===================== + +The following MPEG class controls deal with MPEG encoding settings that +are specific to the Conexant CX23415 and CX23416 MPEG encoding chips. + + +.. _cx2341x-control-id: + +CX2341x Control IDs +------------------- + +.. _v4l2-mpeg-cx2341x-video-spatial-filter-mode: + +``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE`` + (enum) + +enum v4l2_mpeg_cx2341x_video_spatial_filter_mode - + Sets the Spatial Filter mode (default ``MANUAL``). Possible values + are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL`` + - Choose the filter manually + * - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO`` + - Choose the filter automatically + + + +``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))`` + The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default + is 0.) + +.. _luma-spatial-filter-type: + +``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE`` + (enum) + +enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - + Select the algorithm to use for the Luma Spatial Filter (default + ``1D_HOR``). Possible values: + + + +.. tabularcolumns:: |p{14.5cm}|p{3.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF`` + - No filter + * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR`` + - One-dimensional horizontal + * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT`` + - One-dimensional vertical + * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE`` + - Two-dimensional separable + * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE`` + - Two-dimensional symmetrical non-separable + + + +.. _chroma-spatial-filter-type: + +``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE`` + (enum) + +enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - + Select the algorithm for the Chroma Spatial Filter (default + ``1D_HOR``). Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF`` + - No filter + * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR`` + - One-dimensional horizontal + + + +.. _v4l2-mpeg-cx2341x-video-temporal-filter-mode: + +``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE`` + (enum) + +enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - + Sets the Temporal Filter mode (default ``MANUAL``). Possible values + are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL`` + - Choose the filter manually + * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO`` + - Choose the filter automatically + + + +``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))`` + The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default + is 8 for full-scale capturing and 0 for scaled capturing.) + +.. _v4l2-mpeg-cx2341x-video-median-filter-type: + +``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE`` + (enum) + +enum v4l2_mpeg_cx2341x_video_median_filter_type - + Median Filter Type (default ``OFF``). Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF`` + - No filter + * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR`` + - Horizontal filter + * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT`` + - Vertical filter + * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT`` + - Horizontal and vertical filter + * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG`` + - Diagonal filter + + + +``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))`` + Threshold above which the luminance median filter is enabled + (default 0) + +``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))`` + Threshold below which the luminance median filter is enabled + (default 255) + +``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))`` + Threshold above which the chroma median filter is enabled (default + 0) + +``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))`` + Threshold below which the chroma median filter is enabled (default + 255) + +``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)`` + The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into + the stream between every four video frames. The packet size is 2048 + bytes, including the packet_start_code_prefix and stream_id + fields. The stream_id is 0xBF (private stream 2). The payload + consists of 0x00 bytes, to be filled in by the application. 0 = do + not insert, 1 = insert packets. + + +VPX Control Reference +===================== + +The VPX controls include controls for encoding parameters of VPx video +codec. + + +.. _vpx-control-id: + +VPX Control IDs +--------------- + +.. _v4l2-vpx-num-partitions: + +``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS`` + (enum) + +enum v4l2_vp8_num_partitions - + The number of token partitions to use in VP8 encoder. Possible + values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION`` + - 1 coefficient partition + * - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS`` + - 2 coefficient partitions + * - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS`` + - 4 coefficient partitions + * - ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS`` + - 8 coefficient partitions + + + +``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)`` + Setting this prevents intra 4x4 mode in the intra mode decision. + +.. _v4l2-vpx-num-ref-frames: + +``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES`` + (enum) + +enum v4l2_vp8_num_ref_frames - + The number of reference pictures for encoding P frames. Possible + values are: + +.. tabularcolumns:: |p{7.9cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME`` + - Last encoded frame will be searched + * - ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME`` + - Two frames will be searched among the last encoded frame, the + golden frame and the alternate reference (altref) frame. The + encoder implementation will decide which two are chosen. + * - ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME`` + - The last encoded frame, the golden frame and the altref frame will + be searched. + + + +``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)`` + Indicates the loop filter level. The adjustment of the loop filter + level is done via a delta value against a baseline loop filter + value. + +``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)`` + This parameter affects the loop filter. Anything above zero weakens + the deblocking effect on the loop filter. + +``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)`` + Sets the refresh period for the golden frame. The period is defined + in number of frames. For a value of 'n', every nth frame starting + from the first key frame will be taken as a golden frame. For eg. + for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden + frame refresh period is set as 4, the frames 0, 4, 8 etc will be + taken as the golden frames as frame 0 is always a key frame. + +.. _v4l2-vpx-golden-frame-sel: + +``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL`` + (enum) + +enum v4l2_vp8_golden_frame_sel - + Selects the golden frame for encoding. Possible values are: + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV`` + - Use the (n-2)th frame as a golden frame, current frame index being + 'n'. + * - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD`` + - Use the previous specific frame indicated by + ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD`` as a + golden frame. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)`` + Minimum quantization parameter for VP8. + +``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)`` + Maximum quantization parameter for VP8. + +``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)`` + Quantization parameter for an I frame for VP8. + +``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)`` + Quantization parameter for a P frame for VP8. + +.. _v4l2-mpeg-video-vp8-profile: + +``V4L2_CID_MPEG_VIDEO_VP8_PROFILE`` + (enum) + +enum v4l2_mpeg_video_vp8_profile - + This control allows selecting the profile for VP8 encoder. + This is also used to enumerate supported profiles by VP8 encoder or decoder. + Possible values are: + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_0`` + - Profile 0 + * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_1`` + - Profile 1 + * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_2`` + - Profile 2 + * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_3`` + - Profile 3 + +.. _v4l2-mpeg-video-vp9-profile: + +``V4L2_CID_MPEG_VIDEO_VP9_PROFILE`` + (enum) + +enum v4l2_mpeg_video_vp9_profile - + This control allows selecting the profile for VP9 encoder. + This is also used to enumerate supported profiles by VP9 encoder or decoder. + Possible values are: + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_0`` + - Profile 0 + * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_1`` + - Profile 1 + * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_2`` + - Profile 2 + * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_3`` + - Profile 3 + + +High Efficiency Video Coding (HEVC/H.265) Control Reference +=========================================================== + +The HEVC/H.265 controls include controls for encoding parameters of HEVC/H.265 +video codec. + + +.. _hevc-control-id: + +HEVC/H.265 Control IDs +---------------------- + +``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP (integer)`` + Minimum quantization parameter for HEVC. + Valid range: from 0 to 51. + +``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP (integer)`` + Maximum quantization parameter for HEVC. + Valid range: from 0 to 51. + +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_QP (integer)`` + Quantization parameter for an I frame for HEVC. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_QP (integer)`` + Quantization parameter for a P frame for HEVC. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_QP (integer)`` + Quantization parameter for a B frame for HEVC. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_QP (boolean)`` + HIERARCHICAL_QP allows the host to specify the quantization parameter + values for each temporal layer through HIERARCHICAL_QP_LAYER. This is + valid only if HIERARCHICAL_CODING_LAYER is greater than 1. Setting the + control value to 1 enables setting of the QP values for the layers. + +.. _v4l2-hevc-hier-coding-type: + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_TYPE`` + (enum) + +enum v4l2_mpeg_video_hevc_hier_coding_type - + Selects the hierarchical coding type for encoding. Possible values are: + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_HIERARCHICAL_CODING_B`` + - Use the B frame for hierarchical coding. + * - ``V4L2_MPEG_VIDEO_HEVC_HIERARCHICAL_CODING_P`` + - Use the P frame for hierarchical coding. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_LAYER (integer)`` + Selects the hierarchical coding layer. In normal encoding + (non-hierarchial coding), it should be zero. Possible values are [0, 6]. + 0 indicates HIERARCHICAL CODING LAYER 0, 1 indicates HIERARCHICAL CODING + LAYER 1 and so on. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 0. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 1. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 2. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 3. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 4. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 5. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 6. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +.. _v4l2-hevc-profile: + +``V4L2_CID_MPEG_VIDEO_HEVC_PROFILE`` + (enum) + +enum v4l2_mpeg_video_hevc_profile - + Select the desired profile for HEVC encoder. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN`` + - Main profile. + * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_STILL_PICTURE`` + - Main still picture profile. + * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_10`` + - Main 10 profile. + +.. raw:: latex + + \normalsize + + +.. _v4l2-hevc-level: + +``V4L2_CID_MPEG_VIDEO_HEVC_LEVEL`` + (enum) + +enum v4l2_mpeg_video_hevc_level - + Selects the desired level for HEVC encoder. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` + - Level 1.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` + - Level 2.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` + - Level 2.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` + - Level 3.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` + - Level 3.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` + - Level 4.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` + - Level 4.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` + - Level 5.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` + - Level 5.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` + - Level 5.2 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` + - Level 6.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` + - Level 6.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` + - Level 6.2 + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_FRAME_RATE_RESOLUTION (integer)`` + Indicates the number of evenly spaced subintervals, called ticks, within + one second. This is a 16 bit unsigned integer and has a maximum value up to + 0xffff and a minimum value of 1. + +.. _v4l2-hevc-tier: + +``V4L2_CID_MPEG_VIDEO_HEVC_TIER`` + (enum) + +enum v4l2_mpeg_video_hevc_tier - + TIER_FLAG specifies tiers information of the HEVC encoded picture. Tier + were made to deal with applications that differ in terms of maximum bit + rate. Setting the flag to 0 selects HEVC tier as Main tier and setting + this flag to 1 indicates High tier. High tier is for applications requiring + high bit rates. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` + - Main tier. + * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` + - High tier. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)`` + Selects HEVC maximum coding unit depth. + +.. _v4l2-hevc-loop-filter-mode: + +``V4L2_CID_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE`` + (enum) + +enum v4l2_mpeg_video_hevc_loop_filter_mode - + Loop filter mode for HEVC encoder. Possible values are: + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{10.7cm}|p{6.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_DISABLED`` + - Loop filter is disabled. + * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_ENABLED`` + - Loop filter is enabled. + * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY`` + - Loop filter is disabled at the slice boundary. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_LF_BETA_OFFSET_DIV2 (integer)`` + Selects HEVC loop filter beta offset. The valid range is [-6, +6]. + +``V4L2_CID_MPEG_VIDEO_HEVC_LF_TC_OFFSET_DIV2 (integer)`` + Selects HEVC loop filter tc offset. The valid range is [-6, +6]. + +.. _v4l2-hevc-refresh-type: + +``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_TYPE`` + (enum) + +enum v4l2_mpeg_video_hevc_hier_refresh_type - + Selects refresh type for HEVC encoder. + Host has to specify the period into + V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_PERIOD. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.0cm}|p{9.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_NONE`` + - Use the B frame for hierarchical coding. + * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_CRA`` + - Use CRA (Clean Random Access Unit) picture encoding. + * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_IDR`` + - Use IDR (Instantaneous Decoding Refresh) picture encoding. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_PERIOD (integer)`` + Selects the refresh period for HEVC encoder. + This specifies the number of I pictures between two CRA/IDR pictures. + This is valid only if REFRESH_TYPE is not 0. + +``V4L2_CID_MPEG_VIDEO_HEVC_LOSSLESS_CU (boolean)`` + Indicates HEVC lossless encoding. Setting it to 0 disables lossless + encoding. Setting it to 1 enables lossless encoding. + +``V4L2_CID_MPEG_VIDEO_HEVC_CONST_INTRA_PRED (boolean)`` + Indicates constant intra prediction for HEVC encoder. Specifies the + constrained intra prediction in which intra largest coding unit (LCU) + prediction is performed by using residual data and decoded samples of + neighboring intra LCU only. Setting the value to 1 enables constant intra + prediction and setting the value to 0 disables constant intra prediction. + +``V4L2_CID_MPEG_VIDEO_HEVC_WAVEFRONT (boolean)`` + Indicates wavefront parallel processing for HEVC encoder. Setting it to 0 + disables the feature and setting it to 1 enables the wavefront parallel + processing. + +``V4L2_CID_MPEG_VIDEO_HEVC_GENERAL_PB (boolean)`` + Setting the value to 1 enables combination of P and B frame for HEVC + encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_TEMPORAL_ID (boolean)`` + Indicates temporal identifier for HEVC encoder which is enabled by + setting the value to 1. + +``V4L2_CID_MPEG_VIDEO_HEVC_STRONG_SMOOTHING (boolean)`` + Indicates bi-linear interpolation is conditionally used in the intra + prediction filtering process in the CVS when set to 1. Indicates bi-linear + interpolation is not used in the CVS when set to 0. + +``V4L2_CID_MPEG_VIDEO_HEVC_MAX_NUM_MERGE_MV_MINUS1 (integer)`` + Indicates maximum number of merge candidate motion vectors. + Values are from 0 to 4. + +``V4L2_CID_MPEG_VIDEO_HEVC_TMV_PREDICTION (boolean)`` + Indicates temporal motion vector prediction for HEVC encoder. Setting it to + 1 enables the prediction. Setting it to 0 disables the prediction. + +``V4L2_CID_MPEG_VIDEO_HEVC_WITHOUT_STARTCODE (boolean)`` + Specifies if HEVC generates a stream with a size of the length field + instead of start code pattern. The size of the length field is configurable + through the V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD control. Setting + the value to 0 disables encoding without startcode pattern. Setting the + value to 1 will enables encoding without startcode pattern. + +.. _v4l2-hevc-size-of-length-field: + +``V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD`` +(enum) + +enum v4l2_mpeg_video_hevc_size_of_length_field - + Indicates the size of length field. + This is valid when encoding WITHOUT_STARTCODE_ENABLE is enabled. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{6.0cm}|p{11.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_0`` + - Generate start code pattern (Normal). + * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_1`` + - Generate size of length field instead of start code pattern and length is 1. + * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_2`` + - Generate size of length field instead of start code pattern and length is 2. + * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_4`` + - Generate size of length field instead of start code pattern and length is 4. + +.. raw:: latex + + \normalsize + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_BR (integer)`` + Indicates bit rate for hierarchical coding layer 0 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_BR (integer)`` + Indicates bit rate for hierarchical coding layer 1 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_BR (integer)`` + Indicates bit rate for hierarchical coding layer 2 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_BR (integer)`` + Indicates bit rate for hierarchical coding layer 3 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_BR (integer)`` + Indicates bit rate for hierarchical coding layer 4 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_BR (integer)`` + Indicates bit rate for hierarchical coding layer 5 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_BR (integer)`` + Indicates bit rate for hierarchical coding layer 6 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_REF_NUMBER_FOR_PFRAMES (integer)`` + Selects number of P reference pictures required for HEVC encoder. + P-Frame can use 1 or 2 frames for reference. + +``V4L2_CID_MPEG_VIDEO_PREPEND_SPSPPS_TO_IDR (integer)`` + Indicates whether to generate SPS and PPS at every IDR. Setting it to 0 + disables generating SPS and PPS at every IDR. Setting it to one enables + generating SPS and PPS at every IDR. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-detect.rst b/Documentation/media/uapi/v4l/ext-ctrls-detect.rst new file mode 100644 index 000000000000..8a45ce642829 --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-detect.rst @@ -0,0 +1,71 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _detect-controls: + +************************ +Detect Control Reference +************************ + +The Detect class includes controls for common features of various motion +or object detection capable devices. + + +.. _detect-control-id: + +Detect Control IDs +================== + +``V4L2_CID_DETECT_CLASS (class)`` + The Detect class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_DETECT_MD_MODE (menu)`` + Sets the motion detection mode. + +.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_DETECT_MD_MODE_DISABLED`` + - Disable motion detection. + * - ``V4L2_DETECT_MD_MODE_GLOBAL`` + - Use a single motion detection threshold. + * - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` + - The image is divided into a grid, each cell with its own motion + detection threshold. These thresholds are set through the + ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control. + * - ``V4L2_DETECT_MD_MODE_REGION_GRID`` + - The image is divided into a grid, each cell with its own region + value that specifies which per-region motion detection thresholds + should be used. Each region has its own thresholds. How these + per-region thresholds are set up is driver-specific. The region + values for the grid are set through the + ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control. + + + +``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)`` + Sets the global motion detection threshold to be used with the + ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode. + +``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)`` + Sets the motion detection thresholds for each cell in the grid. To + be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion + detection mode. Matrix element (0, 0) represents the cell at the + top-left of the grid. + +``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)`` + Sets the motion detection region value for each cell in the grid. To + be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion + detection mode. Matrix element (0, 0) represents the cell at the + top-left of the grid. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-dv.rst b/Documentation/media/uapi/v4l/ext-ctrls-dv.rst new file mode 100644 index 000000000000..57edf211875c --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-dv.rst @@ -0,0 +1,166 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _dv-controls: + +******************************* +Digital Video Control Reference +******************************* + +The Digital Video control class is intended to control receivers and +transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__, +`DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__ +(Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort +(:ref:`dp`). These controls are generally expected to be private to +the receiver or transmitter subdevice that implements them, so they are +only exposed on the ``/dev/v4l-subdev*`` device node. + +.. note:: + + Note that these devices can have multiple input or output pads which are + hooked up to e.g. HDMI connectors. Even though the subdevice will + receive or transmit video from/to only one of those pads, the other pads + can still be active when it comes to EDID (Extended Display + Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital + Content Protection System, :ref:`hdcp`) processing, allowing the + device to do the fairly slow EDID/HDCP handling in advance. This allows + for quick switching between connectors. + +These pads appear in several of the controls in this section as +bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad +1, etc. The maximum value of the control is the set of valid pads. + + +.. _dv-control-id: + +Digital Video Control IDs +========================= + +``V4L2_CID_DV_CLASS (class)`` + The Digital Video class descriptor. + +``V4L2_CID_DV_TX_HOTPLUG (bitmask)`` + Many connectors have a hotplug pin which is high if EDID information + is available from the source. This control shows the state of the + hotplug pin as seen by the transmitter. Each bit corresponds to an + output pad on the transmitter. If an output pad does not have an + associated hotplug pin, then the bit for that pad will be 0. This + read-only control is applicable to DVI-D, HDMI and DisplayPort + connectors. + +``V4L2_CID_DV_TX_RXSENSE (bitmask)`` + Rx Sense is the detection of pull-ups on the TMDS clock lines. This + normally means that the sink has left/entered standby (i.e. the + transmitter can sense that the receiver is ready to receive video). + Each bit corresponds to an output pad on the transmitter. If an + output pad does not have an associated Rx Sense, then the bit for + that pad will be 0. This read-only control is applicable to DVI-D + and HDMI devices. + +``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)`` + When the transmitter sees the hotplug signal from the receiver it + will attempt to read the EDID. If set, then the transmitter has read + at least the first block (= 128 bytes). Each bit corresponds to an + output pad on the transmitter. If an output pad does not support + EDIDs, then the bit for that pad will be 0. This read-only control + is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. + +``V4L2_CID_DV_TX_MODE`` + (enum) + +enum v4l2_dv_tx_mode - + HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI + mode (video + audio + auxiliary data). This control selects which + mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI. + This control is applicable to HDMI connectors. + +``V4L2_CID_DV_TX_RGB_RANGE`` + (enum) + +enum v4l2_dv_rgb_range - + Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO + follows the RGB quantization range specified in the standard for the + video interface (ie. :ref:`cea861` for HDMI). + V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the + standard to be compatible with sinks that have not implemented the + standard correctly (unfortunately quite common for HDMI and DVI-D). + Full range allows all possible values to be used whereas limited + range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is + the number of bits per component. This control is applicable to VGA, + DVI-A/D, HDMI and DisplayPort connectors. + +``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` + (enum) + +enum v4l2_dv_it_content_type - + Configures the IT Content Type of the transmitted video. This + information is sent over HDMI and DisplayPort connectors as part of + the AVI InfoFrame. The term 'IT Content' is used for content that + originates from a computer as opposed to content from a TV broadcast + or an analog source. The enum v4l2_dv_it_content_type defines + the possible content types: + +.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS`` + - Graphics content. Pixel data should be passed unfiltered and + without analog reconstruction. + * - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO`` + - Photo content. The content is derived from digital still pictures. + The content should be passed through with minimal scaling and + picture enhancements. + * - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA`` + - Cinema content. + * - ``V4L2_DV_IT_CONTENT_TYPE_GAME`` + - Game content. Audio and video latency should be minimized. + * - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC`` + - No IT Content information is available and the ITC bit in the AVI + InfoFrame is set to 0. + + + +``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)`` + Detects whether the receiver receives power from the source (e.g. + HDMI carries 5V on one of the pins). This is often used to power an + eeprom which contains EDID information, such that the source can + read the EDID even if the sink is in standby/power off. Each bit + corresponds to an input pad on the receiver. If an input pad + cannot detect whether power is present, then the bit for that pad + will be 0. This read-only control is applicable to DVI-D, HDMI and + DisplayPort connectors. + +``V4L2_CID_DV_RX_RGB_RANGE`` + (enum) + +enum v4l2_dv_rgb_range - + Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO + follows the RGB quantization range specified in the standard for the + video interface (ie. :ref:`cea861` for HDMI). + V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the + standard to be compatible with sources that have not implemented the + standard correctly (unfortunately quite common for HDMI and DVI-D). + Full range allows all possible values to be used whereas limited + range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is + the number of bits per component. This control is applicable to VGA, + DVI-A/D, HDMI and DisplayPort connectors. + +``V4L2_CID_DV_RX_IT_CONTENT_TYPE`` + (enum) + +enum v4l2_dv_it_content_type - + Reads the IT Content Type of the received video. This information is + sent over HDMI and DisplayPort connectors as part of the AVI + InfoFrame. The term 'IT Content' is used for content that originates + from a computer as opposed to content from a TV broadcast or an + analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the + available content types. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-flash.rst b/Documentation/media/uapi/v4l/ext-ctrls-flash.rst new file mode 100644 index 000000000000..5f30791c35b5 --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-flash.rst @@ -0,0 +1,192 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _flash-controls: + +*********************** +Flash Control Reference +*********************** + +The V4L2 flash controls are intended to provide generic access to flash +controller devices. Flash controller devices are typically used in +digital cameras. + +The interface can support both LED and xenon flash devices. As of +writing this, there is no xenon flash driver using this interface. + + +.. _flash-controls-use-cases: + +Supported use cases +=================== + + +Unsynchronised LED flash (software strobe) +------------------------------------------ + +Unsynchronised LED flash is controlled directly by the host as the +sensor. The flash must be enabled by the host before the exposure of the +image starts and disabled once it ends. The host is fully responsible +for the timing of the flash. + +Example of such device: Nokia N900. + + +Synchronised LED flash (hardware strobe) +---------------------------------------- + +The synchronised LED flash is pre-programmed by the host (power and +timeout) but controlled by the sensor through a strobe signal from the +sensor to the flash. + +The sensor controls the flash duration and timing. This information +typically must be made available to the sensor. + + +LED flash as torch +------------------ + +LED flash may be used as torch in conjunction with another use case +involving camera or individually. + + +.. _flash-control-id: + +Flash Control IDs +----------------- + +``V4L2_CID_FLASH_CLASS (class)`` + The FLASH class descriptor. + +``V4L2_CID_FLASH_LED_MODE (menu)`` + Defines the mode of the flash LED, the high-power white LED attached + to the flash controller. Setting this control may not be possible in + presence of some faults. See V4L2_CID_FLASH_FAULT. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_FLASH_LED_MODE_NONE`` + - Off. + * - ``V4L2_FLASH_LED_MODE_FLASH`` + - Flash mode. + * - ``V4L2_FLASH_LED_MODE_TORCH`` + - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. + + + +``V4L2_CID_FLASH_STROBE_SOURCE (menu)`` + Defines the source of the flash LED strobe. + +.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE`` + - The flash strobe is triggered by using the + V4L2_CID_FLASH_STROBE control. + * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL`` + - The flash strobe is triggered by an external source. Typically + this is a sensor, which makes it possible to synchronises the + flash strobe start to exposure start. + + + +``V4L2_CID_FLASH_STROBE (button)`` + Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to + V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE + is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this + control may not be possible in presence of some faults. See + V4L2_CID_FLASH_FAULT. + +``V4L2_CID_FLASH_STROBE_STOP (button)`` + Stop flash strobe immediately. + +``V4L2_CID_FLASH_STROBE_STATUS (boolean)`` + Strobe status: whether the flash is strobing at the moment or not. + This is a read-only control. + +``V4L2_CID_FLASH_TIMEOUT (integer)`` + Hardware timeout for flash. The flash strobe is stopped after this + period of time has passed from the start of the strobe. + +``V4L2_CID_FLASH_INTENSITY (integer)`` + Intensity of the flash strobe when the flash LED is in flash mode + (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA) + if possible. + +``V4L2_CID_FLASH_TORCH_INTENSITY (integer)`` + Intensity of the flash LED in torch mode + (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA) + if possible. Setting this control may not be possible in presence of + some faults. See V4L2_CID_FLASH_FAULT. + +``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)`` + Intensity of the indicator LED. The indicator LED may be fully + independent of the flash LED. The unit should be microamps (uA) if + possible. + +``V4L2_CID_FLASH_FAULT (bitmask)`` + Faults related to the flash. The faults tell about specific problems + in the flash chip itself or the LEDs attached to it. Faults may + prevent further use of some of the flash controls. In particular, + V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE + if the fault affects the flash LED. Exactly which faults have such + an effect is chip dependent. Reading the faults resets the control + and returns the chip to a usable state if possible. + +.. tabularcolumns:: |p{8.0cm}|p{9.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE`` + - Flash controller voltage to the flash LED has exceeded the limit + specific to the flash controller. + * - ``V4L2_FLASH_FAULT_TIMEOUT`` + - The flash strobe was still on when the timeout set by the user --- + V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash + controllers may set this in all such conditions. + * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE`` + - The flash controller has overheated. + * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT`` + - The short circuit protection of the flash controller has been + triggered. + * - ``V4L2_FLASH_FAULT_OVER_CURRENT`` + - Current in the LED power supply has exceeded the limit specific to + the flash controller. + * - ``V4L2_FLASH_FAULT_INDICATOR`` + - The flash controller has detected a short or open circuit + condition on the indicator LED. + * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE`` + - Flash controller voltage to the flash LED has been below the + minimum limit specific to the flash controller. + * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE`` + - The input voltage of the flash controller is below the limit under + which strobing the flash at full current will not be possible.The + condition persists until this flag is no longer set. + * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE`` + - The temperature of the LED has exceeded its allowed upper limit. + + + +``V4L2_CID_FLASH_CHARGE (boolean)`` + Enable or disable charging of the xenon flash capacitor. + +``V4L2_CID_FLASH_READY (boolean)`` + Is the flash ready to strobe? Xenon flashes require their capacitors + charged before strobing. LED flashes often require a cooldown period + after strobe during which another strobe will not be possible. This + is a read-only control. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-fm-rx.rst b/Documentation/media/uapi/v4l/ext-ctrls-fm-rx.rst new file mode 100644 index 000000000000..3ed6dd7f586d --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-fm-rx.rst @@ -0,0 +1,95 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _fm-rx-controls: + +***************************** +FM Receiver Control Reference +***************************** + +The FM Receiver (FM_RX) class includes controls for common features of +FM Reception capable devices. + + +.. _fm-rx-control-id: + +FM_RX Control IDs +================= + +``V4L2_CID_FM_RX_CLASS (class)`` + The FM_RX class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_RDS_RECEPTION (boolean)`` + Enables/disables RDS reception by the radio tuner + +``V4L2_CID_RDS_RX_PTY (integer)`` + Gets RDS Programme Type field. This encodes up to 31 pre-defined + programme types. + +``V4L2_CID_RDS_RX_PS_NAME (string)`` + Gets the Programme Service name (PS_NAME). It is intended for + static display on a receiver. It is the primary aid to listeners in + programme service identification and selection. In Annex E of + :ref:`iec62106`, the RDS specification, there is a full + description of the correct character encoding for Programme Service + name strings. Also from RDS specification, PS is usually a single + eight character text. However, it is also possible to find receivers + which can scroll strings sized as 8 x N characters. So, this control + must be configured with steps of 8 characters. The result is it must + always contain a string with size multiple of 8. + +``V4L2_CID_RDS_RX_RADIO_TEXT (string)`` + Gets the Radio Text info. It is a textual description of what is + being broadcasted. RDS Radio Text can be applied when broadcaster + wishes to transmit longer PS names, programme-related information or + any other text. In these cases, RadioText can be used in addition to + ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is + also fully described in Annex E of :ref:`iec62106`. The length of + Radio Text strings depends on which RDS Block is being used to + transmit it, either 32 (2A block) or 64 (2B block). However, it is + also possible to find receivers which can scroll strings sized as 32 + x N or 64 x N characters. So, this control must be configured with + steps of 32 or 64 characters. The result is it must always contain a + string with size multiple of 32 or 64. + +``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)`` + If set, then a traffic announcement is in progress. + +``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)`` + If set, then the tuned programme carries traffic announcements. + +``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)`` + If set, then this channel broadcasts music. If cleared, then it + broadcasts speech. If the transmitter doesn't make this distinction, + then it will be set. + +``V4L2_CID_TUNE_DEEMPHASIS`` + (enum) + +enum v4l2_deemphasis - + Configures the de-emphasis value for reception. A de-emphasis filter + is applied to the broadcast to accentuate the high audio + frequencies. Depending on the region, a time constant of either 50 + or 75 useconds is used. The enum v4l2_deemphasis defines possible + values for de-emphasis. Here they are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_DEEMPHASIS_DISABLED`` + - No de-emphasis is applied. + * - ``V4L2_DEEMPHASIS_50_uS`` + - A de-emphasis of 50 uS is used. + * - ``V4L2_DEEMPHASIS_75_uS`` + - A de-emphasis of 75 uS is used. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-fm-tx.rst b/Documentation/media/uapi/v4l/ext-ctrls-fm-tx.rst new file mode 100644 index 000000000000..db88346d99fd --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-fm-tx.rst @@ -0,0 +1,188 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _fm-tx-controls: + +******************************** +FM Transmitter Control Reference +******************************** + +The FM Transmitter (FM_TX) class includes controls for common features +of FM transmissions capable devices. Currently this class includes +parameters for audio compression, pilot tone generation, audio deviation +limiter, RDS transmission and tuning power features. + + +.. _fm-tx-control-id: + +FM_TX Control IDs +================= + +``V4L2_CID_FM_TX_CLASS (class)`` + The FM_TX class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_RDS_TX_DEVIATION (integer)`` + Configures RDS signal frequency deviation level in Hz. The range and + step are driver-specific. + +``V4L2_CID_RDS_TX_PI (integer)`` + Sets the RDS Programme Identification field for transmission. + +``V4L2_CID_RDS_TX_PTY (integer)`` + Sets the RDS Programme Type field for transmission. This encodes up + to 31 pre-defined programme types. + +``V4L2_CID_RDS_TX_PS_NAME (string)`` + Sets the Programme Service name (PS_NAME) for transmission. It is + intended for static display on a receiver. It is the primary aid to + listeners in programme service identification and selection. In + Annex E of :ref:`iec62106`, the RDS specification, there is a full + description of the correct character encoding for Programme Service + name strings. Also from RDS specification, PS is usually a single + eight character text. However, it is also possible to find receivers + which can scroll strings sized as 8 x N characters. So, this control + must be configured with steps of 8 characters. The result is it must + always contain a string with size multiple of 8. + +``V4L2_CID_RDS_TX_RADIO_TEXT (string)`` + Sets the Radio Text info for transmission. It is a textual + description of what is being broadcasted. RDS Radio Text can be + applied when broadcaster wishes to transmit longer PS names, + programme-related information or any other text. In these cases, + RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``. + The encoding for Radio Text strings is also fully described in Annex + E of :ref:`iec62106`. The length of Radio Text strings depends on + which RDS Block is being used to transmit it, either 32 (2A block) + or 64 (2B block). However, it is also possible to find receivers + which can scroll strings sized as 32 x N or 64 x N characters. So, + this control must be configured with steps of 32 or 64 characters. + The result is it must always contain a string with size multiple of + 32 or 64. + +``V4L2_CID_RDS_TX_MONO_STEREO (boolean)`` + Sets the Mono/Stereo bit of the Decoder Identification code. If set, + then the audio was recorded as stereo. + +``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)`` + Sets the + `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__ + bit of the Decoder Identification code. If set, then the audio was + recorded using an artificial head. + +``V4L2_CID_RDS_TX_COMPRESSED (boolean)`` + Sets the Compressed bit of the Decoder Identification code. If set, + then the audio is compressed. + +``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)`` + Sets the Dynamic PTY bit of the Decoder Identification code. If set, + then the PTY code is dynamically switched. + +``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)`` + If set, then a traffic announcement is in progress. + +``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)`` + If set, then the tuned programme carries traffic announcements. + +``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)`` + If set, then this channel broadcasts music. If cleared, then it + broadcasts speech. If the transmitter doesn't make this distinction, + then it should be set. + +``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)`` + If set, then transmit alternate frequencies. + +``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)`` + The alternate frequencies in kHz units. The RDS standard allows for + up to 25 frequencies to be defined. Drivers may support fewer + frequencies so check the array size. + +``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)`` + Enables or disables the audio deviation limiter feature. The limiter + is useful when trying to maximize the audio volume, minimize + receiver-generated distortion and prevent overmodulation. + +``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)`` + Sets the audio deviation limiter feature release time. Unit is in + useconds. Step and range are driver-specific. + +``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)`` + Configures audio frequency deviation level in Hz. The range and step + are driver-specific. + +``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)`` + Enables or disables the audio compression feature. This feature + amplifies signals below the threshold by a fixed gain and compresses + audio signals above the threshold by the ratio of Threshold/(Gain + + Threshold). + +``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)`` + Sets the gain for audio compression feature. It is a dB value. The + range and step are driver-specific. + +``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)`` + Sets the threshold level for audio compression freature. It is a dB + value. The range and step are driver-specific. + +``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)`` + Sets the attack time for audio compression feature. It is a useconds + value. The range and step are driver-specific. + +``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)`` + Sets the release time for audio compression feature. It is a + useconds value. The range and step are driver-specific. + +``V4L2_CID_PILOT_TONE_ENABLED (boolean)`` + Enables or disables the pilot tone generation feature. + +``V4L2_CID_PILOT_TONE_DEVIATION (integer)`` + Configures pilot tone frequency deviation level. Unit is in Hz. The + range and step are driver-specific. + +``V4L2_CID_PILOT_TONE_FREQUENCY (integer)`` + Configures pilot tone frequency value. Unit is in Hz. The range and + step are driver-specific. + +``V4L2_CID_TUNE_PREEMPHASIS`` + (enum) + +enum v4l2_preemphasis - + Configures the pre-emphasis value for broadcasting. A pre-emphasis + filter is applied to the broadcast to accentuate the high audio + frequencies. Depending on the region, a time constant of either 50 + or 75 useconds is used. The enum v4l2_preemphasis defines possible + values for pre-emphasis. Here they are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_PREEMPHASIS_DISABLED`` + - No pre-emphasis is applied. + * - ``V4L2_PREEMPHASIS_50_uS`` + - A pre-emphasis of 50 uS is used. + * - ``V4L2_PREEMPHASIS_75_uS`` + - A pre-emphasis of 75 uS is used. + + + +``V4L2_CID_TUNE_POWER_LEVEL (integer)`` + Sets the output power level for signal transmission. Unit is in + dBuV. Range and step are driver-specific. + +``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)`` + This selects the value of antenna tuning capacitor manually or + automatically if set to zero. Unit, range and step are + driver-specific. + +For more details about RDS specification, refer to :ref:`iec62106` +document, from CENELEC. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-image-process.rst b/Documentation/media/uapi/v4l/ext-ctrls-image-process.rst new file mode 100644 index 000000000000..22fc2d3e433d --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-image-process.rst @@ -0,0 +1,63 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _image-process-controls: + +******************************* +Image Process Control Reference +******************************* + +The Image Process control class is intended for low-level control of +image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the +controls in this class affect processing the image, and do not control +capturing of it. + + +.. _image-process-control-id: + +Image Process Control IDs +========================= + +``V4L2_CID_IMAGE_PROC_CLASS (class)`` + The IMAGE_PROC class descriptor. + +``V4L2_CID_LINK_FREQ (integer menu)`` + Data bus frequency. Together with the media bus pixel code, bus type + (clock cycles per sample), the data bus frequency defines the pixel + rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly + elsewhere, if the device is not an image sensor). The frame rate can + be calculated from the pixel clock, image width and height and + horizontal and vertical blanking. While the pixel rate control may + be defined elsewhere than in the subdev containing the pixel array, + the frame rate cannot be obtained from that information. This is + because only on the pixel array it can be assumed that the vertical + and horizontal blanking information is exact: no other blanking is + allowed in the pixel array. The selection of frame rate is performed + by selecting the desired horizontal and vertical blanking. The unit + of this control is Hz. + +``V4L2_CID_PIXEL_RATE (64-bit integer)`` + Pixel rate in the source pads of the subdev. This control is + read-only and its unit is pixels / second. + +``V4L2_CID_TEST_PATTERN (menu)`` + Some capture/display/sensor devices have the capability to generate + test pattern images. These hardware specific test patterns can be + used to test if a device is working properly. + +``V4L2_CID_DEINTERLACING_MODE (menu)`` + The video deinterlacing mode (such as Bob, Weave, ...). The menu items are + driver specific and are documented in :ref:`v4l-drivers`. + +``V4L2_CID_DIGITAL_GAIN (integer)`` + Digital gain is the value by which all colour components + are multiplied by. Typically the digital gain applied is the + control value divided by e.g. 0x100, meaning that to get no + digital gain the control value needs to be 0x100. The no-gain + configuration is also typically the default. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-image-source.rst b/Documentation/media/uapi/v4l/ext-ctrls-image-source.rst new file mode 100644 index 000000000000..2c3ab5796d76 --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-image-source.rst @@ -0,0 +1,57 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _image-source-controls: + +****************************** +Image Source Control Reference +****************************** + +The Image Source control class is intended for low-level control of +image source devices such as image sensors. The devices feature an +analogue to digital converter and a bus transmitter to transmit the +image data out of the device. + + +.. _image-source-control-id: + +Image Source Control IDs +======================== + +``V4L2_CID_IMAGE_SOURCE_CLASS (class)`` + The IMAGE_SOURCE class descriptor. + +``V4L2_CID_VBLANK (integer)`` + Vertical blanking. The idle period after every frame during which no + image data is produced. The unit of vertical blanking is a line. + Every line has length of the image width plus horizontal blanking at + the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the + same sub-device. + +``V4L2_CID_HBLANK (integer)`` + Horizontal blanking. The idle period after every line of image data + during which no image data is produced. The unit of horizontal + blanking is pixels. + +``V4L2_CID_ANALOGUE_GAIN (integer)`` + Analogue gain is gain affecting all colour components in the pixel + matrix. The gain operation is performed in the analogue domain + before A/D conversion. + +``V4L2_CID_TEST_PATTERN_RED (integer)`` + Test pattern red colour component. + +``V4L2_CID_TEST_PATTERN_GREENR (integer)`` + Test pattern green (next to red) colour component. + +``V4L2_CID_TEST_PATTERN_BLUE (integer)`` + Test pattern blue colour component. + +``V4L2_CID_TEST_PATTERN_GREENB (integer)`` + Test pattern green (next to blue) colour component. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst b/Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst new file mode 100644 index 000000000000..cf9cd8a9f9b4 --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst @@ -0,0 +1,113 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _jpeg-controls: + +********************** +JPEG Control Reference +********************** + +The JPEG class includes controls for common features of JPEG encoders +and decoders. Currently it includes features for codecs implementing +progressive baseline DCT compression process with Huffman entrophy +coding. + + +.. _jpeg-control-id: + +JPEG Control IDs +================ + +``V4L2_CID_JPEG_CLASS (class)`` + The JPEG class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)`` + The chroma subsampling factors describe how each component of an + input image is sampled, in respect to maximum sample rate in each + spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more + details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines + how Cb and Cr components are downsampled after converting an input + image from RGB to Y'CbCr color space. + +.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444`` + - No chroma subsampling, each pixel has Y, Cr and Cb values. + * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422`` + - Horizontally subsample Cr, Cb components by a factor of 2. + * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420`` + - Subsample Cr, Cb components horizontally and vertically by 2. + * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411`` + - Horizontally subsample Cr, Cb components by a factor of 4. + * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410`` + - Subsample Cr, Cb components horizontally by 4 and vertically by 2. + * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY`` + - Use only luminance component. + + + +``V4L2_CID_JPEG_RESTART_INTERVAL (integer)`` + The restart interval determines an interval of inserting RSTm + markers (m = 0..7). The purpose of these markers is to additionally + reinitialize the encoder process, in order to process blocks of an + image independently. For the lossy compression processes the restart + interval unit is MCU (Minimum Coded Unit) and its value is contained + in DRI (Define Restart Interval) marker. If + ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm + markers will not be inserted. + +.. _jpeg-quality-control: + +``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)`` + ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off + between image quality and size. It provides simpler method for + applications to control image quality, without a need for direct + reconfiguration of luminance and chrominance quantization tables. In + cases where a driver uses quantization tables configured directly by + an application, using interfaces defined elsewhere, + ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by + driver to 0. + + The value range of this control is driver-specific. Only positive, + non-zero values are meaningful. The recommended range is 1 - 100, + where larger values correspond to better image quality. + +.. _jpeg-active-marker-control: + +``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)`` + Specify which JPEG markers are included in compressed stream. This + control is valid only for encoders. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_JPEG_ACTIVE_MARKER_APP0`` + - Application data segment APP\ :sub:`0`. + * - ``V4L2_JPEG_ACTIVE_MARKER_APP1`` + - Application data segment APP\ :sub:`1`. + * - ``V4L2_JPEG_ACTIVE_MARKER_COM`` + - Comment segment. + * - ``V4L2_JPEG_ACTIVE_MARKER_DQT`` + - Quantization tables segment. + * - ``V4L2_JPEG_ACTIVE_MARKER_DHT`` + - Huffman tables segment. + + + +For more details about JPEG specification, refer to :ref:`itu-t81`, +:ref:`jfif`, :ref:`w3c-jpeg-jfif`. diff --git a/Documentation/media/uapi/v4l/ext-ctrls-rf-tuner.rst b/Documentation/media/uapi/v4l/ext-ctrls-rf-tuner.rst new file mode 100644 index 000000000000..0fb85ba878dd --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-rf-tuner.rst @@ -0,0 +1,96 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _rf-tuner-controls: + +************************** +RF Tuner Control Reference +************************** + +The RF Tuner (RF_TUNER) class includes controls for common features of +devices having RF tuner. + +In this context, RF tuner is radio receiver circuit between antenna and +demodulator. It receives radio frequency (RF) from the antenna and +converts that received signal to lower intermediate frequency (IF) or +baseband frequency (BB). Tuners that could do baseband output are often +called Zero-IF tuners. Older tuners were typically simple PLL tuners +inside a metal box, while newer ones are highly integrated chips +without a metal box "silicon tuners". These controls are mostly +applicable for new feature rich silicon tuners, just because older +tuners does not have much adjustable features. + +For more information about RF tuners see +`Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__ +and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__ +from Wikipedia. + + +.. _rf-tuner-control-id: + +RF_TUNER Control IDs +==================== + +``V4L2_CID_RF_TUNER_CLASS (class)`` + The RF_TUNER class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)`` + Enables/disables tuner radio channel bandwidth configuration. In + automatic mode bandwidth configuration is performed by the driver. + +``V4L2_CID_RF_TUNER_BANDWIDTH (integer)`` + Filter(s) on tuner signal path are used to filter signal according + to receiving party needs. Driver configures filters to fulfill + desired bandwidth requirement. Used when + V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The + range and step are driver-specific. + +``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)`` + Enables/disables LNA automatic gain control (AGC) + +``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)`` + Enables/disables mixer automatic gain control (AGC) + +``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)`` + Enables/disables IF automatic gain control (AGC) + +``V4L2_CID_RF_TUNER_RF_GAIN (integer)`` + The RF amplifier is the very first amplifier on the receiver signal + path, just right after the antenna input. The difference between the + LNA gain and the RF gain in this document is that the LNA gain is + integrated in the tuner chip while the RF gain is a separate chip. + There may be both RF and LNA gain controls in the same device. The + range and step are driver-specific. + +``V4L2_CID_RF_TUNER_LNA_GAIN (integer)`` + LNA (low noise amplifier) gain is first gain stage on the RF tuner + signal path. It is located very close to tuner antenna input. Used + when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See + ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain + differs from the each others. The range and step are + driver-specific. + +``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)`` + Mixer gain is second gain stage on the RF tuner signal path. It is + located inside mixer block, where RF signal is down-converted by the + mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set. + The range and step are driver-specific. + +``V4L2_CID_RF_TUNER_IF_GAIN (integer)`` + IF gain is last gain stage on the RF tuner signal path. It is + located on output of RF tuner. It controls signal level of + intermediate frequency output or baseband output. Used when + ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step + are driver-specific. + +``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)`` + Is synthesizer PLL locked? RF tuner is receiving given frequency + when that control is set. This is a read-only control. diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 286a2dd7ec36..24274b398e63 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -9,9 +9,9 @@ .. _extended-controls: -***************** -Extended Controls -***************** +********************* +Extended Controls API +********************* Introduction @@ -181,3902 +181,3 @@ The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also contains hints on the behavior of the control. See the :ref:`VIDIOC_QUERYCTRL` documentation for more details. - - -.. _mpeg-controls: - -Codec Control Reference -======================= - -Below all controls within the Codec control class are described. First -the generic controls, then controls specific for certain hardware. - -.. note:: - - These controls are applicable to all codecs and not just MPEG. The - defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls - were originally made for MPEG codecs and later extended to cover all - encoding formats. - - -Generic Codec Controls ----------------------- - - -.. _mpeg-control-id: - -Codec Control IDs -^^^^^^^^^^^^^^^^^ - -``V4L2_CID_MPEG_CLASS (class)`` - The Codec class descriptor. Calling - :ref:`VIDIOC_QUERYCTRL` for this control will - return a description of this control class. This description can be - used as the caption of a Tab page in a GUI, for example. - -.. _v4l2-mpeg-stream-type: - -``V4L2_CID_MPEG_STREAM_TYPE`` - (enum) - -enum v4l2_mpeg_stream_type - - The MPEG-1, -2 or -4 output stream type. One cannot assume anything - here. Each hardware MPEG encoder tends to support different subsets - of the available MPEG stream types. This control is specific to - multiplexed MPEG streams. The currently defined stream types are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS`` - - MPEG-2 program stream - * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS`` - - MPEG-2 transport stream - * - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS`` - - MPEG-1 system stream - * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD`` - - MPEG-2 DVD-compatible stream - * - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD`` - - MPEG-1 VCD-compatible stream - * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD`` - - MPEG-2 SVCD-compatible stream - - - -``V4L2_CID_MPEG_STREAM_PID_PMT (integer)`` - Program Map Table Packet ID for the MPEG transport stream (default - 16) - -``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)`` - Audio Packet ID for the MPEG transport stream (default 256) - -``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)`` - Video Packet ID for the MPEG transport stream (default 260) - -``V4L2_CID_MPEG_STREAM_PID_PCR (integer)`` - Packet ID for the MPEG transport stream carrying PCR fields (default - 259) - -``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)`` - Audio ID for MPEG PES - -``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)`` - Video ID for MPEG PES - -.. _v4l2-mpeg-stream-vbi-fmt: - -``V4L2_CID_MPEG_STREAM_VBI_FMT`` - (enum) - -enum v4l2_mpeg_stream_vbi_fmt - - Some cards can embed VBI data (e. g. Closed Caption, Teletext) into - the MPEG stream. This control selects whether VBI data should be - embedded, and if so, what embedding method should be used. The list - of possible VBI formats depends on the driver. The currently defined - VBI format types are: - - - -.. tabularcolumns:: |p{6 cm}|p{11.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_STREAM_VBI_FMT_NONE`` - - No VBI in the MPEG stream - * - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV`` - - VBI in private packets, IVTV format (documented in the kernel - sources in the file - ``Documentation/media/v4l-drivers/cx2341x.rst``) - - - -.. _v4l2-mpeg-audio-sampling-freq: - -``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ`` - (enum) - -enum v4l2_mpeg_audio_sampling_freq - - MPEG Audio sampling frequency. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100`` - - 44.1 kHz - * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000`` - - 48 kHz - * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000`` - - 32 kHz - - - -.. _v4l2-mpeg-audio-encoding: - -``V4L2_CID_MPEG_AUDIO_ENCODING`` - (enum) - -enum v4l2_mpeg_audio_encoding - - MPEG Audio encoding. This control is specific to multiplexed MPEG - streams. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1`` - - MPEG-1/2 Layer I encoding - * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2`` - - MPEG-1/2 Layer II encoding - * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3`` - - MPEG-1/2 Layer III encoding - * - ``V4L2_MPEG_AUDIO_ENCODING_AAC`` - - MPEG-2/4 AAC (Advanced Audio Coding) - * - ``V4L2_MPEG_AUDIO_ENCODING_AC3`` - - AC-3 aka ATSC A/52 encoding - - - -.. _v4l2-mpeg-audio-l1-bitrate: - -``V4L2_CID_MPEG_AUDIO_L1_BITRATE`` - (enum) - -enum v4l2_mpeg_audio_l1_bitrate - - MPEG-1/2 Layer I bitrate. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K`` - - 32 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K`` - - 64 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K`` - - 96 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K`` - - 128 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K`` - - 160 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K`` - - 192 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K`` - - 224 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K`` - - 256 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K`` - - 288 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K`` - - 320 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K`` - - 352 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K`` - - 384 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K`` - - 416 kbit/s - * - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K`` - - 448 kbit/s - - - -.. _v4l2-mpeg-audio-l2-bitrate: - -``V4L2_CID_MPEG_AUDIO_L2_BITRATE`` - (enum) - -enum v4l2_mpeg_audio_l2_bitrate - - MPEG-1/2 Layer II bitrate. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K`` - - 32 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K`` - - 48 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K`` - - 56 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K`` - - 64 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K`` - - 80 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K`` - - 96 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K`` - - 112 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K`` - - 128 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K`` - - 160 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K`` - - 192 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K`` - - 224 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K`` - - 256 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K`` - - 320 kbit/s - * - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K`` - - 384 kbit/s - - - -.. _v4l2-mpeg-audio-l3-bitrate: - -``V4L2_CID_MPEG_AUDIO_L3_BITRATE`` - (enum) - -enum v4l2_mpeg_audio_l3_bitrate - - MPEG-1/2 Layer III bitrate. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K`` - - 32 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K`` - - 40 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K`` - - 48 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K`` - - 56 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K`` - - 64 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K`` - - 80 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K`` - - 96 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K`` - - 112 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K`` - - 128 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K`` - - 160 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K`` - - 192 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K`` - - 224 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K`` - - 256 kbit/s - * - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K`` - - 320 kbit/s - - - -``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)`` - AAC bitrate in bits per second. - -.. _v4l2-mpeg-audio-ac3-bitrate: - -``V4L2_CID_MPEG_AUDIO_AC3_BITRATE`` - (enum) - -enum v4l2_mpeg_audio_ac3_bitrate - - AC-3 bitrate. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K`` - - 32 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K`` - - 40 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K`` - - 48 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K`` - - 56 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K`` - - 64 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K`` - - 80 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K`` - - 96 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K`` - - 112 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K`` - - 128 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K`` - - 160 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K`` - - 192 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K`` - - 224 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K`` - - 256 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K`` - - 320 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K`` - - 384 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K`` - - 448 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K`` - - 512 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K`` - - 576 kbit/s - * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K`` - - 640 kbit/s - - - -.. _v4l2-mpeg-audio-mode: - -``V4L2_CID_MPEG_AUDIO_MODE`` - (enum) - -enum v4l2_mpeg_audio_mode - - MPEG Audio mode. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_MODE_STEREO`` - - Stereo - * - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO`` - - Joint Stereo - * - ``V4L2_MPEG_AUDIO_MODE_DUAL`` - - Bilingual - * - ``V4L2_MPEG_AUDIO_MODE_MONO`` - - Mono - - - -.. _v4l2-mpeg-audio-mode-extension: - -``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION`` - (enum) - -enum v4l2_mpeg_audio_mode_extension - - Joint Stereo audio mode extension. In Layer I and II they indicate - which subbands are in intensity stereo. All other subbands are coded - in stereo. Layer III is not (yet) supported. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4`` - - Subbands 4-31 in intensity stereo - * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8`` - - Subbands 8-31 in intensity stereo - * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12`` - - Subbands 12-31 in intensity stereo - * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16`` - - Subbands 16-31 in intensity stereo - - - -.. _v4l2-mpeg-audio-emphasis: - -``V4L2_CID_MPEG_AUDIO_EMPHASIS`` - (enum) - -enum v4l2_mpeg_audio_emphasis - - Audio Emphasis. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE`` - - None - * - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS`` - - 50/15 microsecond emphasis - * - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17`` - - CCITT J.17 - - - -.. _v4l2-mpeg-audio-crc: - -``V4L2_CID_MPEG_AUDIO_CRC`` - (enum) - -enum v4l2_mpeg_audio_crc - - CRC method. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_CRC_NONE`` - - None - * - ``V4L2_MPEG_AUDIO_CRC_CRC16`` - - 16 bit parity check - - - -``V4L2_CID_MPEG_AUDIO_MUTE (boolean)`` - Mutes the audio when capturing. This is not done by muting audio - hardware, which can still produce a slight hiss, but in the encoder - itself, guaranteeing a fixed and reproducible audio bitstream. 0 = - unmuted, 1 = muted. - -.. _v4l2-mpeg-audio-dec-playback: - -``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` - (enum) - -enum v4l2_mpeg_audio_dec_playback - - Determines how monolingual audio should be played back. Possible - values are: - - - -.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO`` - - Automatically determines the best playback mode. - * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO`` - - Stereo playback. - * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT`` - - Left channel playback. - * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT`` - - Right channel playback. - * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO`` - - Mono playback. - * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO`` - - Stereo playback with swapped left and right channels. - - - -.. _v4l2-mpeg-audio-dec-multilingual-playback: - -``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` - (enum) - -enum v4l2_mpeg_audio_dec_playback - - Determines how multilingual audio should be played back. - -.. _v4l2-mpeg-video-encoding: - -``V4L2_CID_MPEG_VIDEO_ENCODING`` - (enum) - -enum v4l2_mpeg_video_encoding - - MPEG Video encoding method. This control is specific to multiplexed - MPEG streams. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1`` - - MPEG-1 Video encoding - * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2`` - - MPEG-2 Video encoding - * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` - - MPEG-4 AVC (H.264) Video encoding - - - -.. _v4l2-mpeg-video-aspect: - -``V4L2_CID_MPEG_VIDEO_ASPECT`` - (enum) - -enum v4l2_mpeg_video_aspect - - Video aspect. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_ASPECT_1x1`` - * - ``V4L2_MPEG_VIDEO_ASPECT_4x3`` - * - ``V4L2_MPEG_VIDEO_ASPECT_16x9`` - * - ``V4L2_MPEG_VIDEO_ASPECT_221x100`` - - - -``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)`` - Number of B-Frames (default 2) - -``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)`` - GOP size (default 12) - -``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)`` - GOP closure (default 1) - -``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)`` - Enable 3:2 pulldown (default 0) - -.. _v4l2-mpeg-video-bitrate-mode: - -``V4L2_CID_MPEG_VIDEO_BITRATE_MODE`` - (enum) - -enum v4l2_mpeg_video_bitrate_mode - - Video bitrate mode. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR`` - - Variable bitrate - * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR`` - - Constant bitrate - - - -``V4L2_CID_MPEG_VIDEO_BITRATE (integer)`` - Video bitrate in bits per second. - -``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)`` - Peak video bitrate in bits per second. Must be larger or equal to - the average video bitrate. It is ignored if the video bitrate mode - is set to constant bitrate. - -``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)`` - For every captured frame, skip this many subsequent frames (default - 0). - -``V4L2_CID_MPEG_VIDEO_MUTE (boolean)`` - "Mutes" the video to a fixed color when capturing. This is useful - for testing, to produce a fixed video bitstream. 0 = unmuted, 1 = - muted. - -``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)`` - Sets the "mute" color of the video. The supplied 32-bit integer is - interpreted as follows (bit 0 = least significant bit): - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - Bit 0:7 - - V chrominance information - * - Bit 8:15 - - U chrominance information - * - Bit 16:23 - - Y luminance information - * - Bit 24:31 - - Must be zero. - - - -.. _v4l2-mpeg-video-dec-pts: - -``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)`` - This read-only control returns the 33-bit video Presentation Time - Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the - currently displayed frame. This is the same PTS as is used in - :ref:`VIDIOC_DECODER_CMD`. - -.. _v4l2-mpeg-video-dec-frame: - -``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)`` - This read-only control returns the frame counter of the frame that - is currently displayed (decoded). This value is reset to 0 whenever - the decoder is started. - -``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)`` - If enabled the decoder expects to receive a single slice per buffer, - otherwise the decoder expects a single frame in per buffer. - Applicable to the decoder, all codecs. - -``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)`` - Enable writing sample aspect ratio in the Video Usability - Information. Applicable to the H264 encoder. - -.. _v4l2-mpeg-video-h264-vui-sar-idc: - -``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC`` - (enum) - -enum v4l2_mpeg_video_h264_vui_sar_idc - - VUI sample aspect ratio indicator for H.264 encoding. The value is - defined in the table E-1 in the standard. Applicable to the H264 - encoder. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED`` - - Unspecified - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1`` - - 1x1 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11`` - - 12x11 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11`` - - 10x11 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11`` - - 16x11 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33`` - - 40x33 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11`` - - 24x11 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11`` - - 20x11 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11`` - - 32x11 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33`` - - 80x33 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11`` - - 18x11 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11`` - - 15x11 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33`` - - 64x33 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99`` - - 160x99 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3`` - - 4x3 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2`` - - 3x2 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1`` - - 2x1 - * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED`` - - Extended SAR - - - -``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)`` - Extended sample aspect ratio width for H.264 VUI encoding. - Applicable to the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)`` - Extended sample aspect ratio height for H.264 VUI encoding. - Applicable to the H264 encoder. - -.. _v4l2-mpeg-video-h264-level: - -``V4L2_CID_MPEG_VIDEO_H264_LEVEL`` - (enum) - -enum v4l2_mpeg_video_h264_level - - The level information for the H264 video elementary stream. - Applicable to the H264 encoder. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0`` - - Level 1.0 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B`` - - Level 1B - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1`` - - Level 1.1 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2`` - - Level 1.2 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3`` - - Level 1.3 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0`` - - Level 2.0 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1`` - - Level 2.1 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2`` - - Level 2.2 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0`` - - Level 3.0 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1`` - - Level 3.1 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2`` - - Level 3.2 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0`` - - Level 4.0 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1`` - - Level 4.1 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2`` - - Level 4.2 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0`` - - Level 5.0 - * - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1`` - - Level 5.1 - - - -.. _v4l2-mpeg-video-mpeg4-level: - -``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL`` - (enum) - -enum v4l2_mpeg_video_mpeg4_level - - The level information for the MPEG4 elementary stream. Applicable to - the MPEG4 encoder. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_0`` - - Level 0 - * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_0B`` - - Level 0b - * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_1`` - - Level 1 - * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_2`` - - Level 2 - * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_3`` - - Level 3 - * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_3B`` - - Level 3b - * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_4`` - - Level 4 - * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_5`` - - Level 5 - - - -.. _v4l2-mpeg-video-h264-profile: - -``V4L2_CID_MPEG_VIDEO_H264_PROFILE`` - (enum) - -enum v4l2_mpeg_video_h264_profile - - The profile information for H264. Applicable to the H264 encoder. - Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE`` - - Baseline profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE`` - - Constrained Baseline profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN`` - - Main profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED`` - - Extended profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH`` - - High profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10`` - - High 10 profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422`` - - High 422 profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE`` - - High 444 Predictive profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA`` - - High 10 Intra profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA`` - - High 422 Intra profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA`` - - High 444 Intra profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA`` - - CAVLC 444 Intra profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE`` - - Scalable Baseline profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH`` - - Scalable High profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA`` - - Scalable High Intra profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH`` - - Stereo High profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH`` - - Multiview High profile - - - -.. _v4l2-mpeg-video-mpeg4-profile: - -``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE`` - (enum) - -enum v4l2_mpeg_video_mpeg4_profile - - The profile information for MPEG4. Applicable to the MPEG4 encoder. - Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE`` - - Simple profile - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_SIMPLE`` - - Advanced Simple profile - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_CORE`` - - Core profile - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE_SCALABLE`` - - Simple Scalable profile - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY`` - - - - - -``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)`` - The maximum number of reference pictures used for encoding. - Applicable to the encoder. - -.. _v4l2-mpeg-video-multi-slice-mode: - -``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` - (enum) - -enum v4l2_mpeg_video_multi_slice_mode - - Determines how the encoder should handle division of frame into - slices. Applicable to the encoder. Possible values are: - - - -.. tabularcolumns:: |p{8.7cm}|p{8.8cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE`` - - Single slice per frame. - * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB`` - - Multiple slices with set maximum number of macroblocks per slice. - * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES`` - - Multiple slice with set maximum size in bytes per slice. - - - -``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)`` - The maximum number of macroblocks in a slice. Used when - ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the - encoder. - -``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)`` - The maximum size of a slice in bytes. Used when - ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the - encoder. - -.. _v4l2-mpeg-video-h264-loop-filter-mode: - -``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE`` - (enum) - -enum v4l2_mpeg_video_h264_loop_filter_mode - - Loop filter mode for H264 encoder. Possible values are: - - - -.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED`` - - Loop filter is enabled. - * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED`` - - Loop filter is disabled. - * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY`` - - Loop filter is disabled at the slice boundary. - - - -``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)`` - Loop filter alpha coefficient, defined in the H264 standard. - This value corresponds to the slice_alpha_c0_offset_div2 slice header - field, and should be in the range of -6 to +6, inclusive. The actual alpha - offset FilterOffsetA is twice this value. - Applicable to the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)`` - Loop filter beta coefficient, defined in the H264 standard. - This corresponds to the slice_beta_offset_div2 slice header field, and - should be in the range of -6 to +6, inclusive. The actual beta offset - FilterOffsetB is twice this value. - Applicable to the H264 encoder. - -.. _v4l2-mpeg-video-h264-entropy-mode: - -``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE`` - (enum) - -enum v4l2_mpeg_video_h264_entropy_mode - - Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264 - encoder. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC`` - - Use CAVLC entropy coding. - * - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC`` - - Use CABAC entropy coding. - - - -``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)`` - Enable 8X8 transform for H264. Applicable to the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)`` - Cyclic intra macroblock refresh. This is the number of continuous - macroblocks refreshed every frame. Each frame a successive set of - macroblocks is refreshed until the cycle completes and starts from - the top of the frame. Applicable to H264, H263 and MPEG4 encoder. - -``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)`` - Frame level rate control enable. If this control is disabled then - the quantization parameter for each frame type is constant and set - with appropriate controls (e.g. - ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is - enabled then quantization parameter is adjusted to meet the chosen - bitrate. Minimum and maximum value for the quantization parameter - can be set with appropriate controls (e.g. - ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders. - -``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)`` - Macroblock level rate control enable. Applicable to the MPEG4 and - H264 encoders. - -``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)`` - Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4 - encoder. - -``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)`` - Quantization parameter for an I frame for H263. Valid range: from 1 - to 31. - -``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)`` - Minimum quantization parameter for H263. Valid range: from 1 to 31. - -``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)`` - Maximum quantization parameter for H263. Valid range: from 1 to 31. - -``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)`` - Quantization parameter for an P frame for H263. Valid range: from 1 - to 31. - -``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)`` - Quantization parameter for an B frame for H263. Valid range: from 1 - to 31. - -``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)`` - Quantization parameter for an I frame for H264. Valid range: from 0 - to 51. - -``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)`` - Minimum quantization parameter for H264. Valid range: from 0 to 51. - -``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)`` - Maximum quantization parameter for H264. Valid range: from 0 to 51. - -``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)`` - Quantization parameter for an P frame for H264. Valid range: from 0 - to 51. - -``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)`` - Quantization parameter for an B frame for H264. Valid range: from 0 - to 51. - -``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)`` - Quantization parameter for an I frame for MPEG4. Valid range: from 1 - to 31. - -``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)`` - Minimum quantization parameter for MPEG4. Valid range: from 1 to 31. - -``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)`` - Maximum quantization parameter for MPEG4. Valid range: from 1 to 31. - -``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)`` - Quantization parameter for an P frame for MPEG4. Valid range: from 1 - to 31. - -``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)`` - Quantization parameter for an B frame for MPEG4. Valid range: from 1 - to 31. - -``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)`` - The Video Buffer Verifier size in kilobytes, it is used as a - limitation of frame skip. The VBV is defined in the standard as a - mean to verify that the produced stream will be successfully - decoded. The standard describes it as "Part of a hypothetical - decoder that is conceptually connected to the output of the encoder. - Its purpose is to provide a constraint on the variability of the - data rate that an encoder or editing process may produce.". - Applicable to the MPEG1, MPEG2, MPEG4 encoders. - -.. _v4l2-mpeg-video-vbv-delay: - -``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)`` - Sets the initial delay in milliseconds for VBV buffer control. - -.. _v4l2-mpeg-video-hor-search-range: - -``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)`` - Horizontal search range defines maximum horizontal search area in - pixels to search and match for the present Macroblock (MB) in the - reference picture. This V4L2 control macro is used to set horizontal - search range for motion estimation module in video encoder. - -.. _v4l2-mpeg-video-vert-search-range: - -``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)`` - Vertical search range defines maximum vertical search area in pixels - to search and match for the present Macroblock (MB) in the reference - picture. This V4L2 control macro is used to set vertical search - range for motion estimation module in video encoder. - -.. _v4l2-mpeg-video-force-key-frame: - -``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)`` - Force a key frame for the next queued buffer. Applicable to - encoders. This is a general, codec-agnostic keyframe control. - -``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)`` - The Coded Picture Buffer size in kilobytes, it is used as a - limitation of frame skip. The CPB is defined in the H264 standard as - a mean to verify that the produced stream will be successfully - decoded. Applicable to the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)`` - Period between I-frames in the open GOP for H264. In case of an open - GOP this is the period between two I-frames. The period between IDR - (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE - control. An IDR frame, which stands for Instantaneous Decoding - Refresh is an I-frame after which no prior frames are referenced. - This means that a stream can be restarted from an IDR frame without - the need to store or decode any previous frames. Applicable to the - H264 encoder. - -.. _v4l2-mpeg-video-header-mode: - -``V4L2_CID_MPEG_VIDEO_HEADER_MODE`` - (enum) - -enum v4l2_mpeg_video_header_mode - - Determines whether the header is returned as the first buffer or is - it returned together with the first frame. Applicable to encoders. - Possible values are: - - - -.. tabularcolumns:: |p{10.3cm}|p{7.2cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE`` - - The stream header is returned separately in the first buffer. - * - ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME`` - - The stream header is returned together with the first encoded - frame. - - - -``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)`` - Repeat the video sequence headers. Repeating these headers makes - random access to the video stream easier. Applicable to the MPEG1, 2 - and 4 encoder. - -``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)`` - Enabled the deblocking post processing filter for MPEG4 decoder. - Applicable to the MPEG4 decoder. - -``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)`` - vop_time_increment_resolution value for MPEG4. Applicable to the - MPEG4 encoder. - -``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)`` - vop_time_increment value for MPEG4. Applicable to the MPEG4 - encoder. - -``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)`` - Enable generation of frame packing supplemental enhancement - information in the encoded bitstream. The frame packing SEI message - contains the arrangement of L and R planes for 3D viewing. - Applicable to the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)`` - Sets current frame as frame0 in frame packing SEI. Applicable to the - H264 encoder. - -.. _v4l2-mpeg-video-h264-sei-fp-arrangement-type: - -``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE`` - (enum) - -enum v4l2_mpeg_video_h264_sei_fp_arrangement_type - - Frame packing arrangement type for H264 SEI. Applicable to the H264 - encoder. Possible values are: - -.. tabularcolumns:: |p{12cm}|p{5.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD`` - - Pixels are alternatively from L and R. - * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN`` - - L and R are interlaced by column. - * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW`` - - L and R are interlaced by row. - * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE`` - - L is on the left, R on the right. - * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM`` - - L is on top, R on bottom. - * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL`` - - One view per frame. - - - -``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)`` - Enables flexible macroblock ordering in the encoded bitstream. It is - a technique used for restructuring the ordering of macroblocks in - pictures. Applicable to the H264 encoder. - -.. _v4l2-mpeg-video-h264-fmo-map-type: - -``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE`` - (enum) - -enum v4l2_mpeg_video_h264_fmo_map_type - - When using FMO, the map type divides the image in different scan - patterns of macroblocks. Applicable to the H264 encoder. Possible - values are: - -.. tabularcolumns:: |p{12.5cm}|p{5.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES`` - - Slices are interleaved one after other with macroblocks in run - length order. - * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES`` - - Scatters the macroblocks based on a mathematical function known to - both encoder and decoder. - * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER`` - - Macroblocks arranged in rectangular areas or regions of interest. - * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT`` - - Slice groups grow in a cyclic way from centre to outwards. - * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN`` - - Slice groups grow in raster scan pattern from left to right. - * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN`` - - Slice groups grow in wipe scan pattern from top to bottom. - * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT`` - - User defined map type. - - - -``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)`` - Number of slice groups in FMO. Applicable to the H264 encoder. - -.. _v4l2-mpeg-video-h264-fmo-change-direction: - -``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION`` - (enum) - -enum v4l2_mpeg_video_h264_fmo_change_dir - - Specifies a direction of the slice group change for raster and wipe - maps. Applicable to the H264 encoder. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT`` - - Raster scan or wipe right. - * - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT`` - - Reverse raster scan or wipe left. - - - -``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)`` - Specifies the size of the first slice group for raster and wipe map. - Applicable to the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)`` - Specifies the number of consecutive macroblocks for the interleaved - map. Applicable to the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)`` - Enables arbitrary slice ordering in encoded bitstream. Applicable to - the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)`` - Specifies the slice order in ASO. Applicable to the H264 encoder. - The supplied 32-bit integer is interpreted as follows (bit 0 = least - significant bit): - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - Bit 0:15 - - Slice ID - * - Bit 16:32 - - Slice position or order - - - -``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)`` - Enables H264 hierarchical coding. Applicable to the H264 encoder. - -.. _v4l2-mpeg-video-h264-hierarchical-coding-type: - -``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE`` - (enum) - -enum v4l2_mpeg_video_h264_hierarchical_coding_type - - Specifies the hierarchical coding type. Applicable to the H264 - encoder. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B`` - - Hierarchical B coding. - * - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P`` - - Hierarchical P coding. - - - -``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)`` - Specifies the number of hierarchical coding layers. Applicable to - the H264 encoder. - -``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)`` - Specifies a user defined QP for each layer. Applicable to the H264 - encoder. The supplied 32-bit integer is interpreted as follows (bit - 0 = least significant bit): - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - Bit 0:15 - - QP value - * - Bit 16:32 - - Layer number - - - -.. _v4l2-mpeg-mpeg2: - -``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)`` - Specifies the slice parameters (as extracted from the bitstream) for the - associated MPEG-2 slice data. This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for MPEG-2. - The bitstream parameters are defined according to :ref:`mpeg2part2`. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_mpeg2_slice_params - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_mpeg2_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``bit_size`` - - Size (in bits) of the current slice data. - * - __u32 - - ``data_bit_offset`` - - Offset (in bits) to the video data in the current slice data. - * - struct :c:type:`v4l2_mpeg2_sequence` - - ``sequence`` - - Structure with MPEG-2 sequence metadata, merging relevant fields from - the sequence header and sequence extension parts of the bitstream. - * - struct :c:type:`v4l2_mpeg2_picture` - - ``picture`` - - Structure with MPEG-2 picture metadata, merging relevant fields from - the picture header and picture coding extension parts of the bitstream. - * - __u8 - - ``quantiser_scale_code`` - - Code used to determine the quantization scale to use for the IDCT. - * - __u8 - - ``backward_ref_index`` - - Index for the V4L2 buffer to use as backward reference, used with - B-coded and P-coded frames. - * - __u8 - - ``forward_ref_index`` - - Index for the V4L2 buffer to use as forward reference, used with - B-coded frames. - -.. c:type:: v4l2_mpeg2_sequence - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_mpeg2_sequence - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``horizontal_size`` - - The width of the displayable part of the frame's luminance component. - * - __u16 - - ``vertical_size`` - - The height of the displayable part of the frame's luminance component. - * - __u32 - - ``vbv_buffer_size`` - - Used to calculate the required size of the video buffering verifier, - defined (in bits) as: 16 * 1024 * vbv_buffer_size. - * - __u8 - - ``profile_and_level_indication`` - - The current profile and level indication as extracted from the - bitstream. - * - __u8 - - ``progressive_sequence`` - - Indication that all the frames for the sequence are progressive instead - of interlaced. - * - __u8 - - ``chroma_format`` - - The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4). - -.. c:type:: v4l2_mpeg2_picture - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_mpeg2_picture - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``picture_coding_type`` - - Picture coding type for the frame covered by the current slice - (V4L2_MPEG2_PICTURE_CODING_TYPE_I, V4L2_MPEG2_PICTURE_CODING_TYPE_P or - V4L2_MPEG2_PICTURE_CODING_TYPE_B). - * - __u8 - - ``f_code[2][2]`` - - Motion vector codes. - * - __u8 - - ``intra_dc_precision`` - - Precision of Discrete Cosine transform (0: 8 bits precision, - 1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision). - * - __u8 - - ``picture_structure`` - - Picture structure (1: interlaced top field, 2: interlaced bottom field, - 3: progressive frame). - * - __u8 - - ``top_field_first`` - - If set to 1 and interlaced stream, top field is output first. - * - __u8 - - ``frame_pred_frame_dct`` - - If set to 1, only frame-DCT and frame prediction are used. - * - __u8 - - ``concealment_motion_vectors`` - - If set to 1, motion vectors are coded for intra macroblocks. - * - __u8 - - ``q_scale_type`` - - This flag affects the inverse quantization process. - * - __u8 - - ``intra_vlc_format`` - - This flag affects the decoding of transform coefficient data. - * - __u8 - - ``alternate_scan`` - - This flag affects the decoding of transform coefficient data. - * - __u8 - - ``repeat_first_field`` - - This flag affects the decoding process of progressive frames. - * - __u8 - - ``progressive_frame`` - - Indicates whether the current frame is progressive. - -``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION (struct)`` - Specifies quantization matrices (as extracted from the bitstream) for the - associated MPEG-2 slice data. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_mpeg2_quantization - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_mpeg2_quantization - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``load_intra_quantiser_matrix`` - - One bit to indicate whether to load the ``intra_quantiser_matrix`` data. - * - __u8 - - ``load_non_intra_quantiser_matrix`` - - One bit to indicate whether to load the ``non_intra_quantiser_matrix`` - data. - * - __u8 - - ``load_chroma_intra_quantiser_matrix`` - - One bit to indicate whether to load the - ``chroma_intra_quantiser_matrix`` data, only relevant for non-4:2:0 YUV - formats. - * - __u8 - - ``load_chroma_non_intra_quantiser_matrix`` - - One bit to indicate whether to load the - ``chroma_non_intra_quantiser_matrix`` data, only relevant for non-4:2:0 - YUV formats. - * - __u8 - - ``intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for intra-coded frames, in zigzag - scanning order. It is relevant for both luma and chroma components, - although it can be superseded by the chroma-specific matrix for - non-4:2:0 YUV formats. - * - __u8 - - ``non_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for non-intra-coded frames, in - zigzag scanning order. It is relevant for both luma and chroma - components, although it can be superseded by the chroma-specific matrix - for non-4:2:0 YUV formats. - * - __u8 - - ``chroma_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for the chominance component of - intra-coded frames, in zigzag scanning order. Only relevant for - non-4:2:0 YUV formats. - * - __u8 - - ``chroma_non_intra_quantiser_matrix[64]`` - - The quantization matrix coefficients for the chrominance component of - non-intra-coded frames, in zigzag scanning order. Only relevant for - non-4:2:0 YUV formats. - -MFC 5.1 MPEG Controls ---------------------- - -The following MPEG class controls deal with MPEG decoding and encoding -settings that are specific to the Multi Format Codec 5.1 device present -in the S5P family of SoCs by Samsung. - - -.. _mfc51-control-id: - -MFC 5.1 Control IDs -^^^^^^^^^^^^^^^^^^^ - -``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE (boolean)`` - If the display delay is enabled then the decoder is forced to return - a CAPTURE buffer (decoded frame) after processing a certain number - of OUTPUT buffers. The delay can be set through - ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This - feature can be used for example for generating thumbnails of videos. - Applicable to the H264 decoder. - -``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)`` - Display delay value for H264 decoder. The decoder is forced to - return a decoded frame after the set 'display delay' number of - frames. If this number is low it may result in frames returned out - of dispaly order, in addition the hardware may still be using the - returned buffer as a reference picture for subsequent frames. - -``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)`` - The number of reference pictures used for encoding a P picture. - Applicable to the H264 encoder. - -``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)`` - Padding enable in the encoder - use a color instead of repeating - border pixels. Applicable to encoders. - -``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)`` - Padding color in the encoder. Applicable to encoders. The supplied - 32-bit integer is interpreted as follows (bit 0 = least significant - bit): - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - Bit 0:7 - - V chrominance information - * - Bit 8:15 - - U chrominance information - * - Bit 16:23 - - Y luminance information - * - Bit 24:31 - - Must be zero. - - - -``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)`` - Reaction coefficient for MFC rate control. Applicable to encoders. - - .. note:: - - #. Valid only when the frame level RC is enabled. - - #. For tight CBR, this field must be small (ex. 2 ~ 10). For - VBR, this field must be large (ex. 100 ~ 1000). - - #. It is not recommended to use the greater number than - FRAME_RATE * (10^9 / BIT_RATE). - -``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)`` - Adaptive rate control for dark region. Valid only when H.264 and - macroblock level RC is enabled - (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264 - encoder. - -``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)`` - Adaptive rate control for smooth region. Valid only when H.264 and - macroblock level RC is enabled - (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264 - encoder. - -``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)`` - Adaptive rate control for static region. Valid only when H.264 and - macroblock level RC is enabled - (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264 - encoder. - -``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)`` - Adaptive rate control for activity region. Valid only when H.264 and - macroblock level RC is enabled - (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264 - encoder. - -.. _v4l2-mpeg-mfc51-video-frame-skip-mode: - -``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE`` - (enum) - -enum v4l2_mpeg_mfc51_video_frame_skip_mode - - Indicates in what conditions the encoder should skip frames. If - encoding a frame would cause the encoded stream to be larger then a - chosen data limit then the frame will be skipped. Possible values - are: - - -.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED`` - - Frame skip mode is disabled. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT`` - - Frame skip mode enabled and buffer limit is set by the chosen - level and is defined by the standard. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT`` - - Frame skip mode enabled and buffer limit is set by the VBV - (MPEG1/2/4) or CPB (H264) buffer size control. - - - -``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)`` - Enable rate-control with fixed target bit. If this setting is - enabled, then the rate control logic of the encoder will calculate - the average bitrate for a GOP and keep it below or equal the set - bitrate target. Otherwise the rate control logic calculates the - overall average bitrate for the stream and keeps it below or equal - to the set bitrate. In the first case the average bitrate for the - whole stream will be smaller then the set bitrate. This is caused - because the average is calculated for smaller number of frames, on - the other hand enabling this setting will ensure that the stream - will meet tight bandwidth constraints. Applicable to encoders. - -.. _v4l2-mpeg-mfc51-video-force-frame-type: - -``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE`` - (enum) - -enum v4l2_mpeg_mfc51_video_force_frame_type - - Force a frame type for the next queued buffer. Applicable to - encoders. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED`` - - Forcing a specific frame type disabled. - * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME`` - - Force an I-frame. - * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED`` - - Force a non-coded frame. - - - - -CX2341x MPEG Controls ---------------------- - -The following MPEG class controls deal with MPEG encoding settings that -are specific to the Conexant CX23415 and CX23416 MPEG encoding chips. - - -.. _cx2341x-control-id: - -CX2341x Control IDs -^^^^^^^^^^^^^^^^^^^ - -.. _v4l2-mpeg-cx2341x-video-spatial-filter-mode: - -``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE`` - (enum) - -enum v4l2_mpeg_cx2341x_video_spatial_filter_mode - - Sets the Spatial Filter mode (default ``MANUAL``). Possible values - are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL`` - - Choose the filter manually - * - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO`` - - Choose the filter automatically - - - -``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))`` - The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default - is 0.) - -.. _luma-spatial-filter-type: - -``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE`` - (enum) - -enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - - Select the algorithm to use for the Luma Spatial Filter (default - ``1D_HOR``). Possible values: - - - -.. tabularcolumns:: |p{14.5cm}|p{3.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF`` - - No filter - * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR`` - - One-dimensional horizontal - * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT`` - - One-dimensional vertical - * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE`` - - Two-dimensional separable - * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE`` - - Two-dimensional symmetrical non-separable - - - -.. _chroma-spatial-filter-type: - -``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE`` - (enum) - -enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - - Select the algorithm for the Chroma Spatial Filter (default - ``1D_HOR``). Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF`` - - No filter - * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR`` - - One-dimensional horizontal - - - -.. _v4l2-mpeg-cx2341x-video-temporal-filter-mode: - -``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE`` - (enum) - -enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - - Sets the Temporal Filter mode (default ``MANUAL``). Possible values - are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL`` - - Choose the filter manually - * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO`` - - Choose the filter automatically - - - -``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))`` - The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default - is 8 for full-scale capturing and 0 for scaled capturing.) - -.. _v4l2-mpeg-cx2341x-video-median-filter-type: - -``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE`` - (enum) - -enum v4l2_mpeg_cx2341x_video_median_filter_type - - Median Filter Type (default ``OFF``). Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF`` - - No filter - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR`` - - Horizontal filter - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT`` - - Vertical filter - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT`` - - Horizontal and vertical filter - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG`` - - Diagonal filter - - - -``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))`` - Threshold above which the luminance median filter is enabled - (default 0) - -``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))`` - Threshold below which the luminance median filter is enabled - (default 255) - -``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))`` - Threshold above which the chroma median filter is enabled (default - 0) - -``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))`` - Threshold below which the chroma median filter is enabled (default - 255) - -``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)`` - The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into - the stream between every four video frames. The packet size is 2048 - bytes, including the packet_start_code_prefix and stream_id - fields. The stream_id is 0xBF (private stream 2). The payload - consists of 0x00 bytes, to be filled in by the application. 0 = do - not insert, 1 = insert packets. - - -VPX Control Reference ---------------------- - -The VPX controls include controls for encoding parameters of VPx video -codec. - - -.. _vpx-control-id: - -VPX Control IDs -^^^^^^^^^^^^^^^ - -.. _v4l2-vpx-num-partitions: - -``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS`` - (enum) - -enum v4l2_vp8_num_partitions - - The number of token partitions to use in VP8 encoder. Possible - values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION`` - - 1 coefficient partition - * - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS`` - - 2 coefficient partitions - * - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS`` - - 4 coefficient partitions - * - ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS`` - - 8 coefficient partitions - - - -``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)`` - Setting this prevents intra 4x4 mode in the intra mode decision. - -.. _v4l2-vpx-num-ref-frames: - -``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES`` - (enum) - -enum v4l2_vp8_num_ref_frames - - The number of reference pictures for encoding P frames. Possible - values are: - -.. tabularcolumns:: |p{7.9cm}|p{9.6cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME`` - - Last encoded frame will be searched - * - ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME`` - - Two frames will be searched among the last encoded frame, the - golden frame and the alternate reference (altref) frame. The - encoder implementation will decide which two are chosen. - * - ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME`` - - The last encoded frame, the golden frame and the altref frame will - be searched. - - - -``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)`` - Indicates the loop filter level. The adjustment of the loop filter - level is done via a delta value against a baseline loop filter - value. - -``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)`` - This parameter affects the loop filter. Anything above zero weakens - the deblocking effect on the loop filter. - -``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)`` - Sets the refresh period for the golden frame. The period is defined - in number of frames. For a value of 'n', every nth frame starting - from the first key frame will be taken as a golden frame. For eg. - for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden - frame refresh period is set as 4, the frames 0, 4, 8 etc will be - taken as the golden frames as frame 0 is always a key frame. - -.. _v4l2-vpx-golden-frame-sel: - -``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL`` - (enum) - -enum v4l2_vp8_golden_frame_sel - - Selects the golden frame for encoding. Possible values are: - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV`` - - Use the (n-2)th frame as a golden frame, current frame index being - 'n'. - * - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD`` - - Use the previous specific frame indicated by - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD`` as a - golden frame. - -.. raw:: latex - - \normalsize - - -``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)`` - Minimum quantization parameter for VP8. - -``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)`` - Maximum quantization parameter for VP8. - -``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)`` - Quantization parameter for an I frame for VP8. - -``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)`` - Quantization parameter for a P frame for VP8. - -.. _v4l2-mpeg-video-vp8-profile: - -``V4L2_CID_MPEG_VIDEO_VP8_PROFILE`` - (enum) - -enum v4l2_mpeg_video_vp8_profile - - This control allows selecting the profile for VP8 encoder. - This is also used to enumerate supported profiles by VP8 encoder or decoder. - Possible values are: - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_0`` - - Profile 0 - * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_1`` - - Profile 1 - * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_2`` - - Profile 2 - * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_3`` - - Profile 3 - -.. _v4l2-mpeg-video-vp9-profile: - -``V4L2_CID_MPEG_VIDEO_VP9_PROFILE`` - (enum) - -enum v4l2_mpeg_video_vp9_profile - - This control allows selecting the profile for VP9 encoder. - This is also used to enumerate supported profiles by VP9 encoder or decoder. - Possible values are: - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_0`` - - Profile 0 - * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_1`` - - Profile 1 - * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_2`` - - Profile 2 - * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_3`` - - Profile 3 - - -High Efficiency Video Coding (HEVC/H.265) Control Reference ------------------------------------------------------------ - -The HEVC/H.265 controls include controls for encoding parameters of HEVC/H.265 -video codec. - - -.. _hevc-control-id: - -HEVC/H.265 Control IDs -^^^^^^^^^^^^^^^^^^^^^^ - -``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP (integer)`` - Minimum quantization parameter for HEVC. - Valid range: from 0 to 51. - -``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP (integer)`` - Maximum quantization parameter for HEVC. - Valid range: from 0 to 51. - -``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_QP (integer)`` - Quantization parameter for an I frame for HEVC. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_QP (integer)`` - Quantization parameter for a P frame for HEVC. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_QP (integer)`` - Quantization parameter for a B frame for HEVC. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_QP (boolean)`` - HIERARCHICAL_QP allows the host to specify the quantization parameter - values for each temporal layer through HIERARCHICAL_QP_LAYER. This is - valid only if HIERARCHICAL_CODING_LAYER is greater than 1. Setting the - control value to 1 enables setting of the QP values for the layers. - -.. _v4l2-hevc-hier-coding-type: - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_TYPE`` - (enum) - -enum v4l2_mpeg_video_hevc_hier_coding_type - - Selects the hierarchical coding type for encoding. Possible values are: - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_HIERARCHICAL_CODING_B`` - - Use the B frame for hierarchical coding. - * - ``V4L2_MPEG_VIDEO_HEVC_HIERARCHICAL_CODING_P`` - - Use the P frame for hierarchical coding. - -.. raw:: latex - - \normalsize - - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_LAYER (integer)`` - Selects the hierarchical coding layer. In normal encoding - (non-hierarchial coding), it should be zero. Possible values are [0, 6]. - 0 indicates HIERARCHICAL CODING LAYER 0, 1 indicates HIERARCHICAL CODING - LAYER 1 and so on. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_QP (integer)`` - Indicates quantization parameter for hierarchical coding layer 0. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_QP (integer)`` - Indicates quantization parameter for hierarchical coding layer 1. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_QP (integer)`` - Indicates quantization parameter for hierarchical coding layer 2. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_QP (integer)`` - Indicates quantization parameter for hierarchical coding layer 3. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_QP (integer)`` - Indicates quantization parameter for hierarchical coding layer 4. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_QP (integer)`` - Indicates quantization parameter for hierarchical coding layer 5. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_QP (integer)`` - Indicates quantization parameter for hierarchical coding layer 6. - Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, - V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. - -.. _v4l2-hevc-profile: - -``V4L2_CID_MPEG_VIDEO_HEVC_PROFILE`` - (enum) - -enum v4l2_mpeg_video_hevc_profile - - Select the desired profile for HEVC encoder. - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN`` - - Main profile. - * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_STILL_PICTURE`` - - Main still picture profile. - * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_10`` - - Main 10 profile. - -.. raw:: latex - - \normalsize - - -.. _v4l2-hevc-level: - -``V4L2_CID_MPEG_VIDEO_HEVC_LEVEL`` - (enum) - -enum v4l2_mpeg_video_hevc_level - - Selects the desired level for HEVC encoder. - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` - - Level 1.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` - - Level 2.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` - - Level 2.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` - - Level 3.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` - - Level 3.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` - - Level 4.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` - - Level 4.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` - - Level 5.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` - - Level 5.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` - - Level 5.2 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` - - Level 6.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` - - Level 6.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` - - Level 6.2 - -.. raw:: latex - - \normalsize - - -``V4L2_CID_MPEG_VIDEO_HEVC_FRAME_RATE_RESOLUTION (integer)`` - Indicates the number of evenly spaced subintervals, called ticks, within - one second. This is a 16 bit unsigned integer and has a maximum value up to - 0xffff and a minimum value of 1. - -.. _v4l2-hevc-tier: - -``V4L2_CID_MPEG_VIDEO_HEVC_TIER`` - (enum) - -enum v4l2_mpeg_video_hevc_tier - - TIER_FLAG specifies tiers information of the HEVC encoded picture. Tier - were made to deal with applications that differ in terms of maximum bit - rate. Setting the flag to 0 selects HEVC tier as Main tier and setting - this flag to 1 indicates High tier. High tier is for applications requiring - high bit rates. - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` - - Main tier. - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` - - High tier. - -.. raw:: latex - - \normalsize - - -``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)`` - Selects HEVC maximum coding unit depth. - -.. _v4l2-hevc-loop-filter-mode: - -``V4L2_CID_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE`` - (enum) - -enum v4l2_mpeg_video_hevc_loop_filter_mode - - Loop filter mode for HEVC encoder. Possible values are: - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{10.7cm}|p{6.3cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_DISABLED`` - - Loop filter is disabled. - * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_ENABLED`` - - Loop filter is enabled. - * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY`` - - Loop filter is disabled at the slice boundary. - -.. raw:: latex - - \normalsize - - -``V4L2_CID_MPEG_VIDEO_HEVC_LF_BETA_OFFSET_DIV2 (integer)`` - Selects HEVC loop filter beta offset. The valid range is [-6, +6]. - -``V4L2_CID_MPEG_VIDEO_HEVC_LF_TC_OFFSET_DIV2 (integer)`` - Selects HEVC loop filter tc offset. The valid range is [-6, +6]. - -.. _v4l2-hevc-refresh-type: - -``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_TYPE`` - (enum) - -enum v4l2_mpeg_video_hevc_hier_refresh_type - - Selects refresh type for HEVC encoder. - Host has to specify the period into - V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_PERIOD. - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{8.0cm}|p{9.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_NONE`` - - Use the B frame for hierarchical coding. - * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_CRA`` - - Use CRA (Clean Random Access Unit) picture encoding. - * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_IDR`` - - Use IDR (Instantaneous Decoding Refresh) picture encoding. - -.. raw:: latex - - \normalsize - - -``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_PERIOD (integer)`` - Selects the refresh period for HEVC encoder. - This specifies the number of I pictures between two CRA/IDR pictures. - This is valid only if REFRESH_TYPE is not 0. - -``V4L2_CID_MPEG_VIDEO_HEVC_LOSSLESS_CU (boolean)`` - Indicates HEVC lossless encoding. Setting it to 0 disables lossless - encoding. Setting it to 1 enables lossless encoding. - -``V4L2_CID_MPEG_VIDEO_HEVC_CONST_INTRA_PRED (boolean)`` - Indicates constant intra prediction for HEVC encoder. Specifies the - constrained intra prediction in which intra largest coding unit (LCU) - prediction is performed by using residual data and decoded samples of - neighboring intra LCU only. Setting the value to 1 enables constant intra - prediction and setting the value to 0 disables constant intra prediction. - -``V4L2_CID_MPEG_VIDEO_HEVC_WAVEFRONT (boolean)`` - Indicates wavefront parallel processing for HEVC encoder. Setting it to 0 - disables the feature and setting it to 1 enables the wavefront parallel - processing. - -``V4L2_CID_MPEG_VIDEO_HEVC_GENERAL_PB (boolean)`` - Setting the value to 1 enables combination of P and B frame for HEVC - encoder. - -``V4L2_CID_MPEG_VIDEO_HEVC_TEMPORAL_ID (boolean)`` - Indicates temporal identifier for HEVC encoder which is enabled by - setting the value to 1. - -``V4L2_CID_MPEG_VIDEO_HEVC_STRONG_SMOOTHING (boolean)`` - Indicates bi-linear interpolation is conditionally used in the intra - prediction filtering process in the CVS when set to 1. Indicates bi-linear - interpolation is not used in the CVS when set to 0. - -``V4L2_CID_MPEG_VIDEO_HEVC_MAX_NUM_MERGE_MV_MINUS1 (integer)`` - Indicates maximum number of merge candidate motion vectors. - Values are from 0 to 4. - -``V4L2_CID_MPEG_VIDEO_HEVC_TMV_PREDICTION (boolean)`` - Indicates temporal motion vector prediction for HEVC encoder. Setting it to - 1 enables the prediction. Setting it to 0 disables the prediction. - -``V4L2_CID_MPEG_VIDEO_HEVC_WITHOUT_STARTCODE (boolean)`` - Specifies if HEVC generates a stream with a size of the length field - instead of start code pattern. The size of the length field is configurable - through the V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD control. Setting - the value to 0 disables encoding without startcode pattern. Setting the - value to 1 will enables encoding without startcode pattern. - -.. _v4l2-hevc-size-of-length-field: - -``V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD`` -(enum) - -enum v4l2_mpeg_video_hevc_size_of_length_field - - Indicates the size of length field. - This is valid when encoding WITHOUT_STARTCODE_ENABLE is enabled. - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{6.0cm}|p{11.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_0`` - - Generate start code pattern (Normal). - * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_1`` - - Generate size of length field instead of start code pattern and length is 1. - * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_2`` - - Generate size of length field instead of start code pattern and length is 2. - * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_4`` - - Generate size of length field instead of start code pattern and length is 4. - -.. raw:: latex - - \normalsize - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_BR (integer)`` - Indicates bit rate for hierarchical coding layer 0 for HEVC encoder. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_BR (integer)`` - Indicates bit rate for hierarchical coding layer 1 for HEVC encoder. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_BR (integer)`` - Indicates bit rate for hierarchical coding layer 2 for HEVC encoder. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_BR (integer)`` - Indicates bit rate for hierarchical coding layer 3 for HEVC encoder. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_BR (integer)`` - Indicates bit rate for hierarchical coding layer 4 for HEVC encoder. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_BR (integer)`` - Indicates bit rate for hierarchical coding layer 5 for HEVC encoder. - -``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_BR (integer)`` - Indicates bit rate for hierarchical coding layer 6 for HEVC encoder. - -``V4L2_CID_MPEG_VIDEO_REF_NUMBER_FOR_PFRAMES (integer)`` - Selects number of P reference pictures required for HEVC encoder. - P-Frame can use 1 or 2 frames for reference. - -``V4L2_CID_MPEG_VIDEO_PREPEND_SPSPPS_TO_IDR (integer)`` - Indicates whether to generate SPS and PPS at every IDR. Setting it to 0 - disables generating SPS and PPS at every IDR. Setting it to one enables - generating SPS and PPS at every IDR. - - -.. _camera-controls: - -Camera Control Reference -======================== - -The Camera class includes controls for mechanical (or equivalent -digital) features of a device such as controllable lenses or sensors. - - -.. _camera-control-id: - -Camera Control IDs ------------------- - -``V4L2_CID_CAMERA_CLASS (class)`` - The Camera class descriptor. Calling - :ref:`VIDIOC_QUERYCTRL` for this control will - return a description of this control class. - -.. _v4l2-exposure-auto-type: - -``V4L2_CID_EXPOSURE_AUTO`` - (enum) - -enum v4l2_exposure_auto_type - - Enables automatic adjustments of the exposure time and/or iris - aperture. The effect of manual changes of the exposure time or iris - aperture while these features are enabled is undefined, drivers - should ignore such requests. Possible values are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_EXPOSURE_AUTO`` - - Automatic exposure time, automatic iris aperture. - * - ``V4L2_EXPOSURE_MANUAL`` - - Manual exposure time, manual iris. - * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY`` - - Manual exposure time, auto iris. - * - ``V4L2_EXPOSURE_APERTURE_PRIORITY`` - - Auto exposure time, manual iris. - - - -``V4L2_CID_EXPOSURE_ABSOLUTE (integer)`` - Determines the exposure time of the camera sensor. The exposure time - is limited by the frame interval. Drivers should interpret the - values as 100 µs units, where the value 1 stands for 1/10000th of a - second, 10000 for 1 second and 100000 for 10 seconds. - -``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)`` - When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or - ``APERTURE_PRIORITY``, this control determines if the device may - dynamically vary the frame rate. By default this feature is disabled - (0) and the frame rate must remain constant. - -``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)`` - Determines the automatic exposure compensation, it is effective only - when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``, - ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in - terms of EV, drivers should interpret the values as 0.001 EV units, - where the value 1000 stands for +1 EV. - - Increasing the exposure compensation value is equivalent to - decreasing the exposure value (EV) and will increase the amount of - light at the image sensor. The camera performs the exposure - compensation by adjusting absolute exposure time and/or aperture. - -.. _v4l2-exposure-metering: - -``V4L2_CID_EXPOSURE_METERING`` - (enum) - -enum v4l2_exposure_metering - - Determines how the camera measures the amount of light available for - the frame exposure. Possible values are: - -.. tabularcolumns:: |p{8.5cm}|p{9.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_EXPOSURE_METERING_AVERAGE`` - - Use the light information coming from the entire frame and average - giving no weighting to any particular portion of the metered area. - * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED`` - - Average the light information coming from the entire frame giving - priority to the center of the metered area. - * - ``V4L2_EXPOSURE_METERING_SPOT`` - - Measure only very small area at the center of the frame. - * - ``V4L2_EXPOSURE_METERING_MATRIX`` - - A multi-zone metering. The light intensity is measured in several - points of the frame and the results are combined. The algorithm of - the zones selection and their significance in calculating the - final value is device dependent. - - - -``V4L2_CID_PAN_RELATIVE (integer)`` - This control turns the camera horizontally by the specified amount. - The unit is undefined. A positive value moves the camera to the - right (clockwise when viewed from above), a negative value to the - left. A value of zero does not cause motion. This is a write-only - control. - -``V4L2_CID_TILT_RELATIVE (integer)`` - This control turns the camera vertically by the specified amount. - The unit is undefined. A positive value moves the camera up, a - negative value down. A value of zero does not cause motion. This is - a write-only control. - -``V4L2_CID_PAN_RESET (button)`` - When this control is set, the camera moves horizontally to the - default position. - -``V4L2_CID_TILT_RESET (button)`` - When this control is set, the camera moves vertically to the default - position. - -``V4L2_CID_PAN_ABSOLUTE (integer)`` - This control turns the camera horizontally to the specified - position. Positive values move the camera to the right (clockwise - when viewed from above), negative values to the left. Drivers should - interpret the values as arc seconds, with valid values between -180 - * 3600 and +180 * 3600 inclusive. - -``V4L2_CID_TILT_ABSOLUTE (integer)`` - This control turns the camera vertically to the specified position. - Positive values move the camera up, negative values down. Drivers - should interpret the values as arc seconds, with valid values - between -180 * 3600 and +180 * 3600 inclusive. - -``V4L2_CID_FOCUS_ABSOLUTE (integer)`` - This control sets the focal point of the camera to the specified - position. The unit is undefined. Positive values set the focus - closer to the camera, negative values towards infinity. - -``V4L2_CID_FOCUS_RELATIVE (integer)`` - This control moves the focal point of the camera by the specified - amount. The unit is undefined. Positive values move the focus closer - to the camera, negative values towards infinity. This is a - write-only control. - -``V4L2_CID_FOCUS_AUTO (boolean)`` - Enables continuous automatic focus adjustments. The effect of manual - focus adjustments while this feature is enabled is undefined, - drivers should ignore such requests. - -``V4L2_CID_AUTO_FOCUS_START (button)`` - Starts single auto focus process. The effect of setting this control - when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined, - drivers should ignore such requests. - -``V4L2_CID_AUTO_FOCUS_STOP (button)`` - Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START`` - control. It is effective only when the continuous autofocus is - disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to - ``FALSE`` (0). - -.. _v4l2-auto-focus-status: - -``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)`` - The automatic focus status. This is a read-only control. - - Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK`` - control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS`` - control value. - -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_AUTO_FOCUS_STATUS_IDLE`` - - Automatic focus is not active. - * - ``V4L2_AUTO_FOCUS_STATUS_BUSY`` - - Automatic focusing is in progress. - * - ``V4L2_AUTO_FOCUS_STATUS_REACHED`` - - Focus has been reached. - * - ``V4L2_AUTO_FOCUS_STATUS_FAILED`` - - Automatic focus has failed, the driver will not transition from - this state until another action is performed by an application. - - - -.. _v4l2-auto-focus-range: - -``V4L2_CID_AUTO_FOCUS_RANGE`` - (enum) - -enum v4l2_auto_focus_range - - Determines auto focus distance range for which lens may be adjusted. - -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_AUTO_FOCUS_RANGE_AUTO`` - - The camera automatically selects the focus range. - * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL`` - - Normal distance range, limited for best automatic focus - performance. - * - ``V4L2_AUTO_FOCUS_RANGE_MACRO`` - - Macro (close-up) auto focus. The camera will use its minimum - possible distance for auto focus. - * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY`` - - The lens is set to focus on an object at infinite distance. - - - -``V4L2_CID_ZOOM_ABSOLUTE (integer)`` - Specify the objective lens focal length as an absolute value. The - zoom unit is driver-specific and its value should be a positive - integer. - -``V4L2_CID_ZOOM_RELATIVE (integer)`` - Specify the objective lens focal length relatively to the current - value. Positive values move the zoom lens group towards the - telephoto direction, negative values towards the wide-angle - direction. The zoom unit is driver-specific. This is a write-only - control. - -``V4L2_CID_ZOOM_CONTINUOUS (integer)`` - Move the objective lens group at the specified speed until it - reaches physical device limits or until an explicit request to stop - the movement. A positive value moves the zoom lens group towards the - telephoto direction. A value of zero stops the zoom lens group - movement. A negative value moves the zoom lens group towards the - wide-angle direction. The zoom speed unit is driver-specific. - -``V4L2_CID_IRIS_ABSOLUTE (integer)`` - This control sets the camera's aperture to the specified value. The - unit is undefined. Larger values open the iris wider, smaller values - close it. - -``V4L2_CID_IRIS_RELATIVE (integer)`` - This control modifies the camera's aperture by the specified amount. - The unit is undefined. Positive values open the iris one step - further, negative values close it one step further. This is a - write-only control. - -``V4L2_CID_PRIVACY (boolean)`` - Prevent video from being acquired by the camera. When this control - is set to ``TRUE`` (1), no image can be captured by the camera. - Common means to enforce privacy are mechanical obturation of the - sensor and firmware image processing, but the device is not - restricted to these methods. Devices that implement the privacy - control must support read access and may support write access. - -``V4L2_CID_BAND_STOP_FILTER (integer)`` - Switch the band-stop filter of a camera sensor on or off, or specify - its strength. Such band-stop filters can be used, for example, to - filter out the fluorescent light component. - -.. _v4l2-auto-n-preset-white-balance: - -``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE`` - (enum) - -enum v4l2_auto_n_preset_white_balance - - Sets white balance to automatic, manual or a preset. The presets - determine color temperature of the light as a hint to the camera for - white balance adjustments resulting in most accurate color - representation. The following white balance presets are listed in - order of increasing color temperature. - -.. tabularcolumns:: |p{7.0 cm}|p{10.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_WHITE_BALANCE_MANUAL`` - - Manual white balance. - * - ``V4L2_WHITE_BALANCE_AUTO`` - - Automatic white balance adjustments. - * - ``V4L2_WHITE_BALANCE_INCANDESCENT`` - - White balance setting for incandescent (tungsten) lighting. It - generally cools down the colors and corresponds approximately to - 2500...3500 K color temperature range. - * - ``V4L2_WHITE_BALANCE_FLUORESCENT`` - - White balance preset for fluorescent lighting. It corresponds - approximately to 4000...5000 K color temperature. - * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H`` - - With this setting the camera will compensate for fluorescent H - lighting. - * - ``V4L2_WHITE_BALANCE_HORIZON`` - - White balance setting for horizon daylight. It corresponds - approximately to 5000 K color temperature. - * - ``V4L2_WHITE_BALANCE_DAYLIGHT`` - - White balance preset for daylight (with clear sky). It corresponds - approximately to 5000...6500 K color temperature. - * - ``V4L2_WHITE_BALANCE_FLASH`` - - With this setting the camera will compensate for the flash light. - It slightly warms up the colors and corresponds roughly to - 5000...5500 K color temperature. - * - ``V4L2_WHITE_BALANCE_CLOUDY`` - - White balance preset for moderately overcast sky. This option - corresponds approximately to 6500...8000 K color temperature - range. - * - ``V4L2_WHITE_BALANCE_SHADE`` - - White balance preset for shade or heavily overcast sky. It - corresponds approximately to 9000...10000 K color temperature. - - - -.. _v4l2-wide-dynamic-range: - -``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)`` - Enables or disables the camera's wide dynamic range feature. This - feature allows to obtain clear images in situations where intensity - of the illumination varies significantly throughout the scene, i.e. - there are simultaneously very dark and very bright areas. It is most - commonly realized in cameras by combining two subsequent frames with - different exposure times. [#f1]_ - -.. _v4l2-image-stabilization: - -``V4L2_CID_IMAGE_STABILIZATION (boolean)`` - Enables or disables image stabilization. - -``V4L2_CID_ISO_SENSITIVITY (integer menu)`` - Determines ISO equivalent of an image sensor indicating the sensor's - sensitivity to light. The numbers are expressed in arithmetic scale, - as per :ref:`iso12232` standard, where doubling the sensor - sensitivity is represented by doubling the numerical ISO value. - Applications should interpret the values as standard ISO values - multiplied by 1000, e.g. control value 800 stands for ISO 0.8. - Drivers will usually support only a subset of standard ISO values. - The effect of setting this control while the - ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other - than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers - should ignore such requests. - -.. _v4l2-iso-sensitivity-auto-type: - -``V4L2_CID_ISO_SENSITIVITY_AUTO`` - (enum) - -enum v4l2_iso_sensitivity_type - - Enables or disables automatic ISO sensitivity adjustments. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` - - Manual ISO sensitivity. - * - ``V4L2_CID_ISO_SENSITIVITY_AUTO`` - - Automatic ISO sensitivity adjustments. - - - -.. _v4l2-scene-mode: - -``V4L2_CID_SCENE_MODE`` - (enum) - -enum v4l2_scene_mode - - This control allows to select scene programs as the camera automatic - modes optimized for common shooting scenes. Within these modes the - camera determines best exposure, aperture, focusing, light metering, - white balance and equivalent sensitivity. The controls of those - parameters are influenced by the scene mode control. An exact - behavior in each mode is subject to the camera specification. - - When the scene mode feature is not used, this control should be set - to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related - controls are accessible. The following scene programs are defined: - -.. tabularcolumns:: |p{6.0cm}|p{11.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_SCENE_MODE_NONE`` - - The scene mode feature is disabled. - * - ``V4L2_SCENE_MODE_BACKLIGHT`` - - Backlight. Compensates for dark shadows when light is coming from - behind a subject, also by automatically turning on the flash. - * - ``V4L2_SCENE_MODE_BEACH_SNOW`` - - Beach and snow. This mode compensates for all-white or bright - scenes, which tend to look gray and low contrast, when camera's - automatic exposure is based on an average scene brightness. To - compensate, this mode automatically slightly overexposes the - frames. The white balance may also be adjusted to compensate for - the fact that reflected snow looks bluish rather than white. - * - ``V4L2_SCENE_MODE_CANDLELIGHT`` - - Candle light. The camera generally raises the ISO sensitivity and - lowers the shutter speed. This mode compensates for relatively - close subject in the scene. The flash is disabled in order to - preserve the ambiance of the light. - * - ``V4L2_SCENE_MODE_DAWN_DUSK`` - - Dawn and dusk. Preserves the colors seen in low natural light - before dusk and after down. The camera may turn off the flash, and - automatically focus at infinity. It will usually boost saturation - and lower the shutter speed. - * - ``V4L2_SCENE_MODE_FALL_COLORS`` - - Fall colors. Increases saturation and adjusts white balance for - color enhancement. Pictures of autumn leaves get saturated reds - and yellows. - * - ``V4L2_SCENE_MODE_FIREWORKS`` - - Fireworks. Long exposure times are used to capture the expanding - burst of light from a firework. The camera may invoke image - stabilization. - * - ``V4L2_SCENE_MODE_LANDSCAPE`` - - Landscape. The camera may choose a small aperture to provide deep - depth of field and long exposure duration to help capture detail - in dim light conditions. The focus is fixed at infinity. Suitable - for distant and wide scenery. - * - ``V4L2_SCENE_MODE_NIGHT`` - - Night, also known as Night Landscape. Designed for low light - conditions, it preserves detail in the dark areas without blowing - out bright objects. The camera generally sets itself to a - medium-to-high ISO sensitivity, with a relatively long exposure - time, and turns flash off. As such, there will be increased image - noise and the possibility of blurred image. - * - ``V4L2_SCENE_MODE_PARTY_INDOOR`` - - Party and indoor. Designed to capture indoor scenes that are lit - by indoor background lighting as well as the flash. The camera - usually increases ISO sensitivity, and adjusts exposure for the - low light conditions. - * - ``V4L2_SCENE_MODE_PORTRAIT`` - - Portrait. The camera adjusts the aperture so that the depth of - field is reduced, which helps to isolate the subject against a - smooth background. Most cameras recognize the presence of faces in - the scene and focus on them. The color hue is adjusted to enhance - skin tones. The intensity of the flash is often reduced. - * - ``V4L2_SCENE_MODE_SPORTS`` - - Sports. Significantly increases ISO and uses a fast shutter speed - to freeze motion of rapidly-moving subjects. Increased image noise - may be seen in this mode. - * - ``V4L2_SCENE_MODE_SUNSET`` - - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps - up the saturation. - * - ``V4L2_SCENE_MODE_TEXT`` - - Text. It applies extra contrast and sharpness, it is typically a - black-and-white mode optimized for readability. Automatic focus - may be switched to close-up mode and this setting may also involve - some lens-distortion correction. - - - -``V4L2_CID_3A_LOCK (bitmask)`` - This control locks or unlocks the automatic focus, exposure and - white balance. The automatic adjustments can be paused independently - by setting the corresponding lock bit to 1. The camera then retains - the settings until the lock bit is cleared. The following lock bits - are defined: - - When a given algorithm is not enabled, drivers should ignore - requests to lock it and should return no error. An example might be - an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the - ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The - value of this control may be changed by exposure, white balance or - focus controls. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_LOCK_EXPOSURE`` - - Automatic exposure adjustments lock. - * - ``V4L2_LOCK_WHITE_BALANCE`` - - Automatic white balance adjustments lock. - * - ``V4L2_LOCK_FOCUS`` - - Automatic focus lock. - - - -``V4L2_CID_PAN_SPEED (integer)`` - This control turns the camera horizontally at the specific speed. - The unit is undefined. A positive value moves the camera to the - right (clockwise when viewed from above), a negative value to the - left. A value of zero stops the motion if one is in progress and has - no effect otherwise. - -``V4L2_CID_TILT_SPEED (integer)`` - This control turns the camera vertically at the specified speed. The - unit is undefined. A positive value moves the camera up, a negative - value down. A value of zero stops the motion if one is in progress - and has no effect otherwise. - - -.. _fm-tx-controls: - -FM Transmitter Control Reference -================================ - -The FM Transmitter (FM_TX) class includes controls for common features -of FM transmissions capable devices. Currently this class includes -parameters for audio compression, pilot tone generation, audio deviation -limiter, RDS transmission and tuning power features. - - -.. _fm-tx-control-id: - -FM_TX Control IDs ------------------ - -``V4L2_CID_FM_TX_CLASS (class)`` - The FM_TX class descriptor. Calling - :ref:`VIDIOC_QUERYCTRL` for this control will - return a description of this control class. - -``V4L2_CID_RDS_TX_DEVIATION (integer)`` - Configures RDS signal frequency deviation level in Hz. The range and - step are driver-specific. - -``V4L2_CID_RDS_TX_PI (integer)`` - Sets the RDS Programme Identification field for transmission. - -``V4L2_CID_RDS_TX_PTY (integer)`` - Sets the RDS Programme Type field for transmission. This encodes up - to 31 pre-defined programme types. - -``V4L2_CID_RDS_TX_PS_NAME (string)`` - Sets the Programme Service name (PS_NAME) for transmission. It is - intended for static display on a receiver. It is the primary aid to - listeners in programme service identification and selection. In - Annex E of :ref:`iec62106`, the RDS specification, there is a full - description of the correct character encoding for Programme Service - name strings. Also from RDS specification, PS is usually a single - eight character text. However, it is also possible to find receivers - which can scroll strings sized as 8 x N characters. So, this control - must be configured with steps of 8 characters. The result is it must - always contain a string with size multiple of 8. - -``V4L2_CID_RDS_TX_RADIO_TEXT (string)`` - Sets the Radio Text info for transmission. It is a textual - description of what is being broadcasted. RDS Radio Text can be - applied when broadcaster wishes to transmit longer PS names, - programme-related information or any other text. In these cases, - RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``. - The encoding for Radio Text strings is also fully described in Annex - E of :ref:`iec62106`. The length of Radio Text strings depends on - which RDS Block is being used to transmit it, either 32 (2A block) - or 64 (2B block). However, it is also possible to find receivers - which can scroll strings sized as 32 x N or 64 x N characters. So, - this control must be configured with steps of 32 or 64 characters. - The result is it must always contain a string with size multiple of - 32 or 64. - -``V4L2_CID_RDS_TX_MONO_STEREO (boolean)`` - Sets the Mono/Stereo bit of the Decoder Identification code. If set, - then the audio was recorded as stereo. - -``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)`` - Sets the - `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__ - bit of the Decoder Identification code. If set, then the audio was - recorded using an artificial head. - -``V4L2_CID_RDS_TX_COMPRESSED (boolean)`` - Sets the Compressed bit of the Decoder Identification code. If set, - then the audio is compressed. - -``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)`` - Sets the Dynamic PTY bit of the Decoder Identification code. If set, - then the PTY code is dynamically switched. - -``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)`` - If set, then a traffic announcement is in progress. - -``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)`` - If set, then the tuned programme carries traffic announcements. - -``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)`` - If set, then this channel broadcasts music. If cleared, then it - broadcasts speech. If the transmitter doesn't make this distinction, - then it should be set. - -``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)`` - If set, then transmit alternate frequencies. - -``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)`` - The alternate frequencies in kHz units. The RDS standard allows for - up to 25 frequencies to be defined. Drivers may support fewer - frequencies so check the array size. - -``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)`` - Enables or disables the audio deviation limiter feature. The limiter - is useful when trying to maximize the audio volume, minimize - receiver-generated distortion and prevent overmodulation. - -``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)`` - Sets the audio deviation limiter feature release time. Unit is in - useconds. Step and range are driver-specific. - -``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)`` - Configures audio frequency deviation level in Hz. The range and step - are driver-specific. - -``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)`` - Enables or disables the audio compression feature. This feature - amplifies signals below the threshold by a fixed gain and compresses - audio signals above the threshold by the ratio of Threshold/(Gain + - Threshold). - -``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)`` - Sets the gain for audio compression feature. It is a dB value. The - range and step are driver-specific. - -``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)`` - Sets the threshold level for audio compression freature. It is a dB - value. The range and step are driver-specific. - -``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)`` - Sets the attack time for audio compression feature. It is a useconds - value. The range and step are driver-specific. - -``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)`` - Sets the release time for audio compression feature. It is a - useconds value. The range and step are driver-specific. - -``V4L2_CID_PILOT_TONE_ENABLED (boolean)`` - Enables or disables the pilot tone generation feature. - -``V4L2_CID_PILOT_TONE_DEVIATION (integer)`` - Configures pilot tone frequency deviation level. Unit is in Hz. The - range and step are driver-specific. - -``V4L2_CID_PILOT_TONE_FREQUENCY (integer)`` - Configures pilot tone frequency value. Unit is in Hz. The range and - step are driver-specific. - -``V4L2_CID_TUNE_PREEMPHASIS`` - (enum) - -enum v4l2_preemphasis - - Configures the pre-emphasis value for broadcasting. A pre-emphasis - filter is applied to the broadcast to accentuate the high audio - frequencies. Depending on the region, a time constant of either 50 - or 75 useconds is used. The enum v4l2_preemphasis defines possible - values for pre-emphasis. Here they are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_PREEMPHASIS_DISABLED`` - - No pre-emphasis is applied. - * - ``V4L2_PREEMPHASIS_50_uS`` - - A pre-emphasis of 50 uS is used. - * - ``V4L2_PREEMPHASIS_75_uS`` - - A pre-emphasis of 75 uS is used. - - - -``V4L2_CID_TUNE_POWER_LEVEL (integer)`` - Sets the output power level for signal transmission. Unit is in - dBuV. Range and step are driver-specific. - -``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)`` - This selects the value of antenna tuning capacitor manually or - automatically if set to zero. Unit, range and step are - driver-specific. - -For more details about RDS specification, refer to :ref:`iec62106` -document, from CENELEC. - - -.. _flash-controls: - -Flash Control Reference -======================= - -The V4L2 flash controls are intended to provide generic access to flash -controller devices. Flash controller devices are typically used in -digital cameras. - -The interface can support both LED and xenon flash devices. As of -writing this, there is no xenon flash driver using this interface. - - -.. _flash-controls-use-cases: - -Supported use cases -------------------- - - -Unsynchronised LED flash (software strobe) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Unsynchronised LED flash is controlled directly by the host as the -sensor. The flash must be enabled by the host before the exposure of the -image starts and disabled once it ends. The host is fully responsible -for the timing of the flash. - -Example of such device: Nokia N900. - - -Synchronised LED flash (hardware strobe) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The synchronised LED flash is pre-programmed by the host (power and -timeout) but controlled by the sensor through a strobe signal from the -sensor to the flash. - -The sensor controls the flash duration and timing. This information -typically must be made available to the sensor. - - -LED flash as torch -^^^^^^^^^^^^^^^^^^ - -LED flash may be used as torch in conjunction with another use case -involving camera or individually. - - -.. _flash-control-id: - -Flash Control IDs -""""""""""""""""" - -``V4L2_CID_FLASH_CLASS (class)`` - The FLASH class descriptor. - -``V4L2_CID_FLASH_LED_MODE (menu)`` - Defines the mode of the flash LED, the high-power white LED attached - to the flash controller. Setting this control may not be possible in - presence of some faults. See V4L2_CID_FLASH_FAULT. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_FLASH_LED_MODE_NONE`` - - Off. - * - ``V4L2_FLASH_LED_MODE_FLASH`` - - Flash mode. - * - ``V4L2_FLASH_LED_MODE_TORCH`` - - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. - - - -``V4L2_CID_FLASH_STROBE_SOURCE (menu)`` - Defines the source of the flash LED strobe. - -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE`` - - The flash strobe is triggered by using the - V4L2_CID_FLASH_STROBE control. - * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL`` - - The flash strobe is triggered by an external source. Typically - this is a sensor, which makes it possible to synchronises the - flash strobe start to exposure start. - - - -``V4L2_CID_FLASH_STROBE (button)`` - Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to - V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE - is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this - control may not be possible in presence of some faults. See - V4L2_CID_FLASH_FAULT. - -``V4L2_CID_FLASH_STROBE_STOP (button)`` - Stop flash strobe immediately. - -``V4L2_CID_FLASH_STROBE_STATUS (boolean)`` - Strobe status: whether the flash is strobing at the moment or not. - This is a read-only control. - -``V4L2_CID_FLASH_TIMEOUT (integer)`` - Hardware timeout for flash. The flash strobe is stopped after this - period of time has passed from the start of the strobe. - -``V4L2_CID_FLASH_INTENSITY (integer)`` - Intensity of the flash strobe when the flash LED is in flash mode - (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA) - if possible. - -``V4L2_CID_FLASH_TORCH_INTENSITY (integer)`` - Intensity of the flash LED in torch mode - (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA) - if possible. Setting this control may not be possible in presence of - some faults. See V4L2_CID_FLASH_FAULT. - -``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)`` - Intensity of the indicator LED. The indicator LED may be fully - independent of the flash LED. The unit should be microamps (uA) if - possible. - -``V4L2_CID_FLASH_FAULT (bitmask)`` - Faults related to the flash. The faults tell about specific problems - in the flash chip itself or the LEDs attached to it. Faults may - prevent further use of some of the flash controls. In particular, - V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE - if the fault affects the flash LED. Exactly which faults have such - an effect is chip dependent. Reading the faults resets the control - and returns the chip to a usable state if possible. - -.. tabularcolumns:: |p{8.0cm}|p{9.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE`` - - Flash controller voltage to the flash LED has exceeded the limit - specific to the flash controller. - * - ``V4L2_FLASH_FAULT_TIMEOUT`` - - The flash strobe was still on when the timeout set by the user --- - V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash - controllers may set this in all such conditions. - * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE`` - - The flash controller has overheated. - * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT`` - - The short circuit protection of the flash controller has been - triggered. - * - ``V4L2_FLASH_FAULT_OVER_CURRENT`` - - Current in the LED power supply has exceeded the limit specific to - the flash controller. - * - ``V4L2_FLASH_FAULT_INDICATOR`` - - The flash controller has detected a short or open circuit - condition on the indicator LED. - * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE`` - - Flash controller voltage to the flash LED has been below the - minimum limit specific to the flash controller. - * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE`` - - The input voltage of the flash controller is below the limit under - which strobing the flash at full current will not be possible.The - condition persists until this flag is no longer set. - * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE`` - - The temperature of the LED has exceeded its allowed upper limit. - - - -``V4L2_CID_FLASH_CHARGE (boolean)`` - Enable or disable charging of the xenon flash capacitor. - -``V4L2_CID_FLASH_READY (boolean)`` - Is the flash ready to strobe? Xenon flashes require their capacitors - charged before strobing. LED flashes often require a cooldown period - after strobe during which another strobe will not be possible. This - is a read-only control. - - -.. _jpeg-controls: - -JPEG Control Reference -====================== - -The JPEG class includes controls for common features of JPEG encoders -and decoders. Currently it includes features for codecs implementing -progressive baseline DCT compression process with Huffman entrophy -coding. - - -.. _jpeg-control-id: - -JPEG Control IDs ----------------- - -``V4L2_CID_JPEG_CLASS (class)`` - The JPEG class descriptor. Calling - :ref:`VIDIOC_QUERYCTRL` for this control will - return a description of this control class. - -``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)`` - The chroma subsampling factors describe how each component of an - input image is sampled, in respect to maximum sample rate in each - spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more - details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines - how Cb and Cr components are downsampled after converting an input - image from RGB to Y'CbCr color space. - -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444`` - - No chroma subsampling, each pixel has Y, Cr and Cb values. - * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422`` - - Horizontally subsample Cr, Cb components by a factor of 2. - * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420`` - - Subsample Cr, Cb components horizontally and vertically by 2. - * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411`` - - Horizontally subsample Cr, Cb components by a factor of 4. - * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410`` - - Subsample Cr, Cb components horizontally by 4 and vertically by 2. - * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY`` - - Use only luminance component. - - - -``V4L2_CID_JPEG_RESTART_INTERVAL (integer)`` - The restart interval determines an interval of inserting RSTm - markers (m = 0..7). The purpose of these markers is to additionally - reinitialize the encoder process, in order to process blocks of an - image independently. For the lossy compression processes the restart - interval unit is MCU (Minimum Coded Unit) and its value is contained - in DRI (Define Restart Interval) marker. If - ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm - markers will not be inserted. - -.. _jpeg-quality-control: - -``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)`` - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off - between image quality and size. It provides simpler method for - applications to control image quality, without a need for direct - reconfiguration of luminance and chrominance quantization tables. In - cases where a driver uses quantization tables configured directly by - an application, using interfaces defined elsewhere, - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by - driver to 0. - - The value range of this control is driver-specific. Only positive, - non-zero values are meaningful. The recommended range is 1 - 100, - where larger values correspond to better image quality. - -.. _jpeg-active-marker-control: - -``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)`` - Specify which JPEG markers are included in compressed stream. This - control is valid only for encoders. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_JPEG_ACTIVE_MARKER_APP0`` - - Application data segment APP\ :sub:`0`. - * - ``V4L2_JPEG_ACTIVE_MARKER_APP1`` - - Application data segment APP\ :sub:`1`. - * - ``V4L2_JPEG_ACTIVE_MARKER_COM`` - - Comment segment. - * - ``V4L2_JPEG_ACTIVE_MARKER_DQT`` - - Quantization tables segment. - * - ``V4L2_JPEG_ACTIVE_MARKER_DHT`` - - Huffman tables segment. - - - -For more details about JPEG specification, refer to :ref:`itu-t81`, -:ref:`jfif`, :ref:`w3c-jpeg-jfif`. - - -.. _image-source-controls: - -Image Source Control Reference -============================== - -The Image Source control class is intended for low-level control of -image source devices such as image sensors. The devices feature an -analogue to digital converter and a bus transmitter to transmit the -image data out of the device. - - -.. _image-source-control-id: - -Image Source Control IDs ------------------------- - -``V4L2_CID_IMAGE_SOURCE_CLASS (class)`` - The IMAGE_SOURCE class descriptor. - -``V4L2_CID_VBLANK (integer)`` - Vertical blanking. The idle period after every frame during which no - image data is produced. The unit of vertical blanking is a line. - Every line has length of the image width plus horizontal blanking at - the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the - same sub-device. - -``V4L2_CID_HBLANK (integer)`` - Horizontal blanking. The idle period after every line of image data - during which no image data is produced. The unit of horizontal - blanking is pixels. - -``V4L2_CID_ANALOGUE_GAIN (integer)`` - Analogue gain is gain affecting all colour components in the pixel - matrix. The gain operation is performed in the analogue domain - before A/D conversion. - -``V4L2_CID_TEST_PATTERN_RED (integer)`` - Test pattern red colour component. - -``V4L2_CID_TEST_PATTERN_GREENR (integer)`` - Test pattern green (next to red) colour component. - -``V4L2_CID_TEST_PATTERN_BLUE (integer)`` - Test pattern blue colour component. - -``V4L2_CID_TEST_PATTERN_GREENB (integer)`` - Test pattern green (next to blue) colour component. - - -.. _image-process-controls: - -Image Process Control Reference -=============================== - -The Image Process control class is intended for low-level control of -image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the -controls in this class affect processing the image, and do not control -capturing of it. - - -.. _image-process-control-id: - -Image Process Control IDs -------------------------- - -``V4L2_CID_IMAGE_PROC_CLASS (class)`` - The IMAGE_PROC class descriptor. - -``V4L2_CID_LINK_FREQ (integer menu)`` - Data bus frequency. Together with the media bus pixel code, bus type - (clock cycles per sample), the data bus frequency defines the pixel - rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly - elsewhere, if the device is not an image sensor). The frame rate can - be calculated from the pixel clock, image width and height and - horizontal and vertical blanking. While the pixel rate control may - be defined elsewhere than in the subdev containing the pixel array, - the frame rate cannot be obtained from that information. This is - because only on the pixel array it can be assumed that the vertical - and horizontal blanking information is exact: no other blanking is - allowed in the pixel array. The selection of frame rate is performed - by selecting the desired horizontal and vertical blanking. The unit - of this control is Hz. - -``V4L2_CID_PIXEL_RATE (64-bit integer)`` - Pixel rate in the source pads of the subdev. This control is - read-only and its unit is pixels / second. - -``V4L2_CID_TEST_PATTERN (menu)`` - Some capture/display/sensor devices have the capability to generate - test pattern images. These hardware specific test patterns can be - used to test if a device is working properly. - -``V4L2_CID_DEINTERLACING_MODE (menu)`` - The video deinterlacing mode (such as Bob, Weave, ...). The menu items are - driver specific and are documented in :ref:`v4l-drivers`. - -``V4L2_CID_DIGITAL_GAIN (integer)`` - Digital gain is the value by which all colour components - are multiplied by. Typically the digital gain applied is the - control value divided by e.g. 0x100, meaning that to get no - digital gain the control value needs to be 0x100. The no-gain - configuration is also typically the default. - - -.. _dv-controls: - -Digital Video Control Reference -=============================== - -The Digital Video control class is intended to control receivers and -transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__, -`DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__ -(Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort -(:ref:`dp`). These controls are generally expected to be private to -the receiver or transmitter subdevice that implements them, so they are -only exposed on the ``/dev/v4l-subdev*`` device node. - -.. note:: - - Note that these devices can have multiple input or output pads which are - hooked up to e.g. HDMI connectors. Even though the subdevice will - receive or transmit video from/to only one of those pads, the other pads - can still be active when it comes to EDID (Extended Display - Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital - Content Protection System, :ref:`hdcp`) processing, allowing the - device to do the fairly slow EDID/HDCP handling in advance. This allows - for quick switching between connectors. - -These pads appear in several of the controls in this section as -bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad -1, etc. The maximum value of the control is the set of valid pads. - - -.. _dv-control-id: - -Digital Video Control IDs -------------------------- - -``V4L2_CID_DV_CLASS (class)`` - The Digital Video class descriptor. - -``V4L2_CID_DV_TX_HOTPLUG (bitmask)`` - Many connectors have a hotplug pin which is high if EDID information - is available from the source. This control shows the state of the - hotplug pin as seen by the transmitter. Each bit corresponds to an - output pad on the transmitter. If an output pad does not have an - associated hotplug pin, then the bit for that pad will be 0. This - read-only control is applicable to DVI-D, HDMI and DisplayPort - connectors. - -``V4L2_CID_DV_TX_RXSENSE (bitmask)`` - Rx Sense is the detection of pull-ups on the TMDS clock lines. This - normally means that the sink has left/entered standby (i.e. the - transmitter can sense that the receiver is ready to receive video). - Each bit corresponds to an output pad on the transmitter. If an - output pad does not have an associated Rx Sense, then the bit for - that pad will be 0. This read-only control is applicable to DVI-D - and HDMI devices. - -``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)`` - When the transmitter sees the hotplug signal from the receiver it - will attempt to read the EDID. If set, then the transmitter has read - at least the first block (= 128 bytes). Each bit corresponds to an - output pad on the transmitter. If an output pad does not support - EDIDs, then the bit for that pad will be 0. This read-only control - is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. - -``V4L2_CID_DV_TX_MODE`` - (enum) - -enum v4l2_dv_tx_mode - - HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI - mode (video + audio + auxiliary data). This control selects which - mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI. - This control is applicable to HDMI connectors. - -``V4L2_CID_DV_TX_RGB_RANGE`` - (enum) - -enum v4l2_dv_rgb_range - - Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO - follows the RGB quantization range specified in the standard for the - video interface (ie. :ref:`cea861` for HDMI). - V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the - standard to be compatible with sinks that have not implemented the - standard correctly (unfortunately quite common for HDMI and DVI-D). - Full range allows all possible values to be used whereas limited - range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is - the number of bits per component. This control is applicable to VGA, - DVI-A/D, HDMI and DisplayPort connectors. - -``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` - (enum) - -enum v4l2_dv_it_content_type - - Configures the IT Content Type of the transmitted video. This - information is sent over HDMI and DisplayPort connectors as part of - the AVI InfoFrame. The term 'IT Content' is used for content that - originates from a computer as opposed to content from a TV broadcast - or an analog source. The enum v4l2_dv_it_content_type defines - the possible content types: - -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS`` - - Graphics content. Pixel data should be passed unfiltered and - without analog reconstruction. - * - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO`` - - Photo content. The content is derived from digital still pictures. - The content should be passed through with minimal scaling and - picture enhancements. - * - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA`` - - Cinema content. - * - ``V4L2_DV_IT_CONTENT_TYPE_GAME`` - - Game content. Audio and video latency should be minimized. - * - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC`` - - No IT Content information is available and the ITC bit in the AVI - InfoFrame is set to 0. - - - -``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)`` - Detects whether the receiver receives power from the source (e.g. - HDMI carries 5V on one of the pins). This is often used to power an - eeprom which contains EDID information, such that the source can - read the EDID even if the sink is in standby/power off. Each bit - corresponds to an input pad on the receiver. If an input pad - cannot detect whether power is present, then the bit for that pad - will be 0. This read-only control is applicable to DVI-D, HDMI and - DisplayPort connectors. - -``V4L2_CID_DV_RX_RGB_RANGE`` - (enum) - -enum v4l2_dv_rgb_range - - Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO - follows the RGB quantization range specified in the standard for the - video interface (ie. :ref:`cea861` for HDMI). - V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the - standard to be compatible with sources that have not implemented the - standard correctly (unfortunately quite common for HDMI and DVI-D). - Full range allows all possible values to be used whereas limited - range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is - the number of bits per component. This control is applicable to VGA, - DVI-A/D, HDMI and DisplayPort connectors. - -``V4L2_CID_DV_RX_IT_CONTENT_TYPE`` - (enum) - -enum v4l2_dv_it_content_type - - Reads the IT Content Type of the received video. This information is - sent over HDMI and DisplayPort connectors as part of the AVI - InfoFrame. The term 'IT Content' is used for content that originates - from a computer as opposed to content from a TV broadcast or an - analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the - available content types. - - -.. _fm-rx-controls: - -FM Receiver Control Reference -============================= - -The FM Receiver (FM_RX) class includes controls for common features of -FM Reception capable devices. - - -.. _fm-rx-control-id: - -FM_RX Control IDs ------------------ - -``V4L2_CID_FM_RX_CLASS (class)`` - The FM_RX class descriptor. Calling - :ref:`VIDIOC_QUERYCTRL` for this control will - return a description of this control class. - -``V4L2_CID_RDS_RECEPTION (boolean)`` - Enables/disables RDS reception by the radio tuner - -``V4L2_CID_RDS_RX_PTY (integer)`` - Gets RDS Programme Type field. This encodes up to 31 pre-defined - programme types. - -``V4L2_CID_RDS_RX_PS_NAME (string)`` - Gets the Programme Service name (PS_NAME). It is intended for - static display on a receiver. It is the primary aid to listeners in - programme service identification and selection. In Annex E of - :ref:`iec62106`, the RDS specification, there is a full - description of the correct character encoding for Programme Service - name strings. Also from RDS specification, PS is usually a single - eight character text. However, it is also possible to find receivers - which can scroll strings sized as 8 x N characters. So, this control - must be configured with steps of 8 characters. The result is it must - always contain a string with size multiple of 8. - -``V4L2_CID_RDS_RX_RADIO_TEXT (string)`` - Gets the Radio Text info. It is a textual description of what is - being broadcasted. RDS Radio Text can be applied when broadcaster - wishes to transmit longer PS names, programme-related information or - any other text. In these cases, RadioText can be used in addition to - ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is - also fully described in Annex E of :ref:`iec62106`. The length of - Radio Text strings depends on which RDS Block is being used to - transmit it, either 32 (2A block) or 64 (2B block). However, it is - also possible to find receivers which can scroll strings sized as 32 - x N or 64 x N characters. So, this control must be configured with - steps of 32 or 64 characters. The result is it must always contain a - string with size multiple of 32 or 64. - -``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)`` - If set, then a traffic announcement is in progress. - -``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)`` - If set, then the tuned programme carries traffic announcements. - -``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)`` - If set, then this channel broadcasts music. If cleared, then it - broadcasts speech. If the transmitter doesn't make this distinction, - then it will be set. - -``V4L2_CID_TUNE_DEEMPHASIS`` - (enum) - -enum v4l2_deemphasis - - Configures the de-emphasis value for reception. A de-emphasis filter - is applied to the broadcast to accentuate the high audio - frequencies. Depending on the region, a time constant of either 50 - or 75 useconds is used. The enum v4l2_deemphasis defines possible - values for de-emphasis. Here they are: - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_DEEMPHASIS_DISABLED`` - - No de-emphasis is applied. - * - ``V4L2_DEEMPHASIS_50_uS`` - - A de-emphasis of 50 uS is used. - * - ``V4L2_DEEMPHASIS_75_uS`` - - A de-emphasis of 75 uS is used. - - - - -.. _detect-controls: - -Detect Control Reference -======================== - -The Detect class includes controls for common features of various motion -or object detection capable devices. - - -.. _detect-control-id: - -Detect Control IDs ------------------- - -``V4L2_CID_DETECT_CLASS (class)`` - The Detect class descriptor. Calling - :ref:`VIDIOC_QUERYCTRL` for this control will - return a description of this control class. - -``V4L2_CID_DETECT_MD_MODE (menu)`` - Sets the motion detection mode. - -.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_DETECT_MD_MODE_DISABLED`` - - Disable motion detection. - * - ``V4L2_DETECT_MD_MODE_GLOBAL`` - - Use a single motion detection threshold. - * - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` - - The image is divided into a grid, each cell with its own motion - detection threshold. These thresholds are set through the - ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control. - * - ``V4L2_DETECT_MD_MODE_REGION_GRID`` - - The image is divided into a grid, each cell with its own region - value that specifies which per-region motion detection thresholds - should be used. Each region has its own thresholds. How these - per-region thresholds are set up is driver-specific. The region - values for the grid are set through the - ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control. - - - -``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)`` - Sets the global motion detection threshold to be used with the - ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode. - -``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)`` - Sets the motion detection thresholds for each cell in the grid. To - be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion - detection mode. Matrix element (0, 0) represents the cell at the - top-left of the grid. - -``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)`` - Sets the motion detection region value for each cell in the grid. To - be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion - detection mode. Matrix element (0, 0) represents the cell at the - top-left of the grid. - - -.. _rf-tuner-controls: - -RF Tuner Control Reference -========================== - -The RF Tuner (RF_TUNER) class includes controls for common features of -devices having RF tuner. - -In this context, RF tuner is radio receiver circuit between antenna and -demodulator. It receives radio frequency (RF) from the antenna and -converts that received signal to lower intermediate frequency (IF) or -baseband frequency (BB). Tuners that could do baseband output are often -called Zero-IF tuners. Older tuners were typically simple PLL tuners -inside a metal box, while newer ones are highly integrated chips -without a metal box "silicon tuners". These controls are mostly -applicable for new feature rich silicon tuners, just because older -tuners does not have much adjustable features. - -For more information about RF tuners see -`Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__ -and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__ -from Wikipedia. - - -.. _rf-tuner-control-id: - -RF_TUNER Control IDs --------------------- - -``V4L2_CID_RF_TUNER_CLASS (class)`` - The RF_TUNER class descriptor. Calling - :ref:`VIDIOC_QUERYCTRL` for this control will - return a description of this control class. - -``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)`` - Enables/disables tuner radio channel bandwidth configuration. In - automatic mode bandwidth configuration is performed by the driver. - -``V4L2_CID_RF_TUNER_BANDWIDTH (integer)`` - Filter(s) on tuner signal path are used to filter signal according - to receiving party needs. Driver configures filters to fulfill - desired bandwidth requirement. Used when - V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The - range and step are driver-specific. - -``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)`` - Enables/disables LNA automatic gain control (AGC) - -``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)`` - Enables/disables mixer automatic gain control (AGC) - -``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)`` - Enables/disables IF automatic gain control (AGC) - -``V4L2_CID_RF_TUNER_RF_GAIN (integer)`` - The RF amplifier is the very first amplifier on the receiver signal - path, just right after the antenna input. The difference between the - LNA gain and the RF gain in this document is that the LNA gain is - integrated in the tuner chip while the RF gain is a separate chip. - There may be both RF and LNA gain controls in the same device. The - range and step are driver-specific. - -``V4L2_CID_RF_TUNER_LNA_GAIN (integer)`` - LNA (low noise amplifier) gain is first gain stage on the RF tuner - signal path. It is located very close to tuner antenna input. Used - when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See - ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain - differs from the each others. The range and step are - driver-specific. - -``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)`` - Mixer gain is second gain stage on the RF tuner signal path. It is - located inside mixer block, where RF signal is down-converted by the - mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set. - The range and step are driver-specific. - -``V4L2_CID_RF_TUNER_IF_GAIN (integer)`` - IF gain is last gain stage on the RF tuner signal path. It is - located on output of RF tuner. It controls signal level of - intermediate frequency output or baseband output. Used when - ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step - are driver-specific. - -``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)`` - Is synthesizer PLL locked? RF tuner is receiving given frequency - when that control is set. This is a read-only control. - -.. [#f1] - This control may be changed to a menu control in the future, if more - options are required. diff --git a/Documentation/media/uapi/v4l/meta-formats.rst b/Documentation/media/uapi/v4l/meta-formats.rst index 5f956fa784b7..b10ca9ee3968 100644 --- a/Documentation/media/uapi/v4l/meta-formats.rst +++ b/Documentation/media/uapi/v4l/meta-formats.rst @@ -19,8 +19,8 @@ These formats are used for the :ref:`metadata` interface only. .. toctree:: :maxdepth: 1 - pixfmt-meta-intel-ipu3 pixfmt-meta-d4xx + pixfmt-meta-intel-ipu3 pixfmt-meta-uvc pixfmt-meta-vsp1-hgo pixfmt-meta-vsp1-hgt diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst index e4c5e456df59..2675bef3eefe 100644 --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst @@ -73,7 +73,7 @@ Compressed Formats - 'MG2S' - MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream. This format is adapted for stateless video decoders that implement a - MPEG-2 pipeline (using the :ref:`codec` and :ref:`media-request-api`). + MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). Metadata associated with the frame to decode is required to be passed through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and quantization matrices can optionally be specified through the diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst b/Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst index dc871006b41a..7fb54339f4a7 100644 --- a/Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst +++ b/Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst @@ -1,4 +1,27 @@ -.. -*- coding: utf-8; mode: rst -*- +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file is free software; you can redistribute it and/or +.. modify it under the terms of the GNU General Public License version +.. 2.0 as published by the Free Software Foundation. +.. +.. This file is distributed in the hope that it will be useful, +.. but WITHOUT ANY WARRANTY; without even the implied warranty of +.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. GNU General Public License version 2.0 for more details. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-meta-fmt-params: .. _v4l2-meta-fmt-stat-3a: @@ -7,21 +30,22 @@ V4L2_META_FMT_IPU3_PARAMS ('ip3p'), V4L2_META_FMT_IPU3_3A ('ip3s') ****************************************************************** -.. c:type:: ipu3_uapi_stats_3a +.. ipu3_uapi_stats_3a 3A statistics ============= -For IPU3 ImgU, the 3A statistics accelerators collect different statistics over -an input bayer frame. Those statistics, defined in data struct :c:type:`ipu3_uapi_stats_3a`, -are obtained from "ipu3-imgu 3a stat" metadata capture video node, which are then -passed to user space for statistics analysis using :c:type:`v4l2_meta_format` interface. +The IPU3 ImgU 3A statistics accelerators collect different statistics over +an input Bayer frame. Those statistics are obtained from the "ipu3-imgu [01] 3a +stat" metadata capture video nodes, using the :c:type:`v4l2_meta_format` +interface. They are formatted as described by the :c:type:`ipu3_uapi_stats_3a` +structure. The statistics collected are AWB (Auto-white balance) RGBS (Red, Green, Blue and Saturation measure) cells, AWB filter response, AF (Auto-focus) filter response, and AE (Auto-exposure) histogram. -struct :c:type:`ipu3_uapi_4a_config` saves configurable parameters for all above. +The struct :c:type:`ipu3_uapi_4a_config` saves all configurable parameters. .. code-block:: c @@ -37,105 +61,14 @@ struct :c:type:`ipu3_uapi_4a_config` saves configurable parameters for all above struct ipu3_uapi_ff_status stats_3a_status; }; -.. c:type:: ipu3_uapi_params +.. ipu3_uapi_params Pipeline parameters =================== -IPU3 pipeline has a number of image processing stages, each of which takes a -set of parameters as input. The major stages of pipelines are shown here: - -Raw pixels -> Bayer Downscaling -> Optical Black Correction -> - -Linearization -> Lens Shading Correction -> White Balance / Exposure / - -Focus Apply -> Bayer Noise Reduction -> ANR -> Demosaicing -> Color - -Correction Matrix -> Gamma correction -> Color Space Conversion -> - -Chroma Down Scaling -> Chromatic Noise Reduction -> Total Color - -Correction -> XNR3 -> TNR -> DDR - -The table below presents a description of the above algorithms. - -======================== ======================================================= -Name Description -======================== ======================================================= -Optical Black Correction Optical Black Correction block subtracts a pre-defined - value from the respective pixel values to obtain better - image quality. - Defined in :c:type:`ipu3_uapi_obgrid_param`. -Linearization This algo block uses linearization parameters to - address non-linearity sensor effects. The Lookup table - table is defined in - :c:type:`ipu3_uapi_isp_lin_vmem_params`. -SHD Lens shading correction is used to correct spatial - non-uniformity of the pixel response due to optical - lens shading. This is done by applying a different gain - for each pixel. The gain, black level etc are - configured in :c:type:`ipu3_uapi_shd_config_static`. -BNR Bayer noise reduction block removes image noise by - applying a bilateral filter. - See :c:type:`ipu3_uapi_bnr_static_config` for details. -ANR Advanced Noise Reduction is a block based algorithm - that performs noise reduction in the Bayer domain. The - convolution matrix etc can be found in - :c:type:`ipu3_uapi_anr_config`. -Demosaicing Demosaicing converts raw sensor data in Bayer format - into RGB (Red, Green, Blue) presentation. Then add - outputs of estimation of Y channel for following stream - processing by Firmware. The struct is defined as - :c:type:`ipu3_uapi_dm_config`. (TODO) -Color Correction Color Correction algo transforms sensor specific color - space to the standard "sRGB" color space. This is done - by applying 3x3 matrix defined in - :c:type:`ipu3_uapi_ccm_mat_config`. -Gamma correction Gamma correction :c:type:`ipu3_uapi_gamma_config` is a - basic non-linear tone mapping correction that is - applied per pixel for each pixel component. -CSC Color space conversion transforms each pixel from the - RGB primary presentation to YUV (Y: brightness, - UV: Luminance) presentation. This is done by applying - a 3x3 matrix defined in - :c:type:`ipu3_uapi_csc_mat_config` -CDS Chroma down sampling - After the CSC is performed, the Chroma Down Sampling - is applied for a UV plane down sampling by a factor - of 2 in each direction for YUV 4:2:0 using a 4x2 - configurable filter :c:type:`ipu3_uapi_cds_params`. -CHNR Chroma noise reduction - This block processes only the chrominance pixels and - performs noise reduction by cleaning the high - frequency noise. - See struct :c:type:`ipu3_uapi_yuvp1_chnr_config`. -TCC Total color correction as defined in struct - :c:type:`ipu3_uapi_yuvp2_tcc_static_config`. -XNR3 eXtreme Noise Reduction V3 is the third revision of - noise reduction algorithm used to improve image - quality. This removes the low frequency noise in the - captured image. Two related structs are being defined, - :c:type:`ipu3_uapi_isp_xnr3_params` for ISP data memory - and :c:type:`ipu3_uapi_isp_xnr3_vmem_params` for vector - memory. -TNR Temporal Noise Reduction block compares successive - frames in time to remove anomalies / noise in pixel - values. :c:type:`ipu3_uapi_isp_tnr3_vmem_params` and - :c:type:`ipu3_uapi_isp_tnr3_params` are defined for ISP - vector and data memory respectively. -======================== ======================================================= - -A few stages of the pipeline will be executed by firmware running on the ISP -processor, while many others will use a set of fixed hardware blocks also -called accelerator cluster (ACC) to crunch pixel data and produce statistics. - -ACC parameters of individual algorithms, as defined by -:c:type:`ipu3_uapi_acc_param`, can be chosen to be applied by the user -space through struct :c:type:`ipu3_uapi_flags` embedded in -:c:type:`ipu3_uapi_params` structure. For parameters that are configured as -not enabled by the user space, the corresponding structs are ignored by the -driver, in which case the existing configuration of the algorithm will be -preserved. +The pipeline parameters are passed to the "ipu3-imgu [01] parameters" metadata +output video nodes, using the :c:type:`v4l2_meta_format` interface. They are +formatted as described by the :c:type:`ipu3_uapi_params` structure. Both 3A statistics and pipeline parameters described here are closely tied to the underlying camera sub-system (CSS) APIs. They are usually consumed and @@ -143,13 +76,6 @@ produced by dedicated user space libraries that comprise the important tuning tools, thus freeing the developers from being bothered with the low level hardware and algorithm details. -It should be noted that IPU3 DMA operations require the addresses of all data -structures (that includes both input and output) to be aligned on 32 byte -boundaries. - -The meta data :c:type:`ipu3_uapi_params` will be sent to "ipu3-imgu parameters" -video node in ``V4L2_BUF_TYPE_META_CAPTURE`` format. - .. code-block:: c struct ipu3_uapi_params { diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst index f53e8f57a003..7fcee1c11ac4 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst @@ -190,6 +190,170 @@ component of each pixel in one 16 or 32 bit word. - Cr\ :sub:`2` - Cr\ :sub:`1` - Cr\ :sub:`0` + - + * .. _V4L2-PIX-FMT-AYUV32: + + - ``V4L2_PIX_FMT_AYUV32`` + - 'AYUV' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - Y'\ :sub:`7` + - Y'\ :sub:`6` + - Y'\ :sub:`5` + - Y'\ :sub:`4` + - Y'\ :sub:`3` + - Y'\ :sub:`2` + - Y'\ :sub:`1` + - Y'\ :sub:`0` + + - Cb\ :sub:`7` + - Cb\ :sub:`6` + - Cb\ :sub:`5` + - Cb\ :sub:`4` + - Cb\ :sub:`3` + - Cb\ :sub:`2` + - Cb\ :sub:`1` + - Cb\ :sub:`0` + + - Cr\ :sub:`7` + - Cr\ :sub:`6` + - Cr\ :sub:`5` + - Cr\ :sub:`4` + - Cr\ :sub:`3` + - Cr\ :sub:`2` + - Cr\ :sub:`1` + - Cr\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XYUV32: + + - ``V4L2_PIX_FMT_XYUV32`` + - 'XYUV' + + - + - + - + - + - + - + - + - + + - Y'\ :sub:`7` + - Y'\ :sub:`6` + - Y'\ :sub:`5` + - Y'\ :sub:`4` + - Y'\ :sub:`3` + - Y'\ :sub:`2` + - Y'\ :sub:`1` + - Y'\ :sub:`0` + + - Cb\ :sub:`7` + - Cb\ :sub:`6` + - Cb\ :sub:`5` + - Cb\ :sub:`4` + - Cb\ :sub:`3` + - Cb\ :sub:`2` + - Cb\ :sub:`1` + - Cb\ :sub:`0` + + - Cr\ :sub:`7` + - Cr\ :sub:`6` + - Cr\ :sub:`5` + - Cr\ :sub:`4` + - Cr\ :sub:`3` + - Cr\ :sub:`2` + - Cr\ :sub:`1` + - Cr\ :sub:`0` + - + * .. _V4L2-PIX-FMT-VUYA32: + + - ``V4L2_PIX_FMT_VUYA32`` + - 'VUYA' + + - Cr\ :sub:`7` + - Cr\ :sub:`6` + - Cr\ :sub:`5` + - Cr\ :sub:`4` + - Cr\ :sub:`3` + - Cr\ :sub:`2` + - Cr\ :sub:`1` + - Cr\ :sub:`0` + + - Cb\ :sub:`7` + - Cb\ :sub:`6` + - Cb\ :sub:`5` + - Cb\ :sub:`4` + - Cb\ :sub:`3` + - Cb\ :sub:`2` + - Cb\ :sub:`1` + - Cb\ :sub:`0` + + - Y'\ :sub:`7` + - Y'\ :sub:`6` + - Y'\ :sub:`5` + - Y'\ :sub:`4` + - Y'\ :sub:`3` + - Y'\ :sub:`2` + - Y'\ :sub:`1` + - Y'\ :sub:`0` + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - + * .. _V4L2-PIX-FMT-VUYX32: + + - ``V4L2_PIX_FMT_VUYX32`` + - 'VUYX' + + - Cr\ :sub:`7` + - Cr\ :sub:`6` + - Cr\ :sub:`5` + - Cr\ :sub:`4` + - Cr\ :sub:`3` + - Cr\ :sub:`2` + - Cr\ :sub:`1` + - Cr\ :sub:`0` + + - Cb\ :sub:`7` + - Cb\ :sub:`6` + - Cb\ :sub:`5` + - Cb\ :sub:`4` + - Cb\ :sub:`3` + - Cb\ :sub:`2` + - Cb\ :sub:`1` + - Cb\ :sub:`0` + + - Y'\ :sub:`7` + - Y'\ :sub:`6` + - Y'\ :sub:`5` + - Y'\ :sub:`4` + - Y'\ :sub:`3` + - Y'\ :sub:`2` + - Y'\ :sub:`1` + - Y'\ :sub:`0` + + - + - + - + - + - + - + - + - .. raw:: latex @@ -202,4 +366,8 @@ component of each pixel in one 16 or 32 bit word. #) The value of a = alpha bits is undefined when reading from the driver, ignored when writing to the driver, except when alpha blending has been negotiated for a :ref:`Video Overlay <overlay>` or - :ref:`Video Output Overlay <osd>`. + :ref:`Video Output Overlay <osd>` for the formats Y444, YUV555 and + YUV4. However, for formats AYUV32 and VUYA32, the alpha component is + expected to contain a meaningful value that can be used by drivers + and applications. And, the formats XYUV32 and VUYX32 contain undefined + alpha values that must be ignored by all applications and drivers. diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index ff4b2a972fd2..f5440d55d510 100644 --- a/Documentation/media/uapi/v4l/subdev-formats.rst +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -75,15 +75,15 @@ Media Bus Pixel Codes --------------------- The media bus pixel codes describe image formats as flowing over -physical busses (both between separate physical components and inside +physical buses (both between separate physical components and inside SoC devices). This should not be confused with the V4L2 pixel formats that describe, using four character codes, image formats as stored in memory. -While there is a relationship between image formats on busses and image +While there is a relationship between image formats on buses and image formats in memory (a raw Bayer image won't be magically converted to JPEG just by storing it to memory), there is no one-to-one -correspondance between them. +correspondence between them. Packed RGB Formats diff --git a/Documentation/media/uapi/v4l/vidioc-g-parm.rst b/Documentation/media/uapi/v4l/vidioc-g-parm.rst index 0d2593176c90..d9d5d97848d3 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-parm.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-parm.rst @@ -213,7 +213,7 @@ union holding separate parameters for input and output devices. .. _parm-caps: -.. flat-table:: Streaming Parameters Capabilites +.. flat-table:: Streaming Parameters Capabilities :header-rows: 0 :stub-columns: 0 :widths: 3 1 4 diff --git a/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst index 60986710967b..7c6b5f4e1011 100644 --- a/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst +++ b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst @@ -43,10 +43,7 @@ Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to pass ownership of the buffer to the driver before actually enqueuing it, using the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl, and to prepare it for future I/O. Such preparations may include cache invalidation or cleaning. Performing them -in advance saves time during the actual I/O. In case such cache -operations are not required, the application can use one of -``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` and -``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` flags to skip the respective step. +in advance saves time during the actual I/O. The struct :c:type:`v4l2_buffer` structure is specified in :ref:`buffer`. diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst index 3259168a7358..c138d149faea 100644 --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -123,7 +123,7 @@ then ``EINVAL`` will be returned. :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS` the check for this will be reset. - For :ref:`memory-to-memory devices <codec>` you can specify the + For :ref:`memory-to-memory devices <mem2mem>` you can specify the ``request_fd`` only for output buffers, not for capture buffers. Attempting to specify this for a capture buffer will result in an ``EACCES`` error. diff --git a/Documentation/media/v4l-drivers/bttv.rst b/Documentation/media/v4l-drivers/bttv.rst index d72a0f8fd267..f956ee264099 100644 --- a/Documentation/media/v4l-drivers/bttv.rst +++ b/Documentation/media/v4l-drivers/bttv.rst @@ -85,7 +85,7 @@ same card listens there is much higher... For problems with sound: There are a lot of different systems used for TV sound all over the world. And there are also different chips which decode the audio signal. Reports about sound problems ("stereo -does'nt work") are pretty useless unless you include some details +doesn't work") are pretty useless unless you include some details about your hardware and the TV sound scheme used in your country (or at least the country you are living in). @@ -771,7 +771,7 @@ Identifying: - Lifeview.com.tw states (Feb. 2002): "The FlyVideo2000 and FlyVideo2000s product name have renamed to FlyVideo98." Their Bt8x8 cards are listed as discontinued. - - Flyvideo 2000S was probably sold as Flyvideo 3000 in some contries(Europe?). + - Flyvideo 2000S was probably sold as Flyvideo 3000 in some countries(Europe?). The new Flyvideo 2000/3000 are SAA7130/SAA7134 based. "Flyvideo II" had been the name for the 848 cards, nowadays (in Germany) diff --git a/Documentation/media/v4l-drivers/imx.rst b/Documentation/media/v4l-drivers/imx.rst index 6922dde4a82b..1d7eb8c7bd5c 100644 --- a/Documentation/media/v4l-drivers/imx.rst +++ b/Documentation/media/v4l-drivers/imx.rst @@ -24,12 +24,12 @@ memory. Various dedicated DMA channels exist for both video capture and display paths. During transfer, the IDMAC is also capable of vertical image flip, 8x8 block transfer (see IRT description), pixel component re-ordering (for example UYVY to YUYV) within the same colorspace, and -even packed <--> planar conversion. It can also perform a simple -de-interlacing by interleaving even and odd lines during transfer +packed <--> planar conversion. The IDMAC can also perform a simple +de-interlacing by interweaving even and odd lines during transfer (without motion compensation which requires the VDIC). The CSI is the backend capture unit that interfaces directly with -camera sensors over Parallel, BT.656/1120, and MIPI CSI-2 busses. +camera sensors over Parallel, BT.656/1120, and MIPI CSI-2 buses. The IC handles color-space conversion, resizing (downscaling and upscaling), horizontal flip, and 90/270 degree rotation operations. @@ -175,15 +175,21 @@ via the SMFC and an IDMAC channel, bypassing IC pre-processing. This source pad is routed to a capture device node, with a node name of the format "ipuX_csiY capture". -Note that since the IDMAC source pad makes use of an IDMAC channel, it -can do pixel reordering within the same colorspace. For example, the -sink pad can take UYVY2X8, but the IDMAC source pad can output YUYV2X8. -If the sink pad is receiving YUV, the output at the capture device can -also be converted to a planar YUV format such as YUV420. - -It will also perform simple de-interlace without motion compensation, -which is activated if the sink pad's field type is an interlaced type, -and the IDMAC source pad field type is set to none. +Note that since the IDMAC source pad makes use of an IDMAC channel, +pixel reordering within the same colorspace can be carried out by the +IDMAC channel. For example, if the CSI sink pad is receiving in UYVY +order, the capture device linked to the IDMAC source pad can capture +in YUYV order. Also, if the CSI sink pad is receiving a packed YUV +format, the capture device can capture a planar YUV format such as +YUV420. + +The IDMAC channel at the IDMAC source pad also supports simple +interweave without motion compensation, which is activated if the source +pad's field type is sequential top-bottom or bottom-top, and the +requested capture interface field type is set to interlaced (t-b, b-t, +or unqualified interlaced). The capture interface will enforce the same +field order as the source pad field order (interlaced-bt if source pad +is seq-bt, interlaced-tb if source pad is seq-tb). This subdev can generate the following event when enabling the second IDMAC source pad: @@ -201,7 +207,7 @@ The CSI supports cropping the incoming raw sensor frames. This is implemented in the ipuX_csiY entities at the sink pad, using the crop selection subdev API. -The CSI also supports fixed divide-by-two downscaling indepently in +The CSI also supports fixed divide-by-two downscaling independently in width and height. This is implemented in the ipuX_csiY entities at the sink pad, using the compose selection subdev API. @@ -325,14 +331,14 @@ ipuX_vdic The VDIC carries out motion compensated de-interlacing, with three motion compensation modes: low, medium, and high motion. The mode is -specified with the menu control V4L2_CID_DEINTERLACING_MODE. It has -two sink pads and a single source pad. +specified with the menu control V4L2_CID_DEINTERLACING_MODE. The VDIC +has two sink pads and a single source pad. The direct sink pad receives from an ipuX_csiY direct pad. With this link the VDIC can only operate in high motion mode. When the IDMAC sink pad is activated, it receives from an output -or mem2mem device node. With this pipeline, it can also operate +or mem2mem device node. With this pipeline, the VDIC can also operate in low and medium modes, because these modes require receiving frames from memory buffers. Note that an output or mem2mem device is not implemented yet, so this sink pad currently has no links. @@ -345,8 +351,8 @@ ipuX_ic_prp This is the IC pre-processing entity. It acts as a router, routing data from its sink pad to one or both of its source pads. -It has a single sink pad. The sink pad can receive from the ipuX_csiY -direct pad, or from ipuX_vdic. +This entity has a single sink pad. The sink pad can receive from the +ipuX_csiY direct pad, or from ipuX_vdic. This entity has two source pads. One source pad routes to the pre-process encode task entity (ipuX_ic_prpenc), the other to the @@ -369,8 +375,8 @@ color-space conversion, resizing (downscaling and upscaling), horizontal and vertical flip, and 90/270 degree rotation. Flip and rotation are provided via standard V4L2 controls. -Like the ipuX_csiY IDMAC source, it can also perform simple de-interlace -without motion compensation, and pixel reordering. +Like the ipuX_csiY IDMAC source, this entity also supports simple +de-interlace without motion compensation, and pixel reordering. ipuX_ic_prpvf ------------- @@ -380,18 +386,18 @@ pad from ipuX_ic_prp, and a single source pad. The source pad is routed to a capture device node, with a node name of the format "ipuX_ic_prpvf capture". -It is identical in operation to ipuX_ic_prpenc, with the same resizing -and CSC operations and flip/rotation controls. It will receive and -process de-interlaced frames from the ipuX_vdic if ipuX_ic_prp is +This entity is identical in operation to ipuX_ic_prpenc, with the same +resizing and CSC operations and flip/rotation controls. It will receive +and process de-interlaced frames from the ipuX_vdic if ipuX_ic_prp is receiving from ipuX_vdic. -Like the ipuX_csiY IDMAC source, it can perform simple de-interlace -without motion compensation. However, note that if the ipuX_vdic is -included in the pipeline (ipuX_ic_prp is receiving from ipuX_vdic), -it's not possible to use simple de-interlace in ipuX_ic_prpvf, since -the ipuX_vdic has already carried out de-interlacing (with motion -compensation) and therefore the field type output from ipuX_ic_prp can -only be none. +Like the ipuX_csiY IDMAC source, this entity supports simple +interweaving without motion compensation. However, note that if the +ipuX_vdic is included in the pipeline (ipuX_ic_prp is receiving from +ipuX_vdic), it's not possible to use interweave in ipuX_ic_prpvf, +since the ipuX_vdic has already carried out de-interlacing (with +motion compensation) and therefore the field type output from +ipuX_vdic can only be none (progressive). Capture Pipelines ----------------- @@ -516,10 +522,33 @@ On the SabreAuto, an on-board ADV7180 SD decoder is connected to the parallel bus input on the internal video mux to IPU1 CSI0. The following example configures a pipeline to capture from the ADV7180 -video decoder, assuming NTSC 720x480 input signals, with Motion -Compensated de-interlacing. Pad field types assume the adv7180 outputs -"interlaced". $outputfmt can be any format supported by the ipu1_ic_prpvf -entity at its output pad: +video decoder, assuming NTSC 720x480 input signals, using simple +interweave (unconverted and without motion compensation). The adv7180 +must output sequential or alternating fields (field type 'seq-bt' for +NTSC, or 'alternate'): + +.. code-block:: none + + # Setup links + media-ctl -l "'adv7180 3-0021':0 -> 'ipu1_csi0_mux':1[1]" + media-ctl -l "'ipu1_csi0_mux':2 -> 'ipu1_csi0':0[1]" + media-ctl -l "'ipu1_csi0':2 -> 'ipu1_csi0 capture':0[1]" + # Configure pads + media-ctl -V "'adv7180 3-0021':0 [fmt:UYVY2X8/720x480 field:seq-bt]" + media-ctl -V "'ipu1_csi0_mux':2 [fmt:UYVY2X8/720x480]" + media-ctl -V "'ipu1_csi0':2 [fmt:AYUV32/720x480]" + # Configure "ipu1_csi0 capture" interface (assumed at /dev/video4) + v4l2-ctl -d4 --set-fmt-video=field=interlaced_bt + +Streaming can then begin on /dev/video4. The v4l2-ctl tool can also be +used to select any supported YUV pixelformat on /dev/video4. + +This example configures a pipeline to capture from the ADV7180 +video decoder, assuming PAL 720x576 input signals, with Motion +Compensated de-interlacing. The adv7180 must output sequential or +alternating fields (field type 'seq-tb' for PAL, or 'alternate'). +$outputfmt can be any format supported by the ipu1_ic_prpvf entity +at its output pad: .. code-block:: none @@ -531,11 +560,11 @@ entity at its output pad: media-ctl -l "'ipu1_ic_prp':2 -> 'ipu1_ic_prpvf':0[1]" media-ctl -l "'ipu1_ic_prpvf':1 -> 'ipu1_ic_prpvf capture':0[1]" # Configure pads - media-ctl -V "'adv7180 3-0021':0 [fmt:UYVY2X8/720x480]" - media-ctl -V "'ipu1_csi0_mux':2 [fmt:UYVY2X8/720x480 field:interlaced]" - media-ctl -V "'ipu1_csi0':1 [fmt:AYUV32/720x480 field:interlaced]" - media-ctl -V "'ipu1_vdic':2 [fmt:AYUV32/720x480 field:none]" - media-ctl -V "'ipu1_ic_prp':2 [fmt:AYUV32/720x480 field:none]" + media-ctl -V "'adv7180 3-0021':0 [fmt:UYVY2X8/720x576 field:seq-tb]" + media-ctl -V "'ipu1_csi0_mux':2 [fmt:UYVY2X8/720x576]" + media-ctl -V "'ipu1_csi0':1 [fmt:AYUV32/720x576]" + media-ctl -V "'ipu1_vdic':2 [fmt:AYUV32/720x576 field:none]" + media-ctl -V "'ipu1_ic_prp':2 [fmt:AYUV32/720x576 field:none]" media-ctl -V "'ipu1_ic_prpvf':1 [fmt:$outputfmt field:none]" Streaming can then begin on the capture device node at diff --git a/Documentation/media/v4l-drivers/imx7.rst b/Documentation/media/v4l-drivers/imx7.rst new file mode 100644 index 000000000000..fe411f65c01c --- /dev/null +++ b/Documentation/media/v4l-drivers/imx7.rst @@ -0,0 +1,162 @@ +.. SPDX-License-Identifier: GPL-2.0 + +i.MX7 Video Capture Driver +========================== + +Introduction +------------ + +The i.MX7 contrary to the i.MX5/6 family does not contain an Image Processing +Unit (IPU); because of that the capabilities to perform operations or +manipulation of the capture frames are less feature rich. + +For image capture the i.MX7 has three units: +- CMOS Sensor Interface (CSI) +- Video Multiplexer +- MIPI CSI-2 Receiver + +.. code-block:: none + + MIPI Camera Input ---> MIPI CSI-2 --- > |\ + | \ + | \ + | M | + | U | ------> CSI ---> Capture + | X | + | / + Parallel Camera Input ----------------> | / + |/ + +For additional information, please refer to the latest versions of the i.MX7 +reference manual [#f1]_. + +Entities +-------- + +imx7-mipi-csi2 +-------------- + +This is the MIPI CSI-2 receiver entity. It has one sink pad to receive the pixel +data from MIPI CSI-2 camera sensor. It has one source pad, corresponding to the +virtual channel 0. This module is compliant to previous version of Samsung +D-phy, and supports two D-PHY Rx Data lanes. + +csi_mux +------- + +This is the video multiplexer. It has two sink pads to select from either camera +sensor with a parallel interface or from MIPI CSI-2 virtual channel 0. It has +a single source pad that routes to the CSI. + +csi +--- + +The CSI enables the chip to connect directly to external CMOS image sensor. CSI +can interface directly with Parallel and MIPI CSI-2 buses. It has 256 x 64 FIFO +to store received image pixel data and embedded DMA controllers to transfer data +from the FIFO through AHB bus. + +This entity has one sink pad that receives from the csi_mux entity and a single +source pad that routes video frames directly to memory buffers. This pad is +routed to a capture device node. + +Usage Notes +----------- + +To aid in configuration and for backward compatibility with V4L2 applications +that access controls only from video device nodes, the capture device interfaces +inherit controls from the active entities in the current pipeline, so controls +can be accessed either directly from the subdev or from the active capture +device interface. For example, the sensor controls are available either from the +sensor subdevs or from the active capture device. + +Warp7 with OV2680 +----------------- + +On this platform an OV2680 MIPI CSI-2 module is connected to the internal MIPI +CSI-2 receiver. The following example configures a video capture pipeline with +an output of 800x600, and BGGR 10 bit bayer format: + +.. code-block:: none + + # Setup links + media-ctl -l "'ov2680 1-0036':0 -> 'imx7-mipi-csis.0':0[1]" + media-ctl -l "'imx7-mipi-csis.0':1 -> 'csi_mux':1[1]" + media-ctl -l "'csi_mux':2 -> 'csi':0[1]" + media-ctl -l "'csi':1 -> 'csi capture':0[1]" + + # Configure pads for pipeline + media-ctl -V "'ov2680 1-0036':0 [fmt:SBGGR10_1X10/800x600 field:none]" + media-ctl -V "'csi_mux':1 [fmt:SBGGR10_1X10/800x600 field:none]" + media-ctl -V "'csi_mux':2 [fmt:SBGGR10_1X10/800x600 field:none]" + media-ctl -V "'imx7-mipi-csis.0':0 [fmt:SBGGR10_1X10/800x600 field:none]" + media-ctl -V "'csi':0 [fmt:SBGGR10_1X10/800x600 field:none]" + +After this streaming can start. The v4l2-ctl tool can be used to select any of +the resolutions supported by the sensor. + +.. code-block:: none + + root@imx7s-warp:~# media-ctl -p + Media controller API version 4.17.0 + + Media device information + ------------------------ + driver imx-media + model imx-media + serial + bus info + hw revision 0x0 + driver version 4.17.0 + + Device topology + - entity 1: csi (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev0 + pad0: Sink + [fmt:SBGGR10_1X10/800x600 field:none] + <- "csi_mux":2 [ENABLED] + pad1: Source + [fmt:SBGGR10_1X10/800x600 field:none] + -> "csi capture":0 [ENABLED] + + - entity 4: csi capture (1 pad, 1 link) + type Node subtype V4L flags 0 + device node name /dev/video0 + pad0: Sink + <- "csi":1 [ENABLED] + + - entity 10: csi_mux (3 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev1 + pad0: Sink + [fmt:unknown/0x0] + pad1: Sink + [fmt:unknown/800x600 field:none] + <- "imx7-mipi-csis.0":1 [ENABLED] + pad2: Source + [fmt:unknown/800x600 field:none] + -> "csi":0 [ENABLED] + + - entity 14: imx7-mipi-csis.0 (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev2 + pad0: Sink + [fmt:SBGGR10_1X10/800x600 field:none] + <- "ov2680 1-0036":0 [ENABLED] + pad1: Source + [fmt:SBGGR10_1X10/800x600 field:none] + -> "csi_mux":1 [ENABLED] + + - entity 17: ov2680 1-0036 (1 pad, 1 link) + type V4L2 subdev subtype Sensor flags 0 + device node name /dev/v4l-subdev3 + pad0: Source + [fmt:SBGGR10_1X10/800x600 field:none] + -> "imx7-mipi-csis.0":0 [ENABLED] + + +References +---------- + +.. [#f1] https://www.nxp.com/docs/en/reference-manual/IMX7SRM.pdf diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index f28570ec9e42..dfd4b205937c 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -44,6 +44,7 @@ For more details see the file COPYING in the source distribution of Linux. davinci-vpbe fimc imx + imx7 ipu3 ivtv max2175 diff --git a/Documentation/media/v4l-drivers/ipu3.rst b/Documentation/media/v4l-drivers/ipu3.rst index f89b51dafadd..c9f780404eee 100644 --- a/Documentation/media/v4l-drivers/ipu3.rst +++ b/Documentation/media/v4l-drivers/ipu3.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. include:: <isonum.txt> =============================================================== @@ -355,10 +357,157 @@ https://chromium.googlesource.com/chromiumos/platform/arc-camera/+/master/ The source can be located under hal/intel directory. +Overview of IPU3 pipeline +========================= + +IPU3 pipeline has a number of image processing stages, each of which takes a +set of parameters as input. The major stages of pipelines are shown here: + +.. kernel-render:: DOT + :alt: IPU3 ImgU Pipeline + :caption: IPU3 ImgU Pipeline Diagram + + digraph "IPU3 ImgU" { + node [shape=box] + splines="ortho" + rankdir="LR" + + a [label="Raw pixels"] + b [label="Bayer Downscaling"] + c [label="Optical Black Correction"] + d [label="Linearization"] + e [label="Lens Shading Correction"] + f [label="White Balance / Exposure / Focus Apply"] + g [label="Bayer Noise Reduction"] + h [label="ANR"] + i [label="Demosaicing"] + j [label="Color Correction Matrix"] + k [label="Gamma correction"] + l [label="Color Space Conversion"] + m [label="Chroma Down Scaling"] + n [label="Chromatic Noise Reduction"] + o [label="Total Color Correction"] + p [label="XNR3"] + q [label="TNR"] + r [label="DDR"] + + { rank=same; a -> b -> c -> d -> e -> f } + { rank=same; g -> h -> i -> j -> k -> l } + { rank=same; m -> n -> o -> p -> q -> r } + + a -> g -> m [style=invis, weight=10] + + f -> g + l -> m + } + +The table below presents a description of the above algorithms. + +======================== ======================================================= +Name Description +======================== ======================================================= +Optical Black Correction Optical Black Correction block subtracts a pre-defined + value from the respective pixel values to obtain better + image quality. + Defined in :c:type:`ipu3_uapi_obgrid_param`. +Linearization This algo block uses linearization parameters to + address non-linearity sensor effects. The Lookup table + table is defined in + :c:type:`ipu3_uapi_isp_lin_vmem_params`. +SHD Lens shading correction is used to correct spatial + non-uniformity of the pixel response due to optical + lens shading. This is done by applying a different gain + for each pixel. The gain, black level etc are + configured in :c:type:`ipu3_uapi_shd_config_static`. +BNR Bayer noise reduction block removes image noise by + applying a bilateral filter. + See :c:type:`ipu3_uapi_bnr_static_config` for details. +ANR Advanced Noise Reduction is a block based algorithm + that performs noise reduction in the Bayer domain. The + convolution matrix etc can be found in + :c:type:`ipu3_uapi_anr_config`. +DM Demosaicing converts raw sensor data in Bayer format + into RGB (Red, Green, Blue) presentation. Then add + outputs of estimation of Y channel for following stream + processing by Firmware. The struct is defined as + :c:type:`ipu3_uapi_dm_config`. +Color Correction Color Correction algo transforms sensor specific color + space to the standard "sRGB" color space. This is done + by applying 3x3 matrix defined in + :c:type:`ipu3_uapi_ccm_mat_config`. +Gamma correction Gamma correction :c:type:`ipu3_uapi_gamma_config` is a + basic non-linear tone mapping correction that is + applied per pixel for each pixel component. +CSC Color space conversion transforms each pixel from the + RGB primary presentation to YUV (Y: brightness, + UV: Luminance) presentation. This is done by applying + a 3x3 matrix defined in + :c:type:`ipu3_uapi_csc_mat_config` +CDS Chroma down sampling + After the CSC is performed, the Chroma Down Sampling + is applied for a UV plane down sampling by a factor + of 2 in each direction for YUV 4:2:0 using a 4x2 + configurable filter :c:type:`ipu3_uapi_cds_params`. +CHNR Chroma noise reduction + This block processes only the chrominance pixels and + performs noise reduction by cleaning the high + frequency noise. + See struct :c:type:`ipu3_uapi_yuvp1_chnr_config`. +TCC Total color correction as defined in struct + :c:type:`ipu3_uapi_yuvp2_tcc_static_config`. +XNR3 eXtreme Noise Reduction V3 is the third revision of + noise reduction algorithm used to improve image + quality. This removes the low frequency noise in the + captured image. Two related structs are being defined, + :c:type:`ipu3_uapi_isp_xnr3_params` for ISP data memory + and :c:type:`ipu3_uapi_isp_xnr3_vmem_params` for vector + memory. +TNR Temporal Noise Reduction block compares successive + frames in time to remove anomalies / noise in pixel + values. :c:type:`ipu3_uapi_isp_tnr3_vmem_params` and + :c:type:`ipu3_uapi_isp_tnr3_params` are defined for ISP + vector and data memory respectively. +======================== ======================================================= + +Other often encountered acronyms not listed in above table: + + ACC + Accelerator cluster + AWB_FR + Auto white balance filter response statistics + BDS + Bayer downscaler parameters + CCM + Color correction matrix coefficients + IEFd + Image enhancement filter directed + Obgrid + Optical black level compensation + OSYS + Output system configuration + ROI + Region of interest + YDS + Y down sampling + YTM + Y-tone mapping + +A few stages of the pipeline will be executed by firmware running on the ISP +processor, while many others will use a set of fixed hardware blocks also +called accelerator cluster (ACC) to crunch pixel data and produce statistics. + +ACC parameters of individual algorithms, as defined by +:c:type:`ipu3_uapi_acc_param`, can be chosen to be applied by the user +space through struct :c:type:`ipu3_uapi_flags` embedded in +:c:type:`ipu3_uapi_params` structure. For parameters that are configured as +not enabled by the user space, the corresponding structs are ignored by the +driver, in which case the existing configuration of the algorithm will be +preserved. + References ========== -.. [#f5] include/uapi/linux/intel-ipu3.h +.. [#f5] drivers/staging/media/ipu3/include/intel-ipu3.h .. [#f1] https://github.com/intel/nvt diff --git a/Documentation/media/v4l-drivers/pxa_camera.rst b/Documentation/media/v4l-drivers/pxa_camera.rst index e4fbca755e1a..ee1bd96b66dd 100644 --- a/Documentation/media/v4l-drivers/pxa_camera.rst +++ b/Documentation/media/v4l-drivers/pxa_camera.rst @@ -18,7 +18,7 @@ Global video workflow --------------------- a) QCI stopped - Initialy, the QCI interface is stopped. + Initially, the QCI interface is stopped. When a buffer is queued (pxa_videobuf_ops->buf_queue), the QCI starts. b) QCI started diff --git a/Documentation/media/v4l-drivers/qcom_camss.rst b/Documentation/media/v4l-drivers/qcom_camss.rst index 6b15385b12b3..a72e17d09cb7 100644 --- a/Documentation/media/v4l-drivers/qcom_camss.rst +++ b/Documentation/media/v4l-drivers/qcom_camss.rst @@ -123,7 +123,7 @@ The considerations to split the driver in this particular way are as follows: - representing CSIPHY and CSID modules by a separate sub-device for each module allows to model the hardware links between these modules; - representing VFE by a separate sub-devices for each input interface allows - to use the input interfaces concurently and independently as this is + to use the input interfaces concurrently and independently as this is supported by the hardware; - representing ISPIF by a number of sub-devices equal to the number of CSID sub-devices allows to create linear media controller pipelines when using two |