Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <refentry id="vidioc-g-modulator"> |
2 | <refmeta> | |
3 | <refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle> | |
4 | &manvol; | |
5 | </refmeta> | |
6 | ||
7 | <refnamediv> | |
8 | <refname>VIDIOC_G_MODULATOR</refname> | |
9 | <refname>VIDIOC_S_MODULATOR</refname> | |
10 | <refpurpose>Get or set modulator attributes</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_modulator | |
20 | *<parameter>argp</parameter></paramdef> | |
21 | </funcprototype> | |
22 | </funcsynopsis> | |
23 | <funcsynopsis> | |
24 | <funcprototype> | |
25 | <funcdef>int <function>ioctl</function></funcdef> | |
26 | <paramdef>int <parameter>fd</parameter></paramdef> | |
27 | <paramdef>int <parameter>request</parameter></paramdef> | |
28 | <paramdef>const struct v4l2_modulator | |
29 | *<parameter>argp</parameter></paramdef> | |
30 | </funcprototype> | |
31 | </funcsynopsis> | |
32 | </refsynopsisdiv> | |
33 | ||
34 | <refsect1> | |
35 | <title>Arguments</title> | |
36 | ||
37 | <variablelist> | |
38 | <varlistentry> | |
39 | <term><parameter>fd</parameter></term> | |
40 | <listitem> | |
41 | <para>&fd;</para> | |
42 | </listitem> | |
43 | </varlistentry> | |
44 | <varlistentry> | |
45 | <term><parameter>request</parameter></term> | |
46 | <listitem> | |
47 | <para>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</para> | |
48 | </listitem> | |
49 | </varlistentry> | |
50 | <varlistentry> | |
51 | <term><parameter>argp</parameter></term> | |
52 | <listitem> | |
53 | <para></para> | |
54 | </listitem> | |
55 | </varlistentry> | |
56 | </variablelist> | |
57 | </refsect1> | |
58 | ||
59 | <refsect1> | |
60 | <title>Description</title> | |
61 | ||
62 | <para>To query the attributes of a modulator applications initialize | |
63 | the <structfield>index</structfield> field and zero out the | |
64 | <structfield>reserved</structfield> array of a &v4l2-modulator; and | |
65 | call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer | |
66 | to this structure. Drivers fill the rest of the structure or return an | |
67 | &EINVAL; when the index is out of bounds. To enumerate all modulators | |
68 | applications shall begin at index zero, incrementing by one until the | |
69 | driver returns <errorcode>EINVAL</errorcode>.</para> | |
70 | ||
71 | <para>Modulators have two writable properties, an audio | |
72 | modulation set and the radio frequency. To change the modulated audio | |
73 | subprograms, applications initialize the <structfield>index | |
74 | </structfield> and <structfield>txsubchans</structfield> fields and the | |
75 | <structfield>reserved</structfield> array and call the | |
76 | <constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a | |
77 | different audio modulation if the request cannot be satisfied. However | |
78 | this is a write-only ioctl, it does not return the actual audio | |
79 | modulation selected.</para> | |
80 | ||
81 | <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl | |
82 | is available.</para> | |
83 | ||
84 | <table pgwide="1" frame="none" id="v4l2-modulator"> | |
85 | <title>struct <structname>v4l2_modulator</structname></title> | |
86 | <tgroup cols="3"> | |
87 | &cs-str; | |
88 | <tbody valign="top"> | |
89 | <row> | |
90 | <entry>__u32</entry> | |
91 | <entry><structfield>index</structfield></entry> | |
92 | <entry>Identifies the modulator, set by the | |
93 | application.</entry> | |
94 | </row> | |
95 | <row> | |
96 | <entry>__u8</entry> | |
97 | <entry><structfield>name</structfield>[32]</entry> | |
98 | <entry>Name of the modulator, a NUL-terminated ASCII | |
99 | string. This information is intended for the user.</entry> | |
100 | </row> | |
101 | <row> | |
102 | <entry>__u32</entry> | |
103 | <entry><structfield>capability</structfield></entry> | |
104 | <entry>Modulator capability flags. No flags are defined | |
105 | for this field, the tuner flags in &v4l2-tuner; | |
106 | are used accordingly. The audio flags indicate the ability | |
107 | to encode audio subprograms. They will <emphasis>not</emphasis> | |
108 | change for example with the current video standard.</entry> | |
109 | </row> | |
110 | <row> | |
111 | <entry>__u32</entry> | |
112 | <entry><structfield>rangelow</structfield></entry> | |
113 | <entry>The lowest tunable frequency in units of 62.5 | |
114 | KHz, or if the <structfield>capability</structfield> flag | |
115 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | |
116 | Hz.</entry> | |
117 | </row> | |
118 | <row> | |
119 | <entry>__u32</entry> | |
120 | <entry><structfield>rangehigh</structfield></entry> | |
121 | <entry>The highest tunable frequency in units of 62.5 | |
122 | KHz, or if the <structfield>capability</structfield> flag | |
123 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | |
124 | Hz.</entry> | |
125 | </row> | |
126 | <row> | |
127 | <entry>__u32</entry> | |
128 | <entry><structfield>txsubchans</structfield></entry> | |
129 | <entry>With this field applications can determine how | |
130 | audio sub-carriers shall be modulated. It contains a set of flags as | |
131 | defined in <xref linkend="modulator-txsubchans" />. Note the tuner | |
132 | <structfield>rxsubchans</structfield> flags are reused, but the | |
133 | semantics are different. Video output devices are assumed to have an | |
134 | analog or PCM audio input with 1-3 channels. The | |
135 | <structfield>txsubchans</structfield> flags select one or more | |
136 | channels for modulation, together with some audio subprogram | |
137 | indicator, for example a stereo pilot tone.</entry> | |
138 | </row> | |
139 | <row> | |
140 | <entry>__u32</entry> | |
141 | <entry><structfield>reserved</structfield>[4]</entry> | |
142 | <entry>Reserved for future extensions. Drivers and | |
143 | applications must set the array to zero.</entry> | |
144 | </row> | |
145 | </tbody> | |
146 | </tgroup> | |
147 | </table> | |
148 | ||
149 | <table pgwide="1" frame="none" id="modulator-txsubchans"> | |
150 | <title>Modulator Audio Transmission Flags</title> | |
151 | <tgroup cols="3"> | |
152 | &cs-def; | |
153 | <tbody valign="top"> | |
154 | <row> | |
155 | <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> | |
156 | <entry>0x0001</entry> | |
157 | <entry>Modulate channel 1 as mono audio, when the input | |
158 | has more channels, a down-mix of channel 1 and 2. This flag does not | |
159 | combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or | |
160 | <constant>V4L2_TUNER_SUB_LANG1</constant>.</entry> | |
161 | </row> | |
162 | <row> | |
163 | <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> | |
164 | <entry>0x0002</entry> | |
165 | <entry>Modulate channel 1 and 2 as left and right | |
166 | channel of a stereo audio signal. When the input has only one channel | |
167 | or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also | |
168 | set, channel 1 is encoded as left and right channel. This flag does | |
169 | not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or | |
170 | <constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not | |
171 | support stereo audio it shall fall back to mono.</entry> | |
172 | </row> | |
173 | <row> | |
174 | <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> | |
175 | <entry>0x0008</entry> | |
176 | <entry>Modulate channel 1 and 2 as primary and secondary | |
177 | language of a bilingual audio signal. When the input has only one | |
178 | channel it is used for both languages. It is not possible to encode | |
179 | the primary or secondary language only. This flag does not combine | |
180 | with <constant>V4L2_TUNER_SUB_MONO</constant>, | |
181 | <constant>V4L2_TUNER_SUB_STEREO</constant> or | |
182 | <constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not | |
183 | support the respective audio matrix, or the current video standard | |
184 | does not permit bilingual audio the | |
185 | <constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL; | |
186 | and the driver shall fall back to mono or stereo mode.</entry> | |
187 | </row> | |
188 | <row> | |
189 | <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> | |
190 | <entry>0x0004</entry> | |
191 | <entry>Same effect as | |
192 | <constant>V4L2_TUNER_SUB_SAP</constant>.</entry> | |
193 | </row> | |
194 | <row> | |
195 | <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> | |
196 | <entry>0x0004</entry> | |
197 | <entry>When combined with <constant>V4L2_TUNER_SUB_MONO | |
198 | </constant> the first channel is encoded as mono audio, the last | |
199 | channel as Second Audio Program. When the input has only one channel | |
200 | it is used for both audio tracks. When the input has three channels | |
201 | the mono track is a down-mix of channel 1 and 2. When combined with | |
202 | <constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are | |
203 | encoded as left and right stereo audio, channel 3 as Second Audio | |
204 | Program. When the input has only two channels, the first is encoded as | |
205 | left and right channel and the second as SAP. When the input has only | |
206 | one channel it is used for all audio tracks. It is not possible to | |
207 | encode a Second Audio Program only. This flag must combine with | |
208 | <constant>V4L2_TUNER_SUB_MONO</constant> or | |
209 | <constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not | |
210 | support the respective audio matrix, or the current video standard | |
211 | does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl | |
212 | shall return an &EINVAL; and driver shall fall back to mono or stereo | |
213 | mode.</entry> | |
214 | </row> | |
215 | <row> | |
216 | <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> | |
217 | <entry>0x0010</entry> | |
218 | <entry>Enable the RDS encoder for a radio FM transmitter.</entry> | |
219 | </row> | |
220 | </tbody> | |
221 | </tgroup> | |
222 | </table> | |
223 | </refsect1> | |
224 | ||
225 | <refsect1> | |
226 | &return-value; | |
227 | ||
228 | <variablelist> | |
229 | <varlistentry> | |
230 | <term><errorcode>EINVAL</errorcode></term> | |
231 | <listitem> | |
232 | <para>The &v4l2-modulator; | |
233 | <structfield>index</structfield> is out of bounds.</para> | |
234 | </listitem> | |
235 | </varlistentry> | |
236 | </variablelist> | |
237 | </refsect1> | |
238 | </refentry> | |
239 | ||
240 | <!-- | |
241 | Local Variables: | |
242 | mode: sgml | |
243 | sgml-parent-document: "v4l2.sgml" | |
244 | indent-tabs-mode: nil | |
245 | End: | |
246 | --> |