1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _output: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab********************** 754f38fcaSMauro Carvalho ChehabVideo Output Interface 854f38fcaSMauro Carvalho Chehab********************** 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabVideo output devices encode stills or image sequences as analog video 1154f38fcaSMauro Carvalho Chehabsignal. With this interface applications can control the encoding 1254f38fcaSMauro Carvalho Chehabprocess and move images from user space to the driver. 1354f38fcaSMauro Carvalho Chehab 1454f38fcaSMauro Carvalho ChehabConventionally V4L2 video output devices are accessed through character 1554f38fcaSMauro Carvalho Chehabdevice special files named ``/dev/video`` and ``/dev/video0`` to 1654f38fcaSMauro Carvalho Chehab``/dev/video63`` with major number 81 and minor numbers 0 to 63. 1754f38fcaSMauro Carvalho Chehab``/dev/video`` is typically a symbolic link to the preferred video 1854f38fcaSMauro Carvalho Chehabdevice. 1954f38fcaSMauro Carvalho Chehab 2054f38fcaSMauro Carvalho Chehab.. note:: The same device file names are used also for video capture devices. 2154f38fcaSMauro Carvalho Chehab 2254f38fcaSMauro Carvalho ChehabQuerying Capabilities 2354f38fcaSMauro Carvalho Chehab===================== 2454f38fcaSMauro Carvalho Chehab 2554f38fcaSMauro Carvalho ChehabDevices supporting the video output interface set the 2654f38fcaSMauro Carvalho Chehab``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in 2754f38fcaSMauro Carvalho Chehabthe ``capabilities`` field of struct 2854f38fcaSMauro Carvalho Chehab:c:type:`v4l2_capability` returned by the 2954f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device 3054f38fcaSMauro Carvalho Chehabfunctions they may also support the :ref:`raw VBI output <raw-vbi>` 3154f38fcaSMauro Carvalho Chehab(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or 3254f38fcaSMauro Carvalho Chehabstreaming I/O methods must be supported. Modulators and audio outputs 3354f38fcaSMauro Carvalho Chehabare optional. 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho ChehabSupplemental Functions 3654f38fcaSMauro Carvalho Chehab====================== 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho ChehabVideo output devices shall support :ref:`audio output <audio>`, 3954f38fcaSMauro Carvalho Chehab:ref:`modulator <tuner>`, :ref:`controls <control>`, 4054f38fcaSMauro Carvalho Chehab:ref:`cropping and scaling <crop>` and 4154f38fcaSMauro Carvalho Chehab:ref:`streaming parameter <streaming-par>` ioctls as needed. The 4254f38fcaSMauro Carvalho Chehab:ref:`video output <video>` ioctls must be supported by all video 4354f38fcaSMauro Carvalho Chehaboutput devices. 4454f38fcaSMauro Carvalho Chehab 4554f38fcaSMauro Carvalho ChehabImage Format Negotiation 4654f38fcaSMauro Carvalho Chehab======================== 4754f38fcaSMauro Carvalho Chehab 4854f38fcaSMauro Carvalho ChehabThe output is determined by cropping and image format parameters. The 4954f38fcaSMauro Carvalho Chehabformer select an area of the video picture where the image will appear, 5054f38fcaSMauro Carvalho Chehabthe latter how images are stored in memory, i. e. in RGB or YUV format, 5154f38fcaSMauro Carvalho Chehabthe number of bits per pixel or width and height. Together they also 5254f38fcaSMauro Carvalho Chehabdefine how images are scaled in the process. 5354f38fcaSMauro Carvalho Chehab 54407e84cdSMauro Carvalho ChehabAs usual these parameters are *not* reset at :c:func:`open()` 5554f38fcaSMauro Carvalho Chehabtime to permit Unix tool chains, programming a device and then writing 5654f38fcaSMauro Carvalho Chehabto it as if it was a plain file. Well written V4L2 applications ensure 5754f38fcaSMauro Carvalho Chehabthey really get what they want, including cropping and scaling. 5854f38fcaSMauro Carvalho Chehab 5954f38fcaSMauro Carvalho ChehabCropping initialization at minimum requires to reset the parameters to 6054f38fcaSMauro Carvalho Chehabdefaults. An example is given in :ref:`crop`. 6154f38fcaSMauro Carvalho Chehab 6254f38fcaSMauro Carvalho ChehabTo query the current image format applications set the ``type`` field of 6354f38fcaSMauro Carvalho Chehaba struct :c:type:`v4l2_format` to 6454f38fcaSMauro Carvalho Chehab``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` 6554f38fcaSMauro Carvalho Chehaband call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer 6654f38fcaSMauro Carvalho Chehabto this structure. Drivers fill the struct 6754f38fcaSMauro Carvalho Chehab:c:type:`v4l2_pix_format` ``pix`` or the struct 6854f38fcaSMauro Carvalho Chehab:c:type:`v4l2_pix_format_mplane` ``pix_mp`` 6954f38fcaSMauro Carvalho Chehabmember of the ``fmt`` union. 7054f38fcaSMauro Carvalho Chehab 7154f38fcaSMauro Carvalho ChehabTo request different parameters applications set the ``type`` field of a 7254f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_format` as above and initialize all 7354f38fcaSMauro Carvalho Chehabfields of the struct :c:type:`v4l2_pix_format` 7454f38fcaSMauro Carvalho Chehab``vbi`` member of the ``fmt`` union, or better just modify the results 7554f38fcaSMauro Carvalho Chehabof :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` 7654f38fcaSMauro Carvalho Chehabioctl with a pointer to this structure. Drivers may adjust the 7754f38fcaSMauro Carvalho Chehabparameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` 7854f38fcaSMauro Carvalho Chehabdoes. 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho ChehabLike :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl 8154f38fcaSMauro Carvalho Chehabcan be used to learn about hardware limitations without disabling I/O or 8254f38fcaSMauro Carvalho Chehabpossibly time consuming hardware preparations. 8354f38fcaSMauro Carvalho Chehab 8454f38fcaSMauro Carvalho ChehabThe contents of struct :c:type:`v4l2_pix_format` and 8554f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_pix_format_mplane` are 8654f38fcaSMauro Carvalho Chehabdiscussed in :ref:`pixfmt`. See also the specification of the 8754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for 8854f38fcaSMauro Carvalho Chehabdetails. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` 8954f38fcaSMauro Carvalho Chehaband :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all 9054f38fcaSMauro Carvalho Chehabrequests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. 9154f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. 9254f38fcaSMauro Carvalho Chehab 9354f38fcaSMauro Carvalho ChehabWriting Images 9454f38fcaSMauro Carvalho Chehab============== 9554f38fcaSMauro Carvalho Chehab 9654f38fcaSMauro Carvalho ChehabA video output device may support the :ref:`write() function <rw>` 9754f38fcaSMauro Carvalho Chehaband/or streaming (:ref:`memory mapping <mmap>` or 9854f38fcaSMauro Carvalho Chehab:ref:`user pointer <userp>`) I/O. See :ref:`io` for details. 99