diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l/vidioc-g-audio.rst')
| -rw-r--r-- | Documentation/userspace-api/media/v4l/vidioc-g-audio.rst | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst new file mode 100644 index 000000000000..68531bcb62ab --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst @@ -0,0 +1,135 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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 +======== + +.. c:function:: int ioctl( int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp ) + :name: VIDIOC_G_AUDIO + +.. c:function:: int ioctl( int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp ) + :name: VIDIOC_S_AUDIO + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``argp`` + Pointer to struct :c:type:`v4l2_audio`. + + +Description +=========== + +To query the current audio input applications zero out the ``reserved`` +array of a struct :c:type:`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 +struct :c:type:`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. + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_audio + +.. flat-table:: struct v4l2_audio + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``index`` + - Identifies the audio input, set by the driver or application. + * - __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. + * - __u32 + - ``capability`` + - Audio capability flags, see :ref:`audio-capability`. + * - __u32 + - ``mode`` + - Audio mode flags set by drivers and applications (on + :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`. + * - __u32 + - ``reserved``\ [2] + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. _audio-capability: + +.. flat-table:: Audio Capability Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``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. + * - ``V4L2_AUDCAP_AVL`` + - 0x00002 + - Automatic Volume Level mode is supported. + + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. _audio-mode: + +.. flat-table:: Audio Mode Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``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. |