diff options
Diffstat (limited to 'Documentation/media')
69 files changed, 5665 insertions, 4858 deletions
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/index.rst b/Documentation/media/index.rst index 0a222fc1d7ca..0301c25ff887 100644 --- a/Documentation/media/index.rst +++ b/Documentation/media/index.rst @@ -18,7 +18,7 @@ Linux Media Subsystem Documentation v4l-drivers/index cec-drivers/index -.. only:: subproject +.. only:: html and subproject Indices ======= 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..05bba0b61748 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 @@ -259,6 +259,45 @@ Subsystems should facilitate link validation by providing subsystem specific helper functions to provide easy access for commonly needed information, and in the end provide a way to use driver-specific callbacks. +Media Controller Device Allocator API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the media device belongs to more than one driver, the shared media +device is allocated with the shared struct device as the key for look ups. + +The shared media device should stay in registered state until the last +driver unregisters it. In addition, the media device should be released when +all the references are released. Each driver gets a reference to the media +device during probe, when it allocates the media device. If media device is +already allocated, the allocate API bumps up the refcount and returns the +existing media device. The driver puts the reference back in its disconnect +routine when it calls :c:func:`media_device_delete()`. + +The media device is unregistered and cleaned up from the kref put handler to +ensure that the media device stays in registered state until the last driver +unregisters the media device. + +**Driver Usage** + +Drivers should use the appropriate media-core routines to manage the shared +media device life-time handling the two states: +1. allocate -> register -> delete +2. get reference to already registered device -> delete + +call :c:func:`media_device_delete()` routine to make sure the shared media +device delete is handled correctly. + +**driver probe:** +Call :c:func:`media_device_usb_allocate()` to allocate or get a reference +Call :c:func:`media_device_register()`, if media devnode isn't registered + +**driver disconnect:** +Call :c:func:`media_device_delete()` to free the media_device. Freeing is +handled by the kref put handler. + +API Definitions +^^^^^^^^^^^^^^^ + .. kernel-doc:: include/media/media-device.h .. kernel-doc:: include/media/media-devnode.h @@ -266,3 +305,5 @@ in the end provide a way to use driver-specific callbacks. .. kernel-doc:: include/media/media-entity.h .. kernel-doc:: include/media/media-request.h + +.. kernel-doc:: include/media/media-dev-allocator.h 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..ac768d769113 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -60,6 +60,10 @@ 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 +ignore symbol RC_PROTO_XBOX_DVD # 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..a74c82d95609 100644 --- a/Documentation/media/uapi/mediactl/request-api.rst +++ b/Documentation/media/uapi/mediactl/request-api.rst @@ -91,9 +91,9 @@ 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. + to a request will result in an ``EBADR`` error. If the request contains configurations for multiple entities, individual drivers may synchronize so the requested pipeline's topology is applied before the @@ -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..177ac44fa0fa 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 @@ -623,7 +623,7 @@ the remote via /dev/input/event devices. - .. row 78 - - ``KEY_SCREEN`` + - ``KEY_ASPECT_RATIO`` - Select screen aspect ratio @@ -631,7 +631,7 @@ the remote via /dev/input/event devices. - .. row 79 - - ``KEY_ZOOM`` + - ``KEY_FULL_SCREEN`` - Put device into zoom/full screen mode diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst index 86878bb0087f..1cbd9cde57f3 100644 --- a/Documentation/media/uapi/v4l/buffer.rst +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -165,7 +165,7 @@ of appropriately sized buffers for each use case). struct v4l2_buffer ================== -.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.3cm}|p{10.5cm}| +.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.6cm}|p{10.2cm}| .. cssclass:: longtable @@ -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 @@ -327,7 +326,7 @@ struct v4l2_buffer Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls other than :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. - If the device does not support requests, then ``EACCES`` will be returned. + If the device does not support requests, then ``EBADR`` will be returned. If requests are supported but an invalid request file descriptor is given, then ``EINVAL`` will be returned. @@ -421,7 +420,7 @@ enum v4l2_buf_type .. cssclass:: longtable -.. tabularcolumns:: |p{7.2cm}|p{0.6cm}|p{9.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{9.1cm}| .. flat-table:: :header-rows: 0 @@ -483,7 +482,11 @@ enum v4l2_buf_type Buffer Flags ============ -.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| .. cssclass:: longtable @@ -682,6 +685,9 @@ Buffer Flags exposure of the frame has begun. This is only valid for the ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. +.. raw:: latex + + \normalsize .. c:type:: v4l2_memory @@ -689,7 +695,7 @@ Buffer Flags enum v4l2_memory ================ -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.7cm}| .. flat-table:: :header-rows: 0 @@ -714,10 +720,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 @@ -725,7 +731,7 @@ struct :c:type:`timeval` timestamps are stored in struct struct v4l2_timecode -------------------- -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{12.3cm}| .. flat-table:: :header-rows: 0 @@ -762,7 +768,7 @@ struct v4l2_timecode Timecode Types -------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.8cm}|p{11.1cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/colorspaces-defs.rst b/Documentation/media/uapi/v4l/colorspaces-defs.rst index c4e8fc620379..e122bbe3d799 100644 --- a/Documentation/media/uapi/v4l/colorspaces-defs.rst +++ b/Documentation/media/uapi/v4l/colorspaces-defs.rst @@ -39,7 +39,7 @@ whole range, 0-255, dividing the angular value by 1.41. The enum colorspaces except for BT.2020 which uses limited range R'G'B' quantization. -.. tabularcolumns:: |p{6.0cm}|p{11.5cm}| +.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| .. c:type:: v4l2_colorspace @@ -112,7 +112,7 @@ whole range, 0-255, dividing the angular value by 1.41. The enum .. c:type:: v4l2_ycbcr_encoding -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| +.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| .. flat-table:: V4L2 Y'CbCr Encodings :header-rows: 1 diff --git a/Documentation/media/uapi/v4l/colorspaces.rst b/Documentation/media/uapi/v4l/colorspaces.rst index c5a560f0c13d..4f6c82fa057f 100644 --- a/Documentation/media/uapi/v4l/colorspaces.rst +++ b/Documentation/media/uapi/v4l/colorspaces.rst @@ -56,9 +56,9 @@ The Y value in the CIE XYZ colorspace corresponds to luminance. Often the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace: -x = X / (X + Y + Z) + x = X / (X + Y + Z) -y = Y / (X + Y + Z) + y = Y / (X + Y + Z) The x and y values are the chromaticity coordinates and can be used to define a color without the luminance component Y. It is very confusing 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-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst index d6a707f0b24f..e06b03ca2ab2 100644 --- a/Documentation/media/uapi/v4l/dev-raw-vbi.rst +++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst @@ -106,7 +106,7 @@ VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. -.. tabularcolumns:: |p{2.4cm}|p{4.4cm}|p{10.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.7cm}| .. c:type:: v4l2_vbi_format @@ -190,7 +190,7 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does applications must set it to zero. -.. tabularcolumns:: |p{4.0cm}|p{1.5cm}|p{12.0cm}| +.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.6cm}| .. _vbifmt-flags: diff --git a/Documentation/media/uapi/v4l/dev-rds.rst b/Documentation/media/uapi/v4l/dev-rds.rst index 624d6f95b842..64a724ef58f5 100644 --- a/Documentation/media/uapi/v4l/dev-rds.rst +++ b/Documentation/media/uapi/v4l/dev-rds.rst @@ -146,7 +146,7 @@ RDS datastructures .. _v4l2-rds-block-codes: -.. tabularcolumns:: |p{5.6cm}|p{2.0cm}|p{1.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| .. flat-table:: Block defines :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/dev-sliced-vbi.rst b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst index 0aa6cb8a272b..e86346f66017 100644 --- a/Documentation/media/uapi/v4l/dev-sliced-vbi.rst +++ b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst @@ -118,7 +118,7 @@ struct v4l2_sliced_vbi_format \scriptsize \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{.75cm}|p{3.3cm}|p{3.4cm}|p{3.4cm}|p{3.4cm}| +.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.4cm}|p{4.4cm}|p{4.4cm}| .. cssclass:: longtable @@ -223,7 +223,7 @@ Sliced VBI services .. raw:: latex - \footnotesize + \scriptsize .. tabularcolumns:: |p{4.1cm}|p{1.1cm}|p{2.4cm}|p{2.0cm}|p{7.3cm}| @@ -541,7 +541,7 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 ------------------------------------------------- -.. tabularcolumns:: |p{4.9cm}|p{2.4cm}|p{10.2cm}| +.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| .. flat-table:: :header-rows: 0 @@ -561,12 +561,12 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 :: - linemask[0] b0: line 6 first field - linemask[0] b17: line 23 first field - linemask[0] b18: line 6 second field - linemask[0] b31: line 19 second field - linemask[1] b0: line 20 second field - linemask[1] b3: line 23 second field + linemask[0] b0: line 6 first field + linemask[0] b17: line 23 first field + linemask[0] b18: line 6 second field + linemask[0] b31: line 19 second field + linemask[1] b0: line 20 second field + linemask[1] b3: line 23 second field linemask[1] b4-b31: unused and set to 0 * - struct :c:type:`v4l2_mpeg_vbi_itv0_line` @@ -590,7 +590,7 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 struct v4l2_mpeg_vbi_ITV0 ------------------------- -.. tabularcolumns:: |p{4.9cm}|p{4.4cm}|p{8.2cm}| +.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| .. flat-table:: :header-rows: 0 @@ -635,7 +635,7 @@ struct v4l2_mpeg_vbi_itv0_line Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field ------------------------------------------------------------ -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| .. flat-table:: :header-rows: 1 diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst index 2c2768c7343b..029bb2d9928a 100644 --- a/Documentation/media/uapi/v4l/dev-subdev.rst +++ b/Documentation/media/uapi/v4l/dev-subdev.rst @@ -211,7 +211,7 @@ list entity names and pad numbers). .. raw:: latex - \tiny + \scriptsize .. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}| @@ -223,40 +223,80 @@ list entity names and pad numbers). :widths: 5 5 5 5 5 5 5 * - - - Sensor/0 format - - Frontend/0 format - - Frontend/1 format - - Scaler/0 format - - Scaler/0 compose selection rectangle - - Scaler/1 format + - Sensor/0 + + format + - Frontend/0 + + format + - Frontend/1 + + format + - Scaler/0 + + format + - Scaler/0 + + compose selection rectangle + - Scaler/1 + + format * - Initial state - - 2048x1536/SGRBG8_1X8 + - 2048x1536 + + SGRBG8_1X8 - (default) - (default) - (default) - (default) - (default) * - Configure frontend sink format - - 2048x1536/SGRBG8_1X8 - - *2048x1536/SGRBG8_1X8* - - *2046x1534/SGRBG8_1X8* + - 2048x1536 + + SGRBG8_1X8 + - *2048x1536* + + *SGRBG8_1X8* + - *2046x1534* + + *SGRBG8_1X8* - (default) - (default) - (default) * - Configure scaler sink format - - 2048x1536/SGRBG8_1X8 - - 2048x1536/SGRBG8_1X8 - - 2046x1534/SGRBG8_1X8 - - *2046x1534/SGRBG8_1X8* + - 2048x1536 + + SGRBG8_1X8 + - 2048x1536 + + SGRBG8_1X8 + - 2046x1534 + + SGRBG8_1X8 + - *2046x1534* + + *SGRBG8_1X8* - *0,0/2046x1534* - - *2046x1534/SGRBG8_1X8* + - *2046x1534* + + *SGRBG8_1X8* * - Configure scaler sink compose selection - - 2048x1536/SGRBG8_1X8 - - 2048x1536/SGRBG8_1X8 - - 2046x1534/SGRBG8_1X8 - - 2046x1534/SGRBG8_1X8 + - 2048x1536 + + SGRBG8_1X8 + - 2048x1536 + + SGRBG8_1X8 + - 2046x1534 + + SGRBG8_1X8 + - 2046x1534 + + SGRBG8_1X8 - *0,0/1280x960* - - *1280x960/SGRBG8_1X8* + - *1280x960* + + *SGRBG8_1X8* .. raw:: latex 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..51c1d5c9eb00 --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst @@ -0,0 +1,515 @@ +.. 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.7cm}|p{8.8cm}| + +.. 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.7cm}|p{10.8cm}| + +.. 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.8cm}|p{10.7cm}| + +.. 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.2 cm}|p{10.3cm}| + +.. 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: + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.9cm}|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. + +.. raw:: latex + + \normalsize + + +``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..4a8446203085 --- /dev/null +++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst @@ -0,0 +1,2668 @@ +.. 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.6 cm}|p{10.9cm}| + +.. 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.8cm}|p{7.7cm}| + +.. 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{9.6cm}|p{7.9cm}| + +.. 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: + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{13.6cm}|p{3.9cm}| + +.. 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. + +.. raw:: latex + + \normalsize + + +``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: + + +.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| + + +.. 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_H264_I_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the H264 I frame to limit I frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the H264 I frame to limit I frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the H264 P frame to limit P frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the H264 P frame to limit P frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``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: + +.. raw:: latex + + \small + +.. 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. + +.. raw:: latex + + \normalsize + + +``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: + +.. raw:: latex + + \small + +.. 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. + +.. raw:: latex + + \normalsize + + + +``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: + +.. raw:: latex + + \small + +.. 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. + +.. raw:: latex + + \normalsize + + + +``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 + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. 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 + +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + +.. 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 + +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + +.. 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 + +.. tabularcolumns:: |p{1.2cm}|p{8.0cm}|p{7.4cm}| + +.. raw:: latex + + \small + +.. 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. + +``V4L2_CID_FWHT_I_FRAME_QP (integer)`` + Quantization parameter for an I frame for FWHT. Valid range: from 1 + to 31. + +``V4L2_CID_FWHT_P_FRAME_QP (integer)`` + Quantization parameter for a P frame for FWHT. Valid range: from 1 + to 31. + +.. raw:: latex + + \normalsize + + +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.2cm}|p{8.3cm}| + +.. raw:: latex + + \small + +.. 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. + +.. raw:: latex + + \normalsize + +``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: + +.. tabularcolumns:: |p{9.5cm}|p{8.0cm}| + +.. 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. + + +.. _v4l2-mpeg-fwht: + +``V4L2_CID_MPEG_VIDEO_FWHT_PARAMS (struct)`` + Specifies the fwht parameters (as extracted from the bitstream) for the + associated FWHT data. This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for FWHT. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_fwht_params + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| + +.. flat-table:: struct v4l2_ctrl_fwht_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with 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. + * - __u32 + - ``version`` + - The version of the codec + * - __u32 + - ``width`` + - The width of the frame + * - __u32 + - ``height`` + - The height of the frame + * - __u32 + - ``flags`` + - The flags of the frame, see :ref:`fwht-flags`. + * - __u32 + - ``colorspace`` + - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. + * - __u32 + - ``xfer_func`` + - The transfer function, from enum :c:type:`v4l2_xfer_func`. + * - __u32 + - ``ycbcr_enc`` + - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. + * - __u32 + - ``quantization`` + - The quantization range, from enum :c:type:`v4l2_quantization`. + + + +.. _fwht-flags: + +FWHT Flags +============ + +.. cssclass:: longtable + +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``FWHT_FL_IS_INTERLACED`` + - 0x00000001 + - Set if this is an interlaced format + * - ``FWHT_FL_IS_BOTTOM_FIRST`` + - 0x00000002 + - Set if this is a bottom-first (NTSC) interlaced format + * - ``FWHT_FL_IS_ALTERNATE`` + - 0x00000004 + - Set if each 'frame' contains just one field + * - ``FWHT_FL_IS_BOTTOM_FIELD`` + - 0x00000008 + - If FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the + bottom field, else it is the top field. + * - ``FWHT_FL_LUMA_IS_UNCOMPRESSED`` + - 0x00000010 + - Set if the luma plane is uncompressed + * - ``FWHT_FL_CB_IS_UNCOMPRESSED`` + - 0x00000020 + - Set if the cb plane is uncompressed + * - ``FWHT_FL_CR_IS_UNCOMPRESSED`` + - 0x00000040 + - Set if the cr plane is uncompressed + * - ``FWHT_FL_CHROMA_FULL_HEIGHT`` + - 0x00000080 + - Set if the chroma plane has the same height as the luma plane, + else the chroma plane is half the height of the luma plane + * - ``FWHT_FL_CHROMA_FULL_WIDTH`` + - 0x00000100 + - Set if the chroma plane has the same width as the luma plane, + else the chroma plane is half the width of the luma plane + * - ``FWHT_FL_ALPHA_IS_UNCOMPRESSED`` + - 0x00000200 + - Set if the alpha plane is uncompressed + * - ``FWHT_FL_I_FRAME`` + - 0x00000400 + - Set if this is an I-frame + * - ``FWHT_FL_COMPONENTS_NUM_MSK`` + - 0x00070000 + - A 4-values flag - the number of components - 1 + * - ``FWHT_FL_PIXENC_YUV`` + - 0x00080000 + - Set if the pixel encoding is YUV + * - ``FWHT_FL_PIXENC_RGB`` + - 0x00100000 + - Set if the pixel encoding is RGB + * - ``FWHT_FL_PIXENC_HSV`` + - 0x00180000 + - Set if the pixel encoding is HSV + + +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}| + +.. raw:: latex + + \small + +.. 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 + +.. raw:: latex + + \normalsize + + + +.. _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: + + +.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| + +.. 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}| + +.. raw:: latex + + \small + +.. 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. + +.. raw:: latex + + \normalsize + + + +``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 + + \scriptsize + +.. 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{12.1cm}|p{5.4cm}| + +.. 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..80981d0cff42 --- /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.7cm}|p{9.8cm}| + +.. 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..5c70ac98f710 --- /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.3cm}|p{10.4cm}| + +.. 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..eff056b17167 --- /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.5cm}|p{10.0cm}| + +.. 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.4cm}|p{9.1cm}| + +.. 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..60ce3f949319 --- /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.5cm}|p{10.0cm}| + +.. 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/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index 8415268d439c..d640e922a974 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -64,7 +64,9 @@ enum v4l2_field .. c:type:: v4l2_field -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{11.1cm}| + +.. cssclass:: longtable .. flat-table:: :header-rows: 0 @@ -73,12 +75,11 @@ enum v4l2_field * - ``V4L2_FIELD_ANY`` - 0 - - Applications request this field order when any one of the - ``V4L2_FIELD_NONE``, ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``, or - ``V4L2_FIELD_INTERLACED`` formats is acceptable. Drivers choose - depending on hardware capabilities or e. g. the requested image - size, and return the actual field order. Drivers must never return - ``V4L2_FIELD_ANY``. If multiple field orders are possible the + - Applications request this field order when any field format + is acceptable. Drivers choose depending on hardware capabilities or + e.g. the requested image size, and return the actual field order. + Drivers must never return ``V4L2_FIELD_ANY``. + If multiple field orders are possible the driver must choose one of the possible field orders during :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct @@ -86,9 +87,8 @@ enum v4l2_field ``V4L2_FIELD_ANY``. * - ``V4L2_FIELD_NONE`` - 1 - - Images are in progressive format, not interlaced. The driver may - also indicate this order when it cannot distinguish between - ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``. + - Images are in progressive (frame-based) format, not interlaced + (field-based). * - ``V4L2_FIELD_TOP`` - 2 - Images consist of the top (aka odd) field only. 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..6c961cfb74da 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 @@ -125,3 +125,9 @@ Compressed Formats - Video elementary stream using a codec based on the Fast Walsh Hadamard Transform. This codec is implemented by the vicodec ('Virtual Codec') driver. See the codec-fwht.h header for more details. + * .. _V4L2-PIX-FMT-FWHT-STATELESS: + + - ``V4L2_PIX_FMT_FWHT_STATELESS`` + - 'SFWH' + - Same format as V4L2_PIX_FMT_FWHT but requires stateless codec implementation. + See the :ref:`associated Codec Control IDs <v4l2-mpeg-fwht>`. diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst b/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst index 862e1f327150..87e8fd7d5d02 100644 --- a/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst +++ b/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst @@ -36,13 +36,16 @@ per frame, therefore their headers cannot be larger than 255 bytes. Below are proprietary Microsoft style metadata types, used by D4xx cameras, where all fields are in little endian order: +.. tabularcolumns:: |p{5.0cm}|p{12.5cm}| + + .. flat-table:: D4xx metadata - :widths: 1 4 + :widths: 1 2 :header-rows: 1 :stub-columns: 0 - * - Field - - Description + * - **Field** + - **Description** * - :cspan:`1` *Depth Control* * - __u32 ID - 0x80000000 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-meta-vsp1-hgt.rst b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst index 2ebccdcca95d..d1a341af9c48 100644 --- a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst +++ b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst @@ -41,6 +41,10 @@ The Hue position **m** (0 - 5) of the bucket in the matrix depends on how the HGT Hue areas are configured. There are 6 user configurable Hue Areas which can be configured to cover overlapping Hue values: +.. raw:: latex + + \small + :: Area 0 Area 1 Area 2 Area 3 Area 4 Area 5 @@ -53,6 +57,11 @@ Areas which can be configured to cover overlapping Hue values: 5U 0L 0U 1L 1U 2L 2U 3L 3U 4L 4U 5L 5U 0L <0..............................Hue Value............................255> + +.. raw:: latex + + \normalsize + When two consecutive areas don't overlap (n+1L is equal to nU) the boundary value is considered as part of the lower area. diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst index 38b1895a509f..dfc4a8367b3d 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst @@ -31,7 +31,7 @@ The values are packed in 24 or 32 bit formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.0cm}|p{0.54cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{2.6cm}|p{0.8cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _packed-hsv-formats: diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst index 6b3781c04dd5..738bb14c0ee2 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst @@ -27,7 +27,7 @@ next to each other in memory. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.3cm}|p{1.6cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _rgb-formats: @@ -139,6 +139,144 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - + * .. _V4L2-PIX-FMT-RGBA444: + + - ``V4L2_PIX_FMT_RGBA444`` + - 'RA12' + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGBX444: + + - ``V4L2_PIX_FMT_RGBX444`` + - 'RX12' + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + - + - + - + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-ABGR444: + + - ``V4L2_PIX_FMT_ABGR444`` + - 'AB12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XBGR444: + + - ``V4L2_PIX_FMT_XBGR444`` + - 'XB12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - + - + - + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGRA444: + + - ``V4L2_PIX_FMT_BGRA444`` + - 'BA12' + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGRX444: + + - ``V4L2_PIX_FMT_BGRX444`` + - 'BX12' + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + - + - + - + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - * .. _V4L2-PIX-FMT-ARGB555: - ``V4L2_PIX_FMT_ARGB555`` @@ -185,6 +323,144 @@ next to each other in memory. - g\ :sub:`4` - g\ :sub:`3` - + * .. _V4L2-PIX-FMT-RGBA555: + + - ``V4L2_PIX_FMT_RGBA555`` + - 'RA15' + + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-RGBX555: + + - ``V4L2_PIX_FMT_RGBX555`` + - 'RX15' + + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-ABGR555: + + - ``V4L2_PIX_FMT_ABGR555`` + - 'AB15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-XBGR555: + + - ``V4L2_PIX_FMT_XBGR555`` + - 'XB15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-BGRA555: + + - ``V4L2_PIX_FMT_BGRA555`` + - 'BA15' + + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - a + + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-BGRX555: + + - ``V4L2_PIX_FMT_BGRX555`` + - 'BX15' + + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - * .. _V4L2-PIX-FMT-RGB565: - ``V4L2_PIX_FMT_RGB565`` @@ -461,6 +737,166 @@ next to each other in memory. - - - + * .. _V4L2-PIX-FMT-BGRA32: + + - ``V4L2_PIX_FMT_BGRA32`` + - 'RA24' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _V4L2-PIX-FMT-BGRX32: + + - ``V4L2_PIX_FMT_BGRX32`` + - 'RX24' + + - + - + - + - + - + - + - + - + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _V4L2-PIX-FMT-RGBA32: + + - ``V4L2_PIX_FMT_RGBA32`` + - 'AB24' + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :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-RGBX32: + + - ``V4L2_PIX_FMT_RGBX32`` + - 'XB24' + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - + - + - + - + - + - + - + - * .. _V4L2-PIX-FMT-ARGB32: - ``V4L2_PIX_FMT_ARGB32`` @@ -656,7 +1092,7 @@ either the corresponding ARGB or XRGB format, depending on the driver. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.2cm}|p{0.60cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{2.6cm}|p{0.70cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _rgb-formats-deprecated: diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst index f53e8f57a003..41b60fae703a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst @@ -28,7 +28,7 @@ component of each pixel in one 16 or 32 bit word. .. _packed-yuv-formats: -.. tabularcolumns:: |p{2.0cm}|p{0.67cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}| +.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| .. flat-table:: Packed YUV Image Formats :header-rows: 2 @@ -44,6 +44,7 @@ component of each pixel in one 16 or 32 bit word. - :cspan:`7` Byte 2 - :cspan:`7` Byte 3 + * - - - 7 @@ -81,6 +82,7 @@ component of each pixel in one 16 or 32 bit word. - 2 - 1 - 0 + * .. _V4L2-PIX-FMT-YUV444: - ``V4L2_PIX_FMT_YUV444`` @@ -103,7 +105,9 @@ component of each pixel in one 16 or 32 bit word. - Y'\ :sub:`2` - Y'\ :sub:`1` - Y'\ :sub:`0` - - + + - :cspan:`15` + * .. _V4L2-PIX-FMT-YUV555: - ``V4L2_PIX_FMT_YUV555`` @@ -126,7 +130,8 @@ component of each pixel in one 16 or 32 bit word. - Y'\ :sub:`0` - Cb\ :sub:`4` - Cb\ :sub:`3` - - + + - :cspan:`15` * .. _V4L2-PIX-FMT-YUV565: - ``V4L2_PIX_FMT_YUV565`` @@ -149,7 +154,9 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`5` - Cb\ :sub:`4` - Cb\ :sub:`3` - - + + - :cspan:`15` + * .. _V4L2-PIX-FMT-YUV32: - ``V4L2_PIX_FMT_YUV32`` @@ -191,6 +198,170 @@ component of each pixel in one 16 or 32 bit word. - 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 \endgroup @@ -202,4 +373,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/pixfmt-srggb10p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst index cdb70ac26126..fd32660a3766 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst @@ -40,7 +40,7 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{5.4cm}| +.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst index 01413be12916..960851275f23 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst @@ -18,6 +18,7 @@ V4L2_PIX_FMT_SRGGB12P ('pRAA'), V4L2_PIX_FMT_SGRBG12P ('pgAA'), V4L2_PIX_FMT_SGB 12-bit packed Bayer formats +--------------------------- Description @@ -37,7 +38,7 @@ Below is an example of a small V4L2_PIX_FMT_SBGGR12P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{2.7cm}|p{1.0cm}|p{1.0cm}|p{2.7cm}| +.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}| .. flat-table:: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst index b583531c2853..1a988d7e7ff8 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst @@ -41,17 +41,21 @@ of one of these formats: **Byte Order.** Each cell is one byte. +.. raw:: latex + \footnotesize + +.. tabularcolumns:: |p{1.8cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.1cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 2 1 1 1 1 1 1 1 + :widths: 2 1 1 1 1 3 3 3 - .. row 1 - - start + 0: + - start + 0 - B\ :sub:`00high` @@ -62,17 +66,20 @@ Each cell is one byte. - G\ :sub:`03high` - G\ :sub:`01low bits 1--0`\ (bits 7--6) + B\ :sub:`00low bits 5--0`\ (bits 5--0) - R\ :sub:`02low bits 3--0`\ (bits 7--4) + G\ :sub:`01low bits 5--2`\ (bits 3--0) - G\ :sub:`03low bits 5--0`\ (bits 7--2) + R\ :sub:`02low bits 5--4`\ (bits 1--0) - .. row 2 - - start + 7: + - start + 7 - G\ :sub:`00high` @@ -83,12 +90,15 @@ Each cell is one byte. - R\ :sub:`03high` - R\ :sub:`01low bits 1--0`\ (bits 7--6) + G\ :sub:`00low bits 5--0`\ (bits 5--0) - G\ :sub:`02low bits 3--0`\ (bits 7--4) + R\ :sub:`01low bits 5--2`\ (bits 3--0) - R\ :sub:`03low bits 5--0`\ (bits 7--2) + G\ :sub:`02low bits 5--4`\ (bits 1--0) - .. row 3 @@ -104,12 +114,15 @@ Each cell is one byte. - G\ :sub:`23high` - G\ :sub:`21low bits 1--0`\ (bits 7--6) + B\ :sub:`20low bits 5--0`\ (bits 5--0) - R\ :sub:`22low bits 3--0`\ (bits 7--4) + G\ :sub:`21low bits 5--2`\ (bits 3--0) - G\ :sub:`23low bits 5--0`\ (bits 7--2) + R\ :sub:`22low bits 5--4`\ (bits 1--0) - .. row 4 @@ -132,3 +145,8 @@ Each cell is one byte. - R\ :sub:`33low bits 5--0`\ (bits 7--2) G\ :sub:`32low bits 5--4`\ (bits 1--0) + +.. raw:: latex + + \normalsize + diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst index 7f82dad9013a..5688c816e334 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst @@ -19,6 +19,7 @@ array of struct :c:type:`v4l2_plane_pix_format` structures, describing all planes of that format. + .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_plane_pix_format @@ -41,6 +42,10 @@ describing all planes of that format. applications. +.. raw:: latex + + \small + .. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}| .. c:type:: v4l2_pix_format_mplane @@ -82,9 +87,7 @@ describing all planes of that format. * - __u8 - ``flags`` - Flags set by the application or driver, see :ref:`format-flags`. - * - union { - - (anonymous) - - + * - :cspan:`2` union { (anonymous) * - __u8 - ``ycbcr_enc`` - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. @@ -97,9 +100,7 @@ describing all planes of that format. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. - * - } - - - - + * - :cspan:`2` } * - __u8 - ``quantization`` - Quantization range, from enum :c:type:`v4l2_quantization`. @@ -116,3 +117,7 @@ describing all planes of that format. - ``reserved[7]`` - Reserved for future extensions. Should be zeroed by drivers and applications. + +.. raw:: latex + + \normalsize diff --git a/Documentation/media/uapi/v4l/pixfmt-y10p.rst b/Documentation/media/uapi/v4l/pixfmt-y10p.rst index 7893642faee3..39cd789dcb59 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y10p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y10p.rst @@ -27,6 +27,12 @@ in the same order. **Bit-packed representation.** +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}||p{1.2cm}||p{1.2cm}||p{1.2cm}|p{3.2cm}|p{3.2cm}| + .. flat-table:: :header-rows: 0 :stub-columns: 0 @@ -38,3 +44,7 @@ in the same order. - Y'\ :sub:`03[9:2]` - Y'\ :sub:`03[1:0]`\ (bits 7--6) Y'\ :sub:`02[1:0]`\ (bits 5--4) Y'\ :sub:`01[1:0]`\ (bits 3--2) Y'\ :sub:`00[1:0]`\ (bits 1--0) + +.. raw:: latex + + \normalsize diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index ff4b2a972fd2..ab1a48a5ae80 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 @@ -980,6 +980,113 @@ The following tables list existing packed RGB formats. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR888-3X8: + + - MEDIA_BUS_FMT_BGR888_3X8 + - 0x101b + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` * .. _MEDIA-BUS-FMT-GBR888-1X24: - MEDIA_BUS_FMT_GBR888_1X24 @@ -7414,7 +7521,7 @@ The following table lists existing HSV/HSL formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{3.0cm}|p{0.60cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{3.9cm}|p{0.73cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-hsv: @@ -7524,7 +7631,7 @@ The following table lists existing JPEG compressed formats. .. _v4l2-mbus-pixelcode-jpeg: -.. tabularcolumns:: |p{5.4cm}|p{1.4cm}|p{10.7cm}| +.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{10.1cm}| .. flat-table:: JPEG Formats :header-rows: 1 @@ -7557,7 +7664,7 @@ formats. .. _v4l2-mbus-pixelcode-vendor-specific: -.. tabularcolumns:: |p{6.8cm}|p{1.4cm}|p{9.3cm}| +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| .. flat-table:: Vendor and device specific formats :header-rows: 1 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..dbf7b445a27b 100644 --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -111,7 +111,7 @@ in use. Setting it means that the buffer will not be passed to the driver until the request itself is queued. Also, the driver will apply any settings associated with the request for this buffer. This field will be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. -If the device does not support requests, then ``EACCES`` will be returned. +If the device does not support requests, then ``EBADR`` will be returned. If requests are supported but an invalid request file descriptor is given, then ``EINVAL`` will be returned. @@ -123,9 +123,9 @@ 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. + to specify this for a capture buffer will result in an ``EBADR`` error. Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing @@ -185,9 +185,11 @@ EPIPE codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already dequeued and no new buffers are expected to become available. -EACCES +EBADR The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not - support requests for the given buffer type. + support requests for the given buffer type, or + the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires + that the buffer is part of a request. EBUSY The first buffer was queued via a request, but the application now tries 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..33a055907258 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 @@ -64,5 +65,4 @@ For more details see the file COPYING in the source distribution of Linux. soc-camera uvcvideo vivid - zoran zr364xx 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 diff --git a/Documentation/media/v4l-drivers/zoran.rst b/Documentation/media/v4l-drivers/zoran.rst deleted file mode 100644 index d2724a863d1d..000000000000 --- a/Documentation/media/v4l-drivers/zoran.rst +++ /dev/null @@ -1,583 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The Zoran driver -================ - -unified zoran driver (zr360x7, zoran, buz, dc10(+), dc30(+), lml33) - -website: http://mjpeg.sourceforge.net/driver-zoran/ - - -Frequently Asked Questions --------------------------- - -What cards are supported ------------------------- - -Iomega Buz, Linux Media Labs LML33/LML33R10, Pinnacle/Miro -DC10/DC10+/DC30/DC30+ and related boards (available under various names). - -Iomega Buz -~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Philips saa7111 TV decoder -* Philips saa7185 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, saa7111, saa7185, zr36060, zr36067 - -Inputs/outputs: Composite and S-video - -Norms: PAL, SECAM (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) - -Card number: 7 - -AverMedia 6 Eyes AVS6EYES -~~~~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Samsung ks0127 TV decoder -* Conexant bt866 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, ks0127, bt866, zr36060, zr36067 - -Inputs/outputs: - Six physical inputs. 1-6 are composite, - 1-2, 3-4, 5-6 doubles as S-video, - 1-3 triples as component. - One composite output. - -Norms: PAL, SECAM (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) - -Card number: 8 - -.. note:: - - Not autodetected, card=8 is necessary. - -Linux Media Labs LML33 -~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Brooktree bt819 TV decoder -* Brooktree bt856 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, bt819, bt856, zr36060, zr36067 - -Inputs/outputs: Composite and S-video - -Norms: PAL (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) - -Card number: 5 - -Linux Media Labs LML33R10 -~~~~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Philips saa7114 TV decoder -* Analog Devices adv7170 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, saa7114, adv7170, zr36060, zr36067 - -Inputs/outputs: Composite and S-video - -Norms: PAL (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) - -Card number: 6 - -Pinnacle/Miro DC10(new) -~~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36057 PCI controller -* Zoran zr36060 MJPEG codec -* Philips saa7110a TV decoder -* Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, saa7110, adv7175, zr36060, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 1 - -Pinnacle/Miro DC10+ -~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Philips saa7110a TV decoder -* Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, sa7110, adv7175, zr36060, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 2 - -Pinnacle/Miro DC10(old) -~~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36057 PCI controller -* Zoran zr36050 MJPEG codec -* Zoran zr36016 Video Front End or Fuji md0211 Video Front End (clone?) -* Micronas vpx3220a TV decoder -* mse3000 TV encoder or Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, vpx3220, mse3000/adv7175, zr36050, zr36016, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 0 - -Pinnacle/Miro DC30 -~~~~~~~~~~~~~~~~~~ - -* Zoran zr36057 PCI controller -* Zoran zr36050 MJPEG codec -* Zoran zr36016 Video Front End -* Micronas vpx3225d/vpx3220a/vpx3216b TV decoder -* Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, vpx3220/vpx3224, adv7175, zr36050, zr36016, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 3 - -Pinnacle/Miro DC30+ -~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36050 MJPEG codec -* Zoran zr36016 Video Front End -* Micronas vpx3225d/vpx3220a/vpx3216b TV decoder -* Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, vpx3220/vpx3224, adv7175, zr36050, zr36015, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 4 - -.. note:: - - #) No module for the mse3000 is available yet - #) No module for the vpx3224 is available yet - -1.1 What the TV decoder can do an what not ------------------------------------------- - -The best know TV standards are NTSC/PAL/SECAM. but for decoding a frame that -information is not enough. There are several formats of the TV standards. -And not every TV decoder is able to handle every format. Also the every -combination is supported by the driver. There are currently 11 different -tv broadcast formats all aver the world. - -The CCIR defines parameters needed for broadcasting the signal. -The CCIR has defined different standards: A,B,D,E,F,G,D,H,I,K,K1,L,M,N,... -The CCIR says not much about the colorsystem used !!! -And talking about a colorsystem says not to much about how it is broadcast. - -The CCIR standards A,E,F are not used any more. - -When you speak about NTSC, you usually mean the standard: CCIR - M using -the NTSC colorsystem which is used in the USA, Japan, Mexico, Canada -and a few others. - -When you talk about PAL, you usually mean: CCIR - B/G using the PAL -colorsystem which is used in many Countries. - -When you talk about SECAM, you mean: CCIR - L using the SECAM Colorsystem -which is used in France, and a few others. - -There the other version of SECAM, CCIR - D/K is used in Bulgaria, China, -Slovakai, Hungary, Korea (Rep.), Poland, Rumania and a others. - -The CCIR - H uses the PAL colorsystem (sometimes SECAM) and is used in -Egypt, Libya, Sri Lanka, Syrain Arab. Rep. - -The CCIR - I uses the PAL colorsystem, and is used in Great Britain, Hong Kong, -Ireland, Nigeria, South Africa. - -The CCIR - N uses the PAL colorsystem and PAL frame size but the NTSC framerate, -and is used in Argentinia, Uruguay, an a few others - -We do not talk about how the audio is broadcast ! - -A rather good sites about the TV standards are: -http://www.sony.jp/support/ -http://info.electronicwerkstatt.de/bereiche/fernsehtechnik/frequenzen_und_normen/Fernsehnormen/ -and http://www.cabl.com/restaurant/channel.html - -Other weird things around: NTSC 4.43 is a modificated NTSC, which is mainly -used in PAL VCR's that are able to play back NTSC. PAL 60 seems to be the same -as NTSC 4.43 . The Datasheets also talk about NTSC 44, It seems as if it would -be the same as NTSC 4.43. -NTSC Combs seems to be a decoder mode where the decoder uses a comb filter -to split coma and luma instead of a Delay line. - -But I did not defiantly find out what NTSC Comb is. - -Philips saa7111 TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1997, is used in the BUZ and -- can handle: PAL B/G/H/I, PAL N, PAL M, NTSC M, NTSC N, NTSC 4.43 and SECAM - -Philips saa7110a TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1995, is used in the Pinnacle/Miro DC10(new), DC10+ and -- can handle: PAL B/G, NTSC M and SECAM - -Philips saa7114 TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 2000, is used in the LML33R10 and -- can handle: PAL B/G/D/H/I/N, PAL N, PAL M, NTSC M, NTSC 4.43 and SECAM - -Brooktree bt819 TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1996, and is used in the LML33 and -- can handle: PAL B/D/G/H/I, NTSC M - -Micronas vpx3220a TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1996, is used in the DC30 and DC30+ and -- can handle: PAL B/G/H/I, PAL N, PAL M, NTSC M, NTSC 44, PAL 60, SECAM,NTSC Comb - -Samsung ks0127 TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~ - -- is used in the AVS6EYES card and -- can handle: NTSC-M/N/44, PAL-M/N/B/G/H/I/D/K/L and SECAM - - -What the TV encoder can do an what not --------------------------------------- - -The TV encoder are doing the "same" as the decoder, but in the oder direction. -You feed them digital data and the generate a Composite or SVHS signal. -For information about the colorsystems and TV norm take a look in the -TV decoder section. - -Philips saa7185 TV Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1996, is used in the BUZ -- can generate: PAL B/G, NTSC M - -Brooktree bt856 TV Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1994, is used in the LML33 -- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M, PAL-N (Argentina) - -Analog Devices adv7170 TV Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 2000, is used in the LML300R10 -- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M, PAL 60 - -Analog Devices adv7175 TV Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1996, is used in the DC10, DC10+, DC10 old, DC30, DC30+ -- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M - -ITT mse3000 TV encoder -~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1991, is used in the DC10 old -- can generate: PAL , NTSC , SECAM - -Conexant bt866 TV encoder -~~~~~~~~~~~~~~~~~~~~~~~~~ - -- is used in AVS6EYES, and -- can generate: NTSC/PAL, PALM, PALN - -The adv717x, should be able to produce PAL N. But you find nothing PAL N -specific in the registers. Seem that you have to reuse a other standard -to generate PAL N, maybe it would work if you use the PAL M settings. - -How do I get this damn thing to work ------------------------------------- - -Load zr36067.o. If it can't autodetect your card, use the card=X insmod -option with X being the card number as given in the previous section. -To have more than one card, use card=X1[,X2[,X3,[X4[..]]]] - -To automate this, add the following to your /etc/modprobe.d/zoran.conf: - -options zr36067 card=X1[,X2[,X3[,X4[..]]]] -alias char-major-81-0 zr36067 - -One thing to keep in mind is that this doesn't load zr36067.o itself yet. It -just automates loading. If you start using xawtv, the device won't load on -some systems, since you're trying to load modules as a user, which is not -allowed ("permission denied"). A quick workaround is to add 'Load "v4l"' to -XF86Config-4 when you use X by default, or to run 'v4l-conf -c <device>' in -one of your startup scripts (normally rc.local) if you don't use X. Both -make sure that the modules are loaded on startup, under the root account. - -What mainboard should I use (or why doesn't my card work) ---------------------------------------------------------- - - -<insert lousy disclaimer here>. In short: good=SiS/Intel, bad=VIA. - -Experience tells us that people with a Buz, on average, have more problems -than users with a DC10+/LML33. Also, it tells us that people owning a VIA- -based mainboard (ktXXX, MVP3) have more problems than users with a mainboard -based on a different chipset. Here's some notes from Andrew Stevens: - -Here's my experience of using LML33 and Buz on various motherboards: - -- VIA MVP3 - - Forget it. Pointless. Doesn't work. -- Intel 430FX (Pentium 200) - - LML33 perfect, Buz tolerable (3 or 4 frames dropped per movie) -- Intel 440BX (early stepping) - - LML33 tolerable. Buz starting to get annoying (6-10 frames/hour) -- Intel 440BX (late stepping) - - Buz tolerable, LML3 almost perfect (occasional single frame drops) -- SiS735 - - LML33 perfect, Buz tolerable. -- VIA KT133(*) - - LML33 starting to get annoying, Buz poor enough that I have up. - -- Both 440BX boards were dual CPU versions. - -Bernhard Praschinger later added: - -- AMD 751 - - Buz perfect-tolerable -- AMD 760 - - Buz perfect-tolerable - -In general, people on the user mailinglist won't give you much of a chance -if you have a VIA-based motherboard. They may be cheap, but sometimes, you'd -rather want to spend some more money on better boards. In general, VIA -mainboard's IDE/PCI performance will also suck badly compared to others. -You'll noticed the DC10+/DC30+ aren't mentioned anywhere in the overview. -Basically, you can assume that if the Buz works, the LML33 will work too. If -the LML33 works, the DC10+/DC30+ will work too. They're most tolerant to -different mainboard chipsets from all of the supported cards. - -If you experience timeouts during capture, buy a better mainboard or lower -the quality/buffersize during capture (see 'Concerning buffer sizes, quality, -output size etc.'). If it hangs, there's little we can do as of now. Check -your IRQs and make sure the card has its own interrupts. - -Programming interface ---------------------- - -This driver conforms to video4linux2. Support for V4L1 and for the custom -zoran ioctls has been removed in kernel 2.6.38. - -For programming example, please, look at lavrec.c and lavplay.c code in -the MJPEG-tools (http://mjpeg.sf.net/). - -Additional notes for software developers: - - The driver returns maxwidth and maxheight parameters according to - the current TV standard (norm). Therefore, the software which - communicates with the driver and "asks" for these parameters should - first set the correct norm. Well, it seems logically correct: TV - standard is "more constant" for current country than geometry - settings of a variety of TV capture cards which may work in ITU or - square pixel format. - -Applications ------------- - -Applications known to work with this driver: - -TV viewing: - -* xawtv -* kwintv -* probably any TV application that supports video4linux or video4linux2. - -MJPEG capture/playback: - -* mjpegtools/lavtools (or Linux Video Studio) -* gstreamer -* mplayer - -General raw capture: - -* xawtv -* gstreamer -* probably any application that supports video4linux or video4linux2 - -Video editing: - -* Cinelerra -* MainActor -* mjpegtools (or Linux Video Studio) - - -Concerning buffer sizes, quality, output size etc. --------------------------------------------------- - - -The zr36060 can do 1:2 JPEG compression. This is really the theoretical -maximum that the chipset can reach. The driver can, however, limit compression -to a maximum (size) of 1:4. The reason for this is that some cards (e.g. Buz) -can't handle 1:2 compression without stopping capture after only a few minutes. -With 1:4, it'll mostly work. If you have a Buz, use 'low_bitrate=1' to go into -1:4 max. compression mode. - -100% JPEG quality is thus 1:2 compression in practice. So for a full PAL frame -(size 720x576). The JPEG fields are stored in YUY2 format, so the size of the -fields are 720x288x16/2 bits/field (2 fields/frame) = 207360 bytes/field x 2 = -414720 bytes/frame (add some more bytes for headers and DHT (huffman)/DQT -(quantization) tables, and you'll get to something like 512kB per frame for -1:2 compression. For 1:4 compression, you'd have frames of half this size. - -Some additional explanation by Martin Samuelsson, which also explains the -importance of buffer sizes: --- -> Hmm, I do not think it is really that way. With the current (downloaded -> at 18:00 Monday) driver I get that output sizes for 10 sec: -> -q 50 -b 128 : 24.283.332 Bytes -> -q 50 -b 256 : 48.442.368 -> -q 25 -b 128 : 24.655.992 -> -q 25 -b 256 : 25.859.820 - -I woke up, and can't go to sleep again. I'll kill some time explaining why -this doesn't look strange to me. - -Let's do some math using a width of 704 pixels. I'm not sure whether the Buz -actually use that number or not, but that's not too important right now. - -704x288 pixels, one field, is 202752 pixels. Divided by 64 pixels per block; -3168 blocks per field. Each pixel consist of two bytes; 128 bytes per block; -1024 bits per block. 100% in the new driver mean 1:2 compression; the maximum -output becomes 512 bits per block. Actually 510, but 512 is simpler to use -for calculations. - -Let's say that we specify d1q50. We thus want 256 bits per block; times 3168 -becomes 811008 bits; 101376 bytes per field. We're talking raw bits and bytes -here, so we don't need to do any fancy corrections for bits-per-pixel or such -things. 101376 bytes per field. - -d1 video contains two fields per frame. Those sum up to 202752 bytes per -frame, and one of those frames goes into each buffer. - -But wait a second! -b128 gives 128kB buffers! It's not possible to cram -202752 bytes of JPEG data into 128kB! - -This is what the driver notice and automatically compensate for in your -examples. Let's do some math using this information: - -128kB is 131072 bytes. In this buffer, we want to store two fields, which -leaves 65536 bytes for each field. Using 3168 blocks per field, we get -20.68686868... available bytes per block; 165 bits. We can't allow the -request for 256 bits per block when there's only 165 bits available! The -q50 -option is silently overridden, and the -b128 option takes precedence, leaving -us with the equivalence of -q32. - -This gives us a data rate of 165 bits per block, which, times 3168, sums up -to 65340 bytes per field, out of the allowed 65536. The current driver has -another level of rate limiting; it won't accept -q values that fill more than -6/8 of the specified buffers. (I'm not sure why. "Playing it safe" seem to be -a safe bet. Personally, I think I would have lowered requested-bits-per-block -by one, or something like that.) We can't use 165 bits per block, but have to -lower it again, to 6/8 of the available buffer space: We end up with 124 bits -per block, the equivalence of -q24. With 128kB buffers, you can't use greater -than -q24 at -d1. (And PAL, and 704 pixels width...) - -The third example is limited to -q24 through the same process. The second -example, using very similar calculations, is limited to -q48. The only -example that actually grab at the specified -q value is the last one, which -is clearly visible, looking at the file size. --- - -Conclusion: the quality of the resulting movie depends on buffer size, quality, -whether or not you use 'low_bitrate=1' as insmod option for the zr36060.c -module to do 1:4 instead of 1:2 compression, etc. - -If you experience timeouts, lowering the quality/buffersize or using -'low_bitrate=1 as insmod option for zr36060.o might actually help, as is -proven by the Buz. - -It hangs/crashes/fails/whatevers! Help! ---------------------------------------- - -Make sure that the card has its own interrupts (see /proc/interrupts), check -the output of dmesg at high verbosity (load zr36067.o with debug=2, -load all other modules with debug=1). Check that your mainboard is favorable -(see question 2) and if not, test the card in another computer. Also see the -notes given in question 3 and try lowering quality/buffersize/capturesize -if recording fails after a period of time. - -If all this doesn't help, give a clear description of the problem including -detailed hardware information (memory+brand, mainboard+chipset+brand, which -MJPEG card, processor, other PCI cards that might be of interest), give the -system PnP information (/proc/interrupts, /proc/dma, /proc/devices), and give -the kernel version, driver version, glibc version, gcc version and any other -information that might possibly be of interest. Also provide the dmesg output -at high verbosity. See 'Contacting' on how to contact the developers. - -Maintainers/Contacting ----------------------- - -The driver is currently maintained by Laurent Pinchart and Ronald Bultje -(<laurent.pinchart@skynet.be> and <rbultje@ronald.bitfreak.net>). For bug -reports or questions, please contact the mailinglist instead of the developers -individually. For user questions (i.e. bug reports or how-to questions), send -an email to <mjpeg-users@lists.sf.net>, for developers (i.e. if you want to -help programming), send an email to <mjpeg-developer@lists.sf.net>. See -http://www.sf.net/projects/mjpeg/ for subscription information. - -For bug reports, be sure to include all the information as described in -the section 'It hangs/crashes/fails/whatevers! Help!'. Please make sure -you're using the latest version (http://mjpeg.sf.net/driver-zoran/). - -Previous maintainers/developers of this driver include Serguei Miridonov -<mirsev@cicese.mx>, Wolfgang Scherr <scherr@net4you.net>, Dave Perks -<dperks@ibm.net> and Rainer Johanni <Rainer@Johanni.de>. - -Driver's License ----------------- - - This driver is distributed under the terms of the General Public License. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program 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 for more details. - -See http://www.gnu.org/ for more information. |