diff options
| author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-07-08 16:40:06 +0200 |
|---|---|---|
| committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-07-08 16:59:40 +0200 |
| commit | 60c2820d0f6d3497975b6488e2599f8f611d8b95 (patch) | |
| tree | b3b03707c6438ea9b99cc57e847ebf517f968ab1 /Documentation/media/uapi/v4l | |
| parent | doc-rst: remove an invalid include from the docs (diff) | |
| download | linux-60c2820d0f6d3497975b6488e2599f8f611d8b95.tar.xz linux-60c2820d0f6d3497975b6488e2599f8f611d8b95.zip | |
doc_rst: rename the media Sphinx suff to Documentation/media
The name of the subsystem is "media", and not "linux_tv". Also,
as we plan to add other stuff there in the future, let's
rename also the media uAPI book to media_uapi, to make it
clearer.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/media/uapi/v4l')
218 files changed, 51817 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/app-pri.rst b/Documentation/media/uapi/v4l/app-pri.rst new file mode 100644 index 000000000000..a8c41a7ec396 --- /dev/null +++ b/Documentation/media/uapi/v4l/app-pri.rst @@ -0,0 +1,30 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _app-pri: + +******************** +Application Priority +******************** + +When multiple applications share a device it may be desirable to assign +them different priorities. Contrary to the traditional "rm -rf /" school +of thought a video recording application could for example block other +applications from changing video controls or switching the current TV +channel. Another objective is to permit low priority applications +working in background, which can be preempted by user controlled +applications and automatically regain control of the device at a later +time. + +Since these features cannot be implemented entirely in user space V4L2 +defines the :ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` and +:ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctls to request and +query the access priority associate with a file descriptor. Opening a +device assigns a medium priority, compatible with earlier versions of +V4L2 and drivers not supporting these ioctls. Applications requiring a +different priority will usually call :ref:`VIDIOC_S_PRIORITY +<VIDIOC_G_PRIORITY>` after verifying the device with the +:ref:`VIDIOC_QUERYCAP` ioctl. + +Ioctls changing driver properties, such as +:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>`, return an ``EBUSY`` error code +after another application obtained higher priority. diff --git a/Documentation/media/uapi/v4l/async.rst b/Documentation/media/uapi/v4l/async.rst new file mode 100644 index 000000000000..5affc0adb95b --- /dev/null +++ b/Documentation/media/uapi/v4l/async.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _async: + +**************** +Asynchronous I/O +**************** + +This method is not defined yet. diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst new file mode 100644 index 000000000000..71502f0bf8bd --- /dev/null +++ b/Documentation/media/uapi/v4l/audio.rst @@ -0,0 +1,90 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _audio: + +************************ +Audio Inputs and Outputs +************************ + +Audio inputs and outputs are physical connectors of a device. Video +capture devices have inputs, output devices have outputs, zero or more +each. Radio devices have no audio inputs or outputs. They have exactly +one tuner which in fact *is* an audio source, but this API associates +tuners with video inputs or outputs only, and radio devices have none of +these. [1]_ A connector on a TV card to loop back the received audio +signal to a sound card is not considered an audio output. + +Audio and video inputs and outputs are associated. Selecting a video +source also selects an audio source. This is most evident when the video +and audio source is a tuner. Further audio connectors can combine with +more than one video input or output. Assumed two composite video inputs +and two audio inputs exist, there may be up to four valid combinations. +The relation of video and audio connectors is defined in the +``audioset`` field of the respective struct +:ref:`v4l2_input <v4l2-input>` or struct +:ref:`v4l2_output <v4l2-output>`, where each bit represents the index +number, starting at zero, of one audio input or output. + +To learn about the number and attributes of the available inputs and +outputs applications can enumerate them with the +:ref:`VIDIOC_ENUMAUDIO` and +:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively. +The struct :ref:`v4l2_audio <v4l2-audio>` returned by the +:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal +:status information applicable when the current audio input is queried. + +The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and +:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current +audio input and output, respectively. Note that, unlike +:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and +:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a +structure as :ref:`VIDIOC_ENUMAUDIO` and +:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index. + +To select an audio input and change its properties applications call the +:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio +output (which presently has no changeable properties) applications call +the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl. + +Drivers must implement all audio input ioctls when the device has +multiple selectable audio inputs, all audio output ioctls when the +device has multiple selectable audio outputs. When the device has any +audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag +in the struct :ref:`v4l2_capability <v4l2-capability>` returned by +the :ref:`VIDIOC_QUERYCAP` ioctl. + + +.. code-block:: c + :caption: Example 1.3. Information about the current audio input + + struct v4l2_audio audio; + + memset(&audio, 0, sizeof(audio)); + + if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) { + perror("VIDIOC_G_AUDIO"); + exit(EXIT_FAILURE); + } + + printf("Current input: %s\\n", audio.name); + + +.. code-block:: c + :caption: Example 1.4. Switching to the first audio input + + struct v4l2_audio audio; + + memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */ + + audio.index = 0; + + if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) { + perror("VIDIOC_S_AUDIO"); + exit(EXIT_FAILURE); + } + +.. [1] + Actually struct :ref:`v4l2_audio <v4l2-audio>` ought to have a + ``tuner`` field like struct :ref:`v4l2_input <v4l2-input>`, not + only making the API more consistent but also permitting radio devices + with multiple tuners. diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst new file mode 100644 index 000000000000..e911df972d40 --- /dev/null +++ b/Documentation/media/uapi/v4l/biblio.rst @@ -0,0 +1,381 @@ +.. -*- coding: utf-8; mode: rst -*- + +********** +References +********** + + +.. _cea608: + +CEA 608-E +========= + + +:title: CEA-608-E R-2014 "Line 21 Data Services" + +:author: Consumer Electronics Association (http://www.ce.org) + +.. _en300294: + +EN 300 294 +========== + + +:title: EN 300 294 "625-line television Wide Screen Signalling (WSS)" + +:author: European Telecommunication Standards Institute (http://www.etsi.org) + +.. _ets300231: + +ETS 300 231 +=========== + + +:title: ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)" + +:author: European Telecommunication Standards Institute (http://www.etsi.org) + +.. _ets300706: + +ETS 300 706 +=========== + + +:title: ETS 300 706 "Enhanced Teletext specification" + +:author: European Telecommunication Standards Institute (http://www.etsi.org) + +.. _mpeg2part1: + +ISO 13818-1 +=========== + + +:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology — Generic coding of moving pictures and associated audio information: Systems" + +:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) + +.. _mpeg2part2: + +ISO 13818-2 +=========== + + +:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology — Generic coding of moving pictures and associated audio information: Video" + +:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) + +.. _itu470: + +ITU BT.470 +========== + + +:title: ITU-R Recommendation BT.470-6 "Conventional Television Systems" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _itu601: + +ITU BT.601 +========== + + +:title: ITU-R Recommendation BT.601-5 "Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect Ratios" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _itu653: + +ITU BT.653 +========== + + +:title: ITU-R Recommendation BT.653-3 "Teletext systems" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _itu709: + +ITU BT.709 +========== + + +:title: ITU-R Recommendation BT.709-5 "Parameter values for the HDTV standards for production and international programme exchange" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _itu1119: + +ITU BT.1119 +=========== + + +:title: ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _jfif: + +JFIF +==== + + +:title: JPEG File Interchange Format +:subtitle: Version 1.02 + +:author: Independent JPEG Group (http://www.ijg.org) + +.. _itu-t81: + +ITU-T.81 +======== + + +:title: ITU-T Recommendation T.81 "Information Technology — Digital Compression and Coding of Continous-Tone Still Images — Requirements and Guidelines" + +:author: International Telecommunication Union (http://www.itu.int) + +.. _w3c-jpeg-jfif: + +W3C JPEG JFIF +============= + + +:title: JPEG JFIF + +:author: The World Wide Web Consortium (http://www.w3.org) + +.. _smpte12m: + +SMPTE 12M +========= + + +:title: SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _smpte170m: + +SMPTE 170M +========== + + +:title: SMPTE 170M-1999 "Television - Composite Analog Video Signal - NTSC for Studio Applications" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _smpte240m: + +SMPTE 240M +========== + + +:title: SMPTE 240M-1999 "Television - Signal Parameters - 1125-Line High-Definition Production" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _smpte431: + +SMPTE RP 431-2 +============== + + +:title: SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _smpte2084: + +SMPTE ST 2084 +============= + + +:title: SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _srgb: + +sRGB +==== + + +:title: IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB" + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _sycc: + +sYCC +==== + + +:title: IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB" + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _xvycc: + +xvYCC +===== + + +:title: IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video applications - xvYCC" + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _adobergb: + +AdobeRGB +======== + + +:title: Adobe© RGB (1998) Color Image Encoding Version 2005-05 + +:author: Adobe Systems Incorporated (http://www.adobe.com) + +.. _oprgb: + +opRGB +===== + + +:title: IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement and management - Part 2-5: Colour management - Optional RGB colour space - opRGB" + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _itu2020: + +ITU BT.2020 +=========== + + +:title: ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high definition television systems for production and international programme exchange" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _tech3213: + +EBU Tech 3213 +============= + + +:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors" + +:author: European Broadcast Union (http://www.ebu.ch) + +.. _iec62106: + +IEC 62106 +========= + + +:title: Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _nrsc4: + +NRSC-4-B +======== + + +:title: NRSC-4-B: United States RBDS Standard + +:author: National Radio Systems Committee (http://www.nrscstandards.org) + +.. _iso12232: + +ISO 12232:2006 +============== + + +:title: Photography — Digital still cameras — Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index + +:author: International Organization for Standardization (http://www.iso.org) + +.. _cea861: + +CEA-861-E +========= + + +:title: A DTV Profile for Uncompressed High Speed Digital Interfaces + +:author: Consumer Electronics Association (http://www.ce.org) + +.. _vesadmt: + +VESA DMT +======== + + +:title: VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT) + +:author: Video Electronics Standards Association (http://www.vesa.org) + +.. _vesaedid: + +EDID +==== + + +:title: VESA Enhanced Extended Display Identification Data Standard +:subtitle: Release A, Revision 2 + +:author: Video Electronics Standards Association (http://www.vesa.org) + +.. _hdcp: + +HDCP +==== + + +:title: High-bandwidth Digital Content Protection System +:subtitle: Revision 1.3 + +:author: Digital Content Protection LLC (http://www.digital-cp.com) + +.. _hdmi: + +HDMI +==== + + +:title: High-Definition Multimedia Interface +:subtitle: Specification Version 1.4a + +:author: HDMI Licensing LLC (http://www.hdmi.org) + +.. _dp: + +DP +== + + +:title: VESA DisplayPort Standard +:subtitle: Version 1, Revision 2 + +:author: Video Electronics Standards Association (http://www.vesa.org) + +.. _poynton: + +poynton +======= + + +:title: Digital Video and HDTV, Algorithms and Interfaces + +:author: Charles Poynton + +.. _colimg: + +colimg +====== + + +:title: Color Imaging: Fundamentals and Applications + +:author: Erik Reinhard et al. diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst new file mode 100644 index 000000000000..b195eb5b63a1 --- /dev/null +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -0,0 +1,979 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _buffer: + +******* +Buffers +******* + +A buffer contains data exchanged by application and driver using one of +the Streaming I/O methods. In the multi-planar API, the data is held in +planes, while the buffer structure acts as a container for the planes. +Only pointers to buffers (planes) are exchanged, the data itself is not +copied. These pointers, together with meta-information like timestamps +or field parity, are stored in a struct :ref:`struct v4l2_buffer <v4l2-buffer>`, +argument to the :ref:`VIDIOC_QUERYBUF`, +:ref:`VIDIOC_QBUF` and +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, +some plane-specific members of struct :ref:`struct v4l2_buffer <v4l2-buffer>`, +such as pointers and sizes for each plane, are stored in struct +:ref:`struct v4l2_plane <v4l2-plane>` instead. In that case, struct +:ref:`struct v4l2_buffer <v4l2-buffer>` contains an array of plane structures. + +Dequeued video buffers come with timestamps. The driver decides at which +part of the frame and with which clock the timestamp is taken. Please +see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and +``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags +are always valid and constant across all buffers during the whole video +stream. Changes in these flags may take place as a side effect of +:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or +:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The +``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on +mem-to-mem devices is an exception to the rule: the timestamp source +flags are copied from the OUTPUT video buffer to the CAPTURE video +buffer. + + +.. _v4l2-buffer: + +struct v4l2_buffer +================== + +.. flat-table:: struct v4l2_buffer + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - + - Number of the buffer, set by the application except when calling + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the + driver. This field can range from zero to the number of buffers + allocated with the :ref:`VIDIOC_REQBUFS` ioctl + (struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` + ``count``), plus any buffers allocated with + :ref:`VIDIOC_CREATE_BUFS` minus one. + + - .. row 2 + + - __u32 + + - ``type`` + + - + - Type of the buffer, same as struct + :ref:`v4l2_format <v4l2-format>` ``type`` or struct + :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set + by the application. See :ref:`v4l2-buf-type` + + - .. row 3 + + - __u32 + + - ``bytesused`` + + - + - The number of bytes occupied by the data in the buffer. It depends + on the negotiated data format and may change with each buffer for + compressed variable size data like JPEG images. Drivers must set + this field when ``type`` refers to a capture stream, applications + when it refers to an output stream. If the application sets this + to 0 for an output stream, then ``bytesused`` will be set to the + size of the buffer (see the ``length`` field of this struct) by + the driver. For multiplanar formats this field is ignored and the + ``planes`` pointer is used instead. + + - .. row 4 + + - __u32 + + - ``flags`` + + - + - Flags set by the application or driver, see :ref:`buffer-flags`. + + - .. row 5 + + - __u32 + + - ``field`` + + - + - Indicates the field order of the image in the buffer, see + :ref:`v4l2-field`. This field is not used when the buffer + contains VBI data. Drivers must set it when ``type`` refers to a + capture stream, applications when it refers to an output stream. + + - .. row 6 + + - struct timeval + + - ``timestamp`` + + - + - For capture streams this is time when the first data byte was + captured, as returned by the :c:func:`clock_gettime()` function + for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in + :ref:`buffer-flags`. For output streams the driver stores the + time at which the last data byte was actually sent out in the + ``timestamp`` field. This permits applications to monitor the + drift between the video and system clock. For output streams that + use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill + in the timestamp which will be copied by the driver to the capture + stream. + + - .. row 7 + + - struct :ref:`v4l2_timecode <v4l2-timecode>` + + - ``timecode`` + + - + - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the + ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this + structure contains a frame timecode. In + :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and + bottom field contain the same timecode. Timecodes are intended to + help video editing and are typically recorded on video tapes, but + also embedded in compressed formats like MPEG. This field is + independent of the ``timestamp`` and ``sequence`` fields. + + - .. row 8 + + - __u32 + + - ``sequence`` + + - + - Set by the driver, counting the frames (not fields!) in sequence. + This field is set for both input and output devices. + + - .. row 9 + + - :cspan:`3` + + In :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and + bottom field have the same sequence number. The count starts at + zero and includes dropped or repeated frames. A dropped frame was + received by an input device but could not be stored due to lack of + free buffer space. A repeated frame was displayed again by an + output device because the application did not pass new data in + time. + + Note this may count the frames received e.g. over USB, without + taking into account the frames dropped by the remote hardware due + to limited compression throughput or bus bandwidth. These devices + identify by not enumerating any video standards, see + :ref:`standard`. + + - .. row 10 + + - __u32 + + - ``memory`` + + - + - This field must be set by applications and/or drivers in + accordance with the selected I/O method. See :ref:`v4l2-memory` + + - .. row 11 + + - union + + - ``m`` + + - .. row 12 + + - + - __u32 + + - ``offset`` + + - For the single-planar API and when ``memory`` is + ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the + start of the device memory. The value is returned by the driver + and apart of serving as parameter to the + :ref:`mmap() <func-mmap>` function not useful for applications. + See :ref:`mmap` for details + + - .. row 13 + + - + - unsigned long + + - ``userptr`` + + - For the single-planar API and when ``memory`` is + ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to + unsigned long type) in virtual memory, set by the application. See + :ref:`userp` for details. + + - .. row 14 + + - + - struct v4l2_plane + + - ``*planes`` + + - When using the multi-planar API, contains a userspace pointer to + an array of struct :ref:`v4l2_plane <v4l2-plane>`. The size of + the array should be put in the ``length`` field of this + :ref:`struct v4l2_buffer <v4l2-buffer>` structure. + + - .. row 15 + + - + - int + + - ``fd`` + + - For the single-plane API and when ``memory`` is + ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with + a DMABUF buffer. + + - .. row 16 + + - __u32 + + - ``length`` + + - + - Size of the buffer (not the payload) in bytes for the + single-planar API. This is set by the driver based on the calls to + :ref:`VIDIOC_REQBUFS` and/or + :ref:`VIDIOC_CREATE_BUFS`. For the + multi-planar API the application sets this to the number of + elements in the ``planes`` array. The driver will fill in the + actual number of valid elements in that array. + + - .. row 17 + + - __u32 + + - ``reserved2`` + + - + - A place holder for future extensions. Drivers and applications + must set this to 0. + + - .. row 18 + + - __u32 + + - ``reserved`` + + - + - A place holder for future extensions. Drivers and applications + must set this to 0. + + + +.. _v4l2-plane: + +struct v4l2_plane +================= + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __u32 + + - ``bytesused`` + + - + - The number of bytes occupied by data in the plane (its payload). + Drivers must set this field when ``type`` refers to a capture + stream, applications when it refers to an output stream. If the + application sets this to 0 for an output stream, then + ``bytesused`` will be set to the size of the plane (see the + ``length`` field of this struct) by the driver. Note that the + actual image data starts at ``data_offset`` which may not be 0. + + - .. row 2 + + - __u32 + + - ``length`` + + - + - Size in bytes of the plane (not its payload). This is set by the + driver based on the calls to + :ref:`VIDIOC_REQBUFS` and/or + :ref:`VIDIOC_CREATE_BUFS`. + + - .. row 3 + + - union + + - ``m`` + + - + - + + - .. row 4 + + - + - __u32 + + - ``mem_offset`` + + - When the memory type in the containing struct + :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_MMAP``, this + is the value that should be passed to :ref:`mmap() <func-mmap>`, + similar to the ``offset`` field in struct + :ref:`v4l2_buffer <v4l2-buffer>`. + + - .. row 5 + + - + - unsigned long + + - ``userptr`` + + - When the memory type in the containing struct + :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_USERPTR``, + this is a userspace pointer to the memory allocated for this plane + by an application. + + - .. row 6 + + - + - int + + - ``fd`` + + - When the memory type in the containing struct + :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_DMABUF``, + this is a file descriptor associated with a DMABUF buffer, similar + to the ``fd`` field in struct :ref:`v4l2_buffer <v4l2-buffer>`. + + - .. row 7 + + - __u32 + + - ``data_offset`` + + - + - Offset in bytes to video data in the plane. Drivers must set this + field when ``type`` refers to a capture stream, applications when + it refers to an output stream. Note that data_offset is included + in ``bytesused``. So the size of the image in the plane is + ``bytesused``-``data_offset`` at offset ``data_offset`` from the + start of the plane. + + - .. row 8 + + - __u32 + + - ``reserved[11]`` + + - + - Reserved for future use. Should be zeroed by drivers and + applications. + + + +.. _v4l2-buf-type: + +enum v4l2_buf_type +================== + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` + + - 1 + + - Buffer of a single-planar video capture stream, see + :ref:`capture`. + + - .. row 2 + + - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` + + - 9 + + - Buffer of a multi-planar video capture stream, see + :ref:`capture`. + + - .. row 3 + + - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` + + - 2 + + - Buffer of a single-planar video output stream, see + :ref:`output`. + + - .. row 4 + + - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` + + - 10 + + - Buffer of a multi-planar video output stream, see :ref:`output`. + + - .. row 5 + + - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` + + - 3 + + - Buffer for video overlay, see :ref:`overlay`. + + - .. row 6 + + - ``V4L2_BUF_TYPE_VBI_CAPTURE`` + + - 4 + + - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. + + - .. row 7 + + - ``V4L2_BUF_TYPE_VBI_OUTPUT`` + + - 5 + + - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. + + - .. row 8 + + - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` + + - 6 + + - Buffer of a sliced VBI capture stream, see :ref:`sliced`. + + - .. row 9 + + - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` + + - 7 + + - Buffer of a sliced VBI output stream, see :ref:`sliced`. + + - .. row 10 + + - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` + + - 8 + + - Buffer for video output overlay (OSD), see :ref:`osd`. + + - .. row 11 + + - ``V4L2_BUF_TYPE_SDR_CAPTURE`` + + - 11 + + - Buffer for Software Defined Radio (SDR) capture stream, see + :ref:`sdr`. + + - .. row 12 + + - ``V4L2_BUF_TYPE_SDR_OUTPUT`` + + - 12 + + - Buffer for Software Defined Radio (SDR) output stream, see + :ref:`sdr`. + + + +.. _buffer-flags: + +Buffer Flags +============ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_BUF_FLAG_MAPPED`` + + - 0x00000001 + + - The buffer resides in device memory and has been mapped into the + application's address space, see :ref:`mmap` for details. + Drivers set or clear this flag when the + :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the + driver. + + - .. row 2 + + - ``V4L2_BUF_FLAG_QUEUED`` + + - 0x00000002 + + - Internally drivers maintain two buffer queues, an incoming and + outgoing queue. When this flag is set, the buffer is currently on + the incoming queue. It automatically moves to the outgoing queue + after the buffer has been filled (capture devices) or displayed + (output devices). Drivers set or clear this flag when the + ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling + the ``VIDIOC_QBUF``\ ioctl it is always set and after + ``VIDIOC_DQBUF`` always cleared. + + - .. row 3 + + - ``V4L2_BUF_FLAG_DONE`` + + - 0x00000004 + + - When this flag is set, the buffer is currently on the outgoing + queue, ready to be dequeued from the driver. Drivers set or clear + this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After + calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always + cleared. Of course a buffer cannot be on both queues at the same + time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag + are mutually exclusive. They can be both cleared however, then the + buffer is in "dequeued" state, in the application domain so to + say. + + - .. row 4 + + - ``V4L2_BUF_FLAG_ERROR`` + + - 0x00000040 + + - When this flag is set, the buffer has been dequeued successfully, + although the data might have been corrupted. This is recoverable, + streaming may continue as normal and the buffer may be reused + normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is + called. + + - .. row 5 + + - ``V4L2_BUF_FLAG_KEYFRAME`` + + - 0x00000008 + + - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` + ioctl. It may be set by video capture devices when the buffer + contains a compressed image which is a key frame (or field), i. e. + can be decompressed on its own. Also known as an I-frame. + Applications can set this bit when ``type`` refers to an output + stream. + + - .. row 6 + + - ``V4L2_BUF_FLAG_PFRAME`` + + - 0x00000010 + + - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames + or fields which contain only differences to a previous key frame. + Applications can set this bit when ``type`` refers to an output + stream. + + - .. row 7 + + - ``V4L2_BUF_FLAG_BFRAME`` + + - 0x00000020 + + - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional + predicted frame or field which contains only the differences + between the current frame and both the preceding and following key + frames to specify its content. Applications can set this bit when + ``type`` refers to an output stream. + + - .. row 8 + + - ``V4L2_BUF_FLAG_TIMECODE`` + + - 0x00000100 + + - The ``timecode`` field is valid. Drivers set or clear this flag + when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set + this bit and the corresponding ``timecode`` structure when + ``type`` refers to an output stream. + + - .. row 9 + + - ``V4L2_BUF_FLAG_PREPARED`` + + - 0x00000400 + + - The buffer has been prepared for I/O and can be queued by the + application. Drivers set or clear this flag when the + :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, + :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. + + - .. row 10 + + - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` + + - 0x00000800 + + - Caches do not have to be invalidated for this buffer. Typically + applications shall use this flag if the data captured in the + buffer is not going to be touched by the CPU, instead the buffer + will, probably, be passed on to a DMA-capable hardware unit for + further processing or output. + + - .. row 11 + + - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` + + - 0x00001000 + + - Caches do not have to be cleaned for this buffer. Typically + applications shall use this flag for output buffers if the data in + this buffer has not been created by the CPU but by some + DMA-capable unit, in which case caches have not been used. + + - .. row 12 + + - ``V4L2_BUF_FLAG_LAST`` + + - 0x00100000 + + - Last buffer produced by the hardware. mem2mem codec drivers set + this flag on the capture queue for the last buffer when the + :ref:`VIDIOC_QUERYBUF` or + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to + hardware limitations, the last buffer may be empty. In this case + the driver will set the ``bytesused`` field to 0, regardless of + the format. Any Any subsequent call to the + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, + but return an ``EPIPE`` error code. + + - .. row 13 + + - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` + + - 0x0000e000 + + - Mask for timestamp types below. To test the timestamp type, mask + out bits not belonging to timestamp type by performing a logical + and operation with buffer flags and timestamp mask. + + - .. row 14 + + - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` + + - 0x00000000 + + - Unknown timestamp type. This type is used by drivers before Linux + 3.9 and may be either monotonic (see below) or realtime (wall + clock). Monotonic clock has been favoured in embedded systems + whereas most of the drivers use the realtime clock. Either kinds + of timestamps are available in user space via + :c:func:`clock_gettime(2)` using clock IDs ``CLOCK_MONOTONIC`` + and ``CLOCK_REALTIME``, respectively. + + - .. row 15 + + - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` + + - 0x00002000 + + - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` + clock. To access the same clock outside V4L2, use + :c:func:`clock_gettime(2)`. + + - .. row 16 + + - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` + + - 0x00004000 + + - The CAPTURE buffer timestamp has been taken from the corresponding + OUTPUT buffer. This flag applies only to mem2mem devices. + + - .. row 17 + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` + + - 0x00070000 + + - Mask for timestamp sources below. The timestamp source defines the + point of time the timestamp is taken in relation to the frame. + Logical 'and' operation between the ``flags`` field and + ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the + timestamp source. Applications must set the timestamp source when + ``type`` refers to an output stream and + ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. + + - .. row 18 + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` + + - 0x00000000 + + - End Of Frame. The buffer timestamp has been taken when the last + pixel of the frame has been received or the last pixel of the + frame has been transmitted. In practice, software generated + timestamps will typically be read from the clock a small amount of + time after the last pixel has been received or transmitten, + depending on the system and other activity in it. + + - .. row 19 + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` + + - 0x00010000 + + - Start Of Exposure. The buffer timestamp has been taken when the + exposure of the frame has begun. This is only valid for the + ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. + + + +.. _v4l2-memory: + +enum v4l2_memory +================ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_MEMORY_MMAP`` + + - 1 + + - The buffer is used for :ref:`memory mapping <mmap>` I/O. + + - .. row 2 + + - ``V4L2_MEMORY_USERPTR`` + + - 2 + + - The buffer is used for :ref:`user pointer <userp>` I/O. + + - .. row 3 + + - ``V4L2_MEMORY_OVERLAY`` + + - 3 + + - [to do] + + - .. row 4 + + - ``V4L2_MEMORY_DMABUF`` + + - 4 + + - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. + + + +Timecodes +========= + +The :ref:`struct v4l2_timecode <v4l2-timecode>` structure is designed to hold a +:ref:`smpte12m` or similar timecode. (struct +:c:type:`struct timeval` timestamps are stored in struct +:ref:`v4l2_buffer <v4l2-buffer>` field ``timestamp``.) + + +.. _v4l2-timecode: + +struct v4l2_timecode +-------------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - Frame rate the timecodes are based on, see :ref:`timecode-type`. + + - .. row 2 + + - __u32 + + - ``flags`` + + - Timecode flags, see :ref:`timecode-flags`. + + - .. row 3 + + - __u8 + + - ``frames`` + + - Frame count, 0 ... 23/24/29/49/59, depending on the type of + timecode. + + - .. row 4 + + - __u8 + + - ``seconds`` + + - Seconds count, 0 ... 59. This is a binary, not BCD number. + + - .. row 5 + + - __u8 + + - ``minutes`` + + - Minutes count, 0 ... 59. This is a binary, not BCD number. + + - .. row 6 + + - __u8 + + - ``hours`` + + - Hours count, 0 ... 29. This is a binary, not BCD number. + + - .. row 7 + + - __u8 + + - ``userbits``\ [4] + + - The "user group" bits from the timecode. + + + +.. _timecode-type: + +Timecode Types +-------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_TC_TYPE_24FPS`` + + - 1 + + - 24 frames per second, i. e. film. + + - .. row 2 + + - ``V4L2_TC_TYPE_25FPS`` + + - 2 + + - 25 frames per second, i. e. PAL or SECAM video. + + - .. row 3 + + - ``V4L2_TC_TYPE_30FPS`` + + - 3 + + - 30 frames per second, i. e. NTSC video. + + - .. row 4 + + - ``V4L2_TC_TYPE_50FPS`` + + - 4 + + - + + - .. row 5 + + - ``V4L2_TC_TYPE_60FPS`` + + - 5 + + - + + + +.. _timecode-flags: + +Timecode Flags +-------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_TC_FLAG_DROPFRAME`` + + - 0x0001 + + - Indicates "drop frame" semantics for counting frames in 29.97 fps + material. When set, frame numbers 0 and 1 at the start of each + minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the + count. + + - .. row 2 + + - ``V4L2_TC_FLAG_COLORFRAME`` + + - 0x0002 + + - The "color frame" flag. + + - .. row 3 + + - ``V4L2_TC_USERBITS_field`` + + - 0x000C + + - Field mask for the "binary group flags". + + - .. row 4 + + - ``V4L2_TC_USERBITS_USERDEFINED`` + + - 0x0000 + + - Unspecified format. + + - .. row 5 + + - ``V4L2_TC_USERBITS_8BITCHARS`` + + - 0x0008 + + - 8-bit ISO characters. diff --git a/Documentation/media/uapi/v4l/capture-example.rst b/Documentation/media/uapi/v4l/capture-example.rst new file mode 100644 index 000000000000..ac1cd057e25b --- /dev/null +++ b/Documentation/media/uapi/v4l/capture-example.rst @@ -0,0 +1,13 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _capture-example: + +********************* +Video Capture Example +********************* + + +.. toctree:: + :maxdepth: 1 + + capture.c diff --git a/Documentation/media/uapi/v4l/capture.c.rst b/Documentation/media/uapi/v4l/capture.c.rst new file mode 100644 index 000000000000..56525a0fb2fa --- /dev/null +++ b/Documentation/media/uapi/v4l/capture.c.rst @@ -0,0 +1,664 @@ +.. -*- coding: utf-8; mode: rst -*- + +file: media/v4l/capture.c +========================= + +.. code-block:: c + + /* + * V4L2 video capture example + * + * This program can be used and distributed without restrictions. + * + * This program is provided with the V4L2 API + * see https://linuxtv.org/docs.php for more information + */ + + #include <stdio.h> + #include <stdlib.h> + #include <string.h> + #include <assert.h> + + #include <getopt.h> /* getopt_long() */ + + #include <fcntl.h> /* low-level i/o */ + #include <unistd.h> + #include <errno.h> + #include <sys/stat.h> + #include <sys/types.h> + #include <sys/time.h> + #include <sys/mman.h> + #include <sys/ioctl.h> + + #include <linux/videodev2.h> + + #define CLEAR(x) memset(&(x), 0, sizeof(x)) + + enum io_method { + IO_METHOD_READ, + IO_METHOD_MMAP, + IO_METHOD_USERPTR, + }; + + struct buffer { + void *start; + size_t length; + }; + + static char *dev_name; + static enum io_method io = IO_METHOD_MMAP; + static int fd = -1; + struct buffer *buffers; + static unsigned int n_buffers; + static int out_buf; + static int force_format; + static int frame_count = 70; + + static void errno_exit(const char *s) + { + fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno)); + exit(EXIT_FAILURE); + } + + static int xioctl(int fh, int request, void *arg) + { + int r; + + do { + r = ioctl(fh, request, arg); + } while (-1 == r && EINTR == errno); + + return r; + } + + static void process_image(const void *p, int size) + { + if (out_buf) + fwrite(p, size, 1, stdout); + + fflush(stderr); + fprintf(stderr, "."); + fflush(stdout); + } + + static int read_frame(void) + { + struct v4l2_buffer buf; + unsigned int i; + + switch (io) { + case IO_METHOD_READ: + if (-1 == read(fd, buffers[0].start, buffers[0].length)) { + switch (errno) { + case EAGAIN: + return 0; + + case EIO: + /* Could ignore EIO, see spec. */ + + /* fall through */ + + default: + errno_exit("read"); + } + } + + process_image(buffers[0].start, buffers[0].length); + break; + + case IO_METHOD_MMAP: + CLEAR(buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + + if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { + switch (errno) { + case EAGAIN: + return 0; + + case EIO: + /* Could ignore EIO, see spec. */ + + /* fall through */ + + default: + errno_exit("VIDIOC_DQBUF"); + } + } + + assert(buf.index < n_buffers); + + process_image(buffers[buf.index].start, buf.bytesused); + + if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) + errno_exit("VIDIOC_QBUF"); + break; + + case IO_METHOD_USERPTR: + CLEAR(buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_USERPTR; + + if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { + switch (errno) { + case EAGAIN: + return 0; + + case EIO: + /* Could ignore EIO, see spec. */ + + /* fall through */ + + default: + errno_exit("VIDIOC_DQBUF"); + } + } + + for (i = 0; i < n_buffers; ++i) + if (buf.m.userptr == (unsigned long)buffers[i].start + && buf.length == buffers[i].length) + break; + + assert(i < n_buffers); + + process_image((void *)buf.m.userptr, buf.bytesused); + + if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) + errno_exit("VIDIOC_QBUF"); + break; + } + + return 1; + } + + static void mainloop(void) + { + unsigned int count; + + count = frame_count; + + while (count-- > 0) { + for (;;) { + fd_set fds; + struct timeval tv; + int r; + + FD_ZERO(&fds); + FD_SET(fd, &fds); + + /* Timeout. */ + tv.tv_sec = 2; + tv.tv_usec = 0; + + r = select(fd + 1, &fds, NULL, NULL, &tv); + + if (-1 == r) { + if (EINTR == errno) + continue; + errno_exit("select"); + } + + if (0 == r) { + fprintf(stderr, "select timeout\\n"); + exit(EXIT_FAILURE); + } + + if (read_frame()) + break; + /* EAGAIN - continue select loop. */ + } + } + } + + static void stop_capturing(void) + { + enum v4l2_buf_type type; + + switch (io) { + case IO_METHOD_READ: + /* Nothing to do. */ + break; + + case IO_METHOD_MMAP: + case IO_METHOD_USERPTR: + type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type)) + errno_exit("VIDIOC_STREAMOFF"); + break; + } + } + + static void start_capturing(void) + { + unsigned int i; + enum v4l2_buf_type type; + + switch (io) { + case IO_METHOD_READ: + /* Nothing to do. */ + break; + + case IO_METHOD_MMAP: + for (i = 0; i < n_buffers; ++i) { + struct v4l2_buffer buf; + + CLEAR(buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + buf.index = i; + + if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) + errno_exit("VIDIOC_QBUF"); + } + type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) + errno_exit("VIDIOC_STREAMON"); + break; + + case IO_METHOD_USERPTR: + for (i = 0; i < n_buffers; ++i) { + struct v4l2_buffer buf; + + CLEAR(buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_USERPTR; + buf.index = i; + buf.m.userptr = (unsigned long)buffers[i].start; + buf.length = buffers[i].length; + + if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) + errno_exit("VIDIOC_QBUF"); + } + type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) + errno_exit("VIDIOC_STREAMON"); + break; + } + } + + static void uninit_device(void) + { + unsigned int i; + + switch (io) { + case IO_METHOD_READ: + free(buffers[0].start); + break; + + case IO_METHOD_MMAP: + for (i = 0; i < n_buffers; ++i) + if (-1 == munmap(buffers[i].start, buffers[i].length)) + errno_exit("munmap"); + break; + + case IO_METHOD_USERPTR: + for (i = 0; i < n_buffers; ++i) + free(buffers[i].start); + break; + } + + free(buffers); + } + + static void init_read(unsigned int buffer_size) + { + buffers = calloc(1, sizeof(*buffers)); + + if (!buffers) { + fprintf(stderr, "Out of memory\\n"); + exit(EXIT_FAILURE); + } + + buffers[0].length = buffer_size; + buffers[0].start = malloc(buffer_size); + + if (!buffers[0].start) { + fprintf(stderr, "Out of memory\\n"); + exit(EXIT_FAILURE); + } + } + + static void init_mmap(void) + { + struct v4l2_requestbuffers req; + + CLEAR(req); + + req.count = 4; + req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + req.memory = V4L2_MEMORY_MMAP; + + if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { + if (EINVAL == errno) { + fprintf(stderr, "%s does not support " + "memory mappingn", dev_name); + exit(EXIT_FAILURE); + } else { + errno_exit("VIDIOC_REQBUFS"); + } + } + + if (req.count < 2) { + fprintf(stderr, "Insufficient buffer memory on %s\\n", + dev_name); + exit(EXIT_FAILURE); + } + + buffers = calloc(req.count, sizeof(*buffers)); + + if (!buffers) { + fprintf(stderr, "Out of memory\\n"); + exit(EXIT_FAILURE); + } + + for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { + struct v4l2_buffer buf; + + CLEAR(buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + buf.index = n_buffers; + + if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf)) + errno_exit("VIDIOC_QUERYBUF"); + + buffers[n_buffers].length = buf.length; + buffers[n_buffers].start = + mmap(NULL /* start anywhere */, + buf.length, + PROT_READ | PROT_WRITE /* required */, + MAP_SHARED /* recommended */, + fd, buf.m.offset); + + if (MAP_FAILED == buffers[n_buffers].start) + errno_exit("mmap"); + } + } + + static void init_userp(unsigned int buffer_size) + { + struct v4l2_requestbuffers req; + + CLEAR(req); + + req.count = 4; + req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + req.memory = V4L2_MEMORY_USERPTR; + + if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { + if (EINVAL == errno) { + fprintf(stderr, "%s does not support " + "user pointer i/on", dev_name); + exit(EXIT_FAILURE); + } else { + errno_exit("VIDIOC_REQBUFS"); + } + } + + buffers = calloc(4, sizeof(*buffers)); + + if (!buffers) { + fprintf(stderr, "Out of memory\\n"); + exit(EXIT_FAILURE); + } + + for (n_buffers = 0; n_buffers < 4; ++n_buffers) { + buffers[n_buffers].length = buffer_size; + buffers[n_buffers].start = malloc(buffer_size); + + if (!buffers[n_buffers].start) { + fprintf(stderr, "Out of memory\\n"); + exit(EXIT_FAILURE); + } + } + } + + static void init_device(void) + { + struct v4l2_capability cap; + struct v4l2_cropcap cropcap; + struct v4l2_crop crop; + struct v4l2_format fmt; + unsigned int min; + + if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { + if (EINVAL == errno) { + fprintf(stderr, "%s is no V4L2 device\\n", + dev_name); + exit(EXIT_FAILURE); + } else { + errno_exit("VIDIOC_QUERYCAP"); + } + } + + if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { + fprintf(stderr, "%s is no video capture device\\n", + dev_name); + exit(EXIT_FAILURE); + } + + switch (io) { + case IO_METHOD_READ: + if (!(cap.capabilities & V4L2_CAP_READWRITE)) { + fprintf(stderr, "%s does not support read i/o\\n", + dev_name); + exit(EXIT_FAILURE); + } + break; + + case IO_METHOD_MMAP: + case IO_METHOD_USERPTR: + if (!(cap.capabilities & V4L2_CAP_STREAMING)) { + fprintf(stderr, "%s does not support streaming i/o\\n", + dev_name); + exit(EXIT_FAILURE); + } + break; + } + + + /* Select video input, video standard and tune here. */ + + + CLEAR(cropcap); + + cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) { + crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + crop.c = cropcap.defrect; /* reset to default */ + + if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) { + switch (errno) { + case EINVAL: + /* Cropping not supported. */ + break; + default: + /* Errors ignored. */ + break; + } + } + } else { + /* Errors ignored. */ + } + + + CLEAR(fmt); + + fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + if (force_format) { + fmt.fmt.pix.width = 640; + fmt.fmt.pix.height = 480; + fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; + fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; + + if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt)) + errno_exit("VIDIOC_S_FMT"); + + /* Note VIDIOC_S_FMT may change width and height. */ + } else { + /* Preserve original settings as set by v4l2-ctl for example */ + if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt)) + errno_exit("VIDIOC_G_FMT"); + } + + /* Buggy driver paranoia. */ + min = fmt.fmt.pix.width * 2; + if (fmt.fmt.pix.bytesperline < min) + fmt.fmt.pix.bytesperline = min; + min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height; + if (fmt.fmt.pix.sizeimage < min) + fmt.fmt.pix.sizeimage = min; + + switch (io) { + case IO_METHOD_READ: + init_read(fmt.fmt.pix.sizeimage); + break; + + case IO_METHOD_MMAP: + init_mmap(); + break; + + case IO_METHOD_USERPTR: + init_userp(fmt.fmt.pix.sizeimage); + break; + } + } + + static void close_device(void) + { + if (-1 == close(fd)) + errno_exit("close"); + + fd = -1; + } + + static void open_device(void) + { + struct stat st; + + if (-1 == stat(dev_name, &st)) { + fprintf(stderr, "Cannot identify '%s': %d, %s\\n", + dev_name, errno, strerror(errno)); + exit(EXIT_FAILURE); + } + + if (!S_ISCHR(st.st_mode)) { + fprintf(stderr, "%s is no devicen", dev_name); + exit(EXIT_FAILURE); + } + + fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); + + if (-1 == fd) { + fprintf(stderr, "Cannot open '%s': %d, %s\\n", + dev_name, errno, strerror(errno)); + exit(EXIT_FAILURE); + } + } + + static void usage(FILE *fp, int argc, char **argv) + { + fprintf(fp, + "Usage: %s [options]\\n\\n" + "Version 1.3\\n" + "Options:\\n" + "-d | --device name Video device name [%s]n" + "-h | --help Print this messagen" + "-m | --mmap Use memory mapped buffers [default]n" + "-r | --read Use read() callsn" + "-u | --userp Use application allocated buffersn" + "-o | --output Outputs stream to stdoutn" + "-f | --format Force format to 640x480 YUYVn" + "-c | --count Number of frames to grab [%i]n" + "", + argv[0], dev_name, frame_count); + } + + static const char short_options[] = "d:hmruofc:"; + + static const struct option + long_options[] = { + { "device", required_argument, NULL, 'd' }, + { "help", no_argument, NULL, 'h' }, + { "mmap", no_argument, NULL, 'm' }, + { "read", no_argument, NULL, 'r' }, + { "userp", no_argument, NULL, 'u' }, + { "output", no_argument, NULL, 'o' }, + { "format", no_argument, NULL, 'f' }, + { "count", required_argument, NULL, 'c' }, + { 0, 0, 0, 0 } + }; + + int main(int argc, char **argv) + { + dev_name = "/dev/video0"; + + for (;;) { + int idx; + int c; + + c = getopt_long(argc, argv, + short_options, long_options, &idx); + + if (-1 == c) + break; + + switch (c) { + case 0: /* getopt_long() flag */ + break; + + case 'd': + dev_name = optarg; + break; + + case 'h': + usage(stdout, argc, argv); + exit(EXIT_SUCCESS); + + case 'm': + io = IO_METHOD_MMAP; + break; + + case 'r': + io = IO_METHOD_READ; + break; + + case 'u': + io = IO_METHOD_USERPTR; + break; + + case 'o': + out_buf++; + break; + + case 'f': + force_format++; + break; + + case 'c': + errno = 0; + frame_count = strtol(optarg, NULL, 0); + if (errno) + errno_exit(optarg); + break; + + default: + usage(stderr, argc, argv); + exit(EXIT_FAILURE); + } + } + + open_device(); + init_device(); + start_capturing(); + mainloop(); + stop_capturing(); + uninit_device(); + close_device(); + fprintf(stderr, "\\n"); + return 0; + } diff --git a/Documentation/media/uapi/v4l/colorspaces.rst b/Documentation/media/uapi/v4l/colorspaces.rst new file mode 100644 index 000000000000..322eb94c1d44 --- /dev/null +++ b/Documentation/media/uapi/v4l/colorspaces.rst @@ -0,0 +1,163 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _colorspaces: + +*********** +Colorspaces +*********** + +'Color' is a very complex concept and depends on physics, chemistry and +biology. Just because you have three numbers that describe the 'red', +'green' and 'blue' components of the color of a pixel does not mean that +you can accurately display that color. A colorspace defines what it +actually *means* to have an RGB value of e.g. (255, 0, 0). That is, +which color should be reproduced on the screen in a perfectly calibrated +environment. + +In order to do that we first need to have a good definition of color, +i.e. some way to uniquely and unambiguously define a color so that +someone else can reproduce it. Human color vision is trichromatic since +the human eye has color receptors that are sensitive to three different +wavelengths of light. Hence the need to use three numbers to describe +color. Be glad you are not a mantis shrimp as those are sensitive to 12 +different wavelengths, so instead of RGB we would be using the +ABCDEFGHIJKL colorspace... + +Color exists only in the eye and brain and is the result of how strongly +color receptors are stimulated. This is based on the Spectral Power +Distribution (SPD) which is a graph showing the intensity (radiant +power) of the light at wavelengths covering the visible spectrum as it +enters the eye. The science of colorimetry is about the relationship +between the SPD and color as perceived by the human brain. + +Since the human eye has only three color receptors it is perfectly +possible that different SPDs will result in the same stimulation of +those receptors and are perceived as the same color, even though the SPD +of the light is different. + +In the 1920s experiments were devised to determine the relationship +between SPDs and the perceived color and that resulted in the CIE 1931 +standard that defines spectral weighting functions that model the +perception of color. Specifically that standard defines functions that +can take an SPD and calculate the stimulus for each color receptor. +After some further mathematical transforms these stimuli are known as +the *CIE XYZ tristimulus* values and these X, Y and Z values describe a +color as perceived by a human unambiguously. These X, Y and Z values are +all in the range [0…1]. + +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) + +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 +to have such similar names for these colorspaces. Just be aware that if +colors are specified with lower case 'x' and 'y', then the CIE xyY +colorspace is used. Upper case 'X' and 'Y' refer to the CIE XYZ +colorspace. Also, y has nothing to do with luminance. Together x and y +specify a color, and Y the luminance. That is really all you need to +remember from a practical point of view. At the end of this section you +will find reading resources that go into much more detail if you are +interested. + +A monitor or TV will reproduce colors by emitting light at three +different wavelengths, the combination of which will stimulate the color +receptors in the eye and thus cause the perception of color. +Historically these wavelengths were defined by the red, green and blue +phosphors used in the displays. These *color primaries* are part of what +defines a colorspace. + +Different display devices will have different primaries and some +primaries are more suitable for some display technologies than others. +This has resulted in a variety of colorspaces that are used for +different display technologies or uses. To define a colorspace you need +to define the three color primaries (these are typically defined as x, y +chromaticity coordinates from the CIE xyY colorspace) but also the white +reference: that is the color obtained when all three primaries are at +maximum power. This determines the relative power or energy of the +primaries. This is usually chosen to be close to daylight which has been +defined as the CIE D65 Illuminant. + +To recapitulate: the CIE XYZ colorspace uniquely identifies colors. +Other colorspaces are defined by three chromaticity coordinates defined +in the CIE xyY colorspace. Based on those a 3x3 matrix can be +constructed that transforms CIE XYZ colors to colors in the new +colorspace. + +Both the CIE XYZ and the RGB colorspace that are derived from the +specific chromaticity primaries are linear colorspaces. But neither the +eye, nor display technology is linear. Doubling the values of all +components in the linear colorspace will not be perceived as twice the +intensity of the color. So each colorspace also defines a transfer +function that takes a linear color component value and transforms it to +the non-linear component value, which is a closer match to the +non-linear performance of both the eye and displays. Linear component +values are denoted RGB, non-linear are denoted as R'G'B'. In general +colors used in graphics are all R'G'B', except in openGL which uses +linear RGB. Special care should be taken when dealing with openGL to +provide linear RGB colors or to use the built-in openGL support to apply +the inverse transfer function. + +The final piece that defines a colorspace is a function that transforms +non-linear R'G'B' to non-linear Y'CbCr. This function is determined by +the so-called luma coefficients. There may be multiple possible Y'CbCr +encodings allowed for the same colorspace. Many encodings of color +prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the +human eye is more sensitive to differences in luminance than in color +this encoding allows one to reduce the amount of color information +compared to the luma data. Note that the luma (Y') is unrelated to the Y +in the CIE XYZ colorspace. Also note that Y'CbCr is often called YCbCr +or YUV even though these are strictly speaking wrong. + +Sometimes people confuse Y'CbCr as being a colorspace. This is not +correct, it is just an encoding of an R'G'B' color into luma and chroma +values. The underlying colorspace that is associated with the R'G'B' +color is also associated with the Y'CbCr color. + +The final step is how the RGB, R'G'B' or Y'CbCr values are quantized. +The CIE XYZ colorspace where X, Y and Z are in the range [0…1] describes +all colors that humans can perceive, but the transform to another +colorspace will produce colors that are outside the [0…1] range. Once +clamped to the [0…1] range those colors can no longer be reproduced in +that colorspace. This clamping is what reduces the extent or gamut of +the colorspace. How the range of [0…1] is translated to integer values +in the range of [0…255] (or higher, depending on the color depth) is +called the quantization. This is *not* part of the colorspace +definition. In practice RGB or R'G'B' values are full range, i.e. they +use the full [0…255] range. Y'CbCr values on the other hand are limited +range with Y' using [16…235] and Cb and Cr using [16…240]. + +Unfortunately, in some cases limited range RGB is also used where the +components use the range [16…235]. And full range Y'CbCr also exists +using the [0…255] range. + +In order to correctly interpret a color you need to know the +quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr +encoding and the colorspace. From that information you can calculate the +corresponding CIE XYZ color and map that again to whatever colorspace +your display device uses. + +The colorspace definition itself consists of the three chromaticity +primaries, the white reference chromaticity, a transfer function and the +luma coefficients needed to transform R'G'B' to Y'CbCr. While some +colorspace standards correctly define all four, quite often the +colorspace standard only defines some, and you have to rely on other +standards for the missing pieces. The fact that colorspaces are often a +mix of different standards also led to very confusing naming conventions +where the name of a standard was used to name a colorspace when in fact +that standard was part of various other colorspaces as well. + +If you want to read more about colors and colorspaces, then the +following resources are useful: :ref:`poynton` is a good practical +book for video engineers, :ref:`colimg` has a much broader scope and +describes many more aspects of color (physics, chemistry, biology, +etc.). The +`http://www.brucelindbloom.com <http://www.brucelindbloom.com>`__ +website is an excellent resource, especially with respect to the +mathematics behind colorspace conversions. The wikipedia +`CIE 1931 colorspace <http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space>`__ +article is also very useful. diff --git a/Documentation/media/uapi/v4l/common-defs.rst b/Documentation/media/uapi/v4l/common-defs.rst new file mode 100644 index 000000000000..39058216b630 --- /dev/null +++ b/Documentation/media/uapi/v4l/common-defs.rst @@ -0,0 +1,13 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _common-defs: + +****************************************************** +Common definitions for V4L2 and V4L2 subdev interfaces +****************************************************** + + +.. toctree:: + :maxdepth: 1 + + selections-common diff --git a/Documentation/media/uapi/v4l/common.rst b/Documentation/media/uapi/v4l/common.rst new file mode 100644 index 000000000000..13f2ed3fc5a6 --- /dev/null +++ b/Documentation/media/uapi/v4l/common.rst @@ -0,0 +1,46 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _common: + +################### +Common API Elements +################### +Programming a V4L2 device consists of these steps: + +- Opening the device + +- Changing device properties, selecting a video and audio input, video + standard, picture brightness a. o. + +- Negotiating a data format + +- Negotiating an input/output method + +- The actual input/output loop + +- Closing the device + +In practice most steps are optional and can be executed out of order. It +depends on the V4L2 device type, you can read about the details in +:ref:`devices`. In this chapter we will discuss the basic concepts +applicable to all devices. + + +.. toctree:: + :maxdepth: 1 + + open + querycap + app-pri + video + audio + tuner + standard + dv-timings + control + extended-controls + format + planar-apis + crop + selection-api + streaming-par diff --git a/Documentation/media/uapi/v4l/compat.rst b/Documentation/media/uapi/v4l/compat.rst new file mode 100644 index 000000000000..8b5e1cebd8f4 --- /dev/null +++ b/Documentation/media/uapi/v4l/compat.rst @@ -0,0 +1,18 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _compat: + +******* +Changes +******* + +The following chapters document the evolution of the V4L2 API, errata or +extensions. They are also intended to help application and driver +writers to port or update their code. + + +.. toctree:: + :maxdepth: 1 + + diff-v4l + hist-v4l2 diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst new file mode 100644 index 000000000000..6cf218ab36fb --- /dev/null +++ b/Documentation/media/uapi/v4l/control.rst @@ -0,0 +1,533 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _control: + +************* +User Controls +************* + +Devices typically have a number of user-settable controls such as +brightness, saturation and so on, which would be presented to the user +on a graphical user interface. But, different devices will have +different controls available, and furthermore, the range of possible +values, and the default value will vary from device to device. The +control ioctls provide the information and a mechanism to create a nice +user interface for these controls that will work correctly with any +device. + +All controls are accessed using an ID value. V4L2 defines several IDs +for specific purposes. Drivers can also implement their own custom +controls using ``V4L2_CID_PRIVATE_BASE`` [1]_ and higher values. The +pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in +:ref:`control-id`. The ID is used when querying the attributes of a +control, and when getting or setting the current value. + +Generally applications should present controls to the user without +assumptions about their purpose. Each control comes with a name string +the user is supposed to understand. When the purpose is non-intuitive +the driver writer should provide a user manual, a user interface plug-in +or a driver specific panel application. Predefined IDs were introduced +to change a few controls programmatically, for example to mute a device +during a channel switch. + +Drivers may enumerate different controls after switching the current +video input or output, tuner or modulator, or audio input or output. +Different in the sense of other bounds, another default and current +value, step size or other menu items. A control with a certain *custom* +ID can also change name and type. + +If a control is not applicable to the current configuration of the +device (for example, it doesn't apply to the current video input) +drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag. + +Control values are stored globally, they do not change when switching +except to stay within the reported bounds. They also do not change e. g. +when the device is opened or closed, when the tuner radio frequency is +changed or generally never without application request. + +V4L2 specifies an event mechanism to notify applications when controls +change value (see +:ref:`VIDIOC_SUBSCRIBE_EVENT`, event +``V4L2_EVENT_CTRL``), panel applications might want to make use of that +in order to always reflect the correct control value. + +All controls use machine endianness. + + +.. _control-id: + +Control IDs +=========== + +``V4L2_CID_BASE`` + First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``. + +``V4L2_CID_USER_BASE`` + Synonym of ``V4L2_CID_BASE``. + +``V4L2_CID_BRIGHTNESS`` ``(integer)`` + Picture brightness, or more precisely, the black level. + +``V4L2_CID_CONTRAST`` ``(integer)`` + Picture contrast or luma gain. + +``V4L2_CID_SATURATION`` ``(integer)`` + Picture color saturation or chroma gain. + +``V4L2_CID_HUE`` ``(integer)`` + Hue or color balance. + +``V4L2_CID_AUDIO_VOLUME`` ``(integer)`` + Overall audio volume. Note some drivers also provide an OSS or ALSA + mixer interface. + +``V4L2_CID_AUDIO_BALANCE`` ``(integer)`` + Audio stereo balance. Minimum corresponds to all the way left, + maximum to right. + +``V4L2_CID_AUDIO_BASS`` ``(integer)`` + Audio bass adjustment. + +``V4L2_CID_AUDIO_TREBLE`` ``(integer)`` + Audio treble adjustment. + +``V4L2_CID_AUDIO_MUTE`` ``(boolean)`` + Mute audio, i. e. set the volume to zero, however without affecting + ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute + at load time to avoid excessive noise. Actually the entire device + should be reset to a low power consumption state. + +``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)`` + Loudness mode (bass boost). + +``V4L2_CID_BLACK_LEVEL`` ``(integer)`` + Another name for brightness (not a synonym of + ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not + be used in new drivers and applications. + +``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)`` + Automatic white balance (cameras). + +``V4L2_CID_DO_WHITE_BALANCE`` ``(button)`` + This is an action control. When set (the value is ignored), the + device will do a white balance and then hold the current setting. + Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``, + which, when activated, keeps adjusting the white balance. + +``V4L2_CID_RED_BALANCE`` ``(integer)`` + Red chroma balance. + +``V4L2_CID_BLUE_BALANCE`` ``(integer)`` + Blue chroma balance. + +``V4L2_CID_GAMMA`` ``(integer)`` + Gamma adjust. + +``V4L2_CID_WHITENESS`` ``(integer)`` + Whiteness for grey-scale devices. This is a synonym for + ``V4L2_CID_GAMMA``. This control is deprecated and should not be + used in new drivers and applications. + +``V4L2_CID_EXPOSURE`` ``(integer)`` + Exposure (cameras). [Unit?] + +``V4L2_CID_AUTOGAIN`` ``(boolean)`` + Automatic gain/exposure control. + +``V4L2_CID_GAIN`` ``(integer)`` + Gain control. + +``V4L2_CID_HFLIP`` ``(boolean)`` + Mirror the picture horizontally. + +``V4L2_CID_VFLIP`` ``(boolean)`` + Mirror the picture vertically. + +.. _v4l2-power-line-frequency: + +``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` + Enables a power line frequency filter to avoid flicker. Possible + values for ``enum v4l2_power_line_frequency`` are: + ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0), + ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1), + ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and + ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3). + +``V4L2_CID_HUE_AUTO`` ``(boolean)`` + Enables automatic hue control by the device. The effect of setting + ``V4L2_CID_HUE`` while automatic hue control is enabled is + undefined, drivers should ignore such request. + +``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)`` + This control specifies the white balance settings as a color + temperature in Kelvin. A driver should have a minimum of 2800 + (incandescent) to 6500 (daylight). For more information about color + temperature see + `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__. + +``V4L2_CID_SHARPNESS`` ``(integer)`` + Adjusts the sharpness filters in a camera. The minimum value + disables the filters, higher values give a sharper picture. + +``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)`` + Adjusts the backlight compensation in a camera. The minimum value + disables backlight compensation. + +``V4L2_CID_CHROMA_AGC`` ``(boolean)`` + Chroma automatic gain control. + +``V4L2_CID_CHROMA_GAIN`` ``(integer)`` + Adjusts the Chroma gain control (for use when chroma AGC is + disabled). + +``V4L2_CID_COLOR_KILLER`` ``(boolean)`` + Enable the color killer (i. e. force a black & white image in case + of a weak video signal). + +.. _v4l2-colorfx: + +``V4L2_CID_COLORFX`` ``(enum)`` + Selects a color effect. The following values are defined: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_COLORFX_NONE`` + + - Color effect is disabled. + + - .. row 2 + + - ``V4L2_COLORFX_ANTIQUE`` + + - An aging (old photo) effect. + + - .. row 3 + + - ``V4L2_COLORFX_ART_FREEZE`` + + - Frost color effect. + + - .. row 4 + + - ``V4L2_COLORFX_AQUA`` + + - Water color, cool tone. + + - .. row 5 + + - ``V4L2_COLORFX_BW`` + + - Black and white. + + - .. row 6 + + - ``V4L2_COLORFX_EMBOSS`` + + - Emboss, the highlights and shadows replace light/dark boundaries + and low contrast areas are set to a gray background. + + - .. row 7 + + - ``V4L2_COLORFX_GRASS_GREEN`` + + - Grass green. + + - .. row 8 + + - ``V4L2_COLORFX_NEGATIVE`` + + - Negative. + + - .. row 9 + + - ``V4L2_COLORFX_SEPIA`` + + - Sepia tone. + + - .. row 10 + + - ``V4L2_COLORFX_SKETCH`` + + - Sketch. + + - .. row 11 + + - ``V4L2_COLORFX_SKIN_WHITEN`` + + - Skin whiten. + + - .. row 12 + + - ``V4L2_COLORFX_SKY_BLUE`` + + - Sky blue. + + - .. row 13 + + - ``V4L2_COLORFX_SOLARIZATION`` + + - Solarization, the image is partially reversed in tone, only color + values above or below a certain threshold are inverted. + + - .. row 14 + + - ``V4L2_COLORFX_SILHOUETTE`` + + - Silhouette (outline). + + - .. row 15 + + - ``V4L2_COLORFX_VIVID`` + + - Vivid colors. + + - .. row 16 + + - ``V4L2_COLORFX_SET_CBCR`` + + - The Cb and Cr chroma components are replaced by fixed coefficients + determined by ``V4L2_CID_COLORFX_CBCR`` control. + + + +``V4L2_CID_COLORFX_CBCR`` ``(integer)`` + Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR`` + color effect. Bits [7:0] of the supplied 32 bit value are + interpreted as Cr component, bits [15:8] as Cb component and bits + [31:16] must be zero. + +``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)`` + Enable Automatic Brightness. + +``V4L2_CID_ROTATE`` ``(integer)`` + Rotates the image by specified angle. Common angles are 90, 270 and + 180. Rotating the image to 90 and 270 will reverse the height and + width of the display window. It is necessary to set the new height + and width of the picture using the + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the + rotation angle selected. + +``V4L2_CID_BG_COLOR`` ``(integer)`` + Sets the background color on the current output device. Background + color needs to be specified in the RGB24 format. The supplied 32 bit + value is interpreted as bits 0-7 Red color information, bits 8-15 + Green color information, bits 16-23 Blue color information and bits + 24-31 must be zero. + +``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)`` + Switch on or off the illuminator 1 or 2 of the device (usually a + microscope). + +``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)`` + This is a read-only control that can be read by the application and + used as a hint to determine the number of CAPTURE buffers to pass to + REQBUFS. The value is the minimum number of CAPTURE buffers that is + necessary for hardware to work. + +``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)`` + This is a read-only control that can be read by the application and + used as a hint to determine the number of OUTPUT buffers to pass to + REQBUFS. The value is the minimum number of OUTPUT buffers that is + necessary for hardware to work. + +.. _v4l2-alpha-component: + +``V4L2_CID_ALPHA_COMPONENT`` ``(integer)`` + Sets the alpha color component. When a capture device (or capture + queue of a mem-to-mem device) produces a frame format that includes + an alpha component (e.g. + :ref:`packed RGB image formats <rgb-formats>`) and the alpha value + is not defined by the device or the mem-to-mem input data this + control lets you select the alpha component value of all pixels. + When an output device (or output queue of a mem-to-mem device) + consumes a frame format that doesn't include an alpha component and + the device supports alpha channel processing this control lets you + set the alpha component value of all pixels for further processing + in the device. + +``V4L2_CID_LASTP1`` + End of the predefined control IDs (currently + ``V4L2_CID_ALPHA_COMPONENT`` + 1). + +``V4L2_CID_PRIVATE_BASE`` + ID of the first custom (driver specific) control. Applications + depending on particular custom controls should check the driver name + and version, see :ref:`querycap`. + +Applications can enumerate the available controls with the +:ref:`VIDIOC_QUERYCTRL` and +:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a +control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and +:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement +``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the +device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or +more menu type controls. + + +.. _enum_all_controls: + +.. code-block:: c + :caption: Example 1.8. Enumerating all user controls + + + struct v4l2_queryctrl queryctrl; + struct v4l2_querymenu querymenu; + + static void enumerate_menu(void) + { + printf(" Menu items:\\n"); + + memset(&querymenu, 0, sizeof(querymenu)); + querymenu.id = queryctrl.id; + + for (querymenu.index = queryctrl.minimum; + querymenu.index <= queryctrl.maximum; + querymenu.index++) { + if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) { + printf(" %s\\n", querymenu.name); + } + } + } + + memset(&queryctrl, 0, sizeof(queryctrl)); + + for (queryctrl.id = V4L2_CID_BASE; + queryctrl.id < V4L2_CID_LASTP1; + queryctrl.id++) { + if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf("Control %s\\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(); + } else { + if (errno == EINVAL) + continue; + + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } + } + + for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; + queryctrl.id++) { + if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf("Control %s\\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(); + } else { + if (errno == EINVAL) + break; + + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } + } + + +.. code-block:: c + :caption: Example 1.9. Enumerating all user controls (alternative) + + memset(&queryctrl, 0, sizeof(queryctrl)); + + queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL; + while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER) + break; + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf("Control %s\\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(); + + queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; + } + if (errno != EINVAL) { + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } + + +.. code-block:: c + :caption: Example 1.10. Changing controls + + struct v4l2_queryctrl queryctrl; + struct v4l2_control control; + + memset(&queryctrl, 0, sizeof(queryctrl)); + queryctrl.id = V4L2_CID_BRIGHTNESS; + + if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (errno != EINVAL) { + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } else { + printf("V4L2_CID_BRIGHTNESS is not supportedn"); + } + } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { + printf("V4L2_CID_BRIGHTNESS is not supportedn"); + } else { + memset(&control, 0, sizeof (control)); + control.id = V4L2_CID_BRIGHTNESS; + control.value = queryctrl.default_value; + + if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) { + perror("VIDIOC_S_CTRL"); + exit(EXIT_FAILURE); + } + } + + memset(&control, 0, sizeof(control)); + control.id = V4L2_CID_CONTRAST; + + if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) { + control.value += 1; + + /* The driver may clamp the value or return ERANGE, ignored here */ + + if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control) + && errno != ERANGE) { + perror("VIDIOC_S_CTRL"); + exit(EXIT_FAILURE); + } + /* Ignore if V4L2_CID_CONTRAST is unsupported */ + } else if (errno != EINVAL) { + perror("VIDIOC_G_CTRL"); + exit(EXIT_FAILURE); + } + + control.id = V4L2_CID_AUDIO_MUTE; + control.value = 1; /* silence */ + + /* Errors ignored */ + ioctl(fd, VIDIOC_S_CTRL, &control); + +.. [1] + 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 + 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 + kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to + the real IDs. + + Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs + instead of using :ref:`VIDIOC_QUERYCTRL` with + the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so + support for ``V4L2_CID_PRIVATE_BASE`` is still around. diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst new file mode 100644 index 000000000000..ed43b36c51d8 --- /dev/null +++ b/Documentation/media/uapi/v4l/crop.rst @@ -0,0 +1,294 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _crop: + +************************************* +Image Cropping, Insertion and Scaling +************************************* + +Some video capture devices can sample a subsection of the picture and +shrink or enlarge it to an image of arbitrary size. We call these +abilities cropping and scaling. Some video output devices can scale an +image up or down and insert it at an arbitrary scan line and horizontal +offset into a video signal. + +Applications can use the following API to select an area in the video +signal, query the default area and the hardware limits. + +**NOTE**: Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`, +:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP +<VIDIOC_G_CROP>` ioctls apply to input as well as output devices. + +Scaling requires a source and a target. On a video capture or overlay +device the source is the video signal, and the cropping ioctls determine +the area actually sampled. The target are images read by the application +or overlaid onto the graphics screen. Their size (and position for an +overlay) is negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` +and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. + +On a video output device the source are the images passed in by the +application, and their size is again negotiated with the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` +ioctls, or may be encoded in a compressed video stream. The target is +the video signal, and the cropping ioctls determine the area where the +images are inserted. + +Source and target rectangles are defined even if the device does not +support scaling or the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and +:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position +where applicable) will be fixed in this case. + +**NOTE:** All capture and output devices must support the +:ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications can +determine if scaling takes place. + + +Cropping Structures +=================== + + +.. _crop-scale: + +.. figure:: crop_files/crop.* + :alt: crop.pdf / crop.gif + :align: center + + Image Cropping, Insertion and Scaling + + The cropping, insertion and scaling process + + + +For capture devices the coordinates of the top left corner, width and +height of the area which can be sampled is given by the ``bounds`` +substructure of the struct :ref:`v4l2_cropcap <v4l2-cropcap>` returned +by the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl. To support a wide +range of hardware this specification does not define an origin or units. +However by convention drivers should horizontally count unscaled samples +relative to 0H (the leading edge of the horizontal sync pulse, see +:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field +(see ITU R-525 line numbering for :ref:`525 lines <vbi-525>` and for +:ref:`625 lines <vbi-625>`), multiplied by two if the driver +can capture both fields. + +The top left corner, width and height of the source rectangle, that is +the area actually sampled, is given by struct +:ref:`v4l2_crop <v4l2-crop>` using the same coordinate system as +struct :ref:`v4l2_cropcap <v4l2-cropcap>`. Applications can use the +:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` +ioctls to get and set this rectangle. It must lie completely within the +capture boundaries and the driver may further adjust the requested size +and/or position according to hardware limitations. + +Each capture device has a default source rectangle, given by the +``defrect`` substructure of struct +:ref:`v4l2_cropcap <v4l2-cropcap>`. The center of this rectangle +shall align with the center of the active picture area of the video +signal, and cover what the driver writer considers the complete picture. +Drivers shall reset the source rectangle to the default when the driver +is first loaded, but not later. + +For output devices these structures and ioctls are used accordingly, +defining the *target* rectangle where the images will be inserted into +the video signal. + + +Scaling Adjustments +=================== + +Video hardware can have various cropping, insertion and scaling +limitations. It may only scale up or down, support only discrete scaling +factors, or have different scaling abilities in horizontal and vertical +direction. Also it may not support scaling at all. At the same time the +struct :ref:`v4l2_crop <v4l2-crop>` rectangle may have to be aligned, +and both the source and target rectangles may have arbitrary upper and +lower size limits. In particular the maximum ``width`` and ``height`` in +struct :ref:`v4l2_crop <v4l2-crop>` may be smaller than the struct +:ref:`v4l2_cropcap <v4l2-cropcap>`. ``bounds`` area. Therefore, as +usual, drivers are expected to adjust the requested parameters and +return the actual values selected. + +Applications can change the source or the target rectangle first, as +they may prefer a particular image size or a certain area in the video +signal. If the driver has to adjust both to satisfy hardware +limitations, the last requested rectangle shall take priority, and the +driver should preferably adjust the opposite one. The +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl however shall not change +the driver state and therefore only adjust the requested rectangle. + +Suppose scaling on a video capture device is restricted to a factor 1:1 +or 2:1 in either direction and the target image size must be a multiple +of 16 × 16 pixels. The source cropping rectangle is set to defaults, +which are also the upper limit in this example, of 640 × 400 pixels at +offset 0, 0. An application requests an image size of 300 × 225 pixels, +assuming video will be scaled down from the "full picture" accordingly. +The driver sets the image size to the closest possible values 304 × 224, +then chooses the cropping rectangle closest to the requested size, that +is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is +still valid, thus unmodified. Given the default cropping rectangle +reported by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` the application can +easily propose another offset to center the cropping rectangle. + +Now the application may insist on covering an area using a picture +aspect ratio closer to the original request, so it asks for a cropping +rectangle of 608 × 456 pixels. The present scaling factors limit +cropping to 640 × 384, so the driver returns the cropping size 608 × 384 +and adjusts the image size to closest possible 304 × 192. + + +Examples +======== + +Source and target rectangles shall remain unchanged across closing and +reopening a device, such that piping data into or out of a device will +work without special preparations. More advanced applications should +ensure the parameters are suitable before starting I/O. + +**NOTE:** on the next two examples, a video capture device is assumed; +change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. + +.. code-block:: c + :caption: Example 1.11. Resetting the cropping parameters + + struct v4l2_cropcap cropcap; + struct v4l2_crop crop; + + memset (&cropcap, 0, sizeof (cropcap)); + cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); + } + + memset (&crop, 0, sizeof (crop)); + crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + crop.c = cropcap.defrect; + + /* Ignore if cropping is not supported (EINVAL). */ + + if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) + && errno != EINVAL) { + perror ("VIDIOC_S_CROP"); + exit (EXIT_FAILURE); + } + +.. code-block:: c + :caption: Example 1.12. Simple downscaling + + struct v4l2_cropcap cropcap; + struct v4l2_format format; + + reset_cropping_parameters (); + + /* Scale down to 1/4 size of full picture. */ + + memset (&format, 0, sizeof (format)); /* defaults */ + + format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + format.fmt.pix.width = cropcap.defrect.width >> 1; + format.fmt.pix.height = cropcap.defrect.height >> 1; + format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; + + if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) { + perror ("VIDIOC_S_FORMAT"); + exit (EXIT_FAILURE); + } + + /* We could check the actual image size now, the actual scaling factor + or if the driver can scale at all. */ + +**NOTE:** This example assumes an output device. + +.. code-block:: c + :caption: Example 1.13. Selecting an output area + + struct v4l2_cropcap cropcap; + struct v4l2_crop crop; + + memset (&cropcap, 0, sizeof (cropcap)); + cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; + + if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); + } + + memset (&crop, 0, sizeof (crop)); + + crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; + crop.c = cropcap.defrect; + + /* Scale the width and height to 50 % of their original size + and center the output. */ + + crop.c.width /= 2; + crop.c.height /= 2; + crop.c.left += crop.c.width / 2; + crop.c.top += crop.c.height / 2; + + /* Ignore if cropping is not supported (EINVAL). */ + + if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) + && errno != EINVAL) { + perror ("VIDIOC_S_CROP"); + exit (EXIT_FAILURE); + } + +**NOTE:** This example assumes a video capture device. + +.. code-block:: c + :caption: Example 1.14. Current scaling factor and pixel aspect + + struct v4l2_cropcap cropcap; + struct v4l2_crop crop; + struct v4l2_format format; + double hscale, vscale; + double aspect; + int dwidth, dheight; + + memset (&cropcap, 0, sizeof (cropcap)); + cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); + } + + memset (&crop, 0, sizeof (crop)); + crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) { + if (errno != EINVAL) { + perror ("VIDIOC_G_CROP"); + exit (EXIT_FAILURE); + } + + /* Cropping not supported. */ + crop.c = cropcap.defrect; + } + + memset (&format, 0, sizeof (format)); + format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) { + perror ("VIDIOC_G_FMT"); + exit (EXIT_FAILURE); + } + + /* The scaling applied by the driver. */ + + hscale = format.fmt.pix.width / (double) crop.c.width; + vscale = format.fmt.pix.height / (double) crop.c.height; + + aspect = cropcap.pixelaspect.numerator / + (double) cropcap.pixelaspect.denominator; + aspect = aspect * hscale / vscale; + + /* Devices following ITU-R BT.601 do not capture + square pixels. For playback on a computer monitor + we should scale the images to this size. */ + + dwidth = format.fmt.pix.width / aspect; + dheight = format.fmt.pix.height; diff --git a/Documentation/media/uapi/v4l/crop_files/crop.gif b/Documentation/media/uapi/v4l/crop_files/crop.gif Binary files differnew file mode 100644 index 000000000000..3b9e7d836d4b --- /dev/null +++ b/Documentation/media/uapi/v4l/crop_files/crop.gif diff --git a/Documentation/media/uapi/v4l/crop_files/crop.pdf b/Documentation/media/uapi/v4l/crop_files/crop.pdf Binary files differnew file mode 100644 index 000000000000..c9fb81cd32f3 --- /dev/null +++ b/Documentation/media/uapi/v4l/crop_files/crop.pdf diff --git a/Documentation/media/uapi/v4l/depth-formats.rst b/Documentation/media/uapi/v4l/depth-formats.rst new file mode 100644 index 000000000000..82f183870aae --- /dev/null +++ b/Documentation/media/uapi/v4l/depth-formats.rst @@ -0,0 +1,15 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _depth-formats: + +************* +Depth Formats +************* + +Depth data provides distance to points, mapped onto the image plane + + +.. toctree:: + :maxdepth: 1 + + pixfmt-z16 diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst new file mode 100644 index 000000000000..16030a8354fd --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-capture.rst @@ -0,0 +1,102 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _capture: + +*********************** +Video Capture Interface +*********************** + +Video capture devices sample an analog video signal and store the +digitized images in memory. Today nearly all devices can capture at full +25 or 30 frames/second. With this interface applications can control the +capture process and move images from the driver into user space. + +Conventionally V4L2 video capture devices are accessed through character +device special files named ``/dev/video`` and ``/dev/video0`` to +``/dev/video63`` with major number 81 and minor numbers 0 to 63. +``/dev/video`` is typically a symbolic link to the preferred video +device. Note the same device files are used for video output devices. + + +Querying Capabilities +===================== + +Devices supporting the video capture interface set the +``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in +the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device +functions they may also support the :ref:`video overlay <overlay>` +(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>` +(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or +streaming I/O methods must be supported. Tuners and audio inputs are +optional. + + +Supplemental Functions +====================== + +Video capture devices shall support :ref:`audio input <audio>`, +:ref:`tuner`, :ref:`controls <control>`, +:ref:`cropping and scaling <crop>` and +:ref:`streaming parameter <streaming-par>` ioctls as needed. The +:ref:`video input <video>` and :ref:`video standard <standard>` +ioctls must be supported by all video capture devices. + + +Image Format Negotiation +======================== + +The result of a capture operation is determined by cropping and image +format parameters. The former select an area of the video picture to +capture, the latter how images are stored in memory, i. e. in RGB or YUV +format, the number of bits per pixel or width and height. Together they +also define how images are scaled in the process. + +As usual these parameters are *not* reset at :ref:`open() <func-open>` +time to permit Unix tool chains, programming a device and then reading +from it as if it was a plain file. Well written V4L2 applications ensure +they really get what they want, including cropping and scaling. + +Cropping initialization at minimum requires to reset the parameters to +defaults. An example is given in :ref:`crop`. + +To query the current image format applications set the ``type`` field of +a struct :ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or +``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this +structure. Drivers fill the struct +:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct +:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp`` +member of the ``fmt`` union. + +To request different parameters applications set the ``type`` field of a +struct :ref:`v4l2_format <v4l2-format>` as above and initialize all +fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>` +``vbi`` member of the ``fmt`` union, or better just modify the results +of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` +ioctl with a pointer to this structure. Drivers may adjust the +parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` +does. + +Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl +can be used to learn about hardware limitations without disabling I/O or +possibly time consuming hardware preparations. + +The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and +struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are +discussed in :ref:`pixfmt`. See also the specification of the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for +details. Video capture devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` +and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all +requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. + + +Reading Images +============== + +A video capture device may support the ::ref:`read() function <func-read>` +and/or streaming (:ref:`memory mapping <func-mmap>` or +:ref:`user pointer <userp>`) I/O. See :ref:`io` for details. diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-codec.rst new file mode 100644 index 000000000000..7fd28d085c2c --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-codec.rst @@ -0,0 +1,32 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _codec: + +*************** +Codec 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 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 +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 that the MPEG controls actually support many more +codecs than just MPEG). See :ref:`mpeg-controls`. + +Memory-to-memory devices can often be used 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 +it independently from the others. The driver will arbitrate access to +the codec 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). diff --git a/Documentation/media/uapi/v4l/dev-effect.rst b/Documentation/media/uapi/v4l/dev-effect.rst new file mode 100644 index 000000000000..be4de3b0a025 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-effect.rst @@ -0,0 +1,22 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _effect: + +************************ +Effect Devices Interface +************************ + + **Note** + + This interface has been be suspended from the V4L2 API implemented + in Linux 2.6 until we have more experience with effect device + interfaces. + +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-event.rst b/Documentation/media/uapi/v4l/dev-event.rst new file mode 100644 index 000000000000..a06ec4d65359 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-event.rst @@ -0,0 +1,47 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _event: + +*************** +Event Interface +*************** + +The V4L2 event interface provides a means for a user to get immediately +notified on certain conditions taking place on a device. This might +include start of frame or loss of signal events, for example. Changes in +the value or state of a V4L2 control can also be reported through +events. + +To receive events, the events the user is interested in first must be +subscribed using the +:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once +an event is subscribed, the events of subscribed types are dequeueable +using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be +unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event +type V4L2_EVENT_ALL may be used to unsubscribe all the events the +driver supports. + +The event subscriptions and event queues are specific to file handles. +Subscribing an event on one file handle does not affect other file +handles. + +The information on dequeueable events is obtained by using select or +poll system calls on video devices. The V4L2 events use POLLPRI events +on poll system call and exceptions on select system call. + +Starting with kernel 3.1 certain guarantees can be given with regards to +events: + +1. Each subscribed event has its own internal dedicated event queue. + This means that flooding of one event type will not interfere with + other event types. + +2. If the internal event queue for a particular subscribed event becomes + full, then the oldest event in that queue will be dropped. + +3. Where applicable, certain event types can ensure that the payload of + the oldest event that is about to be dropped will be merged with the + payload of the next oldest event. Thus ensuring that no information + is lost, but only an intermediate step leading up to that + information. See the documentation for the event you want to + subscribe to whether this is applicable for that event or not. diff --git a/Documentation/media/uapi/v4l/dev-osd.rst b/Documentation/media/uapi/v4l/dev-osd.rst new file mode 100644 index 000000000000..b9b53fd7eb5d --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-osd.rst @@ -0,0 +1,146 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _osd: + +****************************** +Video Output Overlay Interface +****************************** + +**Also known as On-Screen Display (OSD)** + +Some video output devices can overlay a framebuffer image onto the +outgoing video signal. Applications can set up such an overlay using +this interface, which borrows structures and ioctls of the +:ref:`Video Overlay <overlay>` interface. + +The OSD function is accessible through the same character special file +as the :ref:`Video Output <capture>` function. Note the default +function of such a ``/dev/video`` device is video capturing or output. +The OSD function is only available after calling the +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. + + +Querying Capabilities +===================== + +Devices supporting the *Video Output Overlay* interface set the +``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of +struct :ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. + + +Framebuffer +=========== + +Contrary to the *Video Overlay* interface the framebuffer is normally +implemented on the TV card and not the graphics card. On Linux it is +accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device, +applications can find the corresponding framebuffer device by calling +the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl. It returns, amongst +other information, the physical address of the framebuffer in the +``base`` field of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`. +The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same +address in the ``smem_start`` field of struct +:c:type:`struct fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` +ioctl and struct :c:type:`struct fb_fix_screeninfo` are defined in +the ``linux/fb.h`` header file. + +The width and height of the framebuffer depends on the current video +standard. A V4L2 driver may reject attempts to change the video standard +(or any other ioctl which would imply a framebuffer size change) with an +``EBUSY`` error code until all applications closed the framebuffer device. + + +.. code-block:: c + :caption: Example 4.1. Finding a framebuffer device for OSD + + #include <linux/fb.h> + + struct v4l2_framebuffer fbuf; + unsigned int i; + int fb_fd; + + if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) { + perror("VIDIOC_G_FBUF"); + exit(EXIT_FAILURE); + } + + for (i = 0; i < 30; i++) { + char dev_name[16]; + struct fb_fix_screeninfo si; + + snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i); + + fb_fd = open(dev_name, O_RDWR); + if (-1 == fb_fd) { + switch (errno) { + case ENOENT: /* no such file */ + case ENXIO: /* no driver */ + continue; + + default: + perror("open"); + exit(EXIT_FAILURE); + } + } + + if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) { + if (si.smem_start == (unsigned long)fbuf.base) + break; + } else { + /* Apparently not a framebuffer device. */ + } + + close(fb_fd); + fb_fd = -1; + } + + /* fb_fd is the file descriptor of the framebuffer device + for the video output overlay, or -1 if no device was found. */ + + +Overlay Window and Scaling +========================== + +The overlay is controlled by source and target rectangles. The source +rectangle selects a subsection of the framebuffer image to be overlaid, +the target rectangle an area in the outgoing video signal where the +image will appear. Drivers may or may not support scaling, and arbitrary +sizes and positions of these rectangles. Further drivers may support any +(or none) of the clipping/blending methods defined for the +:ref:`Video Overlay <overlay>` interface. + +A struct :ref:`v4l2_window <v4l2-window>` defines the size of the +source rectangle, its position in the framebuffer and the +clipping/blending method to be used for the overlay. To get the current +parameters applications set the ``type`` field of a struct +:ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the +:ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not +possible to retrieve a previously programmed clipping list or bitmap. + +To program the source rectangle applications set the ``type`` field of a +struct :ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win`` +substructure and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. +The driver adjusts the parameters against hardware limits and returns +the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, +the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn +about driver capabilities without actually changing driver state. Unlike +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled. + +A struct :ref:`v4l2_crop <v4l2-crop>` defines the size and position +of the target rectangle. The scaling factor of the overlay is implied by +the width and height given in struct :ref:`v4l2_window <v4l2-window>` +and struct :ref:`v4l2_crop <v4l2-crop>`. The cropping API applies to +*Video Output* and *Video Output Overlay* devices in the same way as to +*Video Capture* and *Video Overlay* devices, merely reversing the +direction of the data flow. For more information see :ref:`crop`. + + +Enabling Overlay +================ + +There is no V4L2 ioctl to enable or disable the overlay, however the +framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl. diff --git a/Documentation/media/uapi/v4l/dev-output.rst b/Documentation/media/uapi/v4l/dev-output.rst new file mode 100644 index 000000000000..5063be7d4938 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-output.rst @@ -0,0 +1,99 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _output: + +********************** +Video Output Interface +********************** + +Video output devices encode stills or image sequences as analog video +signal. With this interface applications can control the encoding +process and move images from user space to the driver. + +Conventionally V4L2 video output devices are accessed through character +device special files named ``/dev/video`` and ``/dev/video0`` to +``/dev/video63`` with major number 81 and minor numbers 0 to 63. +``/dev/video`` is typically a symbolic link to the preferred video +device. Note the same device files are used for video capture devices. + + +Querying Capabilities +===================== + +Devices supporting the video output interface set the +``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in +the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device +functions they may also support the :ref:`raw VBI output <raw-vbi>` +(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or +streaming I/O methods must be supported. Modulators and audio outputs +are optional. + + +Supplemental Functions +====================== + +Video output devices shall support :ref:`audio output <audio>`, +:ref:`modulator <tuner>`, :ref:`controls <control>`, +:ref:`cropping and scaling <crop>` and +:ref:`streaming parameter <streaming-par>` ioctls as needed. The +:ref:`video output <video>` and :ref:`video standard <standard>` +ioctls must be supported by all video output devices. + + +Image Format Negotiation +======================== + +The output is determined by cropping and image format parameters. The +former select an area of the video picture where the image will appear, +the latter how images are stored in memory, i. e. in RGB or YUV format, +the number of bits per pixel or width and height. Together they also +define how images are scaled in the process. + +As usual these parameters are *not* reset at :ref:`open() <func-open>` +time to permit Unix tool chains, programming a device and then writing +to it as if it was a plain file. Well written V4L2 applications ensure +they really get what they want, including cropping and scaling. + +Cropping initialization at minimum requires to reset the parameters to +defaults. An example is given in :ref:`crop`. + +To query the current image format applications set the ``type`` field of +a struct :ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` +and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer +to this structure. Drivers fill the struct +:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct +:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp`` +member of the ``fmt`` union. + +To request different parameters applications set the ``type`` field of a +struct :ref:`v4l2_format <v4l2-format>` as above and initialize all +fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>` +``vbi`` member of the ``fmt`` union, or better just modify the results +of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` +ioctl with a pointer to this structure. Drivers may adjust the +parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` +does. + +Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl +can be used to learn about hardware limitations without disabling I/O or +possibly time consuming hardware preparations. + +The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and +struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are +discussed in :ref:`pixfmt`. See also the specification of the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for +details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` +and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all +requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. + + +Writing Images +============== + +A video output device may support the :ref:`write() function <rw>` +and/or streaming (:ref:`memory mapping <mmap>` or +:ref:`user pointer <userp>`) I/O. See :ref:`io` for details. diff --git a/Documentation/media/uapi/v4l/dev-overlay.rst b/Documentation/media/uapi/v4l/dev-overlay.rst new file mode 100644 index 000000000000..bed00bf34982 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-overlay.rst @@ -0,0 +1,316 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _overlay: + +*********************** +Video Overlay Interface +*********************** + +**Also known as Framebuffer Overlay or Previewing.** + +Video overlay devices have the ability to genlock (TV-)video into the +(VGA-)video signal of a graphics card, or to store captured images +directly in video memory of a graphics card, typically with clipping. +This can be considerable more efficient than capturing images and +displaying them by other means. In the old days when only nuclear power +plants needed cooling towers this used to be the only way to put live +video into a window. + +Video overlay devices are accessed through the same character special +files as :ref:`video capture <capture>` devices. Note the default +function of a ``/dev/video`` device is video capturing. The overlay +function is only available after calling the +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. + +The driver may support simultaneous overlay and capturing using the +read/write and streaming I/O methods. If so, operation at the nominal +frame rate of the video standard is not guaranteed. Frames may be +directed away from overlay to capture, or one field may be used for +overlay and the other for capture if the capture parameters permit this. + +Applications should use different file descriptors for capturing and +overlay. This must be supported by all drivers capable of simultaneous +capturing and overlay. Optionally these drivers may also permit +capturing and overlay with a single file descriptor for compatibility +with V4L and earlier versions of V4L2. [1]_ + + +Querying Capabilities +===================== + +Devices supporting the video overlay interface set the +``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O +method specified below must be supported. Tuners and audio inputs are +optional. + + +Supplemental Functions +====================== + +Video overlay devices shall support :ref:`audio input <audio>`, +:ref:`tuner`, :ref:`controls <control>`, +:ref:`cropping and scaling <crop>` and +:ref:`streaming parameter <streaming-par>` ioctls as needed. The +:ref:`video input <video>` and :ref:`video standard <standard>` +ioctls must be supported by all video overlay devices. + + +Setup +===== + +Before overlay can commence applications must program the driver with +frame buffer parameters, namely the address and size of the frame buffer +and the image format, for example RGB 5:6:5. The +:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and +:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and +set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is +privileged because it allows to set up DMA into physical memory, +bypassing the memory protection mechanisms of the kernel. Only the +superuser can change the frame buffer address and size. Users are not +supposed to run TV applications as root or with SUID bit set. A small +helper application with suitable privileges should query the graphics +system and program the V4L2 driver at the appropriate time. + +Some devices add the video overlay to the output signal of the graphics +card. In this case the frame buffer is not modified by the video device, +and the frame buffer address and pixel format are not needed by the +driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application +can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` +ioctl. + +A driver may support any (or none) of five clipping/blending methods: + +1. Chroma-keying displays the overlaid image only where pixels in the + primary graphics surface assume a certain color. + +2. A bitmap can be specified where each bit corresponds to a pixel in + the overlaid image. When the bit is set, the corresponding video + pixel is displayed, otherwise a pixel of the graphics surface. + +3. A list of clipping rectangles can be specified. In these regions *no* + video is displayed, so the graphics surface can be seen here. + +4. The framebuffer has an alpha channel that can be used to clip or + blend the framebuffer with the video. + +5. A global alpha value can be specified to blend the framebuffer + contents with video images. + +When simultaneous capturing and overlay is supported and the hardware +prohibits different image and frame buffer formats, the format requested +first takes precedence. The attempt to capture +(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay +(:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error +code or return accordingly modified parameters.. + + +Overlay Window +============== + +The overlaid image is determined by cropping and overlay window +parameters. The former select an area of the video picture to capture, +the latter how images are overlaid and clipped. Cropping initialization +at minimum requires to reset the parameters to defaults. An example is +given in :ref:`crop`. + +The overlay window is described by a struct +:ref:`v4l2_window <v4l2-window>`. It defines the size of the image, +its position over the graphics surface and the clipping to be applied. +To get the current parameters applications set the ``type`` field of a +struct :ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the +:ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not +possible to retrieve a previously programmed clipping list or bitmap. + +To program the overlay window applications set the ``type`` field of a +struct :ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and +call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver +adjusts the parameters against hardware limits and returns the actual +parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn +about driver capabilities without actually changing driver state. Unlike +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled. + +The scaling factor of the overlaid image is implied by the width and +height given in struct :ref:`v4l2_window <v4l2-window>` and the size +of the cropping rectangle. For more information see :ref:`crop`. + +When simultaneous capturing and overlay is supported and the hardware +prohibits different image and window sizes, the size requested first +takes precedence. The attempt to capture or overlay as well +(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error +code or return accordingly modified parameters. + + +.. _v4l2-window: + +struct v4l2_window +------------------ + +``struct v4l2_rect w`` + Size and position of the window relative to the top, left corner of + the frame buffer defined with + :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the + frame buffer width and height, the ``x`` and ``y`` coordinates can + be negative, and it can lie completely outside the frame buffer. The + driver clips the window accordingly, or if that is not possible, + modifies its size and/or position. + +``enum v4l2_field field`` + Applications set this field to determine which video field shall be + overlaid, typically one of ``V4L2_FIELD_ANY`` (0), + ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or + ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different + field order and return the actual setting here. + +``__u32 chromakey`` + When chroma-keying has been negotiated with + :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field + to the desired pixel value for the chroma key. The format is the + same as the pixel format of the framebuffer (struct + :ref:`v4l2_framebuffer <v4l2-framebuffer>` ``fmt.pixelformat`` + field), with bytes in host order. E. g. for + :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should + be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host. + +``struct v4l2_clip * clips`` + When chroma-keying has *not* been negotiated and + :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, + applications can set this field to point to an array of clipping + rectangles. + + Like the window coordinates w, clipping rectangles are defined + relative to the top, left corner of the frame buffer. However + clipping rectangles must not extend the frame buffer width and + height, and they must not overlap. If possible applications + should merge adjacent rectangles. Whether this must create + x-y or y-x bands, or the order of rectangles, is not defined. When + clip lists are not supported the driver ignores this field. Its + contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` + are undefined. + +``__u32 clipcount`` + When the application set the ``clips`` field, this field must + contain the number of clipping rectangles in the list. When clip + lists are not supported the driver ignores this field, its contents + after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are + supported but no clipping is desired this field must be set to zero. + +``void * bitmap`` + When chroma-keying has *not* been negotiated and + :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, + applications can set this field to point to a clipping bit mask. + +It must be of the same size as the window, ``w.width`` and ``w.height``. +Each bit corresponds to a pixel in the overlaid image, which is +displayed only when the bit is *set*. Pixel coordinates translate to +bits like: + + +.. code-block:: c + + ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7)) + +where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [2]_ + +When a clipping bit mask is not supported the driver ignores this field, +its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are +undefined. When a bit mask is supported but no clipping is desired this +field must be set to ``NULL``. + +Applications need not create a clip list or bit mask. When they pass +both, or despite negotiating chroma-keying, the results are undefined. +Regardless of the chosen method, the clipping abilities of the hardware +may be limited in quantity or quality. The results when these limits are +exceeded are undefined. [3]_ + +``__u8 global_alpha`` + The global alpha value used to blend the framebuffer with video + images, if global alpha blending has been negotiated + (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see + :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`, + :ref:`framebuffer-flags`). + + **Note**: this field was added in Linux 2.6.23, extending the structure. + However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>` + ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>` + parent structure with padding bytes at the end, are not affected. + + +.. _v4l2-clip: + +struct v4l2_clip [4]_ +--------------------- + +``struct v4l2_rect c`` + Coordinates of the clipping rectangle, relative to the top, left + corner of the frame buffer. Only window pixels *outside* all + clipping rectangles are displayed. + +``struct v4l2_clip * next`` + Pointer to the next clipping rectangle, ``NULL`` when this is the last + rectangle. Drivers ignore this field, it cannot be used to pass a + linked list of clipping rectangles. + + +.. _v4l2-rect: + +struct v4l2_rect +---------------- + +``__s32 left`` + Horizontal offset of the top, left corner of the rectangle, in + pixels. + +``__s32 top`` + Vertical offset of the top, left corner of the rectangle, in pixels. + Offsets increase to the right and down. + +``__u32 width`` + Width of the rectangle, in pixels. + +``__u32 height`` + Height of the rectangle, in pixels. + + +Enabling Overlay +================ + +To start or stop the frame buffer overlay applications call the +:ref:`VIDIOC_OVERLAY` ioctl. + +.. [1] + A common application of two file descriptors is the XFree86 + :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. + While the X server controls video overlay, the application can take + advantage of memory mapping and DMA. + + In the opinion of the designers of this API, no driver writer taking + the efforts to support simultaneous capturing and overlay will + restrict this ability by requiring a single file descriptor, as in + V4L and earlier versions of V4L2. Making this optional means + applications depending on two file descriptors need backup routines + to be compatible with all drivers, which is considerable more work + than using two fds in applications which do not. Also two fd's fit + the general concept of one file descriptor for each logical stream. + Hence as a complexity trade-off drivers *must* support two file + descriptors and *may* support single fd operation. + +.. [2] + Should we require ``w.width`` to be a multiple of eight? + +.. [3] + When the image is written into frame buffer memory it will be + undesirable if the driver clips out less pixels than expected, + because the application and graphics system are not aware these + regions need to be refreshed. The driver should clip out more pixels + or not write the image at all. + +.. [4] + The X Window system defines "regions" which are vectors of ``struct + BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and + ``height = y2 - y1``, so one cannot pass X11 clip lists directly. diff --git a/Documentation/media/uapi/v4l/dev-radio.rst b/Documentation/media/uapi/v4l/dev-radio.rst new file mode 100644 index 000000000000..5ff7cded2591 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-radio.rst @@ -0,0 +1,52 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _radio: + +*************** +Radio Interface +*************** + +This interface is intended for AM and FM (analog) radio receivers and +transmitters. + +Conventionally V4L2 radio devices are accessed through character device +special files named ``/dev/radio`` and ``/dev/radio0`` to +``/dev/radio63`` with major number 81 and minor numbers 64 to 127. + + +Querying Capabilities +===================== + +Devices supporting the radio interface set the ``V4L2_CAP_RADIO`` and +``V4L2_CAP_TUNER`` or ``V4L2_CAP_MODULATOR`` flag in the +``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. Other combinations of +capability flags are reserved for future extensions. + + +Supplemental Functions +====================== + +Radio devices can support :ref:`controls <control>`, and must support +the :ref:`tuner or modulator <tuner>` ioctls. + +They do not support the video input or output, audio input or output, +video standard, cropping and scaling, compression and streaming +parameter, or overlay ioctls. All other ioctls and I/O methods are +reserved for future extensions. + + +Programming +=========== + +Radio devices may have a couple audio controls (as discussed in +:ref:`control`) such as a volume control, possibly custom controls. +Further all radio devices have one tuner or modulator (these are +discussed in :ref:`tuner`) with index number zero to select the radio +frequency and to determine if a monaural or FM stereo program is +received/emitted. Drivers switch automatically between AM and FM +depending on the selected frequency. The +:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` or +:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl reports the +supported frequency range. diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst new file mode 100644 index 000000000000..da85be88d57e --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst @@ -0,0 +1,350 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _raw-vbi: + +********************** +Raw VBI Data Interface +********************** + +VBI is an abbreviation of Vertical Blanking Interval, a gap in the +sequence of lines of an analog video signal. During VBI no picture +information is transmitted, allowing some time while the electron beam +of a cathode ray tube TV returns to the top of the screen. Using an +oscilloscope you will find here the vertical synchronization pulses and +short data packages ASK modulated [1]_ onto the video signal. These are +transmissions of services such as Teletext or Closed Caption. + +Subject of this interface type is raw VBI data, as sampled off a video +signal, or to be added to a signal for output. The data format is +similar to uncompressed video images, a number of lines times a number +of samples per line, we call this a VBI image. + +Conventionally V4L2 VBI devices are accessed through character device +special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31`` +with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is +typically a symbolic link to the preferred VBI device. This convention +applies to both input and output devices. + +To address the problems of finding related video and VBI devices VBI +capturing and output is also available as device function under +``/dev/video``. To capture or output raw VBI data with these devices +applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. +Accessed as ``/dev/vbi``, raw VBI capturing or output is the default +device function. + + +Querying Capabilities +===================== + +Devices supporting the raw VBI capturing or output API set the +``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively, +in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the +read/write, streaming or asynchronous I/O methods must be supported. VBI +devices may or may not have a tuner or modulator. + + +Supplemental Functions +====================== + +VBI devices shall support :ref:`video input or output <video>`, +:ref:`tuner or modulator <tuner>`, and :ref:`controls <control>` +ioctls as needed. The :ref:`video standard <standard>` ioctls provide +information vital to program a VBI device, therefore must be supported. + + +Raw VBI Format Negotiation +========================== + +Raw VBI sampling abilities can vary, in particular the sampling +frequency. To properly interpret the data V4L2 specifies an ioctl to +query the sampling parameters. Moreover, to allow for some flexibility +applications can also suggest different parameters. + +As usual these parameters are *not* reset at :ref:`open() <func-open>` +time to permit Unix tool chains, programming a device and then reading +from it as if it was a plain file. Well written V4L2 applications should +always ensure they really get what they want, requesting reasonable +parameters and then checking if the actual parameters are suitable. + +To query the current raw VBI capture parameters applications set the +``type`` field of a struct :ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call +the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this +structure. Drivers fill the struct +:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``vbi`` member of the +``fmt`` union. + +To request different parameters applications set the ``type`` field of a +struct :ref:`v4l2_format <v4l2-format>` as above and initialize all +fields of the struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` +``vbi`` member of the ``fmt`` union, or better just modify the results +of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` +ioctl with a pointer to this structure. Drivers return an ``EINVAL`` error +code only when the given parameters are ambiguous, otherwise they modify +the parameters according to the hardware capabilities and return the +actual parameters. When the driver allocates resources at this point, it +may return an ``EBUSY`` error code to indicate the returned parameters are +valid but the required resources are currently not available. That may +happen for instance when the video and VBI areas to capture would +overlap, or when the driver supports multiple opens and another process +already requested VBI capturing or output. Anyway, applications must +expect other resource allocation points which may return ``EBUSY``, at the +:ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>` +, :ref:`write() <func-write>` and :ref:`select() <func-select>` calls. + +VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests +and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. + + +.. _v4l2-vbi-format: + +.. flat-table:: struct v4l2_vbi_format + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``sampling_rate`` + + - Samples per second, i. e. unit 1 Hz. + + - .. row 2 + + - __u32 + + - ``offset`` + + - Horizontal offset of the VBI image, relative to the leading edge + of the line synchronization pulse and counted in samples: The + first sample in the VBI image will be located ``offset`` / + ``sampling_rate`` seconds following the leading edge. See also + :ref:`vbi-hsync`. + + - .. row 3 + + - __u32 + + - ``samples_per_line`` + + - + + - .. row 4 + + - __u32 + + - ``sample_format`` + + - Defines the sample format as in :ref:`pixfmt`, a + four-character-code. [2]_ Usually this is ``V4L2_PIX_FMT_GREY``, + i. e. each sample consists of 8 bits with lower values oriented + towards the black level. Do not assume any other correlation of + values with the signal level. For example, the MSB does not + necessarily indicate if the signal is 'high' or 'low' because 128 + may not be the mean value of the signal. Drivers shall not convert + the sample format by software. + + - .. row 5 + + - __u32 + + - ``start``\ [2]_ + + - This is the scanning system line number associated with the first + line of the VBI image, of the first and the second field + respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid + values. The ``V4L2_VBI_ITU_525_F1_START``, + ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and + ``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers + for each field for each 525 or 625 line format as a convenience. + Don't forget that ITU line numbering starts at 1, not 0. VBI input + drivers can return start values 0 if the hardware cannot reliable + identify scanning lines, VBI acquisition may not require this + information. + + - .. row 6 + + - __u32 + + - ``count``\ [2]_ + + - The number of lines in the first and second field image, + respectively. + + - .. row 7 + + - :cspan:`2` + + Drivers should be as flexibility as possible. For example, it may + be possible to extend or move the VBI capture window down to the + picture area, implementing a 'full field mode' to capture data + service transmissions embedded in the picture. + + An application can set the first or second ``count`` value to zero + if no data is required from the respective field; ``count``\ [1] + if the scanning system is progressive, i. e. not interlaced. The + corresponding start value shall be ignored by the application and + driver. Anyway, drivers may not support single field capturing and + return both count values non-zero. + + Both ``count`` values set to zero, or line numbers outside the + bounds depicted in :ref:`vbi-525` and :ref:`vbi-625`, or a + field image covering lines of two fields, are invalid and shall + not be returned by the driver. + + To initialize the ``start`` and ``count`` fields, applications + must first determine the current video standard selection. The + :ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field + of struct :ref:`v4l2_standard <v4l2-standard>` can be evaluated + for this purpose. + + - .. row 8 + + - __u32 + + - ``flags`` + + - See :ref:`vbifmt-flags` below. Currently only drivers set flags, + applications must set this field to zero. + + - .. row 9 + + - __u32 + + - ``reserved``\ [2]_ + + - This array is reserved for future extensions. Drivers and + applications must set it to zero. + + + +.. _vbifmt-flags: + +.. flat-table:: Raw VBI Format Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_VBI_UNSYNC`` + + - 0x0001 + + - This flag indicates hardware which does not properly distinguish + between fields. Normally the VBI image stores the first field + (lower scanning line numbers) first in memory. This may be a top + or bottom field depending on the video standard. When this flag is + set the first or second field may be stored first, however the + fields are still in correct temporal order with the older field + first in memory. [3]_ + + - .. row 2 + + - ``V4L2_VBI_INTERLACED`` + + - 0x0002 + + - By default the two field images will be passed sequentially; all + lines of the first field followed by all lines of the second field + (compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and + ``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in + memory depends on the video standard). When this flag is set, the + two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The + first line of the first field followed by the first line of the + second field, then the two second lines, and so on. Such a layout + may be necessary when the hardware has been programmed to capture + or output interlaced video images and is unable to separate the + fields for VBI capturing at the same time. For simplicity setting + this flag implies that both ``count`` values are equal and + non-zero. + + + +.. _vbi-hsync: + +.. figure:: dev-raw-vbi_files/vbi_hsync.* + :alt: vbi_hsync.pdf / vbi_hsync.gif + :align: center + + **Figure 4.1. Line synchronization** + + +.. _vbi-525: + +.. figure:: dev-raw-vbi_files/vbi_525.* + :alt: vbi_525.pdf / vbi_525.gif + :align: center + + **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)** + + + +.. _vbi-625: + +.. figure:: dev-raw-vbi_files/vbi_625.* + :alt: vbi_625.pdf / vbi_625.gif + :align: center + + **Figure 4.3. ITU-R 625 line numbering** + + + +Remember the VBI image format depends on the selected video standard, +therefore the application must choose a new standard or query the +current standard first. Attempts to read or write data ahead of format +negotiation, or after switching the video standard which may invalidate +the negotiated VBI parameters, should be refused by the driver. A format +change during active I/O is not permitted. + + +Reading and writing VBI images +============================== + +To assure synchronization with the field number and easier +implementation, the smallest unit of data passed at a time is one frame, +consisting of two fields of VBI images immediately following in memory. + +The total size of a frame computes as follows: + + +.. code-block:: c + + (count[0] + count[1]) * samples_per_line * sample size in bytes + +The sample size is most likely always one byte, applications must check +the ``sample_format`` field though, to function properly with other +drivers. + +A VBI device may support :ref:`read/write <rw>` and/or streaming +(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O. +The latter bears the possibility of synchronizing video and VBI data by +using buffer timestamps. + +Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the +first :ref:`read() <func-read>`, :ref:`write() <func-write>` and +:ref:`select() <func-select>` call can be resource allocation +points returning an ``EBUSY`` error code if the required hardware resources +are temporarily unavailable, for example the device is already in use by +another process. + +.. [1] + ASK: Amplitude-Shift Keying. A high signal level represents a '1' + bit, a low level a '0' bit. + +.. [2] + A few devices may be unable to sample VBI data at all but can extend + the video capture window to the VBI region. + +.. [3] + Most VBI services transmit on both fields, but some have different + semantics depending on the field number. These cannot be reliable + decoded or encoded when ``V4L2_VBI_UNSYNC`` is set. diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif Binary files differnew file mode 100644 index 000000000000..5580b690d504 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf Binary files differnew file mode 100644 index 000000000000..9e72c25b208d --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif Binary files differnew file mode 100644 index 000000000000..34e3251983c4 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf Binary files differnew file mode 100644 index 000000000000..765235e33a4d --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif Binary files differnew file mode 100644 index 000000000000..b02434d3b356 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf Binary files differnew file mode 100644 index 000000000000..200b668189bf --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf diff --git a/Documentation/media/uapi/v4l/dev-rds.rst b/Documentation/media/uapi/v4l/dev-rds.rst new file mode 100644 index 000000000000..6a0b1a874668 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-rds.rst @@ -0,0 +1,255 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _rds: + +************* +RDS Interface +************* + +The Radio Data System transmits supplementary information in binary +format, for example the station name or travel information, on an +inaudible audio subcarrier of a radio program. This interface is aimed +at devices capable of receiving and/or transmitting RDS information. + +For more information see the core RDS standard :ref:`iec62106` and the +RBDS standard :ref:`nrsc4`. + +Note that the RBDS standard as is used in the USA is almost identical to +the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only +some of the fields have slightly different meanings. See the RBDS +standard for more information. + +The RBDS standard also specifies support for MMBS (Modified Mobile +Search). This is a proprietary format which seems to be discontinued. +The RDS interface does not support this format. Should support for MMBS +(or the so-called 'E blocks' in general) be needed, then please contact +the linux-media mailing list: +`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. + + +Querying Capabilities +===================== + +Devices supporting the RDS capturing API set the +``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that +supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the +``capability`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`. If the +driver only passes RDS blocks without interpreting the data the +``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see +:ref:`Reading RDS data <reading-rds-data>`. For future use the flag +``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver +for a radio tuner with this capability does not yet exist, so if you are +planning to write such a driver you should discuss this on the +linux-media mailing list: +`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. + +Whether an RDS signal is present can be detected by looking at the +``rxsubchans`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`: the +``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected. + +Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT`` +flag in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that +supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the +``capability`` field of struct +:ref:`v4l2_modulator <v4l2-modulator>`. In order to enable the RDS +transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the +``txsubchans`` field of struct +:ref:`v4l2_modulator <v4l2-modulator>`. If the driver only passes RDS +blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` +flag has to be set. If the tuner is capable of handling RDS entities +like program identification codes and radio text, the flag +``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see +:ref:`Writing RDS data <writing-rds-data>` and +:ref:`FM Transmitter Control Reference <fm-tx-controls>`. + + +.. _reading-rds-data: + +Reading RDS data +================ + +RDS data can be read from the radio device with the +:ref:`read() <func-read>` function. The data is packed in groups of +three bytes. + + +.. _writing-rds-data: + +Writing RDS data +================ + +RDS data can be written to the radio device with the +:ref:`write() <func-write>` function. The data is packed in groups of +three bytes, as follows: + + +RDS datastructures +================== + + +.. _v4l2-rds-data: + +.. flat-table:: struct v4l2_rds_data + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 5 + + + - .. row 1 + + - __u8 + + - ``lsb`` + + - Least Significant Byte of RDS Block + + - .. row 2 + + - __u8 + + - ``msb`` + + - Most Significant Byte of RDS Block + + - .. row 3 + + - __u8 + + - ``block`` + + - Block description + + + +.. _v4l2-rds-block: + +.. flat-table:: Block description + :header-rows: 0 + :stub-columns: 0 + :widths: 1 5 + + + - .. row 1 + + - Bits 0-2 + + - Block (aka offset) of the received data. + + - .. row 2 + + - Bits 3-5 + + - Deprecated. Currently identical to bits 0-2. Do not use these + bits. + + - .. row 3 + + - Bit 6 + + - Corrected bit. Indicates that an error was corrected for this data + block. + + - .. row 4 + + - Bit 7 + + - Error bit. Indicates that an uncorrectable error occurred during + reception of this block. + + + +.. _v4l2-rds-block-codes: + +.. flat-table:: Block defines + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 5 + + + - .. row 1 + + - V4L2_RDS_BLOCK_MSK + + - + - 7 + + - Mask for bits 0-2 to get the block ID. + + - .. row 2 + + - V4L2_RDS_BLOCK_A + + - + - 0 + + - Block A. + + - .. row 3 + + - V4L2_RDS_BLOCK_B + + - + - 1 + + - Block B. + + - .. row 4 + + - V4L2_RDS_BLOCK_C + + - + - 2 + + - Block C. + + - .. row 5 + + - V4L2_RDS_BLOCK_D + + - + - 3 + + - Block D. + + - .. row 6 + + - V4L2_RDS_BLOCK_C_ALT + + - + - 4 + + - Block C'. + + - .. row 7 + + - V4L2_RDS_BLOCK_INVALID + + - read-only + + - 7 + + - An invalid block. + + - .. row 8 + + - V4L2_RDS_BLOCK_CORRECTED + + - read-only + + - 0x40 + + - A bit error was detected but corrected. + + - .. row 9 + + - V4L2_RDS_BLOCK_ERROR + + - read-only + + - 0x80 + + - An uncorrectable error occurred. diff --git a/Documentation/media/uapi/v4l/dev-sdr.rst b/Documentation/media/uapi/v4l/dev-sdr.rst new file mode 100644 index 000000000000..fc4053f957fb --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-sdr.rst @@ -0,0 +1,120 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _sdr: + +************************************** +Software Defined Radio Interface (SDR) +************************************** + +SDR is an abbreviation of Software Defined Radio, the radio device which +uses application software for modulation or demodulation. This interface +is intended for controlling and data streaming of such devices. + +SDR devices are accessed through character device special files named +``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and +dynamically allocated minor numbers 0 to 255. + + +Querying Capabilities +===================== + +Devices supporting the SDR receiver interface set the +``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the +``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the +device has an Analog to Digital Converter (ADC), which is a mandatory +element for the SDR receiver. + +Devices supporting the SDR transmitter interface set the +``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the +``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the +device has an Digital to Analog Converter (DAC), which is a mandatory +element for the SDR transmitter. + +At least one of the read/write, streaming or asynchronous I/O methods +must be supported. + + +Supplemental Functions +====================== + +SDR devices can support :ref:`controls <control>`, and must support +the :ref:`tuner` ioctls. Tuner ioctls are used for setting the +ADC/DAC sampling rate (sampling frequency) and the possible radio +frequency (RF). + +The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC +frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting +radio frequency. The tuner index of the RF tuner (if any) must always +follow the SDR tuner index. Normally the SDR tuner is #0 and the RF +tuner is #1. + +The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is +not supported. + + +Data Format Negotiation +======================= + +The SDR device uses the :ref:`format` ioctls to select the +capture and output format. Both the sampling resolution and the data +streaming format are bound to that selectable format. In addition to the +basic :ref:`format` ioctls, the +:ref:`VIDIOC_ENUM_FMT` ioctl must be supported as +well. + +To use the :ref:`format` ioctls applications set the ``type`` +field of a struct :ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use +the struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` ``sdr`` member +of the ``fmt`` union as needed per the desired operation. Currently +there is two fields, ``pixelformat`` and ``buffersize``, of struct +struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` which are used. +Content of the ``pixelformat`` is V4L2 FourCC code of the data format. +The ``buffersize`` field is maximum buffer size in bytes required for +data transfer, set by the driver in order to inform application. + + +.. _v4l2-sdr-format: + +.. flat-table:: struct v4l2_sdr_format + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``pixelformat`` + + - The data format or type of compression, set by the application. + This is a little endian + :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR + formats in :ref:`sdr-formats`. + + - .. row 2 + + - __u32 + + - ``buffersize`` + + - Maximum size in bytes required for data. Value is set by the + driver. + + - .. row 3 + + - __u8 + + - ``reserved[24]`` + + - This array is reserved for future extensions. Drivers and + applications must set it to zero. + + +An SDR device may support :ref:`read/write <rw>` and/or streaming +(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O. diff --git a/Documentation/media/uapi/v4l/dev-sliced-vbi.rst b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst new file mode 100644 index 000000000000..fbd04fee0484 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst @@ -0,0 +1,822 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _sliced: + +************************* +Sliced VBI Data Interface +************************* + +VBI stands for Vertical Blanking Interval, a gap in the sequence of +lines of an analog video signal. During VBI no picture information is +transmitted, allowing some time while the electron beam of a cathode ray +tube TV returns to the top of the screen. + +Sliced VBI devices use hardware to demodulate data transmitted in the +VBI. V4L2 drivers shall *not* do this by software, see also the +:ref:`raw VBI interface <raw-vbi>`. The data is passed as short +packets of fixed size, covering one scan line each. The number of +packets per video frame is variable. + +Sliced VBI capture and output devices are accessed through the same +character special files as raw VBI devices. When a driver supports both +interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI +capturing or output, and the sliced VBI function is only available after +calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as defined +below. Likewise a ``/dev/video`` device may support the sliced VBI API, +however the default function here is video capturing or output. +Different file descriptors must be used to pass raw and sliced VBI data +simultaneously, if this is supported by the driver. + + +Querying Capabilities +===================== + +Devices supporting the sliced VBI capturing or output API set the +``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag +respectively, in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the +read/write, streaming or asynchronous :ref:`I/O methods <io>` must be +supported. Sliced VBI devices may have a tuner or modulator. + + +Supplemental Functions +====================== + +Sliced VBI devices shall support :ref:`video input or output <video>` +and :ref:`tuner or modulator <tuner>` ioctls if they have these +capabilities, and they may support :ref:`control` ioctls. +The :ref:`video standard <standard>` ioctls provide information vital +to program a sliced VBI device, therefore must be supported. + + +.. _sliced-vbi-format-negotitation: + +Sliced VBI Format Negotiation +============================= + +To find out which data services are supported by the hardware +applications can call the +:ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. +All drivers implementing the sliced VBI interface must support this +ioctl. The results may differ from those of the +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl when the number of VBI +lines the hardware can capture or output per frame, or the number of +services it can identify on a given line are limited. For example on PAL +line 16 the hardware may be able to look for a VPS or Teletext signal, +but not both at the same time. + +To determine the currently selected services applications set the +``type`` field of struct :ref:`v4l2_format <v4l2-format>` to +``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or +``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl fills the ``fmt.sliced`` +member, a struct +:ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`. + +Applications can request different parameters by initializing or +modifying the ``fmt.sliced`` member and calling the +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with a pointer to the +:ref:`struct v4l2_format <v4l2-format>` structure. + +The sliced VBI API is more complicated than the raw VBI API because the +hardware must be told which VBI service to expect on each scan line. Not +all services may be supported by the hardware on all lines (this is +especially true for VBI output where Teletext is often unsupported and +other services can only be inserted in one specific line). In many +cases, however, it is sufficient to just set the ``service_set`` field +to the required services and let the driver fill the ``service_lines`` +array according to hardware capabilities. Only if more precise control +is needed should the programmer set the ``service_lines`` array +explicitly. + +The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl modifies the parameters +according to hardware capabilities. When the driver allocates resources +at this point, it may return an ``EBUSY`` error code if the required +resources are temporarily unavailable. Other resource allocation points +which may return ``EBUSY`` can be the +:ref:`VIDIOC_STREAMON` ioctl and the first +:ref:`read() <func-read>`, :ref:`write() <func-write>` and +:ref:`select() <func-select>` call. + + +.. _v4l2-sliced-vbi-format: + +struct v4l2_sliced_vbi_format +----------------------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 3 2 2 2 + + + - .. row 1 + + - __u32 + + - ``service_set`` + + - :cspan:`2` + + If ``service_set`` is non-zero when passed with + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or + :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines`` + array will be filled by the driver according to the services + specified in this field. For example, if ``service_set`` is + initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``, + a driver for the cx25840 video decoder sets lines 7-22 of both + fields [1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first + field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to + zero, then the values of ``service_lines`` will be used instead. + + On return the driver sets this field to the union of all elements + of the returned ``service_lines`` array. It may contain less + services than requested, perhaps just one, if the hardware cannot + handle more services simultaneously. It may be empty (zero) if + none of the requested services are supported by the hardware. + + - .. row 2 + + - __u16 + + - ``service_lines``\ [2][24] + + - :cspan:`2` + + Applications initialize this array with sets of data services the + driver shall look for or insert on the respective scan line. + Subject to hardware capabilities drivers return the requested set, + a subset, which may be just a single service, or an empty set. + When the hardware cannot handle multiple services on the same line + the driver shall choose one. No assumptions can be made on which + service the driver chooses. + + Data services are defined in :ref:`vbi-services2`. Array indices + map to ITU-R line numbers (see also :ref:`vbi-525` and + :ref:`vbi-625`) as follows: + + - .. row 3 + + - + - + - Element + + - 525 line systems + + - 625 line systems + + - .. row 4 + + - + - + - ``service_lines``\ [0][1] + + - 1 + + - 1 + + - .. row 5 + + - + - + - ``service_lines``\ [0][23] + + - 23 + + - 23 + + - .. row 6 + + - + - + - ``service_lines``\ [1][1] + + - 264 + + - 314 + + - .. row 7 + + - + - + - ``service_lines``\ [1][23] + + - 286 + + - 336 + + - .. row 8 + + - + - + - :cspan:`2` Drivers must set ``service_lines`` [0][0] and + ``service_lines``\ [1][0] to zero. The + ``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``, + ``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START`` + defines give the start line numbers for each field for each 525 or + 625 line format as a convenience. Don't forget that ITU line + numbering starts at 1, not 0. + + - .. row 9 + + - __u32 + + - ``io_size`` + + - :cspan:`2` Maximum number of bytes passed by one + :ref:`read() <func-read>` or :ref:`write() <func-write>` call, + and the buffer size in bytes for the + :ref:`VIDIOC_QBUF` and + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field + to the size of struct + :ref:`v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` times the + number of non-zero elements in the returned ``service_lines`` + array (that is the number of lines potentially carrying data). + + - .. row 10 + + - __u32 + + - ``reserved``\ [2] + + - :cspan:`2` This array is reserved for future extensions. + Applications and drivers must set it to zero. + + + +.. _vbi-services2: + +Sliced VBI services +------------------- + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 2 1 1 2 2 + + + - .. row 1 + + - Symbol + + - Value + + - Reference + + - Lines, usually + + - Payload + + - .. row 2 + + - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B) + + - 0x0001 + + - :ref:`ets300706`, :ref:`itu653` + + - PAL/SECAM line 7-22, 320-335 (second field 7-22) + + - Last 42 of the 45 byte Teletext packet, that is without clock + run-in and framing code, lsb first transmitted. + + - .. row 3 + + - ``V4L2_SLICED_VPS`` + + - 0x0400 + + - :ref:`ets300231` + + - PAL line 16 + + - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb + first transmitted. + + - .. row 4 + + - ``V4L2_SLICED_CAPTION_525`` + + - 0x1000 + + - :ref:`cea608` + + - NTSC line 21, 284 (second field 21) + + - Two bytes in transmission order, including parity bit, lsb first + transmitted. + + - .. row 5 + + - ``V4L2_SLICED_WSS_625`` + + - 0x4000 + + - :ref:`itu1119`, :ref:`en300294` + + - PAL/SECAM line 23 + + - + + :: + + Byte 0 1 + msb lsb msb lsb + Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + + - .. row 6 + + - ``V4L2_SLICED_VBI_525`` + + - 0x1000 + + - :cspan:`2` Set of services applicable to 525 line systems. + + - .. row 7 + + - ``V4L2_SLICED_VBI_625`` + + - 0x4401 + + - :cspan:`2` Set of services applicable to 625 line systems. + + +Drivers may return an ``EINVAL`` error code when applications attempt to +read or write data without prior format negotiation, after switching the +video standard (which may invalidate the negotiated VBI parameters) and +after switching the video input (which may change the video standard as +a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may +return an ``EBUSY`` error code when applications attempt to change the +format while i/o is in progress (between a +:ref:`VIDIOC_STREAMON` and +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first +:ref:`read() <func-read>` or :ref:`write() <func-write>` call). + + +Reading and writing sliced VBI data +=================================== + +A single :ref:`read() <func-read>` or :ref:`write() <func-write>` +call must pass all data belonging to one video frame. That is an array +of :ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` structures with one or +more elements and a total size not exceeding ``io_size`` bytes. Likewise +in streaming I/O mode one buffer of ``io_size`` bytes must contain data +of one video frame. The ``id`` of unused +:ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` elements must be zero. + + +.. _v4l2-sliced-vbi-data: + +struct v4l2_sliced_vbi_data +--------------------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - __u32 + + - ``id`` + + - A flag from :ref:`vbi-services` identifying the type of data in + this packet. Only a single bit must be set. When the ``id`` of a + captured packet is zero, the packet is empty and the contents of + other fields are undefined. Applications shall ignore empty + packets. When the ``id`` of a packet for output is zero the + contents of the ``data`` field are undefined and the driver must + no longer insert data on the requested ``field`` and ``line``. + + - .. row 2 + + - __u32 + + - ``field`` + + - The video field number this data has been captured from, or shall + be inserted at. ``0`` for the first field, ``1`` for the second + field. + + - .. row 3 + + - __u32 + + - ``line`` + + - The field (as opposed to frame) line number this data has been + captured from, or shall be inserted at. See :ref:`vbi-525` and + :ref:`vbi-625` for valid values. Sliced VBI capture devices can + set the line number of all packets to ``0`` if the hardware cannot + reliably identify scan lines. The field number must always be + valid. + + - .. row 4 + + - __u32 + + - ``reserved`` + + - This field is reserved for future extensions. Applications and + drivers must set it to zero. + + - .. row 5 + + - __u8 + + - ``data``\ [48] + + - The packet payload. See :ref:`vbi-services` for the contents and + number of bytes passed for each data type. The contents of padding + bytes at the end of this array are undefined, drivers and + applications shall ignore them. + + +Packets are always passed in ascending line number order, without +duplicate line numbers. The :ref:`write() <func-write>` function and +the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL`` +error code when applications violate this rule. They must also return an +EINVAL error code when applications pass an incorrect field or line +number, or a combination of ``field``, ``line`` and ``id`` which has not +been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are +unknown the driver must pass the packets in transmitted order. The +driver can insert empty packets with ``id`` set to zero anywhere in the +packet array. + +To assure synchronization and to distinguish from frame dropping, when a +captured frame does not carry any of the requested data services drivers +must pass one or more empty packets. When an application fails to pass +VBI data in time for output, the driver must output the last VPS and WSS +packet again, and disable the output of Closed Caption and Teletext +data, or output data which is ignored by Closed Caption and Teletext +decoders. + +A sliced VBI device may support :ref:`read/write <rw>` and/or +streaming (:ref:`memory mapping <mmap>` and/or +:ref:`user pointer <userp>`) I/O. The latter bears the possibility of +synchronizing video and VBI data by using buffer timestamps. + + +Sliced VBI Data in MPEG Streams +=============================== + +If a device can produce an MPEG output stream, it may be capable of +providing +:ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>` +as data embedded in the MPEG stream. Users or applications control this +sliced VBI data insertion with the +:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>` +control. + +If the driver does not provide the +:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>` +control, or only allows that control to be set to +:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`, +then the device cannot embed sliced VBI data in the MPEG stream. + +The +:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>` +control does not implicitly set the device driver to capture nor cease +capturing sliced VBI data. The control only indicates to embed sliced +VBI data in the MPEG stream, if an application has negotiated sliced VBI +service be captured. + +It may also be the case that a device can embed sliced VBI data in only +certain types of MPEG streams: for example in an MPEG-2 PS but not an +MPEG-2 TS. In this situation, if sliced VBI data insertion is requested, +the sliced VBI data will be embedded in MPEG stream types when +supported, and silently omitted from MPEG stream types where sliced VBI +data insertion is not supported by the device. + +The following subsections specify the format of the embedded sliced VBI +data. + + +MPEG Stream Embedded, Sliced VBI Data Format: NONE +-------------------------------------------------- + +The +:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>` +embedded sliced VBI format shall be interpreted by drivers as a control +to cease embedding sliced VBI data in MPEG streams. Neither the device +nor driver shall insert "empty" embedded sliced VBI data packets in the +MPEG stream when this format is set. No MPEG stream data structures are +specified for this format. + + +MPEG Stream Embedded, Sliced VBI Data Format: IVTV +-------------------------------------------------- + +The +:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>` +embedded sliced VBI format, when supported, indicates to the driver to +embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private +Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the +MPEG stream. + +*Historical context*: This format specification originates from a +custom, embedded, sliced VBI data format used by the ``ivtv`` driver. +This format has already been informally specified in the kernel sources +in the file ``Documentation/video4linux/cx2341x/README.vbi`` . The +maximum size of the payload and other aspects of this format are driven +by the CX23415 MPEG decoder's capabilities and limitations with respect +to extracting, decoding, and displaying sliced VBI data embedded within +an MPEG stream. + +This format's use is *not* exclusive to the ``ivtv`` driver *nor* +exclusive to CX2341x devices, as the sliced VBI data packet insertion +into the MPEG stream is implemented in driver software. At least the +``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in +this format as well. + +The following definitions specify the payload of the MPEG-2 *Private +Stream 1 PES* packets that contain sliced VBI data when +:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>` +is set. (The MPEG-2 *Private Stream 1 PES* packet header and +encapsulating MPEG-2 *Program Pack* header are not detailed here. Please +refer to the MPEG-2 specifications for details on those packet headers.) + +The payload of the MPEG-2 *Private Stream 1 PES* packets that contain +sliced VBI data is specified by struct +:ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>`. The +payload is variable length, depending on the actual number of lines of +sliced VBI data present in a video frame. The payload may be padded at +the end with unspecified fill bytes to align the end of the payload to a +4-byte boundary. The payload shall never exceed 1552 bytes (2 fields +with 18 lines/field with 43 bytes of data/line and a 4 byte magic +number). + + +.. _v4l2-mpeg-vbi-fmt-ivtv: + +struct v4l2_mpeg_vbi_fmt_ivtv +----------------------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __u8 + + - ``magic``\ [4] + + - + - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that + indicates this is a valid sliced VBI data payload and also + indicates which member of the anonymous union, ``itv0`` or + ``ITV0``, to use for the payload data. + + - .. row 2 + + - union + + - (anonymous) + + - .. row 3 + + - + - struct :ref:`v4l2_mpeg_vbi_itv0 <v4l2-mpeg-vbi-itv0>` + + - ``itv0`` + + - The primary form of the sliced VBI data payload that contains + anywhere from 1 to 35 lines of sliced VBI data. Line masks are + provided in this form of the payload indicating which VBI lines + are provided. + + - .. row 4 + + - + - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>` + + - ``ITV0`` + + - An alternate form of the sliced VBI data payload used when 36 + lines of sliced VBI data are present. No line masks are provided + in this form of the payload; all valid line mask bits are + implcitly set. + + + +.. _v4l2-mpeg-vbi-fmt-ivtv-magic: + +Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field +------------------------------------------------------------- + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - Defined Symbol + + - Value + + - Description + + - .. row 2 + + - ``V4L2_MPEG_VBI_IVTV_MAGIC0`` + + - "itv0" + + - Indicates the ``itv0`` member of the union in struct + :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is + valid. + + - .. row 3 + + - ``V4L2_MPEG_VBI_IVTV_MAGIC1`` + + - "ITV0" + + - Indicates the ``ITV0`` member of the union in struct + :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is + valid and that 36 lines of sliced VBI data are present. + + + +.. _v4l2-mpeg-vbi-itv0: + +struct v4l2_mpeg_vbi_itv0 +------------------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __le32 + + - ``linemask``\ [2] + + - Bitmasks indicating the VBI service lines present. These + ``linemask`` values are stored in little endian byte order in the + MPEG stream. Some reference ``linemask`` bit positions with their + corresponding VBI line number and video field are given below. + b\ :sub:`0` indicates the least significant bit of a ``linemask`` + value: + + + + :: + + 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 + + - .. row 2 + + - struct + :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>` + + - ``line``\ [35] + + - This is a variable length array that holds from 1 to 35 lines of + sliced VBI data. The sliced VBI data lines present correspond to + the bits set in the ``linemask`` array, starting from b\ :sub:`0` + of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0], + and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of + ``linemask``\ [1]. ``line``\ [0] corresponds to the first bit + found set in the ``linemask`` array, ``line``\ [1] corresponds to + the second bit found set in the ``linemask`` array, etc. If no + ``linemask`` array bits are set, then ``line``\ [0] may contain + one line of unspecified data that should be ignored by + applications. + + + +.. _v4l2-mpeg-vbi-itv0-1: + +struct v4l2_mpeg_vbi_ITV0 +------------------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - struct + :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>` + + - ``line``\ [36] + + - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0] + through ``line``\ [17] correspond to lines 6 through 23 of the + first field. ``line``\ [18] through ``line``\ [35] corresponds to + lines 6 through 23 of the second field. + + + +.. _v4l2-mpeg-vbi-itv0-line: + +struct v4l2_mpeg_vbi_itv0_line +------------------------------ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u8 + + - ``id`` + + - A line identifier value from + :ref:`ITV0-Line-Identifier-Constants` that indicates the type of + sliced VBI data stored on this line. + + - .. row 2 + + - __u8 + + - ``data``\ [42] + + - The sliced VBI data for the line. + + + +.. _ITV0-Line-Identifier-Constants: + +Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field +------------------------------------------------------------ + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - Defined Symbol + + - Value + + - Description + + - .. row 2 + + - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B`` + + - 1 + + - Refer to :ref:`Sliced VBI services <vbi-services2>` for a + description of the line payload. + + - .. row 3 + + - ``V4L2_MPEG_VBI_IVTV_CAPTION_525`` + + - 4 + + - Refer to :ref:`Sliced VBI services <vbi-services2>` for a + description of the line payload. + + - .. row 4 + + - ``V4L2_MPEG_VBI_IVTV_WSS_625`` + + - 5 + + - Refer to :ref:`Sliced VBI services <vbi-services2>` for a + description of the line payload. + + - .. row 5 + + - ``V4L2_MPEG_VBI_IVTV_VPS`` + + - 7 + + - Refer to :ref:`Sliced VBI services <vbi-services2>` for a + description of the line payload. + + + +.. [1] + According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first + field and lines 5-22 of the second field may carry Teletext data. diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst new file mode 100644 index 000000000000..39d3d860dda4 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev.rst @@ -0,0 +1,491 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _subdev: + +******************** +Sub-device Interface +******************** + +The complex nature of V4L2 devices, where hardware is often made of +several integrated circuits that need to interact with each other in a +controlled way, leads to complex V4L2 drivers. The drivers usually +reflect the hardware model in software, and model the different hardware +components as software blocks called sub-devices. + +V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver +implements the media device API, they will automatically inherit from +media entities. Applications will be able to enumerate the sub-devices +and discover the hardware topology using the media entities, pads and +links enumeration API. + +In addition to make sub-devices discoverable, drivers can also choose to +make them directly configurable by applications. When both the +sub-device driver and the V4L2 device driver support this, sub-devices +will feature a character device node on which ioctls can be called to + +- query, read and write sub-devices controls + +- subscribe and unsubscribe to events and retrieve them + +- negotiate image formats on individual pads + +Sub-device character device nodes, conventionally named +``/dev/v4l-subdev*``, use major number 81. + + +Controls +======== + +Most V4L2 controls are implemented by sub-device hardware. Drivers +usually merge all controls and expose them through video device nodes. +Applications can control all sub-devices through a single interface. + +Complex devices sometimes implement the same control in different pieces +of hardware. This situation is common in embedded platforms, where both +sensors and image processing hardware implement identical functions, +such as contrast adjustment, white balance or faulty pixels correction. +As the V4L2 controls API doesn't support several identical controls in a +single device, all but one of the identical controls are hidden. + +Applications can access those hidden controls through the sub-device +node with the V4L2 control API described in :ref:`control`. The ioctls +behave identically as when issued on V4L2 device nodes, with the +exception that they deal only with controls implemented in the +sub-device. + +Depending on the driver, those controls might also be exposed through +one (or several) V4L2 device nodes. + + +Events +====== + +V4L2 sub-devices can notify applications of events as described in +:ref:`event`. The API behaves identically as when used on V4L2 device +nodes, with the exception that it only deals with events generated by +the sub-device. Depending on the driver, those events might also be +reported on one (or several) V4L2 device nodes. + + +.. _pad-level-formats: + +Pad-level Formats +================= + + **Warning** + + Pad-level formats are only applicable to very complex device that + need to expose low-level format configuration to user space. Generic + V4L2 applications do *not* need to use the API described in this + section. + + **Note** + + For the purpose of this section, the term *format* means the + combination of media bus data format, frame width and frame height. + +Image formats are typically negotiated on video capture and output +devices using the format and +:ref:`selection <VIDIOC_SUBDEV_G_SELECTION>` ioctls. The driver is +responsible for configuring every block in the video pipeline according +to the requested format at the pipeline input and/or output. + +For complex devices, such as often found in embedded systems, identical +image sizes at the output of a pipeline can be achieved using different +hardware configurations. One such example is shown on +:ref:`pipeline-scaling`, where image scaling can be performed on both +the video sensor and the host image processing hardware. + + +.. _pipeline-scaling: + +.. figure:: dev-subdev_files/pipeline.* + :alt: pipeline.pdf / pipeline.png + :align: center + + Image Format Negotiation on Pipelines + + High quality and high speed pipeline configuration + + + +The sensor scaler is usually of less quality than the host scaler, but +scaling on the sensor is required to achieve higher frame rates. +Depending on the use case (quality vs. speed), the pipeline must be +configured differently. Applications need to configure the formats at +every point in the pipeline explicitly. + +Drivers that implement the :ref:`media API <media-controller-intro>` +can expose pad-level image format configuration to applications. When +they do, applications can use the +:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and +:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls. to +negotiate formats on a per-pad basis. + +Applications are responsible for configuring coherent parameters on the +whole pipeline and making sure that connected pads have compatible +formats. The pipeline is checked for formats mismatch at +:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` time, and an ``EPIPE`` error +code is then returned if the configuration is invalid. + +Pad-level image format configuration support can be tested by calling +the :ref:`VIDIOC_SUBDEV_G_FMT` ioctl on pad +0. If the driver returns an ``EINVAL`` error code pad-level format +configuration is not supported by the sub-device. + + +Format Negotiation +------------------ + +Acceptable formats on pads can (and usually do) depend on a number of +external parameters, such as formats on other pads, active links, or +even controls. Finding a combination of formats on all pads in a video +pipeline, acceptable to both application and driver, can't rely on +formats enumeration only. A format negotiation mechanism is required. + +Central to the format negotiation mechanism are the get/set format +operations. When called with the ``which`` argument set to +:ref:`V4L2_SUBDEV_FORMAT_TRY <VIDIOC_SUBDEV_G_FMT>`, the +:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and +:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls operate on +a set of formats parameters that are not connected to the hardware +configuration. Modifying those 'try' formats leaves the device state +untouched (this applies to both the software state stored in the driver +and the hardware state stored in the device itself). + +While not kept as part of the device state, try formats are stored in +the sub-device file handles. A +:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` call will return +the last try format set *on the same sub-device file handle*. Several +applications querying the same sub-device at the same time will thus not +interact with each other. + +To find out whether a particular format is supported by the device, +applications use the +:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl. Drivers +verify and, if needed, change the requested ``format`` based on device +requirements and return the possibly modified value. Applications can +then choose to try a different format or accept the returned value and +continue. + +Formats returned by the driver during a negotiation iteration are +guaranteed to be supported by the device. In particular, drivers +guarantee that a returned format will not be further changed if passed +to an :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` call as-is +(as long as external parameters, such as formats on other pads or links' +configuration are not changed). + +Drivers automatically propagate formats inside sub-devices. When a try +or active format is set on a pad, corresponding formats on other pads of +the same sub-device can be modified by the driver. Drivers are free to +modify formats as required by the device. However, they should comply +with the following rules when possible: + +- Formats should be propagated from sink pads to source pads. Modifying + a format on a source pad should not modify the format on any sink + pad. + +- Sub-devices that scale frames using variable scaling factors should + reset the scale factors to default values when sink pads formats are + modified. If the 1:1 scaling ratio is supported, this means that + source pads formats should be reset to the sink pads formats. + +Formats are not propagated across links, as that would involve +propagating them from one sub-device file handle to another. +Applications must then take care to configure both ends of every link +explicitly with compatible formats. Identical formats on the two ends of +a link are guaranteed to be compatible. Drivers are free to accept +different formats matching device requirements as being compatible. + +:ref:`sample-pipeline-config` shows a sample configuration sequence +for the pipeline described in :ref:`pipeline-scaling` (table columns +list entity names and pad numbers). + + +.. _sample-pipeline-config: + +.. flat-table:: Sample Pipeline Configuration + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - + - Sensor/0 format + + - Frontend/0 format + + - Frontend/1 format + + - Scaler/0 format + + - Scaler/0 compose selection rectangle + + - Scaler/1 format + + - .. row 2 + + - Initial state + + - 2048x1536/SGRBG8_1X8 + + - (default) + + - (default) + + - (default) + + - (default) + + - (default) + + - .. row 3 + + - Configure frontend sink format + + - 2048x1536/SGRBG8_1X8 + + - *2048x1536/SGRBG8_1X8* + + - *2046x1534/SGRBG8_1X8* + + - (default) + + - (default) + + - (default) + + - .. row 4 + + - Configure scaler sink format + + - 2048x1536/SGRBG8_1X8 + + - 2048x1536/SGRBG8_1X8 + + - 2046x1534/SGRBG8_1X8 + + - *2046x1534/SGRBG8_1X8* + + - *0,0/2046x1534* + + - *2046x1534/SGRBG8_1X8* + + - .. row 5 + + - Configure scaler sink compose selection + + - 2048x1536/SGRBG8_1X8 + + - 2048x1536/SGRBG8_1X8 + + - 2046x1534/SGRBG8_1X8 + + - 2046x1534/SGRBG8_1X8 + + - *0,0/1280x960* + + - *1280x960/SGRBG8_1X8* + + + +1. Initial state. The sensor source pad format is set to its native 3MP + size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the + host frontend and scaler sink and source pads have the default + values, as well as the compose rectangle on the scaler's sink pad. + +2. The application configures the frontend sink pad format's size to + 2048x1536 and its media bus code to V4L2_MBUS_FMT_SGRBG_1X8. The + driver propagates the format to the frontend source pad. + +3. The application configures the scaler sink pad format's size to + 2046x1534 and the media bus code to V4L2_MBUS_FMT_SGRBG_1X8 to + match the frontend source size and media bus code. The media bus code + on the sink pad is set to V4L2_MBUS_FMT_SGRBG_1X8. The driver + propagates the size to the compose selection rectangle on the + scaler's sink pad, and the format to the scaler source pad. + +4. The application configures the size of the compose selection + rectangle of the scaler's sink pad 1280x960. The driver propagates + the size to the scaler's source pad format. + +When satisfied with the try results, applications can set the active +formats by setting the ``which`` argument to +``V4L2_SUBDEV_FORMAT_ACTIVE``. Active formats are changed exactly as try +formats by drivers. To avoid modifying the hardware state during format +negotiation, applications should negotiate try formats first and then +modify the active settings using the try formats returned during the +last negotiation iteration. This guarantees that the active format will +be applied as-is by the driver without being modified. + + +.. _v4l2-subdev-selections: + +Selections: cropping, scaling and composition +--------------------------------------------- + +Many sub-devices support cropping frames on their input or output pads +(or possible even on both). Cropping is used to select the area of +interest in an image, typically on an image sensor or a video decoder. +It can also be used as part of digital zoom implementations to select +the area of the image that will be scaled up. + +Crop settings are defined by a crop rectangle and represented in a +struct :ref:`v4l2_rect <v4l2-rect>` by the coordinates of the top +left corner and the rectangle size. Both the coordinates and sizes are +expressed in pixels. + +As for pad formats, drivers store try and active rectangles for the +selection targets :ref:`v4l2-selections-common`. + +On sink pads, cropping is applied relative to the current pad format. +The pad format represents the image size as received by the sub-device +from the previous block in the pipeline, and the crop rectangle +represents the sub-image that will be transmitted further inside the +sub-device for processing. + +The scaling operation changes the size of the image by scaling it to new +dimensions. The scaling ratio isn't specified explicitly, but is implied +from the original and scaled image sizes. Both sizes are represented by +struct :ref:`v4l2_rect <v4l2-rect>`. + +Scaling support is optional. When supported by a subdev, the crop +rectangle on the subdev's sink pad is scaled to the size configured +using the +:ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>` IOCTL +using ``V4L2_SEL_TGT_COMPOSE`` selection target on the same pad. If the +subdev supports scaling but not composing, the top and left values are +not used and must always be set to zero. + +On source pads, cropping is similar to sink pads, with the exception +that the source size from which the cropping is performed, is the +COMPOSE rectangle on the sink pad. In both sink and source pads, the +crop rectangle must be entirely contained inside the source image size +for the crop operation. + +The drivers should always use the closest possible rectangle the user +requests on all selection targets, unless specifically told otherwise. +``V4L2_SEL_FLAG_GE`` and ``V4L2_SEL_FLAG_LE`` flags may be used to round +the image size either up or down. :ref:`v4l2-selection-flags` + + +Types of selection targets +-------------------------- + + +Actual targets +^^^^^^^^^^^^^^ + +Actual targets (without a postfix) reflect the actual hardware +configuration at any point of time. There is a BOUNDS target +corresponding to every actual target. + + +BOUNDS targets +^^^^^^^^^^^^^^ + +BOUNDS targets is the smallest rectangle that contains all valid actual +rectangles. It may not be possible to set the actual rectangle as large +as the BOUNDS rectangle, however. This may be because e.g. a sensor's +pixel array is not rectangular but cross-shaped or round. The maximum +size may also be smaller than the BOUNDS rectangle. + + +Order of configuration and format propagation +--------------------------------------------- + +Inside subdevs, the order of image processing steps will always be from +the sink pad towards the source pad. This is also reflected in the order +in which the configuration must be performed by the user: the changes +made will be propagated to any subsequent stages. If this behaviour is +not desired, the user must set ``V4L2_SEL_FLAG_KEEP_CONFIG`` flag. This +flag causes no propagation of the changes are allowed in any +circumstances. This may also cause the accessed rectangle to be adjusted +by the driver, depending on the properties of the underlying hardware. + +The coordinates to a step always refer to the actual size of the +previous step. The exception to this rule is the source compose +rectangle, which refers to the sink compose bounds rectangle --- if it +is supported by the hardware. + +1. Sink pad format. The user configures the sink pad format. This format + defines the parameters of the image the entity receives through the + pad for further processing. + +2. Sink pad actual crop selection. The sink pad crop defines the crop + performed to the sink pad format. + +3. Sink pad actual compose selection. The size of the sink pad compose + rectangle defines the scaling ratio compared to the size of the sink + pad crop rectangle. The location of the compose rectangle specifies + the location of the actual sink compose rectangle in the sink compose + bounds rectangle. + +4. Source pad actual crop selection. Crop on the source pad defines crop + performed to the image in the sink compose bounds rectangle. + +5. Source pad format. The source pad format defines the output pixel + format of the subdev, as well as the other parameters with the + exception of the image width and height. Width and height are defined + by the size of the source pad actual crop selection. + +Accessing any of the above rectangles not supported by the subdev will +return ``EINVAL``. Any rectangle referring to a previous unsupported +rectangle coordinates will instead refer to the previous supported +rectangle. For example, if sink crop is not supported, the compose +selection will refer to the sink pad format dimensions instead. + + +.. _subdev-image-processing-crop: + +.. figure:: dev-subdev_files/subdev-image-processing-crop.* + :alt: subdev-image-processing-crop.svg + :align: center + + **Figure 4.5. Image processing in subdevs: simple crop example** + +In the above example, the subdev supports cropping on its sink pad. To +configure it, the user sets the media bus format on the subdev's sink +pad. Now the actual crop rectangle can be set on the sink pad --- the +location and size of this rectangle reflect the location and size of a +rectangle to be cropped from the sink format. The size of the sink crop +rectangle will also be the size of the format of the subdev's source +pad. + + +.. _subdev-image-processing-scaling-multi-source: + +.. figure:: dev-subdev_files/subdev-image-processing-scaling-multi-source.* + :alt: subdev-image-processing-scaling-multi-source.svg + :align: center + + **Figure 4.6. Image processing in subdevs: scaling with multiple sources** + +In this example, the subdev is capable of first cropping, then scaling +and finally cropping for two source pads individually from the resulting +scaled image. The location of the scaled image in the cropped image is +ignored in sink compose target. Both of the locations of the source crop +rectangles refer to the sink scaling rectangle, independently cropping +an area at location specified by the source crop rectangle from it. + + +.. _subdev-image-processing-full: + +.. figure:: dev-subdev_files/subdev-image-processing-full.* + :alt: subdev-image-processing-full.svg + :align: center + + **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources** + +The subdev driver supports two sink pads and two source pads. The images +from both of the sink pads are individually cropped, then scaled and +further composed on the composition bounds rectangle. From that, two +independent streams are cropped and sent out of the subdev from the +source pads. + + +.. toctree:: + :maxdepth: 1 + + subdev-formats diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf Binary files differnew file mode 100644 index 000000000000..ee3e37f04b6a --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png Binary files differnew file mode 100644 index 000000000000..f19b86c2c24d --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf Binary files differnew file mode 100644 index 000000000000..29a806f839b4 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg new file mode 100644 index 000000000000..18b0f5de9ed2 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg @@ -0,0 +1,63 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> +<svg width="43cm" height="10cm" viewBox="-194 128 844 196" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="469.774" height="193"/> + <g> + <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/> + </g> + <g> + <rect style="fill: #ffffff" x="63.5" y="211" width="94" height="77"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="63.5" y="211" width="94" height="77"/> + </g> + <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="74.5" y="227.75"> + <tspan x="74.5" y="227.75">sink</tspan> + <tspan x="74.5" y="243.75">crop</tspan> + <tspan x="74.5" y="259.75">selection</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158"> + <tspan x="29.5" y="158"></tspan> + </text> + <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914"> + <tspan x="8.53836" y="157.914">sink media</tspan> + <tspan x="8.53836" y="173.914">bus format</tspan> + </text> + <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="349.774" y="155"> + <tspan x="349.774" y="155">source media</tspan> + <tspan x="349.774" y="171">bus format</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="350.488" y="190.834" width="93.2863" height="75.166"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="350.488" y="190.834" width="93.2863" height="75.166"/> + </g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="266" x2="63.5" y2="288"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="190.834" x2="63.5" y2="211"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="266" x2="157.5" y2="288"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="190.834" x2="157.5" y2="211"/> + <g> + <ellipse style="fill: #ffffff" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="481.6" y1="219.984" x2="637.934" y2="220.012"/> + <polygon style="fill: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="506.908" y="209.8"> + <tspan x="506.908" y="209.8">pad 1 (source)</tspan> + </text> + <g> + <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/> + <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8"> + <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan> + </text> +</svg> diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf Binary files differnew file mode 100644 index 000000000000..b78a8e8f6b35 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg new file mode 100644 index 000000000000..3322cf4c0093 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg @@ -0,0 +1,163 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> +<svg width="59cm" height="18cm" viewBox="-186 71 1178 346" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <g> + <rect style="fill: #ffffff" x="318.9" y="129" width="208.1" height="249"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff765a" x="318.9" y="129" width="208.1" height="249"/> + </g> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-2" y="73" width="806" height="343"/> + <g> + <ellipse style="fill: #ffffff" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/> + </g> + <g> + <ellipse style="fill: #ffffff" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.5" y1="167" x2="-30.7361" y2="166.729"/> + <polygon style="fill: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.732" y1="205.184" x2="980.066" y2="205.212"/> + <polygon style="fill: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139.96" y="155"> + <tspan x="-139.96" y="155">pad 0 (sink)</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.04" y="195"> + <tspan x="849.04" y="195">pad 2 (source)</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="5.5" y="120" width="159" height="104"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="5.5" y="120" width="159" height="104"/> + </g> + <g> + <rect style="fill: #ffffff" x="62.5" y="136" width="94" height="77"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="62.5" y="136" width="94" height="77"/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="30.5" y="89"> + <tspan x="30.5" y="89"></tspan> + </text> + <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="9.53836" y="88.9138"> + <tspan x="9.53836" y="88.9138">sink media</tspan> + <tspan x="9.53836" y="104.914">bus format</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/> + </g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="62.5" y2="213"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="62.5" y2="136"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="156.5" y2="213"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="156.5" y2="136"/> + <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442"> + <tspan x="334.704" y="149.442">sink compose</tspan> + <tspan x="334.704" y="165.442">selection (scaling)</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="409.322" y="194.565" width="100.186" height="71.4523"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="409.322" y="194.565" width="100.186" height="71.4523"/> + </g> + <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="689.5" y="105.128"> + <tspan x="689.5" y="105.128">source media</tspan> + <tspan x="689.5" y="121.128">bus format</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="688.488" y="173.834" width="100.186" height="71.4523"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="688.488" y="173.834" width="100.186" height="71.4523"/> + </g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="245.286" x2="409.322" y2="266.018"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="173.834" x2="409.322" y2="194.565"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="245.286" x2="509.508" y2="266.018"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="173.834" x2="509.508" y2="194.565"/> + <text style="fill: #ff765a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="325" y="103"> + <tspan x="325" y="103">sink compose</tspan> + <tspan x="325" y="119">bounds selection</tspan> + </text> + <g> + <ellipse style="fill: #ffffff" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.098" y1="341.8" x2="-30.3343" y2="341.529"/> + <polygon style="fill: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139" y="329"> + <tspan x="-139" y="329">pad 1 (sink)</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="7.80824" y="292.8" width="112.092" height="82.2"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="7.80824" y="292.8" width="112.092" height="82.2"/> + </g> + <g> + <rect style="fill: #ffffff" x="52.9" y="314.8" width="58.1" height="50.2"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="52.9" y="314.8" width="58.1" height="50.2"/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="31.9" y="259.8"> + <tspan x="31.9" y="259.8"></tspan> + </text> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="251.9" x2="52.9" y2="314.8"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="316" x2="52.9" y2="365"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="316" x2="111" y2="365"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="251.9" x2="111" y2="314.8"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="358.9" y="251.9" width="75.1" height="64.1"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="443.262" y="284.466" width="64.738" height="48.534"/> + <g> + <rect style="fill: #ffffff" x="693.428" y="324.734" width="63.572" height="49.266"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="693.428" y="324.734" width="63.572" height="49.266"/> + </g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="374" x2="443.262" y2="333"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="324.734" x2="443.262" y2="284.466"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="374" x2="508" y2="333"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="324.734" x2="508" y2="284.466"/> + <g> + <ellipse style="fill: #ffffff" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.94" y1="343.984" x2="980.274" y2="344.012"/> + <polygon style="fill: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.248" y="333.8"> + <tspan x="849.248" y="333.8">pad 3 (source)</tspan> + </text> + <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="197" y="91"> + <tspan x="197" y="91">sink</tspan> + <tspan x="197" y="107">crop</tspan> + <tspan x="197" y="123">selection</tspan> + </text> + <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="553" y="95"> + <tspan x="553" y="95">source</tspan> + <tspan x="553" y="111">crop</tspan> + <tspan x="553" y="127">selection</tspan> + </text> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="211" y1="132" x2="166.21" y2="135.287"/> + <polygon style="fill: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="209" y1="131" x2="115.581" y2="306.209"/> + <polygon style="fill: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.492" y1="133.214" x2="514.916" y2="186.469"/> + <polygon style="fill: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.072" y1="133.787" x2="510.618" y2="275.089"/> + <polygon style="fill: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/> + </g> +</svg> diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf Binary files differnew file mode 100644 index 000000000000..8f7a95b6eb4d --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg new file mode 100644 index 000000000000..2340c0f8bc92 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg @@ -0,0 +1,116 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> +<svg width="59cm" height="17cm" viewBox="-194 128 1179 330" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="806" height="327"/> + <g> + <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/> + </g> + <g> + <rect style="fill: #ffffff" x="49.5" y="204" width="94" height="77"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="49.5" y="204" width="94" height="77"/> + </g> + <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="60" y="224"> + <tspan x="60" y="224">sink</tspan> + <tspan x="60" y="240">crop</tspan> + <tspan x="60" y="256">selection</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158"> + <tspan x="29.5" y="158"></tspan> + </text> + <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914"> + <tspan x="8.53836" y="157.914">sink media</tspan> + <tspan x="8.53836" y="173.914">bus format</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/> + </g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="49.5" y2="281"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="49.5" y2="204"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="143.5" y2="281"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="143.5" y2="204"/> + <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442"> + <tspan x="334.704" y="149.442">sink compose</tspan> + <tspan x="334.704" y="165.442">selection (scaling)</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="382.322" y="199.565" width="100.186" height="71.4523"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="382.322" y="199.565" width="100.186" height="71.4523"/> + </g> + <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="543.322" y="149.442"> + <tspan x="543.322" y="149.442">source</tspan> + <tspan x="543.322" y="165.442">crop</tspan> + <tspan x="543.322" y="181.442">selection</tspan> + </text> + <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="691.5" y="157.128"> + <tspan x="691.5" y="157.128">source media</tspan> + <tspan x="691.5" y="173.128">bus format</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="690.488" y="225.834" width="100.186" height="71.4523"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="690.488" y="225.834" width="100.186" height="71.4523"/> + </g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="297.286" x2="382.322" y2="271.018"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="225.834" x2="382.322" y2="199.565"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="297.286" x2="482.508" y2="271.018"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="225.834" x2="482.508" y2="199.565"/> + <g> + <ellipse style="fill: #ffffff" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="816.6" y1="249.984" x2="972.934" y2="250.012"/> + <polygon style="fill: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="841.908" y="239.8"> + <tspan x="841.908" y="239.8">pad 1 (source)</tspan> + </text> + <g> + <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/> + <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8"> + <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan> + </text> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="389.822" y="276.666" width="100.186" height="71.4523"/> + <g> + <rect style="fill: #ffffff" x="689.988" y="345.934" width="100.186" height="71.4523"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="689.988" y="345.934" width="100.186" height="71.4523"/> + </g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="417.386" x2="389.822" y2="348.118"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="345.934" x2="389.822" y2="276.666"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="417.386" x2="490.008" y2="348.118"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="345.934" x2="490.008" y2="276.666"/> + <g> + <ellipse style="fill: #ffffff" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="814.1" y1="384.084" x2="970.434" y2="384.112"/> + <polygon style="fill: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="839.408" y="373.9"> + <tspan x="839.408" y="373.9">pad 2 (source)</tspan> + </text> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546" y1="191" x2="492.157" y2="198.263"/> + <polygon style="fill: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546.908" y1="190.725" x2="495.383" y2="268.548"/> + <polygon style="fill: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/> + </g> +</svg> diff --git a/Documentation/media/uapi/v4l/dev-teletext.rst b/Documentation/media/uapi/v4l/dev-teletext.rst new file mode 100644 index 000000000000..2648f6b37ea3 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-teletext.rst @@ -0,0 +1,34 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..aed0ce11d1f8 --- /dev/null +++ b/Documentation/media/uapi/v4l/devices.rst @@ -0,0 +1,26 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _devices: + +********** +Interfaces +********** + + +.. toctree:: + :maxdepth: 1 + + dev-capture + dev-overlay + dev-output + dev-osd + dev-codec + dev-effect + dev-raw-vbi + dev-sliced-vbi + dev-teletext + dev-radio + dev-rds + dev-sdr + dev-event + dev-subdev diff --git a/Documentation/media/uapi/v4l/diff-v4l.rst b/Documentation/media/uapi/v4l/diff-v4l.rst new file mode 100644 index 000000000000..5f45ec123162 --- /dev/null +++ b/Documentation/media/uapi/v4l/diff-v4l.rst @@ -0,0 +1,954 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _diff-v4l: + +******************************** +Differences between V4L and V4L2 +******************************** + +The Video For Linux API was first introduced in Linux 2.1 to unify and +replace various TV and radio device related interfaces, developed +independently by driver writers in prior years. Starting with Linux 2.5 +the much improved V4L2 API replaces the V4L API. The support for the old +V4L calls were removed from Kernel, but the library :ref:`libv4l` +supports the conversion of a V4L API system call into a V4L2 one. + + +Opening and Closing Devices +=========================== + +For compatibility reasons the character device file names recommended +for V4L2 video capture, overlay, radio and raw vbi capture devices did +not change from those used by V4L. They are listed in :ref:`devices` +and below in :ref:`v4l-dev`. + +The teletext devices (minor range 192-223) have been removed in V4L2 and +no longer exist. There is no hardware available anymore for handling +pure teletext. Instead raw or sliced VBI is used. + +The V4L ``videodev`` module automatically assigns minor numbers to +drivers in load order, depending on the registered device type. We +recommend that V4L2 drivers by default register devices with the same +numbers, but the system administrator can assign arbitrary minor numbers +using driver module options. The major device number remains 81. + + +.. _v4l-dev: + +.. flat-table:: V4L Device Types, Names and Numbers + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Device Type + + - File Name + + - Minor Numbers + + - .. row 2 + + - Video capture and overlay + + - ``/dev/video`` and ``/dev/bttv0``\ [1]_, ``/dev/video0`` to + ``/dev/video63`` + + - 0-63 + + - .. row 3 + + - Radio receiver + + - ``/dev/radio``\ [2]_, ``/dev/radio0`` to ``/dev/radio63`` + + - 64-127 + + - .. row 4 + + - Raw VBI capture + + - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31`` + + - 224-255 + + +V4L prohibits (or used to prohibit) multiple opens of a device file. +V4L2 drivers *may* support multiple opens, see :ref:`open` for details +and consequences. + +V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code. + + +Querying Capabilities +===================== + +The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's +:ref:`VIDIOC_QUERYCAP`. + +The ``name`` field in struct :c:type:`struct video_capability` became +``card`` in struct :ref:`v4l2_capability <v4l2-capability>`, ``type`` +was replaced by ``capabilities``. Note V4L2 does not distinguish between +device types like this, better think of basic video input, video output +and radio devices supporting a set of related functions like video +capturing, video overlay and VBI capturing. See :ref:`open` for an +introduction. + + + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - struct :c:type:`struct video_capability` ``type`` + + - struct :ref:`v4l2_capability <v4l2-capability>` + ``capabilities`` flags + + - Purpose + + - .. row 2 + + - ``VID_TYPE_CAPTURE`` + + - ``V4L2_CAP_VIDEO_CAPTURE`` + + - The :ref:`video capture <capture>` interface is supported. + + - .. row 3 + + - ``VID_TYPE_TUNER`` + + - ``V4L2_CAP_TUNER`` + + - The device has a :ref:`tuner or modulator <tuner>`. + + - .. row 4 + + - ``VID_TYPE_TELETEXT`` + + - ``V4L2_CAP_VBI_CAPTURE`` + + - The :ref:`raw VBI capture <raw-vbi>` interface is supported. + + - .. row 5 + + - ``VID_TYPE_OVERLAY`` + + - ``V4L2_CAP_VIDEO_OVERLAY`` + + - The :ref:`video overlay <overlay>` interface is supported. + + - .. row 6 + + - ``VID_TYPE_CHROMAKEY`` + + - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct + :ref:`v4l2_framebuffer <v4l2-framebuffer>` + + - Whether chromakey overlay is supported. For more information on + overlay see :ref:`overlay`. + + - .. row 7 + + - ``VID_TYPE_CLIPPING`` + + - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and + ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of + struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` + + - Whether clipping the overlaid image is supported, see + :ref:`overlay`. + + - .. row 8 + + - ``VID_TYPE_FRAMERAM`` + + - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability`` + of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` + + - Whether overlay overwrites frame buffer memory, see + :ref:`overlay`. + + - .. row 9 + + - ``VID_TYPE_SCALES`` + + - ``-`` + + - This flag indicates if the hardware can scale images. The V4L2 API + implies the scale factor by setting the cropping dimensions and + image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The + driver returns the closest sizes possible. For more information on + cropping and scaling see :ref:`crop`. + + - .. row 10 + + - ``VID_TYPE_MONOCHROME`` + + - ``-`` + + - Applications can enumerate the supported image formats with the + :ref:`VIDIOC_ENUM_FMT` ioctl to determine if + the device supports grey scale capturing only. For more + information on image formats see :ref:`pixfmt`. + + - .. row 11 + + - ``VID_TYPE_SUBCAPTURE`` + + - ``-`` + + - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` + ioctl to determine if the device supports capturing a subsection + of the full picture ("cropping" in V4L2). If not, the ioctl + returns the ``EINVAL`` error code. For more information on cropping + and scaling see :ref:`crop`. + + - .. row 12 + + - ``VID_TYPE_MPEG_DECODER`` + + - ``-`` + + - Applications can enumerate the supported image formats with the + :ref:`VIDIOC_ENUM_FMT` ioctl to determine if + the device supports MPEG streams. + + - .. row 13 + + - ``VID_TYPE_MPEG_ENCODER`` + + - ``-`` + + - See above. + + - .. row 14 + + - ``VID_TYPE_MJPEG_DECODER`` + + - ``-`` + + - See above. + + - .. row 15 + + - ``VID_TYPE_MJPEG_ENCODER`` + + - ``-`` + + - See above. + + +The ``audios`` field was replaced by ``capabilities`` flag +``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or +outputs. To determine their number applications can enumerate audio +inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The +audio ioctls are described in :ref:`audio`. + +The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields +were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired +dimensions returns the closest size possible, taking into account the +current video standard, cropping and scaling limitations. + + +Video Sources +============= + +V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct +:c:type:`struct video_channel` to enumerate the video inputs of a V4L +device. The equivalent V4L2 ioctls are +:ref:`VIDIOC_ENUMINPUT`, +:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and +:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct +:ref:`v4l2_input <v4l2-input>` as discussed in :ref:`video`. + +The ``channel`` field counting inputs was renamed to ``index``, the +video input types were renamed as follows: + + + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - struct :c:type:`struct video_channel` ``type`` + + - struct :ref:`v4l2_input <v4l2-input>` ``type`` + + - .. row 2 + + - ``VIDEO_TYPE_TV`` + + - ``V4L2_INPUT_TYPE_TUNER`` + + - .. row 3 + + - ``VIDEO_TYPE_CAMERA`` + + - ``V4L2_INPUT_TYPE_CAMERA`` + + +Unlike the ``tuners`` field expressing the number of tuners of this +input, V4L2 assumes each video input is connected to at most one tuner. +However a tuner can have more than one input, i. e. RF connectors, and a +device can have multiple tuners. The index number of the tuner +associated with the input, if any, is stored in field ``tuner`` of +struct :ref:`v4l2_input <v4l2-input>`. Enumeration of tuners is +discussed in :ref:`tuner`. + +The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs +associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The +``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2 +considers devices with up to 32 audio inputs. Each set bit in the +``audioset`` field represents one audio input this video input combines +with. For information about audio inputs and how to switch between them +see :ref:`audio`. + +The ``norm`` field describing the supported video standards was replaced +by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM`` +indicating whether the standard can be changed. This flag was a later +addition together with the ``norm`` field and has been removed in the +meantime. V4L2 has a similar, albeit more comprehensive approach to +video standards, see :ref:`standard` for more information. + + +Tuning +====== + +The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct +:c:type:`struct video_tuner` can be used to enumerate the tuners of a +V4L TV or radio device. The equivalent V4L2 ioctls are +:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and +:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct +:ref:`v4l2_tuner <v4l2-tuner>`. Tuners are covered in :ref:`tuner`. + +The ``tuner`` field counting tuners was renamed to ``index``. The fields +``name``, ``rangelow`` and ``rangehigh`` remained unchanged. + +The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM`` +flags indicating the supported video standards were dropped. This +information is now contained in the associated struct +:ref:`v4l2_input <v4l2-input>`. No replacement exists for the +``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be +switched. The ``mode`` field to select a different video standard was +replaced by a whole new set of ioctls and structures described in +:ref:`standard`. Due to its ubiquity it should be mentioned the BTTV +driver supports several standards in addition to the regular +``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and +``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC +Japan with numbers 3-6 (sic). + +The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became +``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also +permits the detection of monaural and bilingual audio, see the +definition of struct :ref:`v4l2_tuner <v4l2-tuner>` for details. +Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and +``VIDEO_TUNER_MBS_ON`` flags. + +The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in +the struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field. + +The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner +frequency where renamed to +:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and +:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer +to a struct :ref:`v4l2_frequency <v4l2-frequency>` instead of an +unsigned long integer. + + +.. _v4l-image-properties: + +Image Properties +================ + +V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl +and struct :c:type:`struct video_picture`. The following fields where +replaced by V4L2 controls accessible with the +:ref:`VIDIOC_QUERYCTRL`, +:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and +:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: + + + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - struct :c:type:`struct video_picture` + + - V4L2 Control ID + + - .. row 2 + + - ``brightness`` + + - ``V4L2_CID_BRIGHTNESS`` + + - .. row 3 + + - ``hue`` + + - ``V4L2_CID_HUE`` + + - .. row 4 + + - ``colour`` + + - ``V4L2_CID_SATURATION`` + + - .. row 5 + + - ``contrast`` + + - ``V4L2_CID_CONTRAST`` + + - .. row 6 + + - ``whiteness`` + + - ``V4L2_CID_WHITENESS`` + + +The V4L picture controls are assumed to range from 0 to 65535 with no +particular reset value. The V4L2 API permits arbitrary limits and +defaults which can be queried with the +:ref:`VIDIOC_QUERYCTRL` ioctl. For general +information about controls see :ref:`control`. + +The ``depth`` (average number of bits per pixel) of a video image is +implied by the selected image format. V4L2 does not explicitly provide +such information assuming applications recognizing the format are aware +of the image depth and others need not know. The ``palette`` field moved +into the struct :ref:`v4l2_pix_format <v4l2-pix-format>`: + + + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - struct :c:type:`struct video_picture` ``palette`` + + - struct :ref:`v4l2_pix_format <v4l2-pix-format>` ``pixfmt`` + + - .. row 2 + + - ``VIDEO_PALETTE_GREY`` + + - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>` + + - .. row 3 + + - ``VIDEO_PALETTE_HI240`` + + - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [3]_ + + - .. row 4 + + - ``VIDEO_PALETTE_RGB565`` + + - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>` + + - .. row 5 + + - ``VIDEO_PALETTE_RGB555`` + + - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>` + + - .. row 6 + + - ``VIDEO_PALETTE_RGB24`` + + - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>` + + - .. row 7 + + - ``VIDEO_PALETTE_RGB32`` + + - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [4]_ + + - .. row 8 + + - ``VIDEO_PALETTE_YUV422`` + + - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>` + + - .. row 9 + + - ``VIDEO_PALETTE_YUYV``\ [5]_ + + - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>` + + - .. row 10 + + - ``VIDEO_PALETTE_UYVY`` + + - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>` + + - .. row 11 + + - ``VIDEO_PALETTE_YUV420`` + + - None + + - .. row 12 + + - ``VIDEO_PALETTE_YUV411`` + + - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [6]_ + + - .. row 13 + + - ``VIDEO_PALETTE_RAW`` + + - None [7]_ + + - .. row 14 + + - ``VIDEO_PALETTE_YUV422P`` + + - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>` + + - .. row 15 + + - ``VIDEO_PALETTE_YUV411P`` + + - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [8]_ + + - .. row 16 + + - ``VIDEO_PALETTE_YUV420P`` + + - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>` + + - .. row 17 + + - ``VIDEO_PALETTE_YUV410P`` + + - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>` + + +V4L2 image formats are defined in :ref:`pixfmt`. The image format can +be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. + + +Audio +===== + +The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct +:c:type:`struct video_audio` are used to enumerate the audio inputs +of a V4L device. The equivalent V4L2 ioctls are +:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and +:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct +:ref:`v4l2_audio <v4l2-audio>` as discussed in :ref:`audio`. + +The ``audio`` "channel number" field counting audio inputs was renamed +to ``index``. + +On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the +``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or +``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio +standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and +``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L +specification, there is no way to query the selected mode. On +``VIDIOCGAUDIO`` the driver returns the *actually received* audio +programmes in this field. In the V4L2 API this information is stored in +the struct :ref:`v4l2_tuner <v4l2-tuner>` ``rxsubchans`` and +``audmode`` fields, respectively. See :ref:`tuner` for more +information on tuners. Related to audio modes struct +:ref:`v4l2_audio <v4l2-audio>` also reports if this is a mono or +stereo input, regardless if the source is a tuner. + +The following fields where replaced by V4L2 controls accessible with the +:ref:`VIDIOC_QUERYCTRL`, +:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and +:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: + + + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - struct :c:type:`struct video_audio` + + - V4L2 Control ID + + - .. row 2 + + - ``volume`` + + - ``V4L2_CID_AUDIO_VOLUME`` + + - .. row 3 + + - ``bass`` + + - ``V4L2_CID_AUDIO_BASS`` + + - .. row 4 + + - ``treble`` + + - ``V4L2_CID_AUDIO_TREBLE`` + + - .. row 5 + + - ``balance`` + + - ``V4L2_CID_AUDIO_BALANCE`` + + +To determine which of these controls are supported by a driver V4L +provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``, +``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the +:ref:`VIDIOC_QUERYCTRL` ioctl reports if the +respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE`` +and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean +``V4L2_CID_AUDIO_MUTE`` control. + +All V4L2 controls have a ``step`` attribute replacing the struct +:c:type:`struct video_audio` ``step`` field. The V4L audio controls +are assumed to range from 0 to 65535 with no particular reset value. The +V4L2 API permits arbitrary limits and defaults which can be queried with +the :ref:`VIDIOC_QUERYCTRL` ioctl. For general +information about controls see :ref:`control`. + + +Frame Buffer Overlay +==================== + +The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are +:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and +:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct +:c:type:`struct video_buffer` remained unchanged, except V4L2 defines +a flag to indicate non-destructive overlays instead of a ``NULL`` +pointer. All other fields moved into the struct +:ref:`v4l2_pix_format <v4l2-pix-format>` ``fmt`` substructure of +struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`. The ``depth`` +field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a +list of RGB formats and their respective color depths. + +Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2 +uses the general-purpose data format negotiation ioctls +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct +:ref:`v4l2_format <v4l2-format>` as argument. Here the ``win`` member +of the ``fmt`` union is used, a struct +:ref:`v4l2_window <v4l2-window>`. + +The ``x``, ``y``, ``width`` and ``height`` fields of struct +:c:type:`struct video_window` moved into struct +:ref:`v4l2_rect <v4l2-rect>` substructure ``w`` of struct +:c:type:`struct v4l2_window`. The ``chromakey``, ``clips``, and +``clipcount`` fields remained unchanged. Struct +:c:type:`struct video_clip` was renamed to struct +:ref:`v4l2_clip <v4l2-clip>`, also containing a struct +:c:type:`struct v4l2_rect`, but the semantics are still the same. + +The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications +must set the ``field`` field to ``V4L2_FIELD_ANY`` or +``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved +into struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`, under the new +name ``V4L2_FBUF_FLAG_CHROMAKEY``. + +In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount`` +to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed +size bitmap of 1024 × 625 bits. Struct :c:type:`struct v4l2_window` +has a separate ``bitmap`` pointer field for this purpose and the bitmap +size is determined by ``w.width`` and ``w.height``. + +The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to +:ref:`VIDIOC_OVERLAY`. + + +Cropping +======== + +To capture only a subsection of the full picture V4L defines the +``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct +:c:type:`struct video_capture`. The equivalent V4L2 ioctls are +:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and +:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct +:ref:`v4l2_crop <v4l2-crop>`, and the related +:ref:`VIDIOC_CROPCAP` ioctl. This is a rather +complex matter, see :ref:`crop` for details. + +The ``x``, ``y``, ``width`` and ``height`` fields moved into struct +:ref:`v4l2_rect <v4l2-rect>` substructure ``c`` of struct +:c:type:`struct v4l2_crop`. The ``decimation`` field was dropped. In +the V4L2 API the scaling factor is implied by the size of the cropping +rectangle and the size of the captured or overlaid image. + +The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture +only the odd or even field, respectively, were replaced by +``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named +``field`` of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and +struct :ref:`v4l2_window <v4l2-window>`. These structures are used to +select a capture or overlay format with the +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. + + +Reading Images, Memory Mapping +============================== + + +Capturing using the read method +------------------------------- + +There is no essential difference between reading images from a V4L or +V4L2 device using the :ref:`read() <func-read>` function, however V4L2 +drivers are not required to support this I/O method. Applications can +determine if the function is available with the +:ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices +exchanging data with applications must support the +:ref:`select() <func-select>` and :ref:`poll() <func-poll>` +functions. + +To select an image format and size, V4L provides the ``VIDIOCSPICT`` and +``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format +negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct +:ref:`v4l2_format <v4l2-format>` as argument, here the struct +:ref:`v4l2_pix_format <v4l2-pix-format>` named ``pix`` of its +``fmt`` union is used. + +For more information about the V4L2 read interface see :ref:`rw`. + + +Capturing using memory mapping +------------------------------ + +Applications can read from V4L devices by mapping buffers in device +memory, or more often just buffers allocated in DMA-able system memory, +into their address space. This avoids the data copying overhead of the +read method. V4L2 supports memory mapping as well, with a few +differences. + + + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - V4L + + - V4L2 + + - .. row 2 + + - + - The image format must be selected before buffers are allocated, + with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no + format is selected the driver may use the last, possibly by + another application requested format. + + - .. row 3 + + - Applications cannot change the number of buffers. The it is built + into the driver, unless it has a module option to change the + number when the driver module is loaded. + + - The :ref:`VIDIOC_REQBUFS` ioctl allocates the + desired number of buffers, this is a required step in the + initialization sequence. + + - .. row 4 + + - Drivers map all buffers as one contiguous range of memory. The + ``VIDIOCGMBUF`` ioctl is available to query the number of buffers, + the offset of each buffer from the start of the virtual file, and + the overall amount of memory used, which can be used as arguments + for the :ref:`mmap() <func-mmap>` function. + + - Buffers are individually mapped. The offset and size of each + buffer can be determined with the + :ref:`VIDIOC_QUERYBUF` ioctl. + + - .. row 5 + + - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It + also determines the image format for this buffer. The ioctl + returns immediately, eventually with an ``EAGAIN`` error code if no + video signal had been detected. When the driver supports more than + one buffer applications can call the ioctl multiple times and thus + have multiple outstanding capture requests. + + The ``VIDIOCSYNC`` ioctl suspends execution until a particular + buffer has been filled. + + - Drivers maintain an incoming and outgoing queue. + :ref:`VIDIOC_QBUF` enqueues any empty buffer into + the incoming queue. Filled buffers are dequeued from the outgoing + queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait + until filled buffers become available this function, + :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can + be used. The :ref:`VIDIOC_STREAMON` ioctl + must be called once after enqueuing one or more buffers to start + capturing. Its counterpart + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and + dequeues all buffers from both queues. Applications can query the + signal status, if known, with the + :ref:`VIDIOC_ENUMINPUT` ioctl. + + +For a more in-depth discussion of memory mapping and examples, see +:ref:`mmap`. + + +Reading Raw VBI Data +==================== + +Originally the V4L API did not specify a raw VBI capture interface, only +the device file ``/dev/vbi`` was reserved for this purpose. The only +driver supporting this interface was the BTTV driver, de-facto defining +the V4L VBI interface. Reading from the device yields a raw VBI image +with the following parameters: + + + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` + + - V4L, BTTV driver + + - .. row 2 + + - sampling_rate + + - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL + and SECAM (625-line standards) + + - .. row 3 + + - offset + + - ? + + - .. row 4 + + - samples_per_line + + - 2048 + + - .. row 5 + + - sample_format + + - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness + integer) contain a frame counter. + + - .. row 6 + + - start[] + + - 10, 273 NTSC; 22, 335 PAL and SECAM + + - .. row 7 + + - count[] + + - 16, 16 [9]_ + + - .. row 8 + + - flags + + - 0 + + +Undocumented in the V4L specification, in Linux 2.3 the +``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct +:c:type:`struct vbi_format` were added to determine the VBI image +parameters. These ioctls are only partially compatible with the V4L2 VBI +interface specified in :ref:`raw-vbi`. + +An ``offset`` field does not exist, ``sample_format`` is supposed to be +``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The +remaining fields are probably equivalent to struct +:ref:`v4l2_vbi_format <v4l2-vbi-format>`. + +Apparently only the Zoran (ZR 36120) driver implements these ioctls. The +semantics differ from those specified for V4L2 in two ways. The +parameters are reset on :ref:`open() <func-open>` and +``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters +are invalid. + + +Miscellaneous +============= + +V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can +find the VBI device associated with a video capture device (or vice +versa) by reopening the device and requesting VBI data. For details see +:ref:`open`. + +No replacement exists for ``VIDIOCKEY``, and the V4L functions for +microcode programming. A new interface for MPEG compression and playback +devices is documented in :ref:`extended-controls`. + +.. [1] + According to Documentation/devices.txt these should be symbolic links + to ``/dev/video0``. Note the original bttv interface is not + compatible with V4L or V4L2. + +.. [2] + According to ``Documentation/devices.txt`` a symbolic link to + ``/dev/radio0``. + +.. [3] + This is a custom format used by the BTTV driver, not one of the V4L2 + standard formats. + +.. [4] + Presumably all V4L RGB formats are little-endian, although some + drivers might interpret them according to machine endianness. V4L2 + defines little-endian, big-endian and red/blue swapped variants. For + details see :ref:`pixfmt-rgb`. + +.. [5] + ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same + formats. Some V4L drivers respond to one, some to the other. + +.. [6] + Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar + format. + +.. [7] + V4L explains this as: "RAW capture (BT848)" + +.. [8] + Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed + format. + +.. [9] + Old driver versions used different values, eventually the custom + ``BTTV_VBISIZE`` ioctl was added to query the correct values. diff --git a/Documentation/media/uapi/v4l/dmabuf.rst b/Documentation/media/uapi/v4l/dmabuf.rst new file mode 100644 index 000000000000..474d8c021507 --- /dev/null +++ b/Documentation/media/uapi/v4l/dmabuf.rst @@ -0,0 +1,155 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dmabuf: + +************************************ +Streaming I/O (DMA buffer importing) +************************************ + +The DMABUF framework provides a generic method for sharing buffers +between multiple devices. Device drivers that support DMABUF can export +a DMA buffer to userspace as a file descriptor (known as the exporter +role), import a DMA buffer from userspace using a file descriptor +previously exported for a different or the same device (known as the +importer role), or both. This section describes the DMABUF importer role +API in V4L2. + +Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF>` for details about +exporting V4L2 buffers as DMABUF file descriptors. + +Input and output devices support the streaming I/O method when the +``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is set. Whether +importing DMA buffers through DMABUF file descriptors is supported is +determined by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` +ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``. + +This I/O method is dedicated to sharing DMA buffers between different +devices, which may be V4L devices or other video-related devices (e.g. +DRM). Buffers (planes) are allocated by a driver on behalf of an +application. Next, these buffers are exported to the application as file +descriptors using an API which is specific for an allocator driver. Only +such file descriptor are exchanged. The descriptors and meta-information +are passed in struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct +:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The +driver must be switched into DMABUF I/O mode by calling the +:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type. + + +.. code-block:: c + :caption: Example 3.4. Initiating streaming I/O with DMABUF file descriptors + + struct v4l2_requestbuffers reqbuf; + + memset(&reqbuf, 0, sizeof (reqbuf)); + reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + reqbuf.memory = V4L2_MEMORY_DMABUF; + reqbuf.count = 1; + + if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == -1) { + if (errno == EINVAL) + printf("Video capturing or DMABUF streaming is not supported\\n"); + else + perror("VIDIOC_REQBUFS"); + + exit(EXIT_FAILURE); + } + +The buffer (plane) file descriptor is passed on the fly with the +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In case of multiplanar +buffers, every plane can be associated with a different DMABUF +descriptor. Although buffers are commonly cycled, applications can pass +a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. + + +.. code-block:: c + :caption: Example 3.5. Queueing DMABUF using single plane API + + int buffer_queue(int v4lfd, int index, int dmafd) + { + struct v4l2_buffer buf; + + memset(&buf, 0, sizeof buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_DMABUF; + buf.index = index; + buf.m.fd = dmafd; + + if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) { + perror("VIDIOC_QBUF"); + return -1; + } + + return 0; + } + + +.. code-block:: c + :caption: Example 3.6. Queueing DMABUF using multi plane API + + int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes) + { + struct v4l2_buffer buf; + struct v4l2_plane planes[VIDEO_MAX_PLANES]; + int i; + + memset(&buf, 0, sizeof buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; + buf.memory = V4L2_MEMORY_DMABUF; + buf.index = index; + buf.m.planes = planes; + buf.length = n_planes; + + memset(&planes, 0, sizeof planes); + + for (i = 0; i < n_planes; ++i) + buf.m.planes[i].m.fd = dmafd[i]; + + if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) { + perror("VIDIOC_QBUF"); + return -1; + } + + return 0; + } + +Captured or displayed buffers are dequeued with the +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the +buffer at any time between the completion of the DMA and this ioctl. The +memory is also unlocked when +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called, +:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or when the device is closed. + +For capturing applications it is customary to enqueue a number of empty +buffers, to start capturing and enter the read loop. Here the +application waits until a filled buffer can be dequeued, and re-enqueues +the buffer when the data is no longer needed. Output applications fill +and enqueue buffers, when enough buffers are stacked up output is +started. In the write loop, when the application runs out of free +buffers it must wait until an empty buffer can be dequeued and reused. +Two methods exist to suspend execution of the application until one or +more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF +<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the +``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` +error code when no buffer is available. The +:ref:`select() <func-select>` and :ref:`poll() <func-poll>` +functions are always available. + +To start and stop capturing or displaying applications call the +:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls. Note that +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from +both queues and unlocks all buffers as a side effect. Since there is no +notion of doing anything "now" on a multitasking system, if an +application needs to synchronize with another event it should examine +the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or +outputted buffers. + +Drivers implementing DMABUF importing I/O must support the +:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON +<VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, +and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>` +functions. diff --git a/Documentation/media/uapi/v4l/driver.rst b/Documentation/media/uapi/v4l/driver.rst new file mode 100644 index 000000000000..2319b383f0a4 --- /dev/null +++ b/Documentation/media/uapi/v4l/driver.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _driver: + +*********************** +V4L2 Driver Programming +*********************** + +to do diff --git a/Documentation/media/uapi/v4l/dv-timings.rst b/Documentation/media/uapi/v4l/dv-timings.rst new file mode 100644 index 000000000000..415a0c4e2ccb --- /dev/null +++ b/Documentation/media/uapi/v4l/dv-timings.rst @@ -0,0 +1,38 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dv-timings: + +************************** +Digital Video (DV) Timings +************************** + +The video standards discussed so far have been dealing with Analog TV +and the corresponding video timings. Today there are many more different +hardware interfaces such as High Definition TV interfaces (HDMI), VGA, +DVI connectors etc., that carry video signals and there is a need to +extend the API to select the video timings for these interfaces. Since +it is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>` +due to the limited bits available, a new set of ioctls was added to +set/get video timings at the input and output. + +These ioctls deal with the detailed digital video timings that define +each video format. This includes parameters such as the active video +width and height, signal polarities, frontporches, backporches, sync +widths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get +the timings of the formats in the :ref:`cea861` and :ref:`vesadmt` +standards. + +To enumerate and query the attributes of the DV timings supported by a +device applications use the +:ref:`VIDIOC_ENUM_DV_TIMINGS` and +:ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set +DV timings for the device applications use the +:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get +current DV timings they use the +:ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. To detect +the DV timings as seen by the video receiver applications use the +:ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl. + +Applications can make use of the :ref:`input-capabilities` and +:ref:`output-capabilities` flags to determine whether the digital +video ioctls can be used with the given input or output. diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst new file mode 100644 index 000000000000..26eb6ee851c3 --- /dev/null +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -0,0 +1,4524 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _extended-controls: + +***************** +Extended Controls +***************** + + +Introduction +============ + +The control mechanism as originally designed was meant to be used for +user settings (brightness, saturation, etc). However, it turned out to +be a very useful model for implementing more complicated driver APIs +where each driver implements only a subset of a larger API. + +The MPEG encoding API was the driving force behind designing and +implementing this extended control mechanism: the MPEG standard is quite +large and the currently supported hardware MPEG encoders each only +implement a subset of this standard. Further more, many parameters +relating to how the video is encoded into an MPEG stream are specific to +the MPEG encoding chip since the MPEG standard only defines the format +of the resulting MPEG stream, not how the video is actually encoded into +that format. + +Unfortunately, the original control API lacked some features needed for +these new uses and so it was extended into the (not terribly originally +named) extended control API. + +Even though the MPEG encoding API was the first effort to use the +Extended Control API, nowadays there are also other classes of Extended +Controls, such as Camera Controls and FM Transmitter Controls. The +Extended Controls API as well as all Extended Controls classes are +described in the following text. + + +The Extended Control API +======================== + +Three new ioctls are available: +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, +:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and +:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act +on arrays of controls (as opposed to the +:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and +:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single +control). This is needed since it is often required to atomically change +several controls at once. + +Each of the new ioctls expects a pointer to a struct +:ref:`v4l2_ext_controls <v4l2-ext-controls>`. This structure +contains a pointer to the control array, a count of the number of +controls in that array and a control class. Control classes are used to +group similar controls into a single class. For example, control class +``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls +that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` +ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls +relating to MPEG encoding, etc. + +All controls in the control array must belong to the specified control +class. An error is returned if this is not the case. + +It is also possible to use an empty control array (``count`` == 0) to check +whether the specified control class is supported. + +The control array is a struct +:ref:`v4l2_ext_control <v4l2-ext-control>` array. The +:ref:`struct v4l2_ext_control <v4l2-ext-control>` structure is very similar to +struct :ref:`v4l2_control <v4l2-control>`, except for the fact that +it also allows for 64-bit values and pointers to be passed. + +Since the struct :ref:`v4l2_ext_control <v4l2-ext-control>` supports +pointers it is now also possible to have controls with compound types +such as N-dimensional arrays and/or structures. You need to specify the +``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually +be able to see such compound controls. In other words, these controls +with compound types should only be used programmatically. + +Since such compound controls need to expose more information about +themselves than is possible with +:ref:`VIDIOC_QUERYCTRL` the +:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In +particular, this ioctl gives the dimensions of the N-dimensional array +if this control consists of more than one element. + +It is important to realize that due to the flexibility of controls it is +necessary to check whether the control you want to set actually is +supported in the driver and what the valid range of values is. So use +the :ref:`VIDIOC_QUERYCTRL` (or +:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`) and +:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls to check this. Also +note that it is possible that some of the menu indices in a control of +type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` +will return an error). A good example is the list of supported MPEG +audio bitrates. Some drivers only support one or two bitrates, others +support a wider range. + +All controls use machine endianness. + + +Enumerating Extended Controls +============================= + +The recommended way to enumerate over the extended controls is by using +:ref:`VIDIOC_QUERYCTRL` in combination with the +``V4L2_CTRL_FLAG_NEXT_CTRL`` flag: + + +.. code-block:: c + + struct v4l2_queryctrl qctrl; + + qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; + while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) { + /* ... */ + qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; + } + +The initial control ID is set to 0 ORed with the +``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will +return the first control with a higher ID than the specified one. When +no such controls are found an error is returned. + +If you want to get all controls within a specific control class, then +you can set the initial ``qctrl.id`` value to the control class and add +an extra check to break out of the loop when a control of another +control class is found: + + +.. code-block:: c + + qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; + while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { + if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) + break; + /* ... */ + qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; + } + +The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the +top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``) +and are not actually part of the ID. The remaining 28 bits form the +control ID, of which the most significant 12 bits define the control +class and the least significant 16 bits identify the control within the +control class. It is guaranteed that these last 16 bits are always +non-zero for controls. The range of 0x1000 and up are reserved for +driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns +the control class ID based on a control ID. + +If the driver does not support extended controls, then +``VIDIOC_QUERYCTRL`` will fail when used in combination with +``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating +control should be used (see :ref:`enum_all_controls`). But if it is +supported, then it is guaranteed to enumerate over all controls, +including driver-private controls. + + +Creating Control Panels +======================= + +It is possible to create control panels for a graphical user interface +where the user can select the various controls. Basically you will have +to iterate over all controls using the method described above. Each +control class starts with a control of type +``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name +of this control class which can be used as the title of a tab page +within a control panel. + +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 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 + + + - .. row 1 + + - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS`` + + - MPEG-2 program stream + + - .. row 2 + + - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS`` + + - MPEG-2 transport stream + + - .. row 3 + + - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS`` + + - MPEG-1 system stream + + - .. row 4 + + - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD`` + + - MPEG-2 DVD-compatible stream + + - .. row 5 + + - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD`` + + - MPEG-1 VCD-compatible stream + + - .. row 6 + + - ``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 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: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_STREAM_VBI_FMT_NONE`` + + - No VBI in the MPEG stream + + - .. row 2 + + - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV`` + + - VBI in private packets, IVTV format (documented in the kernel + sources in the file + ``Documentation/video4linux/cx2341x/README.vbi``) + + + +.. _v4l2-mpeg-audio-sampling-freq: + +``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (enum v4l2_mpeg_audio_sampling_freq)`` + MPEG Audio sampling frequency. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100`` + + - 44.1 kHz + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000`` + + - 48 kHz + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000`` + + - 32 kHz + + + +.. _v4l2-mpeg-audio-encoding: + +``V4L2_CID_MPEG_AUDIO_ENCODING (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 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1`` + + - MPEG-1/2 Layer I encoding + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2`` + + - MPEG-1/2 Layer II encoding + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3`` + + - MPEG-1/2 Layer III encoding + + - .. row 4 + + - ``V4L2_MPEG_AUDIO_ENCODING_AAC`` + + - MPEG-2/4 AAC (Advanced Audio Coding) + + - .. row 5 + + - ``V4L2_MPEG_AUDIO_ENCODING_AC3`` + + - AC-3 aka ATSC A/52 encoding + + + +.. _v4l2-mpeg-audio-l1-bitrate: + +``V4L2_CID_MPEG_AUDIO_L1_BITRATE (enum v4l2_mpeg_audio_l1_bitrate)`` + MPEG-1/2 Layer I bitrate. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K`` + + - 32 kbit/s + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K`` + + - 64 kbit/s + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K`` + + - 96 kbit/s + + - .. row 4 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K`` + + - 128 kbit/s + + - .. row 5 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K`` + + - 160 kbit/s + + - .. row 6 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K`` + + - 192 kbit/s + + - .. row 7 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K`` + + - 224 kbit/s + + - .. row 8 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K`` + + - 256 kbit/s + + - .. row 9 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K`` + + - 288 kbit/s + + - .. row 10 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K`` + + - 320 kbit/s + + - .. row 11 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K`` + + - 352 kbit/s + + - .. row 12 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K`` + + - 384 kbit/s + + - .. row 13 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K`` + + - 416 kbit/s + + - .. row 14 + + - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K`` + + - 448 kbit/s + + + +.. _v4l2-mpeg-audio-l2-bitrate: + +``V4L2_CID_MPEG_AUDIO_L2_BITRATE (enum v4l2_mpeg_audio_l2_bitrate)`` + MPEG-1/2 Layer II bitrate. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K`` + + - 32 kbit/s + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K`` + + - 48 kbit/s + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K`` + + - 56 kbit/s + + - .. row 4 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K`` + + - 64 kbit/s + + - .. row 5 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K`` + + - 80 kbit/s + + - .. row 6 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K`` + + - 96 kbit/s + + - .. row 7 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K`` + + - 112 kbit/s + + - .. row 8 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K`` + + - 128 kbit/s + + - .. row 9 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K`` + + - 160 kbit/s + + - .. row 10 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K`` + + - 192 kbit/s + + - .. row 11 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K`` + + - 224 kbit/s + + - .. row 12 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K`` + + - 256 kbit/s + + - .. row 13 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K`` + + - 320 kbit/s + + - .. row 14 + + - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K`` + + - 384 kbit/s + + + +.. _v4l2-mpeg-audio-l3-bitrate: + +``V4L2_CID_MPEG_AUDIO_L3_BITRATE (enum v4l2_mpeg_audio_l3_bitrate)`` + MPEG-1/2 Layer III bitrate. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K`` + + - 32 kbit/s + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K`` + + - 40 kbit/s + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K`` + + - 48 kbit/s + + - .. row 4 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K`` + + - 56 kbit/s + + - .. row 5 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K`` + + - 64 kbit/s + + - .. row 6 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K`` + + - 80 kbit/s + + - .. row 7 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K`` + + - 96 kbit/s + + - .. row 8 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K`` + + - 112 kbit/s + + - .. row 9 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K`` + + - 128 kbit/s + + - .. row 10 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K`` + + - 160 kbit/s + + - .. row 11 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K`` + + - 192 kbit/s + + - .. row 12 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K`` + + - 224 kbit/s + + - .. row 13 + + - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K`` + + - 256 kbit/s + + - .. row 14 + + - ``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 v4l2_mpeg_audio_ac3_bitrate)`` + AC-3 bitrate. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K`` + + - 32 kbit/s + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K`` + + - 40 kbit/s + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K`` + + - 48 kbit/s + + - .. row 4 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K`` + + - 56 kbit/s + + - .. row 5 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K`` + + - 64 kbit/s + + - .. row 6 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K`` + + - 80 kbit/s + + - .. row 7 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K`` + + - 96 kbit/s + + - .. row 8 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K`` + + - 112 kbit/s + + - .. row 9 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K`` + + - 128 kbit/s + + - .. row 10 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K`` + + - 160 kbit/s + + - .. row 11 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K`` + + - 192 kbit/s + + - .. row 12 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K`` + + - 224 kbit/s + + - .. row 13 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K`` + + - 256 kbit/s + + - .. row 14 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K`` + + - 320 kbit/s + + - .. row 15 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K`` + + - 384 kbit/s + + - .. row 16 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K`` + + - 448 kbit/s + + - .. row 17 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K`` + + - 512 kbit/s + + - .. row 18 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K`` + + - 576 kbit/s + + - .. row 19 + + - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K`` + + - 640 kbit/s + + + +.. _v4l2-mpeg-audio-mode: + +``V4L2_CID_MPEG_AUDIO_MODE (enum v4l2_mpeg_audio_mode)`` + MPEG Audio mode. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_MODE_STEREO`` + + - Stereo + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO`` + + - Joint Stereo + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_MODE_DUAL`` + + - Bilingual + + - .. row 4 + + - ``V4L2_MPEG_AUDIO_MODE_MONO`` + + - Mono + + + +.. _v4l2-mpeg-audio-mode-extension: + +``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (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 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4`` + + - Subbands 4-31 in intensity stereo + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8`` + + - Subbands 8-31 in intensity stereo + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12`` + + - Subbands 12-31 in intensity stereo + + - .. row 4 + + - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16`` + + - Subbands 16-31 in intensity stereo + + + +.. _v4l2-mpeg-audio-emphasis: + +``V4L2_CID_MPEG_AUDIO_EMPHASIS (enum v4l2_mpeg_audio_emphasis)`` + Audio Emphasis. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE`` + + - None + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS`` + + - 50/15 microsecond emphasis + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17`` + + - CCITT J.17 + + + +.. _v4l2-mpeg-audio-crc: + +``V4L2_CID_MPEG_AUDIO_CRC (enum v4l2_mpeg_audio_crc)`` + CRC method. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_CRC_NONE`` + + - None + + - .. row 2 + + - ``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 v4l2_mpeg_audio_dec_playback)`` + Determines how monolingual audio should be played back. Possible + values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO`` + + - Automatically determines the best playback mode. + + - .. row 2 + + - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO`` + + - Stereo playback. + + - .. row 3 + + - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT`` + + - Left channel playback. + + - .. row 4 + + - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT`` + + - Right channel playback. + + - .. row 5 + + - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO`` + + - Mono playback. + + - .. row 6 + + - ``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 v4l2_mpeg_audio_dec_playback)`` + Determines how multilingual audio should be played back. + +.. _v4l2-mpeg-video-encoding: + +``V4L2_CID_MPEG_VIDEO_ENCODING (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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1`` + + - MPEG-1 Video encoding + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2`` + + - MPEG-2 Video encoding + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` + + - MPEG-4 AVC (H.264) Video encoding + + + +.. _v4l2-mpeg-video-aspect: + +``V4L2_CID_MPEG_VIDEO_ASPECT (enum v4l2_mpeg_video_aspect)`` + Video aspect. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_ASPECT_1x1`` + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_ASPECT_4x3`` + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_ASPECT_16x9`` + + - .. row 4 + + - ``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 v4l2_mpeg_video_bitrate_mode)`` + Video bitrate mode. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR`` + + - Variable bitrate + + - .. row 2 + + - ``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 + + + - .. row 1 + + - Bit 0:7 + + - V chrominance information + + - .. row 2 + + - Bit 8:15 + + - U chrominance information + + - .. row 3 + + - Bit 16:23 + + - Y luminance information + + - .. row 4 + + - 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 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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED`` + + - Unspecified + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1`` + + - 1x1 + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11`` + + - 12x11 + + - .. row 4 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11`` + + - 10x11 + + - .. row 5 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11`` + + - 16x11 + + - .. row 6 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33`` + + - 40x33 + + - .. row 7 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11`` + + - 24x11 + + - .. row 8 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11`` + + - 20x11 + + - .. row 9 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11`` + + - 32x11 + + - .. row 10 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33`` + + - 80x33 + + - .. row 11 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11`` + + - 18x11 + + - .. row 12 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11`` + + - 15x11 + + - .. row 13 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33`` + + - 64x33 + + - .. row 14 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99`` + + - 160x99 + + - .. row 15 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3`` + + - 4x3 + + - .. row 16 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2`` + + - 3x2 + + - .. row 17 + + - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1`` + + - 2x1 + + - .. row 18 + + - ``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 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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0`` + + - Level 1.0 + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B`` + + - Level 1B + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1`` + + - Level 1.1 + + - .. row 4 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2`` + + - Level 1.2 + + - .. row 5 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3`` + + - Level 1.3 + + - .. row 6 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0`` + + - Level 2.0 + + - .. row 7 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1`` + + - Level 2.1 + + - .. row 8 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2`` + + - Level 2.2 + + - .. row 9 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0`` + + - Level 3.0 + + - .. row 10 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1`` + + - Level 3.1 + + - .. row 11 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2`` + + - Level 3.2 + + - .. row 12 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0`` + + - Level 4.0 + + - .. row 13 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1`` + + - Level 4.1 + + - .. row 14 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2`` + + - Level 4.2 + + - .. row 15 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0`` + + - Level 5.0 + + - .. row 16 + + - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1`` + + - Level 5.1 + + + +.. _v4l2-mpeg-video-mpeg4-level: + +``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL (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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_LEVEL_0`` + + - Level 0 + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_LEVEL_0B`` + + - Level 0b + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_LEVEL_1`` + + - Level 1 + + - .. row 4 + + - ``V4L2_MPEG_VIDEO_LEVEL_2`` + + - Level 2 + + - .. row 5 + + - ``V4L2_MPEG_VIDEO_LEVEL_3`` + + - Level 3 + + - .. row 6 + + - ``V4L2_MPEG_VIDEO_LEVEL_3B`` + + - Level 3b + + - .. row 7 + + - ``V4L2_MPEG_VIDEO_LEVEL_4`` + + - Level 4 + + - .. row 8 + + - ``V4L2_MPEG_VIDEO_LEVEL_5`` + + - Level 5 + + + +.. _v4l2-mpeg-video-h264-profile: + +``V4L2_CID_MPEG_VIDEO_H264_PROFILE (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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE`` + + - Baseline profile + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE`` + + - Constrained Baseline profile + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN`` + + - Main profile + + - .. row 4 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED`` + + - Extended profile + + - .. row 5 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH`` + + - High profile + + - .. row 6 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10`` + + - High 10 profile + + - .. row 7 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422`` + + - High 422 profile + + - .. row 8 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE`` + + - High 444 Predictive profile + + - .. row 9 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA`` + + - High 10 Intra profile + + - .. row 10 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA`` + + - High 422 Intra profile + + - .. row 11 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA`` + + - High 444 Intra profile + + - .. row 12 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA`` + + - CAVLC 444 Intra profile + + - .. row 13 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE`` + + - Scalable Baseline profile + + - .. row 14 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH`` + + - Scalable High profile + + - .. row 15 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA`` + + - Scalable High Intra profile + + - .. row 16 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH`` + + - Stereo High profile + + - .. row 17 + + - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH`` + + - Multiview High profile + + + +.. _v4l2-mpeg-video-mpeg4-profile: + +``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE (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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE`` + + - Simple profile + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE`` + + - Advanced Simple profile + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_PROFILE_CORE`` + + - Core profile + + - .. row 4 + + - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE`` + + - Simple Scalable profile + + - .. row 5 + + - ``V4L2_MPEG_VIDEO_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 v4l2_mpeg_video_multi_slice_mode)`` + Determines how the encoder should handle division of frame into + slices. Applicable to the encoder. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE`` + + - Single slice per frame. + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB`` + + - Multiple slices with set maximum number of macroblocks per slice. + + - .. row 3 + + - ``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 v4l2_mpeg_video_h264_loop_filter_mode)`` + Loop filter mode for H264 encoder. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED`` + + - Loop filter is enabled. + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED`` + + - Loop filter is disabled. + + - .. row 3 + + - ``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. + Applicable to the H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)`` + Loop filter beta coefficient, defined in the H264 standard. + Applicable to the H264 encoder. + +.. _v4l2-mpeg-video-h264-entropy-mode: + +``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE (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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC`` + + - Use CAVLC entropy coding. + + - .. row 2 + + - ``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 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: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE`` + + - The stream header is returned separately in the first buffer. + + - .. row 2 + + - ``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 v4l2_mpeg_video_h264_sei_fp_arrangement_type)`` + Frame packing arrangement type for H264 SEI. Applicable to the H264 + encoder. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD`` + + - Pixels are alternatively from L and R. + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN`` + + - L and R are interlaced by column. + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW`` + + - L and R are interlaced by row. + + - .. row 4 + + - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE`` + + - L is on the left, R on the right. + + - .. row 5 + + - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM`` + + - L is on top, R on bottom. + + - .. row 6 + + - ``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 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: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES`` + + - Slices are interleaved one after other with macroblocks in run + length order. + + - .. row 2 + + - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES`` + + - Scatters the macroblocks based on a mathematical function known to + both encoder and decoder. + + - .. row 3 + + - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER`` + + - Macroblocks arranged in rectangular areas or regions of interest. + + - .. row 4 + + - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT`` + + - Slice groups grow in a cyclic way from centre to outwards. + + - .. row 5 + + - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN`` + + - Slice groups grow in raster scan pattern from left to right. + + - .. row 6 + + - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN`` + + - Slice groups grow in wipe scan pattern from top to bottom. + + - .. row 7 + + - ``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 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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT`` + + - Raster scan or wipe right. + + - .. row 2 + + - ``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 + + + - .. row 1 + + - Bit 0:15 + + - Slice ID + + - .. row 2 + + - 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 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 + + + - .. row 1 + + - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B`` + + - Hierarchical B coding. + + - .. row 2 + + - ``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 + + + - .. row 1 + + - Bit 0:15 + + - QP value + + - .. row 2 + + - Bit 16:32 + + - Layer number + + + + +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 + + + - .. row 1 + + - Bit 0:7 + + - V chrominance information + + - .. row 2 + + - Bit 8:15 + + - U chrominance information + + - .. row 3 + + - Bit 16:23 + + - Y luminance information + + - .. row 4 + + - 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 1: Valid only when the frame level RC is enabled. + + Note 2: For tight CBR, this field must be small (ex. 2 ~ 10). For + VBR, this field must be large (ex. 100 ~ 1000). + + Note 3: 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 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: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED`` + + - Frame skip mode is disabled. + + - .. row 2 + + - ``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. + + - .. row 3 + + - ``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 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 + + + - .. row 1 + + - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED`` + + - Forcing a specific frame type disabled. + + - .. row 2 + + - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME`` + + - Force an I-frame. + + - .. row 3 + + - ``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 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 + + + - .. row 1 + + - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL`` + + - Choose the filter manually + + - .. row 2 + + - ``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 v4l2_mpeg_cx2341x_video_luma_spatial_filter_type)`` + Select the algorithm to use for the Luma Spatial Filter (default + ``1D_HOR``). Possible values: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF`` + + - No filter + + - .. row 2 + + - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR`` + + - One-dimensional horizontal + + - .. row 3 + + - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT`` + + - One-dimensional vertical + + - .. row 4 + + - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE`` + + - Two-dimensional separable + + - .. row 5 + + - ``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 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 + + + - .. row 1 + + - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF`` + + - No filter + + - .. row 2 + + - ``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 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 + + + - .. row 1 + + - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL`` + + - Choose the filter manually + + - .. row 2 + + - ``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 v4l2_mpeg_cx2341x_video_median_filter_type)`` + Median Filter Type (default ``OFF``). Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF`` + + - No filter + + - .. row 2 + + - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR`` + + - Horizontal filter + + - .. row 3 + + - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT`` + + - Vertical filter + + - .. row 4 + + - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT`` + + - Horizontal and vertical filter + + - .. row 5 + + - ``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 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 + + + - .. row 1 + + - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION`` + + - 1 coefficient partition + + - .. row 2 + + - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS`` + + - 2 coefficient partitions + + - .. row 3 + + - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS`` + + - 4 coefficient partitions + + - .. row 4 + + - ``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 v4l2_vp8_num_ref_frames)`` + The number of reference pictures for encoding P frames. Possible + values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME`` + + - Last encoded frame will be searched + + - .. row 2 + + - ``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. + + - .. row 3 + + - ``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 v4l2_vp8_golden_frame_sel)`` + Selects the golden frame for encoding. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV`` + + - Use the (n-2)th frame as a golden frame, current frame index being + 'n'. + + - .. row 2 + + - ``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. + + + +``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_CID_MPEG_VIDEO_VPX_PROFILE (integer)`` + Select the desired profile for VPx encoder. Acceptable values are 0, + 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3. + + +.. _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 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 + + + - .. row 1 + + - ``V4L2_EXPOSURE_AUTO`` + + - Automatic exposure time, automatic iris aperture. + + - .. row 2 + + - ``V4L2_EXPOSURE_MANUAL`` + + - Manual exposure time, manual iris. + + - .. row 3 + + - ``V4L2_EXPOSURE_SHUTTER_PRIORITY`` + + - Manual exposure time, auto iris. + + - .. row 4 + + - ``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_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 v4l2_exposure_metering)`` + Determines how the camera measures the amount of light available for + the frame exposure. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``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. + + - .. row 2 + + - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED`` + + - Average the light information coming from the entire frame giving + priority to the center of the metered area. + + - .. row 3 + + - ``V4L2_EXPOSURE_METERING_SPOT`` + + - Measure only very small area at the center of the frame. + + - .. row 4 + + - ``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. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_AUTO_FOCUS_STATUS_IDLE`` + + - Automatic focus is not active. + + - .. row 2 + + - ``V4L2_AUTO_FOCUS_STATUS_BUSY`` + + - Automatic focusing is in progress. + + - .. row 3 + + - ``V4L2_AUTO_FOCUS_STATUS_REACHED`` + + - Focus has been reached. + + - .. row 4 + + - ``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 v4l2_auto_focus_range)`` + Determines auto focus distance range for which lens may be adjusted. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_AUTO_FOCUS_RANGE_AUTO`` + + - The camera automatically selects the focus range. + + - .. row 2 + + - ``V4L2_AUTO_FOCUS_RANGE_NORMAL`` + + - Normal distance range, limited for best automatic focus + performance. + + - .. row 3 + + - ``V4L2_AUTO_FOCUS_RANGE_MACRO`` + + - Macro (close-up) auto focus. The camera will use its minimum + possible distance for auto focus. + + - .. row 4 + + - ``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 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. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_WHITE_BALANCE_MANUAL`` + + - Manual white balance. + + - .. row 2 + + - ``V4L2_WHITE_BALANCE_AUTO`` + + - Automatic white balance adjustments. + + - .. row 3 + + - ``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. + + - .. row 4 + + - ``V4L2_WHITE_BALANCE_FLUORESCENT`` + + - White balance preset for fluorescent lighting. It corresponds + approximately to 4000...5000 K color temperature. + + - .. row 5 + + - ``V4L2_WHITE_BALANCE_FLUORESCENT_H`` + + - With this setting the camera will compensate for fluorescent H + lighting. + + - .. row 6 + + - ``V4L2_WHITE_BALANCE_HORIZON`` + + - White balance setting for horizon daylight. It corresponds + approximately to 5000 K color temperature. + + - .. row 7 + + - ``V4L2_WHITE_BALANCE_DAYLIGHT`` + + - White balance preset for daylight (with clear sky). It corresponds + approximately to 5000...6500 K color temperature. + + - .. row 8 + + - ``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. + + - .. row 9 + + - ``V4L2_WHITE_BALANCE_CLOUDY`` + + - White balance preset for moderately overcast sky. This option + corresponds approximately to 6500...8000 K color temperature + range. + + - .. row 10 + + - ``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. [1]_ + +.. _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 v4l2_iso_sensitivity_type)`` + Enables or disables automatic ISO sensitivity adjustments. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` + + - Manual ISO sensitivity. + + - .. row 2 + + - ``V4L2_CID_ISO_SENSITIVITY_AUTO`` + + - Automatic ISO sensitivity adjustments. + + + +.. _v4l2-scene-mode: + +``V4L2_CID_SCENE_MODE (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: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_SCENE_MODE_NONE`` + + - The scene mode feature is disabled. + + - .. row 2 + + - ``V4L2_SCENE_MODE_BACKLIGHT`` + + - Backlight. Compensates for dark shadows when light is coming from + behind a subject, also by automatically turning on the flash. + + - .. row 3 + + - ``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. + + - .. row 4 + + - ``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. + + - .. row 5 + + - ``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. + + - .. row 6 + + - ``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. + + - .. row 7 + + - ``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. + + - .. row 8 + + - ``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. + + - .. row 9 + + - ``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. + + - .. row 10 + + - ``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. + + - .. row 11 + + - ``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. + + - .. row 12 + + - ``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. + + - .. row 13 + + - ``V4L2_SCENE_MODE_SUNSET`` + + - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps + up the saturation. + + - .. row 14 + + - ``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 + + + - .. row 1 + + - ``V4L2_LOCK_EXPOSURE`` + + - Automatic exposure adjustments lock. + + - .. row 2 + + - ``V4L2_LOCK_WHITE_BALANCE`` + + - Automatic white balance adjustments lock. + + - .. row 3 + + - ``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 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 + + + - .. row 1 + + - ``V4L2_PREEMPHASIS_DISABLED`` + + - No pre-emphasis is applied. + + - .. row 2 + + - ``V4L2_PREEMPHASIS_50_uS`` + + - A pre-emphasis of 50 uS is used. + + - .. row 3 + + - ``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 + + + - .. row 1 + + - ``V4L2_FLASH_LED_MODE_NONE`` + + - Off. + + - .. row 2 + + - ``V4L2_FLASH_LED_MODE_FLASH`` + + - Flash mode. + + - .. row 3 + + - ``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. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE`` + + - The flash strobe is triggered by using the + V4L2_CID_FLASH_STROBE control. + + - .. row 2 + + - ``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. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_FLASH_FAULT_OVER_VOLTAGE`` + + - Flash controller voltage to the flash LED has exceeded the limit + specific to the flash controller. + + - .. row 2 + + - ``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. + + - .. row 3 + + - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE`` + + - The flash controller has overheated. + + - .. row 4 + + - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT`` + + - The short circuit protection of the flash controller has been + triggered. + + - .. row 5 + + - ``V4L2_FLASH_FAULT_OVER_CURRENT`` + + - Current in the LED power supply has exceeded the limit specific to + the flash controller. + + - .. row 6 + + - ``V4L2_FLASH_FAULT_INDICATOR`` + + - The flash controller has detected a short or open circuit + condition on the indicator LED. + + - .. row 7 + + - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE`` + + - Flash controller voltage to the flash LED has been below the + minimum limit specific to the flash controller. + + - .. row 8 + + - ``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. + + - .. row 9 + + - ``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 coverting an input + image from RGB to Y'CbCr color space. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444`` + + - No chroma subsampling, each pixel has Y, Cr and Cb values. + + - .. row 2 + + - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422`` + + - Horizontally subsample Cr, Cb components by a factor of 2. + + - .. row 3 + + - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420`` + + - Subsample Cr, Cb components horizontally and vertically by 2. + + - .. row 4 + + - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411`` + + - Horizontally subsample Cr, Cb components by a factor of 4. + + - .. row 5 + + - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410`` + + - Subsample Cr, Cb components horizontally by 4 and vertically by 2. + + - .. row 6 + + - ``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 + + + - .. row 1 + + - ``V4L2_JPEG_ACTIVE_MARKER_APP0`` + + - Application data segment APP\ :sub:`0`. + + - .. row 2 + + - ``V4L2_JPEG_ACTIVE_MARKER_APP1`` + + - Application data segment APP\ :sub:`1`. + + - .. row 3 + + - ``V4L2_JPEG_ACTIVE_MARKER_COM`` + + - Comment segment. + + - .. row 4 + + - ``V4L2_JPEG_ACTIVE_MARKER_DQT`` + + - Quantization tables segment. + + - .. row 5 + + - ``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. + + +.. _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 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 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 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 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: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS`` + + - Graphics content. Pixel data should be passed unfiltered and + without analog reconstruction. + + - .. row 2 + + - ``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. + + - .. row 3 + + - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA`` + + - Cinema content. + + - .. row 4 + + - ``V4L2_DV_IT_CONTENT_TYPE_GAME`` + + - Game content. Audio and video latency should be minimized. + + - .. row 5 + + - ``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 transmitter. 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 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 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 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 + + + - .. row 1 + + - ``V4L2_DEEMPHASIS_DISABLED`` + + - No de-emphasis is applied. + + - .. row 2 + + - ``V4L2_DEEMPHASIS_50_uS`` + + - A de-emphasis of 50 uS is used. + + - .. row 3 + + - ``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. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_DETECT_MD_MODE_DISABLED`` + + - Disable motion detection. + + - .. row 2 + + - ``V4L2_DETECT_MD_MODE_GLOBAL`` + + - Use a single motion detection threshold. + + - .. row 3 + + - ``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. + + - .. row 4 + + - ``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, whilst 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. + +.. [1] + 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 new file mode 100644 index 000000000000..979fedbb2bda --- /dev/null +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -0,0 +1,205 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _field-order: + +*********** +Field Order +*********** + +We have to distinguish between progressive and interlaced video. +Progressive video transmits all lines of a video image sequentially. +Interlaced video divides an image into two fields, containing only the +odd and even lines of the image, respectively. Alternating the so called +odd and even field are transmitted, and due to a small delay between +fields a cathode ray TV displays the lines interleaved, yielding the +original frame. This curious technique was invented because at refresh +rates similar to film the image would fade out too quickly. Transmitting +fields reduces the flicker without the necessity of doubling the frame +rate and with it the bandwidth required for each channel. + +It is important to understand a video camera does not expose one frame +at a time, merely transmitting the frames separated into fields. The +fields are in fact captured at two different instances in time. An +object on screen may well move between one field and the next. For +applications analysing motion it is of paramount importance to recognize +which field of a frame is older, the *temporal order*. + +When the driver provides or accepts images field by field rather than +interleaved, it is also important applications understand how the fields +combine to frames. We distinguish between top (aka odd) and bottom (aka +even) fields, the *spatial order*: The first line of the top field is +the first line of an interlaced frame, the first line of the bottom +field is the second line of that frame. + +However because fields were captured one after the other, arguing +whether a frame commences with the top or bottom field is pointless. Any +two successive top and bottom, or bottom and top fields yield a valid +frame. Only when the source was progressive to begin with, e. g. when +transferring film to video, two fields may come from the same frame, +creating a natural order. + +Counter to intuition the top field is not necessarily the older field. +Whether the older field contains the top or bottom lines is a convention +determined by the video standard. Hence the distinction between temporal +and spatial order of fields. The diagrams below should make this +clearer. + +All video capture and output devices must report the current field +order. Some drivers may permit the selection of a different order, to +this end applications initialize the ``field`` field of struct +:ref:`v4l2_pix_format <v4l2-pix-format>` before calling the +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it +should have the value ``V4L2_FIELD_ANY`` (0). + + +.. _v4l2-field: + +enum v4l2_field +=============== + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``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 + 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 + :ref:`v4l2_buffer <v4l2-buffer>` ``field`` can never be + ``V4L2_FIELD_ANY``. + + - .. row 2 + + - ``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``. + + - .. row 3 + + - ``V4L2_FIELD_TOP`` + + - 2 + + - Images consist of the top (aka odd) field only. + + - .. row 4 + + - ``V4L2_FIELD_BOTTOM`` + + - 3 + + - Images consist of the bottom (aka even) field only. Applications + may wish to prevent a device from capturing interlaced images + because they will have "comb" or "feathering" artefacts around + moving objects. + + - .. row 5 + + - ``V4L2_FIELD_INTERLACED`` + + - 4 + + - Images contain both fields, interleaved line by line. The temporal + order of the fields (whether the top or bottom field is first + transmitted) depends on the current video standard. M/NTSC + transmits the bottom field first, all other standards the top + field first. + + - .. row 6 + + - ``V4L2_FIELD_SEQ_TB`` + + - 5 + + - Images contain both fields, the top field lines are stored first + in memory, immediately followed by the bottom field lines. Fields + are always stored in temporal order, the older one first in + memory. Image sizes refer to the frame, not fields. + + - .. row 7 + + - ``V4L2_FIELD_SEQ_BT`` + + - 6 + + - Images contain both fields, the bottom field lines are stored + first in memory, immediately followed by the top field lines. + Fields are always stored in temporal order, the older one first in + memory. Image sizes refer to the frame, not fields. + + - .. row 8 + + - ``V4L2_FIELD_ALTERNATE`` + + - 7 + + - The two fields of a frame are passed in separate buffers, in + temporal order, i. e. the older one first. To indicate the field + parity (whether the current field is a top or bottom field) the + driver or application, depending on data direction, must set + struct :ref:`v4l2_buffer <v4l2-buffer>` ``field`` to + ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive + fields pair to build a frame. If fields are successive, without + any dropped fields between them (fields can drop individually), + can be determined from the struct + :ref:`v4l2_buffer <v4l2-buffer>` ``sequence`` field. This + format cannot be selected when using the read/write I/O method + since there is no way to communicate if a field was a top or + bottom field. + + - .. row 9 + + - ``V4L2_FIELD_INTERLACED_TB`` + + - 8 + + - Images contain both fields, interleaved line by line, top field + first. The top field is transmitted first. + + - .. row 10 + + - ``V4L2_FIELD_INTERLACED_BT`` + + - 9 + + - Images contain both fields, interleaved line by line, top field + first. The bottom field is transmitted first. + + + +.. _fieldseq-tb: + +Field Order, Top Field First Transmitted +======================================== + +.. figure:: field-order_files/fieldseq_tb.* + :alt: fieldseq_tb.pdf / fieldseq_tb.gif + :align: center + + +.. _fieldseq-bt: + +Field Order, Bottom Field First Transmitted +=========================================== + +.. figure:: field-order_files/fieldseq_bt.* + :alt: fieldseq_bt.pdf / fieldseq_bt.gif + :align: center + diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif Binary files differnew file mode 100644 index 000000000000..60e8569a76c9 --- /dev/null +++ b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf Binary files differnew file mode 100644 index 000000000000..26598b23f80d --- /dev/null +++ b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif Binary files differnew file mode 100644 index 000000000000..718492f1cfc7 --- /dev/null +++ b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf Binary files differnew file mode 100644 index 000000000000..4965b22ddb3a --- /dev/null +++ b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf diff --git a/Documentation/media/uapi/v4l/format.rst b/Documentation/media/uapi/v4l/format.rst new file mode 100644 index 000000000000..a29dd9466b8f --- /dev/null +++ b/Documentation/media/uapi/v4l/format.rst @@ -0,0 +1,92 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _format: + +************ +Data Formats +************ + + +Data Format Negotiation +======================= + +Different devices exchange different kinds of data with applications, +for example video images, raw or sliced VBI data, RDS datagrams. Even +within one kind many different formats are possible, in particular an +abundance of image formats. Although drivers must provide a default and +the selection persists across closing and reopening a device, +applications should always negotiate a data format before engaging in +data exchange. Negotiation means the application asks for a particular +format and the driver selects and reports the best the hardware can do +to satisfy the request. Of course applications can also just query the +current selection. + +A single mechanism exists to negotiate all data formats using the +aggregate struct :ref:`v4l2_format <v4l2-format>` and the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine +what the hardware *could* do, without actually selecting a new data +format. The data formats supported by the V4L2 API are covered in the +respective device section in :ref:`devices`. For a closer look at +image formats see :ref:`pixfmt`. + +The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the +initialization sequence. Prior to this point multiple panel applications +can access the same device concurrently to select the current input, +change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` +assigns a logical stream (video data, VBI data etc.) exclusively to one +file descriptor. + +Exclusive means no other application, more precisely no other file +descriptor, can grab this stream or change device properties +inconsistent with the negotiated parameters. A video standard change for +example, when the new standard uses a different number of scan lines, +can invalidate the selected image format. Therefore only the file +descriptor owning the stream can make invalidating changes. Accordingly +multiple file descriptors which grabbed different logical streams +prevent each other from interfering with their settings. When for +example video overlay is about to start or already in progress, +simultaneous video capturing may be restricted to the same cropping and +image size. + +When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side +effects are implied by the next step, the selection of an I/O method +with the :ref:`VIDIOC_REQBUFS` ioctl or implicit +with the first :ref:`read() <func-read>` or +:ref:`write() <func-write>` call. + +Generally only one logical stream can be assigned to a file descriptor, +the exception being drivers permitting simultaneous video capturing and +overlay using the same file descriptor for compatibility with V4L and +earlier versions of V4L2. Switching the logical stream or returning into +"panel mode" is possible by closing and reopening the device. Drivers +*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. + +All drivers exchanging data with applications must support the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. + + +Image Format Enumeration +======================== + +Apart of the generic format negotiation functions a special ioctl to +enumerate all image formats supported by video capture, overlay or +output devices is available. [1]_ + +The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported +by all drivers exchanging image data with applications. + + **Important** + + Drivers are not supposed to convert image formats in kernel space. + They must enumerate only formats directly supported by the hardware. + If necessary driver writers should publish an example conversion + routine or library for integration into applications. + +.. [1] + Enumerating formats an application has no a-priori knowledge of + (otherwise it could explicitly ask for them and need not enumerate) + seems useless, but there are applications serving as proxy between + drivers and the actual video applications for which this is useful. diff --git a/Documentation/media/uapi/v4l/func-close.rst b/Documentation/media/uapi/v4l/func-close.rst new file mode 100644 index 000000000000..926a2ccc32e5 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-close.rst @@ -0,0 +1,49 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-close: + +************ +V4L2 close() +************ + +Name +==== + +v4l2-close - Close a V4L2 device + + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + + +.. cpp:function:: int close( int fd ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + + +Description +=========== + +Closes the device. Any I/O in progress is terminated and resources +associated with the file descriptor are freed. However data format +parameters, current input or output, control values or other properties +remain unchanged. + + +Return Value +============ + +The function returns 0 on success, -1 on failure and the ``errno`` is +set appropriately. Possible error codes: + +EBADF + ``fd`` is not a valid open file descriptor. diff --git a/Documentation/media/uapi/v4l/func-ioctl.rst b/Documentation/media/uapi/v4l/func-ioctl.rst new file mode 100644 index 000000000000..5632f48fce1b --- /dev/null +++ b/Documentation/media/uapi/v4l/func-ioctl.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-ioctl: + +************ +V4L2 ioctl() +************ + +Name +==== + +v4l2-ioctl - Program a V4L2 device + + +Synopsis +======== + +.. code-block:: c + + #include <sys/ioctl.h> + + +.. cpp:function:: int ioctl( int fd, int request, void *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + V4L2 ioctl request code as defined in the ``videodev2.h`` header + file, for example VIDIOC_QUERYCAP. + +``argp`` + Pointer to a function parameter, usually a structure. + + +Description +=========== + +The :ref:`ioctl() <func-ioctl>` function is used to program V4L2 devices. The +argument ``fd`` must be an open file descriptor. An ioctl ``request`` +has encoded in it whether the argument is an input, output or read/write +parameter, and the size of the argument ``argp`` in bytes. Macros and +defines specifying V4L2 ioctl requests are located in the +``videodev2.h`` header file. Applications should use their own copy, not +include the version in the kernel sources on the system they compile on. +All V4L2 ioctl requests, their respective function and parameters are +specified in :ref:`user-func`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +When an ioctl that takes an output or read/write parameter fails, the +parameter remains unmodified. diff --git a/Documentation/media/uapi/v4l/func-mmap.rst b/Documentation/media/uapi/v4l/func-mmap.rst new file mode 100644 index 000000000000..3502c2afd894 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-mmap.rst @@ -0,0 +1,134 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-mmap: + +*********** +V4L2 mmap() +*********** + +Name +==== + +v4l2-mmap - Map device memory into application address space + + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + #include <sys/mman.h> + + +.. cpp:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) + + +Arguments +========= + +``start`` + Map the buffer to this address in the application's address space. + When the ``MAP_FIXED`` flag is specified, ``start`` must be a + multiple of the pagesize and mmap will fail when the specified + address cannot be used. Use of this option is discouraged; + applications should just specify a ``NULL`` pointer here. + +``length`` + Length of the memory area to map. This must be the same value as + returned by the driver in the struct + :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the + single-planar API, and the same value as returned by the driver in + the struct :ref:`v4l2_plane <v4l2-plane>` ``length`` field for + the multi-planar API. + +``prot`` + The ``prot`` argument describes the desired memory protection. + Regardless of the device type and the direction of data exchange it + should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read + and write access to image buffers. Drivers should support at least + this combination of flags. Note the Linux ``video-buf`` kernel + module, which is used by the bttv, saa7134, saa7146, cx88 and vivi + driver supports only ``PROT_READ`` | ``PROT_WRITE``. When the + driver does not support the desired protection the + :ref:`mmap() <func-mmap>` function fails. + + Note device memory accesses (e. g. the memory on a graphics card + with video capturing hardware) may incur a performance penalty + compared to main memory accesses, or reads may be significantly + slower than writes or vice versa. Other I/O methods may be more + efficient in this case. + +``flags`` + The ``flags`` parameter specifies the type of the mapped object, + mapping options and whether modifications made to the mapped copy of + the page are private to the process or are to be shared with other + references. + + ``MAP_FIXED`` requests that the driver selects no other address than + the one specified. If the specified address cannot be used, + :ref:`mmap() <func-mmap>` will fail. If ``MAP_FIXED`` is specified, + ``start`` must be a multiple of the pagesize. Use of this option is + discouraged. + + One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. + ``MAP_SHARED`` allows applications to share the mapped memory with + other (e. g. child-) processes. Note the Linux ``video-buf`` module + which is used by the bttv, saa7134, saa7146, cx88 and vivi driver + supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write + semantics. V4L2 applications should not set the ``MAP_PRIVATE``, + ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` flag. + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``offset`` + Offset of the buffer in device memory. This must be the same value + as returned by the driver in the struct + :ref:`v4l2_buffer <v4l2-buffer>` ``m`` union ``offset`` field for + the single-planar API, and the same value as returned by the driver + in the struct :ref:`v4l2_plane <v4l2-plane>` ``m`` union + ``mem_offset`` field for the multi-planar API. + + +Description +=========== + +The :ref:`mmap() <func-mmap>` function asks to map ``length`` bytes starting at +``offset`` in the memory of the device specified by ``fd`` into the +application address space, preferably at address ``start``. This latter +address is a hint only, and is usually specified as 0. + +Suitable length and offset parameters are queried with the +:ref:`VIDIOC_QUERYBUF` ioctl. Buffers must be +allocated with the :ref:`VIDIOC_REQBUFS` ioctl +before they can be queried. + +To unmap buffers the :ref:`munmap() <func-munmap>` function is used. + + +Return Value +============ + +On success :ref:`mmap() <func-mmap>` returns a pointer to the mapped buffer. On +error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set +appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid file descriptor. + +EACCES + ``fd`` is not open for reading and writing. + +EINVAL + The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. + they are too large, or not aligned on a ``PAGESIZE`` boundary.) + + The ``flags`` or ``prot`` value is not supported. + + No buffers have been allocated with the + :ref:`VIDIOC_REQBUFS` ioctl. + +ENOMEM + Not enough physical or virtual memory was available to complete the + request. diff --git a/Documentation/media/uapi/v4l/func-munmap.rst b/Documentation/media/uapi/v4l/func-munmap.rst new file mode 100644 index 000000000000..c29c03f21279 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-munmap.rst @@ -0,0 +1,58 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-munmap: + +************* +V4L2 munmap() +************* + +Name +==== + +v4l2-munmap - Unmap device memory + + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + #include <sys/mman.h> + + +.. cpp:function:: int munmap( void *start, size_t length ) + + +Arguments +========= + +``start`` + Address of the mapped buffer as returned by the + :ref:`mmap() <func-mmap>` function. + +``length`` + Length of the mapped buffer. This must be the same value as given to + :ref:`mmap() <func-mmap>` and returned by the driver in the struct + :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the + single-planar API and in the struct + :ref:`v4l2_plane <v4l2-plane>` ``length`` field for the + multi-planar API. + + +Description +=========== + +Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped +buffer and frees it, if possible. + + +Return Value +============ + +On success :ref:`munmap() <func-munmap>` returns 0, on failure -1 and the +``errno`` variable is set appropriately: + +EINVAL + The ``start`` or ``length`` is incorrect, or no buffers have been + mapped yet. diff --git a/Documentation/media/uapi/v4l/func-open.rst b/Documentation/media/uapi/v4l/func-open.rst new file mode 100644 index 000000000000..06bcadc269a4 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-open.rst @@ -0,0 +1,83 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-open: + +*********** +V4L2 open() +*********** + +Name +==== + +v4l2-open - Open a V4L2 device + + +Synopsis +======== + +.. code-block:: c + + #include <fcntl.h> + + +.. cpp:function:: int open( const char *device_name, int flags ) + + +Arguments +========= + +``device_name`` + Device to be opened. + +``flags`` + Open flags. Access mode must be ``O_RDWR``. This is just a + technicality, input devices still support only reading and output + devices only writing. + + When the ``O_NONBLOCK`` flag is given, the :ref:`read() <func-read>` + function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will + return the ``EAGAIN`` error code when no data is available or no + buffer is in the driver outgoing queue, otherwise these functions + block until data becomes available. All V4L2 drivers exchanging data + with applications must support the ``O_NONBLOCK`` flag. + + Other flags have no effect. + + +Description +=========== + +To open a V4L2 device applications call :ref:`open() <func-open>` with the +desired device name. This function has no side effects; all data format +parameters, current input or output, control values or other properties +remain unchanged. At the first :ref:`open() <func-open>` call after loading the +driver they will be reset to default values, drivers are never in an +undefined state. + + +Return Value +============ + +On success :ref:`open() <func-open>` returns the new file descriptor. On error +-1 is returned, and the ``errno`` variable is set appropriately. +Possible error codes are: + +EACCES + The caller has no permission to access the device. + +EBUSY + The driver does not support multiple opens and the device is already + in use. + +ENXIO + No device corresponding to this device special file exists. + +ENOMEM + Not enough kernel memory was available to complete the request. + +EMFILE + The process already has the maximum number of files open. + +ENFILE + The limit on the total number of files open on the system has been + reached. diff --git a/Documentation/media/uapi/v4l/func-poll.rst b/Documentation/media/uapi/v4l/func-poll.rst new file mode 100644 index 000000000000..e6ceb712b783 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-poll.rst @@ -0,0 +1,116 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-poll: + +*********** +V4L2 poll() +*********** + +Name +==== + +v4l2-poll - Wait for some event on a file descriptor + + +Synopsis +======== + +.. code-block:: c + + #include <sys/poll.h> + + +.. cpp:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) + + +Arguments +========= + + + +Description +=========== + +With the :ref:`poll() <func-poll>` function applications can suspend execution +until the driver has captured data or is ready to accept data for +output. + +When streaming I/O has been negotiated this function waits until a +buffer has been filled by the capture device and can be dequeued with +the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this +function waits until the device is ready to accept a new buffer to be +queued up with the :ref:`VIDIOC_QBUF` ioctl for +display. When buffers are already in the outgoing queue of the driver +(capture) or the incoming queue isn't full (display) the function +returns immediately. + +On success :ref:`poll() <func-poll>` returns the number of file descriptors +that have been selected (that is, file descriptors for which the +``revents`` field of the respective :c:func:`struct pollfd` structure +is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM`` +flags in the ``revents`` field, output devices the ``POLLOUT`` and +``POLLWRNORM`` flags. When the function timed out it returns a value of +zero, on failure it returns -1 and the ``errno`` variable is set +appropriately. When the application did not call +:ref:`VIDIOC_STREAMON` the :ref:`poll() <func-poll>` +function succeeds, but sets the ``POLLERR`` flag in the ``revents`` +field. When the application has called +:ref:`VIDIOC_STREAMON` for a capture device but +hasn't yet called :ref:`VIDIOC_QBUF`, the +:ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in +the ``revents`` field. For output devices this same situation will cause +:ref:`poll() <func-poll>` to succeed as well, but it sets the ``POLLOUT`` and +``POLLWRNORM`` flags in the ``revents`` field. + +If an event occurred (see :ref:`VIDIOC_DQEVENT`) +then ``POLLPRI`` will be set in the ``revents`` field and +:ref:`poll() <func-poll>` will return. + +When use of the :ref:`read() <func-read>` function has been negotiated and the +driver does not capture yet, the :ref:`poll() <func-poll>` function starts +capturing. When that fails it returns a ``POLLERR`` as above. Otherwise +it waits until data has been captured and can be read. When the driver +captures continuously (as opposed to, for example, still images) the +function may return immediately. + +When use of the :ref:`write() <func-write>` function has been negotiated and the +driver does not stream yet, the :ref:`poll() <func-poll>` function starts +streaming. When that fails it returns a ``POLLERR`` as above. Otherwise +it waits until the driver is ready for a non-blocking +:ref:`write() <func-write>` call. + +If the caller is only interested in events (just ``POLLPRI`` is set in +the ``events`` field), then :ref:`poll() <func-poll>` will *not* start +streaming if the driver does not stream yet. This makes it possible to +just poll for events and not for buffers. + +All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` +function or streaming I/O must also support the :ref:`poll() <func-poll>` +function. + +For more details see the :ref:`poll() <func-poll>` manual page. + + +Return Value +============ + +On success, :ref:`poll() <func-poll>` returns the number structures which have +non-zero ``revents`` fields, or zero if the call timed out. On error -1 +is returned, and the ``errno`` variable is set appropriately: + +EBADF + One or more of the ``ufds`` members specify an invalid file + descriptor. + +EBUSY + The driver does not support multiple read or write streams and the + device is already in use. + +EFAULT + ``ufds`` references an inaccessible memory area. + +EINTR + The call was interrupted by a signal. + +EINVAL + The ``nfds`` argument is greater than ``OPEN_MAX``. diff --git a/Documentation/media/uapi/v4l/func-read.rst b/Documentation/media/uapi/v4l/func-read.rst new file mode 100644 index 000000000000..9a2aa5210233 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-read.rst @@ -0,0 +1,131 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-read: + +*********** +V4L2 read() +*********** + +Name +==== + +v4l2-read - Read from a V4L2 device + + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + + +.. cpp:function:: ssize_t read( int fd, void *buf, size_t count ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``buf`` +``count`` + + +Description +=========== + +:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file +descriptor ``fd`` into the buffer starting at ``buf``. The layout of the +data in the buffer is discussed in the respective device interface +section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero +and has no other results. If ``count`` is greater than ``SSIZE_MAX``, +the result is unspecified. Regardless of the ``count`` value each +:ref:`read() <func-read>` call will provide at most one frame (two fields) +worth of data. + +By default :ref:`read() <func-read>` blocks until data becomes available. When +the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` +function it returns immediately with an ``EAGAIN`` error code when no data +is available. The :ref:`select() <func-select>` or +:ref:`poll() <func-poll>` functions can always be used to suspend +execution until data becomes available. All drivers supporting the +:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and +:ref:`poll() <func-poll>`. + +Drivers can implement read functionality in different ways, using a +single or multiple buffers and discarding the oldest or newest frames +once the internal buffers are filled. + +:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled. +Using a single buffer the driver will stop capturing when the +application starts reading the buffer until the read is finished. Thus +only the period of the vertical blanking interval is available for +reading, or the capture rate must fall below the nominal frame rate of +the video standard. + +The behavior of :ref:`read() <func-read>` when called during the active picture +period or the vertical blanking separating the top and bottom field +depends on the discarding policy. A driver discarding the oldest frames +keeps capturing into an internal buffer, continuously overwriting the +previously, not read frame, and returns the frame being received at the +time of the :ref:`read() <func-read>` call as soon as it is complete. + +A driver discarding the newest frames stops capturing until the next +:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>` +time is discarded, returning the following frame instead. Again this +implies a reduction of the capture rate to one half or less of the +nominal frame rate. An example of this model is the video read mode of +the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>` +is called and returning when the DMA finished. + +In the multiple buffer model drivers maintain a ring of internal +buffers, automatically advancing to the next free buffer. This allows +continuous capturing when the application can empty the buffers fast +enough. Again, the behavior when the driver runs out of free buffers +depends on the discarding policy. + +Applications can get and set the number of buffers used internally by +the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and +:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional, +however. The discarding policy is not reported and cannot be changed. +For minimum requirements see :ref:`devices`. + + +Return Value +============ + +On success, the number of bytes read is returned. It is not an error if +this number is smaller than the number of bytes requested, or the amount +of data required for one frame. This may happen for example because +:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is +returned, and the ``errno`` variable is set appropriately. In this case +the next read will start at the beginning of a new frame. Possible error +codes are: + +EAGAIN + Non-blocking I/O has been selected using O_NONBLOCK and no data was + immediately available for reading. + +EBADF + ``fd`` is not a valid file descriptor or is not open for reading, or + the process already has the maximum number of files open. + +EBUSY + The driver does not support multiple read streams and the device is + already in use. + +EFAULT + ``buf`` references an inaccessible memory area. + +EINTR + The call was interrupted by a signal before any data was read. + +EIO + I/O error. This indicates some hardware problem or a failure to + communicate with a remote device (USB camera etc.). + +EINVAL + The :ref:`read() <func-read>` function is not supported by this driver, not + on this device, or generally not on this type of device. diff --git a/Documentation/media/uapi/v4l/func-select.rst b/Documentation/media/uapi/v4l/func-select.rst new file mode 100644 index 000000000000..954dd00b8301 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-select.rst @@ -0,0 +1,106 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-select: + +************* +V4L2 select() +************* + +Name +==== + +v4l2-select - Synchronous I/O multiplexing + + +Synopsis +======== + +.. code-block:: c + + #include <sys/time.h> + #include <sys/types.h> + #include <unistd.h> + + +.. cpp:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout ) + + +Arguments +========= + + + +Description +=========== + +With the :ref:`select() <func-select>` function applications can suspend +execution until the driver has captured data or is ready to accept data +for output. + +When streaming I/O has been negotiated this function waits until a +buffer has been filled or displayed and can be dequeued with the +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in +the outgoing queue of the driver the function returns immediately. + +On success :ref:`select() <func-select>` returns the total number of bits set in +:c:func:`struct fd_set`. When the function timed out it returns +a value of zero. On failure it returns -1 and the ``errno`` variable is +set appropriately. When the application did not call +:ref:`VIDIOC_QBUF` or +:ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>` +function succeeds, setting the bit of the file descriptor in ``readfds`` +or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` +calls will fail. [1]_ + +When use of the :ref:`read() <func-read>` function has been negotiated and the +driver does not capture yet, the :ref:`select() <func-select>` function starts +capturing. When that fails, :ref:`select() <func-select>` returns successful and +a subsequent :ref:`read() <func-read>` call, which also attempts to start +capturing, will return an appropriate error code. When the driver +captures continuously (as opposed to, for example, still images) and +data is already available the :ref:`select() <func-select>` function returns +immediately. + +When use of the :ref:`write() <func-write>` function has been negotiated the +:ref:`select() <func-select>` function just waits until the driver is ready for a +non-blocking :ref:`write() <func-write>` call. + +All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` +function or streaming I/O must also support the :ref:`select() <func-select>` +function. + +For more details see the :ref:`select() <func-select>` manual page. + + +Return Value +============ + +On success, :ref:`select() <func-select>` returns the number of descriptors +contained in the three returned descriptor sets, which will be zero if +the timeout expired. On error -1 is returned, and the ``errno`` variable +is set appropriately; the sets and ``timeout`` are undefined. Possible +error codes are: + +EBADF + One or more of the file descriptor sets specified a file descriptor + that is not open. + +EBUSY + The driver does not support multiple read or write streams and the + device is already in use. + +EFAULT + The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer + references an inaccessible memory area. + +EINTR + The call was interrupted by a signal. + +EINVAL + The ``nfds`` argument is less than zero or greater than + ``FD_SETSIZE``. + +.. [1] + The Linux kernel implements :ref:`select() <func-select>` like the + :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot + return a ``POLLERR``. diff --git a/Documentation/media/uapi/v4l/func-write.rst b/Documentation/media/uapi/v4l/func-write.rst new file mode 100644 index 000000000000..a3bc9b26fe56 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-write.rst @@ -0,0 +1,82 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-write: + +************ +V4L2 write() +************ + +Name +==== + +v4l2-write - Write to a V4L2 device + + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + + +.. cpp:function:: ssize_t write( int fd, void *buf, size_t count ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``buf`` +``count`` + + +Description +=========== + +:ref:`write() <func-write>` writes up to ``count`` bytes to the device +referenced by the file descriptor ``fd`` from the buffer starting at +``buf``. When the hardware outputs are not active yet, this function +enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0 +without any other effect. + +When the application does not provide more data in time, the previous +video frame, raw VBI image, sliced VPS or WSS data is displayed again. +Sliced Teletext or Closed Caption data is not repeated, the driver +inserts a blank line instead. + + +Return Value +============ + +On success, the number of bytes written are returned. Zero indicates +nothing was written. On error, -1 is returned, and the ``errno`` +variable is set appropriately. In this case the next write will start at +the beginning of a new frame. Possible error codes are: + +EAGAIN + Non-blocking I/O has been selected using the + :ref:`O_NONBLOCK <func-open>` flag and no buffer space was + available to write the data immediately. + +EBADF + ``fd`` is not a valid file descriptor or is not open for writing. + +EBUSY + The driver does not support multiple write streams and the device is + already in use. + +EFAULT + ``buf`` references an inaccessible memory area. + +EINTR + The call was interrupted by a signal before any data was written. + +EIO + I/O error. This indicates some hardware problem. + +EINVAL + The :ref:`write() <func-write>` function is not supported by this driver, + not on this device, or generally not on this type of device. diff --git a/Documentation/media/uapi/v4l/hist-v4l2.rst b/Documentation/media/uapi/v4l/hist-v4l2.rst new file mode 100644 index 000000000000..a571e099fde7 --- /dev/null +++ b/Documentation/media/uapi/v4l/hist-v4l2.rst @@ -0,0 +1,1480 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _hist-v4l2: + +*********************** +Changes of the V4L2 API +*********************** + +Soon after the V4L API was added to the kernel it was criticised as too +inflexible. In August 1998 Bill Dirks proposed a number of improvements +and began to work on documentation, example drivers and applications. +With the help of other volunteers this eventually became the V4L2 API, +not just an extension but a replacement for the V4L API. However it took +another four years and two stable kernel releases until the new API was +finally accepted for inclusion into the kernel in its present form. + + +Early Versions +============== + +1998-08-20: First version. + +1998-08-27: The :ref:`select() <func-select>` function was introduced. + +1998-09-10: New video standard interface. + +1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise +meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the +aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set +this flag if they intend to access controls only, as opposed to capture +applications which need exclusive access. The ``VIDEO_STD_XXX`` +identifiers are now ordinals instead of flags, and the +:c:func:`video_std_construct()` helper function takes id and +transmission arguments. + +1998-09-28: Revamped video standard. Made video controls individually +enumerable. + +1998-10-02: The ``id`` field was removed from struct +:c:type:`struct video_standard` and the color subcarrier fields were +renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was +renamed to :ref:`VIDIOC_ENUMSTD`, +:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to +:ref:`VIDIOC_ENUMINPUT`. A first draft of the +Codec API was released. + +1998-11-08: Many minor changes. Most symbols have been renamed. Some +material changes to struct :ref:`v4l2_capability <v4l2-capability>`. + +1998-11-12: The read/write directon of some ioctls was misdefined. + +1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, +and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio +controls are now accessible with the +:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and +:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls under names starting +with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from +``videodev.h`` since it was only used once in the ``videodev`` kernel +module. The ``YUV422`` and ``YUV411`` planar image formats were added. + +1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video +output devices were added. + +1999-01-14: A raw VBI capture interface was added. + +1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed. + + +V4L2 Version 0.16 1999-01-31 +============================ + +1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF +are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added +digital zoom (cropping) controls. + + +V4L2 Version 0.18 1999-03-16 +============================ + +Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver +writers, this changes how you implement your ioctl handler. See the +Driver Writer's Guide. Added some more control id codes. + + +V4L2 Version 0.19 1999-06-05 +============================ + +1999-03-18: Fill in the category and catname fields of v4l2_queryctrl +objects before passing them to the driver. Required a minor change to +the VIDIOC_QUERYCTRL handlers in the sample drivers. + +1999-03-31: Better compatibility for v4l memory capture ioctls. Requires +changes to drivers to fully support new compatibility features, see +Driver Writer's Guide and v4l2cap.c. Added new control IDs: +V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, +and _YUV411P to _YUV411P. + +1999-04-04: Added a few more control IDs. + +1999-04-07: Added the button control type. + +1999-05-02: Fixed a typo in videodev.h, and added the +V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag. + +1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a +malfunction of this ioctl. + +1999-06-05: Changed the value of V4L2_CID_WHITENESS. + + +V4L2 Version 0.20 (1999-09-10) +============================== + +Version 0.20 introduced a number of changes which were *not backward +compatible* with 0.19 and earlier versions. Purpose of these changes was +to simplify the API, while making it more extensible and following +common Linux driver API conventions. + +1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct + :ref:`v4l2_clip <v4l2-clip>` was changed for compatibility with + v4l. (1999-08-30) + +2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05) + +3. All ioctl() commands that used an integer argument now take a pointer + to an integer. Where it makes sense, ioctls will return the actual + new value in the integer pointed to by the argument, a common + convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW, + VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, + VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example + + + .. code-block:: c + + err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); + + becomes + + + .. code-block:: c + + int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); + +4. All the different get- and set-format commands were swept into one + :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl taking a union and a + type field selecting the union member as parameter. Purpose is to + simplify the API by eliminating several ioctls and to allow new and + driver private data streams without adding new ioctls. + + This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``, + ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``, + ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format + structure :c:type:`struct v4l2_format` was renamed to struct + :ref:`v4l2_pix_format <v4l2-pix-format>`, while struct + :ref:`v4l2_format <v4l2-format>` is now the envelopping structure + for all format negotiations. + +5. Similar to the changes above, the ``VIDIOC_G_PARM`` and + ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and + ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct + :ref:`v4l2_streamparm <v4l2-streamparm>` selects the respective + union member. + + This change obsoletes the ``VIDIOC_G_OUTPARM`` and + ``VIDIOC_S_OUTPARM`` ioctls. + +6. Control enumeration was simplified, and two new control flags were + introduced and one dropped. The ``catname`` field was replaced by a + ``group`` field. + + Drivers can now flag unsupported and temporarily unavailable controls + with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2_CTRL_FLAG_GRABBED`` + respectively. The ``group`` name indicates a possibly narrower + classification than the ``category``. In other words, there may be + multiple groups within a category. Controls within a group would + typically be drawn within a group box. Controls in different + categories might have a greater separation, or may even appear in + separate windows. + +7. The struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` was + changed to a 64 bit integer, containing the sampling or output time + of the frame in nanoseconds. Additionally timestamps will be in + absolute system time, not starting from zero at the beginning of a + stream. The data type name for timestamps is stamp_t, defined as a + signed 64-bit integer. Output devices should not send a buffer out + until the time in the timestamp field has arrived. I would like to + follow SGI's lead, and adopt a multimedia timestamping system like + their UST (Unadjusted System Time). See + http://web.archive.org/web/\*/http://reality.sgi.com + /cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are + 64-bit signed integers (not struct timeval's) and given in nanosecond + units. The UST clock starts at zero when the system is booted and + runs continuously and uniformly. It takes a little over 292 years for + UST to overflow. There is no way to set the UST clock. The regular + Linux time-of-day clock can be changed periodically, which would + cause errors if it were being used for timestamping a multimedia + stream. A real UST style clock will require some support in the + kernel that is not there yet. But in anticipation, I will change the + timestamp field to a 64-bit integer, and I will change the + v4l2_masterclock_gettime() function (used only by drivers) to + return a 64-bit integer. + +8. A ``sequence`` field was added to struct + :ref:`v4l2_buffer <v4l2-buffer>`. The ``sequence`` field counts + captured frames, it is ignored by output devices. When a capture + driver drops a frame, the sequence number of that frame is skipped. + + +V4L2 Version 0.20 incremental changes +===================================== + +1999-12-23: In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the +``reserved1`` field became ``offset``. Previously drivers were required +to clear the ``reserved1`` field. + +2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added. + +2000-07-31: The ``linux/poll.h`` header is now included by +``videodev.h`` for compatibility with the original ``videodev.h`` file. + +2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were +added. + +2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added. + +2000-12-04: A couple typos in symbol names were fixed. + +2001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in +the ``videodev.h`` header file was renamed to ``v4l2_fourcc``. + +2001-01-25: A possible driver-level compatibility problem between the +``videodev.h`` file in Linux 2.4.0 and the ``videodev.h`` file included +in the ``videodevX`` patch was fixed. Users of an earlier version of +``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2 +drivers. + +2001-01-26: A possible kernel-level incompatibility between the +``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h`` +file in Linux 2.2.x with devfs patches applied was fixed. + +2001-03-02: Certain V4L ioctls which pass data in both direction +although they are defined with read-only parameter, did not work +correctly through the backward compatibility layer. [Solution?] + +2001-04-13: Big endian 16-bit RGB formats were added. + +2001-09-17: New YUV formats and the +:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and +:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctls were added. +(The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take +multiple tuners into account.) + +2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break +compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct +:c:type:`struct v4l2_fmt` ``type`` field does not contain +``V4L2_BUF_TYPE_VBI``. In the documentation of the struct +:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``offset`` field the +ambiguous phrase "rising edge" was changed to "leading edge". + + +V4L2 Version 0.20 2000-11-23 +============================ + +A number of changes were made to the raw VBI interface. + +1. Figures clarifying the line numbering scheme were added to the V4L2 + API specification. The ``start``\ [0] and ``start``\ [1] fields no + longer count line numbers beginning at zero. Rationale: a) The + previous definition was unclear. b) The ``start``\ [] values are + ordinal numbers. c) There is no point in inventing a new line + numbering scheme. We now use line number as defined by ITU-R, period. + Compatibility: Add one to the start values. Applications depending on + the previous semantics may not function correctly. + +2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to + "(count[0] + count[1]) > 0". Rationale: Drivers may allocate + resources at scan line granularity and some data services are + transmitted only on the first field. The comment that both ``count`` + values will usually be equal is misleading and pointless and has been + removed. This change *breaks compatibility* with earlier versions: + Drivers may return ``EINVAL``, applications may not function correctly. + +3. Drivers are again permitted to return negative (unknown) start values + as proposed earlier. Why this feature was dropped is unclear. This + change may *break compatibility* with applications depending on the + start values being positive. The use of ``EBUSY`` and ``EINVAL`` + error codes with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl was + clarified. The ``EBUSY`` error code was finally documented, and the + ``reserved2`` field which was previously mentioned only in the + ``videodev.h`` header file. + +4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``V4L2_TYPE_VBI_OUTPUT`` + were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the + latter was missing in the ``videodev.h`` file. + + +V4L2 Version 0.20 2002-07-25 +============================ + +Added sliced VBI interface proposal. + + +V4L2 in Linux 2.5.46, 2002-10 +============================= + +Around October-November 2002, prior to an announced feature freeze of +Linux 2.5, the API was revised, drawing from experience with V4L2 0.20. +This unnamed version was finally merged into Linux 2.5.46. + +1. As specified in :ref:`related`, drivers must make related device + functions available under all minor device numbers. + +2. The :ref:`open() <func-open>` function requires access mode + ``O_RDWR`` regardless of the device type. All V4L2 drivers + exchanging data with applications must support the ``O_NONBLOCK`` + flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the + meaningless ``O_TRUNC`` to indicate accesses without data exchange + (panel applications) was dropped. Drivers must stay in "panel mode" + until the application attempts to initiate a data exchange, see + :ref:`open`. + +3. The struct :ref:`v4l2_capability <v4l2-capability>` changed + dramatically. Note that also the size of the structure changed, + which is encoded in the ioctl request code, thus older V4L2 devices + will respond with an ``EINVAL`` error code to the new + :ref:`VIDIOC_QUERYCAP` ioctl. + + There are new fields to identify the driver, a new RDS device + function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag + indicates if the device has any audio connectors, another I/O + capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these + changes the ``type`` field became a bit set and was merged into the + ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to + ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced + ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and + ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``. + ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into + ``V4L2_CAP_READWRITE``. + + The redundant fields ``inputs``, ``outputs`` and ``audios`` were + removed. These properties can be determined as described in + :ref:`video` and :ref:`audio`. + + The somewhat volatile and therefore barely useful fields + ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``, + ``maxframerate`` were removed. This information is available as + described in :ref:`format` and :ref:`standard`. + + ``V4L2_FLAG_SELECT`` was removed. We believe the select() function + is important enough to require support of it in all V4L2 drivers + exchanging data with applications. The redundant + ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is + available as described in :ref:`format`. + +4. In struct :ref:`v4l2_input <v4l2-input>` the ``assoc_audio`` + field and the ``capability`` field and its only flag + ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field. + Instead of linking one video input to one audio input this field + reports all audio inputs this video input combines with. + + New fields are ``tuner`` (reversing the former link from tuners to + video inputs), ``std`` and ``status``. + + Accordingly struct :ref:`v4l2_output <v4l2-output>` lost its + ``capability`` and ``assoc_audio`` fields. ``audioset``, + ``modulator`` and ``std`` where added instead. + +5. The struct :ref:`v4l2_audio <v4l2-audio>` field ``audio`` was + renamed to ``index``, for consistency with other structures. A new + capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the + audio input in question supports stereo sound. + ``V4L2_AUDCAP_EFFECTS`` and the corresponding ``V4L2_AUDMODE`` flags + where removed. This can be easily implemented using controls. + (However the same applies to AVL which is still there.) + + Again for consistency the struct + :ref:`v4l2_audioout <v4l2-audioout>` field ``audio`` was renamed + to ``index``. + +6. The struct :ref:`v4l2_tuner <v4l2-tuner>` ``input`` field was + replaced by an ``index`` field, permitting devices with multiple + tuners. The link between video inputs and tuners is now reversed, + inputs point to their tuner. The ``std`` substructure became a + simple set (more about this below) and moved into struct + :ref:`v4l2_input <v4l2-input>`. A ``type`` field was added. + + Accordingly in struct :ref:`v4l2_modulator <v4l2-modulator>` the + ``output`` was replaced by an ``index`` field. + + In struct :ref:`v4l2_frequency <v4l2-frequency>` the ``port`` + field was replaced by a ``tuner`` field containing the respective + tuner or modulator index number. A tuner ``type`` field was added + and the ``reserved`` field became larger for future extensions + (satellite tuners in particular). + +7. The idea of completely transparent video standards was dropped. + Experience showed that applications must be able to work with video + standards beyond presenting the user a menu. Instead of enumerating + supported standards with an ioctl applications can now refer to + standards by :ref:`v4l2_std_id <v4l2-std-id>` and symbols + defined in the ``videodev2.h`` header file. For details see + :ref:`standard`. The :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and + :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this + type as argument. :ref:`VIDIOC_QUERYSTD` was + added to autodetect the received standard, if the hardware has this + capability. In struct :ref:`v4l2_standard <v4l2-standard>` an + ``index`` field was added for + :ref:`VIDIOC_ENUMSTD`. A + :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as + machine readable identifier, also replacing the ``transmission`` + field. The misleading ``framerate`` field was renamed to + ``frameperiod``. The now obsolete ``colorstandard`` information, + originally needed to distguish between variations of standards, were + removed. + + Struct :c:type:`struct v4l2_enumstd` ceased to be. + :ref:`VIDIOC_ENUMSTD` now takes a pointer to a + struct :ref:`v4l2_standard <v4l2-standard>` directly. The + information which standards are supported by a particular video + input or output moved into struct :ref:`v4l2_input <v4l2-input>` + and struct :ref:`v4l2_output <v4l2-output>` fields named ``std``, + respectively. + +8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields + ``category`` and ``group`` did not catch on and/or were not + implemented as expected and therefore removed. + +9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl was added to + negotiate data formats as with + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of + programming the hardware and regardless of I/O in progress. + + In struct :ref:`v4l2_format <v4l2-format>` the ``fmt`` union was + extended to contain struct :ref:`v4l2_window <v4l2-window>`. All + image format negotiations are now possible with ``VIDIOC_G_FMT``, + ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN`` + and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were + removed. The ``type`` field changed to type enum + :ref:`v4l2_buf_type <v4l2-buf-type>` and the buffer type names + changed as follows. + + + + .. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Old defines + + - enum :ref:`v4l2_buf_type <v4l2-buf-type>` + + - .. row 2 + + - ``V4L2_BUF_TYPE_CAPTURE`` + + - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` + + - .. row 3 + + - ``V4L2_BUF_TYPE_CODECIN`` + + - Omitted for now + + - .. row 4 + + - ``V4L2_BUF_TYPE_CODECOUT`` + + - Omitted for now + + - .. row 5 + + - ``V4L2_BUF_TYPE_EFFECTSIN`` + + - Omitted for now + + - .. row 6 + + - ``V4L2_BUF_TYPE_EFFECTSIN2`` + + - Omitted for now + + - .. row 7 + + - ``V4L2_BUF_TYPE_EFFECTSOUT`` + + - Omitted for now + + - .. row 8 + + - ``V4L2_BUF_TYPE_VIDEOOUT`` + + - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` + + - .. row 9 + + - ``-`` + + - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` + + - .. row 10 + + - ``-`` + + - ``V4L2_BUF_TYPE_VBI_CAPTURE`` + + - .. row 11 + + - ``-`` + + - ``V4L2_BUF_TYPE_VBI_OUTPUT`` + + - .. row 12 + + - ``-`` + + - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` + + - .. row 13 + + - ``-`` + + - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` + + - .. row 14 + + - ``V4L2_BUF_TYPE_PRIVATE_BASE`` + + - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated) + + +10. In struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` a enum + :ref:`v4l2_buf_type <v4l2-buf-type>` field named ``type`` was + added as in struct :ref:`v4l2_format <v4l2-format>`. The + ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed. + These calls can be replaced by + :ref:`VIDIOC_ENUM_FMT` with type + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. + +11. In struct :ref:`v4l2_pix_format <v4l2-pix-format>` the ``depth`` + field was removed, assuming applications which recognize the format + by its four-character-code already know the color depth, and others + do not care about it. The same rationale lead to the removal of the + ``V4L2_FMT_FLAG_COMPRESSED`` flag. The + ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag was removed because drivers + are not supposed to convert images in kernel space. A user library + of conversion functions should be provided instead. The + ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was redundant. Applications can + set the ``bytesperline`` field to zero to get a reasonable default. + Since the remaining flags were replaced as well, the ``flags`` field + itself was removed. + + The interlace flags were replaced by a enum + :ref:`v4l2_field <v4l2-field>` value in a newly added ``field`` + field. + + + + .. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Old flag + + - enum :ref:`v4l2_field <v4l2-field>` + + - .. row 2 + + - ``V4L2_FMT_FLAG_NOT_INTERLACED`` + + - ? + + - .. row 3 + + - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED`` + + - ``V4L2_FIELD_INTERLACED`` + + - .. row 4 + + - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD`` + + - ``V4L2_FIELD_TOP`` + + - .. row 5 + + - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD`` + + - ``V4L2_FIELD_BOTTOM`` + + - .. row 6 + + - ``-`` + + - ``V4L2_FIELD_SEQ_TB`` + + - .. row 7 + + - ``-`` + + - ``V4L2_FIELD_SEQ_BT`` + + - .. row 8 + + - ``-`` + + - ``V4L2_FIELD_ALTERNATE`` + + + The color space flags were replaced by a enum + :ref:`v4l2_colorspace <v4l2-colorspace>` value in a newly added + ``colorspace`` field, where one of ``V4L2_COLORSPACE_SMPTE170M``, + ``V4L2_COLORSPACE_BT878``, ``V4L2_COLORSPACE_470_SYSTEM_M`` or + ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``. + +12. In struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` the + ``type`` field was properly defined as enum + :ref:`v4l2_buf_type <v4l2-buf-type>`. Buffer types changed as + mentioned above. A new ``memory`` field of type enum + :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between + I/O methods using buffers allocated by the driver or the + application. See :ref:`io` for details. + +13. In struct :ref:`v4l2_buffer <v4l2-buffer>` the ``type`` field was + properly defined as enum :ref:`v4l2_buf_type <v4l2-buf-type>`. + Buffer types changed as mentioned above. A ``field`` field of type + enum :ref:`v4l2_field <v4l2-field>` was added to indicate if a + buffer contains a top or bottom field. The old field flags were + removed. Since no unadjusted system time clock was added to the + kernel as planned, the ``timestamp`` field changed back from type + stamp_t, an unsigned 64 bit integer expressing the sample time in + nanoseconds, to struct :c:type:`struct timeval`. With the addition + of a second memory mapping method the ``offset`` field moved into + union ``m``, and a new ``memory`` field of type enum + :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between + I/O methods. See :ref:`io` for details. + + The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility + layer, after changes to this code it was no longer needed. The + ``V4L2_BUF_ATTR_DEVICEMEM`` flag would indicate if the buffer was + indeed allocated in device memory rather than DMA-able system + memory. It was barely useful and so was removed. + +14. In struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` the + ``base[3]`` array anticipating double- and triple-buffering in + off-screen video memory, however without defining a synchronization + mechanism, was replaced by a single pointer. The + ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_CAP_SCALEDOWN`` flags were + removed. Applications can determine this capability more accurately + using the new cropping and scaling interface. The + ``V4L2_FBUF_CAP_CLIPPING`` flag was replaced by + ``V4L2_FBUF_CAP_LIST_CLIPPING`` and + ``V4L2_FBUF_CAP_BITMAP_CLIPPING``. + +15. In struct :ref:`v4l2_clip <v4l2-clip>` the ``x``, ``y``, + ``width`` and ``height`` field moved into a ``c`` substructure of + type struct :ref:`v4l2_rect <v4l2-rect>`. The ``x`` and ``y`` + fields were renamed to ``left`` and ``top``, i. e. offsets to a + context dependent origin. + +16. In struct :ref:`v4l2_window <v4l2-window>` the ``x``, ``y``, + ``width`` and ``height`` field moved into a ``w`` substructure as + above. A ``field`` field of type %v4l2-field; was added to + distinguish between field and frame (interlaced) overlay. + +17. The digital zoom interface, including struct + :c:type:`struct v4l2_zoomcap`, struct + :c:type:`struct v4l2_zoom`, ``V4L2_ZOOM_NONCAP`` and + ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and + scaling interface. The previously unused struct + :c:type:`struct v4l2_cropcap` and :c:type:`struct v4l2_crop` + where redefined for this purpose. See :ref:`crop` for details. + +18. In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the + ``SAMPLE_FORMAT`` field now contains a four-character-code as used + to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces + the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was + extended. + +19. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` the type of + the ``timeperframe`` field changed from unsigned long to struct + :ref:`v4l2_fract <v4l2-fract>`. This allows the accurate + expression of multiples of the NTSC-M frame rate 30000 / 1001. A new + field ``readbuffers`` was added to control the driver behaviour in + read I/O mode. + + Similar changes were made to struct + :ref:`v4l2_outputparm <v4l2-outputparm>`. + +20. The struct :c:type:`struct v4l2_performance` and + ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the + :ref:`read/write I/O method <rw>`, which is limited anyway, this + information is already available to applications. + +21. The example transformation from RGB to YCbCr color space in the old + V4L2 documentation was inaccurate, this has been corrected in + :ref:`pixfmt`. + + +V4L2 2003-06-19 +=============== + +1. A new capability flag ``V4L2_CAP_RADIO`` was added for radio devices. + Prior to this change radio devices would identify solely by having + exactly one tuner whose type field reads ``V4L2_TUNER_RADIO``. + +2. An optional driver access priority mechanism was added, see + :ref:`app-pri` for details. + +3. The audio input and output interface was found to be incomplete. + + Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl would + enumerate the available audio inputs. An ioctl to determine the + current audio input, if more than one combines with the current video + input, did not exist. So ``VIDIOC_G_AUDIO`` was renamed to + ``VIDIOC_G_AUDIO_OLD``, this ioctl was removed on Kernel 2.6.39. The + :ref:`VIDIOC_ENUMAUDIO` ioctl was added to + enumerate audio inputs, while + :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now reports the current + audio input. + + The same changes were made to + :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` and + :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>`. + + Until further the "videodev" module will automatically translate + between the old and new ioctls, but drivers and applications must be + updated to successfully compile again. + +4. The :ref:`VIDIOC_OVERLAY` ioctl was incorrectly + defined with write-read parameter. It was changed to write-only, + while the write-read version was renamed to ``VIDIOC_OVERLAY_OLD``. + The old ioctl was removed on Kernel 2.6.39. Until further the + "videodev" kernel module will automatically translate to the new + version, so drivers must be recompiled, but not applications. + +5. :ref:`overlay` incorrectly stated that clipping rectangles define + regions where the video can be seen. Correct is that clipping + rectangles define regions where *no* video shall be displayed and so + the graphics surface can be seen. + +6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` and + :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls were defined with + write-only parameter, inconsistent with other ioctls modifying their + argument. They were changed to write-read, while a ``_OLD`` suffix + was added to the write-only versions. The old ioctls were removed on + Kernel 2.6.39. Drivers and applications assuming a constant parameter + need an update. + + +V4L2 2003-11-05 +=============== + +1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly + transferred from Bill Dirks' V4L2 specification. Descriptions below + refer to bytes in memory, in ascending address order. + + + + .. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Symbol + + - In this document prior to revision 0.5 + + - Corrected + + - .. row 2 + + - ``V4L2_PIX_FMT_RGB24`` + + - B, G, R + + - R, G, B + + - .. row 3 + + - ``V4L2_PIX_FMT_BGR24`` + + - R, G, B + + - B, G, R + + - .. row 4 + + - ``V4L2_PIX_FMT_RGB32`` + + - B, G, R, X + + - R, G, B, X + + - .. row 5 + + - ``V4L2_PIX_FMT_BGR32`` + + - R, G, B, X + + - B, G, R, X + + + The ``V4L2_PIX_FMT_BGR24`` example was always correct. + + In :ref:`v4l-image-properties` the mapping of the V4L + ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2 + pixel formats was accordingly corrected. + +2. Unrelated to the fixes above, drivers may still interpret some V4L2 + RGB pixel formats differently. These issues have yet to be addressed, + for details see :ref:`pixfmt-rgb`. + + +V4L2 in Linux 2.6.6, 2004-05-09 +=============================== + +1. The :ref:`VIDIOC_CROPCAP` ioctl was incorrectly + defined with read-only parameter. It is now defined as write-read + ioctl, while the read-only version was renamed to + ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39. + + +V4L2 in Linux 2.6.8 +=================== + +1. A new field ``input`` (former ``reserved[0]``) was added to the + struct :ref:`v4l2_buffer <v4l2-buffer>` structure. Purpose of this + field is to alternate between video inputs (e. g. cameras) in step + with the video capturing process. This function must be enabled with + the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no + longer read-only. + + +V4L2 spec erratum 2004-08-01 +============================ + +1. The return value of the :ref:`func-open` function was incorrectly + documented. + +2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT. + +3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took + the wrong argument. + +4. The documentation of the :ref:`VIDIOC_QBUF` and + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the + struct :ref:`v4l2_buffer <v4l2-buffer>` ``memory`` field. It was + also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO`` + error code was not documented. + + +V4L2 in Linux 2.6.14 +==================== + +1. A new sliced VBI interface was added. It is documented in + :ref:`sliced` and replaces the interface first proposed in V4L2 + specification 0.8. + + +V4L2 in Linux 2.6.15 +==================== + +1. The :ref:`VIDIOC_LOG_STATUS` ioctl was added. + +2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``, + ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and + ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and + ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60`` + set now includes ``V4L2_STD_NTSC_443``. See also + :ref:`v4l2-std-id`. + +3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to + ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their + argument was replaced by a struct + :c:type:`struct v4l2_mpeg_compression` pointer. (The + ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed + in Linux 2.6.25.) + + +V4L2 spec erratum 2005-11-27 +============================ + +The capture example in :ref:`capture-example` called the +:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if +cropping is supported. In the video standard selection example in +:ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used +the wrong argument type. + + +V4L2 spec erratum 2006-01-10 +============================ + +1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct + :ref:`v4l2_input <v4l2-input>` not only indicates if the color + killer is enabled, but also if it is active. (The color killer + disables color decoding when it detects no color in the video signal + to improve the image quality.) + +2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not + write-only as stated on its reference page. The ioctl changed in 2003 + as noted above. + + +V4L2 spec erratum 2006-02-03 +============================ + +1. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` and struct + :ref:`v4l2_outputparm <v4l2-outputparm>` the ``timeperframe`` + field gives the time in seconds, not microseconds. + + +V4L2 spec erratum 2006-02-04 +============================ + +1. The ``clips`` field in struct :ref:`v4l2_window <v4l2-window>` + must point to an array of struct :ref:`v4l2_clip <v4l2-clip>`, not + a linked list, because drivers ignore the struct + :c:type:`struct v4l2_clip`. ``next`` pointer. + + +V4L2 in Linux 2.6.17 +==================== + +1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M + South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``, + ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and + ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and + ``V4L2_STD_SECAM_LC`` respectively. + +2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both + languages of a bilingual program. The use of + ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See + the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details. + + +V4L2 spec erratum 2006-09-23 (Draft 0.15) +========================================= + +1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and + ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were + not mentioned along with other buffer types. + +2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the struct + :ref:`v4l2_audio <v4l2-audio>` ``mode`` field is a flags field. + +3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio + capability flags. + +4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that applications + must initialize the tuner ``type`` field of struct + :ref:`v4l2_frequency <v4l2-frequency>` before calling + :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. + +5. The ``reserved`` array in struct + :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` has 2 elements, + not 32. + +6. In :ref:`output` and :ref:`raw-vbi` the device file names + ``/dev/vout`` which never caught on were replaced by ``/dev/video``. + +7. With Linux 2.6.15 the possible range for VBI device minor numbers was + extended from 224-239 to 224-255. Accordingly device file names + ``/dev/vbi0`` to ``/dev/vbi31`` are possible now. + + +V4L2 in Linux 2.6.18 +==================== + +1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and + :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` were added, a + flag to skip unsupported controls with + :ref:`VIDIOC_QUERYCTRL`, new control types + ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS`` + (:ref:`v4l2-ctrl-type`), and new control flags + ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``, + ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER`` + (:ref:`control-flags`). See :ref:`extended-controls` for details. + + +V4L2 in Linux 2.6.19 +==================== + +1. In struct :ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>` a + buffer type field was added replacing a reserved field. Note on + architectures where the size of enum types differs from int types the + size of the structure changed. The + :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl + was redefined from being read-only to write-read. Applications must + initialize the type field and clear the reserved fields now. These + changes may *break the compatibility* with older drivers and + applications. + +2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES` + and + :ref:`VIDIOC_ENUM_FRAMEINTERVALS` + were added. + +3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) was + added. + + +V4L2 spec erratum 2006-10-12 (Draft 0.17) +========================================= + +1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not + 4:2:2 format. + + +V4L2 in Linux 2.6.21 +==================== + +1. The ``videodev2.h`` header file is now dual licensed under GNU + General Public License version two or later, and under a 3-clause + BSD-style license. + + +V4L2 in Linux 2.6.22 +==================== + +1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and + ``V4L2_FIELD_INTERLACED_BT`` were added. See :ref:`v4l2-field` for + details. + +2. Three new clipping/blending methods with a global or straight or + inverted local alpha value were added to the video overlay interface. + See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` + and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details. + + A new ``global_alpha`` field was added to + :ref:`v4l2_window <v4l2-window>`, extending the structure. This + may *break compatibility* with applications using a struct + :c:type:`struct v4l2_window` directly. However the + :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a + pointer to a :ref:`v4l2_format <v4l2-format>` parent structure + with padding bytes at the end, are not affected. + +3. The format of the ``chromakey`` field in struct + :ref:`v4l2_window <v4l2-window>` changed from "host order RGB32" + to a pixel value in the same format as the framebuffer. This may + *break compatibility* with existing applications. Drivers supporting + the "host order RGB32" format are not known. + + +V4L2 in Linux 2.6.24 +==================== + +1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``, + ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and + ``V4L2_PIX_FMT_YUV32`` were added. + + +V4L2 in Linux 2.6.25 +==================== + +1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and + :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added. + +2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``, + ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``, + ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were + added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``, + ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated. + +3. A :ref:`Camera controls class <camera-controls>` was added, with + the new controls ``V4L2_CID_EXPOSURE_AUTO``, + ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``, + ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``, + ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``, + ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``, + ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and + ``V4L2_CID_FOCUS_AUTO``. + +4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which + were superseded by the :ref:`extended controls <extended-controls>` + interface in Linux 2.6.18, where finally removed from the + ``videodev2.h`` header file. + + +V4L2 in Linux 2.6.26 +==================== + +1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16`` + were added. + +2. Added user controls ``V4L2_CID_CHROMA_AGC`` and + ``V4L2_CID_COLOR_KILLER``. + + +V4L2 in Linux 2.6.27 +==================== + +1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl + and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added. + +2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``, + ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``, + ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``, + ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added. + + +V4L2 in Linux 2.6.28 +==================== + +1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and + ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings. + +2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding. + +3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and + ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added. + + +V4L2 in Linux 2.6.29 +==================== + +1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to + ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was + introduced in its place. The old struct + :c:type:`struct v4l2_chip_ident` was renamed to + :c:type:`struct v4l2_chip_ident_old`. + +2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and + ``V4L2_PIX_FMT_NV61`` were added. + +3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``, + ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and + ``V4L2_CID_PRIVACY``. + + +V4L2 in Linux 2.6.30 +==================== + +1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added. + +2. New control ``V4L2_CID_COLORFX`` was added. + + +V4L2 in Linux 2.6.32 +==================== + +1. In order to be easier to compare a V4L2 API and a kernel version, now + V4L2 API is numbered using the Linux Kernel version numeration. + +2. Finalized the RDS capture API. See :ref:`rds` for more information. + +3. Added new capabilities for modulators and RDS encoders. + +4. Add description for libv4l API. + +5. Added support for string controls via new type + ``V4L2_CTRL_TYPE_STRING``. + +6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation. + +7. Added FM Modulator (FM TX) Extended Control Class: + ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs. + +8. Added FM Receiver (FM RX) Extended Control Class: + ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs. + +9. Added Remote Controller chapter, describing the default Remote + Controller mapping for media devices. + + +V4L2 in Linux 2.6.33 +==================== + +1. Added support for Digital Video timings in order to support HDTV + receivers and transmitters. + + +V4L2 in Linux 2.6.34 +==================== + +1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE`` + controls to the :ref:`Camera controls class <camera-controls>`. + + +V4L2 in Linux 2.6.37 +==================== + +1. Remove the vtx (videotext/teletext) API. This API was no longer used + and no hardware exists to verify the API. Nor were any userspace + applications found that used it. It was originally scheduled for + removal in 2.6.35. + + +V4L2 in Linux 2.6.39 +==================== + +1. The old VIDIOC_*_OLD symbols and V4L1 support were removed. + +2. Multi-planar API added. Does not affect the compatibility of current + drivers and applications. See :ref:`multi-planar API <planar-apis>` + for details. + + +V4L2 in Linux 3.1 +================= + +1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a + per-driver one. + + Standardize an error code for invalid ioctl. + + Added V4L2_CTRL_TYPE_BITMASK. + + +V4L2 in Linux 3.2 +================= + +1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to + userspace. + +2. Add selection API for extended control over cropping and composing. + Does not affect the compatibility of current drivers and + applications. See :ref:`selection API <selection-api>` for details. + + +V4L2 in Linux 3.3 +================= + +1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the + :ref:`User controls class <control>`. + +2. Added the device_caps field to struct v4l2_capabilities and added + the new V4L2_CAP_DEVICE_CAPS capability. + + +V4L2 in Linux 3.4 +================= + +1. Added :ref:`JPEG compression control class <jpeg-controls>`. + +2. Extended the DV Timings API: + :ref:`VIDIOC_ENUM_DV_TIMINGS`, + :ref:`VIDIOC_QUERY_DV_TIMINGS` and + :ref:`VIDIOC_DV_TIMINGS_CAP`. + + +V4L2 in Linux 3.5 +================= + +1. Added integer menus, the new type will be + V4L2_CTRL_TYPE_INTEGER_MENU. + +2. Added selection API for V4L2 subdev interface: + :ref:`VIDIOC_SUBDEV_G_SELECTION` and + :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`. + +3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``, + ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``, + ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and + ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the + ``V4L2_CID_COLORFX`` control. + +4. Added ``V4L2_CID_COLORFX_CBCR`` control. + +5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``, + ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``, + ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``, + ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``, + ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``, + ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``, + ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``. + + +V4L2 in Linux 3.6 +================= + +1. Replaced ``input`` in :c:type:`struct v4l2_buffer` by + ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``. + +2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE + capabilities. + +3. Added support for frequency band enumerations: + :ref:`VIDIOC_ENUM_FREQ_BANDS`. + + +V4L2 in Linux 3.9 +================= + +1. Added timestamp types to ``flags`` field in + :c:type:`struct v4l2_buffer`. See :ref:`buffer-flags`. + +2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See + :ref:`ctrl-changes-flags`. + + +V4L2 in Linux 3.10 +================== + +1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET, + VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and + VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output + capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. + +2. Added new debugging ioctl + :ref:`VIDIOC_DBG_G_CHIP_INFO`. + + +V4L2 in Linux 3.11 +================== + +1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl. + + +V4L2 in Linux 3.14 +================== + +1. In struct :c:type:`struct v4l2_rect`, the type of ``width`` and + ``height`` fields changed from _s32 to _u32. + + +V4L2 in Linux 3.15 +================== + +1. Added Software Defined Radio (SDR) Interface. + + +V4L2 in Linux 3.16 +================== + +1. Added event V4L2_EVENT_SOURCE_CHANGE. + + +V4L2 in Linux 3.17 +================== + +1. Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added + format flags. + +2. Added compound control types and + :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. + + +V4L2 in Linux 3.18 +================== + +1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera + controls. + + +V4L2 in Linux 3.19 +================== + +1. Rewrote Colorspace chapter, added new enum + :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum + :ref:`v4l2_quantization <v4l2-quantization>` fields to struct + :ref:`v4l2_pix_format <v4l2-pix-format>`, struct + :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and + struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`. + + +V4L2 in Linux 4.4 +================= + +1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of + ``V4L2_TUNER_ADC`` is deprecated now. + +2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control. + +3. Added transmitter support for Software Defined Radio (SDR) Interface. + + +.. _other: + +Relation of V4L2 to other Linux multimedia APIs +=============================================== + + +.. _xvideo: + +X Video Extension +----------------- + +The X Video Extension (abbreviated XVideo or just Xv) is an extension of +the X Window system, implemented for example by the XFree86 project. Its +scope is similar to V4L2, an API to video capture and output devices for +X clients. Xv allows applications to display live video in a window, +send window contents to a TV output, and capture or output still images +in XPixmaps [1]_. With their implementation XFree86 makes the extension +available across many operating systems and architectures. + +Because the driver is embedded into the X server Xv has a number of +advantages over the V4L2 :ref:`video overlay interface <overlay>`. The +driver can easily determine the overlay target, i. e. visible graphics +memory or off-screen buffers for a destructive overlay. It can program +the RAMDAC for a non-destructive overlay, scaling or color-keying, or +the clipping functions of the video capture hardware, always in sync +with drawing operations or windows moving or changing their stacking +order. + +To combine the advantages of Xv and V4L a special Xv driver exists in +XFree86 and XOrg, just programming any overlay capable Video4Linux +device it finds. To enable it ``/etc/X11/XF86Config`` must contain these +lines: + +:: + + Section "Module" + Load "v4l" + EndSection + +As of XFree86 4.2 this driver still supports only V4L ioctls, however it +should work just fine with all V4L2 devices through the V4L2 +backward-compatibility layer. Since V4L2 permits multiple opens it is +possible (if supported by the V4L2 driver) to capture video while an X +client requested video overlay. Restrictions of simultaneous capturing +and overlay are discussed in :ref:`overlay` apply. + +Only marginally related to V4L2, XFree86 extended Xv to support hardware +YUV to RGB conversion and scaling for faster video playback, and added +an interface to MPEG-2 decoding hardware. This API is useful to display +images captured with V4L2 devices. + + +Digital Video +------------- + +V4L2 does not support digital terrestrial, cable or satellite broadcast. +A separate project aiming at digital receivers exists. You can find its +homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux +DVB API has no connection to the V4L2 API except that drivers for hybrid +hardware may support both. + + +Audio Interfaces +---------------- + +[to do - OSS/ALSA] + + +.. _experimental: + +Experimental API Elements +========================= + +The following V4L2 API elements are currently experimental and may +change in the future. + +- :ref:`VIDIOC_DBG_G_REGISTER` and + :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_REGISTER>` ioctls. + +- :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. + + +.. _obsolete: + +Obsolete API Elements +===================== + +The following V4L2 API elements were superseded by new interfaces and +should not be implemented in new drivers. + +- ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended + Controls, :ref:`extended-controls`. + +- VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, + VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use + the DV Timings API (:ref:`dv-timings`). + +- ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use + ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``, + :ref:`VIDIOC_SUBDEV_G_SELECTION`. + +.. [1] + This is not implemented in XFree86. diff --git a/Documentation/media/uapi/v4l/io.rst b/Documentation/media/uapi/v4l/io.rst new file mode 100644 index 000000000000..94b38a10ee65 --- /dev/null +++ b/Documentation/media/uapi/v4l/io.rst @@ -0,0 +1,51 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _io: + +############ +Input/Output +############ +The V4L2 API defines several different methods to read from or write to +a device. All drivers exchanging data with applications must support at +least one of them. + +The classic I/O method using the :ref:`read() <func-read>` and +:ref:`write() <func-write>` function is automatically selected after opening a +V4L2 device. When the driver does not support this method attempts to +read or write will fail at any time. + +Other methods must be negotiated. To select the streaming I/O method +with memory mapped or user buffers applications call the +:ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O +method is not defined yet. + +Video overlay can be considered another I/O method, although the +application does not directly receive the image data. It is selected by +initiating video overlay with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` +ioctl. For more information see :ref:`overlay`. + +Generally exactly one I/O method, including overlay, is associated with +each file descriptor. The only exceptions are applications not +exchanging data with a driver ("panel applications", see :ref:`open`) +and drivers permitting simultaneous video capturing and overlay using +the same file descriptor, for compatibility with V4L and earlier +versions of V4L2. + +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_REQBUFS` would permit this to some +degree, but for simplicity drivers need not support switching the I/O +method (after first switching away from read/write) other than by +closing and reopening the device. + +The following sections describe the various I/O methods in more detail. + + +.. toctree:: + :maxdepth: 1 + + rw + mmap + userp + dmabuf + async + buffer + field-order diff --git a/Documentation/media/uapi/v4l/libv4l-introduction.rst b/Documentation/media/uapi/v4l/libv4l-introduction.rst new file mode 100644 index 000000000000..61d085f9f105 --- /dev/null +++ b/Documentation/media/uapi/v4l/libv4l-introduction.rst @@ -0,0 +1,169 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _libv4l-introduction: + +************ +Introduction +************ + +libv4l is a collection of libraries which adds a thin abstraction layer +on top of video4linux2 devices. The purpose of this (thin) layer is to +make it easy for application writers to support a wide variety of +devices without having to write separate code for different devices in +the same class. + +An example of using libv4l is provided by +:ref:`v4l2grab <v4l2grab-example>`. + +libv4l consists of 3 different libraries: + + +libv4lconvert +============= + +libv4lconvert is a library that converts several different pixelformats +found in V4L2 drivers into a few common RGB and YUY formats. + +It currently accepts the following V4L2 driver formats: +:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`, +:ref:`V4L2_PIX_FMT_HM12 <V4L2-PIX-FMT-HM12>`, +:ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`, +:ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`, +:ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`, +:ref:`V4L2_PIX_FMT_OV511 <V4L2-PIX-FMT-OV511>`, +:ref:`V4L2_PIX_FMT_OV518 <V4L2-PIX-FMT-OV518>`, +:ref:`V4L2_PIX_FMT_PAC207 <V4L2-PIX-FMT-PAC207>`, +:ref:`V4L2_PIX_FMT_PJPG <V4L2-PIX-FMT-PJPG>`, +:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`, +:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`, +:ref:`V4L2_PIX_FMT_SGBRG8 <V4L2-PIX-FMT-SGBRG8>`, +:ref:`V4L2_PIX_FMT_SGRBG8 <V4L2-PIX-FMT-SGRBG8>`, +:ref:`V4L2_PIX_FMT_SN9C10X <V4L2-PIX-FMT-SN9C10X>`, +:ref:`V4L2_PIX_FMT_SN9C20X_I420 <V4L2-PIX-FMT-SN9C20X-I420>`, +:ref:`V4L2_PIX_FMT_SPCA501 <V4L2-PIX-FMT-SPCA501>`, +:ref:`V4L2_PIX_FMT_SPCA505 <V4L2-PIX-FMT-SPCA505>`, +:ref:`V4L2_PIX_FMT_SPCA508 <V4L2-PIX-FMT-SPCA508>`, +:ref:`V4L2_PIX_FMT_SPCA561 <V4L2-PIX-FMT-SPCA561>`, +:ref:`V4L2_PIX_FMT_SQ905C <V4L2-PIX-FMT-SQ905C>`, +:ref:`V4L2_PIX_FMT_SRGGB8 <V4L2-PIX-FMT-SRGGB8>`, +:ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`, +:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, +:ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`, +:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, and +:ref:`V4L2_PIX_FMT_YVYU <V4L2-PIX-FMT-YVYU>`. + +Later on libv4lconvert was expanded to also be able to do various video +processing functions to improve webcam video quality. The video +processing is split in to 2 parts: libv4lconvert/control and +libv4lconvert/processing. + +The control part is used to offer video controls which can be used to +control the video processing functions made available by +libv4lconvert/processing. These controls are stored application wide +(until reboot) by using a persistent shared memory object. + +libv4lconvert/processing offers the actual video processing +functionality. + + +libv4l1 +======= + +This library offers functions that can be used to quickly make v4l1 +applications work with v4l2 devices. These functions work exactly like +the normal open/close/etc, except that libv4l1 does full emulation of +the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will +just pass calls through. + +Since those functions are emulations of the old V4L1 API, it shouldn't +be used for new applications. + + +libv4l2 +======= + +This library should be used for all modern V4L2 applications. + +It provides handles to call V4L2 open/ioctl/close/poll methods. Instead +of just providing the raw output of the device, it enhances the calls in +the sense that it will use libv4lconvert to provide more video formats +and to enhance the image quality. + +In most cases, libv4l2 just passes the calls directly through to the +v4l2 driver, intercepting the calls to +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, +:ref:`VIDIOC_ENUM_FRAMESIZES <VIDIOC_ENUM_FRAMESIZES>` and +:ref:`VIDIOC_ENUM_FRAMEINTERVALS <VIDIOC_ENUM_FRAMEINTERVALS>` in +order to emulate the formats +:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`, +:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`, +:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, and +:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, if they aren't +available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>` +keeps enumerating the hardware supported formats, plus the emulated +formats offered by libv4l at the end. + + +.. _libv4l-ops: + +Libv4l device control functions +------------------------------- + +The common file operation methods are provided by libv4l. + +Those functions operate just like glibc +open/close/dup/ioctl/read/mmap/munmap: + +- :c:type:`int v4l2_open(const char *file, int oflag, ...)` - operates like the + standard :ref:`open() <func-open>` function. + +- :c:type:`int v4l2_close(int fd)` - operates like the standard + :ref:`close() <func-close>` function. + +- :c:type:`int v4l2_dup(int fd)` - operates like the standard dup() function, + duplicating a file handler. + +- :c:type:`int v4l2_ioctl (int fd, unsigned long int request, ...)` - operates + like the standard :ref:`ioctl() <func-ioctl>` function. + +- :c:type:`int v4l2_read (int fd, void* buffer, size_t n)` - operates like the + standard :ref:`read() <func-read>` function. + +- :c:type:`void v4l2_mmap(void *start, size_t length, int prot, int flags, int + fd, int64_t offset);` - operates like the standard + :ref:`mmap() <func-mmap>` function. + +- :c:type:`int v4l2_munmap(void *_start, size_t length);` - operates like the + standard :ref:`munmap() <func-munmap>` function. + +Those functions provide additional control: + +- :c:type:`int v4l2_fd_open(int fd, int v4l2_flags)` - opens an already opened + fd for further use through v4l2lib and possibly modify libv4l2's + default behavior through the v4l2_flags argument. Currently, + v4l2_flags can be ``V4L2_DISABLE_CONVERSION``, to disable format + conversion. + +- :c:type:`int v4l2_set_control(int fd, int cid, int value)` - This function + takes a value of 0 - 65535, and then scales that range to the actual + range of the given v4l control id, and then if the cid exists and is + not locked sets the cid to the scaled value. + +- :c:type:`int v4l2_get_control(int fd, int cid)` - This function returns a + value of 0 - 65535, scaled to from the actual range of the given v4l + control id. when the cid does not exist, could not be accessed for + some reason, or some error occurred 0 is returned. + + +v4l1compat.so wrapper library +============================= + +This library intercepts calls to open/close/ioctl/mmap/mmunmap +operations and redirects them to the libv4l counterparts, by using +LD_PRELOAD=/usr/lib/v4l1compat.so. It also emulates V4L1 calls via V4L2 +API. + +It allows usage of binary legacy applications that still don't use +libv4l. diff --git a/Documentation/media/uapi/v4l/libv4l.rst b/Documentation/media/uapi/v4l/libv4l.rst new file mode 100644 index 000000000000..332c1d42688b --- /dev/null +++ b/Documentation/media/uapi/v4l/libv4l.rst @@ -0,0 +1,13 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _libv4l: + +************************ +Libv4l Userspace Library +************************ + + +.. toctree:: + :maxdepth: 1 + + libv4l-introduction diff --git a/Documentation/media/uapi/v4l/mmap.rst b/Documentation/media/uapi/v4l/mmap.rst new file mode 100644 index 000000000000..2171b18c1aab --- /dev/null +++ b/Documentation/media/uapi/v4l/mmap.rst @@ -0,0 +1,280 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _mmap: + +****************************** +Streaming I/O (Memory Mapping) +****************************** + +Input and output devices support this I/O method when the +``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl is set. There are two +streaming methods, to determine if the memory mapping flavor is +supported applications must call the +:ref:`VIDIOC_REQBUFS` ioctl. + +Streaming is an I/O method where only pointers to buffers are exchanged +between application and driver, the data itself is not copied. Memory +mapping is primarily intended to map buffers in device memory into the +application's address space. Device memory can be for example the video +memory on a graphics card with a video capture add-on. However, being +the most efficient I/O method available for a long time, many other +drivers support streaming as well, allocating buffers in DMA-able main +memory. + +A driver can support many sets of buffers. Each set is identified by a +unique buffer type value. The sets are independent and each set can hold +a different type of data. To access different sets at the same time +different file descriptors must be used. [1]_ + +To allocate device buffers applications call the +:ref:`VIDIOC_REQBUFS` ioctl with the desired number +of buffers and buffer type, for example ``V4L2_BUF_TYPE_VIDEO_CAPTURE``. +This ioctl can also be used to change the number of buffers or to free +the allocated memory, provided none of the buffers are still mapped. + +Before applications can access the buffers they must map them into their +address space with the :ref:`mmap() <func-mmap>` function. The +location of the buffers in device memory can be determined with the +:ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar +API case, the ``m.offset`` and ``length`` returned in a struct +:ref:`v4l2_buffer <v4l2-buffer>` are passed as sixth and second +parameter to the :ref:`mmap() <func-mmap>` function. When using the +multi-planar API, struct :ref:`v4l2_buffer <v4l2-buffer>` contains an +array of struct :ref:`v4l2_plane <v4l2-plane>` structures, each +containing its own ``m.offset`` and ``length``. When using the +multi-planar API, every plane of every buffer has to be mapped +separately, so the number of calls to :ref:`mmap() <func-mmap>` should +be equal to number of buffers times number of planes in each buffer. The +offset and length values must not be modified. Remember, the buffers are +allocated in physical memory, as opposed to virtual memory, which can be +swapped out to disk. Applications should free the buffers as soon as +possible with the :ref:`munmap() <func-munmap>` function. + + +.. code-block:: c + :caption: Example 3.1. Mapping buffers in the single-planar API + + struct v4l2_requestbuffers reqbuf; + struct { + void *start; + size_t length; + } *buffers; + unsigned int i; + + memset(&reqbuf, 0, sizeof(reqbuf)); + reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + reqbuf.memory = V4L2_MEMORY_MMAP; + reqbuf.count = 20; + + if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqbuf)) { + if (errno == EINVAL) + printf("Video capturing or mmap-streaming is not supported\\n"); + else + perror("VIDIOC_REQBUFS"); + + exit(EXIT_FAILURE); + } + + /* We want at least five buffers. */ + + if (reqbuf.count < 5) { + /* You may need to free the buffers here. */ + printf("Not enough buffer memory\\n"); + exit(EXIT_FAILURE); + } + + buffers = calloc(reqbuf.count, sizeof(*buffers)); + assert(buffers != NULL); + + for (i = 0; i < reqbuf.count; i++) { + struct v4l2_buffer buffer; + + memset(&buffer, 0, sizeof(buffer)); + buffer.type = reqbuf.type; + buffer.memory = V4L2_MEMORY_MMAP; + buffer.index = i; + + if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) { + perror("VIDIOC_QUERYBUF"); + exit(EXIT_FAILURE); + } + + buffers[i].length = buffer.length; /* remember for munmap() */ + + buffers[i].start = mmap(NULL, buffer.length, + PROT_READ | PROT_WRITE, /* recommended */ + MAP_SHARED, /* recommended */ + fd, buffer.m.offset); + + if (MAP_FAILED == buffers[i].start) { + /* If you do not exit here you should unmap() and free() + the buffers mapped so far. */ + perror("mmap"); + exit(EXIT_FAILURE); + } + } + + /* Cleanup. */ + + for (i = 0; i < reqbuf.count; i++) + munmap(buffers[i].start, buffers[i].length); + + +.. code-block:: c + :caption: Example 3.2. Mapping buffers in the multi-planar API + + struct v4l2_requestbuffers reqbuf; + /* Our current format uses 3 planes per buffer */ + #define FMT_NUM_PLANES = 3 + + struct { + void *start[FMT_NUM_PLANES]; + size_t length[FMT_NUM_PLANES]; + } *buffers; + unsigned int i, j; + + memset(&reqbuf, 0, sizeof(reqbuf)); + reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; + reqbuf.memory = V4L2_MEMORY_MMAP; + reqbuf.count = 20; + + if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0) { + if (errno == EINVAL) + printf("Video capturing or mmap-streaming is not supported\\n"); + else + perror("VIDIOC_REQBUFS"); + + exit(EXIT_FAILURE); + } + + /* We want at least five buffers. */ + + if (reqbuf.count < 5) { + /* You may need to free the buffers here. */ + printf("Not enough buffer memory\\n"); + exit(EXIT_FAILURE); + } + + buffers = calloc(reqbuf.count, sizeof(*buffers)); + assert(buffers != NULL); + + for (i = 0; i < reqbuf.count; i++) { + struct v4l2_buffer buffer; + struct v4l2_plane planes[FMT_NUM_PLANES]; + + memset(&buffer, 0, sizeof(buffer)); + buffer.type = reqbuf.type; + buffer.memory = V4L2_MEMORY_MMAP; + buffer.index = i; + /* length in struct v4l2_buffer in multi-planar API stores the size + * of planes array. */ + buffer.length = FMT_NUM_PLANES; + buffer.m.planes = planes; + + if (ioctl(fd, VIDIOC_QUERYBUF, &buffer) < 0) { + perror("VIDIOC_QUERYBUF"); + exit(EXIT_FAILURE); + } + + /* Every plane has to be mapped separately */ + for (j = 0; j < FMT_NUM_PLANES; j++) { + buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */ + + buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length, + PROT_READ | PROT_WRITE, /* recommended */ + MAP_SHARED, /* recommended */ + fd, buffer.m.planes[j].m.offset); + + if (MAP_FAILED == buffers[i].start[j]) { + /* If you do not exit here you should unmap() and free() + the buffers and planes mapped so far. */ + perror("mmap"); + exit(EXIT_FAILURE); + } + } + } + + /* Cleanup. */ + + for (i = 0; i < reqbuf.count; i++) + for (j = 0; j < FMT_NUM_PLANES; j++) + munmap(buffers[i].start[j], buffers[i].length[j]); + +Conceptually streaming drivers maintain two buffer queues, an incoming +and an outgoing queue. They separate the synchronous capture or output +operation locked to a video clock from the application which is subject +to random disk or network delays and preemption by other processes, +thereby reducing the probability of data loss. The queues are organized +as FIFOs, buffers will be output in the order enqueued in the incoming +FIFO, and were captured in the order dequeued from the outgoing FIFO. + +The driver may require a minimum number of buffers enqueued at all times +to function, apart of this no limit exists on the number of buffers +applications can enqueue in advance, or dequeue and process. They can +also enqueue in a different order than buffers have been dequeued, and +the driver can *fill* enqueued *empty* buffers in any order. [2]_ The +index number of a buffer (struct :ref:`v4l2_buffer <v4l2-buffer>` +``index``) plays no role here, it only identifies the buffer. + +Initially all mapped buffers are in dequeued state, inaccessible by the +driver. For capturing applications it is customary to first enqueue all +mapped buffers, then to start capturing and enter the read loop. Here +the application waits until a filled buffer can be dequeued, and +re-enqueues the buffer when the data is no longer needed. Output +applications fill and enqueue buffers, when enough buffers are stacked +up the output is started with :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`. +In the write loop, when the application runs out of free buffers, it +must wait until an empty buffer can be dequeued and reused. + +To enqueue and dequeue a buffer applications use the :ref:`VIDIOC_QBUF` +and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer +being mapped, enqueued, full or empty can be determined at any time +using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend +execution of the application until one or more buffers can be dequeued. +By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is +in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the +:ref:`open() <func-open>` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` +returns immediately with an ``EAGAIN`` error code when no buffer is +available. The :ref:`select() <func-select>` or :ref:`poll() +<func-poll>` functions are always available. + +To start and stop capturing or output applications call the +:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF +<VIDIOC_STREAMON>` ioctl. Note :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +removes all buffers from both queues as a side effect. Since there is +no notion of doing anything "now" on a multitasking system, if an +application needs to synchronize with another event it should examine +the struct ::ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured +or outputted buffers. + +Drivers implementing memory mapping I/O must support the +:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QUERYBUF +<VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF +<VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` +and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap() +<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select() +<func-select>` and :ref:`poll() <func-poll>` function. [3]_ + +[capture example] + +.. [1] + One could use one file descriptor and set the buffer type field + accordingly when calling :ref:`VIDIOC_QBUF` etc., + but it makes the :ref:`select() <func-select>` function ambiguous. We also + like the clean approach of one file descriptor per logical stream. + Video overlay for example is also a logical stream, although the CPU + is not needed for continuous operation. + +.. [2] + Random enqueue order permits applications processing images out of + order (such as video codecs) to return buffers earlier, reducing the + probability of data loss. Random fill order allows drivers to reuse + buffers on a LIFO-basis, taking advantage of caches holding + scatter-gather lists and the like. + +.. [3] + At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are + the same, and :ref:`select() <func-select>` is too important to be optional. + The rest should be evident. diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst new file mode 100644 index 000000000000..a3e39df91e9d --- /dev/null +++ b/Documentation/media/uapi/v4l/open.rst @@ -0,0 +1,158 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _open: + +*************************** +Opening and Closing Devices +*************************** + + +Device Naming +============= + +V4L2 drivers are implemented as kernel modules, loaded manually by the +system administrator or automatically when a device is first discovered. +The driver modules plug into the "videodev" kernel module. It provides +helper functions and a common application interface specified in this +document. + +Each driver thus loaded registers one or more device nodes with major +number 81 and a minor number between 0 and 255. Minor numbers are +allocated dynamically unless the kernel is compiled with the kernel +option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers +are allocated in ranges depending on the device node type (video, radio, +etc.). + +Many drivers support "video_nr", "radio_nr" or "vbi_nr" module +options to select specific video/radio/vbi node numbers. This allows the +user to request that the device node is named e.g. /dev/video5 instead +of leaving it to chance. When the driver supports multiple devices of +the same type more than one device node number can be assigned, +separated by commas: + +.. code-block:: none + + # modprobe mydriver video_nr=0,1 radio_nr=0,1 + +In ``/etc/modules.conf`` this may be written as: + +:: + + options mydriver video_nr=0,1 radio_nr=0,1 + +When no device node number is given as module option the driver supplies +a default. + +Normally udev will create the device nodes in /dev automatically for +you. If udev is not installed, then you need to enable the +CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to +correctly relate a minor number to a device node number. I.e., you need +to be certain that minor number 5 maps to device node name video5. With +this kernel option different device types have different minor number +ranges. These ranges are listed in :ref:`devices`. + +The creation of character special files (with mknod) is a privileged +operation and devices cannot be opened by major and minor number. That +means applications cannot *reliable* scan for loaded or installed +drivers. The user must enter a device name, or the application can try +the conventional device names. + + +.. _related: + +Related Devices +=============== + +Devices can support several functions. For example video capturing, VBI +capturing and radio support. + +The V4L2 API creates different nodes for each of these functions. + +The V4L2 API was designed with the idea that one device node could +support all functions. However, in practice this never worked: this +'feature' was never used by applications and many drivers did not +support it and if they did it was certainly never tested. In addition, +switching a device node between different functions only works when +using the streaming I/O API, not with the +:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API. + +Today each device node supports just one function. + +Besides video input or output the hardware may also support audio +sampling or playback. If so, these functions are implemented as ALSA PCM +devices with optional ALSA audio mixer devices. + +One problem with all these devices is that the V4L2 API makes no +provisions to find these related devices. Some really complex devices +use the Media Controller (see :ref:`media_controller`) which can be +used for this purpose. But most drivers do not use it, and while some +code exists that uses sysfs to discover related devices (see +libmedia_dev in the +`v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git +repository), there is no library yet that can provide a single API +towards both Media Controller-based devices and devices that do not use +the Media Controller. If you want to work on this please write to the +linux-media mailing list: +`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. + + +Multiple Opens +============== + +V4L2 devices can be opened more than once. [1]_ When this is supported +by the driver, users can for example start a "panel" application to +change controls like brightness or audio volume, while another +application captures video and audio. In other words, panel applications +are comparable to an ALSA audio mixer application. Just opening a V4L2 +device should not change the state of the device. [2]_ + +Once an application has allocated the memory buffers needed for +streaming data (by calling the :ref:`VIDIOC_REQBUFS` +or :ref:`VIDIOC_CREATE_BUFS` ioctls, or +implicitly by calling the :ref:`read() <func-read>` or +:ref:`write() <func-write>` functions) that application (filehandle) +becomes the owner of the device. It is no longer allowed to make changes +that would affect the buffer sizes (e.g. by calling the +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are +no longer allowed to allocate buffers or start or stop streaming. The +EBUSY error code will be returned instead. + +Merely opening a V4L2 device does not grant exclusive access. [3]_ +Initiating data exchange however assigns the right to read or write the +requested type of data, and to change related properties, to this file +descriptor. Applications can request additional access privileges using +the priority mechanism described in :ref:`app-pri`. + + +Shared Data Streams +=================== + +V4L2 drivers should not support multiple applications reading or writing +the same data stream on a device by copying buffers, time multiplexing +or similar means. This is better handled by a proxy application in user +space. + + +Functions +========= + +To open and close V4L2 devices applications use the +:ref:`open() <func-open>` and :ref:`close() <func-close>` function, +respectively. Devices are programmed using the +:ref:`ioctl() <func-ioctl>` function as explained in the following +sections. + +.. [1] + There are still some old and obscure drivers that have not been + updated to allow for multiple opens. This implies that for such + drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code + when the device is already in use. + +.. [2] + Unfortunately, opening a radio device often switches the state of the + device to radio mode in many drivers. This behavior should be fixed + eventually as it violates the V4L2 specification. + +.. [3] + Drivers could recognize the ``O_EXCL`` open flag. Presently this is + not required, so applications cannot know if it really works. diff --git a/Documentation/media/uapi/v4l/pixfmt-002.rst b/Documentation/media/uapi/v4l/pixfmt-002.rst new file mode 100644 index 000000000000..fae9b2d40a85 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-002.rst @@ -0,0 +1,196 @@ +.. -*- coding: utf-8; mode: rst -*- + +****************************** +Single-planar format structure +****************************** + + +.. _v4l2-pix-format: + +.. flat-table:: struct v4l2_pix_format + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``width`` + + - Image width in pixels. + + - .. row 2 + + - __u32 + + - ``height`` + + - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``, + ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height + refers to the number of lines in the field, otherwise it refers to + the number of lines in the frame (which is twice the field height + for interlaced formats). + + - .. row 3 + + - :cspan:`2` Applications set these fields to request an image + size, drivers return the closest possible values. In case of + planar formats the ``width`` and ``height`` applies to the largest + plane. To avoid ambiguities drivers must return values rounded up + to a multiple of the scale factor of any smaller planes. For + example when the image format is YUV 4:2:0, ``width`` and + ``height`` must be multiples of two. + + - .. row 4 + + - __u32 + + - ``pixelformat`` + + - The pixel format or type of compression, set by the application. + This is a little endian + :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard + RGB formats in :ref:`rgb-formats`, YUV formats in + :ref:`yuv-formats`, and reserved codes in + :ref:`reserved-formats` + + - .. row 5 + + - enum :ref:`v4l2_field <v4l2-field>` + + - ``field`` + + - Video images are typically interlaced. Applications can request to + capture or output only the top or bottom field, or both fields + interlaced or sequentially stored in one buffer or alternating in + separate buffers. Drivers return the actual field order selected. + For more details on fields see :ref:`field-order`. + + - .. row 6 + + - __u32 + + - ``bytesperline`` + + - Distance in bytes between the leftmost pixels in two adjacent + lines. + + - .. row 7 + + - :cspan:`2` + + Both applications and drivers can set this field to request + padding bytes at the end of each line. Drivers however may ignore + the value requested by the application, returning ``width`` times + bytes per pixel or a larger value required by the hardware. That + implies applications can just set this field to zero to get a + reasonable default. + + Video hardware may access padding bytes, therefore they must + reside in accessible memory. Consider cases where padding bytes + after the last line of an image cross a system page boundary. + Input devices may write padding bytes, the value is undefined. + Output devices ignore the contents of padding bytes. + + When the image format is planar the ``bytesperline`` value applies + to the first plane and is divided by the same factor as the + ``width`` field for the other planes. For example the Cb and Cr + planes of a YUV 4:2:0 image have half as many padding bytes + following each line as the Y plane. To avoid ambiguities drivers + must return a ``bytesperline`` value rounded up to a multiple of + the scale factor. + + For compressed formats the ``bytesperline`` value makes no sense. + Applications and drivers must set this to 0 in that case. + + - .. row 8 + + - __u32 + + - ``sizeimage`` + + - Size in bytes of the buffer to hold a complete image, set by the + driver. Usually this is ``bytesperline`` times ``height``. When + the image consists of variable length compressed data this is the + maximum number of bytes required to hold an image. + + - .. row 9 + + - enum :ref:`v4l2_colorspace <v4l2-colorspace>` + + - ``colorspace`` + + - This information supplements the ``pixelformat`` and must be set + by the driver for capture streams and by the application for + output streams, see :ref:`colorspaces`. + + - .. row 10 + + - __u32 + + - ``priv`` + + - This field indicates whether the remaining fields of the + :ref:`struct v4l2_pix_format <v4l2-pix-format>` structure, also called the + extended fields, are valid. When set to + ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields + have been correctly initialized. When set to any other value it + indicates that the extended fields contain undefined values. + + Applications that wish to use the pixel format extended fields + must first ensure that the feature is supported by querying the + device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>` + capability. If the capability isn't set the pixel format extended + fields are not supported and using the extended fields will lead + to undefined results. + + To use the extended fields, applications must set the ``priv`` + field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended + fields and zero the unused bytes of the + :ref:`struct v4l2_format <v4l2-format>` ``raw_data`` field. + + When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC`` + drivers must act as if all the extended fields were set to zero. + On return drivers must set the ``priv`` field to + ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to + applicable values. + + - .. row 11 + + - __u32 + + - ``flags`` + + - Flags set by the application or driver, see :ref:`format-flags`. + + - .. row 12 + + - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` + + - ``ycbcr_enc`` + + - 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`. + + - .. row 13 + + - enum :ref:`v4l2_quantization <v4l2-quantization>` + + - ``quantization`` + + - 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`. + + - .. row 14 + + - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>` + + - ``xfer_func`` + + - 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`. diff --git a/Documentation/media/uapi/v4l/pixfmt-003.rst b/Documentation/media/uapi/v4l/pixfmt-003.rst new file mode 100644 index 000000000000..25c54872fbe1 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-003.rst @@ -0,0 +1,166 @@ +.. -*- coding: utf-8; mode: rst -*- + +****************************** +Multi-planar format structures +****************************** + +The :ref:`struct v4l2_plane_pix_format <v4l2-plane-pix-format>` structures define size +and layout for each of the planes in a multi-planar format. The +:ref:`struct v4l2_pix_format_mplane <v4l2-pix-format-mplane>` structure contains +information common to all planes (such as image width and height) and an +array of :ref:`struct v4l2_plane_pix_format <v4l2-plane-pix-format>` structures, +describing all planes of that format. + + +.. _v4l2-plane-pix-format: + +.. flat-table:: struct v4l2_plane_pix_format + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``sizeimage`` + + - Maximum size in bytes required for image data in this plane. + + - .. row 2 + + - __u32 + + - ``bytesperline`` + + - Distance in bytes between the leftmost pixels in two adjacent + lines. See struct :ref:`v4l2_pix_format <v4l2-pix-format>`. + + - .. row 3 + + - __u16 + + - ``reserved[6]`` + + - Reserved for future extensions. Should be zeroed by drivers and + applications. + + + +.. _v4l2-pix-format-mplane: + +.. flat-table:: struct v4l2_pix_format_mplane + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``width`` + + - Image width in pixels. See struct + :ref:`v4l2_pix_format <v4l2-pix-format>`. + + - .. row 2 + + - __u32 + + - ``height`` + + - Image height in pixels. See struct + :ref:`v4l2_pix_format <v4l2-pix-format>`. + + - .. row 3 + + - __u32 + + - ``pixelformat`` + + - The pixel format. Both single- and multi-planar four character + codes can be used. + + - .. row 4 + + - enum :ref:`v4l2_field <v4l2-field>` + + - ``field`` + + - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`. + + - .. row 5 + + - enum :ref:`v4l2_colorspace <v4l2-colorspace>` + + - ``colorspace`` + + - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`. + + - .. row 6 + + - struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>` + + - ``plane_fmt[VIDEO_MAX_PLANES]`` + + - An array of structures describing format of each plane this pixel + format consists of. The number of valid entries in this array has + to be put in the ``num_planes`` field. + + - .. row 7 + + - __u8 + + - ``num_planes`` + + - Number of planes (i.e. separate memory buffers) for this format + and the number of valid entries in the ``plane_fmt`` array. + + - .. row 8 + + - __u8 + + - ``flags`` + + - Flags set by the application or driver, see :ref:`format-flags`. + + - .. row 9 + + - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` + + - ``ycbcr_enc`` + + - 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`. + + - .. row 10 + + - enum :ref:`v4l2_quantization <v4l2-quantization>` + + - ``quantization`` + + - 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`. + + - .. row 11 + + - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>` + + - ``xfer_func`` + + - 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`. + + - .. row 12 + + - __u8 + + - ``reserved[7]`` + + - Reserved for future extensions. Should be zeroed by drivers and + applications. diff --git a/Documentation/media/uapi/v4l/pixfmt-004.rst b/Documentation/media/uapi/v4l/pixfmt-004.rst new file mode 100644 index 000000000000..4bc116aa8193 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-004.rst @@ -0,0 +1,51 @@ +.. -*- coding: utf-8; mode: rst -*- + +********************** +Standard Image Formats +********************** + +In order to exchange images between drivers and applications, it is +necessary to have standard image data formats which both sides will +interpret the same way. V4L2 includes several such formats, and this +section is intended to be an unambiguous specification of the standard +image data formats in V4L2. + +V4L2 drivers are not limited to these formats, however. Driver-specific +formats are possible. In that case the application may depend on a codec +to convert images to one of the standard formats when needed. But the +data can still be stored and retrieved in the proprietary format. For +example, a device may support a proprietary compressed format. +Applications can still capture and save the data in the compressed +format, saving much disk space, and later use a codec to convert the +images to the X Windows screen format when the video is to be displayed. + +Even so, ultimately, some standard formats are needed, so the V4L2 +specification would not be complete without well-defined standard +formats. + +The V4L2 standard formats are mainly uncompressed formats. The pixels +are always arranged in memory from left to right, and from top to +bottom. The first byte of data in the image buffer is always for the +leftmost pixel of the topmost row. Following that is the pixel +immediately to its right, and so on until the end of the top row of +pixels. Following the rightmost pixel of the row there may be zero or +more bytes of padding to guarantee that each row of pixel data has a +certain alignment. Following the pad bytes, if any, is data for the +leftmost pixel of the second row from the top, and so on. The last row +has just as many pad bytes after it as the other rows. + +In V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``, +defined in the :ref:`videodev2.h <videodev>` header file. These +identifiers represent +:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also +listed below, however they are not the same as those used in the Windows +world. + +For some formats, data is stored in separate, discontiguous memory +buffers. Those formats are identified by a separate set of FourCC codes +and are referred to as "multi-planar formats". For example, a +:ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one +memory buffer, but it can also be placed in two or three separate +buffers, with Y component in one buffer and CbCr components in another +in the 2-planar version or with each component in its own buffer in the +3-planar case. Those sub-buffers are referred to as "*planes*". diff --git a/Documentation/media/uapi/v4l/pixfmt-006.rst b/Documentation/media/uapi/v4l/pixfmt-006.rst new file mode 100644 index 000000000000..b9e7c6844020 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-006.rst @@ -0,0 +1,280 @@ +.. -*- coding: utf-8; mode: rst -*- + +**************************** +Defining Colorspaces in V4L2 +**************************** + +In V4L2 colorspaces are defined by four values. The first is the +colorspace identifier (enum :ref:`v4l2_colorspace <v4l2-colorspace>`) +which defines the chromaticities, the default transfer function, the +default Y'CbCr encoding and the default quantization method. The second +is the transfer function identifier (enum +:ref:`v4l2_xfer_func <v4l2-xfer-func>`) to specify non-standard +transfer functions. The third is the Y'CbCr encoding identifier (enum +:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`) to specify +non-standard Y'CbCr encodings and the fourth is the quantization +identifier (enum :ref:`v4l2_quantization <v4l2-quantization>`) to +specify non-standard quantization methods. Most of the time only the +colorspace field of struct :ref:`v4l2_pix_format <v4l2-pix-format>` +or struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` +needs to be filled in. Note that the default R'G'B' quantization is full +range for all colorspaces except for BT.2020 which uses limited range +R'G'B' quantization. + + +.. _v4l2-colorspace: + +.. flat-table:: V4L2 Colorspaces + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Details + + - .. row 2 + + - ``V4L2_COLORSPACE_DEFAULT`` + + - The default colorspace. This can be used by applications to let + the driver fill in the colorspace. + + - .. row 3 + + - ``V4L2_COLORSPACE_SMPTE170M`` + + - See :ref:`col-smpte-170m`. + + - .. row 4 + + - ``V4L2_COLORSPACE_REC709`` + + - See :ref:`col-rec709`. + + - .. row 5 + + - ``V4L2_COLORSPACE_SRGB`` + + - See :ref:`col-srgb`. + + - .. row 6 + + - ``V4L2_COLORSPACE_ADOBERGB`` + + - See :ref:`col-adobergb`. + + - .. row 7 + + - ``V4L2_COLORSPACE_BT2020`` + + - See :ref:`col-bt2020`. + + - .. row 8 + + - ``V4L2_COLORSPACE_DCI_P3`` + + - See :ref:`col-dcip3`. + + - .. row 9 + + - ``V4L2_COLORSPACE_SMPTE240M`` + + - See :ref:`col-smpte-240m`. + + - .. row 10 + + - ``V4L2_COLORSPACE_470_SYSTEM_M`` + + - See :ref:`col-sysm`. + + - .. row 11 + + - ``V4L2_COLORSPACE_470_SYSTEM_BG`` + + - See :ref:`col-sysbg`. + + - .. row 12 + + - ``V4L2_COLORSPACE_JPEG`` + + - See :ref:`col-jpeg`. + + - .. row 13 + + - ``V4L2_COLORSPACE_RAW`` + + - The raw colorspace. This is used for raw image capture where the + image is minimally processed and is using the internal colorspace + of the device. The software that processes an image using this + 'colorspace' will have to know the internals of the capture + device. + + + +.. _v4l2-xfer-func: + +.. flat-table:: V4L2 Transfer Function + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Details + + - .. row 2 + + - ``V4L2_XFER_FUNC_DEFAULT`` + + - Use the default transfer function as defined by the colorspace. + + - .. row 3 + + - ``V4L2_XFER_FUNC_709`` + + - Use the Rec. 709 transfer function. + + - .. row 4 + + - ``V4L2_XFER_FUNC_SRGB`` + + - Use the sRGB transfer function. + + - .. row 5 + + - ``V4L2_XFER_FUNC_ADOBERGB`` + + - Use the AdobeRGB transfer function. + + - .. row 6 + + - ``V4L2_XFER_FUNC_SMPTE240M`` + + - Use the SMPTE 240M transfer function. + + - .. row 7 + + - ``V4L2_XFER_FUNC_NONE`` + + - Do not use a transfer function (i.e. use linear RGB values). + + - .. row 8 + + - ``V4L2_XFER_FUNC_DCI_P3`` + + - Use the DCI-P3 transfer function. + + - .. row 9 + + - ``V4L2_XFER_FUNC_SMPTE2084`` + + - Use the SMPTE 2084 transfer function. + + + +.. _v4l2-ycbcr-encoding: + +.. flat-table:: V4L2 Y'CbCr Encodings + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Details + + - .. row 2 + + - ``V4L2_YCBCR_ENC_DEFAULT`` + + - Use the default Y'CbCr encoding as defined by the colorspace. + + - .. row 3 + + - ``V4L2_YCBCR_ENC_601`` + + - Use the BT.601 Y'CbCr encoding. + + - .. row 4 + + - ``V4L2_YCBCR_ENC_709`` + + - Use the Rec. 709 Y'CbCr encoding. + + - .. row 5 + + - ``V4L2_YCBCR_ENC_XV601`` + + - Use the extended gamut xvYCC BT.601 encoding. + + - .. row 6 + + - ``V4L2_YCBCR_ENC_XV709`` + + - Use the extended gamut xvYCC Rec. 709 encoding. + + - .. row 7 + + - ``V4L2_YCBCR_ENC_SYCC`` + + - Use the extended gamut sYCC encoding. + + - .. row 8 + + - ``V4L2_YCBCR_ENC_BT2020`` + + - Use the default non-constant luminance BT.2020 Y'CbCr encoding. + + - .. row 9 + + - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM`` + + - Use the constant luminance BT.2020 Yc'CbcCrc encoding. + + + +.. _v4l2-quantization: + +.. flat-table:: V4L2 Quantization Methods + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Details + + - .. row 2 + + - ``V4L2_QUANTIZATION_DEFAULT`` + + - Use the default quantization encoding as defined by the + colorspace. This is always full range for R'G'B' (except for the + BT.2020 colorspace) and usually limited range for Y'CbCr. + + - .. row 3 + + - ``V4L2_QUANTIZATION_FULL_RANGE`` + + - Use the full range quantization encoding. I.e. the range [0…1] is + mapped to [0…255] (with possible clipping to [1…254] to avoid the + 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to + [0…255] (with possible clipping to [1…254] to avoid the 0x00 and + 0xff values). + + - .. row 4 + + - ``V4L2_QUANTIZATION_LIM_RANGE`` + + - Use the limited range quantization encoding. I.e. the range [0…1] + is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to + [16…240]. diff --git a/Documentation/media/uapi/v4l/pixfmt-007.rst b/Documentation/media/uapi/v4l/pixfmt-007.rst new file mode 100644 index 000000000000..5e39cda6147a --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-007.rst @@ -0,0 +1,894 @@ +.. -*- coding: utf-8; mode: rst -*- + +******************************** +Detailed Colorspace Descriptions +******************************** + + +.. _col-smpte-170m: + +Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M) +================================================= + +The :ref:`smpte170m` standard defines the colorspace used by NTSC and +PAL and by SDTV in general. The default transfer function is +``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited +range. The chromaticities of the primary colors and the white reference +are: + + + +.. flat-table:: SMPTE 170M Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.630 + + - 0.340 + + - .. row 3 + + - Green + + - 0.310 + + - 0.595 + + - .. row 4 + + - Blue + + - 0.155 + + - 0.070 + + - .. row 5 + + - White Reference (D65) + + - 0.3127 + + - 0.3290 + + +The red, green and blue chromaticities are also often referred to as the +SMPTE C set, so this colorspace is sometimes called SMPTE C as well. + +The transfer function defined for SMPTE 170M is the same as the one +defined in Rec. 709. + + L' = -1.099(-L) :sup:`0.45` + 0.099 for L ≤ -0.018 + + L' = 4.5L for -0.018 < L < 0.018 + + L' = 1.099L :sup:`0.45` - 0.099 for L ≥ 0.018 + +Inverse Transfer function: + + L = -((L' - 0.099) / -1.099) :sup:`1/0.45` for L' ≤ -0.081 + + L = L' / 4.5 for -0.081 < L' < 0.081 + + L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding: + + Y' = 0.299R' + 0.587G' + 0.114B' + + Cb = -0.169R' - 0.331G' + 0.5B' + + Cr = 0.5R' - 0.419G' - 0.081B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in +the :ref:`itu601` standard and this colorspace is sometimes called +BT.601 as well, even though BT.601 does not mention any color primaries. + +The default quantization is limited range, but full range is possible +although rarely seen. + + +.. _col-rec709: + +Colorspace Rec. 709 (V4L2_COLORSPACE_REC709) +============================================ + +The :ref:`itu709` standard defines the colorspace used by HDTV in +general. The default transfer function is ``V4L2_XFER_FUNC_709``. The +default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr +quantization is limited range. The chromaticities of the primary colors +and the white reference are: + + + +.. flat-table:: Rec. 709 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.640 + + - 0.330 + + - .. row 3 + + - Green + + - 0.300 + + - 0.600 + + - .. row 4 + + - Blue + + - 0.150 + + - 0.060 + + - .. row 5 + + - White Reference (D65) + + - 0.3127 + + - 0.3290 + + +The full name of this standard is Rec. ITU-R BT.709-5. + +Transfer function. Normally L is in the range [0…1], but for the +extended gamut xvYCC encoding values outside that range are allowed. + + L' = -1.099(-L) :sup:`0.45` + 0.099 for L ≤ -0.018 + + L' = 4.5L for -0.018 < L < 0.018 + + L' = 1.099L :sup:`0.45` - 0.099 for L ≥ 0.018 + +Inverse Transfer function: + + L = -((L' - 0.099) / -1.099) :sup:`1/0.45` for L' ≤ -0.081 + + L = L' / 4.5 for -0.081 < L' < 0.081 + + L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_709`` encoding: + + Y' = 0.2126R' + 0.7152G' + 0.0722B' + + Cb = -0.1146R' - 0.3854G' + 0.5B' + + Cr = 0.5R' - 0.4542G' - 0.0458B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. + +The default quantization is limited range, but full range is possible +although rarely seen. + +The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for +this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``, +in which case the BT.601 Y'CbCr encoding is used. + +Two additional extended gamut Y'CbCr encodings are also possible with +this colorspace: + +The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is +similar to the Rec. 709 encoding, but it allows for R', G' and B' values +that are outside the range [0…1]. The resulting Y', Cb and Cr values are +scaled and offset: + + Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256) + + Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B') + + Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B') + +The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is +similar to the BT.601 encoding, but it allows for R', G' and B' values +that are outside the range [0…1]. The resulting Y', Cb and Cr values are +scaled and offset: + + Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256) + + Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B') + + Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B') + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be +used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``. +The xvYCC encodings always use full range quantization. + + +.. _col-srgb: + +Colorspace sRGB (V4L2_COLORSPACE_SRGB) +====================================== + +The :ref:`srgb` standard defines the colorspace used by most webcams +and computer graphics. The default transfer function is +``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_SYCC``. The default Y'CbCr quantization is full range. +The chromaticities of the primary colors and the white reference are: + + + +.. flat-table:: sRGB Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.640 + + - 0.330 + + - .. row 3 + + - Green + + - 0.300 + + - 0.600 + + - .. row 4 + + - Blue + + - 0.150 + + - 0.060 + + - .. row 5 + + - White Reference (D65) + + - 0.3127 + + - 0.3290 + + +These chromaticities are identical to the Rec. 709 colorspace. + +Transfer function. Note that negative values for L are only used by the +Y'CbCr conversion. + + L' = -1.055(-L) :sup:`1/2.4` + 0.055 for L < -0.0031308 + + L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308 + + L' = 1.055L :sup:`1/2.4` - 0.055 for 0.0031308 < L ≤ 1 + +Inverse Transfer function: + + L = -((-L' + 0.055) / 1.055) :sup:`2.4` for L' < -0.04045 + + L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045 + + L = ((L' + 0.055) / 1.055) :sup:`2.4` for L' > 0.04045 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_SYCC`` encoding as defined by +:ref:`sycc`: + + Y' = 0.2990R' + 0.5870G' + 0.1140B' + + Cb = -0.1687R' - 0.3313G' + 0.5B' + + Cr = 0.5R' - 0.4187G' - 0.0813B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. The ``V4L2_YCBCR_ENC_SYCC`` quantization is always full +range. Although this Y'CbCr encoding looks very similar to the +``V4L2_YCBCR_ENC_XV601`` encoding, it is not. The +``V4L2_YCBCR_ENC_XV601`` scales and offsets the Y'CbCr values before +quantization, but this encoding does not do that. + + +.. _col-adobergb: + +Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB) +=============================================== + +The :ref:`adobergb` standard defines the colorspace used by computer +graphics that use the AdobeRGB colorspace. This is also known as the +:ref:`oprgb` standard. The default transfer function is +``V4L2_XFER_FUNC_ADOBERGB``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited +range. The chromaticities of the primary colors and the white reference +are: + + + +.. flat-table:: Adobe RGB Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.6400 + + - 0.3300 + + - .. row 3 + + - Green + + - 0.2100 + + - 0.7100 + + - .. row 4 + + - Blue + + - 0.1500 + + - 0.0600 + + - .. row 5 + + - White Reference (D65) + + - 0.3127 + + - 0.3290 + + + +Transfer function: + + L' = L :sup:`1/2.19921875` + +Inverse Transfer function: + + L = L' :sup:`2.19921875` + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding: + + Y' = 0.299R' + 0.587G' + 0.114B' + + Cb = -0.169R' - 0.331G' + 0.5B' + + Cr = 0.5R' - 0.419G' - 0.081B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. This transform is identical to one defined in SMPTE +170M/BT.601. The Y'CbCr quantization is limited range. + + +.. _col-bt2020: + +Colorspace BT.2020 (V4L2_COLORSPACE_BT2020) +=========================================== + +The :ref:`itu2020` standard defines the colorspace used by Ultra-high +definition television (UHDTV). The default transfer function is +``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited +range (!), and so is the default Y'CbCr quantization. The chromaticities +of the primary colors and the white reference are: + + + +.. flat-table:: BT.2020 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.708 + + - 0.292 + + - .. row 3 + + - Green + + - 0.170 + + - 0.797 + + - .. row 4 + + - Blue + + - 0.131 + + - 0.046 + + - .. row 5 + + - White Reference (D65) + + - 0.3127 + + - 0.3290 + + + +Transfer function (same as Rec. 709): + + L' = 4.5L for 0 ≤ L < 0.018 + + L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1 + +Inverse Transfer function: + + L = L' / 4.5 for L' < 0.081 + + L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_BT2020`` encoding: + + Y' = 0.2627R' + 0.6780G' + 0.0593B' + + Cb = -0.1396R' - 0.3604G' + 0.5B' + + Cr = 0.5R' - 0.4598G' - 0.0402B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. The Y'CbCr quantization is limited range. + +There is also an alternate constant luminance R'G'B' to Yc'CbcCrc +(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding: + +Luma: + + Yc' = (0.2627R + 0.6780G + 0.0593B)' + +B' - Yc' ≤ 0: + + Cbc = (B' - Yc') / 1.9404 + +B' - Yc' > 0: + + Cbc = (B' - Yc') / 1.5816 + +R' - Yc' ≤ 0: + + Crc = (R' - Y') / 1.7184 + +R' - Yc' > 0: + + Crc = (R' - Y') / 0.9936 + +Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the +range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range. + + +.. _col-dcip3: + +Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3) +========================================== + +The :ref:`smpte431` standard defines the colorspace used by cinema +projectors that use the DCI-P3 colorspace. The default transfer function +is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_709``. Note that this colorspace does not specify a +Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this +default Y'CbCr encoding was picked because it is the HDTV encoding. The +default Y'CbCr quantization is limited range. The chromaticities of the +primary colors and the white reference are: + + + +.. flat-table:: DCI-P3 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.6800 + + - 0.3200 + + - .. row 3 + + - Green + + - 0.2650 + + - 0.6900 + + - .. row 4 + + - Blue + + - 0.1500 + + - 0.0600 + + - .. row 5 + + - White Reference + + - 0.3140 + + - 0.3510 + + + +Transfer function: + + L' = L :sup:`1/2.6` + +Inverse Transfer function: + + L = L' :sup:`2.6` + +Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709. + + +.. _col-smpte-240m: + +Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M) +================================================= + +The :ref:`smpte240m` standard was an interim standard used during the +early days of HDTV (1988-1998). It has been superseded by Rec. 709. The +default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default +Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr +quantization is limited range. The chromaticities of the primary colors +and the white reference are: + + + +.. flat-table:: SMPTE 240M Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.630 + + - 0.340 + + - .. row 3 + + - Green + + - 0.310 + + - 0.595 + + - .. row 4 + + - Blue + + - 0.155 + + - 0.070 + + - .. row 5 + + - White Reference (D65) + + - 0.3127 + + - 0.3290 + + +These chromaticities are identical to the SMPTE 170M colorspace. + +Transfer function: + + L' = 4L for 0 ≤ L < 0.0228 + + L' = 1.1115L :sup:`0.45` - 0.1115 for 0.0228 ≤ L ≤ 1 + +Inverse Transfer function: + + L = L' / 4 for 0 ≤ L' < 0.0913 + + L = ((L' + 0.1115) / 1.1115) :sup:`1/0.45` for L' ≥ 0.0913 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding: + + Y' = 0.2122R' + 0.7013G' + 0.0865B' + + Cb = -0.1161R' - 0.3839G' + 0.5B' + + Cr = 0.5R' - 0.4451G' - 0.0549B' + +Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the +range [-0.5…0.5]. The Y'CbCr quantization is limited range. + + +.. _col-sysm: + +Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M) +=================================================== + +This standard defines the colorspace used by NTSC in 1953. In practice +this colorspace is obsolete and SMPTE 170M should be used instead. The +default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr +encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is +limited range. The chromaticities of the primary colors and the white +reference are: + + + +.. flat-table:: NTSC 1953 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.67 + + - 0.33 + + - .. row 3 + + - Green + + - 0.21 + + - 0.71 + + - .. row 4 + + - Blue + + - 0.14 + + - 0.08 + + - .. row 5 + + - White Reference (C) + + - 0.310 + + - 0.316 + + +Note that this colorspace uses Illuminant C instead of D65 as the white +reference. To correctly convert an image in this colorspace to another +that uses D65 you need to apply a chromatic adaptation algorithm such as +the Bradford method. + +The transfer function was never properly defined for NTSC 1953. The Rec. +709 transfer function is recommended in the literature: + + L' = 4.5L for 0 ≤ L < 0.018 + + L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1 + +Inverse Transfer function: + + L = L' / 4.5 for L' < 0.081 + + L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding: + + Y' = 0.299R' + 0.587G' + 0.114B' + + Cb = -0.169R' - 0.331G' + 0.5B' + + Cr = 0.5R' - 0.419G' - 0.081B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is +identical to one defined in SMPTE 170M/BT.601. + + +.. _col-sysbg: + +Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG) +========================================================= + +The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM +in 1975. In practice this colorspace is obsolete and SMPTE 170M should +be used instead. The default transfer function is +``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited +range. The chromaticities of the primary colors and the white reference +are: + + + +.. flat-table:: EBU Tech. 3213 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Color + + - x + + - y + + - .. row 2 + + - Red + + - 0.64 + + - 0.33 + + - .. row 3 + + - Green + + - 0.29 + + - 0.60 + + - .. row 4 + + - Blue + + - 0.15 + + - 0.06 + + - .. row 5 + + - White Reference (D65) + + - 0.3127 + + - 0.3290 + + + +The transfer function was never properly defined for this colorspace. +The Rec. 709 transfer function is recommended in the literature: + + L' = 4.5L for 0 ≤ L < 0.018 + + L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1 + +Inverse Transfer function: + + L = L' / 4.5 for L' < 0.081 + + L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding: + + Y' = 0.299R' + 0.587G' + 0.114B' + + Cb = -0.169R' - 0.331G' + 0.5B' + + Cr = 0.5R' - 0.419G' - 0.081B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is +identical to one defined in SMPTE 170M/BT.601. + + +.. _col-jpeg: + +Colorspace JPEG (V4L2_COLORSPACE_JPEG) +====================================== + +This colorspace defines the colorspace used by most (Motion-)JPEG +formats. The chromaticities of the primary colors and the white +reference are identical to sRGB. The transfer function use is +``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601`` +with full range quantization where Y' is scaled to [0…255] and Cb/Cr are +scaled to [-128…128] and then clipped to [-128…127]. + +Note that the JPEG standard does not actually store colorspace +information. So if something other than sRGB is used, then the driver +will have to set that information explicitly. Effectively +``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for +``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and +``V4L2_QUANTIZATION_FULL_RANGE``. diff --git a/Documentation/media/uapi/v4l/pixfmt-008.rst b/Documentation/media/uapi/v4l/pixfmt-008.rst new file mode 100644 index 000000000000..4bec79784bdd --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-008.rst @@ -0,0 +1,32 @@ +.. -*- coding: utf-8; mode: rst -*- + +*************************************** +Detailed Transfer Function Descriptions +*************************************** + + +.. _xf-smpte-2084: + +Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084) +======================================================= + +The :ref:`smpte2084` standard defines the transfer function used by +High Dynamic Range content. + +Constants: + m1 = (2610 / 4096) / 4 + + m2 = (2523 / 4096) * 128 + + c1 = 3424 / 4096 + + c2 = (2413 / 4096) * 32 + + c3 = (2392 / 4096) * 32 + +Transfer function: + L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2` + +Inverse Transfer function: + L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 * + L'\ :sup:`1/m2`))\ :sup:`1/m1` diff --git a/Documentation/media/uapi/v4l/pixfmt-013.rst b/Documentation/media/uapi/v4l/pixfmt-013.rst new file mode 100644 index 000000000000..475f6e6fe785 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-013.rst @@ -0,0 +1,129 @@ +.. -*- coding: utf-8; mode: rst -*- + +****************** +Compressed Formats +****************** + + +.. _compressed-formats: + +.. flat-table:: Compressed Image Formats + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - Identifier + + - Code + + - Details + + - .. _V4L2-PIX-FMT-JPEG: + + - ``V4L2_PIX_FMT_JPEG`` + + - 'JPEG' + + - TBD. See also :ref:`VIDIOC_G_JPEGCOMP <VIDIOC_G_JPEGCOMP>`, + :ref:`VIDIOC_S_JPEGCOMP <VIDIOC_G_JPEGCOMP>`. + + - .. _V4L2-PIX-FMT-MPEG: + + - ``V4L2_PIX_FMT_MPEG`` + + - 'MPEG' + + - MPEG multiplexed stream. The actual format is determined by + extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see + :ref:`mpeg-control-id`. + + - .. _V4L2-PIX-FMT-H264: + + - ``V4L2_PIX_FMT_H264`` + + - 'H264' + + - H264 video elementary stream with start codes. + + - .. _V4L2-PIX-FMT-H264-NO-SC: + + - ``V4L2_PIX_FMT_H264_NO_SC`` + + - 'AVC1' + + - H264 video elementary stream without start codes. + + - .. _V4L2-PIX-FMT-H264-MVC: + + - ``V4L2_PIX_FMT_H264_MVC`` + + - 'M264' + + - H264 MVC video elementary stream. + + - .. _V4L2-PIX-FMT-H263: + + - ``V4L2_PIX_FMT_H263`` + + - 'H263' + + - H263 video elementary stream. + + - .. _V4L2-PIX-FMT-MPEG1: + + - ``V4L2_PIX_FMT_MPEG1`` + + - 'MPG1' + + - MPEG1 video elementary stream. + + - .. _V4L2-PIX-FMT-MPEG2: + + - ``V4L2_PIX_FMT_MPEG2`` + + - 'MPG2' + + - MPEG2 video elementary stream. + + - .. _V4L2-PIX-FMT-MPEG4: + + - ``V4L2_PIX_FMT_MPEG4`` + + - 'MPG4' + + - MPEG4 video elementary stream. + + - .. _V4L2-PIX-FMT-XVID: + + - ``V4L2_PIX_FMT_XVID`` + + - 'XVID' + + - Xvid video elementary stream. + + - .. _V4L2-PIX-FMT-VC1-ANNEX-G: + + - ``V4L2_PIX_FMT_VC1_ANNEX_G`` + + - 'VC1G' + + - VC1, SMPTE 421M Annex G compliant stream. + + - .. _V4L2-PIX-FMT-VC1-ANNEX-L: + + - ``V4L2_PIX_FMT_VC1_ANNEX_L`` + + - 'VC1L' + + - VC1, SMPTE 421M Annex L compliant stream. + + - .. _V4L2-PIX-FMT-VP8: + + - ``V4L2_PIX_FMT_VP8`` + + - 'VP80' + + - VP8 video elementary stream. diff --git a/Documentation/media/uapi/v4l/pixfmt-grey.rst b/Documentation/media/uapi/v4l/pixfmt-grey.rst new file mode 100644 index 000000000000..761d783d4989 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-grey.rst @@ -0,0 +1,77 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-GREY: + +************************** +V4L2_PIX_FMT_GREY ('GREY') +************************** + +*man V4L2_PIX_FMT_GREY(2)* + +Grey-scale image + + +Description +=========== + +This is a grey-scale image. It is really a degenerate Y'CbCr format +which simply contains no Cb or Cr data. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` diff --git a/Documentation/media/uapi/v4l/pixfmt-indexed.rst b/Documentation/media/uapi/v4l/pixfmt-indexed.rst new file mode 100644 index 000000000000..99a780fe6b61 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-indexed.rst @@ -0,0 +1,73 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _pixfmt-indexed: + +************** +Indexed Format +************** + +In this format each pixel is represented by an 8 bit index into a 256 +entry ARGB palette. It is intended for +:ref:`Video Output Overlays <osd>` only. There are no ioctls to access +the palette, this must be done with ioctls of the Linux framebuffer API. + + + +.. flat-table:: Indexed Image Format + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - :cspan:`7` Byte 0 + + - .. row 2 + + - + - + - Bit + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _V4L2-PIX-FMT-PAL8: + + - ``V4L2_PIX_FMT_PAL8`` + + - 'PAL8' + + - + - i\ :sub:`7` + + - i\ :sub:`6` + + - i\ :sub:`5` + + - i\ :sub:`4` + + - i\ :sub:`3` + + - i\ :sub:`2` + + - i\ :sub:`1` + + - i\ :sub:`0` diff --git a/Documentation/media/uapi/v4l/pixfmt-m420.rst b/Documentation/media/uapi/v4l/pixfmt-m420.rst new file mode 100644 index 000000000000..4c5b2969c039 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-m420.rst @@ -0,0 +1,219 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-M420: + +************************** +V4L2_PIX_FMT_M420 ('M420') +************************** + +*man V4L2_PIX_FMT_M420(2)* + +Format with ½ horizontal and vertical chroma resolution, also known as +YUV 4:2:0. Hybrid plane line-interleaved layout. + + +Description +=========== + +M420 is a YUV format with ½ horizontal and vertical chroma subsampling +(YUV 4:2:0). Pixels are organized as interleaved luma and chroma planes. +Two lines of luma data are followed by one line of chroma data. + +The luma plane has one byte per pixel. The chroma plane contains +interleaved CbCr pixels subsampled by ½ in the horizontal and vertical +directions. Each CbCr pair belongs to four pixels. For example, +Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, +Y'\ :sub:`10`, Y'\ :sub:`11`. + +All line lengths are identical: if the Y lines include pad bytes so do +the CbCr lines. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Cb\ :sub:`00` + + - Cr\ :sub:`00` + + - Cb\ :sub:`01` + + - Cr\ :sub:`01` + + - .. row 4 + + - start + 16: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 5 + + - start + 20: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 6 + + - start + 24: + + - Cb\ :sub:`10` + + - Cr\ :sub:`10` + + - Cb\ :sub:`11` + + - Cr\ :sub:`11` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 3 + + - + - + - C + + - + - + - C + + - + + - .. row 4 + + - 1 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 5 + + - + + - .. row 6 + + - 2 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 7 + + - + - + - C + + - + - + - C + + - + + - .. row 8 + + - 3 + + - Y + + - + - Y + + - Y + + - + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12.rst b/Documentation/media/uapi/v4l/pixfmt-nv12.rst new file mode 100644 index 000000000000..cf59b28f75b7 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-nv12.rst @@ -0,0 +1,221 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-NV12: +.. _V4L2-PIX-FMT-NV21: + +****************************************************** +V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21') +****************************************************** + +*man V4L2_PIX_FMT_NV12(2)* + +V4L2_PIX_FMT_NV21 +Formats with ½ horizontal and vertical chroma resolution, also known as +YUV 4:2:0. One luminance and one chrominance plane with alternating +chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` + + +Description +=========== + +These are two-plane versions of the YUV 4:2:0 format. The three +components are separated into two sub-images or planes. The Y plane is +first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a +combined CbCr plane immediately follows the Y plane in memory. The CbCr +plane is the same width, in bytes, as the Y plane (and of the image), +but is half as tall in pixels. Each CbCr pair belongs to four pixels. +For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, +Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is +the same except the Cb and Cr bytes are swapped, the CrCb plane starts +with a Cr byte. + +If the Y plane has pad bytes after each row, then the CbCr plane has as +many pad bytes after its rows. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - start + 16: + + - Cb\ :sub:`00` + + - Cr\ :sub:`00` + + - Cb\ :sub:`01` + + - Cr\ :sub:`01` + + - .. row 6 + + - start + 20: + + - Cb\ :sub:`10` + + - Cr\ :sub:`10` + + - Cb\ :sub:`11` + + - Cr\ :sub:`11` + + +**Color Sample Location..** + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 3 + + - + - + - C + + - + - + - C + + - + + - .. row 4 + + - 1 + + - Y + - + + - Y + + - Y + + - + - Y + + - .. row 5 + + - + + - .. row 6 + + - 2 + + - Y + - + + - Y + + - Y + + - + - Y + + - .. row 7 + + - + - + - C + + - + - + - C + + - + + - .. row 8 + + - 3 + + - Y + + - + - Y + + - Y + + - + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12m.rst b/Documentation/media/uapi/v4l/pixfmt-nv12m.rst new file mode 100644 index 000000000000..a4e7eaeccea8 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-nv12m.rst @@ -0,0 +1,238 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-NV12M: +.. _v4l2-pix-fmt-nv12mt-16x16: +.. _V4L2-PIX-FMT-NV21M: + +*********************************************************************************** +V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16 +*********************************************************************************** + +*man V4L2_PIX_FMT_NV12M(2)* + +V4L2_PIX_FMT_NV21M +V4L2_PIX_FMT_NV12MT_16X16 +Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes +non contiguous in memory. + + +Description +=========== + +This is a multi-planar, two-plane version of the YUV 4:2:0 format. The +three components are separated into two sub-images or planes. +``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the +two planes are non-contiguous in memory, i.e. the chroma plane do not +necessarily immediately follows the luma plane. The luminance data +occupies the first plane. The Y plane has one byte per pixel. In the +second plane there is a chrominance data with alternating chroma +samples. The CbCr plane is the same width, in bytes, as the Y plane (and +of the image), but is half as tall in pixels. Each CbCr pair belongs to +four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to +Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. +``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of +``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are +arranged in 16x16 2D tiles and tiles are arranged in linear order in +memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M`` +except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr +byte. + +``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and +applications that support the multi-planar API, described in +:ref:`planar-apis`. + +If the Y plane has pad bytes after each row, then the CbCr plane has as +many pad bytes after its rows. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start0 + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start0 + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start0 + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start0 + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - + + - .. row 6 + + - start1 + 0: + + - Cb\ :sub:`00` + + - Cr\ :sub:`00` + + - Cb\ :sub:`01` + + - Cr\ :sub:`01` + + - .. row 7 + + - start1 + 4: + + - Cb\ :sub:`10` + + - Cr\ :sub:`10` + + - Cb\ :sub:`11` + + - Cr\ :sub:`11` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 3 + + - + - + - C + + - + - + - C + + - + + - .. row 4 + + - 1 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 5 + + - + + - .. row 6 + + - 2 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 7 + + - + - + - C + + - + - + - + - C + + - + + - .. row 8 + + - 3 + + - Y + + - + - Y + + - Y + + - + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst new file mode 100644 index 000000000000..6198941bb814 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-NV12MT: + +**************************** +V4L2_PIX_FMT_NV12MT ('TM12') +**************************** + +*man V4L2_PIX_FMT_NV12MT(2)* + +Formats with ½ horizontal and vertical chroma resolution. This format +has two planes - one for luminance and one for chrominance. Chroma +samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the +memory layout. Pixels are grouped in macroblocks of 64x32 size. The +order of macroblocks in memory is also not standard. + + +Description +=========== + +This is the two-plane versions of the YUV 4:2:0 format where data is +grouped into 64x32 macroblocks. The three components are separated into +two sub-images or planes. The Y plane has one byte per pixel and pixels +are grouped into 64x32 macroblocks. The CbCr plane has the same width, +in bytes, as the Y plane (and the image), but is half as tall in pixels. +The chroma plane is also grouped into 64x32 macroblocks. + +Width of the buffer has to be aligned to the multiple of 128, and height +alignment is 32. Every four adjacent buffers - two horizontally and two +vertically are grouped together and are located in memory in Z or +flipped Z order. + +Layout of macroblocks in memory is presented in the following figure. + + +.. _nv12mt: + +.. figure:: pixfmt-nv12mt_files/nv12mt.* + :alt: nv12mt.gif + :align: center + + V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout + +The requirement that width is multiple of 128 is implemented because, +the Z shape cannot be cut in half horizontally. In case the vertical +resolution of macroblocks is odd then the last row of macroblocks is +arranged in a linear order. + +In case of chroma the layout is identical. Cb and Cr samples are +interleaved. Height of the buffer is aligned to 32. + + +.. _nv12mt_ex: + +.. figure:: pixfmt-nv12mt_files/nv12mt_example.* + :alt: nv12mt_example.gif + :align: center + + Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks + +Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most +extreme case. diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif Binary files differnew file mode 100644 index 000000000000..ef2d4cf8367b --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif Binary files differnew file mode 100644 index 000000000000..df81d68108ee --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif diff --git a/Documentation/media/uapi/v4l/pixfmt-nv16.rst b/Documentation/media/uapi/v4l/pixfmt-nv16.rst new file mode 100644 index 000000000000..88aa7617f7cf --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-nv16.rst @@ -0,0 +1,270 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-NV16: +.. _V4L2-PIX-FMT-NV61: + +****************************************************** +V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61') +****************************************************** + +*man V4L2_PIX_FMT_NV16(2)* + +V4L2_PIX_FMT_NV61 +Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2. +One luminance and one chrominance plane with alternating chroma samples +as opposed to ``V4L2_PIX_FMT_YVU420`` + + +Description +=========== + +These are two-plane versions of the YUV 4:2:2 format. The three +components are separated into two sub-images or planes. The Y plane is +first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a +combined CbCr plane immediately follows the Y plane in memory. The CbCr +plane is the same width and height, in bytes, as the Y plane (and of the +image). Each CbCr pair belongs to two pixels. For example, +Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. +``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are +swapped, the CrCb plane starts with a Cr byte. + +If the Y plane has pad bytes after each row, then the CbCr plane has as +many pad bytes after its rows. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - start + 16: + + - Cb\ :sub:`00` + + - Cr\ :sub:`00` + + - Cb\ :sub:`01` + + - Cr\ :sub:`01` + + - .. row 6 + + - start + 20: + + - Cb\ :sub:`10` + + - Cr\ :sub:`10` + + - Cb\ :sub:`11` + + - Cr\ :sub:`11` + + - .. row 7 + + - start + 24: + + - Cb\ :sub:`20` + + - Cr\ :sub:`20` + + - Cb\ :sub:`21` + + - Cr\ :sub:`21` + + - .. row 8 + + - start + 28: + + - Cb\ :sub:`30` + + - Cr\ :sub:`30` + + - Cb\ :sub:`31` + + - Cr\ :sub:`31` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 3 + + - + - + - C + + - + - + - C + + - + + - .. row 4 + + - 1 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 5 + + - + - + - C + + - + - + - C + + - + + - .. row 6 + + - + + - .. row 7 + + - 2 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 8 + + - + - + - C + + - + - + - C + + - + + - .. row 9 + + - 3 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 10 + + - + - + - C + + - + - + - C + + - diff --git a/Documentation/media/uapi/v4l/pixfmt-nv16m.rst b/Documentation/media/uapi/v4l/pixfmt-nv16m.rst new file mode 100644 index 000000000000..b7ee068f491c --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-nv16m.rst @@ -0,0 +1,277 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-NV16M: +.. _v4l2-pix-fmt-nv61m: + +******************************************************** +V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61') +******************************************************** + +*man V4L2_PIX_FMT_NV16M(2)* + +V4L2_PIX_FMT_NV61M +Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes +non contiguous in memory. + + +Description +=========== + +This is a multi-planar, two-plane version of the YUV 4:2:2 format. The +three components are separated into two sub-images or planes. +``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the +two planes are non-contiguous in memory, i.e. the chroma plane does not +necessarily immediately follow the luma plane. The luminance data +occupies the first plane. The Y plane has one byte per pixel. In the +second plane there is chrominance data with alternating chroma samples. +The CbCr plane is the same width and height, in bytes, as the Y plane. +Each CbCr pair belongs to two pixels. For example, +Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. +``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the +Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte. + +``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be +used only in drivers and applications that support the multi-planar API, +described in :ref:`planar-apis`. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start0 + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start0 + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start0 + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start0 + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - + + - .. row 6 + + - start1 + 0: + + - Cb\ :sub:`00` + + - Cr\ :sub:`00` + + - Cb\ :sub:`02` + + - Cr\ :sub:`02` + + - .. row 7 + + - start1 + 4: + + - Cb\ :sub:`10` + + - Cr\ :sub:`10` + + - Cb\ :sub:`12` + + - Cr\ :sub:`12` + + - .. row 8 + + - start1 + 8: + + - Cb\ :sub:`20` + + - Cr\ :sub:`20` + + - Cb\ :sub:`22` + + - Cr\ :sub:`22` + + - .. row 9 + + - start1 + 12: + + - Cb\ :sub:`30` + + - Cr\ :sub:`30` + + - Cb\ :sub:`32` + + - Cr\ :sub:`32` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 3 + + - + - + - C + + - + - + - C + + - + + - .. row 4 + + - 1 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 5 + + - + - + - C + + - + - + - C + + - + + - .. row 6 + + - + + - .. row 7 + + - 2 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 8 + + - + - + - C + + - + - + - C + + - + + - .. row 9 + + - 3 + + - Y + + - + - Y + + - Y + + - + - Y + + - .. row 10 + + - + - + - C + + - + - + - C + + - diff --git a/Documentation/media/uapi/v4l/pixfmt-nv24.rst b/Documentation/media/uapi/v4l/pixfmt-nv24.rst new file mode 100644 index 000000000000..db98f476446e --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-nv24.rst @@ -0,0 +1,171 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-NV24: +.. _V4L2-PIX-FMT-NV42: + +****************************************************** +V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42') +****************************************************** + +*man V4L2_PIX_FMT_NV24(2)* + +V4L2_PIX_FMT_NV42 +Formats with full horizontal and vertical chroma resolutions, also known +as YUV 4:4:4. One luminance and one chrominance plane with alternating +chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` + + +Description +=========== + +These are two-plane versions of the YUV 4:4:4 format. The three +components are separated into two sub-images or planes. The Y plane is +first, with each Y sample stored in one byte per pixel. For +``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y +plane in memory. The CbCr plane has the same width and height, in +pixels, as the Y plane (and the image). Each line contains one CbCr pair +per pixel, with each Cb and Cr sample stored in one byte. +``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are +swapped, the CrCb plane starts with a Cr sample. + +If the Y plane has pad bytes after each row, then the CbCr plane has +twice as many pad bytes after its rows. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - start + 16: + + - Cb\ :sub:`00` + + - Cr\ :sub:`00` + + - Cb\ :sub:`01` + + - Cr\ :sub:`01` + + - Cb\ :sub:`02` + + - Cr\ :sub:`02` + + - Cb\ :sub:`03` + + - Cr\ :sub:`03` + + - .. row 6 + + - start + 24: + + - Cb\ :sub:`10` + + - Cr\ :sub:`10` + + - Cb\ :sub:`11` + + - Cr\ :sub:`11` + + - Cb\ :sub:`12` + + - Cr\ :sub:`12` + + - Cb\ :sub:`13` + + - Cr\ :sub:`13` + + - .. row 7 + + - start + 32: + + - Cb\ :sub:`20` + + - Cr\ :sub:`20` + + - Cb\ :sub:`21` + + - Cr\ :sub:`21` + + - Cb\ :sub:`22` + + - Cr\ :sub:`22` + + - Cb\ :sub:`23` + + - Cr\ :sub:`23` + + - .. row 8 + + - start + 40: + + - Cb\ :sub:`30` + + - Cr\ :sub:`30` + + - Cb\ :sub:`31` + + - Cr\ :sub:`31` + + - Cb\ :sub:`32` + + - Cr\ :sub:`32` + + - Cb\ :sub:`33` + + - Cr\ :sub:`33` diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst new file mode 100644 index 000000000000..c7aa2e91ac78 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst @@ -0,0 +1,1469 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _packed-rgb: + +****************** +Packed RGB formats +****************** + +*man Packed RGB formats(2)* + +Packed RGB formats + + +Description +=========== + +These formats are designed to match the pixel formats of typical PC +graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel. +These are all packed-pixel formats, meaning all the data for a pixel lie +next to each other in memory. + + +.. _rgb-formats: + +.. flat-table:: Packed RGB Image Formats + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - :cspan:`7` Byte 0 in memory + + - :cspan:`7` Byte 1 + + - :cspan:`7` Byte 2 + + - :cspan:`7` Byte 3 + + - .. row 2 + + - + - + - Bit + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _V4L2-PIX-FMT-RGB332: + + - ``V4L2_PIX_FMT_RGB332`` + + - 'RGB1' + + - + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _V4L2-PIX-FMT-ARGB444: + + - ``V4L2_PIX_FMT_ARGB444`` + + - 'AR12' + + - + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - 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` + + - .. _V4L2-PIX-FMT-XRGB444: + + - ``V4L2_PIX_FMT_XRGB444`` + + - 'XR12' + + - + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - + - - + + - - + + - - + + - - + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - .. _V4L2-PIX-FMT-ARGB555: + + - ``V4L2_PIX_FMT_ARGB555`` + + - 'AR15' + + - + - g\ :sub:`2` + + - 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` + + - .. _V4L2-PIX-FMT-XRGB555: + + - ``V4L2_PIX_FMT_XRGB555`` + + - 'XR15' + + - + - g\ :sub:`2` + + - 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` + + - .. _V4L2-PIX-FMT-RGB565: + + - ``V4L2_PIX_FMT_RGB565`` + + - 'RGBP' + + - + - g\ :sub:`2` + + - 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:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - .. _V4L2-PIX-FMT-ARGB555X: + + - ``V4L2_PIX_FMT_ARGB555X`` + + - 'AR15' | (1 << 31) + + - + - 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` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _V4L2-PIX-FMT-XRGB555X: + + - ``V4L2_PIX_FMT_XRGB555X`` + + - 'XR15' | (1 << 31) + + - + - - + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _V4L2-PIX-FMT-RGB565X: + + - ``V4L2_PIX_FMT_RGB565X`` + + - 'RGBR' + + - + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _V4L2-PIX-FMT-BGR24: + + - ``V4L2_PIX_FMT_BGR24`` + + - 'BGR3' + + - + - 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-RGB24: + + - ``V4L2_PIX_FMT_RGB24`` + + - 'RGB3' + + - + - 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-BGR666: + + - ``V4L2_PIX_FMT_BGR666`` + + - 'BGRH' + + - + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - r\ :sub:`5` + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - + - r\ :sub:`1` + + - r\ :sub:`0` + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - .. _V4L2-PIX-FMT-ABGR32: + + - ``V4L2_PIX_FMT_ABGR32`` + + - 'AR24' + + - + - 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` + + - + - 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-XBGR32: + + - ``V4L2_PIX_FMT_XBGR32`` + + - 'XR24' + + - + - 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-ARGB32: + + - ``V4L2_PIX_FMT_ARGB32`` + + - 'BA24' + + - + - a\ :sub:`7` + + - a\ :sub:`6` + + - a\ :sub:`5` + + - a\ :sub:`4` + + - a\ :sub:`3` + + - a\ :sub:`2` + + - a\ :sub:`1` + + - a\ :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` + + - + - 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-XRGB32: + + - ``V4L2_PIX_FMT_XRGB32`` + + - 'BX24' + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - 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` + + +Bit 7 is the most significant bit. + +The usage and value of the alpha bits (a) in the ARGB and ABGR formats +(collectively referred to as alpha formats) depend on the device type +and hardware operation. :ref:`Capture <capture>` devices (including +capture queues of mem-to-mem devices) fill the alpha component in +memory. When the device outputs an alpha channel the alpha component +will have a meaningful value. Otherwise, when the device doesn't output +an alpha channel but can set the alpha bit to a user-configurable value, +the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control +is used to specify that alpha value, and the alpha component of all +pixels will be set to the value specified by that control. Otherwise a +corresponding format without an alpha component (XRGB or XBGR) must be +used instead of an alpha format. + +:ref:`Output <output>` devices (including output queues of mem-to-mem +devices and :ref:`video output overlay <osd>` devices) read the alpha +component from memory. When the device processes the alpha channel the +alpha component must be filled with meaningful values by applications. +Otherwise a corresponding format without an alpha component (XRGB or +XBGR) must be used instead of an alpha format. + +The XRGB and XBGR formats contain undefined bits (-). Applications, +devices and drivers must ignore those bits, for both +:ref:`capture` and :ref:`output` devices. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - B\ :sub:`00` + + - G\ :sub:`00` + + - R\ :sub:`00` + + - B\ :sub:`01` + + - G\ :sub:`01` + + - R\ :sub:`01` + + - B\ :sub:`02` + + - G\ :sub:`02` + + - R\ :sub:`02` + + - B\ :sub:`03` + + - G\ :sub:`03` + + - R\ :sub:`03` + + - .. row 2 + + - start + 12: + + - B\ :sub:`10` + + - G\ :sub:`10` + + - R\ :sub:`10` + + - B\ :sub:`11` + + - G\ :sub:`11` + + - R\ :sub:`11` + + - B\ :sub:`12` + + - G\ :sub:`12` + + - R\ :sub:`12` + + - B\ :sub:`13` + + - G\ :sub:`13` + + - R\ :sub:`13` + + - .. row 3 + + - start + 24: + + - B\ :sub:`20` + + - G\ :sub:`20` + + - R\ :sub:`20` + + - B\ :sub:`21` + + - G\ :sub:`21` + + - R\ :sub:`21` + + - B\ :sub:`22` + + - G\ :sub:`22` + + - R\ :sub:`22` + + - B\ :sub:`23` + + - G\ :sub:`23` + + - R\ :sub:`23` + + - .. row 4 + + - start + 36: + + - B\ :sub:`30` + + - G\ :sub:`30` + + - R\ :sub:`30` + + - B\ :sub:`31` + + - G\ :sub:`31` + + - R\ :sub:`31` + + - B\ :sub:`32` + + - G\ :sub:`32` + + - R\ :sub:`32` + + - B\ :sub:`33` + + - G\ :sub:`33` + + - R\ :sub:`33` + + +Formats defined in :ref:`rgb-formats-deprecated` are deprecated and +must not be used by new drivers. They are documented here for reference. +The meaning of their alpha bits (a) is ill-defined and interpreted as in +either the corresponding ARGB or XRGB format, depending on the driver. + + +.. _rgb-formats-deprecated: + +.. flat-table:: Deprecated Packed RGB Image Formats + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - :cspan:`7` Byte 0 in memory + + - :cspan:`7` Byte 1 + + - :cspan:`7` Byte 2 + + - :cspan:`7` Byte 3 + + - .. row 2 + + - + - + - Bit + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _V4L2-PIX-FMT-RGB444: + + - ``V4L2_PIX_FMT_RGB444`` + + - 'R444' + + - + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - 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` + + - .. _V4L2-PIX-FMT-RGB555: + + - ``V4L2_PIX_FMT_RGB555`` + + - 'RGBO' + + - + - g\ :sub:`2` + + - 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` + + - .. _V4L2-PIX-FMT-RGB555X: + + - ``V4L2_PIX_FMT_RGB555X`` + + - 'RGBQ' + + - + - 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` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _V4L2-PIX-FMT-BGR32: + + - ``V4L2_PIX_FMT_BGR32`` + + - 'BGR4' + + - + - 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` + + - + - 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-RGB32: + + - ``V4L2_PIX_FMT_RGB32`` + + - 'RGB4' + + - + - a\ :sub:`7` + + - a\ :sub:`6` + + - a\ :sub:`5` + + - a\ :sub:`4` + + - a\ :sub:`3` + + - a\ :sub:`2` + + - a\ :sub:`1` + + - a\ :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` + + - + - 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 test utility to determine which RGB formats a driver actually supports +is available from the LinuxTV v4l-dvb repository. See +`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access +instructions. diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst new file mode 100644 index 000000000000..54716455f453 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst @@ -0,0 +1,316 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _packed-yuv: + +****************** +Packed YUV formats +****************** + +*man Packed YUV formats(2)* + +Packed YUV formats + + +Description +=========== + +Similar to the packed RGB formats these formats store the Y, Cb and Cr +component of each pixel in one 16 or 32 bit word. + + + +.. flat-table:: Packed YUV Image Formats + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - :cspan:`7` Byte 0 in memory + + - + - :cspan:`7` Byte 1 + + - + - :cspan:`7` Byte 2 + + - + - :cspan:`7` Byte 3 + + - .. row 2 + + - + - + - Bit + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _V4L2-PIX-FMT-YUV444: + + - ``V4L2_PIX_FMT_YUV444`` + + - 'Y444' + + - + - Cb\ :sub:`3` + + - Cb\ :sub:`2` + + - Cb\ :sub:`1` + + - Cb\ :sub:`0` + + - Cr\ :sub:`3` + + - Cr\ :sub:`2` + + - Cr\ :sub:`1` + + - Cr\ :sub:`0` + + - + - a\ :sub:`3` + + - a\ :sub:`2` + + - a\ :sub:`1` + + - a\ :sub:`0` + + - Y'\ :sub:`3` + + - Y'\ :sub:`2` + + - Y'\ :sub:`1` + + - Y'\ :sub:`0` + + - .. _V4L2-PIX-FMT-YUV555: + + - ``V4L2_PIX_FMT_YUV555`` + + - 'YUVO' + + - + - Cb\ :sub:`2` + + - Cb\ :sub:`1` + + - Cb\ :sub:`0` + + - Cr\ :sub:`4` + + - Cr\ :sub:`3` + + - Cr\ :sub:`2` + + - Cr\ :sub:`1` + + - Cr\ :sub:`0` + + - + - a + + - Y'\ :sub:`4` + + - Y'\ :sub:`3` + + - Y'\ :sub:`2` + + - Y'\ :sub:`1` + + - Y'\ :sub:`0` + + - Cb\ :sub:`4` + + - Cb\ :sub:`3` + + - .. _V4L2-PIX-FMT-YUV565: + + - ``V4L2_PIX_FMT_YUV565`` + + - 'YUVP' + + - + - Cb\ :sub:`2` + + - Cb\ :sub:`1` + + - Cb\ :sub:`0` + + - Cr\ :sub:`4` + + - Cr\ :sub:`3` + + - Cr\ :sub:`2` + + - Cr\ :sub:`1` + + - Cr\ :sub:`0` + + - + - Y'\ :sub:`4` + + - Y'\ :sub:`3` + + - Y'\ :sub:`2` + + - Y'\ :sub:`1` + + - Y'\ :sub:`0` + + - Cb\ :sub:`5` + + - Cb\ :sub:`4` + + - Cb\ :sub:`3` + + - .. _V4L2-PIX-FMT-YUV32: + + - ``V4L2_PIX_FMT_YUV32`` + + - 'YUV4' + + - + - 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` + + +Bit 7 is the most significant bit. 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>`. diff --git a/Documentation/media/uapi/v4l/pixfmt-reserved.rst b/Documentation/media/uapi/v4l/pixfmt-reserved.rst new file mode 100644 index 000000000000..9a5704baf9fe --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-reserved.rst @@ -0,0 +1,360 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _pixfmt-reserved: + +*************************** +Reserved Format Identifiers +*************************** + +These formats are not defined by this specification, they are just +listed for reference and to avoid naming conflicts. If you want to +register your own format, send an e-mail to the linux-media mailing list +`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__ +for inclusion in the ``videodev2.h`` file. If you want to share your +format with other developers add a link to your documentation and send a +copy to the linux-media mailing list for inclusion in this section. If +you think your format should be listed in a standard format section +please make a proposal on the linux-media mailing list. + + +.. _reserved-formats: + +.. flat-table:: Reserved Image Formats + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - Identifier + + - Code + + - Details + + - .. _V4L2-PIX-FMT-DV: + + - ``V4L2_PIX_FMT_DV`` + + - 'dvsd' + + - unknown + + - .. _V4L2-PIX-FMT-ET61X251: + + - ``V4L2_PIX_FMT_ET61X251`` + + - 'E625' + + - Compressed format of the ET61X251 driver. + + - .. _V4L2-PIX-FMT-HI240: + + - ``V4L2_PIX_FMT_HI240`` + + - 'HI24' + + - 8 bit RGB format used by the BTTV driver. + + - .. _V4L2-PIX-FMT-HM12: + + - ``V4L2_PIX_FMT_HM12`` + + - 'HM12' + + - YUV 4:2:0 format used by the IVTV driver, + `http://www.ivtvdriver.org/ <http://www.ivtvdriver.org/>`__ + + The format is documented in the kernel sources in the file + ``Documentation/video4linux/cx2341x/README.hm12`` + + - .. _V4L2-PIX-FMT-CPIA1: + + - ``V4L2_PIX_FMT_CPIA1`` + + - 'CPIA' + + - YUV format used by the gspca cpia1 driver. + + - .. _V4L2-PIX-FMT-JPGL: + + - ``V4L2_PIX_FMT_JPGL`` + + - 'JPGL' + + - JPEG-Light format (Pegasus Lossless JPEG) used in Divio webcams NW + 80x. + + - .. _V4L2-PIX-FMT-SPCA501: + + - ``V4L2_PIX_FMT_SPCA501`` + + - 'S501' + + - YUYV per line used by the gspca driver. + + - .. _V4L2-PIX-FMT-SPCA505: + + - ``V4L2_PIX_FMT_SPCA505`` + + - 'S505' + + - YYUV per line used by the gspca driver. + + - .. _V4L2-PIX-FMT-SPCA508: + + - ``V4L2_PIX_FMT_SPCA508`` + + - 'S508' + + - YUVY per line used by the gspca driver. + + - .. _V4L2-PIX-FMT-SPCA561: + + - ``V4L2_PIX_FMT_SPCA561`` + + - 'S561' + + - Compressed GBRG Bayer format used by the gspca driver. + + - .. _V4L2-PIX-FMT-PAC207: + + - ``V4L2_PIX_FMT_PAC207`` + + - 'P207' + + - Compressed BGGR Bayer format used by the gspca driver. + + - .. _V4L2-PIX-FMT-MR97310A: + + - ``V4L2_PIX_FMT_MR97310A`` + + - 'M310' + + - Compressed BGGR Bayer format used by the gspca driver. + + - .. _V4L2-PIX-FMT-JL2005BCD: + + - ``V4L2_PIX_FMT_JL2005BCD`` + + - 'JL20' + + - JPEG compressed RGGB Bayer format used by the gspca driver. + + - .. _V4L2-PIX-FMT-OV511: + + - ``V4L2_PIX_FMT_OV511`` + + - 'O511' + + - OV511 JPEG format used by the gspca driver. + + - .. _V4L2-PIX-FMT-OV518: + + - ``V4L2_PIX_FMT_OV518`` + + - 'O518' + + - OV518 JPEG format used by the gspca driver. + + - .. _V4L2-PIX-FMT-PJPG: + + - ``V4L2_PIX_FMT_PJPG`` + + - 'PJPG' + + - Pixart 73xx JPEG format used by the gspca driver. + + - .. _V4L2-PIX-FMT-SE401: + + - ``V4L2_PIX_FMT_SE401`` + + - 'S401' + + - Compressed RGB format used by the gspca se401 driver + + - .. _V4L2-PIX-FMT-SQ905C: + + - ``V4L2_PIX_FMT_SQ905C`` + + - '905C' + + - Compressed RGGB bayer format used by the gspca driver. + + - .. _V4L2-PIX-FMT-MJPEG: + + - ``V4L2_PIX_FMT_MJPEG`` + + - 'MJPG' + + - Compressed format used by the Zoran driver + + - .. _V4L2-PIX-FMT-PWC1: + + - ``V4L2_PIX_FMT_PWC1`` + + - 'PWC1' + + - Compressed format of the PWC driver. + + - .. _V4L2-PIX-FMT-PWC2: + + - ``V4L2_PIX_FMT_PWC2`` + + - 'PWC2' + + - Compressed format of the PWC driver. + + - .. _V4L2-PIX-FMT-SN9C10X: + + - ``V4L2_PIX_FMT_SN9C10X`` + + - 'S910' + + - Compressed format of the SN9C102 driver. + + - .. _V4L2-PIX-FMT-SN9C20X-I420: + + - ``V4L2_PIX_FMT_SN9C20X_I420`` + + - 'S920' + + - YUV 4:2:0 format of the gspca sn9c20x driver. + + - .. _V4L2-PIX-FMT-SN9C2028: + + - ``V4L2_PIX_FMT_SN9C2028`` + + - 'SONX' + + - Compressed GBRG bayer format of the gspca sn9c2028 driver. + + - .. _V4L2-PIX-FMT-STV0680: + + - ``V4L2_PIX_FMT_STV0680`` + + - 'S680' + + - Bayer format of the gspca stv0680 driver. + + - .. _V4L2-PIX-FMT-WNVA: + + - ``V4L2_PIX_FMT_WNVA`` + + - 'WNVA' + + - Used by the Winnov Videum driver, + `http://www.thedirks.org/winnov/ <http://www.thedirks.org/winnov/>`__ + + - .. _V4L2-PIX-FMT-TM6000: + + - ``V4L2_PIX_FMT_TM6000`` + + - 'TM60' + + - Used by Trident tm6000 + + - .. _V4L2-PIX-FMT-CIT-YYVYUY: + + - ``V4L2_PIX_FMT_CIT_YYVYUY`` + + - 'CITV' + + - Used by xirlink CIT, found at IBM webcams. + + Uses one line of Y then 1 line of VYUY + + - .. _V4L2-PIX-FMT-KONICA420: + + - ``V4L2_PIX_FMT_KONICA420`` + + - 'KONI' + + - Used by Konica webcams. + + YUV420 planar in blocks of 256 pixels. + + - .. _V4L2-PIX-FMT-YYUV: + + - ``V4L2_PIX_FMT_YYUV`` + + - 'YYUV' + + - unknown + + - .. _V4L2-PIX-FMT-Y4: + + - ``V4L2_PIX_FMT_Y4`` + + - 'Y04 ' + + - Old 4-bit greyscale format. Only the most significant 4 bits of + each byte are used, the other bits are set to 0. + + - .. _V4L2-PIX-FMT-Y6: + + - ``V4L2_PIX_FMT_Y6`` + + - 'Y06 ' + + - Old 6-bit greyscale format. Only the most significant 6 bits of + each byte are used, the other bits are set to 0. + + - .. _V4L2-PIX-FMT-S5C-UYVY-JPG: + + - ``V4L2_PIX_FMT_S5C_UYVY_JPG`` + + - 'S5CI' + + - Two-planar format used by Samsung S5C73MX cameras. The first plane + contains interleaved JPEG and UYVY image data, followed by meta + data in form of an array of offsets to the UYVY data blocks. The + actual pointer array follows immediately the interleaved JPEG/UYVY + data, the number of entries in this array equals the height of the + UYVY image. Each entry is a 4-byte unsigned integer in big endian + order and it's an offset to a single pixel line of the UYVY image. + The first plane can start either with JPEG or UYVY data chunk. The + size of a single UYVY block equals the UYVY image's width + multiplied by 2. The size of a JPEG chunk depends on the image and + can vary with each line. + + The second plane, at an offset of 4084 bytes, contains a 4-byte + offset to the pointer array in the first plane. This offset is + followed by a 4-byte value indicating size of the pointer array. + All numbers in the second plane are also in big endian order. + Remaining data in the second plane is undefined. The information + in the second plane allows to easily find location of the pointer + array, which can be different for each frame. The size of the + pointer array is constant for given UYVY image height. + + In order to extract UYVY and JPEG frames an application can + initially set a data pointer to the start of first plane and then + add an offset from the first entry of the pointers table. Such a + pointer indicates start of an UYVY image pixel line. Whole UYVY + line can be copied to a separate buffer. These steps should be + repeated for each line, i.e. the number of entries in the pointer + array. Anything what's in between the UYVY lines is JPEG data and + should be concatenated to form the JPEG stream. + + + +.. _format-flags: + +.. flat-table:: Format Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA`` + + - 0x00000001 + + - The color values are premultiplied by the alpha channel value. For + example, if a light blue pixel with 50% transparency was described + by RGBA values (128, 192, 255, 128), the same pixel described with + premultiplied colors would be described by RGBA values (64, 96, + 128, 128) diff --git a/Documentation/media/uapi/v4l/pixfmt-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-rgb.rst new file mode 100644 index 000000000000..4b3651cc0a96 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-rgb.rst @@ -0,0 +1,23 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _pixfmt-rgb: + +*********** +RGB Formats +*********** + + +.. toctree:: + :maxdepth: 1 + + pixfmt-packed-rgb + pixfmt-sbggr8 + pixfmt-sgbrg8 + pixfmt-sgrbg8 + pixfmt-srggb8 + pixfmt-sbggr16 + pixfmt-srggb10 + pixfmt-srggb10p + pixfmt-srggb10alaw8 + pixfmt-srggb10dpcm8 + pixfmt-srggb12 diff --git a/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst b/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst new file mode 100644 index 000000000000..2cfcc97b3c96 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst @@ -0,0 +1,113 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SBGGR16: + +***************************** +V4L2_PIX_FMT_SBGGR16 ('BYR2') +***************************** + +*man V4L2_PIX_FMT_SBGGR16(2)* + +Bayer RGB format + + +Description +=========== + +This format is similar to +:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`, except each pixel +has a depth of 16 bits. The least significant byte is stored at lower +memory addresses (little-endian). Note the actual sampling precision may +be lower than 16 bits, for example 10 bits per pixel with values in +range 0 to 1023. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - B\ :sub:`00low` + + - B\ :sub:`00high` + + - G\ :sub:`01low` + + - G\ :sub:`01high` + + - B\ :sub:`02low` + + - B\ :sub:`02high` + + - G\ :sub:`03low` + + - G\ :sub:`03high` + + - .. row 2 + + - start + 8: + + - G\ :sub:`10low` + + - G\ :sub:`10high` + + - R\ :sub:`11low` + + - R\ :sub:`11high` + + - G\ :sub:`12low` + + - G\ :sub:`12high` + + - R\ :sub:`13low` + + - R\ :sub:`13high` + + - .. row 3 + + - start + 16: + + - B\ :sub:`20low` + + - B\ :sub:`20high` + + - G\ :sub:`21low` + + - G\ :sub:`21high` + + - B\ :sub:`22low` + + - B\ :sub:`22high` + + - G\ :sub:`23low` + + - G\ :sub:`23high` + + - .. row 4 + + - start + 24: + + - G\ :sub:`30low` + + - G\ :sub:`30high` + + - R\ :sub:`31low` + + - R\ :sub:`31high` + + - G\ :sub:`32low` + + - G\ :sub:`32high` + + - R\ :sub:`33low` + + - R\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/pixfmt-sbggr8.rst b/Documentation/media/uapi/v4l/pixfmt-sbggr8.rst new file mode 100644 index 000000000000..db4c523f49a9 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sbggr8.rst @@ -0,0 +1,81 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SBGGR8: + +**************************** +V4L2_PIX_FMT_SBGGR8 ('BA81') +**************************** + +*man V4L2_PIX_FMT_SBGGR8(2)* + +Bayer RGB format + + +Description +=========== + +This is commonly the native format of digital cameras, reflecting the +arrangement of sensors on the CCD device. Only one red, green or blue +value is given for each pixel. Missing components must be interpolated +from neighbouring pixels. From left to right the first row consists of a +blue and green value, the second row of a green and red value. This +scheme repeats to the right and down for every two columns and rows. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - B\ :sub:`00` + + - G\ :sub:`01` + + - B\ :sub:`02` + + - G\ :sub:`03` + + - .. row 2 + + - start + 4: + + - G\ :sub:`10` + + - R\ :sub:`11` + + - G\ :sub:`12` + + - R\ :sub:`13` + + - .. row 3 + + - start + 8: + + - B\ :sub:`20` + + - G\ :sub:`21` + + - B\ :sub:`22` + + - G\ :sub:`23` + + - .. row 4 + + - start + 12: + + - G\ :sub:`30` + + - R\ :sub:`31` + + - G\ :sub:`32` + + - R\ :sub:`33` diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst new file mode 100644 index 000000000000..2736275d080f --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst @@ -0,0 +1,43 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-sdr-fmt-cs8: + +************************* +V4L2_SDR_FMT_CS8 ('CS08') +************************* + +*man V4L2_SDR_FMT_CS8(2)* + +Complex signed 8-bit IQ sample + + +Description +=========== + +This format contains sequence of complex number samples. Each complex +number consist two parts, called In-phase and Quadrature (IQ). Both I +and Q are represented as a 8 bit signed number. I value comes first and +Q value after that. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 + + + - .. row 1 + + - start + 0: + + - I'\ :sub:`0` + + - .. row 2 + + - start + 1: + + - Q'\ :sub:`0` diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst new file mode 100644 index 000000000000..bfe5804bd84e --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst @@ -0,0 +1,48 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-SDR-FMT-CS14LE: + +**************************** +V4L2_SDR_FMT_CS14LE ('CS14') +**************************** + +*man V4L2_SDR_FMT_CS14LE(2)* + +Complex signed 14-bit little endian IQ sample + + +Description +=========== + +This format contains sequence of complex number samples. Each complex +number consist two parts, called In-phase and Quadrature (IQ). Both I +and Q are represented as a 14 bit signed little endian number. I value +comes first and Q value after that. 14 bit value is stored in 16 bit +space with unused high bits padded with 0. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 + + + - .. row 1 + + - start + 0: + + - I'\ :sub:`0[7:0]` + + - I'\ :sub:`0[13:8]` + + - .. row 2 + + - start + 2: + + - Q'\ :sub:`0[7:0]` + + - Q'\ :sub:`0[13:8]` diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst new file mode 100644 index 000000000000..68ad1717f6d7 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst @@ -0,0 +1,43 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-sdr-fmt-cu8: + +************************* +V4L2_SDR_FMT_CU8 ('CU08') +************************* + +*man V4L2_SDR_FMT_CU8(2)* + +Complex unsigned 8-bit IQ sample + + +Description +=========== + +This format contains sequence of complex number samples. Each complex +number consist two parts, called In-phase and Quadrature (IQ). Both I +and Q are represented as a 8 bit unsigned number. I value comes first +and Q value after that. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 + + + - .. row 1 + + - start + 0: + + - I'\ :sub:`0` + + - .. row 2 + + - start + 1: + + - Q'\ :sub:`0` diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst new file mode 100644 index 000000000000..2a1c0d4924a1 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst @@ -0,0 +1,47 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-SDR-FMT-CU16LE: + +**************************** +V4L2_SDR_FMT_CU16LE ('CU16') +**************************** + +*man V4L2_SDR_FMT_CU16LE(2)* + +Complex unsigned 16-bit little endian IQ sample + + +Description +=========== + +This format contains sequence of complex number samples. Each complex +number consist two parts, called In-phase and Quadrature (IQ). Both I +and Q are represented as a 16 bit unsigned little endian number. I value +comes first and Q value after that. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 + + + - .. row 1 + + - start + 0: + + - I'\ :sub:`0[7:0]` + + - I'\ :sub:`0[15:8]` + + - .. row 2 + + - start + 2: + + - Q'\ :sub:`0[7:0]` + + - Q'\ :sub:`0[15:8]` diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst new file mode 100644 index 000000000000..378581b27d4a --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst @@ -0,0 +1,38 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-SDR-FMT-RU12LE: + +**************************** +V4L2_SDR_FMT_RU12LE ('RU12') +**************************** + +*man V4L2_SDR_FMT_RU12LE(2)* + +Real unsigned 12-bit little endian sample + + +Description +=========== + +This format contains sequence of real number samples. Each sample is +represented as a 12 bit unsigned little endian number. Sample is stored +in 16 bit space with unused high bits padded with 0. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 + + + - .. row 1 + + - start + 0: + + - I'\ :sub:`0[7:0]` + + - I'\ :sub:`0[11:8]` diff --git a/Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst b/Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst new file mode 100644 index 000000000000..6345c24d86f3 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst @@ -0,0 +1,81 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SGBRG8: + +**************************** +V4L2_PIX_FMT_SGBRG8 ('GBRG') +**************************** + +*man V4L2_PIX_FMT_SGBRG8(2)* + +Bayer RGB format + + +Description +=========== + +This is commonly the native format of digital cameras, reflecting the +arrangement of sensors on the CCD device. Only one red, green or blue +value is given for each pixel. Missing components must be interpolated +from neighbouring pixels. From left to right the first row consists of a +green and blue value, the second row of a red and green value. This +scheme repeats to the right and down for every two columns and rows. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - G\ :sub:`00` + + - B\ :sub:`01` + + - G\ :sub:`02` + + - B\ :sub:`03` + + - .. row 2 + + - start + 4: + + - R\ :sub:`10` + + - G\ :sub:`11` + + - R\ :sub:`12` + + - G\ :sub:`13` + + - .. row 3 + + - start + 8: + + - G\ :sub:`20` + + - B\ :sub:`21` + + - G\ :sub:`22` + + - B\ :sub:`23` + + - .. row 4 + + - start + 12: + + - R\ :sub:`30` + + - G\ :sub:`31` + + - R\ :sub:`32` + + - G\ :sub:`33` diff --git a/Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst b/Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst new file mode 100644 index 000000000000..51b7b8ef7519 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst @@ -0,0 +1,81 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SGRBG8: + +**************************** +V4L2_PIX_FMT_SGRBG8 ('GRBG') +**************************** + +*man V4L2_PIX_FMT_SGRBG8(2)* + +Bayer RGB format + + +Description +=========== + +This is commonly the native format of digital cameras, reflecting the +arrangement of sensors on the CCD device. Only one red, green or blue +value is given for each pixel. Missing components must be interpolated +from neighbouring pixels. From left to right the first row consists of a +green and blue value, the second row of a red and green value. This +scheme repeats to the right and down for every two columns and rows. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - G\ :sub:`00` + + - R\ :sub:`01` + + - G\ :sub:`02` + + - R\ :sub:`03` + + - .. row 2 + + - start + 4: + + - B\ :sub:`10` + + - G\ :sub:`11` + + - B\ :sub:`12` + + - G\ :sub:`13` + + - .. row 3 + + - start + 8: + + - G\ :sub:`20` + + - R\ :sub:`21` + + - G\ :sub:`22` + + - R\ :sub:`23` + + - .. row 4 + + - start + 12: + + - B\ :sub:`30` + + - G\ :sub:`31` + + - B\ :sub:`32` + + - G\ :sub:`33` diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10.rst new file mode 100644 index 000000000000..44a49563917c --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10.rst @@ -0,0 +1,120 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SRGGB10: +.. _v4l2-pix-fmt-sbggr10: +.. _v4l2-pix-fmt-sgbrg10: +.. _v4l2-pix-fmt-sgrbg10: + +*************************************************************************************************************************** +V4L2_PIX_FMT_SRGGB10 ('RG10'), V4L2_PIX_FMT_SGRBG10 ('BA10'), V4L2_PIX_FMT_SGBRG10 ('GB10'), V4L2_PIX_FMT_SBGGR10 ('BG10'), +*************************************************************************************************************************** + +*man V4L2_PIX_FMT_SRGGB10(2)* + +V4L2_PIX_FMT_SGRBG10 +V4L2_PIX_FMT_SGBRG10 +V4L2_PIX_FMT_SBGGR10 +10-bit Bayer formats expanded to 16 bits + + +Description +=========== + +These four pixel formats are raw sRGB / Bayer formats with 10 bits per +colour. Each colour component is stored in a 16-bit word, with 6 unused +high bits filled with zeros. Each n-pixel row contains n/2 green samples +and n/2 blue or red samples, with alternating red and blue rows. Bytes +are stored in memory in little endian order. They are conventionally +described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example +of one of these formats + +**Byte Order.** +Each cell is one byte, high 6 bits in high bytes are 0. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - B\ :sub:`00low` + + - B\ :sub:`00high` + + - G\ :sub:`01low` + + - G\ :sub:`01high` + + - B\ :sub:`02low` + + - B\ :sub:`02high` + + - G\ :sub:`03low` + + - G\ :sub:`03high` + + - .. row 2 + + - start + 8: + + - G\ :sub:`10low` + + - G\ :sub:`10high` + + - R\ :sub:`11low` + + - R\ :sub:`11high` + + - G\ :sub:`12low` + + - G\ :sub:`12high` + + - R\ :sub:`13low` + + - R\ :sub:`13high` + + - .. row 3 + + - start + 16: + + - B\ :sub:`20low` + + - B\ :sub:`20high` + + - G\ :sub:`21low` + + - G\ :sub:`21high` + + - B\ :sub:`22low` + + - B\ :sub:`22high` + + - G\ :sub:`23low` + + - G\ :sub:`23high` + + - .. row 4 + + - start + 24: + + - G\ :sub:`30low` + + - G\ :sub:`30high` + + - R\ :sub:`31low` + + - R\ :sub:`31high` + + - G\ :sub:`32low` + + - G\ :sub:`32high` + + - R\ :sub:`33low` + + - R\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst new file mode 100644 index 000000000000..68bae0cb764c --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst @@ -0,0 +1,26 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SBGGR10ALAW8: +.. _v4l2-pix-fmt-sgbrg10alaw8: +.. _v4l2-pix-fmt-sgrbg10alaw8: +.. _v4l2-pix-fmt-srggb10alaw8: + +*********************************************************************************************************************************************** +V4L2_PIX_FMT_SBGGR10ALAW8 ('aBA8'), V4L2_PIX_FMT_SGBRG10ALAW8 ('aGA8'), V4L2_PIX_FMT_SGRBG10ALAW8 ('agA8'), V4L2_PIX_FMT_SRGGB10ALAW8 ('aRA8'), +*********************************************************************************************************************************************** + +*man V4L2_PIX_FMT_SBGGR10ALAW8(2)* + +V4L2_PIX_FMT_SGBRG10ALAW8 +V4L2_PIX_FMT_SGRBG10ALAW8 +V4L2_PIX_FMT_SRGGB10ALAW8 +10-bit Bayer formats compressed to 8 bits + + +Description +=========== + +These four pixel formats are raw sRGB / Bayer formats with 10 bits per +color compressed to 8 bits each, using the A-LAW algorithm. Each color +component consumes 8 bits of memory. In other respects this format is +similar to :ref:`V4L2-PIX-FMT-SRGGB8`. diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst new file mode 100644 index 000000000000..5e041d02eff0 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst @@ -0,0 +1,28 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SBGGR10DPCM8: +.. _v4l2-pix-fmt-sgbrg10dpcm8: +.. _v4l2-pix-fmt-sgrbg10dpcm8: +.. _v4l2-pix-fmt-srggb10dpcm8: + + +*********************************************************************************************************************************************** +V4L2_PIX_FMT_SBGGR10DPCM8 ('bBA8'), V4L2_PIX_FMT_SGBRG10DPCM8 ('bGA8'), V4L2_PIX_FMT_SGRBG10DPCM8 ('BD10'), V4L2_PIX_FMT_SRGGB10DPCM8 ('bRA8'), +*********************************************************************************************************************************************** + +*man V4L2_PIX_FMT_SBGGR10DPCM8(2)* + +V4L2_PIX_FMT_SGBRG10DPCM8 +V4L2_PIX_FMT_SGRBG10DPCM8 +V4L2_PIX_FMT_SRGGB10DPCM8 +10-bit Bayer formats compressed to 8 bits + + +Description +=========== + +These four pixel formats are raw sRGB / Bayer formats with 10 bits per +colour compressed to 8 bits each, using DPCM compression. DPCM, +differential pulse-code modulation, is lossy. Each colour component +consumes 8 bits of memory. In other respects this format is similar to +:ref:`V4L2-PIX-FMT-SRGGB10`. diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst new file mode 100644 index 000000000000..d71368f69087 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst @@ -0,0 +1,103 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SRGGB10P: +.. _v4l2-pix-fmt-sbggr10p: +.. _v4l2-pix-fmt-sgbrg10p: +.. _v4l2-pix-fmt-sgrbg10p: + +******************************************************************************************************************************* +V4L2_PIX_FMT_SRGGB10P ('pRAA'), V4L2_PIX_FMT_SGRBG10P ('pgAA'), V4L2_PIX_FMT_SGBRG10P ('pGAA'), V4L2_PIX_FMT_SBGGR10P ('pBAA'), +******************************************************************************************************************************* + +*man V4L2_PIX_FMT_SRGGB10P(2)* + +V4L2_PIX_FMT_SGRBG10P +V4L2_PIX_FMT_SGBRG10P +V4L2_PIX_FMT_SBGGR10P +10-bit packed Bayer formats + + +Description +=========== + +These four pixel formats are packed raw sRGB / Bayer formats with 10 +bits per colour. Every four consecutive colour components are packed +into 5 bytes. Each of the first 4 bytes contain the 8 high order bits of +the pixels, and the fifth byte contains the two least significants bits +of each pixel, in the same order. + +Each n-pixel row contains n/2 green samples and n/2 blue or red samples, +with alternating green-red and green-blue rows. They are conventionally +described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example +of one of these formats: + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - B\ :sub:`00high` + + - G\ :sub:`01high` + + - B\ :sub:`02high` + + - G\ :sub:`03high` + + - B\ :sub:`00low`\ (bits 7--6) G\ :sub:`01low`\ (bits 5--4) + B\ :sub:`02low`\ (bits 3--2) G\ :sub:`03low`\ (bits 1--0) + + - .. row 2 + + - start + 5: + + - G\ :sub:`10high` + + - R\ :sub:`11high` + + - G\ :sub:`12high` + + - R\ :sub:`13high` + + - G\ :sub:`10low`\ (bits 7--6) R\ :sub:`11low`\ (bits 5--4) + G\ :sub:`12low`\ (bits 3--2) R\ :sub:`13low`\ (bits 1--0) + + - .. row 3 + + - start + 10: + + - B\ :sub:`20high` + + - G\ :sub:`21high` + + - B\ :sub:`22high` + + - G\ :sub:`23high` + + - B\ :sub:`20low`\ (bits 7--6) G\ :sub:`21low`\ (bits 5--4) + B\ :sub:`22low`\ (bits 3--2) G\ :sub:`23low`\ (bits 1--0) + + - .. row 4 + + - start + 15: + + - G\ :sub:`30high` + + - R\ :sub:`31high` + + - G\ :sub:`32high` + + - R\ :sub:`33high` + + - G\ :sub:`30low`\ (bits 7--6) R\ :sub:`31low`\ (bits 5--4) + G\ :sub:`32low`\ (bits 3--2) R\ :sub:`33low`\ (bits 1--0) diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb12.rst b/Documentation/media/uapi/v4l/pixfmt-srggb12.rst new file mode 100644 index 000000000000..f5303ab9e79c --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-srggb12.rst @@ -0,0 +1,121 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SRGGB12: +.. _v4l2-pix-fmt-sbggr12: +.. _v4l2-pix-fmt-sgbrg12: +.. _v4l2-pix-fmt-sgrbg12: + + +*************************************************************************************************************************** +V4L2_PIX_FMT_SRGGB12 ('RG12'), V4L2_PIX_FMT_SGRBG12 ('BA12'), V4L2_PIX_FMT_SGBRG12 ('GB12'), V4L2_PIX_FMT_SBGGR12 ('BG12'), +*************************************************************************************************************************** + +*man V4L2_PIX_FMT_SRGGB12(2)* + +V4L2_PIX_FMT_SGRBG12 +V4L2_PIX_FMT_SGBRG12 +V4L2_PIX_FMT_SBGGR12 +12-bit Bayer formats expanded to 16 bits + + +Description +=========== + +These four pixel formats are raw sRGB / Bayer formats with 12 bits per +colour. Each colour component is stored in a 16-bit word, with 4 unused +high bits filled with zeros. Each n-pixel row contains n/2 green samples +and n/2 blue or red samples, with alternating red and blue rows. Bytes +are stored in memory in little endian order. They are conventionally +described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example +of one of these formats + +**Byte Order.** +Each cell is one byte, high 6 bits in high bytes are 0. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - B\ :sub:`00low` + + - B\ :sub:`00high` + + - G\ :sub:`01low` + + - G\ :sub:`01high` + + - B\ :sub:`02low` + + - B\ :sub:`02high` + + - G\ :sub:`03low` + + - G\ :sub:`03high` + + - .. row 2 + + - start + 8: + + - G\ :sub:`10low` + + - G\ :sub:`10high` + + - R\ :sub:`11low` + + - R\ :sub:`11high` + + - G\ :sub:`12low` + + - G\ :sub:`12high` + + - R\ :sub:`13low` + + - R\ :sub:`13high` + + - .. row 3 + + - start + 16: + + - B\ :sub:`20low` + + - B\ :sub:`20high` + + - G\ :sub:`21low` + + - G\ :sub:`21high` + + - B\ :sub:`22low` + + - B\ :sub:`22high` + + - G\ :sub:`23low` + + - G\ :sub:`23high` + + - .. row 4 + + - start + 24: + + - G\ :sub:`30low` + + - G\ :sub:`30high` + + - R\ :sub:`31low` + + - R\ :sub:`31high` + + - G\ :sub:`32low` + + - G\ :sub:`32high` + + - R\ :sub:`33low` + + - R\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb8.rst new file mode 100644 index 000000000000..e88de4c48d47 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-srggb8.rst @@ -0,0 +1,81 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-SRGGB8: + +**************************** +V4L2_PIX_FMT_SRGGB8 ('RGGB') +**************************** + +*man V4L2_PIX_FMT_SRGGB8(2)* + +Bayer RGB format + + +Description +=========== + +This is commonly the native format of digital cameras, reflecting the +arrangement of sensors on the CCD device. Only one red, green or blue +value is given for each pixel. Missing components must be interpolated +from neighbouring pixels. From left to right the first row consists of a +red and green value, the second row of a green and blue value. This +scheme repeats to the right and down for every two columns and rows. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - R\ :sub:`00` + + - G\ :sub:`01` + + - R\ :sub:`02` + + - G\ :sub:`03` + + - .. row 2 + + - start + 4: + + - G\ :sub:`10` + + - B\ :sub:`11` + + - G\ :sub:`12` + + - B\ :sub:`13` + + - .. row 3 + + - start + 8: + + - R\ :sub:`20` + + - G\ :sub:`21` + + - R\ :sub:`22` + + - G\ :sub:`23` + + - .. row 4 + + - start + 12: + + - G\ :sub:`30` + + - B\ :sub:`31` + + - G\ :sub:`32` + + - B\ :sub:`33` diff --git a/Documentation/media/uapi/v4l/pixfmt-uv8.rst b/Documentation/media/uapi/v4l/pixfmt-uv8.rst new file mode 100644 index 000000000000..fa8f7ee9fee1 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-uv8.rst @@ -0,0 +1,76 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-UV8: + +************************ +V4L2_PIX_FMT_UV8 ('UV8') +************************ + +*man V4L2_PIX_FMT_UV8(2)* + +UV plane interleaved + + +Description +=========== + +In this format there is no Y plane, Only CbCr plane. ie (UV interleaved) + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Cb\ :sub:`00` + + - Cr\ :sub:`00` + + - Cb\ :sub:`01` + + - Cr\ :sub:`01` + + - .. row 2 + + - start + 4: + + - Cb\ :sub:`10` + + - Cr\ :sub:`10` + + - Cb\ :sub:`11` + + - Cr\ :sub:`11` + + - .. row 3 + + - start + 8: + + - Cb\ :sub:`20` + + - Cr\ :sub:`20` + + - Cb\ :sub:`21` + + - Cr\ :sub:`21` + + - .. row 4 + + - start + 12: + + - Cb\ :sub:`30` + + - Cr\ :sub:`30` + + - Cb\ :sub:`31` + + - Cr\ :sub:`31` diff --git a/Documentation/media/uapi/v4l/pixfmt-uyvy.rst b/Documentation/media/uapi/v4l/pixfmt-uyvy.rst new file mode 100644 index 000000000000..87b0081d44ee --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-uyvy.rst @@ -0,0 +1,197 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-UYVY: + +************************** +V4L2_PIX_FMT_UYVY ('UYVY') +************************** + +*man V4L2_PIX_FMT_UYVY(2)* + +Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in +memory + + +Description +=========== + +In this format each four bytes is two pixels. Each four bytes is two +Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr +belong to both pixels. As you can see, the Cr and Cb components have +half the horizontal resolution of the Y component. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Cb\ :sub:`00` + + - Y'\ :sub:`00` + + - Cr\ :sub:`00` + + - Y'\ :sub:`01` + + - Cb\ :sub:`01` + + - Y'\ :sub:`02` + + - Cr\ :sub:`01` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 8: + + - Cb\ :sub:`10` + + - Y'\ :sub:`10` + + - Cr\ :sub:`10` + + - Y'\ :sub:`11` + + - Cb\ :sub:`11` + + - Y'\ :sub:`12` + + - Cr\ :sub:`11` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 16: + + - Cb\ :sub:`20` + + - Y'\ :sub:`20` + + - Cr\ :sub:`20` + + - Y'\ :sub:`21` + + - Cb\ :sub:`21` + + - Y'\ :sub:`22` + + - Cr\ :sub:`21` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 24: + + - Cb\ :sub:`30` + + - Y'\ :sub:`30` + + - Cr\ :sub:`30` + + - Y'\ :sub:`31` + + - Cb\ :sub:`31` + + - Y'\ :sub:`32` + + - Cr\ :sub:`31` + + - Y'\ :sub:`33` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 3 + + - 1 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 4 + + - 2 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 5 + + - 3 + + - Y + + - C + + - Y + + - Y + + - C + + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-vyuy.rst b/Documentation/media/uapi/v4l/pixfmt-vyuy.rst new file mode 100644 index 000000000000..5d8f99f173b6 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-vyuy.rst @@ -0,0 +1,195 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-VYUY: + +************************** +V4L2_PIX_FMT_VYUY ('VYUY') +************************** + +*man V4L2_PIX_FMT_VYUY(2)* + +Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in +memory + + +Description +=========== + +In this format each four bytes is two pixels. Each four bytes is two +Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr +belong to both pixels. As you can see, the Cr and Cb components have +half the horizontal resolution of the Y component. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Cr\ :sub:`00` + + - Y'\ :sub:`00` + + - Cb\ :sub:`00` + + - Y'\ :sub:`01` + + - Cr\ :sub:`01` + + - Y'\ :sub:`02` + + - Cb\ :sub:`01` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 8: + + - Cr\ :sub:`10` + + - Y'\ :sub:`10` + + - Cb\ :sub:`10` + + - Y'\ :sub:`11` + + - Cr\ :sub:`11` + + - Y'\ :sub:`12` + + - Cb\ :sub:`11` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 16: + + - Cr\ :sub:`20` + + - Y'\ :sub:`20` + + - Cb\ :sub:`20` + + - Y'\ :sub:`21` + + - Cr\ :sub:`21` + + - Y'\ :sub:`22` + + - Cb\ :sub:`21` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 24: + + - Cr\ :sub:`30` + + - Y'\ :sub:`30` + + - Cb\ :sub:`30` + + - Y'\ :sub:`31` + + - Cr\ :sub:`31` + + - Y'\ :sub:`32` + + - Cb\ :sub:`31` + + - Y'\ :sub:`33` + + +**Color Sample Location..** + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - + - 2 + + - 3 + + - .. row 2 + + - 0 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 3 + + - 1 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 4 + + - 2 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 5 + + - 3 + + - Y + + - C + + - Y + + - Y + + - C + + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-y10.rst b/Documentation/media/uapi/v4l/pixfmt-y10.rst new file mode 100644 index 000000000000..d22f77138289 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-y10.rst @@ -0,0 +1,110 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Y10: + +************************* +V4L2_PIX_FMT_Y10 ('Y10 ') +************************* + +*man V4L2_PIX_FMT_Y10(2)* + +Grey-scale image + + +Description +=========== + +This is a grey-scale image with a depth of 10 bits per pixel. Pixels are +stored in 16-bit words with unused high bits padded with 0. The least +significant byte is stored at lower memory addresses (little-endian). + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00low` + + - Y'\ :sub:`00high` + + - Y'\ :sub:`01low` + + - Y'\ :sub:`01high` + + - Y'\ :sub:`02low` + + - Y'\ :sub:`02high` + + - Y'\ :sub:`03low` + + - Y'\ :sub:`03high` + + - .. row 2 + + - start + 8: + + - Y'\ :sub:`10low` + + - Y'\ :sub:`10high` + + - Y'\ :sub:`11low` + + - Y'\ :sub:`11high` + + - Y'\ :sub:`12low` + + - Y'\ :sub:`12high` + + - Y'\ :sub:`13low` + + - Y'\ :sub:`13high` + + - .. row 3 + + - start + 16: + + - Y'\ :sub:`20low` + + - Y'\ :sub:`20high` + + - Y'\ :sub:`21low` + + - Y'\ :sub:`21high` + + - Y'\ :sub:`22low` + + - Y'\ :sub:`22high` + + - Y'\ :sub:`23low` + + - Y'\ :sub:`23high` + + - .. row 4 + + - start + 24: + + - Y'\ :sub:`30low` + + - Y'\ :sub:`30high` + + - Y'\ :sub:`31low` + + - Y'\ :sub:`31high` + + - Y'\ :sub:`32low` + + - Y'\ :sub:`32high` + + - Y'\ :sub:`33low` + + - Y'\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/pixfmt-y10b.rst b/Documentation/media/uapi/v4l/pixfmt-y10b.rst new file mode 100644 index 000000000000..5b50cd61e654 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-y10b.rst @@ -0,0 +1,45 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Y10BPACK: + +****************************** +V4L2_PIX_FMT_Y10BPACK ('Y10B') +****************************** + +*man V4L2_PIX_FMT_Y10BPACK(2)* + +Grey-scale image as a bit-packed array + + +Description +=========== + +This is a packed grey-scale image format with a depth of 10 bits per +pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel, +with no padding between them and with the most significant bits coming +first from the left. + +**Bit-packed representation.** + +pixels cross the byte boundary and have a ratio of 5 bytes for each 4 +pixels. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - Y'\ :sub:`00[9:2]` + + - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]` + + - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]` + + - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]` + + - Y'\ :sub:`03[7:0]` diff --git a/Documentation/media/uapi/v4l/pixfmt-y12.rst b/Documentation/media/uapi/v4l/pixfmt-y12.rst new file mode 100644 index 000000000000..7729bcbf3350 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-y12.rst @@ -0,0 +1,110 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Y12: + +************************* +V4L2_PIX_FMT_Y12 ('Y12 ') +************************* + +*man V4L2_PIX_FMT_Y12(2)* + +Grey-scale image + + +Description +=========== + +This is a grey-scale image with a depth of 12 bits per pixel. Pixels are +stored in 16-bit words with unused high bits padded with 0. The least +significant byte is stored at lower memory addresses (little-endian). + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00low` + + - Y'\ :sub:`00high` + + - Y'\ :sub:`01low` + + - Y'\ :sub:`01high` + + - Y'\ :sub:`02low` + + - Y'\ :sub:`02high` + + - Y'\ :sub:`03low` + + - Y'\ :sub:`03high` + + - .. row 2 + + - start + 8: + + - Y'\ :sub:`10low` + + - Y'\ :sub:`10high` + + - Y'\ :sub:`11low` + + - Y'\ :sub:`11high` + + - Y'\ :sub:`12low` + + - Y'\ :sub:`12high` + + - Y'\ :sub:`13low` + + - Y'\ :sub:`13high` + + - .. row 3 + + - start + 16: + + - Y'\ :sub:`20low` + + - Y'\ :sub:`20high` + + - Y'\ :sub:`21low` + + - Y'\ :sub:`21high` + + - Y'\ :sub:`22low` + + - Y'\ :sub:`22high` + + - Y'\ :sub:`23low` + + - Y'\ :sub:`23high` + + - .. row 4 + + - start + 24: + + - Y'\ :sub:`30low` + + - Y'\ :sub:`30high` + + - Y'\ :sub:`31low` + + - Y'\ :sub:`31high` + + - Y'\ :sub:`32low` + + - Y'\ :sub:`32high` + + - Y'\ :sub:`33low` + + - Y'\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/pixfmt-y12i.rst b/Documentation/media/uapi/v4l/pixfmt-y12i.rst new file mode 100644 index 000000000000..8967e8c33b47 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-y12i.rst @@ -0,0 +1,44 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Y12I: + +************************** +V4L2_PIX_FMT_Y12I ('Y12I') +************************** + +*man V4L2_PIX_FMT_Y12I(2)* + +Interleaved grey-scale image, e.g. from a stereo-pair + + +Description +=========== + +This is a grey-scale image with a depth of 12 bits per pixel, but with +pixels from 2 sources interleaved and bit-packed. Each pixel is stored +in a 24-bit word in the little-endian order. On a little-endian machine +these pixels can be deinterlaced using + +.. code-block:: c + + __u8 *buf; + left0 = 0xfff & *(__u16 *)buf; + right0 = *(__u16 *)(buf + 1) >> 4; + +**Bit-packed representation.** +pixels cross the byte boundary and have a ratio of 3 bytes for each +interleaved pixel. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 + + + - .. row 1 + + - Y'\ :sub:`0left[7:0]` + + - Y'\ :sub:`0right[3:0]`\ Y'\ :sub:`0left[11:8]` + + - Y'\ :sub:`0right[11:4]` diff --git a/Documentation/media/uapi/v4l/pixfmt-y16-be.rst b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst new file mode 100644 index 000000000000..0c61a10018c2 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst @@ -0,0 +1,111 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Y16-BE: + +**************************************** +V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31)) +**************************************** + +*man V4L2_PIX_FMT_Y16_BE(2)* + +Grey-scale image + + +Description +=========== + +This is a grey-scale image with a depth of 16 bits per pixel. The most +significant byte is stored at lower memory addresses (big-endian). Note +the actual sampling precision may be lower than 16 bits, for example 10 +bits per pixel with values in range 0 to 1023. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00high` + + - Y'\ :sub:`00low` + + - Y'\ :sub:`01high` + + - Y'\ :sub:`01low` + + - Y'\ :sub:`02high` + + - Y'\ :sub:`02low` + + - Y'\ :sub:`03high` + + - Y'\ :sub:`03low` + + - .. row 2 + + - start + 8: + + - Y'\ :sub:`10high` + + - Y'\ :sub:`10low` + + - Y'\ :sub:`11high` + + - Y'\ :sub:`11low` + + - Y'\ :sub:`12high` + + - Y'\ :sub:`12low` + + - Y'\ :sub:`13high` + + - Y'\ :sub:`13low` + + - .. row 3 + + - start + 16: + + - Y'\ :sub:`20high` + + - Y'\ :sub:`20low` + + - Y'\ :sub:`21high` + + - Y'\ :sub:`21low` + + - Y'\ :sub:`22high` + + - Y'\ :sub:`22low` + + - Y'\ :sub:`23high` + + - Y'\ :sub:`23low` + + - .. row 4 + + - start + 24: + + - Y'\ :sub:`30high` + + - Y'\ :sub:`30low` + + - Y'\ :sub:`31high` + + - Y'\ :sub:`31low` + + - Y'\ :sub:`32high` + + - Y'\ :sub:`32low` + + - Y'\ :sub:`33high` + + - Y'\ :sub:`33low` diff --git a/Documentation/media/uapi/v4l/pixfmt-y16.rst b/Documentation/media/uapi/v4l/pixfmt-y16.rst new file mode 100644 index 000000000000..a8d4b7192ae3 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-y16.rst @@ -0,0 +1,111 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Y16: + +************************* +V4L2_PIX_FMT_Y16 ('Y16 ') +************************* + +*man V4L2_PIX_FMT_Y16(2)* + +Grey-scale image + + +Description +=========== + +This is a grey-scale image with a depth of 16 bits per pixel. The least +significant byte is stored at lower memory addresses (little-endian). +Note the actual sampling precision may be lower than 16 bits, for +example 10 bits per pixel with values in range 0 to 1023. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00low` + + - Y'\ :sub:`00high` + + - Y'\ :sub:`01low` + + - Y'\ :sub:`01high` + + - Y'\ :sub:`02low` + + - Y'\ :sub:`02high` + + - Y'\ :sub:`03low` + + - Y'\ :sub:`03high` + + - .. row 2 + + - start + 8: + + - Y'\ :sub:`10low` + + - Y'\ :sub:`10high` + + - Y'\ :sub:`11low` + + - Y'\ :sub:`11high` + + - Y'\ :sub:`12low` + + - Y'\ :sub:`12high` + + - Y'\ :sub:`13low` + + - Y'\ :sub:`13high` + + - .. row 3 + + - start + 16: + + - Y'\ :sub:`20low` + + - Y'\ :sub:`20high` + + - Y'\ :sub:`21low` + + - Y'\ :sub:`21high` + + - Y'\ :sub:`22low` + + - Y'\ :sub:`22high` + + - Y'\ :sub:`23low` + + - Y'\ :sub:`23high` + + - .. row 4 + + - start + 24: + + - Y'\ :sub:`30low` + + - Y'\ :sub:`30high` + + - Y'\ :sub:`31low` + + - Y'\ :sub:`31high` + + - Y'\ :sub:`32low` + + - Y'\ :sub:`32high` + + - Y'\ :sub:`33low` + + - Y'\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/pixfmt-y41p.rst b/Documentation/media/uapi/v4l/pixfmt-y41p.rst new file mode 100644 index 000000000000..4760174a4668 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-y41p.rst @@ -0,0 +1,274 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Y41P: + +************************** +V4L2_PIX_FMT_Y41P ('Y41P') +************************** + +*man V4L2_PIX_FMT_Y41P(2)* + +Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1 + + +Description +=========== + +In this format each 12 bytes is eight pixels. In the twelve bytes are +two CbCr pairs and eight Y's. The first CbCr pair goes with the first +four Y's, and the second CbCr pair goes with the other four Y's. The Cb +and Cr components have one fourth the horizontal resolution of the Y +component. + +Do not confuse this format with +:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived +from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 +*planar*". + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Cb\ :sub:`00` + + - Y'\ :sub:`00` + + - Cr\ :sub:`00` + + - Y'\ :sub:`01` + + - Cb\ :sub:`01` + + - Y'\ :sub:`02` + + - Cr\ :sub:`01` + + - Y'\ :sub:`03` + + - Y'\ :sub:`04` + + - Y'\ :sub:`05` + + - Y'\ :sub:`06` + + - Y'\ :sub:`07` + + - .. row 2 + + - start + 12: + + - Cb\ :sub:`10` + + - Y'\ :sub:`10` + + - Cr\ :sub:`10` + + - Y'\ :sub:`11` + + - Cb\ :sub:`11` + + - Y'\ :sub:`12` + + - Cr\ :sub:`11` + + - Y'\ :sub:`13` + + - Y'\ :sub:`14` + + - Y'\ :sub:`15` + + - Y'\ :sub:`16` + + - Y'\ :sub:`17` + + - .. row 3 + + - start + 24: + + - Cb\ :sub:`20` + + - Y'\ :sub:`20` + + - Cr\ :sub:`20` + + - Y'\ :sub:`21` + + - Cb\ :sub:`21` + + - Y'\ :sub:`22` + + - Cr\ :sub:`21` + + - Y'\ :sub:`23` + + - Y'\ :sub:`24` + + - Y'\ :sub:`25` + + - Y'\ :sub:`26` + + - Y'\ :sub:`27` + + - .. row 4 + + - start + 36: + + - Cb\ :sub:`30` + + - Y'\ :sub:`30` + + - Cr\ :sub:`30` + + - Y'\ :sub:`31` + + - Cb\ :sub:`31` + + - Y'\ :sub:`32` + + - Cr\ :sub:`31` + + - Y'\ :sub:`33` + + - Y'\ :sub:`34` + + - Y'\ :sub:`35` + + - Y'\ :sub:`36` + + - Y'\ :sub:`37` + + +**Color Sample Location..** + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - 1 + + - + - 2 + + - 3 + + - 4 + + - 5 + + - + - 6 + + - 7 + + - .. row 2 + + - 0 + + - Y + + - Y + + - C + + - Y + + - Y + + - Y + + - Y + + - C + + - Y + + - Y + + - .. row 3 + + - 1 + + - Y + + - Y + + - C + + - Y + + - Y + + - Y + + - Y + + - C + + - Y + + - Y + + - .. row 4 + + - 2 + + - Y + + - Y + + - C + + - Y + + - Y + + - Y + + - Y + + - C + + - Y + + - Y + + - .. row 5 + + - 3 + + - Y + + - Y + + - C + + - Y + + - Y + + - Y + + - Y + + - C + + - Y + + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-y8i.rst b/Documentation/media/uapi/v4l/pixfmt-y8i.rst new file mode 100644 index 000000000000..7fa16ee85ab7 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-y8i.rst @@ -0,0 +1,111 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Y8I: + +************************* +V4L2_PIX_FMT_Y8I ('Y8I ') +************************* + +*man V4L2_PIX_FMT_Y8I(2)* + +Interleaved grey-scale image, e.g. from a stereo-pair + + +Description +=========== + +This is a grey-scale image with a depth of 8 bits per pixel, but with +pixels from 2 sources interleaved. Each pixel is stored in a 16-bit +word. E.g. the R200 RealSense camera stores pixel from the left sensor +in lower and from the right sensor in the higher 8 bits. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00left` + + - Y'\ :sub:`00right` + + - Y'\ :sub:`01left` + + - Y'\ :sub:`01right` + + - Y'\ :sub:`02left` + + - Y'\ :sub:`02right` + + - Y'\ :sub:`03left` + + - Y'\ :sub:`03right` + + - .. row 2 + + - start + 8: + + - Y'\ :sub:`10left` + + - Y'\ :sub:`10right` + + - Y'\ :sub:`11left` + + - Y'\ :sub:`11right` + + - Y'\ :sub:`12left` + + - Y'\ :sub:`12right` + + - Y'\ :sub:`13left` + + - Y'\ :sub:`13right` + + - .. row 3 + + - start + 16: + + - Y'\ :sub:`20left` + + - Y'\ :sub:`20right` + + - Y'\ :sub:`21left` + + - Y'\ :sub:`21right` + + - Y'\ :sub:`22left` + + - Y'\ :sub:`22right` + + - Y'\ :sub:`23left` + + - Y'\ :sub:`23right` + + - .. row 4 + + - start + 24: + + - Y'\ :sub:`30left` + + - Y'\ :sub:`30right` + + - Y'\ :sub:`31left` + + - Y'\ :sub:`31right` + + - Y'\ :sub:`32left` + + - Y'\ :sub:`32right` + + - Y'\ :sub:`33left` + + - Y'\ :sub:`33right` diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv410.rst b/Documentation/media/uapi/v4l/pixfmt-yuv410.rst new file mode 100644 index 000000000000..8a5d1a2ee005 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yuv410.rst @@ -0,0 +1,208 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YVU410: +.. _v4l2-pix-fmt-yuv410: + +********************************************************** +V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9') +********************************************************** + +*man V4L2_PIX_FMT_YVU410(2)* + +V4L2_PIX_FMT_YUV410 +Planar formats with ¼ horizontal and vertical chroma resolution, also +known as YUV 4:1:0 + + +Description +=========== + +These are planar formats, as opposed to a packed format. The three +components are separated into three sub-images or planes. The Y plane is +first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``, +the Cr plane immediately follows the Y plane in memory. The Cr plane is +¼ the width and ¼ the height of the Y plane (and of the image). Each Cr +belongs to 16 pixels, a four-by-four square of the image. Following the +Cr plane is the Cb plane, just like the Cr plane. +``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first, +then the Cr plane. + +If the Y plane has pad bytes after each row, then the Cr and Cb planes +have ¼ as many pad bytes after their rows. In other words, four Cx rows +(including padding) are exactly as long as one Y row (including +padding). + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - start + 16: + + - Cr\ :sub:`00` + + - .. row 6 + + - start + 17: + + - Cb\ :sub:`00` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 3 + + - + + - .. row 4 + + - 1 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 5 + + - + - + - + - + - C + + - + - + - + + - .. row 6 + + - 2 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 7 + + - + + - .. row 8 + + - 3 + + - Y + + - + - Y + + - + - Y + + - + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst b/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst new file mode 100644 index 000000000000..f85e3f388cbe --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst @@ -0,0 +1,214 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YUV411P: + +***************************** +V4L2_PIX_FMT_YUV411P ('411P') +***************************** + +*man V4L2_PIX_FMT_YUV411P(2)* + +Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1. +Planar layout as opposed to ``V4L2_PIX_FMT_Y41P`` + + +Description +=========== + +This format is not commonly used. This is a planar format similar to the +4:2:2 planar format except with half as many chroma. The three +components are separated into three sub-images or planes. The Y plane is +first. The Y plane has one byte per pixel. The Cb plane immediately +follows the Y plane in memory. The Cb plane is ¼ the width of the Y +plane (and of the image). Each Cb belongs to 4 pixels all on the same +row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, +Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane, +just like the Cb plane. + +If the Y plane has pad bytes after each row, then the Cr and Cb planes +have ¼ as many pad bytes after their rows. In other words, four C x rows +(including padding) is exactly as long as one Y row (including padding). + +**Byte Order.** +Each cell is one byte. + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - start + 16: + + - Cb\ :sub:`00` + + - .. row 6 + + - start + 17: + + - Cb\ :sub:`10` + + - .. row 7 + + - start + 18: + + - Cb\ :sub:`20` + + - .. row 8 + + - start + 19: + + - Cb\ :sub:`30` + + - .. row 9 + + - start + 20: + + - Cr\ :sub:`00` + + - .. row 10 + + - start + 21: + + - Cr\ :sub:`10` + + - .. row 11 + + - start + 22: + + - Cr\ :sub:`20` + + - .. row 12 + + - start + 23: + + - Cr\ :sub:`30` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - 1 + + - + - 2 + + - 3 + + - .. row 2 + + - 0 + + - Y + + - Y + + - C + + - Y + + - Y + + - .. row 3 + + - 1 + + - Y + + - Y + + - C + + - Y + + - Y + + - .. row 4 + + - 2 + + - Y + + - Y + + - C + + - Y + + - Y + + - .. row 5 + + - 3 + + - Y + + - Y + + - C + + - Y + + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv420.rst b/Documentation/media/uapi/v4l/pixfmt-yuv420.rst new file mode 100644 index 000000000000..b22e64c14f67 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yuv420.rst @@ -0,0 +1,239 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YVU420: +.. _V4L2-PIX-FMT-YUV420: + +********************************************************** +V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12') +********************************************************** + +*man V4L2_PIX_FMT_YVU420(2)* + +V4L2_PIX_FMT_YUV420 +Planar formats with ½ horizontal and vertical chroma resolution, also +known as YUV 4:2:0 + + +Description +=========== + +These are planar formats, as opposed to a packed format. The three +components are separated into three sub- images or planes. The Y plane +is first. The Y plane has one byte per pixel. For +``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in +memory. The Cr plane is half the width and half the height of the Y +plane (and of the image). Each Cr belongs to four pixels, a two-by-two +square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`, +Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane +is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the +same except the Cb plane comes first, then the Cr plane. + +If the Y plane has pad bytes after each row, then the Cr and Cb planes +have half as many pad bytes after their rows. In other words, two Cx +rows (including padding) is exactly as long as one Y row (including +padding). + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - start + 16: + + - Cr\ :sub:`00` + + - Cr\ :sub:`01` + + - .. row 6 + + - start + 18: + + - Cr\ :sub:`10` + + - Cr\ :sub:`11` + + - .. row 7 + + - start + 20: + + - Cb\ :sub:`00` + + - Cb\ :sub:`01` + + - .. row 8 + + - start + 22: + + - Cb\ :sub:`10` + + - Cb\ :sub:`11` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 3 + + - + - + - C + + - + - + - + - C + + - + + - .. row 4 + + - 1 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 5 + + - + + - .. row 6 + + - 2 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 7 + + - + - + - C + + - + - + - + - C + + - + + - .. row 8 + + - 3 + + - Y + + - + - Y + + - + - Y + + - + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst new file mode 100644 index 000000000000..4dab85090d7d --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst @@ -0,0 +1,254 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YUV420M: +.. _v4l2-pix-fmt-yvu420m: + +************************************************************ +V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21') +************************************************************ + +*man V4L2_PIX_FMT_YUV420M(2)* + +V4L2_PIX_FMT_YVU420M +Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with +planes non contiguous in memory. + + +Description +=========== + +This is a multi-planar format, as opposed to a packed format. The three +components are separated into three sub-images or planes. + +The Y plane is first. The Y plane has one byte per pixel. For +``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which +is half the width and half the height of the Y plane (and of the image). +Each Cb belongs to four pixels, a two-by-two square of the image. For +example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, +Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane, +is in the third plane. + +``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the +second plane and the Cb data in the third plane. + +If the Y plane has pad bytes after each row, then the Cb and Cr planes +have half as many pad bytes after their rows. In other words, two Cx +rows (including padding) is exactly as long as one Y row (including +padding). + +``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be +used only in drivers and applications that support the multi-planar API, +described in :ref:`planar-apis`. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start0 + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start0 + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start0 + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start0 + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - + + - .. row 6 + + - start1 + 0: + + - Cb\ :sub:`00` + + - Cb\ :sub:`01` + + - .. row 7 + + - start1 + 2: + + - Cb\ :sub:`10` + + - Cb\ :sub:`11` + + - .. row 8 + + - + + - .. row 9 + + - start2 + 0: + + - Cr\ :sub:`00` + + - Cr\ :sub:`01` + + - .. row 10 + + - start2 + 2: + + - Cr\ :sub:`10` + + - Cr\ :sub:`11` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 3 + + - + - + - C + + - + - + - + - C + + - + + - .. row 4 + + - 1 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 5 + + - + + - .. row 6 + + - 2 + + - Y + + - + - Y + + - + - Y + + - + - Y + + - .. row 7 + + - + - + - C + + - + - + - + - C + + - + + - .. row 8 + + - 3 + + - Y + + - + - Y + + - + - Y + + - + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst new file mode 100644 index 000000000000..ccb67284133a --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst @@ -0,0 +1,258 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YUV422M: +.. _v4l2-pix-fmt-yvu422m: + +************************************************************ +V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61') +************************************************************ + +*man V4L2_PIX_FMT_YUV422M(2)* + +V4L2_PIX_FMT_YVU422M +Planar formats with ½ horizontal resolution, also known as YUV and YVU +4:2:2 + + +Description +=========== + +This is a multi-planar format, as opposed to a packed format. The three +components are separated into three sub-images or planes. + +The Y plane is first. The Y plane has one byte per pixel. For +``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which +is half the width of the Y plane (and of the image). Each Cb belongs to +two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, +Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third +plane. + +``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the +second plane and the Cb data in the third plane. + +If the Y plane has pad bytes after each row, then the Cb and Cr planes +have half as many pad bytes after their rows. In other words, two Cx +rows (including padding) is exactly as long as one Y row (including +padding). + +``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be +used only in drivers and applications that support the multi-planar API, +described in :ref:`planar-apis`. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start0 + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start0 + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start0 + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start0 + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - + + - .. row 6 + + - start1 + 0: + + - Cb\ :sub:`00` + + - Cb\ :sub:`01` + + - .. row 7 + + - start1 + 2: + + - Cb\ :sub:`10` + + - Cb\ :sub:`11` + + - .. row 8 + + - start1 + 4: + + - Cb\ :sub:`20` + + - Cb\ :sub:`21` + + - .. row 9 + + - start1 + 6: + + - Cb\ :sub:`30` + + - Cb\ :sub:`31` + + - .. row 10 + + - + + - .. row 11 + + - start2 + 0: + + - Cr\ :sub:`00` + + - Cr\ :sub:`01` + + - .. row 12 + + - start2 + 2: + + - Cr\ :sub:`10` + + - Cr\ :sub:`11` + + - .. row 13 + + - start2 + 4: + + - Cr\ :sub:`20` + + - Cr\ :sub:`21` + + - .. row 14 + + - start2 + 6: + + - Cr\ :sub:`30` + + - Cr\ :sub:`31` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 3 + + - 1 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 4 + + - 2 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 5 + + - 3 + + - Y + + - C + + - Y + + - Y + + - C + + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst b/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst new file mode 100644 index 000000000000..9f34762adf18 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst @@ -0,0 +1,240 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YUV422P: + +***************************** +V4L2_PIX_FMT_YUV422P ('422P') +***************************** + +*man V4L2_PIX_FMT_YUV422P(2)* + +Format with ½ horizontal chroma resolution, also known as YUV 4:2:2. +Planar layout as opposed to ``V4L2_PIX_FMT_YUYV`` + + +Description +=========== + +This format is not commonly used. This is a planar version of the YUYV +format. The three components are separated into three sub-images or +planes. The Y plane is first. The Y plane has one byte per pixel. The Cb +plane immediately follows the Y plane in memory. The Cb plane is half +the width of the Y plane (and of the image). Each Cb belongs to two +pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, +Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb +plane. + +If the Y plane has pad bytes after each row, then the Cr and Cb planes +have half as many pad bytes after their rows. In other words, two Cx +rows (including padding) is exactly as long as one Y row (including +padding). + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - start + 16: + + - Cb\ :sub:`00` + + - Cb\ :sub:`01` + + - .. row 6 + + - start + 18: + + - Cb\ :sub:`10` + + - Cb\ :sub:`11` + + - .. row 7 + + - start + 20: + + - Cb\ :sub:`20` + + - Cb\ :sub:`21` + + - .. row 8 + + - start + 22: + + - Cb\ :sub:`30` + + - Cb\ :sub:`31` + + - .. row 9 + + - start + 24: + + - Cr\ :sub:`00` + + - Cr\ :sub:`01` + + - .. row 10 + + - start + 26: + + - Cr\ :sub:`10` + + - Cr\ :sub:`11` + + - .. row 11 + + - start + 28: + + - Cr\ :sub:`20` + + - Cr\ :sub:`21` + + - .. row 12 + + - start + 30: + + - Cr\ :sub:`30` + + - Cr\ :sub:`31` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 3 + + - 1 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 4 + + - 2 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 5 + + - 3 + + - Y + + - C + + - Y + + - Y + + - C + + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst new file mode 100644 index 000000000000..04f34508b934 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst @@ -0,0 +1,266 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YUV444M: +.. _v4l2-pix-fmt-yvu444m: + +************************************************************ +V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42') +************************************************************ + +*man V4L2_PIX_FMT_YUV444M(2)* + +V4L2_PIX_FMT_YVU444M +Planar formats with full horizontal resolution, also known as YUV and +YVU 4:4:4 + + +Description +=========== + +This is a multi-planar format, as opposed to a packed format. The three +components are separated into three sub-images or planes. + +The Y plane is first. The Y plane has one byte per pixel. For +``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which +is the same width and height as the Y plane (and as the image). The Cr +data, just like the Cb plane, is in the third plane. + +``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the +second plane and the Cb data in the third plane. + +If the Y plane has pad bytes after each row, then the Cb and Cr planes +have the same number of pad bytes after their rows. + +``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be +used only in drivers and applications that support the multi-planar API, +described in :ref:`planar-apis`. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 + + + - .. row 1 + + - start0 + 0: + + - Y'\ :sub:`00` + + - Y'\ :sub:`01` + + - Y'\ :sub:`02` + + - Y'\ :sub:`03` + + - .. row 2 + + - start0 + 4: + + - Y'\ :sub:`10` + + - Y'\ :sub:`11` + + - Y'\ :sub:`12` + + - Y'\ :sub:`13` + + - .. row 3 + + - start0 + 8: + + - Y'\ :sub:`20` + + - Y'\ :sub:`21` + + - Y'\ :sub:`22` + + - Y'\ :sub:`23` + + - .. row 4 + + - start0 + 12: + + - Y'\ :sub:`30` + + - Y'\ :sub:`31` + + - Y'\ :sub:`32` + + - Y'\ :sub:`33` + + - .. row 5 + + - + + - .. row 6 + + - start1 + 0: + + - Cb\ :sub:`00` + + - Cb\ :sub:`01` + + - Cb\ :sub:`02` + + - Cb\ :sub:`03` + + - .. row 7 + + - start1 + 4: + + - Cb\ :sub:`10` + + - Cb\ :sub:`11` + + - Cb\ :sub:`12` + + - Cb\ :sub:`13` + + - .. row 8 + + - start1 + 8: + + - Cb\ :sub:`20` + + - Cb\ :sub:`21` + + - Cb\ :sub:`22` + + - Cb\ :sub:`23` + + - .. row 9 + + - start1 + 12: + + - Cb\ :sub:`20` + + - Cb\ :sub:`21` + + - Cb\ :sub:`32` + + - Cb\ :sub:`33` + + - .. row 10 + + - + + - .. row 11 + + - start2 + 0: + + - Cr\ :sub:`00` + + - Cr\ :sub:`01` + + - Cr\ :sub:`02` + + - Cr\ :sub:`03` + + - .. row 12 + + - start2 + 4: + + - Cr\ :sub:`10` + + - Cr\ :sub:`11` + + - Cr\ :sub:`12` + + - Cr\ :sub:`13` + + - .. row 13 + + - start2 + 8: + + - Cr\ :sub:`20` + + - Cr\ :sub:`21` + + - Cr\ :sub:`22` + + - Cr\ :sub:`23` + + - .. row 14 + + - start2 + 12: + + - Cr\ :sub:`30` + + - Cr\ :sub:`31` + + - Cr\ :sub:`32` + + - Cr\ :sub:`33` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - 1 + + - 2 + + - 3 + + - .. row 2 + + - 0 + + - YC + + - YC + + - YC + + - YC + + - .. row 3 + + - 1 + + - YC + + - YC + + - YC + + - YC + + - .. row 4 + + - 2 + + - YC + + - YC + + - YC + + - YC + + - .. row 5 + + - 3 + + - YC + + - YC + + - YC + + - YC diff --git a/Documentation/media/uapi/v4l/pixfmt-yuyv.rst b/Documentation/media/uapi/v4l/pixfmt-yuyv.rst new file mode 100644 index 000000000000..52917dfa9261 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yuyv.rst @@ -0,0 +1,205 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YUYV: + +************************** +V4L2_PIX_FMT_YUYV ('YUYV') +************************** + +*man V4L2_PIX_FMT_YUYV(2)* + +Packed format with ½ horizontal chroma resolution, also known as YUV +4:2:2 + + +Description +=========== + +In this format each four bytes is two pixels. Each four bytes is two +Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr +belong to both pixels. As you can see, the Cr and Cb components have +half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV`` +is known in the Windows environment as YUY2. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Cb\ :sub:`00` + + - Y'\ :sub:`01` + + - Cr\ :sub:`00` + + - Y'\ :sub:`02` + + - Cb\ :sub:`01` + + - Y'\ :sub:`03` + + - Cr\ :sub:`01` + + - .. row 2 + + - start + 8: + + - Y'\ :sub:`10` + + - Cb\ :sub:`10` + + - Y'\ :sub:`11` + + - Cr\ :sub:`10` + + - Y'\ :sub:`12` + + - Cb\ :sub:`11` + + - Y'\ :sub:`13` + + - Cr\ :sub:`11` + + - .. row 3 + + - start + 16: + + - Y'\ :sub:`20` + + - Cb\ :sub:`20` + + - Y'\ :sub:`21` + + - Cr\ :sub:`20` + + - Y'\ :sub:`22` + + - Cb\ :sub:`21` + + - Y'\ :sub:`23` + + - Cr\ :sub:`21` + + - .. row 4 + + - start + 24: + + - Y'\ :sub:`30` + + - Cb\ :sub:`30` + + - Y'\ :sub:`31` + + - Cr\ :sub:`30` + + - Y'\ :sub:`32` + + - Cb\ :sub:`31` + + - Y'\ :sub:`33` + + - Cr\ :sub:`31` + + +**Color Sample Location..** + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - C + + - Y + + - + - Y + + - C + + - Y + + - .. row 3 + + - 1 + + - Y + + - C + + - Y + + - + - Y + + - C + + - Y + + - .. row 4 + + - 2 + + - Y + + - C + + - Y + + - + - Y + + - C + + - Y + + - .. row 5 + + - 3 + + - Y + + - C + + - Y + + - + - Y + + - C + + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-yvyu.rst b/Documentation/media/uapi/v4l/pixfmt-yvyu.rst new file mode 100644 index 000000000000..e466052b68b2 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-yvyu.rst @@ -0,0 +1,195 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-YVYU: + +************************** +V4L2_PIX_FMT_YVYU ('YVYU') +************************** + +*man V4L2_PIX_FMT_YVYU(2)* + +Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in +memory + + +Description +=========== + +In this format each four bytes is two pixels. Each four bytes is two +Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr +belong to both pixels. As you can see, the Cr and Cb components have +half the horizontal resolution of the Y component. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Y'\ :sub:`00` + + - Cr\ :sub:`00` + + - Y'\ :sub:`01` + + - Cb\ :sub:`00` + + - Y'\ :sub:`02` + + - Cr\ :sub:`01` + + - Y'\ :sub:`03` + + - Cb\ :sub:`01` + + - .. row 2 + + - start + 8: + + - Y'\ :sub:`10` + + - Cr\ :sub:`10` + + - Y'\ :sub:`11` + + - Cb\ :sub:`10` + + - Y'\ :sub:`12` + + - Cr\ :sub:`11` + + - Y'\ :sub:`13` + + - Cb\ :sub:`11` + + - .. row 3 + + - start + 16: + + - Y'\ :sub:`20` + + - Cr\ :sub:`20` + + - Y'\ :sub:`21` + + - Cb\ :sub:`20` + + - Y'\ :sub:`22` + + - Cr\ :sub:`21` + + - Y'\ :sub:`23` + + - Cb\ :sub:`21` + + - .. row 4 + + - start + 24: + + - Y'\ :sub:`30` + + - Cr\ :sub:`30` + + - Y'\ :sub:`31` + + - Cb\ :sub:`30` + + - Y'\ :sub:`32` + + - Cr\ :sub:`31` + + - Y'\ :sub:`33` + + - Cb\ :sub:`31` + + +**Color Sample Location..** + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - + - 0 + + - + - 1 + + - 2 + + - + - 3 + + - .. row 2 + + - 0 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 3 + + - 1 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 4 + + - 2 + + - Y + + - C + + - Y + + - Y + + - C + + - Y + + - .. row 5 + + - 3 + + - Y + + - C + + - Y + + - Y + + - C + + - Y diff --git a/Documentation/media/uapi/v4l/pixfmt-z16.rst b/Documentation/media/uapi/v4l/pixfmt-z16.rst new file mode 100644 index 000000000000..c5cce2db78b6 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-z16.rst @@ -0,0 +1,111 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-Z16: + +************************* +V4L2_PIX_FMT_Z16 ('Z16 ') +************************* + +*man V4L2_PIX_FMT_Z16(2)* + +Interleaved grey-scale image, e.g. from a stereo-pair + + +Description +=========== + +This is a 16-bit format, representing depth data. Each pixel is a +distance to the respective point in the image coordinates. Distance unit +can vary and has to be negotiated with the device separately. Each pixel +is stored in a 16-bit word in the little endian byte order. + +**Byte Order.** +Each cell is one byte. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 2 1 1 1 1 1 1 1 1 + + + - .. row 1 + + - start + 0: + + - Z\ :sub:`00low` + + - Z\ :sub:`00high` + + - Z\ :sub:`01low` + + - Z\ :sub:`01high` + + - Z\ :sub:`02low` + + - Z\ :sub:`02high` + + - Z\ :sub:`03low` + + - Z\ :sub:`03high` + + - .. row 2 + + - start + 8: + + - Z\ :sub:`10low` + + - Z\ :sub:`10high` + + - Z\ :sub:`11low` + + - Z\ :sub:`11high` + + - Z\ :sub:`12low` + + - Z\ :sub:`12high` + + - Z\ :sub:`13low` + + - Z\ :sub:`13high` + + - .. row 3 + + - start + 16: + + - Z\ :sub:`20low` + + - Z\ :sub:`20high` + + - Z\ :sub:`21low` + + - Z\ :sub:`21high` + + - Z\ :sub:`22low` + + - Z\ :sub:`22high` + + - Z\ :sub:`23low` + + - Z\ :sub:`23high` + + - .. row 4 + + - start + 24: + + - Z\ :sub:`30low` + + - Z\ :sub:`30high` + + - Z\ :sub:`31low` + + - Z\ :sub:`31high` + + - Z\ :sub:`32low` + + - Z\ :sub:`32high` + + - Z\ :sub:`33low` + + - Z\ :sub:`33high` diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst new file mode 100644 index 000000000000..81222a99f7ce --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt.rst @@ -0,0 +1,35 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _pixfmt: + +############# +Image Formats +############# +The V4L2 API was primarily designed for devices exchanging image data +with applications. The :ref:`struct v4l2_pix_format <v4l2-pix-format>` and +:ref:`struct v4l2_pix_format_mplane <v4l2-pix-format-mplane>` structures define the +format and layout of an image in memory. The former is used with the +single-planar API, while the latter is used with the multi-planar +version (see :ref:`planar-apis`). Image formats are negotiated with +the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. (The explanations here +focus on video capturing and output, for overlay frame buffer formats +see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.) + + +.. toctree:: + :maxdepth: 1 + + pixfmt-002 + pixfmt-003 + pixfmt-004 + colorspaces + pixfmt-006 + pixfmt-007 + pixfmt-008 + pixfmt-indexed + pixfmt-rgb + yuv-formats + depth-formats + pixfmt-013 + sdr-formats + pixfmt-reserved diff --git a/Documentation/media/uapi/v4l/planar-apis.rst b/Documentation/media/uapi/v4l/planar-apis.rst new file mode 100644 index 000000000000..5fe2e1188230 --- /dev/null +++ b/Documentation/media/uapi/v4l/planar-apis.rst @@ -0,0 +1,61 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _planar-apis: + +***************************** +Single- and multi-planar APIs +***************************** + +Some devices require data for each input or output video frame to be +placed in discontiguous memory buffers. In such cases, one video frame +has to be addressed using more than one memory address, i.e. one pointer +per "plane". A plane is a sub-buffer of the current frame. For examples +of such formats see :ref:`pixfmt`. + +Initially, V4L2 API did not support multi-planar buffers and a set of +extensions has been introduced to handle them. Those extensions +constitute what is being referred to as the "multi-planar API". + +Some of the V4L2 API calls and structures are interpreted differently, +depending on whether single- or multi-planar API is being used. An +application can choose whether to use one or the other by passing a +corresponding buffer type to its ioctl calls. Multi-planar versions of +buffer types are suffixed with an ``_MPLANE`` string. For a list of +available multi-planar buffer types see enum +:ref:`v4l2_buf_type <v4l2-buf-type>`. + + +Multi-planar formats +==================== + +Multi-planar API introduces new multi-planar formats. Those formats use +a separate set of FourCC codes. It is important to distinguish between +the multi-planar API and a multi-planar format. Multi-planar API calls +can handle all single-planar formats as well (as long as they are passed +in multi-planar API structures), while the single-planar API cannot +handle multi-planar formats. + + +Calls that distinguish between single and multi-planar APIs +=========================================================== + +:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` + Two additional multi-planar capabilities are added. They can be set + together with non-multi-planar ones for devices that handle both + single- and multi-planar formats. + +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` + New structures for describing multi-planar formats are added: struct + :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and + struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`. + Drivers may define new multi-planar formats, which have distinct + FourCC codes from the existing single-planar ones. + +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` + A new struct :ref:`v4l2_plane <v4l2-plane>` structure for + describing planes is added. Arrays of this structure are passed in + the new ``m.planes`` field of struct + :ref:`v4l2_buffer <v4l2-buffer>`. + +:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` + Will allocate multi-planar buffers as requested. diff --git a/Documentation/media/uapi/v4l/querycap.rst b/Documentation/media/uapi/v4l/querycap.rst new file mode 100644 index 000000000000..c19cce7a816f --- /dev/null +++ b/Documentation/media/uapi/v4l/querycap.rst @@ -0,0 +1,34 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _querycap: + +********************* +Querying Capabilities +********************* + +Because V4L2 covers a wide variety of devices not all aspects of the API +are equally applicable to all types of devices. Furthermore devices of +the same type have different capabilities and this specification permits +the omission of a few complicated and less important parts of the API. + +The :ref:`VIDIOC_QUERYCAP` ioctl is available to +check if the kernel device is compatible with this specification, and to +query the :ref:`functions <devices>` and :ref:`I/O methods <io>` +supported by the device. + +Starting with kernel version 3.1, :ref:`VIDIOC_QUERYCAP` +will return the V4L2 API version used by the driver, with generally +matches the Kernel version. There's no need of using +:ref:`VIDIOC_QUERYCAP` to check if a specific ioctl +is supported, the V4L2 core now returns ``ENOTTY`` if a driver doesn't +provide support for an ioctl. + +Other features can be queried by calling the respective ioctl, for +example :ref:`VIDIOC_ENUMINPUT` to learn about the +number, types and names of video connectors on the device. Although +abstraction is a major objective of this API, the +:ref:`VIDIOC_QUERYCAP` ioctl also allows driver +specific applications to reliably identify the driver. + +All V4L2 drivers must support :ref:`VIDIOC_QUERYCAP`. +Applications should always call this ioctl after opening the device. diff --git a/Documentation/media/uapi/v4l/rw.rst b/Documentation/media/uapi/v4l/rw.rst new file mode 100644 index 000000000000..66ba54648c45 --- /dev/null +++ b/Documentation/media/uapi/v4l/rw.rst @@ -0,0 +1,47 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _rw: + +********** +Read/Write +********** + +Input and output devices support the :ref:`read() <func-read>` and +:ref:`write() <func-write>` function, respectively, when the +``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl is set. + +Drivers may need the CPU to copy the data, but they may also support DMA +to or from user memory, so this I/O method is not necessarily less +efficient than other methods merely exchanging buffer pointers. It is +considered inferior though because no meta-information like frame +counters or timestamps are passed. This information is necessary to +recognize frame dropping and to synchronize with other data streams. +However this is also the simplest I/O method, requiring little or no +setup to exchange data. It permits command line stunts like this (the +vidctrl tool is fictitious): + + +.. code-block:: none + + $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288 + $ dd if=/dev/video of=myimage.422 bs=202752 count=1 + +To read from the device applications use the :ref:`read() <func-read>` +function, to write the :ref:`write() <func-write>` function. Drivers +must implement one I/O method if they exchange data with applications, +but it need not be this. [1]_ When reading or writing is supported, the +driver must also support the :ref:`select() <func-select>` and +:ref:`poll() <func-poll>` function. [2]_ + +.. [1] + It would be desirable if applications could depend on drivers + supporting all I/O interfaces, but as much as the complex memory + mapping I/O can be inadequate for some devices we have no reason to + require this interface, which is most useful for simple applications + capturing still images. + +.. [2] + At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are + the same, and :ref:`select() <func-select>` is too important to be optional. diff --git a/Documentation/media/uapi/v4l/sdr-formats.rst b/Documentation/media/uapi/v4l/sdr-formats.rst new file mode 100644 index 000000000000..f863c08f1add --- /dev/null +++ b/Documentation/media/uapi/v4l/sdr-formats.rst @@ -0,0 +1,19 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _sdr-formats: + +*********** +SDR Formats +*********** + +These formats are used for :ref:`SDR <sdr>` interface only. + + +.. toctree:: + :maxdepth: 1 + + pixfmt-sdr-cu08 + pixfmt-sdr-cu16le + pixfmt-sdr-cs08 + pixfmt-sdr-cs14le + pixfmt-sdr-ru12le diff --git a/Documentation/media/uapi/v4l/selection-api-002.rst b/Documentation/media/uapi/v4l/selection-api-002.rst new file mode 100644 index 000000000000..09ca93f91bf7 --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api-002.rst @@ -0,0 +1,28 @@ +.. -*- coding: utf-8; mode: rst -*- + +************ +Introduction +************ + +Some video capture devices can sample a subsection of a picture and +shrink or enlarge it to an image of arbitrary size. Next, the devices +can insert the image into larger one. Some video output devices can crop +part of an input image, scale it up or down and insert it at an +arbitrary scan line and horizontal offset into a video signal. We call +these abilities cropping, scaling and composing. + +On a video *capture* device the source is a video signal, and the +cropping target determine the area actually sampled. The sink is an +image stored in a memory buffer. The composing area specifies which part +of the buffer is actually written to by the hardware. + +On a video *output* device the source is an image in a memory buffer, +and the cropping target is a part of an image to be shown on a display. +The sink is the display or the graphics screen. The application may +select the part of display where the image should be displayed. The size +and position of such a window is controlled by the compose target. + +Rectangles for all cropping and composing targets are defined even if +the device does supports neither cropping nor composing. Their size and +position will be fixed in such a case. If the device does not support +scaling then the cropping and composing rectangles have the same size. diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-003.rst new file mode 100644 index 000000000000..15cb3b79f12c --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api-003.rst @@ -0,0 +1,20 @@ +.. -*- coding: utf-8; mode: rst -*- + +***************** +Selection targets +***************** + + +.. _sel-targets-capture: + +.. figure:: selection-api-003_files/selection.* + :alt: selection.png + :align: center + + Cropping and composing targets + + Targets used by a cropping, composing and scaling process + + + +See :ref:`v4l2-selection-targets` for more information. diff --git a/Documentation/media/uapi/v4l/selection-api-003_files/selection.png b/Documentation/media/uapi/v4l/selection-api-003_files/selection.png Binary files differnew file mode 100644 index 000000000000..bfc523eae570 --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api-003_files/selection.png diff --git a/Documentation/media/uapi/v4l/selection-api-004.rst b/Documentation/media/uapi/v4l/selection-api-004.rst new file mode 100644 index 000000000000..d782cd5b2117 --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api-004.rst @@ -0,0 +1,137 @@ +.. -*- coding: utf-8; mode: rst -*- + +************* +Configuration +************* + +Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to +select an area in a video signal or a buffer, and to query for default +settings and hardware limits. + +Video hardware can have various cropping, composing and scaling +limitations. It may only scale up or down, support only discrete scaling +factors, or have different scaling abilities in the horizontal and +vertical directions. Also it may not support scaling at all. At the same +time the cropping/composing rectangles may have to be aligned, and both +the source and the sink may have arbitrary upper and lower size limits. +Therefore, as usual, drivers are expected to adjust the requested +parameters and return the actual values selected. An application can +control the rounding behaviour using +:ref:`constraint flags <v4l2-selection-flags>`. + + +Configuration of video capture +============================== + +See figure :ref:`sel-targets-capture` for examples of the selection +targets available for a video capture device. It is recommended to +configure the cropping targets before to the composing targets. + +The range of coordinates of the top left corner, width and height of +areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS`` +target. It is recommended for the driver developers to put the top/left +corner at position ``(0,0)``. The rectangle's coordinates are expressed +in pixels. + +The top left corner, width and height of the source rectangle, that is +the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target. +It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The +active cropping area must lie completely inside the capture boundaries. +The driver may further adjust the requested size and/or position +according to hardware limitations. + +Each capture device has a default source rectangle, given by the +``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the +driver writer considers the complete picture. Drivers shall set the +active crop rectangle to the default when the driver is first loaded, +but not later. + +The composing targets refer to a memory buffer. The limits of composing +coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All +coordinates are expressed in pixels. The rectangle's top/left corner +must be located at position ``(0,0)``. The width and height are equal to +the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. + +The part of a buffer into which the image is inserted by the hardware is +controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's +coordinates are also expressed in the same coordinate system as the +bounds rectangle. The composing rectangle must lie completely inside +bounds rectangle. The driver must adjust the composing rectangle to fit +to the bounding limits. Moreover, the driver can perform other +adjustments according to hardware limitations. The application can +control rounding behaviour using +:ref:`constraint flags <v4l2-selection-flags>`. + +For capture devices the default composing rectangle is queried using +``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding +rectangle. + +The part of a buffer that is modified by the hardware is given by +``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using +``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware +during insertion process. All pixels outside this rectangle *must not* +be changed by the hardware. The content of pixels that lie inside the +padded area but outside active area is undefined. The application can +use the padded and active rectangles to detect where the rubbish pixels +are located and remove them if needed. + + +Configuration of video output +============================= + +For output devices targets and ioctls are used similarly to the video +capture case. The *composing* rectangle refers to the insertion of an +image into a video signal. The cropping rectangles refer to a memory +buffer. It is recommended to configure the composing targets before to +the cropping targets. + +The cropping targets refer to the memory buffer that contains an image +to be inserted into a video signal or graphical screen. The limits of +cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``. +All coordinates are expressed in pixels. The top/left corner is always +point ``(0,0)``. The width and height is equal to the image size +specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. + +The top left corner, width and height of the source rectangle, that is +the area from which image date are processed by the hardware, is given +by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the +same coordinate system as the bounds rectangle. The active cropping area +must lie completely inside the crop boundaries and the driver may +further adjust the requested size and/or position according to hardware +limitations. + +For output devices the default cropping rectangle is queried using +``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding +rectangle. + +The part of a video signal or graphics display where the image is +inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE`` +target. The rectangle's coordinates are expressed in pixels. The +composing rectangle must lie completely inside the bounds rectangle. The +driver must adjust the area to fit to the bounding limits. Moreover, the +driver can perform other adjustments according to hardware limitations. + +The device has a default composing rectangle, given by the +``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what +the driver writer considers the complete picture. It is recommended for +the driver developers to put the top/left corner at position ``(0,0)``. +Drivers shall set the active composing rectangle to the default one when +the driver is first loaded. + +The devices may introduce additional content to video signal other than +an image from memory buffers. It includes borders around an image. +However, such a padded area is driver-dependent feature not covered by +this document. Driver developers are encouraged to keep padded rectangle +equal to active one. The padded target is accessed by the +``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels +from the ``V4L2_SEL_TGT_COMPOSE`` target. + + +Scaling control +=============== + +An application can detect if scaling is performed by comparing the width +and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and +``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the +scaling is applied. The application can compute the scaling ratios using +these values. diff --git a/Documentation/media/uapi/v4l/selection-api-005.rst b/Documentation/media/uapi/v4l/selection-api-005.rst new file mode 100644 index 000000000000..94731a13efdb --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api-005.rst @@ -0,0 +1,34 @@ +.. -*- coding: utf-8; mode: rst -*- + +******************************** +Comparison with old cropping API +******************************** + +The selection API was introduced to cope with deficiencies of previous +:ref:`API <crop>`, that was designed to control simple capture +devices. Later the cropping API was adopted by video output drivers. The +ioctls are used to select a part of the display were the video signal is +inserted. It should be considered as an API abuse because the described +operation is actually the composing. The selection API makes a clear +distinction between composing and cropping operations by setting the +appropriate targets. The V4L2 API lacks any support for composing to and +cropping from an image inside a memory buffer. The application could +configure a capture device to fill only a part of an image by abusing +V4L2 API. Cropping a smaller image from a larger one is achieved by +setting the field ``bytesperline`` at struct +:ref:`v4l2_pix_format <v4l2-pix-format>`. +Introducing an image offsets could be done by modifying field ``m_userptr`` +at struct +:ref:`v4l2_buffer <v4l2-buffer>` before calling +:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not +portable (endianness), and do not work for macroblock and Bayer formats +and mmap buffers. The selection API deals with configuration of buffer +cropping/composing in a clear, intuitive and portable way. Next, with +the selection API the concepts of the padded target and constraints +flags are introduced. Finally, struct :ref:`v4l2_crop <v4l2-crop>` +and struct :ref:`v4l2_cropcap <v4l2-cropcap>` have no reserved +fields. Therefore there is no way to extend their functionality. The new +struct :ref:`v4l2_selection <v4l2-selection>` provides a lot of place +for future extensions. Driver developers are encouraged to implement +only selection API. The former cropping API would be simulated using the +new one. diff --git a/Documentation/media/uapi/v4l/selection-api-006.rst b/Documentation/media/uapi/v4l/selection-api-006.rst new file mode 100644 index 000000000000..b2ac12f2e3d4 --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api-006.rst @@ -0,0 +1,81 @@ +.. -*- coding: utf-8; mode: rst -*- + +******** +Examples +******** + +(A video capture device is assumed; change +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to +``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area) + + +.. code-block:: c + :caption: Example 1.15. Resetting the cropping parameters + + struct v4l2_selection sel = { + .type = V4L2_BUF_TYPE_VIDEO_CAPTURE, + .target = V4L2_SEL_TGT_CROP_DEFAULT, + }; + ret = ioctl(fd, VIDIOC_G_SELECTION, &sel); + if (ret) + exit(-1); + sel.target = V4L2_SEL_TGT_CROP; + ret = ioctl(fd, VIDIOC_S_SELECTION, &sel); + if (ret) + exit(-1); + +Setting a composing area on output of size of *at most* half of limit +placed at a center of a display. + + +.. code-block:: c + :caption: Example 1.16. Simple downscaling + + struct v4l2_selection sel = { + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, + .target = V4L2_SEL_TGT_COMPOSE_BOUNDS, + }; + struct v4l2_rect r; + + ret = ioctl(fd, VIDIOC_G_SELECTION, &sel); + if (ret) + exit(-1); + /* setting smaller compose rectangle */ + r.width = sel.r.width / 2; + r.height = sel.r.height / 2; + r.left = sel.r.width / 4; + r.top = sel.r.height / 4; + sel.r = r; + sel.target = V4L2_SEL_TGT_COMPOSE; + sel.flags = V4L2_SEL_FLAG_LE; + ret = ioctl(fd, VIDIOC_S_SELECTION, &sel); + if (ret) + exit(-1); + +A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` +for other devices + + +.. code-block:: c + :caption: Example 1.17. Querying for scaling factors + + struct v4l2_selection compose = { + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, + .target = V4L2_SEL_TGT_COMPOSE, + }; + struct v4l2_selection crop = { + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, + .target = V4L2_SEL_TGT_CROP, + }; + double hscale, vscale; + + ret = ioctl(fd, VIDIOC_G_SELECTION, &compose); + if (ret) + exit(-1); + ret = ioctl(fd, VIDIOC_G_SELECTION, &crop); + if (ret) + exit(-1); + + /* computing scaling factors */ + hscale = (double)compose.r.width / crop.r.width; + vscale = (double)compose.r.height / crop.r.height; diff --git a/Documentation/media/uapi/v4l/selection-api.rst b/Documentation/media/uapi/v4l/selection-api.rst new file mode 100644 index 000000000000..81ea52d785b9 --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api.rst @@ -0,0 +1,16 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _selection-api: + +API for cropping, composing and scaling +======================================= + + +.. toctree:: + :maxdepth: 1 + + selection-api-002 + selection-api-003 + selection-api-004 + selection-api-005 + selection-api-006 diff --git a/Documentation/media/uapi/v4l/selections-common.rst b/Documentation/media/uapi/v4l/selections-common.rst new file mode 100644 index 000000000000..69dbce4e6e47 --- /dev/null +++ b/Documentation/media/uapi/v4l/selections-common.rst @@ -0,0 +1,23 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-selections-common: + +Common selection definitions +============================ + +While the :ref:`V4L2 selection API <selection-api>` and +:ref:`V4L2 subdev selection APIs <v4l2-subdev-selections>` are very +similar, there's one fundamental difference between the two. On +sub-device API, the selection rectangle refers to the media bus format, +and is bound to a sub-device's pad. On the V4L2 interface the selection +rectangles refer to the in-memory pixel format. + +This section defines the common definitions of the selection interfaces +on the two APIs. + + +.. toctree:: + :maxdepth: 1 + + v4l2-selection-targets + v4l2-selection-flags diff --git a/Documentation/media/uapi/v4l/standard.rst b/Documentation/media/uapi/v4l/standard.rst new file mode 100644 index 000000000000..538588eef317 --- /dev/null +++ b/Documentation/media/uapi/v4l/standard.rst @@ -0,0 +1,179 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _standard: + +*************** +Video Standards +*************** + +Video devices typically support one or more different video standards or +variations of standards. Each video input and output may support another +set of standards. This set is reported by the ``std`` field of struct +:ref:`v4l2_input <v4l2-input>` and struct +:ref:`v4l2_output <v4l2-output>` returned by the +:ref:`VIDIOC_ENUMINPUT` and +:ref:`VIDIOC_ENUMOUTPUT` ioctls, respectively. + +V4L2 defines one bit for each analog video standard currently in use +worldwide, and sets aside bits for driver defined standards, e. g. +hybrid standards to watch NTSC video tapes on PAL TVs and vice versa. +Applications can use the predefined bits to select a particular +standard, although presenting the user a menu of supported standards is +preferred. To enumerate and query the attributes of the supported +standards applications use the :ref:`VIDIOC_ENUMSTD` +ioctl. + +Many of the defined standards are actually just variations of a few +major standards. The hardware may in fact not distinguish between them, +or do so internal and switch automatically. Therefore enumerated +standards also contain sets of one or more standard bits. + +Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL +signals. The first enumerated standard is a set of B and G/PAL, switched +automatically depending on the selected radio frequency in UHF or VHF +band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a +Composite input may collapse standards, enumerating "PAL-B/G/H/I", +"NTSC-M" and "SECAM-D/K". [1]_ + +To query and select the standard used by the current video input or +output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and +:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The +*received* standard can be sensed with the +:ref:`VIDIOC_QUERYSTD` ioctl. Note that the +parameter of all these ioctls is a pointer to a +:ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an +index into the standard enumeration. Drivers must implement all video +standard ioctls when the device has one or more video inputs or outputs. + +Special rules apply to devices such as USB cameras where the notion of +video standards makes little sense. More generally for any capture or +output device which is: + +- incapable of capturing fields or frames at the nominal rate of the + video standard, or + +- that does not support the video standard formats at all. + +Here the driver shall set the ``std`` field of struct +:ref:`v4l2_input <v4l2-input>` and struct +:ref:`v4l2_output <v4l2-output>` to zero and the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`, +:ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls +shall return the ``ENOTTY`` error code or the ``EINVAL`` error code. + +Applications can make use of the :ref:`input-capabilities` and +:ref:`output-capabilities` flags to determine whether the video +standard ioctls can be used with the given input or output. + + +.. code-block:: c + :caption: Example 1.5. Information about the current video standard + + v4l2_std_id std_id; + struct v4l2_standard standard; + + if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) { + /* Note when VIDIOC_ENUMSTD always returns ENOTTY this + is no video device or it falls under the USB exception, + and VIDIOC_G_STD returning ENOTTY is no error. */ + + perror("VIDIOC_G_STD"); + exit(EXIT_FAILURE); + } + + memset(&standard, 0, sizeof(standard)); + standard.index = 0; + + while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) { + if (standard.id & std_id) { + printf("Current video standard: %s\\n", standard.name); + exit(EXIT_SUCCESS); + } + + standard.index++; + } + + /* EINVAL indicates the end of the enumeration, which cannot be + empty unless this device falls under the USB exception. */ + + if (errno == EINVAL || standard.index == 0) { + perror("VIDIOC_ENUMSTD"); + exit(EXIT_FAILURE); + } + + +.. code-block:: c + :caption: Example 1.6. Listing the video standards supported by the current input + + struct v4l2_input input; + struct v4l2_standard standard; + + memset(&input, 0, sizeof(input)); + + if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) { + perror("VIDIOC_G_INPUT"); + exit(EXIT_FAILURE); + } + + if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) { + perror("VIDIOC_ENUM_INPUT"); + exit(EXIT_FAILURE); + } + + printf("Current input %s supports:\\n", input.name); + + memset(&standard, 0, sizeof(standard)); + standard.index = 0; + + while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) { + if (standard.id & input.std) + printf("%s\\n", standard.name); + + standard.index++; + } + + /* EINVAL indicates the end of the enumeration, which cannot be + empty unless this device falls under the USB exception. */ + + if (errno != EINVAL || standard.index == 0) { + perror("VIDIOC_ENUMSTD"); + exit(EXIT_FAILURE); + } + + +.. code-block:: c + :caption: Example 1.7. Selecting a new video standard + + struct v4l2_input input; + v4l2_std_id std_id; + + memset(&input, 0, sizeof(input)); + + if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) { + perror("VIDIOC_G_INPUT"); + exit(EXIT_FAILURE); + } + + if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) { + perror("VIDIOC_ENUM_INPUT"); + exit(EXIT_FAILURE); + } + + if (0 == (input.std & V4L2_STD_PAL_BG)) { + fprintf(stderr, "Oops. B/G PAL is not supported.\\n"); + exit(EXIT_FAILURE); + } + + /* Note this is also supposed to work when only B + or G/PAL is supported. */ + + std_id = V4L2_STD_PAL_BG; + + if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) { + perror("VIDIOC_S_STD"); + exit(EXIT_FAILURE); + } + +.. [1] + Some users are already confused by technical terms PAL, NTSC and + SECAM. There is no point asking them to distinguish between B, G, D, + or K when the software or hardware can do that automatically. diff --git a/Documentation/media/uapi/v4l/streaming-par.rst b/Documentation/media/uapi/v4l/streaming-par.rst new file mode 100644 index 000000000000..b07b0f0b35d4 --- /dev/null +++ b/Documentation/media/uapi/v4l/streaming-par.rst @@ -0,0 +1,33 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _streaming-par: + +******************** +Streaming Parameters +******************** + +Streaming parameters are intended to optimize the video capture process +as well as I/O. Presently applications can request a high quality +capture mode with the :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl. + +The current video standard determines a nominal number of frames per +second. If less than this number of frames is to be captured or output, +applications can request frame skipping or duplicating on the driver +side. This is especially useful when using the +:ref:`read() <func-read>` or :ref:`write() <func-write>`, which are +not augmented by timestamps or sequence counters, and to avoid +unnecessary data copying. + +Finally these ioctls can be used to determine the number of buffers used +internally by a driver in read/write mode. For implications see the +section discussing the :ref:`read() <func-read>` function. + +To get and set the streaming parameters applications call the +:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and +:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take +a pointer to a struct :ref:`v4l2_streamparm <v4l2-streamparm>`, which +contains a union holding separate parameters for input and output +devices. + +These ioctls are optional, drivers need not implement them. If so, they +return the ``EINVAL`` error code. diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst new file mode 100644 index 000000000000..6dbb27b09c34 --- /dev/null +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -0,0 +1,11688 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-mbus-format: + +Media Bus Formats +================= + + +.. _v4l2-mbus-framefmt: + +.. flat-table:: struct v4l2_mbus_framefmt + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``width`` + + - Image width, in pixels. + + - .. row 2 + + - __u32 + + - ``height`` + + - Image height, in pixels. + + - .. row 3 + + - __u32 + + - ``code`` + + - Format code, from enum + :ref:`v4l2_mbus_pixelcode <v4l2-mbus-pixelcode>`. + + - .. row 4 + + - __u32 + + - ``field`` + + - Field order, from enum :ref:`v4l2_field <v4l2-field>`. See + :ref:`field-order` for details. + + - .. row 5 + + - __u32 + + - ``colorspace`` + + - Image colorspace, from enum + :ref:`v4l2_colorspace <v4l2-colorspace>`. See + :ref:`colorspaces` for details. + + - .. row 6 + + - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` + + - ``ycbcr_enc`` + + - 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`. + + - .. row 7 + + - enum :ref:`v4l2_quantization <v4l2-quantization>` + + - ``quantization`` + + - 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`. + + - .. row 8 + + - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>` + + - ``xfer_func`` + + - 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`. + + - .. row 9 + + - __u16 + + - ``reserved``\ [11] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + + +.. _v4l2-mbus-pixelcode: + +Media Bus Pixel Codes +--------------------- + +The media bus pixel codes describe image formats as flowing over +physical busses (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 +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. + + +Packed RGB Formats +^^^^^^^^^^^^^^^^^^ + +Those formats transfer pixel data as red, green and blue components. The +format code is made of the following information. + +- The red, green and blue components order code, as encoded in a pixel + sample. Possible values are RGB and BGR. + +- The number of bits per component, for each component. The values can + be different for all components. Common values are 555 and 565. + +- The number of bus samples per pixel. Pixels that are wider than the + bus width must be transferred in multiple samples. Common values are + 1 and 2. + +- The bus width. + +- For formats where the total number of bits per pixel is smaller than + the number of bus samples per pixel times the bus width, a padding + value stating if the bytes are padded in their most high order bits + (PADHI) or low order bits (PADLO). A "C" prefix is used for + component-wise padding in the most high order bits (CPADHI) or low + order bits (CPADLO) of each separate component. + +- For formats where the number of bus samples per pixel is larger than + 1, an endianness value stating if the pixel is transferred MSB first + (BE) or LSB first (LE). + +For instance, a format where pixels are encoded as 5-bits red, 5-bits +green and 5-bit blue values padded on the high bit, transferred as 2 +8-bit samples per pixel with the most significant bits (padding, red and +half of the green value) transferred first will be named +``MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE``. + +The following tables list existing packed RGB formats. + + +.. _v4l2-mbus-pixelcode-rgb: + +.. flat-table:: RGB formats + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - :cspan:`31` Data organization + + - .. row 2 + + - + - + - Bit + + - 31 + + - 30 + + - 29 + + - 28 + + - 27 + + - 26 + + - 25 + + - 24 + + - 23 + + - 22 + + - 21 + + - 20 + + - 19 + + - 18 + + - 17 + + - 16 + + - 15 + + - 14 + + - 13 + + - 12 + + - 11 + + - 10 + + - 9 + + - 8 + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _MEDIA-BUS-FMT-RGB444-1X12: + + - MEDIA_BUS_FMT_RGB444_1X12 + + - 0x1016 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE: + + - MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE + + - 0x1001 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 0 + + - 0 + + - 0 + + - 0 + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - .. row 5 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE: + + - MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE + + - 0x1002 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. row 7 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 0 + + - 0 + + - 0 + + - 0 + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - .. _MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE: + + - MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE + + - 0x1003 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 0 + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - .. row 9 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE: + + - MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE + + - 0x1004 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. row 11 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 0 + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - .. _MEDIA-BUS-FMT-RGB565-1X16: + + - MEDIA_BUS_FMT_RGB565_1X16 + + - 0x1017 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-BGR565-2X8-BE: + + - MEDIA_BUS_FMT_BGR565_2X8_BE + + - 0x1005 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - .. row 14 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - .. _MEDIA-BUS-FMT-BGR565-2X8-LE: + + - MEDIA_BUS_FMT_BGR565_2X8_LE + + - 0x1006 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - .. row 16 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - .. _MEDIA-BUS-FMT-RGB565-2X8-BE: + + - MEDIA_BUS_FMT_RGB565_2X8_BE + + - 0x1007 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - .. row 18 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-RGB565-2X8-LE: + + - MEDIA_BUS_FMT_RGB565_2X8_LE + + - 0x1008 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. row 20 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - .. _MEDIA-BUS-FMT-RGB666-1X18: + + - MEDIA_BUS_FMT_RGB666_1X18 + + - 0x1009 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - r\ :sub:`5` + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-RBG888-1X24: + + - MEDIA_BUS_FMT_RBG888_1X24 + + - 0x100e + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - r\ :sub:`7` + + - r\ :sub:`6` + + - r\ :sub:`5` + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :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` + + - .. _MEDIA-BUS-FMT-RGB666-1X24_CPADHI: + + - MEDIA_BUS_FMT_RGB666_1X24_CPADHI + + - 0x1015 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 0 + + - 0 + + - r\ :sub:`5` + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + - 0 + + - 0 + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - 0 + + - 0 + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-BGR888-1X24: + + - MEDIA_BUS_FMT_BGR888_1X24 + + - 0x1013 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 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 + + - 0x1014 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 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` + + - 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-RGB888-1X24: + + - MEDIA_BUS_FMT_RGB888_1X24 + + - 0x100a + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 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` + + - .. _MEDIA-BUS-FMT-RGB888-2X12-BE: + + - MEDIA_BUS_FMT_RGB888_2X12_BE + + - 0x100b + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 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` + + - .. row 28 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 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` + + - .. _MEDIA-BUS-FMT-RGB888-2X12-LE: + + - MEDIA_BUS_FMT_RGB888_2X12_LE + + - 0x100c + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 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` + + - .. row 30 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - 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` + + - .. _MEDIA-BUS-FMT-ARGB888-1X32: + + - MEDIA_BUS_FMT_ARGB888_1X32 + + - 0x100d + + - + - a\ :sub:`7` + + - a\ :sub:`6` + + - a\ :sub:`5` + + - a\ :sub:`4` + + - a\ :sub:`3` + + - a\ :sub:`2` + + - a\ :sub:`1` + + - a\ :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` + + - 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` + + - .. _MEDIA-BUS-FMT-RGB888-1X32-PADHI: + + - MEDIA_BUS_FMT_RGB888_1X32_PADHI + + - 0x100f + + - + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - 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` + + - 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` + + +On LVDS buses, usually each sample is transferred serialized in seven +time slots per pixel clock, on three (18-bit) or four (24-bit) +differential data pairs at the same time. The remaining bits are used +for control signals as defined by SPWG/PSWG/VESA or JEIDA standards. The +24-bit RGB format serialized in seven time slots on four lanes using +JEIDA defined bit mapping will be named +``MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA``, for example. + + +.. _v4l2-mbus-pixelcode-rgb-lvds: + +.. flat-table:: LVDS RGB formats + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - + - :cspan:`3` Data organization + + - .. row 2 + + - + - + - Timeslot + + - Lane + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _MEDIA-BUS-FMT-RGB666-1X7X3-SPWG: + + - MEDIA_BUS_FMT_RGB666_1X7X3_SPWG + + - 0x1010 + + - 0 + + - + - - + + - d + + - b\ :sub:`1` + + - g\ :sub:`0` + + - .. row 4 + + - + - + - 1 + + - + - - + + - d + + - b\ :sub:`0` + + - r\ :sub:`5` + + - .. row 5 + + - + - + - 2 + + - + - - + + - d + + - g\ :sub:`5` + + - r\ :sub:`4` + + - .. row 6 + + - + - + - 3 + + - + - - + + - b\ :sub:`5` + + - g\ :sub:`4` + + - r\ :sub:`3` + + - .. row 7 + + - + - + - 4 + + - + - - + + - b\ :sub:`4` + + - g\ :sub:`3` + + - r\ :sub:`2` + + - .. row 8 + + - + - + - 5 + + - + - - + + - b\ :sub:`3` + + - g\ :sub:`2` + + - r\ :sub:`1` + + - .. row 9 + + - + - + - 6 + + - + - - + + - b\ :sub:`2` + + - g\ :sub:`1` + + - r\ :sub:`0` + + - .. _MEDIA-BUS-FMT-RGB888-1X7X4-SPWG: + + - MEDIA_BUS_FMT_RGB888_1X7X4_SPWG + + - 0x1011 + + - 0 + + - + - d + + - d + + - b\ :sub:`1` + + - g\ :sub:`0` + + - .. row 11 + + - + - + - 1 + + - + - b\ :sub:`7` + + - d + + - b\ :sub:`0` + + - r\ :sub:`5` + + - .. row 12 + + - + - + - 2 + + - + - b\ :sub:`6` + + - d + + - g\ :sub:`5` + + - r\ :sub:`4` + + - .. row 13 + + - + - + - 3 + + - + - g\ :sub:`7` + + - b\ :sub:`5` + + - g\ :sub:`4` + + - r\ :sub:`3` + + - .. row 14 + + - + - + - 4 + + - + - g\ :sub:`6` + + - b\ :sub:`4` + + - g\ :sub:`3` + + - r\ :sub:`2` + + - .. row 15 + + - + - + - 5 + + - + - r\ :sub:`7` + + - b\ :sub:`3` + + - g\ :sub:`2` + + - r\ :sub:`1` + + - .. row 16 + + - + - + - 6 + + - + - r\ :sub:`6` + + - b\ :sub:`2` + + - g\ :sub:`1` + + - r\ :sub:`0` + + - .. _MEDIA-BUS-FMT-RGB888-1X7X4-JEIDA: + + - MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA + + - 0x1012 + + - 0 + + - + - d + + - d + + - b\ :sub:`3` + + - g\ :sub:`2` + + - .. row 18 + + - + - + - 1 + + - + - b\ :sub:`1` + + - d + + - b\ :sub:`2` + + - r\ :sub:`7` + + - .. row 19 + + - + - + - 2 + + - + - b\ :sub:`0` + + - d + + - g\ :sub:`7` + + - r\ :sub:`6` + + - .. row 20 + + - + - + - 3 + + - + - g\ :sub:`1` + + - b\ :sub:`7` + + - g\ :sub:`6` + + - r\ :sub:`5` + + - .. row 21 + + - + - + - 4 + + - + - g\ :sub:`0` + + - b\ :sub:`6` + + - g\ :sub:`5` + + - r\ :sub:`4` + + - .. row 22 + + - + - + - 5 + + - + - r\ :sub:`1` + + - b\ :sub:`5` + + - g\ :sub:`4` + + - r\ :sub:`3` + + - .. row 23 + + - + - + - 6 + + - + - r\ :sub:`0` + + - b\ :sub:`4` + + - g\ :sub:`3` + + - r\ :sub:`2` + + + +Bayer Formats +^^^^^^^^^^^^^ + +Those formats transfer pixel data as red, green and blue components. The +format code is made of the following information. + +- The red, green and blue components order code, as encoded in a pixel + sample. The possible values are shown in :ref:`bayer-patterns`. + +- The number of bits per pixel component. All components are + transferred on the same number of bits. Common values are 8, 10 and + 12. + +- The compression (optional). If the pixel components are ALAW- or + DPCM-compressed, a mention of the compression scheme and the number + of bits per compressed pixel component. + +- The number of bus samples per pixel. Pixels that are wider than the + bus width must be transferred in multiple samples. Common values are + 1 and 2. + +- The bus width. + +- For formats where the total number of bits per pixel is smaller than + the number of bus samples per pixel times the bus width, a padding + value stating if the bytes are padded in their most high order bits + (PADHI) or low order bits (PADLO). + +- For formats where the number of bus samples per pixel is larger than + 1, an endianness value stating if the pixel is transferred MSB first + (BE) or LSB first (LE). + +For instance, a format with uncompressed 10-bit Bayer components +arranged in a red, green, green, blue pattern transferred as 2 8-bit +samples per pixel with the least significant bits transferred first will +be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``. + + +.. _bayer-patterns: + +.. figure:: subdev-formats_files/bayer.* + :alt: bayer.png + :align: center + + **Figure 4.8 Bayer Patterns** + + + +The following table lists existing packed Bayer formats. The data +organization is given as an example for the first pixel only. + + +.. _v4l2-mbus-pixelcode-bayer: + +.. flat-table:: Bayer Formats + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - :cspan:`11` Data organization + + - .. row 2 + + - + - + - Bit + + - 11 + + - 10 + + - 9 + + - 8 + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _MEDIA-BUS-FMT-SBGGR8-1X8: + + - MEDIA_BUS_FMT_SBGGR8_1X8 + + - 0x3001 + + - + - - + + - - + + - - + + - - + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGBRG8-1X8: + + - MEDIA_BUS_FMT_SGBRG8_1X8 + + - 0x3013 + + - + - - + + - - + + - - + + - - + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGRBG8-1X8: + + - MEDIA_BUS_FMT_SGRBG8_1X8 + + - 0x3002 + + - + - - + + - - + + - - + + - - + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SRGGB8-1X8: + + - MEDIA_BUS_FMT_SRGGB8_1X8 + + - 0x3014 + + - + - - + + - - + + - - + + - - + + - 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-SBGGR10-ALAW8-1X8: + + - MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8 + + - 0x3015 + + - + - - + + - - + + - - + + - - + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8: + + - MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8 + + - 0x3016 + + - + - - + + - - + + - - + + - - + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8: + + - MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8 + + - 0x3017 + + - + - - + + - - + + - - + + - - + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8: + + - MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8 + + - 0x3018 + + - + - - + + - - + + - - + + - - + + - 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-SBGGR10-DPCM8-1X8: + + - MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8 + + - 0x300b + + - + - - + + - - + + - - + + - - + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8: + + - MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8 + + - 0x300c + + - + - - + + - - + + - - + + - - + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8: + + - MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8 + + - 0x3009 + + - + - - + + - - + + - - + + - - + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8: + + - MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8 + + - 0x300d + + - + - - + + - - + + - - + + - - + + - 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-SBGGR10-2X8-PADHI-BE: + + - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE + + - 0x3003 + + - + - - + + - - + + - - + + - - + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - b\ :sub:`9` + + - b\ :sub:`8` + + - .. row 16 + + - + - + - + - - + + - - + + - - + + - - + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE: + + - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE + + - 0x3004 + + - + - - + + - - + + - - + + - - + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. row 18 + + - + - + - + - - + + - - + + - - + + - - + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - b\ :sub:`9` + + - b\ :sub:`8` + + - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE: + + - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE + + - 0x3005 + + - + - - + + - - + + - - + + - - + + - b\ :sub:`9` + + - b\ :sub:`8` + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - .. row 20 + + - + - + - + - - + + - - + + - - + + - - + + - b\ :sub:`1` + + - b\ :sub:`0` + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE: + + - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE + + - 0x3006 + + - + - - + + - - + + - - + + - - + + - b\ :sub:`1` + + - b\ :sub:`0` + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - 0 + + - .. row 22 + + - + - + - + - - + + - - + + - - + + - - + + - b\ :sub:`9` + + - b\ :sub:`8` + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - .. _MEDIA-BUS-FMT-SBGGR10-1X10: + + - MEDIA_BUS_FMT_SBGGR10_1X10 + + - 0x3007 + + - + - - + + - - + + - b\ :sub:`9` + + - b\ :sub:`8` + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGBRG10-1X10: + + - MEDIA_BUS_FMT_SGBRG10_1X10 + + - 0x300e + + - + - - + + - - + + - g\ :sub:`9` + + - g\ :sub:`8` + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGRBG10-1X10: + + - MEDIA_BUS_FMT_SGRBG10_1X10 + + - 0x300a + + - + - - + + - - + + - g\ :sub:`9` + + - g\ :sub:`8` + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SRGGB10-1X10: + + - MEDIA_BUS_FMT_SRGGB10_1X10 + + - 0x300f + + - + - - + + - - + + - r\ :sub:`9` + + - r\ :sub:`8` + + - 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-SBGGR12-1X12: + + - MEDIA_BUS_FMT_SBGGR12_1X12 + + - 0x3008 + + - + - b\ :sub:`11` + + - b\ :sub:`10` + + - b\ :sub:`9` + + - b\ :sub:`8` + + - b\ :sub:`7` + + - b\ :sub:`6` + + - b\ :sub:`5` + + - b\ :sub:`4` + + - b\ :sub:`3` + + - b\ :sub:`2` + + - b\ :sub:`1` + + - b\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGBRG12-1X12: + + - MEDIA_BUS_FMT_SGBRG12_1X12 + + - 0x3010 + + - + - g\ :sub:`11` + + - g\ :sub:`10` + + - g\ :sub:`9` + + - g\ :sub:`8` + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SGRBG12-1X12: + + - MEDIA_BUS_FMT_SGRBG12_1X12 + + - 0x3011 + + - + - g\ :sub:`11` + + - g\ :sub:`10` + + - g\ :sub:`9` + + - g\ :sub:`8` + + - g\ :sub:`7` + + - g\ :sub:`6` + + - g\ :sub:`5` + + - g\ :sub:`4` + + - g\ :sub:`3` + + - g\ :sub:`2` + + - g\ :sub:`1` + + - g\ :sub:`0` + + - .. _MEDIA-BUS-FMT-SRGGB12-1X12: + + - MEDIA_BUS_FMT_SRGGB12_1X12 + + - 0x3012 + + - + - r\ :sub:`11` + + - r\ :sub:`10` + + - r\ :sub:`9` + + - r\ :sub:`8` + + - r\ :sub:`7` + + - r\ :sub:`6` + + - r\ :sub:`5` + + - r\ :sub:`4` + + - r\ :sub:`3` + + - r\ :sub:`2` + + - r\ :sub:`1` + + - r\ :sub:`0` + + + +Packed YUV Formats +^^^^^^^^^^^^^^^^^^ + +Those data formats transfer pixel data as (possibly downsampled) Y, U +and V components. Some formats include dummy bits in some of their +samples and are collectively referred to as "YDYC" (Y-Dummy-Y-Chroma) +formats. One cannot rely on the values of these dummy bits as those are +undefined. + +The format code is made of the following information. + +- The Y, U and V components order code, as transferred on the bus. + Possible values are YUYV, UYVY, YVYU and VYUY for formats with no + dummy bit, and YDYUYDYV, YDYVYDYU, YUYDYVYD and YVYDYUYD for YDYC + formats. + +- The number of bits per pixel component. All components are + transferred on the same number of bits. Common values are 8, 10 and + 12. + +- The number of bus samples per pixel. Pixels that are wider than the + bus width must be transferred in multiple samples. Common values are + 1, 1.5 (encoded as 1_5) and 2. + +- The bus width. When the bus width is larger than the number of bits + per pixel component, several components are packed in a single bus + sample. The components are ordered as specified by the order code, + with components on the left of the code transferred in the high order + bits. Common values are 8 and 16. + +For instance, a format where pixels are encoded as 8-bit YUV values +downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in +the U, Y, V, Y order will be named ``MEDIA_BUS_FMT_UYVY8_2X8``. + +:ref:`v4l2-mbus-pixelcode-yuv8` lists existing packed YUV formats and +describes the organization of each pixel data in each sample. When a +format pattern is split across multiple samples each of the samples in +the pattern is described. + +The role of each bit transferred over the bus is identified by one of +the following codes. + +- y\ :sub:`x` for luma component bit number x + +- u\ :sub:`x` for blue chroma component bit number x + +- v\ :sub:`x` for red chroma component bit number x + +- a\ :sub:`x` for alpha component bit number x + +- - for non-available bits (for positions higher than the bus width) + +- d for dummy bits + + +.. _v4l2-mbus-pixelcode-yuv8: + +.. flat-table:: YUV Formats + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - :cspan:`31` Data organization + + - .. row 2 + + - + - + - Bit + + - 31 + + - 30 + + - 29 + + - 28 + + - 27 + + - 26 + + - 25 + + - 24 + + - 23 + + - 22 + + - 21 + + - 10 + + - 19 + + - 18 + + - 17 + + - 16 + + - 15 + + - 14 + + - 13 + + - 12 + + - 11 + + - 10 + + - 9 + + - 8 + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _MEDIA-BUS-FMT-Y8-1X8: + + - MEDIA_BUS_FMT_Y8_1X8 + + - 0x2001 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-UV8-1X8: + + - MEDIA_BUS_FMT_UV8_1X8 + + - 0x2015 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 5 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-UYVY8-1_5X8: + + - MEDIA_BUS_FMT_UYVY8_1_5X8 + + - 0x2002 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 7 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 8 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 9 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 10 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 11 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-VYUY8-1_5X8: + + - MEDIA_BUS_FMT_VYUY8_1_5X8 + + - 0x2003 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 13 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 14 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 15 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 16 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 17 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YUYV8-1_5X8: + + - MEDIA_BUS_FMT_YUYV8_1_5X8 + + - 0x2004 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 19 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 20 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 21 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 22 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 23 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YVYU8-1_5X8: + + - MEDIA_BUS_FMT_YVYU8_1_5X8 + + - 0x2005 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 25 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 26 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 27 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 28 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 29 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. _MEDIA-BUS-FMT-UYVY8-2X8: + + - MEDIA_BUS_FMT_UYVY8_2X8 + + - 0x2006 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 31 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 32 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 33 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-VYUY8-2X8: + + - MEDIA_BUS_FMT_VYUY8_2X8 + + - 0x2007 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 35 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 36 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 37 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YUYV8-2X8: + + - MEDIA_BUS_FMT_YUYV8_2X8 + + - 0x2008 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 39 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 40 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 41 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YVYU8-2X8: + + - MEDIA_BUS_FMT_YVYU8_2X8 + + - 0x2009 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 43 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 44 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 45 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. _MEDIA-BUS-FMT-Y10-1X10: + + - MEDIA_BUS_FMT_Y10_1X10 + + - 0x200a + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-UYVY10-2X10: + + - MEDIA_BUS_FMT_UYVY10_2X10 + + - 0x2018 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 48 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 49 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 50 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-VYUY10-2X10: + + - MEDIA_BUS_FMT_VYUY10_2X10 + + - 0x2019 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 52 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 53 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 54 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YUYV10-2X10: + + - MEDIA_BUS_FMT_YUYV10_2X10 + + - 0x200b + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 56 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 57 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 58 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YVYU10-2X10: + + - MEDIA_BUS_FMT_YVYU10_2X10 + + - 0x200c + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 60 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 61 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 62 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. _MEDIA-BUS-FMT-Y12-1X12: + + - MEDIA_BUS_FMT_Y12_1X12 + + - 0x2013 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-UYVY12-2X12: + + - MEDIA_BUS_FMT_UYVY12_2X12 + + - 0x201c + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`11` + + - u\ :sub:`10` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 65 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 66 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`11` + + - v\ :sub:`10` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 67 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-VYUY12-2X12: + + - MEDIA_BUS_FMT_VYUY12_2X12 + + - 0x201d + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`11` + + - v\ :sub:`10` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 69 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 70 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`11` + + - u\ :sub:`10` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 71 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YUYV12-2X12: + + - MEDIA_BUS_FMT_YUYV12_2X12 + + - 0x201e + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 73 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`11` + + - u\ :sub:`10` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 74 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 75 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`11` + + - v\ :sub:`10` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YVYU12-2X12: + + - MEDIA_BUS_FMT_YVYU12_2X12 + + - 0x201f + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 77 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`11` + + - v\ :sub:`10` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 78 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 79 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`11` + + - u\ :sub:`10` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. _MEDIA-BUS-FMT-UYVY8-1X16: + + - MEDIA_BUS_FMT_UYVY8_1X16 + + - 0x200f + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :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` + + - .. row 81 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :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` + + - .. _MEDIA-BUS-FMT-VYUY8-1X16: + + - MEDIA_BUS_FMT_VYUY8_1X16 + + - 0x2010 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :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` + + - .. row 83 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :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` + + - .. _MEDIA-BUS-FMT-YUYV8-1X16: + + - MEDIA_BUS_FMT_YUYV8_1X16 + + - 0x2011 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 85 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YVYU8-1X16: + + - MEDIA_BUS_FMT_YVYU8_1X16 + + - 0x2012 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 87 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YDYUYDYV8-1X16: + + - MEDIA_BUS_FMT_YDYUYDYV8_1X16 + + - 0x2014 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - d + + - d + + - d + + - d + + - d + + - d + + - d + + - d + + - .. row 89 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 90 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - d + + - d + + - d + + - d + + - d + + - d + + - d + + - d + + - .. row 91 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-UYVY10-1X20: + + - MEDIA_BUS_FMT_UYVY10_1X20 + + - 0x201a + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 93 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-VYUY10-1X20: + + - MEDIA_BUS_FMT_VYUY10_1X20 + + - 0x201b + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 95 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YUYV10-1X20: + + - MEDIA_BUS_FMT_YUYV10_1X20 + + - 0x200d + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 97 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YVYU10-1X20: + + - MEDIA_BUS_FMT_YVYU10_1X20 + + - 0x200e + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 99 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. _MEDIA-BUS-FMT-VUY8-1X24: + + - MEDIA_BUS_FMT_VUY8_1X24 + + - 0x201a + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :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` + + - .. _MEDIA-BUS-FMT-YUV8-1X24: + + - MEDIA_BUS_FMT_YUV8_1X24 + + - 0x2025 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-UYVY12-1X24: + + - MEDIA_BUS_FMT_UYVY12_1X24 + + - 0x2020 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`11` + + - u\ :sub:`10` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 103 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`11` + + - v\ :sub:`10` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-VYUY12-1X24: + + - MEDIA_BUS_FMT_VYUY12_1X24 + + - 0x2021 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - v\ :sub:`11` + + - v\ :sub:`10` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. row 105 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - u\ :sub:`11` + + - u\ :sub:`10` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YUYV12-1X24: + + - MEDIA_BUS_FMT_YUYV12_1X24 + + - 0x2022 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`11` + + - u\ :sub:`10` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. row 107 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - v\ :sub:`11` + + - v\ :sub:`10` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YVYU12-1X24: + + - MEDIA_BUS_FMT_YVYU12_1X24 + + - 0x2023 + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - v\ :sub:`11` + + - v\ :sub:`10` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. row 109 + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - y\ :sub:`11` + + - y\ :sub:`10` + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`11` + + - u\ :sub:`10` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - .. _MEDIA-BUS-FMT-YUV10-1X30: + + - MEDIA_BUS_FMT_YUV10_1X30 + + - 0x2016 + + - + - - + + - - + + - y\ :sub:`9` + + - y\ :sub:`8` + + - y\ :sub:`7` + + - y\ :sub:`6` + + - y\ :sub:`5` + + - y\ :sub:`4` + + - y\ :sub:`3` + + - y\ :sub:`2` + + - y\ :sub:`1` + + - y\ :sub:`0` + + - u\ :sub:`9` + + - u\ :sub:`8` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - v\ :sub:`9` + + - v\ :sub:`8` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + - .. _MEDIA-BUS-FMT-AYUV8-1X32: + + - MEDIA_BUS_FMT_AYUV8_1X32 + + - 0x2017 + + - + - 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` + + - u\ :sub:`7` + + - u\ :sub:`6` + + - u\ :sub:`5` + + - u\ :sub:`4` + + - u\ :sub:`3` + + - u\ :sub:`2` + + - u\ :sub:`1` + + - u\ :sub:`0` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + + +HSV/HSL Formats +^^^^^^^^^^^^^^^ + +Those formats transfer pixel data as RGB values in a +cylindrical-coordinate system using Hue-Saturation-Value or +Hue-Saturation-Lightness components. The format code is made of the +following information. + +- The hue, saturation, value or lightness and optional alpha components + order code, as encoded in a pixel sample. The only currently + supported value is AHSV. + +- The number of bits per component, for each component. The values can + be different for all components. The only currently supported value + is 8888. + +- The number of bus samples per pixel. Pixels that are wider than the + bus width must be transferred in multiple samples. The only currently + supported value is 1. + +- The bus width. + +- For formats where the total number of bits per pixel is smaller than + the number of bus samples per pixel times the bus width, a padding + value stating if the bytes are padded in their most high order bits + (PADHI) or low order bits (PADLO). + +- For formats where the number of bus samples per pixel is larger than + 1, an endianness value stating if the pixel is transferred MSB first + (BE) or LSB first (LE). + +The following table lists existing HSV/HSL formats. + + +.. _v4l2-mbus-pixelcode-hsv: + +.. flat-table:: HSV/HSL formats + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - + - :cspan:`31` Data organization + + - .. row 2 + + - + - + - Bit + + - 31 + + - 30 + + - 29 + + - 28 + + - 27 + + - 26 + + - 25 + + - 24 + + - 23 + + - 22 + + - 21 + + - 20 + + - 19 + + - 18 + + - 17 + + - 16 + + - 15 + + - 14 + + - 13 + + - 12 + + - 11 + + - 10 + + - 9 + + - 8 + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 + + - .. _MEDIA-BUS-FMT-AHSV8888-1X32: + + - MEDIA_BUS_FMT_AHSV8888_1X32 + + - 0x6001 + + - + - a\ :sub:`7` + + - a\ :sub:`6` + + - a\ :sub:`5` + + - a\ :sub:`4` + + - a\ :sub:`3` + + - a\ :sub:`2` + + - a\ :sub:`1` + + - a\ :sub:`0` + + - h\ :sub:`7` + + - h\ :sub:`6` + + - h\ :sub:`5` + + - h\ :sub:`4` + + - h\ :sub:`3` + + - h\ :sub:`2` + + - h\ :sub:`1` + + - h\ :sub:`0` + + - s\ :sub:`7` + + - s\ :sub:`6` + + - s\ :sub:`5` + + - s\ :sub:`4` + + - s\ :sub:`3` + + - s\ :sub:`2` + + - s\ :sub:`1` + + - s\ :sub:`0` + + - v\ :sub:`7` + + - v\ :sub:`6` + + - v\ :sub:`5` + + - v\ :sub:`4` + + - v\ :sub:`3` + + - v\ :sub:`2` + + - v\ :sub:`1` + + - v\ :sub:`0` + + + +JPEG Compressed Formats +^^^^^^^^^^^^^^^^^^^^^^^ + +Those data formats consist of an ordered sequence of 8-bit bytes +obtained from JPEG compression process. Additionally to the ``_JPEG`` +postfix the format code is made of the following information. + +- The number of bus samples per entropy encoded byte. + +- The bus width. + +For instance, for a JPEG baseline process and an 8-bit bus width the +format will be named ``MEDIA_BUS_FMT_JPEG_1X8``. + +The following table lists existing JPEG compressed formats. + + +.. _v4l2-mbus-pixelcode-jpeg: + +.. flat-table:: JPEG Formats + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - Remarks + + - .. _MEDIA-BUS-FMT-JPEG-1X8: + + - MEDIA_BUS_FMT_JPEG_1X8 + + - 0x4001 + + - Besides of its usage for the parallel bus this format is + recommended for transmission of JPEG data over MIPI CSI bus using + the User Defined 8-bit Data types. + + + +.. _v4l2-mbus-vendor-spec-fmts: + +Vendor and Device Specific Formats +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This section lists complex data formats that are either vendor or device +specific. + +The following table lists the existing vendor and device specific +formats. + + +.. _v4l2-mbus-pixelcode-vendor-specific: + +.. flat-table:: Vendor and device specific formats + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Identifier + + - Code + + - Comments + + - .. _MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8: + + - MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8 + + - 0x5001 + + - Interleaved raw UYVY and JPEG image format with embedded meta-data + used by Samsung S3C73MX camera sensors. diff --git a/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png b/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png Binary files differnew file mode 100644 index 000000000000..9b15fb22e817 --- /dev/null +++ b/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png diff --git a/Documentation/media/uapi/v4l/tuner.rst b/Documentation/media/uapi/v4l/tuner.rst new file mode 100644 index 000000000000..23d0e00aefdd --- /dev/null +++ b/Documentation/media/uapi/v4l/tuner.rst @@ -0,0 +1,82 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _tuner: + +********************* +Tuners and Modulators +********************* + + +Tuners +====== + +Video input devices can have one or more tuners demodulating a RF +signal. Each tuner is associated with one or more video inputs, +depending on the number of RF connectors on the tuner. The ``type`` +field of the respective struct :ref:`v4l2_input <v4l2-input>` +returned by the :ref:`VIDIOC_ENUMINPUT` ioctl is +set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the +index number of the tuner. + +Radio input devices have exactly one tuner with index zero, no video +inputs. + +To query and change tuner properties applications use the +:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and +:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` ioctls, respectively. The +struct :ref:`v4l2_tuner <v4l2-tuner>` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` +also contains signal status information applicable when the tuner of the +current video or radio input is queried. Note that :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` +does not switch the current tuner, when there is more than one at all. +The tuner is solely determined by the current video input. Drivers must +support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl when the device has +one or more tuners. + + +Modulators +========== + +Video output devices can have one or more modulators, uh, modulating a +video signal for radiation or connection to the antenna input of a TV +set or video recorder. Each modulator is associated with one or more +video outputs, depending on the number of RF connectors on the +modulator. The ``type`` field of the respective struct +:ref:`v4l2_output <v4l2-output>` returned by the +:ref:`VIDIOC_ENUMOUTPUT` ioctl is set to +``V4L2_OUTPUT_TYPE_MODULATOR`` and its ``modulator`` field contains the +index number of the modulator. + +Radio output devices have exactly one modulator with index zero, no +video outputs. + +A video or radio device cannot support both a tuner and a modulator. Two +separate device nodes will have to be used for such hardware, one that +supports the tuner functionality and one that supports the modulator +functionality. The reason is a limitation with the +:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl where you +cannot specify whether the frequency is for a tuner or a modulator. + +To query and change modulator properties applications use the +:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` and +:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Note that +:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` does not switch the current modulator, when there +is more than one at all. The modulator is solely determined by the +current video output. Drivers must support both ioctls and set the +``V4L2_CAP_MODULATOR`` flag in the struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl when the device has +one or more modulators. + + +Radio Frequency +=============== + +To get and set the tuner or modulator radio frequency applications use +the :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and +:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl which both take +a pointer to a struct :ref:`v4l2_frequency <v4l2-frequency>`. These +ioctls are used for TV and radio devices alike. Drivers must support +both ioctls when the tuner or modulator ioctls are supported, or when +the device is a radio device. diff --git a/Documentation/media/uapi/v4l/user-func.rst b/Documentation/media/uapi/v4l/user-func.rst new file mode 100644 index 000000000000..3e0413b83a33 --- /dev/null +++ b/Documentation/media/uapi/v4l/user-func.rst @@ -0,0 +1,81 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _user-func: + +****************** +Function Reference +****************** + + +.. toctree:: + :maxdepth: 1 + + func-close + func-ioctl + vidioc-create-bufs + vidioc-cropcap + vidioc-dbg-g-chip-info + vidioc-dbg-g-register + vidioc-decoder-cmd + vidioc-dqevent + vidioc-dv-timings-cap + vidioc-encoder-cmd + vidioc-enumaudio + vidioc-enumaudioout + vidioc-enum-dv-timings + vidioc-enum-fmt + vidioc-enum-framesizes + vidioc-enum-frameintervals + vidioc-enum-freq-bands + vidioc-enuminput + vidioc-enumoutput + vidioc-enumstd + vidioc-expbuf + vidioc-g-audio + vidioc-g-audioout + vidioc-g-crop + vidioc-g-ctrl + vidioc-g-dv-timings + vidioc-g-edid + vidioc-g-enc-index + vidioc-g-ext-ctrls + vidioc-g-fbuf + vidioc-g-fmt + vidioc-g-frequency + vidioc-g-input + vidioc-g-jpegcomp + vidioc-g-modulator + vidioc-g-output + vidioc-g-parm + vidioc-g-priority + vidioc-g-selection + vidioc-g-sliced-vbi-cap + vidioc-g-std + vidioc-g-tuner + vidioc-log-status + vidioc-overlay + vidioc-prepare-buf + vidioc-qbuf + vidioc-querybuf + vidioc-querycap + vidioc-queryctrl + vidioc-query-dv-timings + vidioc-querystd + vidioc-reqbufs + vidioc-s-hw-freq-seek + vidioc-streamon + vidioc-subdev-enum-frame-interval + vidioc-subdev-enum-frame-size + vidioc-subdev-enum-mbus-code + vidioc-subdev-g-crop + vidioc-subdev-g-fmt + vidioc-subdev-g-frame-interval + vidioc-subdev-g-selection + vidioc-subscribe-event + func-mmap + func-munmap + func-open + func-poll + func-read + func-select + func-write diff --git a/Documentation/media/uapi/v4l/userp.rst b/Documentation/media/uapi/v4l/userp.rst new file mode 100644 index 000000000000..0ecf7a13a7af --- /dev/null +++ b/Documentation/media/uapi/v4l/userp.rst @@ -0,0 +1,117 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _userp: + +***************************** +Streaming I/O (User Pointers) +***************************** + +Input and output devices support this I/O method when the +``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct +:ref:`v4l2_capability <v4l2-capability>` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl is set. If the +particular user pointer method (not only memory mapping) is supported +must be determined by calling the +:ref:`VIDIOC_REQBUFS` ioctl. + +This I/O method combines advantages of the read/write and memory mapping +methods. Buffers (planes) are allocated by the application itself, and +can reside for example in virtual or shared memory. Only pointers to +data are exchanged, these pointers and meta-information are passed in +struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct +:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The +driver must be switched into user pointer I/O mode by calling the +:ref:`VIDIOC_REQBUFS` with the desired buffer type. +No buffers (planes) are allocated beforehand, consequently they are not +indexed and cannot be queried like mapped buffers with the +:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl. + + +.. code-block:: c + :caption: Example 3.3. Initiating streaming I/O with user pointers + + struct v4l2_requestbuffers reqbuf; + + memset (&reqbuf, 0, sizeof (reqbuf)); + reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + reqbuf.memory = V4L2_MEMORY_USERPTR; + + if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) { + if (errno == EINVAL) + printf ("Video capturing or user pointer streaming is not supported\\n"); + else + perror ("VIDIOC_REQBUFS"); + + exit (EXIT_FAILURE); + } + +Buffer (plane) addresses and sizes are passed on the fly with the +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly +cycled, applications can pass different addresses and sizes at each +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the +driver swaps memory pages within physical memory to create a continuous +area of memory. This happens transparently to the application in the +virtual memory subsystem of the kernel. When buffer pages have been +swapped out to disk they are brought back and finally locked in physical +memory for DMA. [1]_ + +Filled or displayed buffers are dequeued with the +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the +memory pages at any time between the completion of the DMA and this +ioctl. The memory is also unlocked when +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called, +:ref:`VIDIOC_REQBUFS`, or when the device is closed. +Applications must take care not to free buffers without dequeuing. For +once, the buffers remain locked until further, wasting physical memory. +Second the driver will not be notified when the memory is returned to +the application's free list and subsequently reused for other purposes, +possibly completing the requested DMA and overwriting valuable data. + +For capturing applications it is customary to enqueue a number of empty +buffers, to start capturing and enter the read loop. Here the +application waits until a filled buffer can be dequeued, and re-enqueues +the buffer when the data is no longer needed. Output applications fill +and enqueue buffers, when enough buffers are stacked up output is +started. In the write loop, when the application runs out of free +buffers it must wait until an empty buffer can be dequeued and reused. +Two methods exist to suspend execution of the application until one or +more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF +<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the +``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` +error code when no buffer is available. The :ref:`select() +<func-select>` or :ref:`poll() <func-poll>` function are always +available. + +To start and stop capturing or output applications call the +:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. Note +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from both +queues and unlocks all buffers as a side effect. Since there is no +notion of doing anything "now" on a multitasking system, if an +application needs to synchronize with another event it should examine +the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or +outputted buffers. + +Drivers implementing user pointer I/O must support the +:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` +and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the +:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [2]_ + +.. [1] + We expect that frequently used buffers are typically not swapped out. + Anyway, the process of swapping, locking or generating scatter-gather + lists may be time consuming. The delay can be masked by the depth of + the incoming buffer queue, and perhaps by maintaining caches assuming + a buffer will be soon enqueued again. On the other hand, to optimize + memory usage drivers can limit the number of buffers locked in + advance and recycle the most recently used buffers first. Of course, + the pages of empty buffers in the incoming queue need not be saved to + disk. Output buffers must be saved on the incoming and outgoing queue + because an application may share them with other processes. + +.. [2] + At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are + the same, and :ref:`select() <func-select>` is too important to be optional. + The rest should be evident. diff --git a/Documentation/media/uapi/v4l/v4l2-selection-flags.rst b/Documentation/media/uapi/v4l/v4l2-selection-flags.rst new file mode 100644 index 000000000000..3ce3731faf5f --- /dev/null +++ b/Documentation/media/uapi/v4l/v4l2-selection-flags.rst @@ -0,0 +1,71 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-selection-flags: + +*************** +Selection flags +*************** + + +.. _v4l2-selection-flags-table: + +.. flat-table:: Selection flag definitions + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Flag name + + - id + + - Definition + + - Valid for V4L2 + + - Valid for V4L2 subdev + + - .. row 2 + + - ``V4L2_SEL_FLAG_GE`` + + - (1 << 0) + + - Suggest the driver it should choose greater or equal rectangle (in + size) than was requested. Albeit the driver may choose a lesser + size, it will only do so due to hardware limitations. Without this + flag (and ``V4L2_SEL_FLAG_LE``) the behaviour is to choose the + closest possible rectangle. + + - Yes + + - Yes + + - .. row 3 + + - ``V4L2_SEL_FLAG_LE`` + + - (1 << 1) + + - Suggest the driver it should choose lesser or equal rectangle (in + size) than was requested. Albeit the driver may choose a greater + size, it will only do so due to hardware limitations. + + - Yes + + - Yes + + - .. row 4 + + - ``V4L2_SEL_FLAG_KEEP_CONFIG`` + + - (1 << 2) + + - The configuration must not be propagated to any further processing + steps. If this flag is not given, the configuration is propagated + inside the subdevice to all further processing steps. + + - No + + - Yes diff --git a/Documentation/media/uapi/v4l/v4l2-selection-targets.rst b/Documentation/media/uapi/v4l/v4l2-selection-targets.rst new file mode 100644 index 000000000000..7519099a50cd --- /dev/null +++ b/Documentation/media/uapi/v4l/v4l2-selection-targets.rst @@ -0,0 +1,135 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-selection-targets: + +***************** +Selection targets +***************** + +The precise meaning of the selection targets may be dependent on which +of the two interfaces they are used. + + +.. _v4l2-selection-targets-table: + +.. flat-table:: Selection target definitions + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Target name + + - id + + - Definition + + - Valid for V4L2 + + - Valid for V4L2 subdev + + - .. row 2 + + - ``V4L2_SEL_TGT_CROP`` + + - 0x0000 + + - Crop rectangle. Defines the cropped area. + + - Yes + + - Yes + + - .. row 3 + + - ``V4L2_SEL_TGT_CROP_DEFAULT`` + + - 0x0001 + + - Suggested cropping rectangle that covers the "whole picture". + + - Yes + + - No + + - .. row 4 + + - ``V4L2_SEL_TGT_CROP_BOUNDS`` + + - 0x0002 + + - Bounds of the crop rectangle. All valid crop rectangles fit inside + the crop bounds rectangle. + + - Yes + + - Yes + + - .. row 5 + + - ``V4L2_SEL_TGT_NATIVE_SIZE`` + + - 0x0003 + + - The native size of the device, e.g. a sensor's pixel array. + ``left`` and ``top`` fields are zero for this target. Setting the + native size will generally only make sense for memory to memory + devices where the software can create a canvas of a given size in + which for example a video frame can be composed. In that case + V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size of + that canvas. + + - Yes + + - Yes + + - .. row 6 + + - ``V4L2_SEL_TGT_COMPOSE`` + + - 0x0100 + + - Compose rectangle. Used to configure scaling and composition. + + - Yes + + - Yes + + - .. row 7 + + - ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` + + - 0x0101 + + - Suggested composition rectangle that covers the "whole picture". + + - Yes + + - No + + - .. row 8 + + - ``V4L2_SEL_TGT_COMPOSE_BOUNDS`` + + - 0x0102 + + - Bounds of the compose rectangle. All valid compose rectangles fit + inside the compose bounds rectangle. + + - Yes + + - Yes + + - .. row 9 + + - ``V4L2_SEL_TGT_COMPOSE_PADDED`` + + - 0x0103 + + - The active area and all padding pixels that are inserted or + modified by hardware. + + - Yes + + - No diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst new file mode 100644 index 000000000000..301f95b5bdc6 --- /dev/null +++ b/Documentation/media/uapi/v4l/v4l2.rst @@ -0,0 +1,395 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. include:: <isonum.txt> +.. _v4l2spec: + +################### +Video for Linux API +################### + +This part describes the Video for Linux API version 2 (V4L2 API) specification. + +**Revision 4.5** + +.. toctree:: + :numbered: + :maxdepth: 1 + :caption: Table of Contents + + common + pixfmt + io + devices + driver + libv4l + compat + user-func + common-defs + videodev + capture-example + v4l2grab-example + biblio + + +********************** +Revision and Copyright +********************** + +Authors, in alphabetical order: + +- Ailus, Sakari <sakari.ailus@iki.fi> + + - Subdev selections API. + +- Carvalho Chehab, Mauro <m.chehab@kernel.org> + + - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter. + +- Dirks, Bill + + - Original author of the V4L2 API and documentation. + +- H Schimek, Michael <mschimek@gmx.at> + + - Original author of the V4L2 API and documentation. + +- Karicheri, Muralidharan <m-karicheri2@ti.com> + + - Documented the Digital Video timings API. + +- Osciak, Pawel <pawel@osciak.com> + + - Designed and documented the multi-planar API. + +- Palosaari, Antti <crope@iki.fi> + + - SDR API. + +- Rubli, Martin + + - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls. + +- Walls, Andy <awalls@md.metrocast.net> + + - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification. + +- Verkuil, Hans <hverkuil@xs4all.nl> + + - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API. + +**Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari. + +Except when explicitly stated as GPL, programming examples within this +part can be used and distributed without restrictions. + +**************** +Revision History +**************** + +:revision: 4.5 / 2015-10-29 (*rr*) + +Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with +ctrl_class and which. Which is used to select the current value of the +control or the default value. + + +:revision: 4.4 / 2015-05-26 (*ap*) + +Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added +V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for +Software Defined Radio (SDR) Interface. + + +:revision: 4.1 / 2015-02-13 (*mcc*) + +Fix documentation for media controller device nodes and add support for +DVB device nodes. Add support for Tuner sub-device. + + +:revision: 3.19 / 2014-12-05 (*hv*) + +Rewrote Colorspace chapter, added new enum +:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum +:ref:`v4l2_quantization <v4l2-quantization>` fields to struct +:ref:`v4l2_pix_format <v4l2-pix-format>`, struct +:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and struct +:ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`. + + +:revision: 3.17 / 2014-08-04 (*lp, hv*) + +Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added +format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL. + + +:revision: 3.15 / 2014-02-03 (*hv, ap*) + +Update several sections of "Common API Elements": "Opening and Closing +Devices" "Querying Capabilities", "Application Priority", "Video Inputs +and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video +Standards" and "Digital Video (DV) Timings". Added SDR API. + + +:revision: 3.14 / 2013-11-25 (*rr*) + +Set width and height as unsigned on v4l2_rect. + + +:revision: 3.11 / 2013-05-26 (*hv*) + +Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl. + + +:revision: 3.10 / 2013-03-25 (*hv*) + +Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET, +VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and +VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output +capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. +Added VIDIOC_DBG_G_CHIP_INFO. + + +:revision: 3.9 / 2012-12-03 (*sa, sn*) + +Added timestamp types to v4l2_buffer. Added +V4L2_EVENT_CTRL_CH_RANGE control event changes flag. + + +:revision: 3.6 / 2012-07-02 (*hv*) + +Added VIDIOC_ENUM_FREQ_BANDS. + + +:revision: 3.5 / 2012-05-07 (*sa, sn, hv*) + +Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. +Improved the description of V4L2_CID_COLORFX control, added +V4L2_CID_COLORFX_CBCR control. Added camera controls +V4L2_CID_AUTO_EXPOSURE_BIAS, +V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, +V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY, +V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING, +V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK, +V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, +V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added +VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and +VIDIOC_DV_TIMINGS_CAP. + + +:revision: 3.4 / 2012-01-25 (*sn*) + +Added :ref:`JPEG compression control class. <jpeg-controls>` + + +:revision: 3.3 / 2012-01-11 (*hv*) + +Added device_caps field to struct v4l2_capabilities. + + +:revision: 3.2 / 2011-08-26 (*hv*) + +Added V4L2_CTRL_FLAG_VOLATILE. + + +:revision: 3.1 / 2011-06-27 (*mcc, po, hv*) + +Documented that VIDIOC_QUERYCAP now returns a per-subsystem version +instead of a per-driver one. Standardize an error code for invalid +ioctl. Added V4L2_CTRL_TYPE_BITMASK. + + +:revision: 2.6.39 / 2011-03-01 (*mcc, po*) + +Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect +latest changes. Added the :ref:`multi-planar API <planar-apis>`. + + +:revision: 2.6.37 / 2010-08-06 (*hv*) + +Removed obsolete vtx (videotext) API. + + +:revision: 2.6.33 / 2009-12-03 (*mk*) + +Added documentation for the Digital Video timings API. + + +:revision: 2.6.32 / 2009-08-31 (*mcc*) + +Now, revisions will match the kernel version where the V4L2 API changes +will be used by the Linux Kernel. Also added Remote Controller chapter. + + +:revision: 0.29 / 2009-08-26 (*ev*) + +Added documentation for string controls and for FM Transmitter controls. + + +:revision: 0.28 / 2009-08-26 (*gl*) + +Added V4L2_CID_BAND_STOP_FILTER documentation. + + +:revision: 0.27 / 2009-08-15 (*mcc*) + +Added libv4l and Remote Controller documentation; added v4l2grab and +keytable application examples. + + +:revision: 0.26 / 2009-07-23 (*hv*) + +Finalized the RDS capture API. Added modulator and RDS encoder +capabilities. Added support for string controls. + + +:revision: 0.25 / 2009-01-18 (*hv*) + +Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls +VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera +controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, +V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY. + + +:revision: 0.24 / 2008-03-04 (*mhs*) + +Added pixel formats Y16 and SBGGR16, new controls and a camera controls +class. Removed VIDIOC_G/S_MPEGCOMP. + + +:revision: 0.23 / 2007-08-30 (*mhs*) + +Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of +packed pixel formats. + + +:revision: 0.22 / 2007-08-29 (*mhs*) + +Added the Video Output Overlay interface, new MPEG controls, +V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, +VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD, +VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. +Clarifications in the cropping chapter, about RGB pixel formats, the +mmap(), poll(), select(), read() and write() functions. Typographical +fixes. + + +:revision: 0.21 / 2006-12-19 (*mhs*) + +Fixed a link in the VIDIOC_G_EXT_CTRLS section. + + +:revision: 0.20 / 2006-11-24 (*mhs*) + +Clarified the purpose of the audioset field in struct v4l2_input and +v4l2_output. + + +:revision: 0.19 / 2006-10-19 (*mhs*) + +Documented V4L2_PIX_FMT_RGB444. + + +:revision: 0.18 / 2006-10-18 (*mhs*) + +Added the description of extended controls by Hans Verkuil. Linked +V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE. + + +:revision: 0.17 / 2006-10-12 (*mhs*) + +Corrected V4L2_PIX_FMT_HM12 description. + + +:revision: 0.16 / 2006-10-08 (*mhs*) + +VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part +of the API. + + +:revision: 0.15 / 2006-09-23 (*mhs*) + +Cleaned up the bibliography, added BT.653 and BT.1119. +capture.c/start_capturing() for user pointer I/O did not initialize the +buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and +V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See +the history chapter for API changes. + + +:revision: 0.14 / 2006-09-14 (*mr*) + +Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal +for frame format enumeration of digital devices. + + +:revision: 0.13 / 2006-04-07 (*mhs*) + +Corrected the description of struct v4l2_window clips. New V4L2_STD\_ +and V4L2_TUNER_MODE_LANG1_LANG2 defines. + + +:revision: 0.12 / 2006-02-03 (*mhs*) + +Corrected the description of struct v4l2_captureparm and +v4l2_outputparm. + + +:revision: 0.11 / 2006-01-27 (*mhs*) + +Improved the description of struct v4l2_tuner. + + +:revision: 0.10 / 2006-01-10 (*mhs*) + +VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications. + + +:revision: 0.9 / 2005-11-27 (*mhs*) + +Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the +sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page. +Fixed VIDIOC_S_STD call in the video standard selection example. +Various updates. + + +:revision: 0.8 / 2004-10-04 (*mhs*) + +Somehow a piece of junk slipped into the capture example, removed. + + +:revision: 0.7 / 2004-09-19 (*mhs*) + +Fixed video standard selection, control enumeration, downscaling and +aspect example. Added read and user pointer i/o to video capture +example. + + +:revision: 0.6 / 2004-08-01 (*mhs*) + +v4l2_buffer changes, added video capture example, various corrections. + + +:revision: 0.5 / 2003-11-05 (*mhs*) + +Pixel format erratum. + + +:revision: 0.4 / 2003-09-17 (*mhs*) + +Corrected source and Makefile to generate a PDF. SGML fixes. Added +latest API changes. Closed gaps in the history chapter. + + +:revision: 0.3 / 2003-02-05 (*mhs*) + +Another draft, more corrections. + + +:revision: 0.2 / 2003-01-15 (*mhs*) + +Second draft, with corrections pointed out by Gerd Knorr. + + +:revision: 0.1 / 2002-12-01 (*mhs*) + +First draft, based on documentation by Bill Dirks and discussions on the +V4L mailing list. diff --git a/Documentation/media/uapi/v4l/v4l2grab-example.rst b/Documentation/media/uapi/v4l/v4l2grab-example.rst new file mode 100644 index 000000000000..c240f0513bee --- /dev/null +++ b/Documentation/media/uapi/v4l/v4l2grab-example.rst @@ -0,0 +1,17 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2grab-example: + +********************************** +Video Grabber example using libv4l +********************************** + +This program demonstrates how to grab V4L2 images in ppm format by using +libv4l handlers. The advantage is that this grabber can potentially work +with any V4L2 driver. + + +.. toctree:: + :maxdepth: 1 + + v4l2grab.c diff --git a/Documentation/media/uapi/v4l/v4l2grab.c.rst b/Documentation/media/uapi/v4l/v4l2grab.c.rst new file mode 100644 index 000000000000..5aabd0b7b089 --- /dev/null +++ b/Documentation/media/uapi/v4l/v4l2grab.c.rst @@ -0,0 +1,169 @@ +.. -*- coding: utf-8; mode: rst -*- + +file: media/v4l/v4l2grab.c +========================== + +.. code-block:: c + + /* V4L2 video picture grabber + Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org> + + 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 version 2 of the License. + + 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. + */ + + #include <stdio.h> + #include <stdlib.h> + #include <string.h> + #include <fcntl.h> + #include <errno.h> + #include <sys/ioctl.h> + #include <sys/types.h> + #include <sys/time.h> + #include <sys/mman.h> + #include <linux/videodev2.h> + #include "../libv4l/include/libv4l2.h" + + #define CLEAR(x) memset(&(x), 0, sizeof(x)) + + struct buffer { + void *start; + size_t length; + }; + + static void xioctl(int fh, int request, void *arg) + { + int r; + + do { + r = v4l2_ioctl(fh, request, arg); + } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN))); + + if (r == -1) { + fprintf(stderr, "error %d, %s\\n", errno, strerror(errno)); + exit(EXIT_FAILURE); + } + } + + int main(int argc, char **argv) + { + struct v4l2_format fmt; + struct v4l2_buffer buf; + struct v4l2_requestbuffers req; + enum v4l2_buf_type type; + fd_set fds; + struct timeval tv; + int r, fd = -1; + unsigned int i, n_buffers; + char *dev_name = "/dev/video0"; + char out_name[256]; + FILE *fout; + struct buffer *buffers; + + fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0); + if (fd < 0) { + perror("Cannot open device"); + exit(EXIT_FAILURE); + } + + CLEAR(fmt); + fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + fmt.fmt.pix.width = 640; + fmt.fmt.pix.height = 480; + fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24; + fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; + xioctl(fd, VIDIOC_S_FMT, &fmt); + if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) { + printf("Libv4l didn't accept RGB24 format. Can't proceed.\\n"); + exit(EXIT_FAILURE); + } + if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480)) + printf("Warning: driver is sending image at %dx%d\\n", + fmt.fmt.pix.width, fmt.fmt.pix.height); + + CLEAR(req); + req.count = 2; + req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + req.memory = V4L2_MEMORY_MMAP; + xioctl(fd, VIDIOC_REQBUFS, &req); + + buffers = calloc(req.count, sizeof(*buffers)); + for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { + CLEAR(buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + buf.index = n_buffers; + + xioctl(fd, VIDIOC_QUERYBUF, &buf); + + buffers[n_buffers].length = buf.length; + buffers[n_buffers].start = v4l2_mmap(NULL, buf.length, + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, buf.m.offset); + + if (MAP_FAILED == buffers[n_buffers].start) { + perror("mmap"); + exit(EXIT_FAILURE); + } + } + + for (i = 0; i < n_buffers; ++i) { + CLEAR(buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + buf.index = i; + xioctl(fd, VIDIOC_QBUF, &buf); + } + type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + xioctl(fd, VIDIOC_STREAMON, &type); + for (i = 0; i < 20; i++) { + do { + FD_ZERO(&fds); + FD_SET(fd, &fds); + + /* Timeout. */ + tv.tv_sec = 2; + tv.tv_usec = 0; + + r = select(fd + 1, &fds, NULL, NULL, &tv); + } while ((r == -1 && (errno = EINTR))); + if (r == -1) { + perror("select"); + return errno; + } + + CLEAR(buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + xioctl(fd, VIDIOC_DQBUF, &buf); + + sprintf(out_name, "out%03d.ppm", i); + fout = fopen(out_name, "w"); + if (!fout) { + perror("Cannot open image"); + exit(EXIT_FAILURE); + } + fprintf(fout, "P6\\n%d %d 255\\n", + fmt.fmt.pix.width, fmt.fmt.pix.height); + fwrite(buffers[buf.index].start, buf.bytesused, 1, fout); + fclose(fout); + + xioctl(fd, VIDIOC_QBUF, &buf); + } + + type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + xioctl(fd, VIDIOC_STREAMOFF, &type); + for (i = 0; i < n_buffers; ++i) + v4l2_munmap(buffers[i].start, buffers[i].length); + v4l2_close(fd); + + return 0; + } diff --git a/Documentation/media/uapi/v4l/video.rst b/Documentation/media/uapi/v4l/video.rst new file mode 100644 index 000000000000..e38ebe192614 --- /dev/null +++ b/Documentation/media/uapi/v4l/video.rst @@ -0,0 +1,63 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _video: + +************************ +Video Inputs and Outputs +************************ + +Video inputs and outputs are physical connectors of a device. These can +be for example RF connectors (antenna/cable), CVBS a.k.a. Composite +Video, S-Video or RGB connectors. Video and VBI capture devices have +inputs. Video and VBI output devices have outputs, at least one each. +Radio devices have no video inputs or outputs. + +To learn about the number and attributes of the available inputs and +outputs applications can enumerate them with the +:ref:`VIDIOC_ENUMINPUT` and +:ref:`VIDIOC_ENUMOUTPUT` ioctl, respectively. The +struct :ref:`v4l2_input <v4l2-input>` returned by the +:ref:`VIDIOC_ENUMINPUT` ioctl also contains signal +:status information applicable when the current video input is queried. + +The :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and +:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctls return the index of +the current video input or output. To select a different input or output +applications call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` and +:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctls. Drivers must +implement all the input ioctls when the device has one or more inputs, +all the output ioctls when the device has one or more outputs. + +.. code-block:: c + :caption: Example 1.1. Information about the current video input + + struct v4l2_input input; + int index; + + if (-1 == ioctl(fd, VIDIOC_G_INPUT, &index)) { + perror("VIDIOC_G_INPUT"); + exit(EXIT_FAILURE); + } + + memset(&input, 0, sizeof(input)); + input.index = index; + + if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) { + perror("VIDIOC_ENUMINPUT"); + exit(EXIT_FAILURE); + } + + printf("Current input: %s\\n", input.name); + + +.. code-block:: c + :caption: Example 1.2. Switching to the first video input + + int index; + + index = 0; + + if (-1 == ioctl(fd, VIDIOC_S_INPUT, &index)) { + perror("VIDIOC_S_INPUT"); + exit(EXIT_FAILURE); + } diff --git a/Documentation/media/uapi/v4l/videodev.rst b/Documentation/media/uapi/v4l/videodev.rst new file mode 100644 index 000000000000..b9ee4672d639 --- /dev/null +++ b/Documentation/media/uapi/v4l/videodev.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _videodev: + +******************************* +Video For Linux Two Header File +******************************* + +.. kernel-include:: $BUILDDIR/videodev2.h.rst diff --git a/Documentation/media/uapi/v4l/vidioc-create-bufs.rst b/Documentation/media/uapi/v4l/vidioc-create-bufs.rst new file mode 100644 index 000000000000..abdc0b4d83d5 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-create-bufs.rst @@ -0,0 +1,146 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_CREATE_BUFS: + +************************ +ioctl VIDIOC_CREATE_BUFS +************************ + +Name +==== + +VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_create_buffers *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_CREATE_BUFS + +``argp`` + + +Description +=========== + +This ioctl is used to create buffers for :ref:`memory mapped <mmap>` +or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It +can be used as an alternative or in addition to the +:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control +over buffers is required. This ioctl can be called multiple times to +create buffers of different sizes. + +To allocate the device buffers applications must initialize the relevant +fields of the :ref:`struct v4l2_create_buffers <v4l2-create-buffers>` structure. The +``count`` field must be set to the number of requested buffers, the +``memory`` field specifies the requested I/O method and the ``reserved`` +array must be zeroed. + +The ``format`` field specifies the image format that the buffers must be +able to handle. The application has to fill in this struct +:ref:`v4l2_format <v4l2-format>`. Usually this will be done using the +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the +requested format is supported by the driver. Based on the format's +``type`` field the requested buffer size (for single-planar) or plane +sizes (for multi-planar formats) will be used for the allocated buffers. +The driver may return an error if the size(s) are not supported by the +hardware (usually because they are too small). + +The buffers created by this ioctl will have as minimum size the size +defined by the ``format.pix.sizeimage`` field (or the corresponding +fields for other format types). Usually if the ``format.pix.sizeimage`` +field is less than the minimum required for the given format, then an +error will be returned since drivers will typically not allow this. If +it is larger, then the value will be used as-is. In other words, the +driver may reject the requested size, but if it is accepted the driver +will use it unchanged. + +When the ioctl is called with a pointer to this structure the driver +will attempt to allocate up to the requested number of buffers and store +the actual number allocated and the starting index in the ``count`` and +the ``index`` fields respectively. On return ``count`` can be smaller +than the number requested. + + +.. _v4l2-create-buffers: + +.. flat-table:: struct v4l2_create_buffers + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - The starting buffer index, returned by the driver. + + - .. row 2 + + - __u32 + + - ``count`` + + - The number of buffers requested or granted. If count == 0, then + :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of + created buffers, and it will check the validity of ``memory`` and + ``format.type``. If those are invalid -1 is returned and errno is + set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns + 0. It will never set errno to ``EBUSY`` error code in this particular + case. + + - .. row 3 + + - __u32 + + - ``memory`` + + - Applications set this field to ``V4L2_MEMORY_MMAP``, + ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See + :ref:`v4l2-memory` + + - .. row 4 + + - struct :ref:`v4l2_format <v4l2-format>` + + - ``format`` + + - Filled in by the application, preserved by the driver. + + - .. row 5 + + - __u32 + + - ``reserved``\ [8] + + - A place holder for future extensions. Drivers and applications + must set the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +ENOMEM + No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. + +EINVAL + The buffer type (``format.type`` field), requested I/O method + (``memory``) or format (``format`` field) is not valid. diff --git a/Documentation/media/uapi/v4l/vidioc-cropcap.rst b/Documentation/media/uapi/v4l/vidioc-cropcap.rst new file mode 100644 index 000000000000..8dcbe6d26219 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-cropcap.rst @@ -0,0 +1,167 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_CROPCAP: + +******************** +ioctl VIDIOC_CROPCAP +******************** + +Name +==== + +VIDIOC_CROPCAP - Information about the video cropping and scaling abilities + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_cropcap *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_CROPCAP + +``argp`` + + +Description +=========== + +Applications use this function to query the cropping limits, the pixel +aspect of images and to calculate scale factors. They set the ``type`` +field of a v4l2_cropcap structure to the respective buffer (stream) +type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this +structure. Drivers fill the rest of the structure. The results are +constant except when switching the video standard. Remember this switch +can occur implicit when switching the video input or output. + +Do not use the multiplanar buffer types. Use +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of +``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use +``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of +``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. + +This ioctl must be implemented for video capture or output devices that +support cropping and/or scaling and/or have non-square pixels, and for +overlay devices. + + +.. _v4l2-cropcap: + +.. flat-table:: struct v4l2_cropcap + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - Type of the data stream, set by the application. Only these types + are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, + ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`. + + - .. row 2 + + - struct :ref:`v4l2_rect <v4l2-rect-crop>` + + - ``bounds`` + + - Defines the window within capturing or output is possible, this + may exclude for example the horizontal and vertical blanking + areas. The cropping rectangle cannot exceed these limits. Width + and height are defined in pixels, the driver writer is free to + choose origin and units of the coordinate system in the analog + domain. + + - .. row 3 + + - struct :ref:`v4l2_rect <v4l2-rect-crop>` + + - ``defrect`` + + - Default cropping rectangle, it shall cover the "whole picture". + Assuming pixel aspect 1/1 this could be for example a 640 × 480 + rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM + centered over the active picture area. The same co-ordinate system + as for ``bounds`` is used. + + - .. row 4 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``pixelaspect`` + + - This is the pixel aspect (y / x) when no scaling is applied, the + ratio of the actual sampling frequency and the frequency required + to get square pixels. + + When cropping coordinates refer to square pixels, the driver sets + ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and + SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`]. + + + +.. _v4l2-rect-crop: + +.. flat-table:: struct v4l2_rect + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __s32 + + - ``left`` + + - Horizontal offset of the top, left corner of the rectangle, in + pixels. + + - .. row 2 + + - __s32 + + - ``top`` + + - Vertical offset of the top, left corner of the rectangle, in + pixels. + + - .. row 3 + + - __u32 + + - ``width`` + + - Width of the rectangle, in pixels. + + - .. row 4 + + - __u32 + + - ``height`` + + - Height of the rectangle, in pixels. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is + invalid. diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst new file mode 100644 index 000000000000..efa911c0fb19 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst @@ -0,0 +1,204 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_DBG_G_CHIP_INFO: + +**************************** +ioctl VIDIOC_DBG_G_CHIP_INFO +**************************** + +Name +==== + +VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_chip_info *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_DBG_G_CHIP_INFO + +``argp`` + + +Description +=========== + + **Note** + + This is an :ref:`experimental` interface and may + change in the future. + +For driver debugging purposes this ioctl allows test applications to +query the driver about the chips present on the TV card. Regular +applications must not use it. When you found a chip specific bug, please +contact the linux-media mailing list +(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__) +so it can be fixed. + +Additionally the Linux kernel must be compiled with the +``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl. + +To query the driver applications must initialize the ``match.type`` and +``match.addr`` or ``match.name`` fields of a struct +:ref:`v4l2_dbg_chip_info <v4l2-dbg-chip-info>` and call +:ref:`VIDIOC_DBG_G_CHIP_INFO` with a pointer to this structure. On success +the driver stores information about the selected chip in the ``name`` +and ``flags`` fields. + +When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr`` +selects the nth bridge 'chip' on the TV card. You can enumerate all +chips by starting at zero and incrementing ``match.addr`` by one until +:ref:`VIDIOC_DBG_G_CHIP_INFO` fails with an ``EINVAL`` error code. The number +zero always selects the bridge chip itself, e. g. the chip connected to +the PCI or USB bus. Non-zero numbers identify specific parts of the +bridge chip such as an AC97 register block. + +When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr`` +selects the nth sub-device. This allows you to enumerate over all +sub-devices. + +On success, the ``name`` field will contain a chip name and the +``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver +supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE`` +if the driver supports writing registers to the device. + +We recommended the v4l2-dbg utility over calling this ioctl directly. It +is available from the LinuxTV v4l-dvb repository; see +`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access +instructions. + + +.. _name-v4l2-dbg-match: + +.. flat-table:: struct v4l2_dbg_match + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - See :ref:`name-chip-match-types` for a list of possible types. + + - .. row 2 + + - union + + - (anonymous) + + - .. row 3 + + - + - __u32 + + - ``addr`` + + - Match a chip by this number, interpreted according to the ``type`` + field. + + - .. row 4 + + - + - char + + - ``name[32]`` + + - Match a chip by this name, interpreted according to the ``type`` + field. Currently unused. + + + +.. _v4l2-dbg-chip-info: + +.. flat-table:: struct v4l2_dbg_chip_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - struct v4l2_dbg_match + + - ``match`` + + - How to match the chip, see :ref:`name-v4l2-dbg-match`. + + - .. row 2 + + - char + + - ``name[32]`` + + - The name of the chip. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the + driver supports reading registers from the device. If + ``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing + registers. + + - .. row 4 + + - __u32 + + - ``reserved[8]`` + + - Reserved fields, both application and driver must set these to 0. + + + +.. _name-chip-match-types: + +.. flat-table:: Chip Match Types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_CHIP_MATCH_BRIDGE`` + + - 0 + + - Match the nth chip on the card, zero for the bridge chip. Does not + match sub-devices. + + - .. row 2 + + - ``V4L2_CHIP_MATCH_SUBDEV`` + + - 4 + + - Match the nth sub-device. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The ``match_type`` is invalid or no device could be matched. diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst new file mode 100644 index 000000000000..345aa321f380 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst @@ -0,0 +1,209 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_DBG_G_REGISTER: + +************************************************** +ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER +************************************************** + +Name +==== + +VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_register *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_dbg_register *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER + +``argp`` + + +Description +=========== + + **Note** + + This is an :ref:`experimental` interface and may + change in the future. + +For driver debugging purposes these ioctls allow test applications to +access hardware registers directly. Regular applications must not use +them. + +Since writing or even reading registers can jeopardize the system +security, its stability and damage the hardware, both ioctls require +superuser privileges. Additionally the Linux kernel must be compiled +with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls. + +To write a register applications must initialize all fields of a struct +:ref:`v4l2_dbg_register <v4l2-dbg-register>` except for ``size`` and +call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The +``match.type`` and ``match.addr`` or ``match.name`` fields select a chip +on the TV card, the ``reg`` field specifies a register number and the +``val`` field the value to be written into the register. + +To read a register applications must initialize the ``match.type``, +``match.addr`` or ``match.name`` and ``reg`` fields, and call +``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success +the driver stores the register value in the ``val`` field and the size +(in bytes) of the value in ``size``. + +When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr`` +selects the nth non-sub-device chip on the TV card. The number zero +always selects the host chip, e. g. the chip connected to the PCI or USB +bus. You can find out which chips are present with the +:ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. + +When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr`` +selects the nth sub-device. + +These ioctls are optional, not all drivers may support them. However +when a driver supports these ioctls it must also support +:ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely +it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls. + +``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced +in Linux 2.6.21, but their API was changed to the one described here in +kernel 2.6.29. + +We recommended the v4l2-dbg utility over calling these ioctls directly. +It is available from the LinuxTV v4l-dvb repository; see +`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access +instructions. + + +.. _v4l2-dbg-match: + +.. flat-table:: struct v4l2_dbg_match + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - See :ref:`chip-match-types` for a list of possible types. + + - .. row 2 + + - union + + - (anonymous) + + - .. row 3 + + - + - __u32 + + - ``addr`` + + - Match a chip by this number, interpreted according to the ``type`` + field. + + - .. row 4 + + - + - char + + - ``name[32]`` + + - Match a chip by this name, interpreted according to the ``type`` + field. Currently unused. + + + +.. _v4l2-dbg-register: + +.. flat-table:: struct v4l2_dbg_register + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - struct v4l2_dbg_match + + - ``match`` + + - How to match the chip, see :ref:`v4l2-dbg-match`. + + - .. row 2 + + - __u32 + + - ``size`` + + - The register size in bytes. + + - .. row 3 + + - __u64 + + - ``reg`` + + - A register number. + + - .. row 4 + + - __u64 + + - ``val`` + + - The value read from, or to be written into the register. + + + +.. _chip-match-types: + +.. flat-table:: Chip Match Types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_CHIP_MATCH_BRIDGE`` + + - 0 + + - Match the nth chip on the card, zero for the bridge chip. Does not + match sub-devices. + + - .. row 2 + + - ``V4L2_CHIP_MATCH_SUBDEV`` + + - 4 + + - Match the nth sub-device. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EPERM + Insufficient permissions. Root privileges are required to execute + these ioctls. diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst new file mode 100644 index 000000000000..2a36e91b57b9 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst @@ -0,0 +1,271 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_DECODER_CMD: + +************************************************ +ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD +************************************************ + +Name +==== + +VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_decoder_cmd *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD + +``argp`` + + +Description +=========== + +These ioctls control an audio/video (usually MPEG-) decoder. +``VIDIOC_DECODER_CMD`` sends a command to the decoder, +``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually +executing it. To send a command applications must initialize all fields +of a struct :ref:`v4l2_decoder_cmd <v4l2-decoder-cmd>` and call +``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to +this structure. + +The ``cmd`` field must contain the command code. Some commands use the +``flags`` field for additional information. + +A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON` +call sends an implicit START command to the decoder if it has not been +started yet. + +A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +call of a streaming file descriptor sends an implicit immediate STOP +command to the decoder, and all buffered data is discarded. + +These ioctls are optional, not all drivers may support them. They were +introduced in Linux 3.3. + + +.. _v4l2-decoder-cmd: + +.. flat-table:: struct v4l2_decoder_cmd + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 1 + + + - .. row 1 + + - __u32 + + - ``cmd`` + + - + - + - The decoder command, see :ref:`decoder-cmds`. + + - .. row 2 + + - __u32 + + - ``flags`` + + - + - + - Flags to go with the command. If no flags are defined for this + command, drivers and applications must set this field to zero. + + - .. row 3 + + - union + + - (anonymous) + + - + - + - + + - .. row 4 + + - + - struct + + - ``start`` + + - + - Structure containing additional data for the + ``V4L2_DEC_CMD_START`` command. + + - .. row 5 + + - + - + - __s32 + + - ``speed`` + + - Playback speed and direction. The playback speed is defined as + ``speed``/1000 of the normal speed. So 1000 is normal playback. + Negative numbers denote reverse playback, so -1000 does reverse + playback at normal speed. Speeds -1, 0 and 1 have special + meanings: speed 0 is shorthand for 1000 (normal playback). A speed + of 1 steps just one frame forward, a speed of -1 steps just one + frame back. + + - .. row 6 + + - + - + - __u32 + + - ``format`` + + - Format restrictions. This field is set by the driver, not the + application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if + there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if + the decoder operates on full GOPs (*Group Of Pictures*). This is + usually the case for reverse playback: the decoder needs full + GOPs, which it can then play in reverse order. So to implement + reverse playback the application must feed the decoder the last + GOP in the video file, then the GOP before that, etc. etc. + + - .. row 7 + + - + - struct + + - ``stop`` + + - + - Structure containing additional data for the ``V4L2_DEC_CMD_STOP`` + command. + + - .. row 8 + + - + - + - __u64 + + - ``pts`` + + - Stop playback at this ``pts`` or immediately if the playback is + already past that timestamp. Leave to 0 if you want to stop after + the last frame was decoded. + + - .. row 9 + + - + - struct + + - ``raw`` + + - + - + + - .. row 10 + + - + - + - __u32 + + - ``data``\ [16] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. _decoder-cmds: + +.. flat-table:: Decoder Commands + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_DEC_CMD_START`` + + - 0 + + - Start the decoder. When the decoder is already running or paused, + this command will just change the playback speed. That means that + calling ``V4L2_DEC_CMD_START`` when the decoder was paused will + *not* resume the decoder. You have to explicitly call + ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag: + ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be + muted when playing back at a non-standard speed. + + - .. row 2 + + - ``V4L2_DEC_CMD_STOP`` + + - 1 + + - Stop the decoder. When the decoder is already stopped, this + command does nothing. This command has two flags: if + ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set + the picture to black after it stopped decoding. Otherwise the last + image will repeat. mem2mem decoders will stop producing new frames + altogether. They will send a ``V4L2_EVENT_EOS`` event when the + last frame has been decoded and all frames are ready to be + dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on + the last buffer of the capture queue to indicate there will be no + new buffers produced to dequeue. This buffer may be empty, + indicated by the driver setting the ``bytesused`` field to 0. Once + the ``V4L2_BUF_FLAG_LAST`` flag was set, the + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, + but return an ``EPIPE`` error code. If + ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops + immediately (ignoring the ``pts`` value), otherwise it will keep + decoding until timestamp >= pts or until the last of the pending + data from its internal buffers was decoded. + + - .. row 3 + + - ``V4L2_DEC_CMD_PAUSE`` + + - 2 + + - Pause the decoder. When the decoder has not been started yet, the + driver will return an ``EPERM`` error code. When the decoder is + already paused, this command does nothing. This command has one + flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the + decoder output to black when paused. + + - .. row 4 + + - ``V4L2_DEC_CMD_RESUME`` + + - 3 + + - Resume decoding after a PAUSE command. When the decoder has not + been started yet, the driver will return an ``EPERM`` error code. When + the decoder is already running, this command does nothing. No + flags are defined for this command. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The ``cmd`` field is invalid. + +EPERM + The application sent a PAUSE or RESUME command when the decoder was + not running. diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst new file mode 100644 index 000000000000..73c0d5be62ee --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-dqevent.rst @@ -0,0 +1,573 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_DQEVENT: + +******************** +ioctl VIDIOC_DQEVENT +******************** + +Name +==== + +VIDIOC_DQEVENT - Dequeue event + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_DQEVENT + +``argp`` + + +Description +=========== + +Dequeue an event from a video device. No input is required for this +ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>` +structure are filled by the driver. The file handle will also receive +exceptions which the application may get by e.g. using the select system +call. + + +.. _v4l2-event: + +.. flat-table:: struct v4l2_event + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 + + + - .. row 1 + + - __u32 + + - ``type`` + + - + - Type of the event, see :ref:`event-type`. + + - .. row 2 + + - union + + - ``u`` + + - + - + + - .. row 3 + + - + - struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` + + - ``vsync`` + + - Event data for event ``V4L2_EVENT_VSYNC``. + + - .. row 4 + + - + - struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` + + - ``ctrl`` + + - Event data for event ``V4L2_EVENT_CTRL``. + + - .. row 5 + + - + - struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` + + - ``frame_sync`` + + - Event data for event ``V4L2_EVENT_FRAME_SYNC``. + + - .. row 6 + + - + - struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>` + + - ``motion_det`` + + - Event data for event V4L2_EVENT_MOTION_DET. + + - .. row 7 + + - + - struct :ref:`v4l2_event_src_change <v4l2-event-src-change>` + + - ``src_change`` + + - Event data for event V4L2_EVENT_SOURCE_CHANGE. + + - .. row 8 + + - + - __u8 + + - ``data``\ [64] + + - Event data. Defined by the event type. The union should be used to + define easily accessible type for events. + + - .. row 9 + + - __u32 + + - ``pending`` + + - + - Number of pending events excluding this one. + + - .. row 10 + + - __u32 + + - ``sequence`` + + - + - Event sequence number. The sequence number is incremented for + every subscribed event that takes place. If sequence numbers are + not contiguous it means that events have been lost. + + - .. row 11 + + - struct timespec + + - ``timestamp`` + + - + - Event timestamp. The timestamp has been taken from the + ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2, + use :c:func:`clock_gettime(2)`. + + - .. row 12 + + - u32 + + - ``id`` + + - + - The ID associated with the event source. If the event does not + have an associated ID (this depends on the event type), then this + is 0. + + - .. row 13 + + - __u32 + + - ``reserved``\ [8] + + - + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _event-type: + +.. flat-table:: Event Types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_EVENT_ALL`` + + - 0 + + - All events. V4L2_EVENT_ALL is valid only for + VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. + + - .. row 2 + + - ``V4L2_EVENT_VSYNC`` + + - 1 + + - This event is triggered on the vertical sync. This event has a + struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated + with it. + + - .. row 3 + + - ``V4L2_EVENT_EOS`` + + - 2 + + - This event is triggered when the end of a stream is reached. This + is typically used with MPEG decoders to report to the application + when the last of the MPEG stream has been decoded. + + - .. row 4 + + - ``V4L2_EVENT_CTRL`` + + - 3 + + - This event requires that the ``id`` matches the control ID from + which you want to receive events. This event is triggered if the + control's value changes, if a button control is pressed or if the + control's flags change. This event has a struct + :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it. + This struct contains much of the same information as struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct + :ref:`v4l2_control <v4l2-control>`. + + If the event is generated due to a call to + :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the + event will *not* be sent to the file handle that called the ioctl + function. This prevents nasty feedback loops. If you *do* want to + get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK`` + flag. + + This event type will ensure that no information is lost when more + events are raised than there is room internally. In that case the + struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the + second-oldest event is kept, but the ``changes`` field of the + second-oldest event is ORed with the ``changes`` field of the + oldest event. + + - .. row 5 + + - ``V4L2_EVENT_FRAME_SYNC`` + + - 4 + + - Triggered immediately when the reception of a frame has begun. + This event has a struct + :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` + associated with it. + + If the hardware needs to be stopped in the case of a buffer + underrun it might not be able to generate this event. In such + cases the ``frame_sequence`` field in struct + :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not + be incremented. This causes two consecutive frame sequence numbers + to have n times frame interval in between them. + + - .. row 6 + + - ``V4L2_EVENT_SOURCE_CHANGE`` + + - 5 + + - This event is triggered when a source parameter change is detected + during runtime by the video device. It can be a runtime resolution + change triggered by a video decoder or the format change happening + on an input connector. This event requires that the ``id`` matches + the input index (when used with a video device node) or the pad + index (when used with a subdevice node) from which you want to + receive events. + + This event has a struct + :ref:`v4l2_event_src_change <v4l2-event-src-change>` + associated with it. The ``changes`` bitfield denotes what has + changed for the subscribed pad. If multiple events occurred before + application could dequeue them, then the changes will have the + ORed value of all the events generated. + + - .. row 7 + + - ``V4L2_EVENT_MOTION_DET`` + + - 6 + + - Triggered whenever the motion detection state for one or more of + the regions changes. This event has a struct + :ref:`v4l2_event_motion_det <v4l2-event-motion-det>` + associated with it. + + - .. row 8 + + - ``V4L2_EVENT_PRIVATE_START`` + + - 0x08000000 + + - Base event number for driver-private events. + + + +.. _v4l2-event-vsync: + +.. flat-table:: struct v4l2_event_vsync + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u8 + + - ``field`` + + - The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`. + + + +.. _v4l2-event-ctrl: + +.. flat-table:: struct v4l2_event_ctrl + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 + + + - .. row 1 + + - __u32 + + - ``changes`` + + - + - A bitmask that tells what has changed. See + :ref:`ctrl-changes-flags`. + + - .. row 2 + + - __u32 + + - ``type`` + + - + - The type of the control. See enum + :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`. + + - .. row 3 + + - union (anonymous) + + - + - + - + + - .. row 4 + + - + - __s32 + + - ``value`` + + - The 32-bit value of the control for 32-bit control types. This is + 0 for string controls since the value of a string cannot be passed + using :ref:`VIDIOC_DQEVENT`. + + - .. row 5 + + - + - __s64 + + - ``value64`` + + - The 64-bit value of the control for 64-bit control types. + + - .. row 6 + + - __u32 + + - ``flags`` + + - + - The control flags. See :ref:`control-flags`. + + - .. row 7 + + - __s32 + + - ``minimum`` + + - + - The minimum value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + + - .. row 8 + + - __s32 + + - ``maximum`` + + - + - The maximum value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + + - .. row 9 + + - __s32 + + - ``step`` + + - + - The step value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + + - .. row 10 + + - __s32 + + - ``default_value`` + + - + - The default value value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + + + +.. _v4l2-event-frame-sync: + +.. flat-table:: struct v4l2_event_frame_sync + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``frame_sequence`` + + - The sequence number of the frame being received. + + + +.. _v4l2-event-src-change: + +.. flat-table:: struct v4l2_event_src_change + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``changes`` + + - A bitmask that tells what has changed. See + :ref:`src-changes-flags`. + + + +.. _v4l2-event-motion-det: + +.. flat-table:: struct v4l2_event_motion_det + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``flags`` + + - Currently only one flag is available: if + ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the + ``frame_sequence`` field is valid, otherwise that field should be + ignored. + + - .. row 2 + + - __u32 + + - ``frame_sequence`` + + - The sequence number of the frame being received. Only valid if the + ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set. + + - .. row 3 + + - __u32 + + - ``region_mask`` + + - The bitmask of the regions that reported motion. There is at least + one region. If this field is 0, then no motion was detected at + all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control + (see :ref:`detect-controls`) to assign a different region to + each cell in the motion detection grid, then that all cells are + automatically assigned to the default region 0. + + + +.. _ctrl-changes-flags: + +.. flat-table:: Control Changes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_EVENT_CTRL_CH_VALUE`` + + - 0x0001 + + - This control event was triggered because the value of the control + changed. Special cases: Volatile controls do no generate this + event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` + flag set, then this event is sent as well, regardless its value. + + - .. row 2 + + - ``V4L2_EVENT_CTRL_CH_FLAGS`` + + - 0x0002 + + - This control event was triggered because the control flags + changed. + + - .. row 3 + + - ``V4L2_EVENT_CTRL_CH_RANGE`` + + - 0x0004 + + - This control event was triggered because the minimum, maximum, + step or the default value of the control changed. + + + +.. _src-changes-flags: + +.. flat-table:: Source Changes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_EVENT_SRC_CH_RESOLUTION`` + + - 0x0001 + + - This event gets triggered when a resolution change is detected at + an input. This can come from an input connector or from a video + decoder. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst new file mode 100644 index 000000000000..5a35bb254b4b --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst @@ -0,0 +1,250 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_DV_TIMINGS_CAP: + +********************************************************* +ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP +********************************************************* + +Name +==== + +VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings_cap *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP + +``argp`` + + +Description +=========== + +To query the capabilities of the DV receiver/transmitter applications +initialize the ``pad`` field to 0, zero the reserved array of struct +:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` and call the +``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill +in the structure. Note that drivers may return different values after +switching the video input or output. + +When implemented by the driver DV capabilities of subdevices can be +queried by calling the ``VIDIOC_SUBDEV_DV_TIMINGS_CAP`` ioctl directly +on a subdevice node. The capabilities are specific to inputs (for DV +receivers) or outputs (for DV transmitters), applications must specify +the desired pad number in the struct +:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` ``pad`` field and +zero the ``reserved`` array. Attempts to query capabilities on a pad +that doesn't support them will return an ``EINVAL`` error code. + + +.. _v4l2-bt-timings-cap: + +.. flat-table:: struct v4l2_bt_timings_cap + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``min_width`` + + - Minimum width of the active video in pixels. + + - .. row 2 + + - __u32 + + - ``max_width`` + + - Maximum width of the active video in pixels. + + - .. row 3 + + - __u32 + + - ``min_height`` + + - Minimum height of the active video in lines. + + - .. row 4 + + - __u32 + + - ``max_height`` + + - Maximum height of the active video in lines. + + - .. row 5 + + - __u64 + + - ``min_pixelclock`` + + - Minimum pixelclock frequency in Hz. + + - .. row 6 + + - __u64 + + - ``max_pixelclock`` + + - Maximum pixelclock frequency in Hz. + + - .. row 7 + + - __u32 + + - ``standards`` + + - The video standard(s) supported by the hardware. See + :ref:`dv-bt-standards` for a list of standards. + + - .. row 8 + + - __u32 + + - ``capabilities`` + + - Several flags giving more information about the capabilities. See + :ref:`dv-bt-cap-capabilities` for a description of the flags. + + - .. row 9 + + - __u32 + + - ``reserved``\ [16] + + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _v4l2-dv-timings-cap: + +.. flat-table:: struct v4l2_dv_timings_cap + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 + + + - .. row 1 + + - __u32 + + - ``type`` + + - Type of DV timings as listed in :ref:`dv-timing-types`. + + - .. row 2 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media controller API. This field is + only used when operating on a subdevice node. When operating on a + video node applications must set this field to zero. + + - .. row 3 + + - __u32 + + - ``reserved``\ [2] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + - .. row 4 + + - union + + - + - + + - .. row 5 + + - + - struct :ref:`v4l2_bt_timings_cap <v4l2-bt-timings-cap>` + + - ``bt`` + + - BT.656/1120 timings capabilities of the hardware. + + - .. row 6 + + - + - __u32 + + - ``raw_data``\ [32] + + - + + + +.. _dv-bt-cap-capabilities: + +.. flat-table:: DV BT Timing capabilities + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - Flag + + - Description + + - .. row 2 + + - + - + + - .. row 3 + + - ``V4L2_DV_BT_CAP_INTERLACED`` + + - Interlaced formats are supported. + + - .. row 4 + + - ``V4L2_DV_BT_CAP_PROGRESSIVE`` + + - Progressive formats are supported. + + - .. row 5 + + - ``V4L2_DV_BT_CAP_REDUCED_BLANKING`` + + - CVT/GTF specific: the timings can make use of reduced blanking + (CVT) or the 'Secondary GTF' curve (GTF). + + - .. row 6 + + - ``V4L2_DV_BT_CAP_CUSTOM`` + + - Can support non-standard timings, i.e. timings not belonging to + the standards set in the ``standards`` field. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst new file mode 100644 index 000000000000..69bd9b4e0e56 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst @@ -0,0 +1,195 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENCODER_CMD: + +************************************************ +ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD +************************************************ + +Name +==== + +VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_encoder_cmd *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD + +``argp`` + + +Description +=========== + +These ioctls control an audio/video (usually MPEG-) encoder. +``VIDIOC_ENCODER_CMD`` sends a command to the encoder, +``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually +executing it. + +To send a command applications must initialize all fields of a struct +:ref:`v4l2_encoder_cmd <v4l2-encoder-cmd>` and call +``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to +this structure. + +The ``cmd`` field must contain the command code. The ``flags`` field is +currently only used by the STOP command and contains one bit: If the +``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue +until the end of the current *Group Of Pictures*, otherwise it will stop +immediately. + +A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` +call sends an implicit START command to the encoder if it has not been +started yet. After a STOP command, :ref:`read() <func-read>` calls will read +the remaining data buffered by the driver. When the buffer is empty, +:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>` +call will restart the encoder. + +A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +call of a streaming file descriptor sends an implicit immediate STOP to +the encoder, and all buffered data is discarded. + +These ioctls are optional, not all drivers may support them. They were +introduced in Linux 2.6.21. + + +.. _v4l2-encoder-cmd: + +.. flat-table:: struct v4l2_encoder_cmd + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``cmd`` + + - The encoder command, see :ref:`encoder-cmds`. + + - .. row 2 + + - __u32 + + - ``flags`` + + - Flags to go with the command, see :ref:`encoder-flags`. If no + flags are defined for this command, drivers and applications must + set this field to zero. + + - .. row 3 + + - __u32 + + - ``data``\ [8] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. _encoder-cmds: + +.. flat-table:: Encoder Commands + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_ENC_CMD_START`` + + - 0 + + - Start the encoder. When the encoder is already running or paused, + this command does nothing. No flags are defined for this command. + + - .. row 2 + + - ``V4L2_ENC_CMD_STOP`` + + - 1 + + - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag + is set, encoding will continue until the end of the current *Group + Of Pictures*, otherwise encoding will stop immediately. When the + encoder is already stopped, this command does nothing. mem2mem + encoders will send a ``V4L2_EVENT_EOS`` event when the last frame + has been encoded and all frames are ready to be dequeued and will + set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of + the capture queue to indicate there will be no new buffers + produced to dequeue. This buffer may be empty, indicated by the + driver setting the ``bytesused`` field to 0. Once the + ``V4L2_BUF_FLAG_LAST`` flag was set, the + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, + but return an ``EPIPE`` error code. + + - .. row 3 + + - ``V4L2_ENC_CMD_PAUSE`` + + - 2 + + - Pause the encoder. When the encoder has not been started yet, the + driver will return an ``EPERM`` error code. When the encoder is + already paused, this command does nothing. No flags are defined + for this command. + + - .. row 4 + + - ``V4L2_ENC_CMD_RESUME`` + + - 3 + + - Resume encoding after a PAUSE command. When the encoder has not + been started yet, the driver will return an ``EPERM`` error code. When + the encoder is already running, this command does nothing. No + flags are defined for this command. + + + +.. _encoder-flags: + +.. flat-table:: Encoder Command Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_ENC_CMD_STOP_AT_GOP_END`` + + - 0x0001 + + - Stop encoding at the end of the current *Group Of Pictures*, + rather than immediately. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The ``cmd`` field is invalid. + +EPERM + The application sent a PAUSE or RESUME command when the encoder was + not running. diff --git a/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst new file mode 100644 index 000000000000..f0dd0c4ca7d0 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst @@ -0,0 +1,119 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUM_DV_TIMINGS: + +*********************************************************** +ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS +*********************************************************** + +Name +==== + +VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_enum_dv_timings *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS + +``argp`` + + +Description +=========== + +While some DV receivers or transmitters support a wide range of timings, +others support only a limited number of timings. With this ioctl +applications can enumerate a list of known supported timings. Call +:ref:`VIDIOC_DV_TIMINGS_CAP` to check if it +also supports other standards or even custom timings that are not in +this list. + +To query the available timings, applications initialize the ``index`` +field, set the ``pad`` field to 0, zero the reserved array of struct +:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` and call the +``VIDIOC_ENUM_DV_TIMINGS`` ioctl on a video node with a pointer to this +structure. Drivers fill the rest of the structure or return an ``EINVAL`` +error code when the index is out of bounds. To enumerate all supported +DV timings, applications shall begin at index zero, incrementing by one +until the driver returns ``EINVAL``. Note that drivers may enumerate a +different set of DV timings after switching the video input or output. + +When implemented by the driver DV timings of subdevices can be queried +by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a +subdevice node. The DV timings are specific to inputs (for DV receivers) +or outputs (for DV transmitters), applications must specify the desired +pad number in the struct +:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` ``pad`` field. +Attempts to enumerate timings on a pad that doesn't support them will +return an ``EINVAL`` error code. + + +.. _v4l2-enum-dv-timings: + +.. flat-table:: struct v4l2_enum_dv_timings + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Number of the DV timings, set by the application. + + - .. row 2 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media controller API. This field is + only used when operating on a subdevice node. When operating on a + video node applications must set this field to zero. + + - .. row 3 + + - __u32 + + - ``reserved``\ [2] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + - .. row 4 + + - struct :ref:`v4l2_dv_timings <v4l2-dv-timings>` + + - ``timings`` + + - The timings. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` + ``index`` is out of bounds or the ``pad`` number is invalid. + +ENODATA + Digital video presets are not supported for this input or output. diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst new file mode 100644 index 000000000000..257c624e27be --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst @@ -0,0 +1,164 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUM_FMT: + +********************* +ioctl VIDIOC_ENUM_FMT +********************* + +Name +==== + +VIDIOC_ENUM_FMT - Enumerate image formats + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_fmtdesc *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUM_FMT + +``argp`` + + +Description +=========== + +To enumerate image formats applications initialize the ``type`` and +``index`` field of struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` and call +the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers +fill the rest of the structure or return an ``EINVAL`` error code. All +formats are enumerable by beginning at index zero and incrementing by +one until ``EINVAL`` is returned. + +Note that after switching input or output the list of enumerated image +formats may be different. + + +.. _v4l2-fmtdesc: + +.. flat-table:: struct v4l2_fmtdesc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Number of the format in the enumeration, set by the application. + This is in no way related to the ``pixelformat`` field. + + - .. row 2 + + - __u32 + + - ``type`` + + - Type of the data stream, set by the application. Only these types + are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, + ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, + ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, + ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`. + + - .. row 3 + + - __u32 + + - ``flags`` + + - See :ref:`fmtdesc-flags` + + - .. row 4 + + - __u8 + + - ``description``\ [32] + + - Description of the format, a NUL-terminated ASCII string. This + information is intended for the user, for example: "YUV 4:2:2". + + - .. row 5 + + - __u32 + + - ``pixelformat`` + + - The image format identifier. This is a four character code as + computed by the v4l2_fourcc() macro: + + - .. row 6 + + - :cspan:`2` + + + .. _v4l2-fourcc: + .. code-block:: c + + #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) + + Several image formats are already defined by this specification in + :ref:`pixfmt`. Note these codes are not the same as those used + in the Windows world. + + - .. row 7 + + - __u32 + + - ``reserved``\ [4] + + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _fmtdesc-flags: + +.. flat-table:: Image Format Description Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_FMT_FLAG_COMPRESSED`` + + - 0x0001 + + - This is a compressed format. + + - .. row 2 + + - ``V4L2_FMT_FLAG_EMULATED`` + + - 0x0002 + + - This format is not native to the device but emulated through + software (usually libv4l2), where possible try to use a native + format instead for better performance. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` ``type`` is not + supported or the ``index`` is out of bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst new file mode 100644 index 000000000000..5d5de535a0fe --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst @@ -0,0 +1,274 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUM_FRAMEINTERVALS: + +******************************** +ioctl VIDIOC_ENUM_FRAMEINTERVALS +******************************** + +Name +==== + +VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmivalenum *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUM_FRAMEINTERVALS + +``argp`` + Pointer to a struct :ref:`v4l2_frmivalenum <v4l2-frmivalenum>` + structure that contains a pixel format and size and receives a frame + interval. + + +Description +=========== + +This ioctl allows applications to enumerate all frame intervals that the +device supports for the given pixel format and frame size. + +The supported pixel formats and frame sizes can be obtained by using the +:ref:`VIDIOC_ENUM_FMT` and +:ref:`VIDIOC_ENUM_FRAMESIZES` functions. + +The return value and the content of the ``v4l2_frmivalenum.type`` field +depend on the type of frame intervals the device supports. Here are the +semantics of the function for the different cases: + +- **Discrete:** The function returns success if the given index value + (zero-based) is valid. The application should increase the index by + one for each call until ``EINVAL`` is returned. The + `v4l2_frmivalenum.type` field is set to + `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only + the `discrete` member is valid. + +- **Step-wise:** The function returns success if the given index value + is zero and ``EINVAL`` for any other index value. The + ``v4l2_frmivalenum.type`` field is set to + ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the + ``stepwise`` member is valid. + +- **Continuous:** This is a special case of the step-wise type above. + The function returns success if the given index value is zero and + ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type`` + field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of + the union only the ``stepwise`` member is valid and the ``step`` + value is set to 1. + +When the application calls the function with index zero, it must check +the ``type`` field to determine the type of frame interval enumeration +the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type +does it make sense to increase the index value to receive more frame +intervals. + +Note that the order in which the frame intervals are returned has no +special meaning. In particular does it not say anything about potential +default frame intervals. + +Applications can assume that the enumeration data does not change +without any interaction from the application itself. This means that the +enumeration data is consistent if the application does not perform any +other ioctl calls while it runs the frame interval enumeration. + + +Notes +===== + +- **Frame intervals and frame rates:** The V4L2 API uses frame + intervals instead of frame rates. Given the frame interval the frame + rate can be computed as follows: + + + + :: + + frame_rate = 1 / frame_interval + + +Structs +======= + +In the structs below, *IN* denotes a value that has to be filled in by +the application, *OUT* denotes values that the driver fills in. The +application should zero out all members except for the *IN* fields. + + +.. _v4l2-frmival-stepwise: + +.. flat-table:: struct v4l2_frmival_stepwise + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``min`` + + - Minimum frame interval [s]. + + - .. row 2 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``max`` + + - Maximum frame interval [s]. + + - .. row 3 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``step`` + + - Frame interval step size [s]. + + + +.. _v4l2-frmivalenum: + +.. flat-table:: struct v4l2_frmivalenum + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``index`` + + - + - IN: Index of the given frame interval in the enumeration. + + - .. row 2 + + - __u32 + + - ``pixel_format`` + + - + - IN: Pixel format for which the frame intervals are enumerated. + + - .. row 3 + + - __u32 + + - ``width`` + + - + - IN: Frame width for which the frame intervals are enumerated. + + - .. row 4 + + - __u32 + + - ``height`` + + - + - IN: Frame height for which the frame intervals are enumerated. + + - .. row 5 + + - __u32 + + - ``type`` + + - + - OUT: Frame interval type the device supports. + + - .. row 6 + + - union + + - + - + - OUT: Frame interval with the given index. + + - .. row 7 + + - + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``discrete`` + + - Frame interval [s]. + + - .. row 8 + + - + - struct :ref:`v4l2_frmival_stepwise <v4l2-frmival-stepwise>` + + - ``stepwise`` + + - + + - .. row 9 + + - __u32 + + - ``reserved[2]`` + + - + - Reserved space for future use. Must be zeroed by drivers and + applications. + + + +Enums +===== + + +.. _v4l2-frmivaltypes: + +.. flat-table:: enum v4l2_frmivaltypes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_FRMIVAL_TYPE_DISCRETE`` + + - 1 + + - Discrete frame interval. + + - .. row 2 + + - ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` + + - 2 + + - Continuous frame interval. + + - .. row 3 + + - ``V4L2_FRMIVAL_TYPE_STEPWISE`` + + - 3 + + - Step-wise defined frame interval. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst new file mode 100644 index 000000000000..d3b2e97df6c9 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst @@ -0,0 +1,291 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUM_FRAMESIZES: + +**************************** +ioctl VIDIOC_ENUM_FRAMESIZES +**************************** + +Name +==== + +VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmsizeenum *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUM_FRAMESIZES + +``argp`` + Pointer to a struct :ref:`v4l2_frmsizeenum <v4l2-frmsizeenum>` + that contains an index and pixel format and receives a frame width + and height. + + +Description +=========== + +This ioctl allows applications to enumerate all frame sizes (i. e. width +and height in pixels) that the device supports for the given pixel +format. + +The supported pixel formats can be obtained by using the +:ref:`VIDIOC_ENUM_FMT` function. + +The return value and the content of the ``v4l2_frmsizeenum.type`` field +depend on the type of frame sizes the device supports. Here are the +semantics of the function for the different cases: + +- **Discrete:** The function returns success if the given index value + (zero-based) is valid. The application should increase the index by + one for each call until ``EINVAL`` is returned. The + ``v4l2_frmsizeenum.type`` field is set to + ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the + ``discrete`` member is valid. + +- **Step-wise:** The function returns success if the given index value + is zero and ``EINVAL`` for any other index value. The + ``v4l2_frmsizeenum.type`` field is set to + ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the + ``stepwise`` member is valid. + +- **Continuous:** This is a special case of the step-wise type above. + The function returns success if the given index value is zero and + ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type`` + field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of + the union only the ``stepwise`` member is valid and the + ``step_width`` and ``step_height`` values are set to 1. + +When the application calls the function with index zero, it must check +the ``type`` field to determine the type of frame size enumeration the +device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does +it make sense to increase the index value to receive more frame sizes. + +Note that the order in which the frame sizes are returned has no special +meaning. In particular does it not say anything about potential default +format sizes. + +Applications can assume that the enumeration data does not change +without any interaction from the application itself. This means that the +enumeration data is consistent if the application does not perform any +other ioctl calls while it runs the frame size enumeration. + + +Structs +======= + +In the structs below, *IN* denotes a value that has to be filled in by +the application, *OUT* denotes values that the driver fills in. The +application should zero out all members except for the *IN* fields. + + +.. _v4l2-frmsize-discrete: + +.. flat-table:: struct v4l2_frmsize_discrete + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``width`` + + - Width of the frame [pixel]. + + - .. row 2 + + - __u32 + + - ``height`` + + - Height of the frame [pixel]. + + + +.. _v4l2-frmsize-stepwise: + +.. flat-table:: struct v4l2_frmsize_stepwise + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``min_width`` + + - Minimum frame width [pixel]. + + - .. row 2 + + - __u32 + + - ``max_width`` + + - Maximum frame width [pixel]. + + - .. row 3 + + - __u32 + + - ``step_width`` + + - Frame width step size [pixel]. + + - .. row 4 + + - __u32 + + - ``min_height`` + + - Minimum frame height [pixel]. + + - .. row 5 + + - __u32 + + - ``max_height`` + + - Maximum frame height [pixel]. + + - .. row 6 + + - __u32 + + - ``step_height`` + + - Frame height step size [pixel]. + + + +.. _v4l2-frmsizeenum: + +.. flat-table:: struct v4l2_frmsizeenum + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``index`` + + - + - IN: Index of the given frame size in the enumeration. + + - .. row 2 + + - __u32 + + - ``pixel_format`` + + - + - IN: Pixel format for which the frame sizes are enumerated. + + - .. row 3 + + - __u32 + + - ``type`` + + - + - OUT: Frame size type the device supports. + + - .. row 4 + + - union + + - + - + - OUT: Frame size with the given index. + + - .. row 5 + + - + - struct :ref:`v4l2_frmsize_discrete <v4l2-frmsize-discrete>` + + - ``discrete`` + + - + + - .. row 6 + + - + - struct :ref:`v4l2_frmsize_stepwise <v4l2-frmsize-stepwise>` + + - ``stepwise`` + + - + + - .. row 7 + + - __u32 + + - ``reserved[2]`` + + - + - Reserved space for future use. Must be zeroed by drivers and + applications. + + + +Enums +===== + + +.. _v4l2-frmsizetypes: + +.. flat-table:: enum v4l2_frmsizetypes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_FRMSIZE_TYPE_DISCRETE`` + + - 1 + + - Discrete frame size. + + - .. row 2 + + - ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` + + - 2 + + - Continuous frame size. + + - .. row 3 + + - ``V4L2_FRMSIZE_TYPE_STEPWISE`` + + - 3 + + - Step-wise defined frame size. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst new file mode 100644 index 000000000000..ea754f4f5532 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst @@ -0,0 +1,190 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUM_FREQ_BANDS: + +**************************** +ioctl VIDIOC_ENUM_FREQ_BANDS +**************************** + +Name +==== + +VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency_band *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUM_FREQ_BANDS + +``argp`` + + +Description +=========== + +Enumerates the frequency bands that a tuner or modulator supports. To do +this applications initialize the ``tuner``, ``type`` and ``index`` +fields, and zero out the ``reserved`` array of a struct +:ref:`v4l2_frequency_band <v4l2-frequency-band>` and call the +:ref:`VIDIOC_ENUM_FREQ_BANDS` ioctl with a pointer to this structure. + +This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability +of the corresponding tuner/modulator is set. + + +.. _v4l2-frequency-band: + +.. flat-table:: struct v4l2_frequency_band + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 1 + + + - .. row 1 + + - __u32 + + - ``tuner`` + + - The tuner or modulator index number. This is the same value as in + the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and + the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or + the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field + and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index`` + field. + + - .. row 2 + + - __u32 + + - ``type`` + + - The tuner type. This is the same value as in the struct + :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be + set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and + to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to + ``V4L2_TUNER_RADIO`` for modulators (currently only radio + modulators are supported). See :ref:`v4l2-tuner-type` + + - .. row 3 + + - __u32 + + - ``index`` + + - Identifies the frequency band, set by the application. + + - .. row 4 + + - __u32 + + - ``capability`` + + - :cspan:`2` The tuner/modulator capability flags for this + frequency band, see :ref:`tuner-capability`. The + ``V4L2_TUNER_CAP_LOW`` or ``V4L2_TUNER_CAP_1HZ`` capability must + be the same for all frequency bands of the selected + tuner/modulator. So either all bands have that capability set, or + none of them have that capability. + + - .. row 5 + + - __u32 + + - ``rangelow`` + + - :cspan:`2` The lowest tunable frequency in units of 62.5 kHz, or + if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units + of 62.5 Hz, for this frequency band. A 1 Hz unit is used when the + ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set. + + - .. row 6 + + - __u32 + + - ``rangehigh`` + + - :cspan:`2` The highest tunable frequency in units of 62.5 kHz, + or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in + units of 62.5 Hz, for this frequency band. A 1 Hz unit is used + when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set. + + - .. row 7 + + - __u32 + + - ``modulation`` + + - :cspan:`2` The supported modulation systems of this frequency + band. See :ref:`band-modulation`. Note that currently only one + modulation system per frequency band is supported. More work will + need to be done if multiple modulation systems are possible. + Contact the linux-media mailing list + (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__) + if you need that functionality. + + - .. row 8 + + - __u32 + + - ``reserved``\ [9] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + + +.. _band-modulation: + +.. flat-table:: Band Modulation Systems + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_BAND_MODULATION_VSB`` + + - 0x02 + + - Vestigial Sideband modulation, used for analog TV. + + - .. row 2 + + - ``V4L2_BAND_MODULATION_FM`` + + - 0x04 + + - Frequency Modulation, commonly used for analog radio. + + - .. row 3 + + - ``V4L2_BAND_MODULATION_AM`` + + - 0x08 + + - Amplitude Modulation, commonly used for analog radio. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The ``tuner`` or ``index`` is out of bounds or the ``type`` field is + wrong. diff --git a/Documentation/media/uapi/v4l/vidioc-enumaudio.rst b/Documentation/media/uapi/v4l/vidioc-enumaudio.rst new file mode 100644 index 000000000000..bfdc3533240d --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enumaudio.rst @@ -0,0 +1,56 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUMAUDIO: + +********************** +ioctl VIDIOC_ENUMAUDIO +********************** + +Name +==== + +VIDIOC_ENUMAUDIO - Enumerate audio inputs + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audio *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUMAUDIO + +``argp`` + + +Description +=========== + +To query the attributes of an audio input applications initialize the +``index`` field and zero out the ``reserved`` array of a struct +:ref:`v4l2_audio <v4l2-audio>` and call the :ref:`VIDIOC_ENUMAUDIO` +ioctl with a pointer to this structure. Drivers fill the rest of the +structure or return an ``EINVAL`` error code when the index is out of +bounds. To enumerate all audio inputs applications shall begin at index +zero, incrementing by one until the driver returns ``EINVAL``. + +See :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` for a description of struct +:ref:`v4l2_audio <v4l2-audio>`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The number of the audio input is out of bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst new file mode 100644 index 000000000000..15bc5a40f4a6 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUMAUDOUT: + +*********************** +ioctl VIDIOC_ENUMAUDOUT +*********************** + +Name +==== + +VIDIOC_ENUMAUDOUT - Enumerate audio outputs + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUMAUDOUT + +``argp`` + + +Description +=========== + +To query the attributes of an audio output applications initialize the +``index`` field and zero out the ``reserved`` array of a struct +:ref:`v4l2_audioout <v4l2-audioout>` and call the ``VIDIOC_G_AUDOUT`` +ioctl with a pointer to this structure. Drivers fill the rest of the +structure or return an ``EINVAL`` error code when the index is out of +bounds. To enumerate all audio outputs applications shall begin at index +zero, incrementing by one until the driver returns ``EINVAL``. + +Note connectors on a TV card to loop back the received audio signal to a +sound card are not audio outputs in this sense. + +See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct +:ref:`v4l2_audioout <v4l2-audioout>`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The number of the audio output is out of bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst new file mode 100644 index 000000000000..c1fc2e1f1d98 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst @@ -0,0 +1,367 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUMINPUT: + +********************** +ioctl VIDIOC_ENUMINPUT +********************** + +Name +==== + +VIDIOC_ENUMINPUT - Enumerate video inputs + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_input *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUMINPUT + +``argp`` + + +Description +=========== + +To query the attributes of a video input applications initialize the +``index`` field of struct :ref:`v4l2_input <v4l2-input>` and call the +:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers +fill the rest of the structure or return an ``EINVAL`` error code when the +index is out of bounds. To enumerate all inputs applications shall begin +at index zero, incrementing by one until the driver returns ``EINVAL``. + + +.. _v4l2-input: + +.. flat-table:: struct v4l2_input + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Identifies the input, set by the application. + + - .. row 2 + + - __u8 + + - ``name``\ [32] + + - Name of the video input, a NUL-terminated ASCII string, for + example: "Vin (Composite 2)". This information is intended for the + user, preferably the connector label on the device itself. + + - .. row 3 + + - __u32 + + - ``type`` + + - Type of the input, see :ref:`input-type`. + + - .. row 4 + + - __u32 + + - ``audioset`` + + - Drivers can enumerate up to 32 video and audio inputs. This field + shows which audio inputs were selectable as audio source if this + was the currently selected video input. It is a bit mask. The LSB + corresponds to audio input 0, the MSB to input 31. Any number of + bits can be set, or none. + + When the driver does not enumerate audio inputs no bits must be + set. Applications shall not interpret this as lack of audio + support. Some drivers automatically select audio sources and do + not enumerate them since there is no choice anyway. + + For details on audio inputs and how to select the current input + see :ref:`audio`. + + - .. row 5 + + - __u32 + + - ``tuner`` + + - Capture devices can have zero or more tuners (RF demodulators). + When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an + RF connector and this field identifies the tuner. It corresponds + to struct :ref:`v4l2_tuner <v4l2-tuner>` field ``index``. For + details on tuners see :ref:`tuner`. + + - .. row 6 + + - :ref:`v4l2_std_id <v4l2-std-id>` + + - ``std`` + + - Every video input supports one or more different video standards. + This field is a set of all supported standards. For details on + video standards and how to switch see :ref:`standard`. + + - .. row 7 + + - __u32 + + - ``status`` + + - This field provides status information about the input. See + :ref:`input-status` for flags. With the exception of the sensor + orientation bits ``status`` is only valid when this is the current + input. + + - .. row 8 + + - __u32 + + - ``capabilities`` + + - This field provides capabilities for the input. See + :ref:`input-capabilities` for flags. + + - .. row 9 + + - __u32 + + - ``reserved``\ [3] + + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _input-type: + +.. flat-table:: Input Types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_INPUT_TYPE_TUNER`` + + - 1 + + - This input uses a tuner (RF demodulator). + + - .. row 2 + + - ``V4L2_INPUT_TYPE_CAMERA`` + + - 2 + + - Analog baseband input, for example CVBS / Composite Video, + S-Video, RGB. + + + +.. _input-status: + +.. flat-table:: Input Status Flags + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - :cspan:`2` General + + - .. row 2 + + - ``V4L2_IN_ST_NO_POWER`` + + - 0x00000001 + + - Attached device is off. + + - .. row 3 + + - ``V4L2_IN_ST_NO_SIGNAL`` + + - 0x00000002 + + - + + - .. row 4 + + - ``V4L2_IN_ST_NO_COLOR`` + + - 0x00000004 + + - The hardware supports color decoding, but does not detect color + modulation in the signal. + + - .. row 5 + + - :cspan:`2` Sensor Orientation + + - .. row 6 + + - ``V4L2_IN_ST_HFLIP`` + + - 0x00000010 + + - The input is connected to a device that produces a signal that is + flipped horizontally and does not correct this before passing the + signal to userspace. + + - .. row 7 + + - ``V4L2_IN_ST_VFLIP`` + + - 0x00000020 + + - The input is connected to a device that produces a signal that is + flipped vertically and does not correct this before passing the + signal to userspace. Note that a 180 degree rotation is the same + as HFLIP | VFLIP + + - .. row 8 + + - :cspan:`2` Analog Video + + - .. row 9 + + - ``V4L2_IN_ST_NO_H_LOCK`` + + - 0x00000100 + + - No horizontal sync lock. + + - .. row 10 + + - ``V4L2_IN_ST_COLOR_KILL`` + + - 0x00000200 + + - A color killer circuit automatically disables color decoding when + it detects no color modulation. When this flag is set the color + killer is enabled *and* has shut off color decoding. + + - .. row 11 + + - :cspan:`2` Digital Video + + - .. row 12 + + - ``V4L2_IN_ST_NO_SYNC`` + + - 0x00010000 + + - No synchronization lock. + + - .. row 13 + + - ``V4L2_IN_ST_NO_EQU`` + + - 0x00020000 + + - No equalizer lock. + + - .. row 14 + + - ``V4L2_IN_ST_NO_CARRIER`` + + - 0x00040000 + + - Carrier recovery failed. + + - .. row 15 + + - :cspan:`2` VCR and Set-Top Box + + - .. row 16 + + - ``V4L2_IN_ST_MACROVISION`` + + - 0x01000000 + + - Macrovision is an analog copy prevention system mangling the video + signal to confuse video recorders. When this flag is set + Macrovision has been detected. + + - .. row 17 + + - ``V4L2_IN_ST_NO_ACCESS`` + + - 0x02000000 + + - Conditional access denied. + + - .. row 18 + + - ``V4L2_IN_ST_VTR`` + + - 0x04000000 + + - VTR time constant. [?] + + + +.. _input-capabilities: + +.. flat-table:: Input capabilities + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_IN_CAP_DV_TIMINGS`` + + - 0x00000002 + + - This input supports setting video timings by using + VIDIOC_S_DV_TIMINGS. + + - .. row 2 + + - ``V4L2_IN_CAP_STD`` + + - 0x00000004 + + - This input supports setting the TV standard by using + VIDIOC_S_STD. + + - .. row 3 + + - ``V4L2_IN_CAP_NATIVE_SIZE`` + + - 0x00000008 + + - This input supports setting the native size using the + ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see + :ref:`v4l2-selections-common`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_input <v4l2-input>` ``index`` is out of + bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst new file mode 100644 index 000000000000..82fc9d3b237f --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst @@ -0,0 +1,222 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUMOUTPUT: + +*********************** +ioctl VIDIOC_ENUMOUTPUT +*********************** + +Name +==== + +VIDIOC_ENUMOUTPUT - Enumerate video outputs + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_output *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUMOUTPUT + +``argp`` + + +Description +=========== + +To query the attributes of a video outputs applications initialize the +``index`` field of struct :ref:`v4l2_output <v4l2-output>` and call +the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure. +Drivers fill the rest of the structure or return an ``EINVAL`` error code +when the index is out of bounds. To enumerate all outputs applications +shall begin at index zero, incrementing by one until the driver returns +EINVAL. + + +.. _v4l2-output: + +.. flat-table:: struct v4l2_output + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Identifies the output, set by the application. + + - .. row 2 + + - __u8 + + - ``name``\ [32] + + - Name of the video output, a NUL-terminated ASCII string, for + example: "Vout". This information is intended for the user, + preferably the connector label on the device itself. + + - .. row 3 + + - __u32 + + - ``type`` + + - Type of the output, see :ref:`output-type`. + + - .. row 4 + + - __u32 + + - ``audioset`` + + - Drivers can enumerate up to 32 video and audio outputs. This field + shows which audio outputs were selectable as the current output if + this was the currently selected video output. It is a bit mask. + The LSB corresponds to audio output 0, the MSB to output 31. Any + number of bits can be set, or none. + + When the driver does not enumerate audio outputs no bits must be + set. Applications shall not interpret this as lack of audio + support. Drivers may automatically select audio outputs without + enumerating them. + + For details on audio outputs and how to select the current output + see :ref:`audio`. + + - .. row 5 + + - __u32 + + - ``modulator`` + + - Output devices can have zero or more RF modulators. When the + ``type`` is ``V4L2_OUTPUT_TYPE_MODULATOR`` this is an RF connector + and this field identifies the modulator. It corresponds to struct + :ref:`v4l2_modulator <v4l2-modulator>` field ``index``. For + details on modulators see :ref:`tuner`. + + - .. row 6 + + - :ref:`v4l2_std_id <v4l2-std-id>` + + - ``std`` + + - Every video output supports one or more different video standards. + This field is a set of all supported standards. For details on + video standards and how to switch see :ref:`standard`. + + - .. row 7 + + - __u32 + + - ``capabilities`` + + - This field provides capabilities for the output. See + :ref:`output-capabilities` for flags. + + - .. row 8 + + - __u32 + + - ``reserved``\ [3] + + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _output-type: + +.. flat-table:: Output Type + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_OUTPUT_TYPE_MODULATOR`` + + - 1 + + - This output is an analog TV modulator. + + - .. row 2 + + - ``V4L2_OUTPUT_TYPE_ANALOG`` + + - 2 + + - Analog baseband output, for example Composite / CVBS, S-Video, + RGB. + + - .. row 3 + + - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY`` + + - 3 + + - [?] + + + +.. _output-capabilities: + +.. flat-table:: Output capabilities + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_OUT_CAP_DV_TIMINGS`` + + - 0x00000002 + + - This output supports setting video timings by using + VIDIOC_S_DV_TIMINGS. + + - .. row 2 + + - ``V4L2_OUT_CAP_STD`` + + - 0x00000004 + + - This output supports setting the TV standard by using + VIDIOC_S_STD. + + - .. row 3 + + - ``V4L2_OUT_CAP_NATIVE_SIZE`` + + - 0x00000008 + + - This output supports setting the native size using the + ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see + :ref:`v4l2-selections-common`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_output <v4l2-output>` ``index`` is out of + bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-enumstd.rst b/Documentation/media/uapi/v4l/vidioc-enumstd.rst new file mode 100644 index 000000000000..ce911c81bd3d --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-enumstd.rst @@ -0,0 +1,442 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_ENUMSTD: + +******************** +ioctl VIDIOC_ENUMSTD +******************** + +Name +==== + +VIDIOC_ENUMSTD - Enumerate supported video standards + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_standard *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_ENUMSTD + +``argp`` + + +Description +=========== + +To query the attributes of a video standard, especially a custom (driver +defined) one, applications initialize the ``index`` field of struct +:ref:`v4l2_standard <v4l2-standard>` and call the :ref:`VIDIOC_ENUMSTD` +ioctl with a pointer to this structure. Drivers fill the rest of the +structure or return an ``EINVAL`` error code when the index is out of +bounds. To enumerate all standards applications shall begin at index +zero, incrementing by one until the driver returns ``EINVAL``. Drivers may +enumerate a different set of standards after switching the video input +or output. [1]_ + + +.. _v4l2-standard: + +.. flat-table:: struct v4l2_standard + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Number of the video standard, set by the application. + + - .. row 2 + + - :ref:`v4l2_std_id <v4l2-std-id>` + + - ``id`` + + - The bits in this field identify the standard as one of the common + standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are + set as custom standards. Multiple bits can be set if the hardware + does not distinguish between these standards, however separate + indices do not indicate the opposite. The ``id`` must be unique. + No other enumerated :ref:`struct v4l2_standard <v4l2-standard>` structure, + for this input or output anyway, can contain the same set of bits. + + - .. row 3 + + - __u8 + + - ``name``\ [24] + + - Name of the standard, a NUL-terminated ASCII string, for example: + "PAL-B/G", "NTSC Japan". This information is intended for the + user. + + - .. row 4 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``frameperiod`` + + - The frame period (not field period) is numerator / denominator. + For example M/NTSC has a frame period of 1001 / 30000 seconds. + + - .. row 5 + + - __u32 + + - ``framelines`` + + - Total lines per frame including blanking, e. g. 625 for B/PAL. + + - .. row 6 + + - __u32 + + - ``reserved``\ [4] + + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _v4l2-fract: + +.. flat-table:: struct v4l2_fract + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``numerator`` + + - + + - .. row 2 + + - __u32 + + - ``denominator`` + + - + + + +.. _v4l2-std-id: + +.. flat-table:: typedef v4l2_std_id + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u64 + + - ``v4l2_std_id`` + + - This type is a set, each bit representing another video standard + as listed below and in :ref:`video-standards`. The 32 most + significant bits are reserved for custom (driver defined) video + standards. + + + +.. code-block:: c + + #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) + #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) + #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) + #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) + #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) + #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) + #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) + #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) + + #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) + #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) + #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) + #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) + +``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh +rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some +PAL video recorders can play back NTSC tapes in this mode for display on +a 50/60 Hz agnostic PAL TV. + + +.. code-block:: c + + #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) + #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) + #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000) + +``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh +rate, and NTSC color modulation with a 4.43 MHz color subcarrier. + + +.. code-block:: c + + #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) + + #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) + #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) + #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) + #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) + #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) + #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) + #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) + #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000) + + /* ATSC/HDTV */ + #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) + #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) + +``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S. +terrestrial digital TV standards. Presently the V4L2 API does not +support digital TV. See also the Linux DVB API at +`https://linuxtv.org <https://linuxtv.org>`__. + + +.. code-block:: c + + #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B | + V4L2_STD_PAL_B1 | + V4L2_STD_PAL_G) + #define V4L2_STD_B (V4L2_STD_PAL_B | + V4L2_STD_PAL_B1 | + V4L2_STD_SECAM_B) + #define V4L2_STD_GH (V4L2_STD_PAL_G | + V4L2_STD_PAL_H | + V4L2_STD_SECAM_G | + V4L2_STD_SECAM_H) + #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D | + V4L2_STD_PAL_D1 | + V4L2_STD_PAL_K) + #define V4L2_STD_PAL (V4L2_STD_PAL_BG | + V4L2_STD_PAL_DK | + V4L2_STD_PAL_H | + V4L2_STD_PAL_I) + #define V4L2_STD_NTSC (V4L2_STD_NTSC_M | + V4L2_STD_NTSC_M_JP | + V4L2_STD_NTSC_M_KR) + #define V4L2_STD_MN (V4L2_STD_PAL_M | + V4L2_STD_PAL_N | + V4L2_STD_PAL_Nc | + V4L2_STD_NTSC) + #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D | + V4L2_STD_SECAM_K | + V4L2_STD_SECAM_K1) + #define V4L2_STD_DK (V4L2_STD_PAL_DK | + V4L2_STD_SECAM_DK) + + #define V4L2_STD_SECAM (V4L2_STD_SECAM_B | + V4L2_STD_SECAM_G | + V4L2_STD_SECAM_H | + V4L2_STD_SECAM_DK | + V4L2_STD_SECAM_L | + V4L2_STD_SECAM_LC) + + #define V4L2_STD_525_60 (V4L2_STD_PAL_M | + V4L2_STD_PAL_60 | + V4L2_STD_NTSC | + V4L2_STD_NTSC_443) + #define V4L2_STD_625_50 (V4L2_STD_PAL | + V4L2_STD_PAL_N | + V4L2_STD_PAL_Nc | + V4L2_STD_SECAM) + + #define V4L2_STD_UNKNOWN 0 + #define V4L2_STD_ALL (V4L2_STD_525_60 | + V4L2_STD_625_50) + + +.. _video-standards: + +.. flat-table:: Video Standards (based on []) + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Characteristics + + - M/NTSC [2]_ + + - M/PAL + + - N/PAL [3]_ + + - B, B1, G/PAL + + - D, D1, K/PAL + + - H/PAL + + - I/PAL + + - B, G/SECAM + + - D, K/SECAM + + - K1/SECAM + + - L/SECAM + + - .. row 2 + + - Frame lines + + - :cspan:`1` 525 + + - :cspan:`9` 625 + + - .. row 3 + + - Frame period (s) + + - :cspan:`1` 1001/30000 + + - :cspan:`9` 1/25 + + - .. row 4 + + - Chrominance sub-carrier frequency (Hz) + + - 3579545 ± 10 + + - 3579611.49 ± 10 + + - 4433618.75 ± 5 (3582056.25 ± 5) + + - :cspan:`3` 4433618.75 ± 5 + + - 4433618.75 ± 1 + + - :cspan:`3` f\ :sub:`OR` = 4406250 ± 2000, f\ :sub:`OB` = 4250000 + ± 2000 + + - .. row 5 + + - Nominal radio-frequency channel bandwidth (MHz) + + - 6 + + - 6 + + - 6 + + - B: 7; B1, G: 8 + + - 8 + + - 8 + + - 8 + + - 8 + + - 8 + + - 8 + + - 8 + + - .. row 6 + + - Sound carrier relative to vision carrier (MHz) + + - + 4.5 + + - + 4.5 + + - + 4.5 + + - + 5.5 ± 0.001 [4]_ [5]_ [6]_ [7]_ + + - + 6.5 ± 0.001 + + - + 5.5 + + - + 5.9996 ± 0.0005 + + - + 5.5 ± 0.001 + + - + 6.5 ± 0.001 + + - + 6.5 + + - + 6.5 [8]_ + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_standard <v4l2-standard>` ``index`` is out + of bounds. + +ENODATA + Standard video timings are not supported for this input or output. + +.. [1] + The supported standards may overlap and we need an unambiguous set to + find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`. + +.. [2] + Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP). + +.. [3] + The values in brackets apply to the combination N/PAL a.k.a. + N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc). + +.. [4] + In the Federal Republic of Germany, Austria, Italy, the Netherlands, + Slovakia and Switzerland a system of two sound carriers is used, the + frequency of the second carrier being 242.1875 kHz above the + frequency of the first sound carrier. For stereophonic sound + transmissions a similar system is used in Australia. + +.. [5] + New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from + the vision carrier. + +.. [6] + In Denmark, Finland, New Zealand, Sweden and Spain a system of two + sound carriers is used. In Iceland, Norway and Poland the same system + is being introduced. The second carrier is 5.85 MHz above the vision + carrier and is DQPSK modulated with 728 kbit/s sound and data + multiplex. (NICAM system) + +.. [7] + In the United Kingdom, a system of two sound carriers is used. The + second sound carrier is 6.552 MHz above the vision carrier and is + DQPSK modulated with a 728 kbit/s sound and data multiplex able to + carry two sound channels. (NICAM system) + +.. [8] + In France, a digital carrier 5.85 MHz away from the vision carrier + may be used in addition to the main sound carrier. It is modulated in + differentially encoded QPSK with a 728 kbit/s sound and data + multiplexer capable of carrying two sound channels. (NICAM system) diff --git a/Documentation/media/uapi/v4l/vidioc-expbuf.rst b/Documentation/media/uapi/v4l/vidioc-expbuf.rst new file mode 100644 index 000000000000..ded708e647fa --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-expbuf.rst @@ -0,0 +1,197 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_EXPBUF: + +******************* +ioctl VIDIOC_EXPBUF +******************* + +Name +==== + +VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor. + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_exportbuffer *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_EXPBUF + +``argp`` + + +Description +=========== + +This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O +method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers. +It can be used to export a buffer as a DMABUF file at any time after +buffers have been allocated with the +:ref:`VIDIOC_REQBUFS` ioctl. + +To export a buffer, applications fill struct +:ref:`v4l2_exportbuffer <v4l2-exportbuffer>`. The ``type`` field is +set to the same buffer type as was previously used with struct +:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``. +Applications must also set the ``index`` field. Valid index numbers +range from zero to the number of buffers allocated with +:ref:`VIDIOC_REQBUFS` (struct +:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus +one. For the multi-planar API, applications set the ``plane`` field to +the index of the plane to be exported. Valid planes range from zero to +the maximal number of valid planes for the currently active format. For +the single-planar API, applications must set ``plane`` to zero. +Additional flags may be posted in the ``flags`` field. Refer to a manual +for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, +and O_RDWR are supported. All other fields must be set to zero. In the +case of multi-planar API, every plane is exported separately using +multiple :ref:`VIDIOC_EXPBUF` calls. + +After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a +driver. This is a DMABUF file descriptor. The application may pass it to +other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>` +for details about importing DMABUF files into V4L2 nodes. It is +recommended to close a DMABUF file when it is no longer used to allow +the associated memory to be reclaimed. + + +Examples +======== + + +.. code-block:: c + + int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd) + { + struct v4l2_exportbuffer expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) { + perror("VIDIOC_EXPBUF"); + return -1; + } + + *dmafd = expbuf.fd; + + return 0; + } + + +.. code-block:: c + + int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index, + int dmafd[], int n_planes) + { + int i; + + for (i = 0; i < n_planes; ++i) { + struct v4l2_exportbuffer expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + expbuf.plane = i; + if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) { + perror("VIDIOC_EXPBUF"); + while (i) + close(dmafd[--i]); + return -1; + } + dmafd[i] = expbuf.fd; + } + + return 0; + } + + +.. _v4l2-exportbuffer: + +.. flat-table:: struct v4l2_exportbuffer + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - Type of the buffer, same as struct + :ref:`v4l2_format <v4l2-format>` ``type`` or struct + :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set + by the application. See :ref:`v4l2-buf-type` + + - .. row 2 + + - __u32 + + - ``index`` + + - Number of the buffer, set by the application. This field is only + used for :ref:`memory mapping <mmap>` I/O and can range from + zero to the number of buffers allocated with the + :ref:`VIDIOC_REQBUFS` and/or + :ref:`VIDIOC_CREATE_BUFS` ioctls. + + - .. row 3 + + - __u32 + + - ``plane`` + + - Index of the plane to be exported when using the multi-planar API. + Otherwise this value must be set to zero. + + - .. row 4 + + - __u32 + + - ``flags`` + + - Flags for the newly created file, currently only ``O_CLOEXEC``, + ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to + the manual of open() for more details. + + - .. row 5 + + - __s32 + + - ``fd`` + + - The DMABUF file descriptor associated with a buffer. Set by the + driver. + + - .. row 6 + + - __u32 + + - ``reserved[11]`` + + - Reserved field for future use. Drivers and applications must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + A queue is not in MMAP mode or DMABUF exporting is not supported or + ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid. diff --git a/Documentation/media/uapi/v4l/vidioc-g-audio.rst b/Documentation/media/uapi/v4l/vidioc-g-audio.rst new file mode 100644 index 000000000000..cccbcdb8c463 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-audio.rst @@ -0,0 +1,162 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_AUDIO: + +************************************ +ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO +************************************ + +Name +==== + +VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audio *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audio *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_AUDIO, VIDIOC_S_AUDIO + +``argp`` + + +Description +=========== + +To query the current audio input applications zero out the ``reserved`` +array of a struct :ref:`v4l2_audio <v4l2-audio>` and call the +:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl with a pointer to this structure. Drivers fill +the rest of the structure or return an ``EINVAL`` error code when the device +has no audio inputs, or none which combine with the current video input. + +Audio inputs have one writable property, the audio mode. To select the +current audio input *and* change the audio mode, applications initialize +the ``index`` and ``mode`` fields, and the ``reserved`` array of a +:ref:`struct v4l2_audio <v4l2-audio>` structure and call the :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` +ioctl. Drivers may switch to a different audio mode if the request +cannot be satisfied. However, this is a write-only ioctl, it does not +return the actual new audio mode. + + +.. _v4l2-audio: + +.. flat-table:: struct v4l2_audio + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Identifies the audio input, set by the driver or application. + + - .. row 2 + + - __u8 + + - ``name``\ [32] + + - Name of the audio input, a NUL-terminated ASCII string, for + example: "Line In". This information is intended for the user, + preferably the connector label on the device itself. + + - .. row 3 + + - __u32 + + - ``capability`` + + - Audio capability flags, see :ref:`audio-capability`. + + - .. row 4 + + - __u32 + + - ``mode`` + + - Audio mode flags set by drivers and applications (on + :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`. + + - .. row 5 + + - __u32 + + - ``reserved``\ [2] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. _audio-capability: + +.. flat-table:: Audio Capability Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_AUDCAP_STEREO`` + + - 0x00001 + + - This is a stereo input. The flag is intended to automatically + disable stereo recording etc. when the signal is always monaural. + The API provides no means to detect if stereo is *received*, + unless the audio input belongs to a tuner. + + - .. row 2 + + - ``V4L2_AUDCAP_AVL`` + + - 0x00002 + + - Automatic Volume Level mode is supported. + + + +.. _audio-mode: + +.. flat-table:: Audio Mode Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_AUDMODE_AVL`` + + - 0x00001 + + - AVL mode is on. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + No audio inputs combine with the current video input, or the number + of the selected audio input is out of bounds or it does not combine. diff --git a/Documentation/media/uapi/v4l/vidioc-g-audioout.rst b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst new file mode 100644 index 000000000000..bee5f78ed7c1 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst @@ -0,0 +1,122 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_AUDOUT: + +************************************** +ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT +************************************** + +Name +==== + +VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audioout *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT + +``argp`` + + +Description +=========== + +To query the current audio output applications zero out the ``reserved`` +array of a struct :ref:`v4l2_audioout <v4l2-audioout>` and call the +``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill +the rest of the structure or return an ``EINVAL`` error code when the device +has no audio inputs, or none which combine with the current video +output. + +Audio outputs have no writable properties. Nevertheless, to select the +current audio output applications can initialize the ``index`` field and +``reserved`` array (which in the future may contain writable properties) +of a :ref:`struct v4l2_audioout <v4l2-audioout>` structure and call the +``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or +return the ``EINVAL`` error code when the index is out of bounds. This is a +write-only ioctl, it does not return the current audio output attributes +as ``VIDIOC_G_AUDOUT`` does. + +Note connectors on a TV card to loop back the received audio signal to a +sound card are not audio outputs in this sense. + + +.. _v4l2-audioout: + +.. flat-table:: struct v4l2_audioout + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Identifies the audio output, set by the driver or application. + + - .. row 2 + + - __u8 + + - ``name``\ [32] + + - Name of the audio output, a NUL-terminated ASCII string, for + example: "Line Out". This information is intended for the user, + preferably the connector label on the device itself. + + - .. row 3 + + - __u32 + + - ``capability`` + + - Audio capability flags, none defined yet. Drivers must set this + field to zero. + + - .. row 4 + + - __u32 + + - ``mode`` + + - Audio mode, none defined yet. Drivers and applications (on + ``VIDIOC_S_AUDOUT``) must set this field to zero. + + - .. row 5 + + - __u32 + + - ``reserved``\ [2] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + No audio outputs combine with the current video output, or the + number of the selected audio output is out of bounds or it does not + combine. diff --git a/Documentation/media/uapi/v4l/vidioc-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-g-crop.rst new file mode 100644 index 000000000000..6cf76497937c --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-crop.rst @@ -0,0 +1,113 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_CROP: + +********************************** +ioctl VIDIOC_G_CROP, VIDIOC_S_CROP +********************************** + +Name +==== + +VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_crop *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_crop *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_CROP, VIDIOC_S_CROP + +``argp`` + + +Description +=========== + +To query the cropping rectangle size and position applications set the +``type`` field of a :ref:`struct v4l2_crop <v4l2-crop>` structure to the +respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl +with a pointer to this structure. The driver fills the rest of the +structure or returns the ``EINVAL`` error code if cropping is not supported. + +To change the cropping rectangle applications initialize the ``type`` +and struct :ref:`v4l2_rect <v4l2-rect>` substructure named ``c`` of a +v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer +to this structure. + +Do not use the multiplanar buffer types. Use +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of +``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use +``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of +``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. + +The driver first adjusts the requested dimensions against hardware +limits, i. e. the bounds given by the capture/output window, and it +rounds to the closest possible values of horizontal and vertical offset, +width and height. In particular the driver must round the vertical +offset of the cropping rectangle to frame lines modulo two, such that +the field order cannot be confused. + +Second the driver adjusts the image size (the opposite rectangle of the +scaling process, source or target depending on the data direction) to +the closest size possible while maintaining the current horizontal and +vertical scaling factor. + +Finally the driver programs the hardware with the actual cropping and +image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not +return the actual parameters. To query them applications must call +:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the +parameters are unsuitable the application may modify the cropping or +image parameters and repeat the cycle until satisfactory parameters have +been negotiated. + +When cropping is not supported then no parameters are changed and +:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code. + + +.. _v4l2-crop: + +.. flat-table:: struct v4l2_crop + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - Type of the data stream, set by the application. Only these types + are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, + ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`. + + - .. row 2 + + - struct :ref:`v4l2_rect <v4l2-rect>` + + - ``c`` + + - Cropping rectangle. The same co-ordinate system as for struct + :ref:`v4l2_cropcap <v4l2-cropcap>` ``bounds`` is used. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst b/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst new file mode 100644 index 000000000000..ee929f692ebe --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst @@ -0,0 +1,105 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_CTRL: + +********************************** +ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL +********************************** + +Name +==== + +VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_control *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_CTRL, VIDIOC_S_CTRL + +``argp`` + + +Description +=========== + +To get the current value of a control applications initialize the ``id`` +field of a struct :ref:`struct v4l2_control <v4l2-control>` and call the +:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the +value of a control applications initialize the ``id`` and ``value`` +fields of a struct :ref:`struct v4l2_control <v4l2-control>` and call the +:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl. + +When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the +``value`` is out of bounds drivers can choose to take the closest valid +value or return an ``ERANGE`` error code, whatever seems more appropriate. +However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the +actual new value. If the ``value`` is inappropriate for the control +(e.g. if it refers to an unsupported menu index of a menu control), then +EINVAL error code is returned as well. + +These ioctls work only with user controls. For other control classes the +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, +:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or +:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used. + + +.. _v4l2-control: + +.. flat-table:: struct v4l2_control + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``id`` + + - Identifies the control, set by the application. + + - .. row 2 + + - __s32 + + - ``value`` + + - New value or current value. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_control <v4l2-control>` ``id`` is invalid + or the ``value`` is inappropriate for the given control (i.e. if a + menu item is selected that is not supported by the driver according + to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`). + +ERANGE + The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of + bounds. + +EBUSY + The control is temporarily not changeable, possibly because another + applications took over control of the device function this control + belongs to. + +EACCES + Attempt to set a read-only control or to get a write-only control. diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst new file mode 100644 index 000000000000..e19d64e0116a --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst @@ -0,0 +1,417 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_DV_TIMINGS: + +********************************************** +ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS +********************************************** + +Name +==== + +VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS, + VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS + +``argp`` + + +Description +=========== + +To set DV timings for the input or output, applications use the +:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings, +applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing +information is filled in using the structure struct +:ref:`v4l2_dv_timings <v4l2-dv-timings>`. These ioctls take a +pointer to the struct :ref:`v4l2_dv_timings <v4l2-dv-timings>` +structure as argument. If the ioctl is not supported or the timing +values are not correct, the driver returns ``EINVAL`` error code. + +The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of +the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If +the current input or output does not support DV timings (e.g. if +:ref:`VIDIOC_ENUMINPUT` does not set the +``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` + parameter was unsuitable. + +ENODATA + Digital video timings are not supported for this input or output. + +EBUSY + The device is busy and therefore can not change the timings. + + +.. _v4l2-bt-timings: + +.. flat-table:: struct v4l2_bt_timings + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``width`` + + - Width of the active video in pixels. + + - .. row 2 + + - __u32 + + - ``height`` + + - Height of the active video frame in lines. So for interlaced + formats the height of the active video in each field is + ``height``/2. + + - .. row 3 + + - __u32 + + - ``interlaced`` + + - Progressive (0) or interlaced (1) + + - .. row 4 + + - __u32 + + - ``polarities`` + + - This is a bit mask that defines polarities of sync signals. bit 0 + (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit + 1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If + the bit is set (1) it is positive polarity and if is cleared (0), + it is negative polarity. + + - .. row 5 + + - __u64 + + - ``pixelclock`` + + - Pixel clock in Hz. Ex. 74.25MHz->74250000 + + - .. row 6 + + - __u32 + + - ``hfrontporch`` + + - Horizontal front porch in pixels + + - .. row 7 + + - __u32 + + - ``hsync`` + + - Horizontal sync length in pixels + + - .. row 8 + + - __u32 + + - ``hbackporch`` + + - Horizontal back porch in pixels + + - .. row 9 + + - __u32 + + - ``vfrontporch`` + + - Vertical front porch in lines. For interlaced formats this refers + to the odd field (aka field 1). + + - .. row 10 + + - __u32 + + - ``vsync`` + + - Vertical sync length in lines. For interlaced formats this refers + to the odd field (aka field 1). + + - .. row 11 + + - __u32 + + - ``vbackporch`` + + - Vertical back porch in lines. For interlaced formats this refers + to the odd field (aka field 1). + + - .. row 12 + + - __u32 + + - ``il_vfrontporch`` + + - Vertical front porch in lines for the even field (aka field 2) of + interlaced field formats. Must be 0 for progressive formats. + + - .. row 13 + + - __u32 + + - ``il_vsync`` + + - Vertical sync length in lines for the even field (aka field 2) of + interlaced field formats. Must be 0 for progressive formats. + + - .. row 14 + + - __u32 + + - ``il_vbackporch`` + + - Vertical back porch in lines for the even field (aka field 2) of + interlaced field formats. Must be 0 for progressive formats. + + - .. row 15 + + - __u32 + + - ``standards`` + + - The video standard(s) this format belongs to. This will be filled + in by the driver. Applications must set this to 0. See + :ref:`dv-bt-standards` for a list of standards. + + - .. row 16 + + - __u32 + + - ``flags`` + + - Several flags giving more information about the format. See + :ref:`dv-bt-flags` for a description of the flags. + + + +.. _v4l2-dv-timings: + +.. flat-table:: struct v4l2_dv_timings + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 + + + - .. row 1 + + - __u32 + + - ``type`` + + - + - Type of DV timings as listed in :ref:`dv-timing-types`. + + - .. row 2 + + - union + + - + - + + - .. row 3 + + - + - struct :ref:`v4l2_bt_timings <v4l2-bt-timings>` + + - ``bt`` + + - Timings defined by BT.656/1120 specifications + + - .. row 4 + + - + - __u32 + + - ``reserved``\ [32] + + - + + + +.. _dv-timing-types: + +.. flat-table:: DV Timing types + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Timing type + + - value + + - Description + + - .. row 2 + + - + - + - + + - .. row 3 + + - ``V4L2_DV_BT_656_1120`` + + - 0 + + - BT.656/1120 timings + + + +.. _dv-bt-standards: + +.. flat-table:: DV BT Timing standards + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - Timing standard + + - Description + + - .. row 2 + + - + - + + - .. row 3 + + - ``V4L2_DV_BT_STD_CEA861`` + + - The timings follow the CEA-861 Digital TV Profile standard + + - .. row 4 + + - ``V4L2_DV_BT_STD_DMT`` + + - The timings follow the VESA Discrete Monitor Timings standard + + - .. row 5 + + - ``V4L2_DV_BT_STD_CVT`` + + - The timings follow the VESA Coordinated Video Timings standard + + - .. row 6 + + - ``V4L2_DV_BT_STD_GTF`` + + - The timings follow the VESA Generalized Timings Formula standard + + + +.. _dv-bt-flags: + +.. flat-table:: DV BT Timing flags + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - Flag + + - Description + + - .. row 2 + + - + - + + - .. row 3 + + - ``V4L2_DV_FL_REDUCED_BLANKING`` + + - CVT/GTF specific: the timings use reduced blanking (CVT) or the + 'Secondary GTF' curve (GTF). In both cases the horizontal and/or + vertical blanking intervals are reduced, allowing a higher + resolution over the same bandwidth. This is a read-only flag, + applications must not set this. + + - .. row 4 + + - ``V4L2_DV_FL_CAN_REDUCE_FPS`` + + - CEA-861 specific: set for CEA-861 formats with a framerate that is + a multiple of six. These formats can be optionally played at 1 / + 1.001 speed to be compatible with 60 Hz based standards such as + NTSC and PAL-M that use a framerate of 29.97 frames per second. If + the transmitter can't generate such frequencies, then the flag + will also be cleared. This is a read-only flag, applications must + not set this. + + - .. row 5 + + - ``V4L2_DV_FL_REDUCED_FPS`` + + - CEA-861 specific: only valid for video transmitters, the flag is + cleared by receivers. It is also only valid for formats with the + ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the + flag will be cleared by the driver. If the application sets this + flag, then the pixelclock used to set up the transmitter is + divided by 1.001 to make it compatible with NTSC framerates. If + the transmitter can't generate such frequencies, then the flag + will also be cleared. + + - .. row 6 + + - ``V4L2_DV_FL_HALF_LINE`` + + - Specific to interlaced formats: if set, then the vertical + frontporch of field 1 (aka the odd field) is really one half-line + longer and the vertical backporch of field 2 (aka the even field) + is really one half-line shorter, so each field has exactly the + same number of half-lines. Whether half-lines can be detected or + used depends on the hardware. + + - .. row 7 + + - ``V4L2_DV_FL_IS_CE_VIDEO`` + + - If set, then this is a Consumer Electronics (CE) video format. + Such formats differ from other formats (commonly called IT + formats) in that if R'G'B' encoding is used then by default the + R'G'B' values use limited range (i.e. 16-235) as opposed to full + range (i.e. 0-255). All formats defined in CEA-861 except for the + 640x480p59.94 format are CE formats. diff --git a/Documentation/media/uapi/v4l/vidioc-g-edid.rst b/Documentation/media/uapi/v4l/vidioc-g-edid.rst new file mode 100644 index 000000000000..907b2c1764a3 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-edid.rst @@ -0,0 +1,158 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_EDID: + +****************************************************************************** +ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID +****************************************************************************** + +Name +==== + +VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_edid *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, + VIDIOC_SUBDEV_S_EDID + +``argp`` + + +Description +=========== + +These ioctls can be used to get or set an EDID associated with an input +from a receiver or an output of a transmitter device. They can be used +with subdevice nodes (/dev/v4l-subdevX) or with video nodes +(/dev/videoX). + +When used with video nodes the ``pad`` field represents the input (for +video capture devices) or output (for video output devices) index as is +returned by :ref:`VIDIOC_ENUMINPUT` and +:ref:`VIDIOC_ENUMOUTPUT` respectively. When used +with subdevice nodes the ``pad`` field represents the input or output +pad of the subdevice. If there is no EDID support for the given ``pad`` +value, then the ``EINVAL`` error code will be returned. + +To get the EDID data the application has to fill in the ``pad``, +``start_block``, ``blocks`` and ``edid`` fields, zero the ``reserved`` +array and call :ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>`. The current EDID from block +``start_block`` and of size ``blocks`` will be placed in the memory +``edid`` points to. The ``edid`` pointer must point to memory at least +``blocks`` * 128 bytes large (the size of one block is 128 bytes). + +If there are fewer blocks than specified, then the driver will set +``blocks`` to the actual number of blocks. If there are no EDID blocks +available at all, then the error code ``ENODATA`` is set. + +If blocks have to be retrieved from the sink, then this call will block +until they have been read. + +If ``start_block`` and ``blocks`` are both set to 0 when +:ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>` is called, then the driver will set ``blocks`` to the +total number of available EDID blocks and it will return 0 without +copying any data. This is an easy way to discover how many EDID blocks +there are. Note that if there are no EDID blocks available at all, then +the driver will set ``blocks`` to 0 and it returns 0. + +To set the EDID blocks of a receiver the application has to fill in the +``pad``, ``blocks`` and ``edid`` fields, set ``start_block`` to 0 and +zero the ``reserved`` array. It is not possible to set part of an EDID, +it is always all or nothing. Setting the EDID data is only valid for +receivers as it makes no sense for a transmitter. + +The driver assumes that the full EDID is passed in. If there are more +EDID blocks than the hardware can handle then the EDID is not written, +but instead the error code ``E2BIG`` is set and ``blocks`` is set to the +maximum that the hardware supports. If ``start_block`` is any value +other than 0 then the error code ``EINVAL`` is set. + +To disable an EDID you set ``blocks`` to 0. Depending on the hardware +this will drive the hotplug pin low and/or block the source from reading +the EDID data in some way. In any case, the end result is the same: the +EDID is no longer available. + + +.. _v4l2-edid: + +.. flat-table:: struct v4l2_edid + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``pad`` + + - Pad for which to get/set the EDID blocks. When used with a video + device node the pad represents the input or output index as + returned by :ref:`VIDIOC_ENUMINPUT` and + :ref:`VIDIOC_ENUMOUTPUT` respectively. + + - .. row 2 + + - __u32 + + - ``start_block`` + + - Read the EDID from starting with this block. Must be 0 when + setting the EDID. + + - .. row 3 + + - __u32 + + - ``blocks`` + + - The number of blocks to get or set. Must be less or equal to 256 + (the maximum number of blocks as defined by the standard). When + you set the EDID and ``blocks`` is 0, then the EDID is disabled or + erased. + + - .. row 4 + + - __u32 + + - ``reserved``\ [5] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + - .. row 5 + + - __u8 * + + - ``edid`` + + - Pointer to memory that contains the EDID. The minimum size is + ``blocks`` * 128. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +``ENODATA`` + The EDID data is not available. + +``E2BIG`` + The EDID data you provided is more than the hardware can handle. diff --git a/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst b/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst new file mode 100644 index 000000000000..f0f41ac56b80 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst @@ -0,0 +1,210 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_ENC_INDEX: + +************************ +ioctl VIDIOC_G_ENC_INDEX +************************ + +Name +==== + +VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_enc_idx *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_ENC_INDEX + +``argp`` + + +Description +=========== + +The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed +video stream the same or another application currently reads from the +driver, which is useful for random access into the stream without +decoding it. + +To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a +pointer to a struct :ref:`v4l2_enc_idx <v4l2-enc-idx>`. On success +the driver fills the ``entry`` array, stores the number of elements +written in the ``entries`` field, and initializes the ``entries_cap`` +field. + +Each element of the ``entry`` array contains meta data about one +picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to +``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up +to ``entries_cap`` entries. This number can be lower or higher than +``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to +read the meta data in time the oldest entries will be lost. When the +buffer is empty or no capturing/encoding is in progress, ``entries`` +will be zero. + +Currently this ioctl is only defined for MPEG-2 program streams and +video elementary streams. + + +.. _v4l2-enc-idx: + +.. flat-table:: struct v4l2_enc_idx + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 1 + + + - .. row 1 + + - __u32 + + - ``entries`` + + - The number of entries the driver stored in the ``entry`` array. + + - .. row 2 + + - __u32 + + - ``entries_cap`` + + - The number of entries the driver can buffer. Must be greater than + zero. + + - .. row 3 + + - __u32 + + - ``reserved``\ [4] + + - :cspan:`2` Reserved for future extensions. Drivers must set the + array to zero. + + - .. row 4 + + - struct :ref:`v4l2_enc_idx_entry <v4l2-enc-idx-entry>` + + - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``] + + - Meta data about a compressed video stream. Each element of the + array corresponds to one picture, sorted in ascending order by + their ``offset``. + + + +.. _v4l2-enc-idx-entry: + +.. flat-table:: struct v4l2_enc_idx_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u64 + + - ``offset`` + + - The offset in bytes from the beginning of the compressed video + stream to the beginning of this picture, that is a *PES packet + header* as defined in :ref:`mpeg2part1` or a *picture header* as + defined in :ref:`mpeg2part2`. When the encoder is stopped, the + driver resets the offset to zero. + + - .. row 2 + + - __u64 + + - ``pts`` + + - The 33 bit *Presentation Time Stamp* of this picture as defined in + :ref:`mpeg2part1`. + + - .. row 3 + + - __u32 + + - ``length`` + + - The length of this picture in bytes. + + - .. row 4 + + - __u32 + + - ``flags`` + + - Flags containing the coding type of this picture, see + :ref:`enc-idx-flags`. + + - .. row 5 + + - __u32 + + - ``reserved``\ [2] + + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _enc-idx-flags: + +.. flat-table:: Index Entry Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_ENC_IDX_FRAME_I`` + + - 0x00 + + - This is an Intra-coded picture. + + - .. row 2 + + - ``V4L2_ENC_IDX_FRAME_P`` + + - 0x01 + + - This is a Predictive-coded picture. + + - .. row 3 + + - ``V4L2_ENC_IDX_FRAME_B`` + + - 0x02 + + - This is a Bidirectionally predictive-coded picture. + + - .. row 4 + + - ``V4L2_ENC_IDX_FRAME_MASK`` + + - 0x0F + + - *AND* the flags field with this mask to obtain the picture coding + type. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst new file mode 100644 index 000000000000..96b6eaca755c --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst @@ -0,0 +1,488 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_EXT_CTRLS: + +****************************************************************** +ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS +****************************************************************** + +Name +==== + +VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_ext_controls *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, + VIDIOC_TRY_EXT_CTRLS + +``argp`` + + +Description +=========== + +These ioctls allow the caller to get or set multiple controls +atomically. Control IDs are grouped into control classes (see +:ref:`ctrl-class`) and all controls in the control array must belong +to the same control class. + +Applications must always fill in the ``count``, ``which``, ``controls`` +and ``reserved`` fields of struct +:ref:`v4l2_ext_controls <v4l2-ext-controls>`, and initialize the +struct :ref:`v4l2_ext_control <v4l2-ext-control>` array pointed to +by the ``controls`` fields. + +To get the current value of a set of controls applications initialize +the ``id``, ``size`` and ``reserved2`` fields of each struct +:ref:`v4l2_ext_control <v4l2-ext-control>` and call the +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the +``string`` field. Controls of compound types +(``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field. + +If the ``size`` is too small to receive the control result (only +relevant for pointer-type controls like strings), then the driver will +set ``size`` to a valid value and return an ``ENOSPC`` error code. You +should re-allocate the memory to this new size and try again. For the +string type it is possible that the same issue occurs again if the +string has grown in the meantime. It is recommended to call +:ref:`VIDIOC_QUERYCTRL` first and use +``maximum``\ +1 as the new ``size`` value. It is guaranteed that that is +sufficient memory. + +N-dimensional arrays are set and retrieved row-by-row. You cannot set a +partial array, all elements have to be set or retrieved. The total size +is calculated as ``elems`` * ``elem_size``. These values can be obtained +by calling :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. + +To change the value of a set of controls applications initialize the +``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields +of each struct :ref:`v4l2_ext_control <v4l2-ext-control>` and call +the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. The controls will only be set if *all* +control values are valid. + +To check if a set of controls have correct values applications +initialize the ``id``, ``size``, ``reserved2`` and +``value/value64/string/ptr`` fields of each struct +:ref:`v4l2_ext_control <v4l2-ext-control>` and call the +:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. It is up to the driver whether wrong +values are automatically adjusted to a valid value or if an error is +returned. + +When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error +code. When the value is out of bounds drivers can choose to take the +closest valid value or return an ``ERANGE`` error code, whatever seems more +appropriate. In the first case the new value is set in struct +:ref:`v4l2_ext_control <v4l2-ext-control>`. If the new control value +is inappropriate (e.g. the given menu index is not supported by the menu +control), then this will also result in an ``EINVAL`` error code error. + +The driver will only set/get these controls if all control values are +correct. This prevents the situation where only some of the controls +were set/get. Only low-level errors (e. g. a failed i2c command) can +still cause this situation. + + +.. _v4l2-ext-control: + +.. flat-table:: struct v4l2_ext_control + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __u32 + + - ``id`` + + - + - Identifies the control, set by the application. + + - .. row 2 + + - __u32 + + - ``size`` + + - + - The total size in bytes of the payload of this control. This is + normally 0, but for pointer controls this should be set to the + size of the memory containing the payload, or that will receive + the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is + less than is required to store the payload result, then it is set + to a value large enough to store the payload result and ``ENOSPC`` is + returned. Note that for string controls this ``size`` field should + not be confused with the length of the string. This field refers + to the size of the memory that contains the string. The actual + *length* of the string may well be much smaller. + + - .. row 3 + + - __u32 + + - ``reserved2``\ [1] + + - + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + - .. row 4 + + - union + + - (anonymous) + + - .. row 5 + + - + - __s32 + + - ``value`` + + - New value or current value. Valid if this control is not of type + ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is + not set. + + - .. row 6 + + - + - __s64 + + - ``value64`` + + - New value or current value. Valid if this control is of type + ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is + not set. + + - .. row 7 + + - + - char * + + - ``string`` + + - A pointer to a string. Valid if this control is of type + ``V4L2_CTRL_TYPE_STRING``. + + - .. row 8 + + - + - __u8 * + + - ``p_u8`` + + - A pointer to a matrix control of unsigned 8-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_U8``. + + - .. row 9 + + - + - __u16 * + + - ``p_u16`` + + - A pointer to a matrix control of unsigned 16-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_U16``. + + - .. row 10 + + - + - __u32 * + + - ``p_u32`` + + - A pointer to a matrix control of unsigned 32-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_U32``. + + - .. row 11 + + - + - void * + + - ``ptr`` + + - A pointer to a compound type which can be an N-dimensional array + and/or a compound type (the control's type is >= + ``V4L2_CTRL_COMPOUND_TYPES``). Valid if + ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control. + + + +.. _v4l2-ext-controls: + +.. flat-table:: struct v4l2_ext_controls + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 + + + - .. row 1 + + - union + + - (anonymous) + + - .. row 2 + + - + - __u32 + + - ``ctrl_class`` + + - The control class to which all controls belong, see + :ref:`ctrl-class`. Drivers that use a kernel framework for + handling controls will also accept a value of 0 here, meaning that + the controls can belong to any control class. Whether drivers + support this can be tested by setting ``ctrl_class`` to 0 and + calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that + succeeds, then the driver supports this feature. + + - .. row 3 + + - + - __u32 + + - ``which`` + + - Which value of the control to get/set/try. + ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the + control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default + value of the control. Please note that you can only get the + default value of the control, you cannot set or try it. + + For backwards compatibility you can also use a control class here + (see :ref:`ctrl-class`). In that case all controls have to + belong to that control class. This usage is deprecated, instead + just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old + drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and + that require a control class here. You can test for such drivers + by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling + VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the + driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + + - .. row 4 + + - __u32 + + - ``count`` + + - The number of controls in the controls array. May also be zero. + + - .. row 5 + + - __u32 + + - ``error_idx`` + + - Set by the driver in case of an error. If the error is associated + with a particular control, then ``error_idx`` is set to the index + of that control. If the error is not related to a specific + control, or the validation step failed (see below), then + ``error_idx`` is set to ``count``. The value is undefined if the + ioctl returned 0 (success). + + Before controls are read from/written to hardware a validation + step takes place: this checks if all controls in the list are + valid controls, if no attempt is made to write to a read-only + control or read from a write-only control, and any other up-front + checks that can be done without accessing the hardware. The exact + validations done during this step are driver dependent since some + checks might require hardware access for some devices, thus making + it impossible to do those checks up-front. However, drivers should + make a best-effort to do as many up-front checks as possible. + + This check is done to avoid leaving the hardware in an + inconsistent state due to easy-to-avoid problems. But it leads to + another problem: the application needs to know whether an error + came from the validation step (meaning that the hardware was not + touched) or from an error during the actual reading from/writing + to hardware. + + The, in hindsight quite poor, solution for that is to set + ``error_idx`` to ``count`` if the validation failed. This has the + unfortunate side-effect that it is not possible to see which + control failed the validation. If the validation was successful + and the error happened while accessing the hardware, then + ``error_idx`` is less than ``count`` and only the controls up to + ``error_idx-1`` were read or written correctly, and the state of + the remaining controls is undefined. + + Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is + also no need to handle the validation step in this special way, so + ``error_idx`` will just be set to the control that failed the + validation step instead of to ``count``. This means that if + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``, + then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the + actual control that failed the validation step. Unfortunately, + there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. + + - .. row 6 + + - __u32 + + - ``reserved``\ [2] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + - .. row 7 + + - struct :ref:`v4l2_ext_control <v4l2-ext-control>` * + + - ``controls`` + + - Pointer to an array of ``count`` v4l2_ext_control structures. + Ignored if ``count`` equals zero. + + + +.. _ctrl-class: + +.. flat-table:: Control classes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_CTRL_CLASS_USER`` + + - 0x980000 + + - The class containing user controls. These controls are described + in :ref:`control`. All controls that can be set using the + :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and + :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this + class. + + - .. row 2 + + - ``V4L2_CTRL_CLASS_MPEG`` + + - 0x990000 + + - The class containing MPEG compression controls. These controls are + described in :ref:`mpeg-controls`. + + - .. row 3 + + - ``V4L2_CTRL_CLASS_CAMERA`` + + - 0x9a0000 + + - The class containing camera controls. These controls are described + in :ref:`camera-controls`. + + - .. row 4 + + - ``V4L2_CTRL_CLASS_FM_TX`` + + - 0x9b0000 + + - The class containing FM Transmitter (FM TX) controls. These + controls are described in :ref:`fm-tx-controls`. + + - .. row 5 + + - ``V4L2_CTRL_CLASS_FLASH`` + + - 0x9c0000 + + - The class containing flash device controls. These controls are + described in :ref:`flash-controls`. + + - .. row 6 + + - ``V4L2_CTRL_CLASS_JPEG`` + + - 0x9d0000 + + - The class containing JPEG compression controls. These controls are + described in :ref:`jpeg-controls`. + + - .. row 7 + + - ``V4L2_CTRL_CLASS_IMAGE_SOURCE`` + + - 0x9e0000 + + - The class containing image source controls. These controls are + described in :ref:`image-source-controls`. + + - .. row 8 + + - ``V4L2_CTRL_CLASS_IMAGE_PROC`` + + - 0x9f0000 + + - The class containing image processing controls. These controls are + described in :ref:`image-process-controls`. + + - .. row 9 + + - ``V4L2_CTRL_CLASS_FM_RX`` + + - 0xa10000 + + - The class containing FM Receiver (FM RX) controls. These controls + are described in :ref:`fm-rx-controls`. + + - .. row 10 + + - ``V4L2_CTRL_CLASS_RF_TUNER`` + + - 0xa20000 + + - The class containing RF tuner controls. These controls are + described in :ref:`rf-tuner-controls`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``id`` is + invalid, the struct :ref:`v4l2_ext_controls <v4l2-ext-controls>` + ``which`` is invalid, or the struct + :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` was + inappropriate (e.g. the given menu index is not supported by the + driver). This error code is also returned by the + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls if two or + more control values are in conflict. + +ERANGE + The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` + is out of bounds. + +EBUSY + The control is temporarily not changeable, possibly because another + applications took over control of the device function this control + belongs to. + +ENOSPC + The space reserved for the control's payload is insufficient. The + field ``size`` is set to a value that is enough to store the payload + and this error code is returned. + +EACCES + Attempt to try or set a read-only control or to get a write-only + control. diff --git a/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst b/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst new file mode 100644 index 000000000000..ef4592c338ef --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst @@ -0,0 +1,500 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_FBUF: + +********************************** +ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF +********************************** + +Name +==== + +VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_framebuffer *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_framebuffer *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_FBUF, VIDIOC_S_FBUF + +``argp`` + + +Description +=========== + +Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl +to get and set the framebuffer parameters for a +:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>` +(OSD). The type of overlay is implied by the device type (capture or +output device) and can be determined with the +:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN`` +device must not support both kinds of overlay. + +The V4L2 API distinguishes destructive and non-destructive overlays. A +destructive overlay copies captured video images into the video memory +of a graphics card. A non-destructive overlay blends video images into a +VGA signal or graphics into a video signal. *Video Output Overlays* are +always non-destructive. + +To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` +ioctl with a pointer to a :ref:`struct v4l2_framebuffer <v4l2-framebuffer>` +structure. The driver fills all fields of the structure or returns an +EINVAL error code when overlays are not supported. + +To set the parameters for a *Video Output Overlay*, applications must +initialize the ``flags`` field of a struct +:ref:`struct v4l2_framebuffer <v4l2-framebuffer>`. Since the framebuffer is +implemented on the TV card all other parameters are determined by the +driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to +this structure, the driver prepares for the overlay and returns the +framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error +code. + +To set the parameters for a *non-destructive Video Overlay*, +applications must initialize the ``flags`` field, the ``fmt`` +substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for +the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` +does, or it returns an error code. + +For a *destructive Video Overlay* applications must additionally provide +a ``base`` address. Setting up a DMA to a random memory location can +jeopardize the system security, its stability or even damage the +hardware, therefore only the superuser can set the parameters for a +destructive video overlay. + + +.. _v4l2-framebuffer: + +.. flat-table:: struct v4l2_framebuffer + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __u32 + + - ``capability`` + + - + - Overlay capability flags set by the driver, see + :ref:`framebuffer-cap`. + + - .. row 2 + + - __u32 + + - ``flags`` + + - + - Overlay control flags set by application and driver, see + :ref:`framebuffer-flags` + + - .. row 3 + + - void * + + - ``base`` + + - + - Physical base address of the framebuffer, that is the address of + the pixel in the top left corner of the framebuffer. [1]_ + + - .. row 4 + + - + - + - + - This field is irrelevant to *non-destructive Video Overlays*. For + *destructive Video Overlays* applications must provide a base + address. The driver may accept only base addresses which are a + multiple of two, four or eight bytes. For *Video Output Overlays* + the driver must return a valid base address, so applications can + find the corresponding Linux framebuffer device (see + :ref:`osd`). + + - .. row 5 + + - struct + + - ``fmt`` + + - + - Layout of the frame buffer. + + - .. row 6 + + - + - __u32 + + - ``width`` + + - Width of the frame buffer in pixels. + + - .. row 7 + + - + - __u32 + + - ``height`` + + - Height of the frame buffer in pixels. + + - .. row 8 + + - + - __u32 + + - ``pixelformat`` + + - The pixel format of the framebuffer. + + - .. row 9 + + - + - + - + - For *non-destructive Video Overlays* this field only defines a + format for the struct :ref:`v4l2_window <v4l2-window>` + ``chromakey`` field. + + - .. row 10 + + - + - + - + - For *destructive Video Overlays* applications must initialize this + field. For *Video Output Overlays* the driver must return a valid + format. + + - .. row 11 + + - + - + - + - Usually this is an RGB format (for example + :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV + formats (only packed YUV formats when chroma keying is used, not + including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the + ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of + the driver when an application requests a compressed format is + undefined. See :ref:`pixfmt` for information on pixel formats. + + - .. row 12 + + - + - enum :ref:`v4l2_field <v4l2-field>` + + - ``field`` + + - Drivers and applications shall ignore this field. If applicable, + the field order is selected with the + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field`` + field of struct :ref:`v4l2_window <v4l2-window>`. + + - .. row 13 + + - + - __u32 + + - ``bytesperline`` + + - Distance in bytes between the leftmost pixels in two adjacent + lines. + + - .. row 14 + + - :cspan:`3` + + This field is irrelevant to *non-destructive Video Overlays*. + + For *destructive Video Overlays* both applications and drivers can + set this field to request padding bytes at the end of each line. + Drivers however may ignore the requested value, returning + ``width`` times bytes-per-pixel or a larger value required by the + hardware. That implies applications can just set this field to + zero to get a reasonable default. + + For *Video Output Overlays* the driver must return a valid value. + + Video hardware may access padding bytes, therefore they must + reside in accessible memory. Consider for example the case where + padding bytes after the last line of an image cross a system page + boundary. Capture devices may write padding bytes, the value is + undefined. Output devices ignore the contents of padding bytes. + + When the image format is planar the ``bytesperline`` value applies + to the first plane and is divided by the same factor as the + ``width`` field for the other planes. For example the Cb and Cr + planes of a YUV 4:2:0 image have half as many padding bytes + following each line as the Y plane. To avoid ambiguities drivers + must return a ``bytesperline`` value rounded up to a multiple of + the scale factor. + + - .. row 15 + + - + - __u32 + + - ``sizeimage`` + + - This field is irrelevant to *non-destructive Video Overlays*. For + *destructive Video Overlays* applications must initialize this + field. For *Video Output Overlays* the driver must return a valid + format. + + Together with ``base`` it defines the framebuffer memory + accessible by the driver. + + - .. row 16 + + - + - enum :ref:`v4l2_colorspace <v4l2-colorspace>` + + - ``colorspace`` + + - This information supplements the ``pixelformat`` and must be set + by the driver, see :ref:`colorspaces`. + + - .. row 17 + + - + - __u32 + + - ``priv`` + + - Reserved. Drivers and applications must set this field to zero. + + + +.. _framebuffer-cap: + +.. flat-table:: Frame Buffer Capability Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` + + - 0x0001 + + - The device is capable of non-destructive overlays. When the driver + clears this flag, only destructive overlays are supported. There + are no drivers yet which support both destructive and + non-destructive overlays. Video Output Overlays are in practice + always non-destructive. + + - .. row 2 + + - ``V4L2_FBUF_CAP_CHROMAKEY`` + + - 0x0002 + + - The device supports clipping by chroma-keying the images. That is, + image pixels replace pixels in the VGA or video signal only where + the latter assume a certain color. Chroma-keying makes no sense + for destructive overlays. + + - .. row 3 + + - ``V4L2_FBUF_CAP_LIST_CLIPPING`` + + - 0x0004 + + - The device supports clipping using a list of clip rectangles. + + - .. row 4 + + - ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` + + - 0x0008 + + - The device supports clipping using a bit mask. + + - .. row 5 + + - ``V4L2_FBUF_CAP_LOCAL_ALPHA`` + + - 0x0010 + + - The device supports clipping/blending using the alpha channel of + the framebuffer or VGA signal. Alpha blending makes no sense for + destructive overlays. + + - .. row 6 + + - ``V4L2_FBUF_CAP_GLOBAL_ALPHA`` + + - 0x0020 + + - The device supports alpha blending using a global alpha value. + Alpha blending makes no sense for destructive overlays. + + - .. row 7 + + - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA`` + + - 0x0040 + + - The device supports clipping/blending using the inverted alpha + channel of the framebuffer or VGA signal. Alpha blending makes no + sense for destructive overlays. + + - .. row 8 + + - ``V4L2_FBUF_CAP_SRC_CHROMAKEY`` + + - 0x0080 + + - The device supports Source Chroma-keying. Video pixels with the + chroma-key colors are replaced by framebuffer pixels, which is + exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY`` + + + +.. _framebuffer-flags: + +.. flat-table:: Frame Buffer Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_FBUF_FLAG_PRIMARY`` + + - 0x0001 + + - The framebuffer is the primary graphics surface. In other words, + the overlay is destructive. This flag is typically set by any + driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY`` + capability and it is cleared otherwise. + + - .. row 2 + + - ``V4L2_FBUF_FLAG_OVERLAY`` + + - 0x0002 + + - If this flag is set for a video capture device, then the driver + will set the initial overlay size to cover the full framebuffer + size, otherwise the existing overlay size (as set by + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one + video capture driver (bttv) supports this flag. The use of this + flag for capture devices is deprecated. There is no way to detect + which drivers support this flag, so the only reliable method of + setting the overlay size is through + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a + video output device, then the video output overlay window is + relative to the top-left corner of the framebuffer and restricted + to the size of the framebuffer. If it is cleared, then the video + output overlay window is relative to the video output display. + + - .. row 3 + + - ``V4L2_FBUF_FLAG_CHROMAKEY`` + + - 0x0004 + + - Use chroma-keying. The chroma-key color is determined by the + ``chromakey`` field of struct :ref:`v4l2_window <v4l2-window>` + and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` + ioctl, see :ref:`overlay` and :ref:`osd`. + + - .. row 4 + + - :cspan:`2` There are no flags to enable clipping using a list of + clip rectangles or a bitmap. These methods are negotiated with the + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` + and :ref:`osd`. + + - .. row 5 + + - ``V4L2_FBUF_FLAG_LOCAL_ALPHA`` + + - 0x0008 + + - Use the alpha channel of the framebuffer to clip or blend + framebuffer pixels with video images. The blend function is: + output = framebuffer pixel * alpha + video pixel * (1 - alpha). + The actual alpha depth depends on the framebuffer pixel format. + + - .. row 6 + + - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA`` + + - 0x0010 + + - Use a global alpha value to blend the framebuffer with video + images. The blend function is: output = (framebuffer pixel * alpha + + video pixel * (255 - alpha)) / 255. The alpha value is + determined by the ``global_alpha`` field of struct + :ref:`v4l2_window <v4l2-window>` and negotiated with the + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` + and :ref:`osd`. + + - .. row 7 + + - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA`` + + - 0x0020 + + - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the + framebuffer to clip or blend framebuffer pixels with video images, + but with an inverted alpha value. The blend function is: output = + framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual + alpha depth depends on the framebuffer pixel format. + + - .. row 8 + + - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY`` + + - 0x0040 + + - Use source chroma-keying. The source chroma-key color is + determined by the ``chromakey`` field of struct + :ref:`v4l2_window <v4l2-window>` and negotiated with the + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` + and :ref:`osd`. Both chroma-keying are mutual exclusive to each + other, so same ``chromakey`` field of struct + :ref:`v4l2_window <v4l2-window>` is being used. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EPERM + :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to + negotiate the parameters for a destructive overlay. + +EINVAL + The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable. + +.. [1] + A physical base address may not suit all platforms. GK notes in + theory we should pass something like PCI device + memory region + + offset instead. If you encounter problems please discuss on the + linux-media mailing list: + `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. diff --git a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst new file mode 100644 index 000000000000..ee6f11978fd6 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst @@ -0,0 +1,188 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_FMT: + +************************************************ +ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT +************************************************ + +Name +==== + +VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_format *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT + +``argp`` + + +Description +=========== + +These ioctls are used to negotiate the format of data (typically image +format) exchanged between driver and application. + +To query the current parameters applications set the ``type`` field of a +struct :ref:`struct v4l2_format <v4l2-format>` to the respective buffer (stream) +type. For example video capture devices use +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or +``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills +the respective member of the ``fmt`` union. In case of video capture +devices that is either the struct +:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct +:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp`` +member. When the requested buffer type is not supported drivers return +an ``EINVAL`` error code. + +To change the current format parameters applications initialize the +``type`` field and all fields of the respective ``fmt`` union member. +For details see the documentation of the various devices types in +:ref:`devices`. Good practice is to query the current parameters +first, and to modify only those parameters not suitable for the +application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with +a pointer to a :ref:`struct v4l2_format <v4l2-format>` structure the driver +checks and adjusts the parameters against hardware abilities. Drivers +should not return an error code unless the ``type`` field is invalid, +this is a mechanism to fathom device capabilities and to approach +parameters acceptable for both the application and driver. On success +the driver may program the hardware, allocate resources and generally +prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns +the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple, +inflexible devices may even ignore all input and always return the +default parameters. However all V4L2 devices exchanging data with the +application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` +ioctl. When the requested buffer type is not supported drivers return an +EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in +progress or the resource is not available for other reasons drivers +return the ``EBUSY`` error code. + +The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one +exception: it does not change driver state. It can also be called at any +time, never returning ``EBUSY``. This function is provided to negotiate +parameters, to learn about hardware limitations, without disabling I/O +or possibly time consuming hardware preparations. Although strongly +recommended drivers are not required to implement this ioctl. + +The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output. + + +.. _v4l2-format: + +.. flat-table:: struct v4l2_format + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``type`` + + - + - Type of the data stream, see :ref:`v4l2-buf-type`. + + - .. row 2 + + - union + + - ``fmt`` + + - .. row 3 + + - + - struct :ref:`v4l2_pix_format <v4l2-pix-format>` + + - ``pix`` + + - Definition of an image format, see :ref:`pixfmt`, used by video + capture and output devices. + + - .. row 4 + + - + - struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` + + - ``pix_mp`` + + - Definition of an image format, see :ref:`pixfmt`, used by video + capture and output devices that support the + :ref:`multi-planar version of the API <planar-apis>`. + + - .. row 5 + + - + - struct :ref:`v4l2_window <v4l2-window>` + + - ``win`` + + - Definition of an overlaid image, see :ref:`overlay`, used by + video overlay devices. + + - .. row 6 + + - + - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` + + - ``vbi`` + + - Raw VBI capture or output parameters. This is discussed in more + detail in :ref:`raw-vbi`. Used by raw VBI capture and output + devices. + + - .. row 7 + + - + - struct :ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>` + + - ``sliced`` + + - Sliced VBI capture or output parameters. See :ref:`sliced` for + details. Used by sliced VBI capture and output devices. + + - .. row 8 + + - + - struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` + + - ``sdr`` + + - Definition of a data format, see :ref:`pixfmt`, used by SDR + capture and output devices. + + - .. row 9 + + - + - __u8 + + - ``raw_data``\ [200] + + - Place holder for future extensions. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_format <v4l2-format>` ``type`` field is + invalid or the requested buffer type not supported. diff --git a/Documentation/media/uapi/v4l/vidioc-g-frequency.rst b/Documentation/media/uapi/v4l/vidioc-g-frequency.rst new file mode 100644 index 000000000000..a1fd2a870de4 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-frequency.rst @@ -0,0 +1,123 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_FREQUENCY: + +******************************************** +ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY +******************************************** + +Name +==== + +VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_frequency *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY + +``argp`` + + +Description +=========== + +To get the current tuner or modulator radio frequency applications set +the ``tuner`` field of a struct +:ref:`v4l2_frequency <v4l2-frequency>` to the respective tuner or +modulator number (only input devices have tuners, only output devices +have modulators), zero out the ``reserved`` array and call the +:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this structure. The +driver stores the current frequency in the ``frequency`` field. + +To change the current tuner or modulator radio frequency applications +initialize the ``tuner``, ``type`` and ``frequency`` fields, and the +``reserved`` array of a struct :ref:`v4l2_frequency <v4l2-frequency>` +and call the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this +structure. When the requested frequency is not possible the driver +assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a +write-only ioctl, it does not return the actual new frequency. + + +.. _v4l2-frequency: + +.. flat-table:: struct v4l2_frequency + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``tuner`` + + - The tuner or modulator index number. This is the same value as in + the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and + the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or + the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field + and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index`` + field. + + - .. row 2 + + - __u32 + + - ``type`` + + - The tuner type. This is the same value as in the struct + :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be + set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and + to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to + ``V4L2_TUNER_RADIO`` for modulators (currently only radio + modulators are supported). See :ref:`v4l2-tuner-type` + + - .. row 3 + + - __u32 + + - ``frequency`` + + - Tuning frequency in units of 62.5 kHz, or if the struct + :ref:`v4l2_tuner <v4l2-tuner>` or struct + :ref:`v4l2_modulator <v4l2-modulator>` ``capability`` flag + ``V4L2_TUNER_CAP_LOW`` is set, in units of 62.5 Hz. A 1 Hz unit is + used when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set. + + - .. row 4 + + - __u32 + + - ``reserved``\ [8] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The ``tuner`` index is out of bounds or the value in the ``type`` + field is wrong. + +EBUSY + A hardware seek is in progress. diff --git a/Documentation/media/uapi/v4l/vidioc-g-input.rst b/Documentation/media/uapi/v4l/vidioc-g-input.rst new file mode 100644 index 000000000000..29e22f6f8028 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-input.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_INPUT: + +************************************ +ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT +************************************ + +Name +==== + +VIDIOC_G_INPUT - VIDIOC_S_INPUT - Query or select the current video input + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, int *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_INPUT, VIDIOC_S_INPUT + +``argp`` + + +Description +=========== + +To query the current video input applications call the +:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` ioctl with a pointer to an integer where the driver +stores the number of the input, as in the struct +:ref:`v4l2_input <v4l2-input>` ``index`` field. This ioctl will fail +only when there are no video inputs, returning ``EINVAL``. + +To select a video input applications store the number of the desired +input in an integer and call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` ioctl with a pointer +to this integer. Side effects are possible. For example inputs may +support different video standards, so the driver may implicitly switch +the current standard. Because of these possible side effects +applications must select an input before querying or negotiating any +other parameters. + +Information about video inputs is available using the +:ref:`VIDIOC_ENUMINPUT` ioctl. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The number of the video input is out of bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst b/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst new file mode 100644 index 000000000000..f5bf8b7915ed --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst @@ -0,0 +1,184 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_JPEGCOMP: + +****************************************** +ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP +****************************************** + +Name +==== + +VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, v4l2_jpegcompression *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const v4l2_jpegcompression *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP + +``argp`` + + +Description +=========== + +These ioctls are **deprecated**. New drivers and applications should use +:ref:`JPEG class controls <jpeg-controls>` for image quality and JPEG +markers control. + +[to do] + +Ronald Bultje elaborates: + +APP is some application-specific information. The application can set it +itself, and it'll be stored in the JPEG-encoded fields (eg; interlacing +information for in an AVI or so). COM is the same, but it's comments, +like 'encoded by me' or so. + +jpeg_markers describes whether the huffman tables, quantization tables +and the restart interval information (all JPEG-specific stuff) should be +stored in the JPEG-encoded fields. These define how the JPEG field is +encoded. If you omit them, applications assume you've used standard +encoding. You usually do want to add them. + + +.. _v4l2-jpegcompression: + +.. flat-table:: struct v4l2_jpegcompression + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - int + + - ``quality`` + + - Deprecated. If + :ref:`V4L2_CID_JPEG_COMPRESSION_QUALITY <jpeg-quality-control>` + control is exposed by a driver applications should use it instead + and ignore this field. + + - .. row 2 + + - int + + - ``APPn`` + + - + + - .. row 3 + + - int + + - ``APP_len`` + + - + + - .. row 4 + + - char + + - ``APP_data``\ [60] + + - + + - .. row 5 + + - int + + - ``COM_len`` + + - + + - .. row 6 + + - char + + - ``COM_data``\ [60] + + - + + - .. row 7 + + - __u32 + + - ``jpeg_markers`` + + - See :ref:`jpeg-markers`. Deprecated. If + :ref:`V4L2_CID_JPEG_ACTIVE_MARKER <jpeg-active-marker-control>` + control is exposed by a driver applications should use it instead + and ignore this field. + + + +.. _jpeg-markers: + +.. flat-table:: JPEG Markers Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_JPEG_MARKER_DHT`` + + - (1<<3) + + - Define Huffman Tables + + - .. row 2 + + - ``V4L2_JPEG_MARKER_DQT`` + + - (1<<4) + + - Define Quantization Tables + + - .. row 3 + + - ``V4L2_JPEG_MARKER_DRI`` + + - (1<<5) + + - Define Restart Interval + + - .. row 4 + + - ``V4L2_JPEG_MARKER_COM`` + + - (1<<6) + + - Comment segment + + - .. row 5 + + - ``V4L2_JPEG_MARKER_APP`` + + - (1<<7) + + - App segment, driver will always use APP0 + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-g-modulator.rst b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst new file mode 100644 index 000000000000..05d83610bdc5 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst @@ -0,0 +1,255 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_MODULATOR: + +******************************************** +ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR +******************************************** + +Name +==== + +VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_modulator *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_modulator *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR + +``argp`` + + +Description +=========== + +To query the attributes of a modulator applications initialize the +``index`` field and zero out the ``reserved`` array of a struct +:ref:`v4l2_modulator <v4l2-modulator>` and call the +:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl with a pointer to this structure. Drivers +fill the rest of the structure or return an ``EINVAL`` error code when the +index is out of bounds. To enumerate all modulators applications shall +begin at index zero, incrementing by one until the driver returns +EINVAL. + +Modulators have two writable properties, an audio modulation set and the +radio frequency. To change the modulated audio subprograms, applications +initialize the ``index`` and ``txsubchans`` fields and the ``reserved`` +array and call the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Drivers may choose a +different audio modulation if the request cannot be satisfied. However +this is a write-only ioctl, it does not return the actual audio +modulation selected. + +:ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and +``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be +initialized to zero. The term 'modulator' means SDR transmitter in this +context. + +To change the radio frequency the +:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. + + +.. _v4l2-modulator: + +.. flat-table:: struct v4l2_modulator + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 1 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Identifies the modulator, set by the application. + + - .. row 2 + + - __u8 + + - ``name``\ [32] + + - Name of the modulator, a NUL-terminated ASCII string. This + information is intended for the user. + + - .. row 3 + + - __u32 + + - ``capability`` + + - Modulator capability flags. No flags are defined for this field, + the tuner flags in struct :ref:`v4l2_tuner <v4l2-tuner>` are + used accordingly. The audio flags indicate the ability to encode + audio subprograms. They will *not* change for example with the + current video standard. + + - .. row 4 + + - __u32 + + - ``rangelow`` + + - The lowest tunable frequency in units of 62.5 KHz, or if the + ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of + 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is + set, in units of 1 Hz. + + - .. row 5 + + - __u32 + + - ``rangehigh`` + + - The highest tunable frequency in units of 62.5 KHz, or if the + ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of + 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is + set, in units of 1 Hz. + + - .. row 6 + + - __u32 + + - ``txsubchans`` + + - With this field applications can determine how audio sub-carriers + shall be modulated. It contains a set of flags as defined in + :ref:`modulator-txsubchans`. Note the tuner ``rxsubchans`` flags + are reused, but the semantics are different. Video output devices + are assumed to have an analog or PCM audio input with 1-3 + channels. The ``txsubchans`` flags select one or more channels for + modulation, together with some audio subprogram indicator, for + example a stereo pilot tone. + + - .. row 7 + + - __u32 + + - ``type`` + + - :cspan:`2` Type of the modulator, see :ref:`v4l2-tuner-type`. + + - .. row 8 + + - __u32 + + - ``reserved``\ [3] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. _modulator-txsubchans: + +.. flat-table:: Modulator Audio Transmission Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_TUNER_SUB_MONO`` + + - 0x0001 + + - Modulate channel 1 as mono audio, when the input has more + channels, a down-mix of channel 1 and 2. This flag does not + combine with ``V4L2_TUNER_SUB_STEREO`` or + ``V4L2_TUNER_SUB_LANG1``. + + - .. row 2 + + - ``V4L2_TUNER_SUB_STEREO`` + + - 0x0002 + + - Modulate channel 1 and 2 as left and right channel of a stereo + audio signal. When the input has only one channel or two channels + and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as + left and right channel. This flag does not combine with + ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the + driver does not support stereo audio it shall fall back to mono. + + - .. row 3 + + - ``V4L2_TUNER_SUB_LANG1`` + + - 0x0008 + + - Modulate channel 1 and 2 as primary and secondary language of a + bilingual audio signal. When the input has only one channel it is + used for both languages. It is not possible to encode the primary + or secondary language only. This flag does not combine with + ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or + ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the + respective audio matrix, or the current video standard does not + permit bilingual audio the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall + return an ``EINVAL`` error code and the driver shall fall back to mono + or stereo mode. + + - .. row 4 + + - ``V4L2_TUNER_SUB_LANG2`` + + - 0x0004 + + - Same effect as ``V4L2_TUNER_SUB_SAP``. + + - .. row 5 + + - ``V4L2_TUNER_SUB_SAP`` + + - 0x0004 + + - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is + encoded as mono audio, the last channel as Second Audio Program. + When the input has only one channel it is used for both audio + tracks. When the input has three channels the mono track is a + down-mix of channel 1 and 2. When combined with + ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and + right stereo audio, channel 3 as Second Audio Program. When the + input has only two channels, the first is encoded as left and + right channel and the second as SAP. When the input has only one + channel it is used for all audio tracks. It is not possible to + encode a Second Audio Program only. This flag must combine with + ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the + hardware does not support the respective audio matrix, or the + current video standard does not permit SAP the + :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall return an ``EINVAL`` error code and + driver shall fall back to mono or stereo mode. + + - .. row 6 + + - ``V4L2_TUNER_SUB_RDS`` + + - 0x0010 + + - Enable the RDS encoder for a radio FM transmitter. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_modulator <v4l2-modulator>` ``index`` is + out of bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-g-output.rst b/Documentation/media/uapi/v4l/vidioc-g-output.rst new file mode 100644 index 000000000000..ae0ad577ba97 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-output.rst @@ -0,0 +1,64 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_OUTPUT: + +************************************** +ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT +************************************** + +Name +==== + +VIDIOC_G_OUTPUT - VIDIOC_S_OUTPUT - Query or select the current video output + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, int *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT + +``argp`` + + +Description +=========== + +To query the current video output applications call the +:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a pointer to an integer where the driver +stores the number of the output, as in the struct +:ref:`v4l2_output <v4l2-output>` ``index`` field. This ioctl will +fail only when there are no video outputs, returning the ``EINVAL`` error +code. + +To select a video output applications store the number of the desired +output in an integer and call the :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a +pointer to this integer. Side effects are possible. For example outputs +may support different video standards, so the driver may implicitly +switch the current standard. standard. Because of these possible side +effects applications must select an output before querying or +negotiating any other parameters. + +Information about video outputs is available using the +:ref:`VIDIOC_ENUMOUTPUT` ioctl. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The number of the video output is out of bounds, or there are no + video outputs at all. diff --git a/Documentation/media/uapi/v4l/vidioc-g-parm.rst b/Documentation/media/uapi/v4l/vidioc-g-parm.rst new file mode 100644 index 000000000000..7116e0decddc --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-parm.rst @@ -0,0 +1,349 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_PARM: + +********************************** +ioctl VIDIOC_G_PARM, VIDIOC_S_PARM +********************************** + +Name +==== + +VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, v4l2_streamparm *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_PARM, VIDIOC_S_PARM + +``argp`` + + +Description +=========== + +The current video standard determines a nominal number of frames per +second. If less than this number of frames is to be captured or output, +applications can request frame skipping or duplicating on the driver +side. This is especially useful when using the :ref:`read() <func-read>` or +:ref:`write() <func-write>`, which are not augmented by timestamps or sequence +counters, and to avoid unnecessary data copying. + +Further these ioctls can be used to determine the number of buffers used +internally by a driver in read/write mode. For implications see the +section discussing the :ref:`read() <func-read>` function. + +To get and set the streaming parameters applications call the +:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a +pointer to a struct :ref:`struct v4l2_streamparm <v4l2-streamparm>` which contains a +union holding separate parameters for input and output devices. + + +.. _v4l2-streamparm: + +.. flat-table:: struct v4l2_streamparm + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - + - The buffer (stream) type, same as struct + :ref:`v4l2_format <v4l2-format>` ``type``, set by the + application. See :ref:`v4l2-buf-type` + + - .. row 2 + + - union + + - ``parm`` + + - + - + + - .. row 3 + + - + - struct :ref:`v4l2_captureparm <v4l2-captureparm>` + + - ``capture`` + + - Parameters for capture devices, used when ``type`` is + ``V4L2_BUF_TYPE_VIDEO_CAPTURE``. + + - .. row 4 + + - + - struct :ref:`v4l2_outputparm <v4l2-outputparm>` + + - ``output`` + + - Parameters for output devices, used when ``type`` is + ``V4L2_BUF_TYPE_VIDEO_OUTPUT``. + + - .. row 5 + + - + - __u8 + + - ``raw_data``\ [200] + + - A place holder for future extensions. + + + +.. _v4l2-captureparm: + +.. flat-table:: struct v4l2_captureparm + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``capability`` + + - See :ref:`parm-caps`. + + - .. row 2 + + - __u32 + + - ``capturemode`` + + - Set by drivers and applications, see :ref:`parm-flags`. + + - .. row 3 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``timeperframe`` + + - This is the desired period between successive frames captured by + the driver, in seconds. The field is intended to skip frames on + the driver side, saving I/O bandwidth. + + Applications store here the desired frame period, drivers return + the actual frame period, which must be greater or equal to the + nominal frame period determined by the current video standard + (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod`` + field). Changing the video standard (also implicitly by switching + the video input) may reset this parameter to the nominal frame + period. To reset manually applications can just set this field to + zero. + + Drivers support this function only when they set the + ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field. + + - .. row 4 + + - __u32 + + - ``extendedmode`` + + - Custom (driver specific) streaming parameters. When unused, + applications and drivers must set this field to zero. Applications + using this field should check the driver name and version, see + :ref:`querycap`. + + - .. row 5 + + - __u32 + + - ``readbuffers`` + + - Applications set this field to the desired number of buffers used + internally by the driver in :ref:`read() <func-read>` mode. + Drivers return the actual number of buffers. When an application + requests zero buffers, drivers should just return the current + setting rather than the minimum or an error code. For details see + :ref:`rw`. + + - .. row 6 + + - __u32 + + - ``reserved``\ [4] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. _v4l2-outputparm: + +.. flat-table:: struct v4l2_outputparm + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``capability`` + + - See :ref:`parm-caps`. + + - .. row 2 + + - __u32 + + - ``outputmode`` + + - Set by drivers and applications, see :ref:`parm-flags`. + + - .. row 3 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``timeperframe`` + + - This is the desired period between successive frames output by the + driver, in seconds. + + - .. row 4 + + - :cspan:`2` + + The field is intended to repeat frames on the driver side in + :ref:`write() <func-write>` mode (in streaming mode timestamps + can be used to throttle the output), saving I/O bandwidth. + + Applications store here the desired frame period, drivers return + the actual frame period, which must be greater or equal to the + nominal frame period determined by the current video standard + (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod`` + field). Changing the video standard (also implicitly by switching + the video output) may reset this parameter to the nominal frame + period. To reset manually applications can just set this field to + zero. + + Drivers support this function only when they set the + ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field. + + - .. row 5 + + - __u32 + + - ``extendedmode`` + + - Custom (driver specific) streaming parameters. When unused, + applications and drivers must set this field to zero. Applications + using this field should check the driver name and version, see + :ref:`querycap`. + + - .. row 6 + + - __u32 + + - ``writebuffers`` + + - Applications set this field to the desired number of buffers used + internally by the driver in :ref:`write() <func-write>` mode. Drivers + return the actual number of buffers. When an application requests + zero buffers, drivers should just return the current setting + rather than the minimum or an error code. For details see + :ref:`rw`. + + - .. row 7 + + - __u32 + + - ``reserved``\ [4] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. _parm-caps: + +.. flat-table:: Streaming Parameters Capabilites + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_CAP_TIMEPERFRAME`` + + - 0x1000 + + - The frame skipping/repeating controlled by the ``timeperframe`` + field is supported. + + + +.. _parm-flags: + +.. flat-table:: Capture Parameters Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_MODE_HIGHQUALITY`` + + - 0x0001 + + - High quality imaging mode. High quality mode is intended for still + imaging applications. The idea is to get the best possible image + quality that the hardware can deliver. It is not defined how the + driver writer may achieve that; it will depend on the hardware and + the ingenuity of the driver writer. High quality mode is a + different mode from the regular motion video capture modes. In + high quality mode: + + - The driver may be able to capture higher resolutions than for + motion capture. + + - The driver may support fewer pixel formats than motion capture + (eg; true color). + + - The driver may capture and arithmetically combine multiple + successive fields or frames to remove color edge artifacts and + reduce the noise in the video data. + + - The driver may capture images in slices like a scanner in order + to handle larger format images than would otherwise be + possible. + + - An image capture operation may be significantly slower than + motion capture. + + - Moving objects in the image might have excessive motion blur. + + - Capture might only work through the :ref:`read() <func-read>` call. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-g-priority.rst b/Documentation/media/uapi/v4l/vidioc-g-priority.rst new file mode 100644 index 000000000000..9f774ce400a4 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-priority.rst @@ -0,0 +1,117 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_PRIORITY: + +****************************************** +ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY +****************************************** + +Name +==== + +VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, enum v4l2_priority *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY + +``argp`` + Pointer to an enum v4l2_priority type. + + +Description +=========== + +To query the current access priority applications call the +:ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority +variable where the driver stores the current priority. + +To request an access priority applications store the desired priority in +an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl +with a pointer to this variable. + + +.. _v4l2-priority: + +.. flat-table:: enum v4l2_priority + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_PRIORITY_UNSET`` + + - 0 + + - + + - .. row 2 + + - ``V4L2_PRIORITY_BACKGROUND`` + + - 1 + + - Lowest priority, usually applications running in background, for + example monitoring VBI transmissions. A proxy application running + in user space will be necessary if multiple applications want to + read from a device at this priority. + + - .. row 3 + + - ``V4L2_PRIORITY_INTERACTIVE`` + + - 2 + + - + + - .. row 4 + + - ``V4L2_PRIORITY_DEFAULT`` + + - 2 + + - Medium priority, usually applications started and interactively + controlled by the user. For example TV viewers, Teletext browsers, + or just "panel" applications to change the channel or video + controls. This is the default priority unless an application + requests another. + + - .. row 5 + + - ``V4L2_PRIORITY_RECORD`` + + - 3 + + - Highest priority. Only one file descriptor can have this priority, + it blocks any other fd from changing device properties. Usually + applications which must not be interrupted, like video recording. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The requested priority value is invalid. + +EBUSY + Another application already requested higher priority. diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst new file mode 100644 index 000000000000..953931fabd00 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst @@ -0,0 +1,209 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_SELECTION: + +******************************************** +ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION +******************************************** + +Name +==== + +VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_selection *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_SELECTION, VIDIOC_S_SELECTION + +``argp`` + + +Description +=========== + +The ioctls are used to query and configure selection rectangles. + +To query the cropping (composing) rectangle set struct +:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the +respective buffer type. Do not use the multiplanar buffer types. Use +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of +``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use +``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of +``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the +value of struct :ref:`v4l2_selection <v4l2-selection>` ``target`` +field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer +to table :ref:`v4l2-selections-common` or :ref:`selection-api` for +additional targets. The ``flags`` and ``reserved`` fields of struct +:ref:`v4l2_selection <v4l2-selection>` are ignored and they must be +filled with zeros. The driver fills the rest of the structure or returns +EINVAL error code if incorrect buffer type or target was used. If +cropping (composing) is not supported then the active rectangle is not +mutable and it is always equal to the bounds rectangle. Finally, the +struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle is filled with +the current cropping (composing) coordinates. The coordinates are +expressed in driver-dependent units. The only exception are rectangles +for images in raw formats, whose coordinates are always expressed in +pixels. + +To change the cropping (composing) rectangle set the struct +:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the +respective buffer type. Do not use multiplanar buffers. Use +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of +``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. Use +``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of +``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the +value of struct :ref:`v4l2_selection <v4l2-selection>` ``target`` to +``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table +:ref:`v4l2-selections-common` or :ref:`selection-api` for additional +targets. The struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle need +to be set to the desired active area. Field struct +:ref:`v4l2_selection <v4l2-selection>` ``reserved`` is ignored and +must be filled with zeros. The driver may adjust coordinates of the +requested rectangle. An application may introduce constraints to control +rounding behaviour. The struct :ref:`v4l2_selection <v4l2-selection>` +``flags`` field must be set to one of the following: + +- ``0`` - The driver can adjust the rectangle size freely and shall + choose a crop/compose rectangle as close as possible to the requested + one. + +- ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the + rectangle. The original rectangle must lay inside the adjusted one. + +- ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the + rectangle. The adjusted rectangle must lay inside the original one. + +- ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the + size exactly the same as in the requested rectangle. + +Please refer to :ref:`sel-const-adjust`. + +The driver may have to adjusts the requested dimensions against hardware +limits and other parts as the pipeline, i.e. the bounds given by the +capture/output window or TV display. The closest possible values of +horizontal and vertical offset and sizes are chosen according to +following priority: + +1. Satisfy constraints from struct + :ref:`v4l2_selection <v4l2-selection>` ``flags``. + +2. Adjust width, height, left, and top to hardware limits and + alignments. + +3. Keep center of adjusted rectangle as close as possible to the + original one. + +4. Keep width and height as close as possible to original ones. + +5. Keep horizontal and vertical offset as close as possible to original + ones. + +On success the struct :ref:`v4l2_rect <v4l2-rect>` ``r`` field +contains the adjusted rectangle. When the parameters are unsuitable the +application may modify the cropping (composing) or image parameters and +repeat the cycle until satisfactory parameters have been negotiated. If +constraints flags have to be violated at then ``ERANGE`` is returned. The +error indicates that *there exist no rectangle* that satisfies the +constraints. + +Selection targets and flags are documented in +:ref:`v4l2-selections-common`. + + +.. _sel-const-adjust: + +.. figure:: vidioc-g-selection_files/constraints.* + :alt: constraints.png + :align: center + + Size adjustments with constraint flags. + + Behaviour of rectangle adjustment for different constraint flags. + + + + +.. _v4l2-selection: + +.. flat-table:: struct v4l2_selection + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - Type of the buffer (from enum + :ref:`v4l2_buf_type <v4l2-buf-type>`). + + - .. row 2 + + - __u32 + + - ``target`` + + - Used to select between + :ref:`cropping and composing rectangles <v4l2-selections-common>`. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Flags controlling the selection rectangle adjustments, refer to + :ref:`selection flags <v4l2-selection-flags>`. + + - .. row 4 + + - struct :ref:`v4l2_rect <v4l2-rect>` + + - ``r`` + + - The selection rectangle. + + - .. row 5 + + - __u32 + + - ``reserved[9]`` + + - Reserved fields for future use. Drivers and applications must zero + this array. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + Given buffer type ``type`` or the selection target ``target`` is not + supported, or the ``flags`` argument is not valid. + +ERANGE + It is not possible to adjust struct :ref:`v4l2_rect <v4l2-rect>` + ``r`` rectangle to satisfy all constraints given in the ``flags`` + argument. + +EBUSY + It is not possible to apply change of the selection rectangle at the + moment. Usually because streaming is in progress. diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png b/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png Binary files differnew file mode 100644 index 000000000000..20228d2c5504 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png diff --git a/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst new file mode 100644 index 000000000000..76dd4ba3254f --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst @@ -0,0 +1,276 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_SLICED_VBI_CAP: + +***************************** +ioctl VIDIOC_G_SLICED_VBI_CAP +***************************** + +Name +==== + +VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_sliced_vbi_cap *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_SLICED_VBI_CAP + +``argp`` + + +Description +=========== + +To find out which data services are supported by a sliced VBI capture or +output device, applications initialize the ``type`` field of a struct +:ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>`, clear the +``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. The +driver fills in the remaining fields or returns an ``EINVAL`` error code if +the sliced VBI API is unsupported or ``type`` is invalid. + +Note the ``type`` field was added, and the ioctl changed from read-only +to write-read, in Linux 2.6.19. + + +.. _v4l2-sliced-vbi-cap: + +.. flat-table:: struct v4l2_sliced_vbi_cap + :header-rows: 0 + :stub-columns: 0 + :widths: 3 3 2 2 2 + + + - .. row 1 + + - __u16 + + - ``service_set`` + + - :cspan:`2` A set of all data services supported by the driver. + Equal to the union of all elements of the ``service_lines`` array. + + - .. row 2 + + - __u16 + + - ``service_lines``\ [2][24] + + - :cspan:`2` Each element of this array contains a set of data + services the hardware can look for or insert into a particular + scan line. Data services are defined in :ref:`vbi-services`. + Array indices map to ITU-R line numbers (see also :ref:`vbi-525` + and :ref:`vbi-625`) as follows: + + - .. row 3 + + - + - + - Element + + - 525 line systems + + - 625 line systems + + - .. row 4 + + - + - + - ``service_lines``\ [0][1] + + - 1 + + - 1 + + - .. row 5 + + - + - + - ``service_lines``\ [0][23] + + - 23 + + - 23 + + - .. row 6 + + - + - + - ``service_lines``\ [1][1] + + - 264 + + - 314 + + - .. row 7 + + - + - + - ``service_lines``\ [1][23] + + - 286 + + - 336 + + - .. row 8 + + - + + - .. row 9 + + - + - + - :cspan:`2` The number of VBI lines the hardware can capture or + output per frame, or the number of services it can identify on a + given line may be limited. For example on PAL line 16 the hardware + may be able to look for a VPS or Teletext signal, but not both at + the same time. Applications can learn about these limits using the + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in + :ref:`sliced`. + + - .. row 10 + + - + + - .. row 11 + + - + - + - :cspan:`2` Drivers must set ``service_lines`` [0][0] and + ``service_lines``\ [1][0] to zero. + + - .. row 12 + + - __u32 + + - ``type`` + + - Type of the data stream, see :ref:`v4l2-buf-type`. Should be + ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or + ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``. + + - .. row 13 + + - __u32 + + - ``reserved``\ [3] + + - :cspan:`2` This array is reserved for future extensions. + Applications and drivers must set it to zero. + + + +.. _vbi-services: + +.. flat-table:: Sliced VBI services + :header-rows: 1 + :stub-columns: 0 + :widths: 2 1 1 2 2 + + + - .. row 1 + + - Symbol + + - Value + + - Reference + + - Lines, usually + + - Payload + + - .. row 2 + + - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B) + + - 0x0001 + + - :ref:`ets300706`, :ref:`itu653` + + - PAL/SECAM line 7-22, 320-335 (second field 7-22) + + - Last 42 of the 45 byte Teletext packet, that is without clock + run-in and framing code, lsb first transmitted. + + - .. row 3 + + - ``V4L2_SLICED_VPS`` + + - 0x0400 + + - :ref:`ets300231` + + - PAL line 16 + + - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb + first transmitted. + + - .. row 4 + + - ``V4L2_SLICED_CAPTION_525`` + + - 0x1000 + + - :ref:`cea608` + + - NTSC line 21, 284 (second field 21) + + - Two bytes in transmission order, including parity bit, lsb first + transmitted. + + - .. row 5 + + - ``V4L2_SLICED_WSS_625`` + + - 0x4000 + + - :ref:`en300294`, :ref:`itu1119` + + - PAL/SECAM line 23 + + - + + :: + + Byte 0 1 + msb lsb msb lsb + Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + + - .. row 6 + + - ``V4L2_SLICED_VBI_525`` + + - 0x1000 + + - :cspan:`2` Set of services applicable to 525 line systems. + + - .. row 7 + + - ``V4L2_SLICED_VBI_625`` + + - 0x4401 + + - :cspan:`2` Set of services applicable to 625 line systems. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The value in the ``type`` field is wrong. diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst new file mode 100644 index 000000000000..5c2b861f8d26 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst @@ -0,0 +1,68 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_STD: + +******************************** +ioctl VIDIOC_G_STD, VIDIOC_S_STD +******************************** + +Name +==== + +VIDIOC_G_STD - VIDIOC_S_STD - Query or select the video standard of the current input + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, v4l2_std_id *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const v4l2_std_id *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_STD, VIDIOC_S_STD + +``argp`` + + +Description +=========== + +To query and select the current video standard applications use the +:ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctls which take a pointer to a +:ref:`v4l2_std_id <v4l2-std-id>` type as argument. :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` +can return a single flag or a set of flags as in struct +:ref:`v4l2_standard <v4l2-standard>` field ``id``. The flags must be +unambiguous such that they appear in only one enumerated +:ref:`struct v4l2_standard <v4l2-standard>` structure. + +:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` accepts one or more flags, being a write-only ioctl it +does not return the actual new standard as :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` does. When +no flags are given or the current input does not support the requested +standard the driver returns an ``EINVAL`` error code. When the standard set +is ambiguous drivers may return ``EINVAL`` or choose any of the requested +standards. If the current input or output does not support standard +video timings (e.g. if :ref:`VIDIOC_ENUMINPUT` +does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is +returned. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` parameter was unsuitable. + +ENODATA + Standard video timings are not supported for this input or output. diff --git a/Documentation/media/uapi/v4l/vidioc-g-tuner.rst b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst new file mode 100644 index 000000000000..a8d7ebd73e8a --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst @@ -0,0 +1,715 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_TUNER: + +************************************ +ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER +************************************ + +Name +==== + +VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_tuner *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_tuner *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_G_TUNER, VIDIOC_S_TUNER + +``argp`` + + +Description +=========== + +To query the attributes of a tuner applications initialize the ``index`` +field and zero out the ``reserved`` array of a struct +:ref:`v4l2_tuner <v4l2-tuner>` and call the ``VIDIOC_G_TUNER`` ioctl +with a pointer to this structure. Drivers fill the rest of the structure +or return an ``EINVAL`` error code when the index is out of bounds. To +enumerate all tuners applications shall begin at index zero, +incrementing by one until the driver returns ``EINVAL``. + +Tuners have two writable properties, the audio mode and the radio +frequency. To change the audio mode, applications initialize the +``index``, ``audmode`` and ``reserved`` fields and call the +``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner, +which is determined by the current video input. Drivers may choose a +different audio mode if the requested mode is invalid or unsupported. +Since this is a write-only ioctl, it does not return the actually +selected audio mode. + +:ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and +``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized +to zero. The term 'tuner' means SDR receiver in this context. + +To change the radio frequency the +:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. + + +.. _v4l2-tuner: + +.. flat-table:: struct v4l2_tuner + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``index`` + + - :cspan:`1` Identifies the tuner, set by the application. + + - .. row 2 + + - __u8 + + - ``name``\ [32] + + - :cspan:`1` + + Name of the tuner, a NUL-terminated ASCII string. This information + is intended for the user. + + - .. row 3 + + - __u32 + + - ``type`` + + - :cspan:`1` Type of the tuner, see :ref:`v4l2-tuner-type`. + + - .. row 4 + + - __u32 + + - ``capability`` + + - :cspan:`1` + + Tuner capability flags, see :ref:`tuner-capability`. Audio flags + indicate the ability to decode audio subprograms. They will *not* + change, for example with the current video standard. + + When the structure refers to a radio tuner the + ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and + ``V4L2_TUNER_CAP_NORM`` flags can't be used. + + If multiple frequency bands are supported, then ``capability`` is + the union of all ``capability`` fields of each struct + :ref:`v4l2_frequency_band <v4l2-frequency-band>`. + + - .. row 5 + + - __u32 + + - ``rangelow`` + + - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or + if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units + of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` + is set, in units of 1 Hz. If multiple frequency bands are + supported, then ``rangelow`` is the lowest frequency of all the + frequency bands. + + - .. row 6 + + - __u32 + + - ``rangehigh`` + + - :cspan:`1` The highest tunable frequency in units of 62.5 kHz, + or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in + units of 62.5 Hz, or if the ``capability`` flag + ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple + frequency bands are supported, then ``rangehigh`` is the highest + frequency of all the frequency bands. + + - .. row 7 + + - __u32 + + - ``rxsubchans`` + + - :cspan:`1` + + Some tuners or audio decoders can determine the received audio + subprograms by analyzing audio carriers, pilot tones or other + indicators. To pass this information drivers set flags defined in + :ref:`tuner-rxsubchans` in this field. For example: + + - .. row 8 + + - + - + - ``V4L2_TUNER_SUB_MONO`` + + - receiving mono audio + + - .. row 9 + + - + - + - ``STEREO | SAP`` + + - receiving stereo audio and a secondary audio program + + - .. row 10 + + - + - + - ``MONO | STEREO`` + + - receiving mono or stereo audio, the hardware cannot distinguish + + - .. row 11 + + - + - + - ``LANG1 | LANG2`` + + - receiving bilingual audio + + - .. row 12 + + - + - + - ``MONO | STEREO | LANG1 | LANG2`` + + - receiving mono, stereo or bilingual audio + + - .. row 13 + + - + - + - :cspan:`1` + + When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or + ``_SAP`` flag is cleared in the ``capability`` field, the + corresponding ``V4L2_TUNER_SUB_`` flag must not be set here. + + This field is valid only if this is the tuner of the current video + input, or when the structure refers to a radio tuner. + + - .. row 14 + + - __u32 + + - ``audmode`` + + - :cspan:`1` + + The selected audio mode, see :ref:`tuner-audmode` for valid + values. The audio mode does not affect audio subprogram detection, + and like a :ref:`control` it does not automatically + change unless the requested mode is invalid or unsupported. See + :ref:`tuner-matrix` for possible results when the selected and + received audio programs do not match. + + Currently this is the only field of struct + :ref:`struct v4l2_tuner <v4l2-tuner>` applications can change. + + - .. row 15 + + - __u32 + + - ``signal`` + + - :cspan:`1` The signal strength if known, ranging from 0 to + 65535. Higher values indicate a better signal. + + - .. row 16 + + - __s32 + + - ``afc`` + + - :cspan:`1` Automatic frequency control: When the ``afc`` value + is negative, the frequency is too low, when positive too high. + + - .. row 17 + + - __u32 + + - ``reserved``\ [4] + + - :cspan:`1` Reserved for future extensions. Drivers and + applications must set the array to zero. + + + +.. _v4l2-tuner-type: + +.. flat-table:: enum v4l2_tuner_type + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_TUNER_RADIO`` + + - 1 + + - + + - .. row 2 + + - ``V4L2_TUNER_ANALOG_TV`` + + - 2 + + - + + - .. row 3 + + - ``V4L2_TUNER_SDR`` + + - 4 + + - + + - .. row 4 + + - ``V4L2_TUNER_RF`` + + - 5 + + - + + + +.. _tuner-capability: + +.. flat-table:: Tuner and Modulator Capability Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_TUNER_CAP_LOW`` + + - 0x0001 + + - When set, tuning frequencies are expressed in units of 62.5 Hz + instead of 62.5 kHz. + + - .. row 2 + + - ``V4L2_TUNER_CAP_NORM`` + + - 0x0002 + + - This is a multi-standard tuner; the video standard can or must be + switched. (B/G PAL tuners for example are typically not considered + multi-standard because the video standard is automatically + determined from the frequency band.) The set of supported video + standards is available from the struct + :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the + description of ioctl :ref:`VIDIOC_ENUMINPUT` + for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this + capability. + + - .. row 3 + + - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED`` + + - 0x0004 + + - If set, then this tuner supports the hardware seek functionality + where the seek stops when it reaches the end of the frequency + range. + + - .. row 4 + + - ``V4L2_TUNER_CAP_HWSEEK_WRAP`` + + - 0x0008 + + - If set, then this tuner supports the hardware seek functionality + where the seek wraps around when it reaches the end of the + frequency range. + + - .. row 5 + + - ``V4L2_TUNER_CAP_STEREO`` + + - 0x0010 + + - Stereo audio reception is supported. + + - .. row 6 + + - ``V4L2_TUNER_CAP_LANG1`` + + - 0x0040 + + - Reception of the primary language of a bilingual audio program is + supported. Bilingual audio is a feature of two-channel systems, + transmitting the primary language monaural on the main audio + carrier and a secondary language monaural on a second carrier. + Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability. + + - .. row 7 + + - ``V4L2_TUNER_CAP_LANG2`` + + - 0x0020 + + - Reception of the secondary language of a bilingual audio program + is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this + capability. + + - .. row 8 + + - ``V4L2_TUNER_CAP_SAP`` + + - 0x0020 + + - Reception of a secondary audio program is supported. This is a + feature of the BTSC system which accompanies the NTSC video + standard. Two audio carriers are available for mono or stereo + transmissions of a primary language, and an independent third + carrier for a monaural secondary language. Only + ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability. + + Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags + are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner + supports the ``V4L2_STD_NTSC_M`` video standard. + + - .. row 9 + + - ``V4L2_TUNER_CAP_RDS`` + + - 0x0080 + + - RDS capture is supported. This capability is only valid for radio + tuners. + + - .. row 10 + + - ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` + + - 0x0100 + + - The RDS data is passed as unparsed RDS blocks. + + - .. row 11 + + - ``V4L2_TUNER_CAP_RDS_CONTROLS`` + + - 0x0200 + + - The RDS data is parsed by the hardware and set via controls. + + - .. row 12 + + - ``V4L2_TUNER_CAP_FREQ_BANDS`` + + - 0x0400 + + - The :ref:`VIDIOC_ENUM_FREQ_BANDS` + ioctl can be used to enumerate the available frequency bands. + + - .. row 13 + + - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` + + - 0x0800 + + - The range to search when using the hardware seek functionality is + programmable, see + :ref:`VIDIOC_S_HW_FREQ_SEEK` for + details. + + - .. row 14 + + - ``V4L2_TUNER_CAP_1HZ`` + + - 0x1000 + + - When set, tuning frequencies are expressed in units of 1 Hz + instead of 62.5 kHz. + + + +.. _tuner-rxsubchans: + +.. flat-table:: Tuner Audio Reception Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_TUNER_SUB_MONO`` + + - 0x0001 + + - The tuner receives a mono audio signal. + + - .. row 2 + + - ``V4L2_TUNER_SUB_STEREO`` + + - 0x0002 + + - The tuner receives a stereo audio signal. + + - .. row 3 + + - ``V4L2_TUNER_SUB_LANG1`` + + - 0x0008 + + - The tuner receives the primary language of a bilingual audio + signal. Drivers must clear this flag when the current video + standard is ``V4L2_STD_NTSC_M``. + + - .. row 4 + + - ``V4L2_TUNER_SUB_LANG2`` + + - 0x0004 + + - The tuner receives the secondary language of a bilingual audio + signal (or a second audio program). + + - .. row 5 + + - ``V4L2_TUNER_SUB_SAP`` + + - 0x0004 + + - The tuner receives a Second Audio Program. Note the + ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are + synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current + video standard is ``V4L2_STD_NTSC_M``. + + - .. row 6 + + - ``V4L2_TUNER_SUB_RDS`` + + - 0x0010 + + - The tuner receives an RDS channel. + + + +.. _tuner-audmode: + +.. flat-table:: Tuner Audio Modes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_TUNER_MODE_MONO`` + + - 0 + + - Play mono audio. When the tuner receives a stereo signal this a + down-mix of the left and right channel. When the tuner receives a + bilingual or SAP signal this mode selects the primary language. + + - .. row 2 + + - ``V4L2_TUNER_MODE_STEREO`` + + - 1 + + - Play stereo audio. When the tuner receives bilingual audio it may + play different languages on the left and right channel or the + primary language is played on both channels. + + Playing different languages in this mode is deprecated. New + drivers should do this only in ``MODE_LANG1_LANG2``. + + When the tuner receives no stereo signal or does not support + stereo reception the driver shall fall back to ``MODE_MONO``. + + - .. row 3 + + - ``V4L2_TUNER_MODE_LANG1`` + + - 3 + + - Play the primary language, mono or stereo. Only + ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. + + - .. row 4 + + - ``V4L2_TUNER_MODE_LANG2`` + + - 2 + + - Play the secondary language, mono. When the tuner receives no + bilingual audio or SAP, or their reception is not supported the + driver shall fall back to mono or stereo mode. Only + ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. + + - .. row 5 + + - ``V4L2_TUNER_MODE_SAP`` + + - 2 + + - Play the Second Audio Program. When the tuner receives no + bilingual audio or SAP, or their reception is not supported the + driver shall fall back to mono or stereo mode. Only + ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the + ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are + synonyms. + + - .. row 6 + + - ``V4L2_TUNER_MODE_LANG1_LANG2`` + + - 4 + + - Play the primary language on the left channel, the secondary + language on the right channel. When the tuner receives no + bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or + ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this + mode. + + + +.. _tuner-matrix: + +.. flat-table:: Tuner Audio Matrix + :header-rows: 2 + :stub-columns: 0 + + + - .. row 1 + + - + - :cspan:`5` Selected ``V4L2_TUNER_MODE_`` + + - .. row 2 + + - Received ``V4L2_TUNER_SUB_`` + + - ``MONO`` + + - ``STEREO`` + + - ``LANG1`` + + - ``LANG2 = SAP`` + + - ``LANG1_LANG2``\ [1]_ + + - .. row 3 + + - ``MONO`` + + - Mono + + - Mono/Mono + + - Mono + + - Mono + + - Mono/Mono + + - .. row 4 + + - ``MONO | SAP`` + + - Mono + + - Mono/Mono + + - Mono + + - SAP + + - Mono/SAP (preferred) or Mono/Mono + + - .. row 5 + + - ``STEREO`` + + - L+R + + - L/R + + - Stereo L/R (preferred) or Mono L+R + + - Stereo L/R (preferred) or Mono L+R + + - L/R (preferred) or L+R/L+R + + - .. row 6 + + - ``STEREO | SAP`` + + - L+R + + - L/R + + - Stereo L/R (preferred) or Mono L+R + + - SAP + + - L+R/SAP (preferred) or L/R or L+R/L+R + + - .. row 7 + + - ``LANG1 | LANG2`` + + - Language 1 + + - Lang1/Lang2 (deprecated [2]_) or Lang1/Lang1 + + - Language 1 + + - Language 2 + + - Lang1/Lang2 (preferred) or Lang1/Lang1 + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of + bounds. + +.. [1] + This mode has been added in Linux 2.6.17 and may not be supported by + older drivers. + +.. [2] + Playback of both languages in ``MODE_STEREO`` is deprecated. In the + future drivers should produce only the primary language in this mode. + Applications should request ``MODE_LANG1_LANG2`` to record both + languages or a stereo signal. diff --git a/Documentation/media/uapi/v4l/vidioc-log-status.rst b/Documentation/media/uapi/v4l/vidioc-log-status.rst new file mode 100644 index 000000000000..66fc352c0ffa --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-log-status.rst @@ -0,0 +1,46 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_LOG_STATUS: + +*********************** +ioctl VIDIOC_LOG_STATUS +*********************** + +Name +==== + +VIDIOC_LOG_STATUS - Log driver status information + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request ) + + +Arguments +========= + + + +Description +=========== + +As the video/audio devices become more complicated it becomes harder to +debug problems. When this ioctl is called the driver will output the +current device status to the kernel log. This is particular useful when +dealing with problems like no sound, no video and incorrectly tuned +channels. Also many modern devices autodetect video and audio standards +and this ioctl will report what the device thinks what the standard is. +Mismatches may give an indication where the problem is. + +This ioctl is optional and not all drivers support it. It was introduced +in Linux 2.6.15. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-overlay.rst b/Documentation/media/uapi/v4l/vidioc-overlay.rst new file mode 100644 index 000000000000..191dbc144ef7 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-overlay.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_OVERLAY: + +******************** +ioctl VIDIOC_OVERLAY +******************** + +Name +==== + +VIDIOC_OVERLAY - Start or stop video overlay + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, const int *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_OVERLAY + +``argp`` + + +Description +=========== + +This ioctl is part of the :ref:`video overlay <overlay>` I/O method. +Applications call :ref:`VIDIOC_OVERLAY` to start or stop the overlay. It +takes a pointer to an integer which must be set to zero by the +application to stop overlay, to one to start. + +Drivers do not support :ref:`VIDIOC_STREAMON` or +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with +``V4L2_BUF_TYPE_VIDEO_OVERLAY``. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The overlay parameters have not been set up. See :ref:`overlay` + for the necessary steps. diff --git a/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst new file mode 100644 index 000000000000..79076dff46fd --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_PREPARE_BUF: + +************************ +ioctl VIDIOC_PREPARE_BUF +************************ + +Name +==== + +VIDIOC_PREPARE_BUF - Prepare a buffer for I/O + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_PREPARE_BUF + +``argp`` + + +Description +=========== + +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` 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. + +The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in +:ref:`buffer`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EBUSY + File I/O is in progress. + +EINVAL + The buffer ``type`` is not supported, or the ``index`` is out of + bounds, or no buffers have been allocated yet, or the ``userptr`` or + ``length`` are invalid. diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst new file mode 100644 index 000000000000..9870d243131a --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -0,0 +1,150 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_QBUF: + +******************************* +ioctl VIDIOC_QBUF, VIDIOC_DQBUF +******************************* + +Name +==== + +VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_QBUF, VIDIOC_DQBUF + +``argp`` + + +Description +=========== + +Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty +(capturing) or filled (output) buffer in the driver's incoming queue. +The semantics depend on the selected I/O method. + +To enqueue a buffer applications set the ``type`` field of a struct +:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was +previously used with struct :ref:`v4l2_format <v4l2-format>` ``type`` +and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``. +Applications must also set the ``index`` field. Valid index numbers +range from zero to the number of buffers allocated with +:ref:`VIDIOC_REQBUFS` (struct +:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus +one. The contents of the struct :ref:`struct v4l2_buffer <v4l2-buffer>` returned +by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well. +When the buffer is intended for output (``type`` is +``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``, +or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the +``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer` +for details. Applications must also set ``flags`` to 0. The +``reserved2`` and ``reserved`` fields must be set to 0. When using the +:ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must +contain a userspace pointer to a filled-in array of struct +:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field must be set +to the number of elements in that array. + +To enqueue a :ref:`memory mapped <mmap>` buffer applications set the +``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called +with a pointer to this structure the driver sets the +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears +the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an +EINVAL error code. + +To enqueue a :ref:`user pointer <userp>` buffer applications set the +``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to +the address of the buffer and ``length`` to its size. When the +multi-planar API is used, ``m.userptr`` and ``length`` members of the +passed array of struct :ref:`v4l2_plane <v4l2-plane>` have to be used +instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure +the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the +``flags`` field, or it returns an error code. This ioctl locks the +memory pages of the buffer in physical memory, they cannot be swapped +out to disk. Buffers remain locked until dequeued, until the +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or +:ref:`VIDIOC_REQBUFS` ioctl is called, or until the +device is closed. + +To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the +``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a +file descriptor associated with a DMABUF buffer. When the multi-planar +API is used the ``m.fd`` fields of the passed array of struct +:ref:`v4l2_plane <v4l2-plane>` have to be used instead. When +``VIDIOC_QBUF`` is called with a pointer to this structure the driver +sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the +``flags`` field, or it returns an error code. This ioctl locks the +buffer. Locking a buffer means passing it to a driver for a hardware +access (usually DMA). If an application accesses (reads/writes) a locked +buffer then the result is undefined. Buffers remain locked until +dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or +:ref:`VIDIOC_REQBUFS` ioctl is called, or until the +device is closed. + +Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled +(capturing) or displayed (output) buffer from the driver's outgoing +queue. They just set the ``type``, ``memory`` and ``reserved`` fields of +a struct :ref:`v4l2_buffer <v4l2-buffer>` as above, when +``VIDIOC_DQBUF`` is called with a pointer to this structure the driver +fills the remaining fields or returns an error code. The driver may also +set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a +non-critical (recoverable) streaming error. In such case the application +may continue as normal, but should be aware that data in the dequeued +buffer might be corrupted. When using the multi-planar API, the planes +array must be passed in as well. + +By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing +queue. When the ``O_NONBLOCK`` flag was given to the +:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns +immediately with an ``EAGAIN`` error code when no buffer is available. + +The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in +:ref:`buffer`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EAGAIN + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no + buffer was in the outgoing queue. + +EINVAL + The buffer ``type`` is not supported, or the ``index`` is out of + bounds, or no buffers have been allocated yet, or the ``userptr`` or + ``length`` are invalid. + +EIO + ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate + temporary problems like signal loss. Note the driver might dequeue + an (empty) buffer despite returning an error, or even stop + capturing. Reusing such buffer may be unsafe though and its details + (e.g. ``index``) may not be returned either. It is recommended that + drivers indicate recoverable errors by setting the + ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the + application should be able to safely reuse the buffer and continue + streaming. + +EPIPE + ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem + codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already + dequeued and no new buffers are expected to become available. diff --git a/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst new file mode 100644 index 000000000000..338b80df5b9b --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst @@ -0,0 +1,83 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_QUERY_DV_TIMINGS: + +***************************** +ioctl VIDIOC_QUERY_DV_TIMINGS +***************************** + +Name +==== + +VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_QUERY_DV_TIMINGS, VIDIOC_SUBDEV_QUERY_DV_TIMINGS + +``argp`` + + +Description +=========== + +The hardware may be able to detect the current DV timings automatically, +similar to sensing the video standard. To do so, applications call +:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct +:ref:`v4l2_dv_timings <v4l2-dv-timings>`. Once the hardware detects +the timings, it will fill in the timings structure. + +Please note that drivers shall *not* switch timings automatically if new +timings are detected. Instead, drivers should send the +``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect +that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`. +The reason is that new timings usually mean different buffer sizes as +well, and you cannot change buffer sizes on the fly. In general, +applications that receive the Source Change event will have to call +:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they +will have to stop streaming, set the new timings, allocate new buffers +and start streaming again. + +If the timings could not be detected because there was no signal, then +ENOLINK is returned. If a signal was detected, but it was unstable and +the receiver could not lock to the signal, then ``ENOLCK`` is returned. If +the receiver could lock to the signal, but the format is unsupported +(e.g. because the pixelclock is out of range of the hardware +capabilities), then the driver fills in whatever timings it could find +and returns ``ERANGE``. In that case the application can call +:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the +found timings with the hardware's capabilities in order to give more +precise feedback to the user. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +ENODATA + Digital video timings are not supported for this input or output. + +ENOLINK + No timings could be detected because no signal was found. + +ENOLCK + The signal was unstable and the hardware could not lock on to it. + +ERANGE + Timings were found, but they are out of range of the hardware + capabilities. diff --git a/Documentation/media/uapi/v4l/vidioc-querybuf.rst b/Documentation/media/uapi/v4l/vidioc-querybuf.rst new file mode 100644 index 000000000000..32af6f7b5060 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-querybuf.rst @@ -0,0 +1,81 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_QUERYBUF: + +********************* +ioctl VIDIOC_QUERYBUF +********************* + +Name +==== + +VIDIOC_QUERYBUF - Query the status of a buffer + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_QUERYBUF + +``argp`` + + +Description +=========== + +This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can +be used to query the status of a buffer at any time after buffers have +been allocated with the :ref:`VIDIOC_REQBUFS` ioctl. + +Applications set the ``type`` field of a struct +:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was +previously used with struct :ref:`v4l2_format <v4l2-format>` ``type`` +and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, +and the ``index`` field. Valid index numbers range from zero to the +number of buffers allocated with +:ref:`VIDIOC_REQBUFS` (struct +:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus +one. The ``reserved`` and ``reserved2`` fields must be set to 0. When +using the :ref:`multi-planar API <planar-apis>`, the ``m.planes`` +field must contain a userspace pointer to an array of struct +:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field has to be set +to the number of elements in that array. After calling +:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an +error code or fill the rest of the structure. + +In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``, +``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and +``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be +set to the current I/O method. For the single-planar API, the +``m.offset`` contains the offset of the buffer from the start of the +device memory, the ``length`` field its size. For the multi-planar API, +fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array +elements will be used instead and the ``length`` field of struct +:ref:`v4l2_buffer <v4l2-buffer>` is set to the number of filled-in +array elements. The driver may or may not set the remaining fields and +flags, they are meaningless in this context. + +The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in +:ref:`buffer`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The buffer ``type`` is not supported, or the ``index`` is out of + bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst new file mode 100644 index 000000000000..f0271f834ac1 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst @@ -0,0 +1,434 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_QUERYCAP: + +********************* +ioctl VIDIOC_QUERYCAP +********************* + +Name +==== + +VIDIOC_QUERYCAP - Query device capabilities + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_capability *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_QUERYCAP + +``argp`` + + +Description +=========== + +All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to +identify kernel devices compatible with this specification and to obtain +information about driver and hardware capabilities. The ioctl takes a +pointer to a struct :ref:`v4l2_capability <v4l2-capability>` which is +filled by the driver. When the driver is not compatible with this +specification the ioctl returns an ``EINVAL`` error code. + + +.. _v4l2-capability: + +.. flat-table:: struct v4l2_capability + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u8 + + - ``driver``\ [16] + + - Name of the driver, a unique NUL-terminated ASCII string. For + example: "bttv". Driver specific applications can use this + information to verify the driver identity. It is also useful to + work around known bugs, or to identify drivers in error reports. + + Storing strings in fixed sized arrays is bad practice but + unavoidable here. Drivers and applications should take precautions + to never read or write beyond the end of the array and to make + sure the strings are properly NUL-terminated. + + - .. row 2 + + - __u8 + + - ``card``\ [32] + + - Name of the device, a NUL-terminated UTF-8 string. For example: + "Yoyodyne TV/FM". One driver may support different brands or + models of video hardware. This information is intended for users, + for example in a menu of available devices. Since multiple TV + cards of the same brand may be installed which are supported by + the same driver, this name should be combined with the character + device file name (e. g. ``/dev/video2``) or the ``bus_info`` + string to avoid ambiguities. + + - .. row 3 + + - __u8 + + - ``bus_info``\ [32] + + - Location of the device in the system, a NUL-terminated ASCII + string. For example: "PCI:0000:05:06.0". This information is + intended for users, to distinguish multiple identical devices. If + no such information is available the field must simply count the + devices controlled by the driver ("platform:vivi-000"). The + bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI + Express boards, "usb-" for USB devices, "I2C:" for i2c devices, + "ISA:" for ISA devices, "parport" for parallel port devices and + "platform:" for platform devices. + + - .. row 4 + + - __u32 + + - ``version`` + + - Version number of the driver. + + Starting with kernel 3.1, the version reported is provided by the + V4L2 subsystem following the kernel numbering scheme. However, it + may not always return the same version as the kernel if, for + example, a stable or distribution-modified kernel uses the V4L2 + stack from a newer kernel. + + The version number is formatted using the ``KERNEL_VERSION()`` + macro: + + - .. row 5 + + - :cspan:`2` + + + .. code-block:: c + + #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) + + __u32 version = KERNEL_VERSION(0, 8, 1); + + printf ("Version: %u.%u.%u\\n", + (version >> 16) & 0xFF, + (version >> 8) & 0xFF, + version & 0xFF); + + - .. row 6 + + - __u32 + + - ``capabilities`` + + - Available capabilities of the physical device as a whole, see + :ref:`device-capabilities`. The same physical device can export + multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and + /dev/radioZ). The ``capabilities`` field should contain a union of + all capabilities available around the several V4L2 devices + exported to userspace. For all those devices the ``capabilities`` + field returns the same set of capabilities. This allows + applications to open just one of the devices (typically the video + device) and discover whether video, vbi and/or radio are also + supported. + + - .. row 7 + + - __u32 + + - ``device_caps`` + + - Device capabilities of the opened device, see + :ref:`device-capabilities`. Should contain the available + capabilities of that specific device node. So, for example, + ``device_caps`` of a radio device will only contain radio related + capabilities and no video or vbi capabilities. This field is only + set if the ``capabilities`` field contains the + ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities`` + field can have the ``V4L2_CAP_DEVICE_CAPS`` capability, + ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``. + + - .. row 8 + + - __u32 + + - ``reserved``\ [3] + + - Reserved for future extensions. Drivers must set this array to + zero. + + + +.. _device-capabilities: + +.. flat-table:: Device Capabilities Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_CAP_VIDEO_CAPTURE`` + + - 0x00000001 + + - The device supports the single-planar API through the + :ref:`Video Capture <capture>` interface. + + - .. row 2 + + - ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` + + - 0x00001000 + + - The device supports the :ref:`multi-planar API <planar-apis>` + through the :ref:`Video Capture <capture>` interface. + + - .. row 3 + + - ``V4L2_CAP_VIDEO_OUTPUT`` + + - 0x00000002 + + - The device supports the single-planar API through the + :ref:`Video Output <output>` interface. + + - .. row 4 + + - ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` + + - 0x00002000 + + - The device supports the :ref:`multi-planar API <planar-apis>` + through the :ref:`Video Output <output>` interface. + + - .. row 5 + + - ``V4L2_CAP_VIDEO_M2M`` + + - 0x00004000 + + - The device supports the single-planar API through the Video + Memory-To-Memory interface. + + - .. row 6 + + - ``V4L2_CAP_VIDEO_M2M_MPLANE`` + + - 0x00008000 + + - The device supports the :ref:`multi-planar API <planar-apis>` + through the Video Memory-To-Memory interface. + + - .. row 7 + + - ``V4L2_CAP_VIDEO_OVERLAY`` + + - 0x00000004 + + - The device supports the :ref:`Video Overlay <overlay>` + interface. A video overlay device typically stores captured images + directly in the video memory of a graphics card, with hardware + clipping and scaling. + + - .. row 8 + + - ``V4L2_CAP_VBI_CAPTURE`` + + - 0x00000010 + + - The device supports the :ref:`Raw VBI Capture <raw-vbi>` + interface, providing Teletext and Closed Caption data. + + - .. row 9 + + - ``V4L2_CAP_VBI_OUTPUT`` + + - 0x00000020 + + - The device supports the :ref:`Raw VBI Output <raw-vbi>` + interface. + + - .. row 10 + + - ``V4L2_CAP_SLICED_VBI_CAPTURE`` + + - 0x00000040 + + - The device supports the :ref:`Sliced VBI Capture <sliced>` + interface. + + - .. row 11 + + - ``V4L2_CAP_SLICED_VBI_OUTPUT`` + + - 0x00000080 + + - The device supports the :ref:`Sliced VBI Output <sliced>` + interface. + + - .. row 12 + + - ``V4L2_CAP_RDS_CAPTURE`` + + - 0x00000100 + + - The device supports the :ref:`RDS <rds>` capture interface. + + - .. row 13 + + - ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` + + - 0x00000200 + + - The device supports the :ref:`Video Output Overlay <osd>` (OSD) + interface. Unlike the *Video Overlay* interface, this is a + secondary function of video output devices and overlays an image + onto an outgoing video signal. When the driver sets this flag, it + must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice + versa. [1]_ + + - .. row 14 + + - ``V4L2_CAP_HW_FREQ_SEEK`` + + - 0x00000400 + + - The device supports the + :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl + for hardware frequency seeking. + + - .. row 15 + + - ``V4L2_CAP_RDS_OUTPUT`` + + - 0x00000800 + + - The device supports the :ref:`RDS <rds>` output interface. + + - .. row 16 + + - ``V4L2_CAP_TUNER`` + + - 0x00010000 + + - The device has some sort of tuner to receive RF-modulated video + signals. For more information about tuner programming see + :ref:`tuner`. + + - .. row 17 + + - ``V4L2_CAP_AUDIO`` + + - 0x00020000 + + - The device has audio inputs or outputs. It may or may not support + audio recording or playback, in PCM or compressed formats. PCM + audio support must be implemented as ALSA or OSS interface. For + more information on audio inputs and outputs see :ref:`audio`. + + - .. row 18 + + - ``V4L2_CAP_RADIO`` + + - 0x00040000 + + - This is a radio receiver. + + - .. row 19 + + - ``V4L2_CAP_MODULATOR`` + + - 0x00080000 + + - The device has some sort of modulator to emit RF-modulated + video/audio signals. For more information about modulator + programming see :ref:`tuner`. + + - .. row 20 + + - ``V4L2_CAP_SDR_CAPTURE`` + + - 0x00100000 + + - The device supports the :ref:`SDR Capture <sdr>` interface. + + - .. row 21 + + - ``V4L2_CAP_EXT_PIX_FORMAT`` + + - 0x00200000 + + - The device supports the struct + :ref:`v4l2_pix_format <v4l2-pix-format>` extended fields. + + - .. row 22 + + - ``V4L2_CAP_SDR_OUTPUT`` + + - 0x00400000 + + - The device supports the :ref:`SDR Output <sdr>` interface. + + - .. row 23 + + - ``V4L2_CAP_READWRITE`` + + - 0x01000000 + + - The device supports the :ref:`read() <rw>` and/or + :ref:`write() <rw>` I/O methods. + + - .. row 24 + + - ``V4L2_CAP_ASYNCIO`` + + - 0x02000000 + + - The device supports the :ref:`asynchronous <async>` I/O methods. + + - .. row 25 + + - ``V4L2_CAP_STREAMING`` + + - 0x04000000 + + - The device supports the :ref:`streaming <mmap>` I/O method. + + - .. row 26 + + - ``V4L2_CAP_DEVICE_CAPS`` + + - 0x80000000 + + - The driver fills the ``device_caps`` field. This capability can + only appear in the ``capabilities`` field and never in the + ``device_caps`` field. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +.. [1] + The struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` lacks an + enum :ref:`v4l2_buf_type <v4l2-buf-type>` field, therefore the + type of overlay is implied by the driver capabilities. diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst new file mode 100644 index 000000000000..0f27e712eec9 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -0,0 +1,780 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_QUERYCTRL: + +******************************************************************* +ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU +******************************************************************* + +Name +==== + +VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_queryctrl *argp ) + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_query_ext_ctrl *argp ) + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_querymenu *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU + +``argp`` + + +Description +=========== + +To query the attributes of a control applications set the ``id`` field +of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the +``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver +fills the rest of the structure or returns an ``EINVAL`` error code when the +``id`` is invalid. + +It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL`` +with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and +exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in +this range is not supported. Further applications can enumerate private +controls, which are not defined in this specification, by starting at +``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver +returns ``EINVAL``. + +In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag +in the ``flags`` field this control is permanently disabled and should +be ignored by the application. [1]_ + +When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the +driver returns the next supported non-compound control, or ``EINVAL`` if +there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag +can be specified to enumerate all compound controls (i.e. controls with +type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words +controls that contain more than one value). Specify both +``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in +order to enumerate all controls, compound or not. Drivers which do not +support these flags yet always return ``EINVAL``. + +The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better +support controls that can use compound types, and to expose additional +control information that cannot be returned in struct +:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full. + +``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as +``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed +as well. + +Additional information is required for menu controls: the names of the +menu items. To query them applications set the ``id`` and ``index`` +fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the +``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver +fills the rest of the structure or returns an ``EINVAL`` error code when the +``id`` or ``index`` is invalid. Menu items are enumerated by calling +``VIDIOC_QUERYMENU`` with successive ``index`` values from struct +:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``, +inclusive. Note that it is possible for ``VIDIOC_QUERYMENU`` to return +an ``EINVAL`` error code for some indices between ``minimum`` and +``maximum``. In that case that particular menu item is not supported by +this driver. Also note that the ``minimum`` value is not necessarily 0. + +See also the examples in :ref:`control`. + + +.. _v4l2-queryctrl: + +.. flat-table:: struct v4l2_queryctrl + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``id`` + + - Identifies the control, set by the application. See + :ref:`control-id` for predefined IDs. When the ID is ORed with + V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and + returns the first control with a higher ID. Drivers which do not + support this flag yet always return an ``EINVAL`` error code. + + - .. row 2 + + - __u32 + + - ``type`` + + - Type of control, see :ref:`v4l2-ctrl-type`. + + - .. row 3 + + - __u8 + + - ``name``\ [32] + + - Name of the control, a NUL-terminated ASCII string. This + information is intended for the user. + + - .. row 4 + + - __s32 + + - ``minimum`` + + - Minimum value, inclusive. This field gives a lower bound for the + control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how + the minimum value is to be used for each possible control type. + Note that this a signed 32-bit value. + + - .. row 5 + + - __s32 + + - ``maximum`` + + - Maximum value, inclusive. This field gives an upper bound for the + control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how + the maximum value is to be used for each possible control type. + Note that this a signed 32-bit value. + + - .. row 6 + + - __s32 + + - ``step`` + + - This field gives a step size for the control. See enum + :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is + to be used for each possible control type. Note that this an + unsigned 32-bit value. + + Generally drivers should not scale hardware control values. It may + be necessary for example when the ``name`` or ``id`` imply a + particular unit and the hardware actually accepts only multiples + of said unit. If so, drivers must take care values are properly + rounded when scaling, such that errors will not accumulate on + repeated read-write cycles. + + This field gives the smallest change of an integer control + actually affecting hardware. Often the information is needed when + the user can change controls by keyboard or GUI buttons, rather + than a slider. When for example a hardware register accepts values + 0-511 and the driver reports 0-65535, step should be 128. + + Note that although signed, the step value is supposed to be always + positive. + + - .. row 7 + + - __s32 + + - ``default_value`` + + - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``, + ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid + for other types of controls. Note that drivers reset controls to + their default value only when the driver is first loaded, never + afterwards. + + - .. row 8 + + - __u32 + + - ``flags`` + + - Control flags, see :ref:`control-flags`. + + - .. row 9 + + - __u32 + + - ``reserved``\ [2] + + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _v4l2-query-ext-ctrl: + +.. flat-table:: struct v4l2_query_ext_ctrl + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``id`` + + - Identifies the control, set by the application. See + :ref:`control-id` for predefined IDs. When the ID is ORed with + ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and + returns the first non-compound control with a higher ID. When the + ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears + the flag and returns the first compound control with a higher ID. + Set both to get the first control (compound or not) with a higher + ID. + + - .. row 2 + + - __u32 + + - ``type`` + + - Type of control, see :ref:`v4l2-ctrl-type`. + + - .. row 3 + + - char + + - ``name``\ [32] + + - Name of the control, a NUL-terminated ASCII string. This + information is intended for the user. + + - .. row 4 + + - __s64 + + - ``minimum`` + + - Minimum value, inclusive. This field gives a lower bound for the + control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how + the minimum value is to be used for each possible control type. + Note that this a signed 64-bit value. + + - .. row 5 + + - __s64 + + - ``maximum`` + + - Maximum value, inclusive. This field gives an upper bound for the + control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how + the maximum value is to be used for each possible control type. + Note that this a signed 64-bit value. + + - .. row 6 + + - __u64 + + - ``step`` + + - This field gives a step size for the control. See enum + :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is + to be used for each possible control type. Note that this an + unsigned 64-bit value. + + Generally drivers should not scale hardware control values. It may + be necessary for example when the ``name`` or ``id`` imply a + particular unit and the hardware actually accepts only multiples + of said unit. If so, drivers must take care values are properly + rounded when scaling, such that errors will not accumulate on + repeated read-write cycles. + + This field gives the smallest change of an integer control + actually affecting hardware. Often the information is needed when + the user can change controls by keyboard or GUI buttons, rather + than a slider. When for example a hardware register accepts values + 0-511 and the driver reports 0-65535, step should be 128. + + - .. row 7 + + - __s64 + + - ``default_value`` + + - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``, + ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8`` + or ``_U16`` control. Not valid for other types of controls. Note + that drivers reset controls to their default value only when the + driver is first loaded, never afterwards. + + - .. row 8 + + - __u32 + + - ``flags`` + + - Control flags, see :ref:`control-flags`. + + - .. row 9 + + - __u32 + + - ``elem_size`` + + - The size in bytes of a single element of the array. Given a char + pointer ``p`` to a 3-dimensional array you can find the position + of cell ``(z, y, x)`` as follows: + ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``. + ``elem_size`` is always valid, also when the control isn't an + array. For string controls ``elem_size`` is equal to + ``maximum + 1``. + + - .. row 10 + + - __u32 + + - ``elems`` + + - The number of elements in the N-dimensional array. If this control + is not an array, then ``elems`` is 1. The ``elems`` field can + never be 0. + + - .. row 11 + + - __u32 + + - ``nr_of_dims`` + + - The number of dimension in the N-dimensional array. If this + control is not an array, then this field is 0. + + - .. row 12 + + - __u32 + + - ``dims[V4L2_CTRL_MAX_DIMS]`` + + - The size of each dimension. The first ``nr_of_dims`` elements of + this array must be non-zero, all remaining elements must be zero. + + - .. row 13 + + - __u32 + + - ``reserved``\ [32] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + + +.. _v4l2-querymenu: + +.. flat-table:: struct v4l2_querymenu + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 1 + + + - .. row 1 + + - __u32 + + - + - ``id`` + + - Identifies the control, set by the application from the respective + struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``. + + - .. row 2 + + - __u32 + + - + - ``index`` + + - Index of the menu item, starting at zero, set by the application. + + - .. row 3 + + - union + + - + - + - + + - .. row 4 + + - + - __u8 + + - ``name``\ [32] + + - Name of the menu item, a NUL-terminated ASCII string. This + information is intended for the user. This field is valid for + ``V4L2_CTRL_FLAG_MENU`` type controls. + + - .. row 5 + + - + - __s64 + + - ``value`` + + - Value of the integer menu item. This field is valid for + ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls. + + - .. row 6 + + - __u32 + + - + - ``reserved`` + + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. _v4l2-ctrl-type: + +.. flat-table:: enum v4l2_ctrl_type + :header-rows: 1 + :stub-columns: 0 + :widths: 30 5 5 5 55 + + + - .. row 1 + + - Type + + - ``minimum`` + + - ``step`` + + - ``maximum`` + + - Description + + - .. row 2 + + - ``V4L2_CTRL_TYPE_INTEGER`` + + - any + + - any + + - any + + - An integer-valued control ranging from minimum to maximum + inclusive. The step value indicates the increment between values. + + - .. row 3 + + - ``V4L2_CTRL_TYPE_BOOLEAN`` + + - 0 + + - 1 + + - 1 + + - A boolean-valued control. Zero corresponds to "disabled", and one + means "enabled". + + - .. row 4 + + - ``V4L2_CTRL_TYPE_MENU`` + + - ≥ 0 + + - 1 + + - N-1 + + - The control has a menu of N choices. The names of the menu items + can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. + + - .. row 5 + + - ``V4L2_CTRL_TYPE_INTEGER_MENU`` + + - ≥ 0 + + - 1 + + - N-1 + + - The control has a menu of N choices. The values of the menu items + can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is + similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings, + the menu items are signed 64-bit integers. + + - .. row 6 + + - ``V4L2_CTRL_TYPE_BITMASK`` + + - 0 + + - n/a + + - any + + - A bitmask field. The maximum value is the set of bits that can be + used, all other bits are to be 0. The maximum value is interpreted + as a __u32, allowing the use of bit 31 in the bitmask. + + - .. row 7 + + - ``V4L2_CTRL_TYPE_BUTTON`` + + - 0 + + - 0 + + - 0 + + - A control which performs an action when set. Drivers must ignore + the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error + code on a ``VIDIOC_G_CTRL`` attempt. + + - .. row 8 + + - ``V4L2_CTRL_TYPE_INTEGER64`` + + - any + + - any + + - any + + - A 64-bit integer valued control. Minimum, maximum and step size + cannot be queried using ``VIDIOC_QUERYCTRL``. Only + ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step + values, they should be interpreted as n/a when using + ``VIDIOC_QUERYCTRL``. + + - .. row 9 + + - ``V4L2_CTRL_TYPE_STRING`` + + - ≥ 0 + + - ≥ 1 + + - ≥ 0 + + - The minimum and maximum string lengths. The step size means that + the string must be (minimum + N * step) characters long for N ≥ 0. + These lengths do not include the terminating zero, so in order to + pass a string of length 8 to + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to + set the ``size`` field of struct + :ref:`v4l2_ext_control <v4l2-ext-control>` to 9. For + :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set + the ``size`` field to ``maximum`` + 1. Which character encoding is + used will depend on the string control itself and should be part + of the control documentation. + + - .. row 10 + + - ``V4L2_CTRL_TYPE_CTRL_CLASS`` + + - n/a + + - n/a + + - n/a + + - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a + control ID equal to a control class code (see :ref:`ctrl-class`) + + 1, the ioctl returns the name of the control class and this + control type. Older drivers which do not support this feature + return an ``EINVAL`` error code. + + - .. row 11 + + - ``V4L2_CTRL_TYPE_U8`` + + - any + + - any + + - any + + - An unsigned 8-bit valued control ranging from minimum to maximum + inclusive. The step value indicates the increment between values. + + - .. row 12 + + - ``V4L2_CTRL_TYPE_U16`` + + - any + + - any + + - any + + - An unsigned 16-bit valued control ranging from minimum to maximum + inclusive. The step value indicates the increment between values. + + - .. row 13 + + - ``V4L2_CTRL_TYPE_U32`` + + - any + + - any + + - any + + - An unsigned 32-bit valued control ranging from minimum to maximum + inclusive. The step value indicates the increment between values. + + + +.. _control-flags: + +.. flat-table:: Control Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_CTRL_FLAG_DISABLED`` + + - 0x0001 + + - This control is permanently disabled and should be ignored by the + application. Any attempt to change the control will result in an + ``EINVAL`` error code. + + - .. row 2 + + - ``V4L2_CTRL_FLAG_GRABBED`` + + - 0x0002 + + - This control is temporarily unchangeable, for example because + another application took over control of the respective resource. + Such controls may be displayed specially in a user interface. + Attempts to change the control may result in an ``EBUSY`` error code. + + - .. row 3 + + - ``V4L2_CTRL_FLAG_READ_ONLY`` + + - 0x0004 + + - This control is permanently readable only. Any attempt to change + the control will result in an ``EINVAL`` error code. + + - .. row 4 + + - ``V4L2_CTRL_FLAG_UPDATE`` + + - 0x0008 + + - A hint that changing this control may affect the value of other + controls within the same control class. Applications should update + their user interface accordingly. + + - .. row 5 + + - ``V4L2_CTRL_FLAG_INACTIVE`` + + - 0x0010 + + - This control is not applicable to the current configuration and + should be displayed accordingly in a user interface. For example + the flag may be set on a MPEG audio level 2 bitrate control when + MPEG audio encoding level 1 was selected with another control. + + - .. row 6 + + - ``V4L2_CTRL_FLAG_SLIDER`` + + - 0x0020 + + - A hint that this control is best represented as a slider-like + element in a user interface. + + - .. row 7 + + - ``V4L2_CTRL_FLAG_WRITE_ONLY`` + + - 0x0040 + + - This control is permanently writable only. Any attempt to read the + control will result in an ``EACCES`` error code error code. This flag + is typically present for relative controls or action controls + where writing a value will cause the device to carry out a given + action (e. g. motor control) but no meaningful value can be + returned. + + - .. row 8 + + - ``V4L2_CTRL_FLAG_VOLATILE`` + + - 0x0080 + + - This control is volatile, which means that the value of the + control changes continuously. A typical example would be the + current gain value if the device is in auto-gain mode. In such a + case the hardware calculates the gain value based on the lighting + conditions which can change over time. Note that setting a new + value for a volatile control will have no effect and no + ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless the + ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is also set. + Otherwise the new value will just be ignored. + + - .. row 9 + + - ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` + + - 0x0100 + + - This control has a pointer type, so its value has to be accessed + using one of the pointer fields of struct + :ref:`v4l2_ext_control <v4l2-ext-control>`. This flag is set + for controls that are an array, string, or have a compound type. + In all cases you have to set a pointer to memory containing the + payload of the control. + + - .. row 10 + + - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` + + - 0x0200 + + - The value provided to the control will be propagated to the driver + even if it remains constant. This is required when the control + represents an action on the hardware. For example: clearing an + error flag or triggering the flash. All the controls of the type + ``V4L2_CTRL_TYPE_BUTTON`` have this flag set. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is + invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id`` + is invalid or ``index`` is out of range (less than ``minimum`` or + greater than ``maximum``) or this particular menu item is not + supported by the driver. + +EACCES + An attempt was made to read a write-only control. + +.. [1] + ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers + can skip predefined controls not supported by the hardware (although + returning ``EINVAL`` would do as well), or disable predefined and private + controls after hardware detection without the trouble of reordering + control arrays and indices (``EINVAL`` cannot be used to skip private + controls because it would prematurely end the enumeration). diff --git a/Documentation/media/uapi/v4l/vidioc-querystd.rst b/Documentation/media/uapi/v4l/vidioc-querystd.rst new file mode 100644 index 000000000000..5bf62775c740 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-querystd.rst @@ -0,0 +1,66 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_QUERYSTD: + +********************* +ioctl VIDIOC_QUERYSTD +********************* + +Name +==== + +VIDIOC_QUERYSTD - Sense the video standard received by the current input + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, v4l2_std_id *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_QUERYSTD + +``argp`` + + +Description +=========== + +The hardware may be able to detect the current video standard +automatically. To do so, applications call :ref:`VIDIOC_QUERYSTD` with a +pointer to a :ref:`v4l2_std_id <v4l2-std-id>` type. The driver +stores here a set of candidates, this can be a single flag or a set of +supported standards if for example the hardware can only distinguish +between 50 and 60 Hz systems. If no signal was detected, then the driver +will return V4L2_STD_UNKNOWN. When detection is not possible or fails, +the set must contain all standards supported by the current video input +or output. + +Please note that drivers shall *not* switch the video standard +automatically if a new video standard is detected. Instead, drivers +should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support +this) and expect that userspace will take action by calling +:ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean +different buffer sizes as well, and you cannot change buffer sizes on +the fly. In general, applications that receive the Source Change event +will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video +standard is valid they will have to stop streaming, set the new +standard, allocate new buffers and start streaming again. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +ENODATA + Standard video timings are not supported for this input or output. diff --git a/Documentation/media/uapi/v4l/vidioc-reqbufs.rst b/Documentation/media/uapi/v4l/vidioc-reqbufs.rst new file mode 100644 index 000000000000..c25b0719c2ff --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-reqbufs.rst @@ -0,0 +1,125 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_REQBUFS: + +******************** +ioctl VIDIOC_REQBUFS +******************** + +Name +==== + +VIDIOC_REQBUFS - Initiate Memory Mapping or User Pointer I/O + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_requestbuffers *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_REQBUFS + +``argp`` + + +Description +=========== + +This ioctl is used to initiate :ref:`memory mapped <mmap>`, +:ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O. +Memory mapped buffers are located in device memory and must be allocated +with this ioctl before they can be mapped into the application's address +space. User buffers are allocated by applications themselves, and this +ioctl is merely used to switch the driver into user pointer I/O mode and +to setup some internal structures. Similarly, DMABUF buffers are +allocated by applications through a device driver, and this ioctl only +configures the driver into DMABUF I/O mode without performing any direct +allocation. + +To allocate device buffers applications initialize all fields of the +:ref:`struct v4l2_requestbuffers <v4l2-requestbuffers>` structure. They set the ``type`` +field to the respective stream or buffer type, the ``count`` field to +the desired number of buffers, ``memory`` must be set to the requested +I/O method and the ``reserved`` array must be zeroed. When the ioctl is +called with a pointer to this structure the driver will attempt to +allocate the requested number of buffers and it stores the actual number +allocated in the ``count`` field. It can be smaller than the number +requested, even zero, when the driver runs out of free memory. A larger +number is also possible when the driver requires more buffers to +function correctly. For example video output requires at least two +buffers, one displayed and one filled by the application. + +When the I/O method is not supported the ioctl returns an ``EINVAL`` error +code. + +Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of +buffers, however this cannot succeed when any buffers are still mapped. +A ``count`` value of zero frees all buffers, after aborting or finishing +any DMA in progress, an implicit +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`. + + +.. _v4l2-requestbuffers: + +.. flat-table:: struct v4l2_requestbuffers + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``count`` + + - The number of buffers requested or granted. + + - .. row 2 + + - __u32 + + - ``type`` + + - Type of the stream or buffers, this is the same as the struct + :ref:`v4l2_format <v4l2-format>` ``type`` field. See + :ref:`v4l2-buf-type` for valid values. + + - .. row 3 + + - __u32 + + - ``memory`` + + - Applications set this field to ``V4L2_MEMORY_MMAP``, + ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See + :ref:`v4l2-memory`. + + - .. row 4 + + - __u32 + + - ``reserved``\ [2] + + - A place holder for future extensions. Drivers and applications + must set the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The buffer type (``type`` field) or the requested I/O method + (``memory``) is not supported. diff --git a/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst new file mode 100644 index 000000000000..5fd332a5bfee --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst @@ -0,0 +1,179 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_S_HW_FREQ_SEEK: + +*************************** +ioctl VIDIOC_S_HW_FREQ_SEEK +*************************** + +Name +==== + +VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_hw_freq_seek *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_S_HW_FREQ_SEEK + +``argp`` + + +Description +=========== + +Start a hardware frequency seek from the current frequency. To do this +applications initialize the ``tuner``, ``type``, ``seek_upward``, +``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and +zero out the ``reserved`` array of a struct +:ref:`v4l2_hw_freq_seek <v4l2-hw-freq-seek>` and call the +``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure. + +The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value +to tell the driver to search a specific band. If the struct +:ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the +``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall +within one of the bands returned by +:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the +``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values +must exactly match those of one of the bands returned by +:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the +current frequency of the tuner does not fall within the selected band it +will be clamped to fit in the band before the seek is started. + +If an error is returned, then the original frequency will be restored. + +This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is +set. + +If this ioctl is called from a non-blocking filehandle, then ``EAGAIN`` +error code is returned and no seek takes place. + + +.. _v4l2-hw-freq-seek: + +.. flat-table:: struct v4l2_hw_freq_seek + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``tuner`` + + - The tuner index number. This is the same value as in the struct + :ref:`v4l2_input <v4l2-input>` ``tuner`` field and the struct + :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field. + + - .. row 2 + + - __u32 + + - ``type`` + + - The tuner type. This is the same value as in the struct + :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. See + :ref:`v4l2-tuner-type` + + - .. row 3 + + - __u32 + + - ``seek_upward`` + + - If non-zero, seek upward from the current frequency, else seek + downward. + + - .. row 4 + + - __u32 + + - ``wrap_around`` + + - If non-zero, wrap around when at the end of the frequency range, + else stop seeking. The struct :ref:`v4l2_tuner <v4l2-tuner>` + ``capability`` field will tell you what the hardware supports. + + - .. row 5 + + - __u32 + + - ``spacing`` + + - If non-zero, defines the hardware seek resolution in Hz. The + driver selects the nearest value that is supported by the device. + If spacing is zero a reasonable default value is used. + + - .. row 6 + + - __u32 + + - ``rangelow`` + + - If non-zero, the lowest tunable frequency of the band to search in + units of 62.5 kHz, or if the struct + :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the + ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the + struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has + the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If + ``rangelow`` is zero a reasonable default value is used. + + - .. row 7 + + - __u32 + + - ``rangehigh`` + + - If non-zero, the highest tunable frequency of the band to search + in units of 62.5 kHz, or if the struct + :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the + ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the + struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has + the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If + ``rangehigh`` is zero a reasonable default value is used. + + - .. row 8 + + - __u32 + + - ``reserved``\ [5] + + - Reserved for future extensions. Applications must set the array to + zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The ``tuner`` index is out of bounds, the ``wrap_around`` value is + not supported or one of the values in the ``type``, ``rangelow`` or + ``rangehigh`` fields is wrong. + +EAGAIN + Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in + non-blocking mode. + +ENODATA + The hardware seek found no channels. + +EBUSY + Another hardware seek is already in progress. diff --git a/Documentation/media/uapi/v4l/vidioc-streamon.rst b/Documentation/media/uapi/v4l/vidioc-streamon.rst new file mode 100644 index 000000000000..e87500e608e1 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-streamon.rst @@ -0,0 +1,103 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_STREAMON: + +*************************************** +ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF +*************************************** + +Name +==== + +VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, const int *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_STREAMON, VIDIOC_STREAMOFF + +``argp`` + + +Description +=========== + +The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop +the capture or output process during streaming +(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or +:ref:`DMABUF <dmabuf>`) I/O. + +Capture hardware is disabled and no input buffers are filled (if there +are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON`` +has been called. Output hardware is disabled and no video signal is +produced until ``VIDIOC_STREAMON`` has been called. The ioctl will +succeed when at least one output buffer is in the incoming queue. + +Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has +been called for both the capture and output stream types. + +If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain +queued. + +The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA +in progress, unlocks any user pointer buffers locked in physical memory, +and it removes all buffers from the incoming and outgoing queues. That +means all images captured but not dequeued yet will be lost, likewise +all images enqueued for output but not transmitted yet. I/O returns to +the same state as after calling +:ref:`VIDIOC_REQBUFS` and can be restarted +accordingly. + +If buffers have been queued with :ref:`VIDIOC_QBUF` and +``VIDIOC_STREAMOFF`` is called without ever having called +``VIDIOC_STREAMON``, then those queued buffers will also be removed from +the incoming queue and all are returned to the same state as after +calling :ref:`VIDIOC_REQBUFS` and can be restarted +accordingly. + +Both ioctls take a pointer to an integer, the desired buffer or stream +type. This is the same as struct +:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``. + +If ``VIDIOC_STREAMON`` is called when streaming is already in progress, +or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped, +then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``, +but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting +state as mentioned above. + +Note that applications can be preempted for unknown periods right before +or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is +no notion of starting or stopping "now". Buffer timestamps can be used +to synchronize with other events. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The buffer ``type`` is not supported, or no buffers have been + allocated (memory mapping) or enqueued (output) yet. + +EPIPE + The driver implements + :ref:`pad-level format configuration <pad-level-formats>` and the + pipeline configuration is invalid. + +ENOLINK + The driver implements Media Controller interface and the pipeline + link configuration is invalid. diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst new file mode 100644 index 000000000000..0aa6482a91a6 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst @@ -0,0 +1,153 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL: + +*************************************** +ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL +*************************************** + +Name +==== + +VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval_enum * argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL + +``argp`` + + +Description +=========== + +This ioctl lets applications enumerate available frame intervals on a +given sub-device pad. Frame intervals only makes sense for sub-devices +that can control the frame period on their own. This includes, for +instance, image sensors and TV tuners. + +For the common use case of image sensors, the frame intervals available +on the sub-device output pad depend on the frame format and size on the +same pad. Applications must thus specify the desired format and size +when enumerating frame intervals. + +To enumerate frame intervals applications initialize the ``index``, +``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct +:ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>` +and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer +to this structure. Drivers fill the rest of the structure or return an +EINVAL error code if one of the input fields is invalid. All frame +intervals are enumerable by beginning at index zero and incrementing by +one until ``EINVAL`` is returned. + +Available frame intervals may depend on the current 'try' formats at +other pads of the sub-device, as well as on the current active links. +See :ref:`VIDIOC_SUBDEV_G_FMT` for more +information about the try formats. + +Sub-devices that support the frame interval enumeration ioctl should +implemented it on a single pad only. Its behaviour when supported on +multiple pads of the same sub-device is not defined. + + +.. _v4l2-subdev-frame-interval-enum: + +.. flat-table:: struct v4l2_subdev_frame_interval_enum + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Number of the format in the enumeration, set by the application. + + - .. row 2 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media controller API. + + - .. row 3 + + - __u32 + + - ``code`` + + - The media bus format code, as defined in + :ref:`v4l2-mbus-format`. + + - .. row 4 + + - __u32 + + - ``width`` + + - Frame width, in pixels. + + - .. row 5 + + - __u32 + + - ``height`` + + - Frame height, in pixels. + + - .. row 6 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``interval`` + + - Period, in seconds, between consecutive video frames. + + - .. row 7 + + - __u32 + + - ``which`` + + - Frame intervals to be enumerated, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + + - .. row 8 + + - __u32 + + - ``reserved``\ [8] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct + :ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>` + ``pad`` references a non-existing pad, one of the ``code``, + ``width`` or ``height`` fields are invalid for the given pad or the + ``index`` field is out of bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst new file mode 100644 index 000000000000..7a5811b71b68 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst @@ -0,0 +1,162 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE: + +*********************************** +ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE +*********************************** + +Name +==== + +VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_size_enum * argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBDEV_ENUM_FRAME_SIZE + +``argp`` + + +Description +=========== + +This ioctl allows applications to enumerate all frame sizes supported by +a sub-device on the given pad for the given media bus format. Supported +formats can be retrieved with the +:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` +ioctl. + +To enumerate frame sizes applications initialize the ``pad``, ``which`` +, ``code`` and ``index`` fields of the struct +:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and +call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the +structure. Drivers fill the minimum and maximum frame sizes or return an +EINVAL error code if one of the input parameters is invalid. + +Sub-devices that only support discrete frame sizes (such as most +sensors) will return one or more frame sizes with identical minimum and +maximum values. + +Not all possible sizes in given [minimum, maximum] ranges need to be +supported. For instance, a scaler that uses a fixed-point scaling ratio +might not be able to produce every frame size between the minimum and +maximum values. Applications must use the +:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the +sub-device for an exact supported frame size. + +Available frame sizes may depend on the current 'try' formats at other +pads of the sub-device, as well as on the current active links and the +current values of V4L2 controls. See +:ref:`VIDIOC_SUBDEV_G_FMT` for more +information about try formats. + + +.. _v4l2-subdev-frame-size-enum: + +.. flat-table:: struct v4l2_subdev_frame_size_enum + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``index`` + + - Number of the format in the enumeration, set by the application. + + - .. row 2 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media controller API. + + - .. row 3 + + - __u32 + + - ``code`` + + - The media bus format code, as defined in + :ref:`v4l2-mbus-format`. + + - .. row 4 + + - __u32 + + - ``min_width`` + + - Minimum frame width, in pixels. + + - .. row 5 + + - __u32 + + - ``max_width`` + + - Maximum frame width, in pixels. + + - .. row 6 + + - __u32 + + - ``min_height`` + + - Minimum frame height, in pixels. + + - .. row 7 + + - __u32 + + - ``max_height`` + + - Maximum frame height, in pixels. + + - .. row 8 + + - __u32 + + - ``which`` + + - Frame sizes to be enumerated, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + + - .. row 9 + + - __u32 + + - ``reserved``\ [8] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct + :ref:`v4l2_subdev_frame_size_enum <v4l2-subdev-frame-size-enum>` + ``pad`` references a non-existing pad, the ``code`` is invalid for + the given pad or the ``index`` field is out of bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst new file mode 100644 index 000000000000..bc0531eb56fa --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst @@ -0,0 +1,115 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBDEV_ENUM_MBUS_CODE: + +********************************** +ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE +********************************** + +Name +==== + +VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_mbus_code_enum * argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBDEV_ENUM_MBUS_CODE + +``argp`` + + +Description +=========== + +To enumerate media bus formats available at a given sub-device pad +applications initialize the ``pad``, ``which`` and ``index`` fields of +struct +:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and +call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this +structure. Drivers fill the rest of the structure or return an ``EINVAL`` +error code if either the ``pad`` or ``index`` are invalid. All media bus +formats are enumerable by beginning at index zero and incrementing by +one until ``EINVAL`` is returned. + +Available media bus formats may depend on the current 'try' formats at +other pads of the sub-device, as well as on the current active links. +See :ref:`VIDIOC_SUBDEV_G_FMT` for more +information about the try formats. + + +.. _v4l2-subdev-mbus-code-enum: + +.. flat-table:: struct v4l2_subdev_mbus_code_enum + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media controller API. + + - .. row 2 + + - __u32 + + - ``index`` + + - Number of the format in the enumeration, set by the application. + + - .. row 3 + + - __u32 + + - ``code`` + + - The media bus format code, as defined in + :ref:`v4l2-mbus-format`. + + - .. row 4 + + - __u32 + + - ``which`` + + - Media bus format codes to be enumerated, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + + - .. row 5 + + - __u32 + + - ``reserved``\ [8] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The struct + :ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` + ``pad`` references a non-existing pad, or the ``index`` field is out + of bounds. diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst new file mode 100644 index 000000000000..690034a391d3 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst @@ -0,0 +1,136 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBDEV_G_CROP: + +************************************************ +ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP +************************************************ + +Name +==== + +VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_crop *argp ) + +.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_subdev_crop *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP + +``argp`` + + +Description +=========== + + **Note** + + This is an :ref:`obsolete` interface and may be removed + in the future. It is superseded by + :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`. + +To retrieve the current crop rectangle applications set the ``pad`` +field of a struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` to the +desired pad number as reported by the media API and the ``which`` field +to ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the +``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The +driver fills the members of the ``rect`` field or returns ``EINVAL`` error +code if the input arguments are invalid, or if cropping is not supported +on the given pad. + +To change the current crop rectangle applications set both the ``pad`` +and ``which`` fields and all members of the ``rect`` field. They then +call the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this +structure. The driver verifies the requested crop rectangle, adjusts it +based on the hardware capabilities and configures the device. Upon +return the struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` +contains the current format as would be returned by a +``VIDIOC_SUBDEV_G_CROP`` call. + +Applications can query the device capabilities by setting the ``which`` +to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not +applied to the device by the driver, but are mangled exactly as active +crop rectangles and stored in the sub-device file handle. Two +applications querying the same sub-device would thus not interact with +each other. + +Drivers must not return an error solely because the requested crop +rectangle doesn't match the device capabilities. They must instead +modify the rectangle to match what the hardware can provide. The +modified format should be as close as possible to the original request. + + +.. _v4l2-subdev-crop: + +.. flat-table:: struct v4l2_subdev_crop + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media framework. + + - .. row 2 + + - __u32 + + - ``which`` + + - Crop rectangle to get or set, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + + - .. row 3 + + - struct :ref:`v4l2_rect <v4l2-rect>` + + - ``rect`` + + - Crop rectangle boundaries, in pixels. + + - .. row 4 + + - __u32 + + - ``reserved``\ [8] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EBUSY + The crop rectangle can't be changed because the pad is currently + busy. This can be caused, for instance, by an active video stream on + the pad. The ioctl must not be retried without performing another + action to fix the problem first. Only returned by + ``VIDIOC_SUBDEV_S_CROP`` + +EINVAL + The struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` ``pad`` + references a non-existing pad, the ``which`` field references a + non-existing format, or cropping is not supported on the given + subdev pad. diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst new file mode 100644 index 000000000000..90e2a6635ebc --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst @@ -0,0 +1,171 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBDEV_G_FMT: + +********************************************** +ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT +********************************************** + +Name +==== + +VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_format *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT + +``argp`` + + +Description +=========== + +These ioctls are used to negotiate the frame format at specific subdev +pads in the image pipeline. + +To retrieve the current format applications set the ``pad`` field of a +struct :ref:`v4l2_subdev_format <v4l2-subdev-format>` to the desired +pad number as reported by the media API and the ``which`` field to +``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the +``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the +driver fills the members of the ``format`` field. + +To change the current format applications set both the ``pad`` and +``which`` fields and all members of the ``format`` field. When they call +the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the +driver verifies the requested format, adjusts it based on the hardware +capabilities and configures the device. Upon return the struct +:ref:`v4l2_subdev_format <v4l2-subdev-format>` contains the current +format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call. + +Applications can query the device capabilities by setting the ``which`` +to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied +to the device by the driver, but are changed exactly as active formats +and stored in the sub-device file handle. Two applications querying the +same sub-device would thus not interact with each other. + +For instance, to try a format at the output pad of a sub-device, +applications would first set the try format at the sub-device input with +the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the +default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl, +or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT`` +ioctl and check the returned value. + +Try formats do not depend on active formats, but can depend on the +current links configuration or sub-device controls value. For instance, +a low-pass noise filter might crop pixels at the frame boundaries, +modifying its output frame size. + +Drivers must not return an error solely because the requested format +doesn't match the device capabilities. They must instead modify the +format to match what the hardware can provide. The modified format +should be as close as possible to the original request. + + +.. _v4l2-subdev-format: + +.. flat-table:: struct v4l2_subdev_format + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media controller API. + + - .. row 2 + + - __u32 + + - ``which`` + + - Format to modified, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + + - .. row 3 + + - struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>` + + - ``format`` + + - Definition of an image format, see :ref:`v4l2-mbus-framefmt` for + details. + + - .. row 4 + + - __u32 + + - ``reserved``\ [8] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + + +.. _v4l2-subdev-format-whence: + +.. flat-table:: enum v4l2_subdev_format_whence + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - V4L2_SUBDEV_FORMAT_TRY + + - 0 + + - Try formats, used for querying device capabilities. + + - .. row 2 + + - V4L2_SUBDEV_FORMAT_ACTIVE + + - 1 + + - Active formats, applied to the hardware. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EBUSY + The format can't be changed because the pad is currently busy. This + can be caused, for instance, by an active video stream on the pad. + The ioctl must not be retried without performing another action to + fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT`` + +EINVAL + The struct :ref:`v4l2_subdev_format <v4l2-subdev-format>` + ``pad`` references a non-existing pad, or the ``which`` field + references a non-existing format. + + +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst new file mode 100644 index 000000000000..d8a1cabbd272 --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst @@ -0,0 +1,122 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBDEV_G_FRAME_INTERVAL: + +******************************************************************** +ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL +******************************************************************** + +Name +==== + +VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBDEV_G_FRAME_INTERVAL, + VIDIOC_SUBDEV_S_FRAME_INTERVAL + +``argp`` + + +Description +=========== + +These ioctls are used to get and set the frame interval at specific +subdev pads in the image pipeline. The frame interval only makes sense +for sub-devices that can control the frame period on their own. This +includes, for instance, image sensors and TV tuners. Sub-devices that +don't support frame intervals must not implement these ioctls. + +To retrieve the current frame interval applications set the ``pad`` +field of a struct +:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` to +the desired pad number as reported by the media controller API. When +they call the ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` ioctl with a pointer to +this structure the driver fills the members of the ``interval`` field. + +To change the current frame interval applications set both the ``pad`` +field and all members of the ``interval`` field. When they call the +``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl with a pointer to this +structure the driver verifies the requested interval, adjusts it based +on the hardware capabilities and configures the device. Upon return the +struct +:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` +contains the current frame interval as would be returned by a +``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call. + +Drivers must not return an error solely because the requested interval +doesn't match the device capabilities. They must instead modify the +interval to match what the hardware can provide. The modified interval +should be as close as possible to the original request. + +Sub-devices that support the frame interval ioctls should implement them +on a single pad only. Their behaviour when supported on multiple pads of +the same sub-device is not defined. + + +.. _v4l2-subdev-frame-interval: + +.. flat-table:: struct v4l2_subdev_frame_interval + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media controller API. + + - .. row 2 + + - struct :ref:`v4l2_fract <v4l2-fract>` + + - ``interval`` + + - Period, in seconds, between consecutive video frames. + + - .. row 3 + + - __u32 + + - ``reserved``\ [9] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EBUSY + The frame interval can't be changed because the pad is currently + busy. This can be caused, for instance, by an active video stream on + the pad. The ioctl must not be retried without performing another + action to fix the problem first. Only returned by + ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` + +EINVAL + The struct + :ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` + ``pad`` references a non-existing pad, or the pad doesn't support + frame intervals. diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst new file mode 100644 index 000000000000..50838a4a429e --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst @@ -0,0 +1,144 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBDEV_G_SELECTION: + +********************************************************** +ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION +********************************************************** + +Name +==== + +VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_selection *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION + +``argp`` + + +Description +=========== + +The selections are used to configure various image processing +functionality performed by the subdevs which affect the image size. This +currently includes cropping, scaling and composition. + +The selection API replaces +:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the +function of the crop API, and more, are supported by the selections API. + +See :ref:`subdev` for more information on how each selection target +affects the image processing pipeline inside the subdevice. + + +Types of selection targets +-------------------------- + +There are two types of selection targets: actual and bounds. The actual +targets are the targets which configure the hardware. The BOUNDS target +will return a rectangle that contain all possible actual rectangles. + + +Discovering supported features +------------------------------ + +To discover which targets are supported, the user can perform +``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will +return ``EINVAL``. + +Selection targets and flags are documented in +:ref:`v4l2-selections-common`. + + +.. _v4l2-subdev-selection: + +.. flat-table:: struct v4l2_subdev_selection + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``which`` + + - Active or try selection, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + + - .. row 2 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media framework. + + - .. row 3 + + - __u32 + + - ``target`` + + - Target selection rectangle. See :ref:`v4l2-selections-common`. + + - .. row 4 + + - __u32 + + - ``flags`` + + - Flags. See :ref:`v4l2-selection-flags`. + + - .. row 5 + + - struct :ref:`v4l2_rect <v4l2-rect>` + + - ``r`` + + - Selection rectangle, in pixels. + + - .. row 6 + + - __u32 + + - ``reserved``\ [8] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EBUSY + The selection rectangle can't be changed because the pad is + currently busy. This can be caused, for instance, by an active video + stream on the pad. The ioctl must not be retried without performing + another action to fix the problem first. Only returned by + ``VIDIOC_SUBDEV_S_SELECTION`` + +EINVAL + The struct :ref:`v4l2_subdev_selection <v4l2-subdev-selection>` + ``pad`` references a non-existing pad, the ``which`` field + references a non-existing format, or the selection target is not + supported on the given subdev pad. diff --git a/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst new file mode 100644 index 000000000000..a027f602de3d --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst @@ -0,0 +1,135 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBSCRIBE_EVENT: + +****************************************************** +ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT +****************************************************** + +Name +==== + +VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event_subscription *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT + +``argp`` + + +Description +=========== + +Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by +using the :ref:`VIDIOC_DQEVENT` ioctl. + + +.. _v4l2-event-subscription: + +.. flat-table:: struct v4l2_event_subscription + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - Type of the event, see :ref:`event-type`. Note that + ``V4L2_EVENT_ALL`` can be used with VIDIOC_UNSUBSCRIBE_EVENT for + unsubscribing all events at once. + + - .. row 2 + + - __u32 + + - ``id`` + + - ID of the event source. If there is no ID associated with the + event source, then set this to 0. Whether or not an event needs an + ID depends on the event type. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Event flags, see :ref:`event-flags`. + + - .. row 4 + + - __u32 + + - ``reserved``\ [5] + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. _event-flags: + +.. flat-table:: Event Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_EVENT_SUB_FL_SEND_INITIAL`` + + - 0x0001 + + - When this event is subscribed an initial event will be sent + containing the current status. This only makes sense for events + that are triggered by a status change such as ``V4L2_EVENT_CTRL``. + Other events will ignore this flag. + + - .. row 2 + + - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK`` + + - 0x0002 + + - If set, then events directly caused by an ioctl will also be sent + to the filehandle that called that ioctl. For example, changing a + control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause + a V4L2_EVENT_CTRL to be sent back to that same filehandle. + Normally such events are suppressed to prevent feedback loops + where an application changes a control to a one value and then + another, and then receives an event telling it that that control + has changed to the first value. + + Since it can't tell whether that event was caused by another + application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` + call it is hard to decide whether to set the control to the value + in the event, or ignore it. + + Think carefully when you set this flag so you won't get into + situations like that. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/v4l/yuv-formats.rst b/Documentation/media/uapi/v4l/yuv-formats.rst new file mode 100644 index 000000000000..3334ea445657 --- /dev/null +++ b/Documentation/media/uapi/v4l/yuv-formats.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _yuv-formats: + +*********** +YUV Formats +*********** + +YUV is the format native to TV broadcast and composite video signals. It +separates the brightness information (Y) from the color information (U +and V or Cb and Cr). The color information consists of red and blue +*color difference* signals, this way the green component can be +reconstructed by subtracting from the brightness component. See +:ref:`colorspaces` for conversion examples. YUV was chosen because +early television would only transmit brightness information. To add +color in a way compatible with existing receivers a new signal carrier +was added to transmit the color difference signals. Secondary in the YUV +format the U and V components usually have lower resolution than the Y +component. This is an analog video compression technique taking +advantage of a property of the human visual system, being more sensitive +to brightness information. + + +.. toctree:: + :maxdepth: 1 + + pixfmt-packed-yuv + pixfmt-grey + pixfmt-y10 + pixfmt-y12 + pixfmt-y10b + pixfmt-y16 + pixfmt-y16-be + pixfmt-y8i + pixfmt-y12i + pixfmt-uv8 + pixfmt-yuyv + pixfmt-uyvy + pixfmt-yvyu + pixfmt-vyuy + pixfmt-y41p + pixfmt-yuv420 + pixfmt-yuv420m + pixfmt-yuv422m + pixfmt-yuv444m + pixfmt-yuv410 + pixfmt-yuv422p + pixfmt-yuv411p + pixfmt-nv12 + pixfmt-nv12m + pixfmt-nv12mt + pixfmt-nv16 + pixfmt-nv16m + pixfmt-nv24 + pixfmt-m420 |
