linux/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml

139 lines
4.3 KiB
XML

<refentry id="vidioc-g-audioout">
<refmeta>
<refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_G_AUDOUT</refname>
<refname>VIDIOC_S_AUDOUT</refname>
<refpurpose>Query or select the current audio output</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>const struct v4l2_audioout *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>To query the current audio output applications zero out the
<structfield>reserved</structfield> array of a &v4l2-audioout; and
call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
&EINVAL; when the device has no audio inputs, or none which combine
with the current video output.</para>
<para>Audio outputs have no writable properties. Nevertheless, to
select the current audio output applications can initialize the
<structfield>index</structfield> field and
<structfield>reserved</structfield> array (which in the future may
contain writable properties) of a
<structname>v4l2_audioout</structname> structure and call the
<constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the
requested output or return the &EINVAL; when the index is out of
bounds. This is a write-only ioctl, it does not return the current
audio output attributes as <constant>VIDIOC_G_AUDOUT</constant>
does.</para>
<para>Note connectors on a TV card to loop back the received audio
signal to a sound card are not audio outputs in this sense.</para>
<table pgwide="1" frame="none" id="v4l2-audioout">
<title>struct <structname>v4l2_audioout</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Identifies the audio output, set by the
driver or application.</entry>
</row>
<row>
<entry>__u8</entry>
<entry><structfield>name</structfield>[32]</entry>
<entry>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.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>capability</structfield></entry>
<entry>Audio capability flags, none defined yet. Drivers
must set this field to zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>mode</structfield></entry>
<entry>Audio mode, none defined yet. Drivers and
applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this
field to zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
<entry>Reserved for future extensions. Drivers and
applications must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>