Documentation/media/uapi/v4l/vidioc-g-audioout.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_G_AUDOUT:
  11
  12 **************************************
  13 ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
  14 **************************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp )
  26     :name: VIDIOC_G_AUDOUT
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp )
  29     :name: VIDIOC_S_AUDOUT
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to struct :c:type:`v4l2_audioout`.
  40
  41
  42 Description
  43 ===========
  44
  45 To query the current audio output applications zero out the ``reserved``
  46 array of a struct :c:type:`v4l2_audioout` and call the
  47 ``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
  48 the rest of the structure or return an ``EINVAL`` error code when the device
  49 has no audio inputs, or none which combine with the current video
  50 output.
  51
  52 Audio outputs have no writable properties. Nevertheless, to select the
  53 current audio output applications can initialize the ``index`` field and
  54 ``reserved`` array (which in the future may contain writable properties)
  55 of a struct :c:type:`v4l2_audioout` structure and call the
  56 ``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
  57 return the ``EINVAL`` error code when the index is out of bounds. This is a
  58 write-only ioctl, it does not return the current audio output attributes
  59 as ``VIDIOC_G_AUDOUT`` does.
  60
  61 .. note::
  62
  63    Connectors on a TV card to loop back the received audio signal
  64    to a sound card are not audio outputs in this sense.
  65
  66
  67 .. c:type:: v4l2_audioout
  68
  69 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  70
  71 .. flat-table:: struct v4l2_audioout
  72     :header-rows:  0
  73     :stub-columns: 0
  74     :widths:       1 1 2
  75
  76     * - __u32
  77       - ``index``
  78       - Identifies the audio output, set by the driver or application.
  79     * - __u8
  80       - ``name``\ [32]
  81       - Name of the audio output, a NUL-terminated ASCII string, for
  82         example: "Line Out". This information is intended for the user,
  83         preferably the connector label on the device itself.
  84     * - __u32
  85       - ``capability``
  86       - Audio capability flags, none defined yet. Drivers must set this
  87         field to zero.
  88     * - __u32
  89       - ``mode``
  90       - Audio mode, none defined yet. Drivers and applications (on
  91         ``VIDIOC_S_AUDOUT``) must set this field to zero.
  92     * - __u32
  93       - ``reserved``\ [2]
  94       - Reserved for future extensions. Drivers and applications must set
  95         the array to zero.
  96
  97
  98 Return Value
  99 ============
 100
 101 On success 0 is returned, on error -1 and the ``errno`` variable is set
 102 appropriately. The generic error codes are described at the
 103 :ref:`Generic Error Codes <gen-errors>` chapter.
 104
 105 EINVAL
 106     No audio outputs combine with the current video output, or the
 107     number of the selected audio output is out of bounds or it does not
 108     combine.