blob: 3632730c5c6e86ab3aba5ce41a2df9b71a73e29c [file] [log] [blame]
Mauro Carvalho Chehab8e080c22009-09-13 22:16:04 -03001<refentry id="vidioc-g-audioout">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_AUDOUT</refname>
9 <refname>VIDIOC_S_AUDOUT</refname>
10 <refpurpose>Query or select the current audio output</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 <funcsynopsis>
23 <funcprototype>
24 <funcdef>int <function>ioctl</function></funcdef>
25 <paramdef>int <parameter>fd</parameter></paramdef>
26 <paramdef>int <parameter>request</parameter></paramdef>
27 <paramdef>const struct v4l2_audioout *<parameter>argp</parameter></paramdef>
28 </funcprototype>
29 </funcsynopsis>
30 </refsynopsisdiv>
31
32 <refsect1>
33 <title>Arguments</title>
34
35 <variablelist>
36 <varlistentry>
37 <term><parameter>fd</parameter></term>
38 <listitem>
39 <para>&fd;</para>
40 </listitem>
41 </varlistentry>
42 <varlistentry>
43 <term><parameter>request</parameter></term>
44 <listitem>
45 <para>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</para>
46 </listitem>
47 </varlistentry>
48 <varlistentry>
49 <term><parameter>argp</parameter></term>
50 <listitem>
51 <para></para>
52 </listitem>
53 </varlistentry>
54 </variablelist>
55 </refsect1>
56
57 <refsect1>
58 <title>Description</title>
59
60 <para>To query the current audio output applications zero out the
61<structfield>reserved</structfield> array of a &v4l2-audioout; and
62call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
63to this structure. Drivers fill the rest of the structure or return an
64&EINVAL; when the device has no audio inputs, or none which combine
65with the current video output.</para>
66
67 <para>Audio outputs have no writable properties. Nevertheless, to
68select the current audio output applications can initialize the
69<structfield>index</structfield> field and
70<structfield>reserved</structfield> array (which in the future may
71contain writable properties) of a
72<structname>v4l2_audioout</structname> structure and call the
73<constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the
74requested output or return the &EINVAL; when the index is out of
75bounds. This is a write-only ioctl, it does not return the current
76audio output attributes as <constant>VIDIOC_G_AUDOUT</constant>
77does.</para>
78
79 <para>Note connectors on a TV card to loop back the received audio
80signal to a sound card are not audio outputs in this sense.</para>
81
82 <table pgwide="1" frame="none" id="v4l2-audioout">
83 <title>struct <structname>v4l2_audioout</structname></title>
84 <tgroup cols="3">
85 &cs-str;
86 <tbody valign="top">
87 <row>
88 <entry>__u32</entry>
89 <entry><structfield>index</structfield></entry>
90 <entry>Identifies the audio output, set by the
91driver or application.</entry>
92 </row>
93 <row>
94 <entry>__u8</entry>
95 <entry><structfield>name</structfield>[32]</entry>
96 <entry>Name of the audio output, a NUL-terminated ASCII
97string, for example: "Line Out". This information is intended for the
98user, preferably the connector label on the device itself.</entry>
99 </row>
100 <row>
101 <entry>__u32</entry>
102 <entry><structfield>capability</structfield></entry>
103 <entry>Audio capability flags, none defined yet. Drivers
104must set this field to zero.</entry>
105 </row>
106 <row>
107 <entry>__u32</entry>
108 <entry><structfield>mode</structfield></entry>
109 <entry>Audio mode, none defined yet. Drivers and
110applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this
111field to zero.</entry>
112 </row>
113 <row>
114 <entry>__u32</entry>
115 <entry><structfield>reserved</structfield>[2]</entry>
116 <entry>Reserved for future extensions. Drivers and
117applications must set the array to zero.</entry>
118 </row>
119 </tbody>
120 </tgroup>
121 </table>
122 </refsect1>
123
124 <refsect1>
125 &return-value;
126
127 <variablelist>
128 <varlistentry>
129 <term><errorcode>EINVAL</errorcode></term>
130 <listitem>
131 <para>No audio outputs combine with the current video
132output, or the number of the selected audio output is out of bounds or
133it does not combine, or there are no audio outputs at all and the
134ioctl is not supported.</para>
135 </listitem>
136 </varlistentry>
137 <varlistentry>
138 <term><errorcode>EBUSY</errorcode></term>
139 <listitem>
140 <para>I/O is in progress, the output cannot be
141switched.</para>
142 </listitem>
143 </varlistentry>
144 </variablelist>
145 </refsect1>
146</refentry>
147
148<!--
149Local Variables:
150mode: sgml
151sgml-parent-document: "v4l2.sgml"
152indent-tabs-mode: nil
153End:
154-->