summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml
blob: 200a2704a970842f68839a0afb2ffd7807b5897f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
<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>