• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2<HTML
3><HEAD
4><TITLE
5>Data Formats</TITLE
6><META
7NAME="GENERATOR"
8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9REL="HOME"
10TITLE="Video for Linux Two API Specification"
11HREF="book1.htm"><LINK
12REL="UP"
13TITLE="Common API Elements"
14HREF="c174.htm"><LINK
15REL="PREVIOUS"
16TITLE="Extended Controls"
17HREF="x802.htm"><LINK
18REL="NEXT"
19TITLE="Image Cropping, Insertion and Scaling"
20HREF="x1904.htm"></HEAD
21><BODY
22CLASS="SECTION"
23BGCOLOR="#FFFFFF"
24TEXT="#000000"
25LINK="#0000FF"
26VLINK="#840084"
27ALINK="#0000FF"
28><DIV
29CLASS="NAVHEADER"
30><TABLE
31SUMMARY="Header navigation table"
32WIDTH="100%"
33BORDER="0"
34CELLPADDING="0"
35CELLSPACING="0"
36><TR
37><TH
38COLSPAN="3"
39ALIGN="center"
40>Video for Linux Two API Specification: Revision 0.24</TH
41></TR
42><TR
43><TD
44WIDTH="10%"
45ALIGN="left"
46VALIGN="bottom"
47><A
48HREF="x802.htm"
49ACCESSKEY="P"
50>Prev</A
51></TD
52><TD
53WIDTH="80%"
54ALIGN="center"
55VALIGN="bottom"
56>Chapter 1. Common API Elements</TD
57><TD
58WIDTH="10%"
59ALIGN="right"
60VALIGN="bottom"
61><A
62HREF="x1904.htm"
63ACCESSKEY="N"
64>Next</A
65></TD
66></TR
67></TABLE
68><HR
69ALIGN="LEFT"
70WIDTH="100%"></DIV
71><DIV
72CLASS="SECTION"
73><H1
74CLASS="SECTION"
75><A
76NAME="FORMAT"
77>1.10. Data Formats</A
78></H1
79><DIV
80CLASS="SECTION"
81><H2
82CLASS="SECTION"
83><A
84NAME="AEN1861"
85>1.10.1. Data Format Negotiation</A
86></H2
87><P
88>Different devices exchange different kinds of data with
89applications, for example video images, raw or sliced VBI data, RDS
90datagrams. Even within one kind many different formats are possible,
91in particular an abundance of image formats. Although drivers must
92provide a default and the selection persists across closing and
93reopening a device, applications should always negotiate a data format
94before engaging in data exchange. Negotiation means the application
95asks for a particular format and the driver selects and reports the
96best the hardware can do to satisfy the request. Of course
97applications can also just query the current selection.</P
98><P
99>A single mechanism exists to negotiate all data formats
100using the aggregate struct&nbsp;<A
101HREF="r10944.htm#V4L2-FORMAT"
102>v4l2_format</A
103> and the <A
104HREF="r10944.htm"
105><CODE
106CLASS="CONSTANT"
107>VIDIOC_G_FMT</CODE
108></A
109> and
110<A
111HREF="r10944.htm"
112><CODE
113CLASS="CONSTANT"
114>VIDIOC_S_FMT</CODE
115></A
116> ioctls. Additionally the <A
117HREF="r10944.htm"
118><CODE
119CLASS="CONSTANT"
120>VIDIOC_TRY_FMT</CODE
121></A
122> ioctl can be
123used to examine what the hardware <SPAN
124CLASS="emphasis"
125><I
126CLASS="EMPHASIS"
127>could</I
128></SPAN
129> do,
130without actually selecting a new data format. The data formats
131supported by the V4L2 API are covered in the respective device section
132in <A
133HREF="c6488.htm"
134>Chapter 4</A
135>. For a closer look at image formats see
136<A
137HREF="c2030.htm"
138>Chapter 2</A
139>.</P
140><P
141>The <CODE
142CLASS="CONSTANT"
143>VIDIOC_S_FMT</CODE
144> ioctl is a major
145turning-point in the initialization sequence. Prior to this point
146multiple panel applications can access the same device concurrently to
147select the current input, change controls or modify other properties.
148The first <CODE
149CLASS="CONSTANT"
150>VIDIOC_S_FMT</CODE
151> assigns a logical stream
152(video data, VBI data etc.) exclusively to one file descriptor.</P
153><P
154>Exclusive means no other application, more precisely no
155other file descriptor, can grab this stream or change device
156properties inconsistent with the negotiated parameters. A video
157standard change for example, when the new standard uses a different
158number of scan lines, can invalidate the selected image format.
159Therefore only the file descriptor owning the stream can make
160invalidating changes. Accordingly multiple file descriptors which
161grabbed different logical streams prevent each other from interfering
162with their settings. When for example video overlay is about to start
163or already in progress, simultaneous video capturing may be restricted
164to the same cropping and image size.</P
165><P
166>When applications omit the
167<CODE
168CLASS="CONSTANT"
169>VIDIOC_S_FMT</CODE
170> ioctl its locking side effects are
171implied by the next step, the selection of an I/O method with the
172<A
173HREF="r13696.htm"
174><CODE
175CLASS="CONSTANT"
176>VIDIOC_REQBUFS</CODE
177></A
178> ioctl or implicit with the first <A
179HREF="r14264.htm"
180><CODE
181CLASS="FUNCTION"
182>read()</CODE
183></A
184> or
185<A
186HREF="r14496.htm"
187><CODE
188CLASS="FUNCTION"
189>write()</CODE
190></A
191> call.</P
192><P
193>Generally only one logical stream can be assigned to a
194file descriptor, the exception being drivers permitting simultaneous
195video capturing and overlay using the same file descriptor for
196compatibility with V4L and earlier versions of V4L2. Switching the
197logical stream or returning into "panel mode" is possible by closing
198and reopening the device. Drivers <SPAN
199CLASS="emphasis"
200><I
201CLASS="EMPHASIS"
202>may</I
203></SPAN
204> support a
205switch using <CODE
206CLASS="CONSTANT"
207>VIDIOC_S_FMT</CODE
208>.</P
209><P
210>All drivers exchanging data with
211applications must support the <CODE
212CLASS="CONSTANT"
213>VIDIOC_G_FMT</CODE
214> and
215<CODE
216CLASS="CONSTANT"
217>VIDIOC_S_FMT</CODE
218> ioctl. Implementation of the
219<CODE
220CLASS="CONSTANT"
221>VIDIOC_TRY_FMT</CODE
222> is highly recommended but
223optional.</P
224></DIV
225><DIV
226CLASS="SECTION"
227><H2
228CLASS="SECTION"
229><A
230NAME="AEN1894"
231>1.10.2. Image Format Enumeration</A
232></H2
233><P
234>Apart of the generic format negotiation functions
235a special ioctl to enumerate all image formats supported by video
236capture, overlay or output devices is available.<A
237NAME="AEN1897"
238HREF="x1859.htm#FTN.AEN1897"
239><SPAN
240CLASS="footnote"
241>[1]</SPAN
242></A
243></P
244><P
245>The <A
246HREF="r8367.htm"
247><CODE
248CLASS="CONSTANT"
249>VIDIOC_ENUM_FMT</CODE
250></A
251> ioctl must be supported
252by all drivers exchanging image data with applications.</P
253><DIV
254CLASS="IMPORTANT"
255><BLOCKQUOTE
256CLASS="IMPORTANT"
257><P
258><B
259>Important: </B
260>Drivers are not supposed to convert image formats in
261kernel space. They must enumerate only formats directly supported by
262the hardware. If necessary driver writers should publish an example
263conversion routine or library for integration into applications.</P
264></BLOCKQUOTE
265></DIV
266></DIV
267></DIV
268><H3
269CLASS="FOOTNOTES"
270>Notes</H3
271><TABLE
272BORDER="0"
273CLASS="FOOTNOTES"
274WIDTH="100%"
275><TR
276><TD
277ALIGN="LEFT"
278VALIGN="TOP"
279WIDTH="5%"
280><A
281NAME="FTN.AEN1897"
282HREF="x1859.htm#AEN1897"
283><SPAN
284CLASS="footnote"
285>[1]</SPAN
286></A
287></TD
288><TD
289ALIGN="LEFT"
290VALIGN="TOP"
291WIDTH="95%"
292><P
293>Enumerating formats an application has no a-priori
294knowledge of (otherwise it could explicitely ask for them and need not
295enumerate) seems useless, but there are applications serving as proxy
296between drivers and the actual video applications for which this is
297useful.</P
298></TD
299></TR
300></TABLE
301><DIV
302CLASS="NAVFOOTER"
303><HR
304ALIGN="LEFT"
305WIDTH="100%"><TABLE
306SUMMARY="Footer navigation table"
307WIDTH="100%"
308BORDER="0"
309CELLPADDING="0"
310CELLSPACING="0"
311><TR
312><TD
313WIDTH="33%"
314ALIGN="left"
315VALIGN="top"
316><A
317HREF="x802.htm"
318ACCESSKEY="P"
319>Prev</A
320></TD
321><TD
322WIDTH="34%"
323ALIGN="center"
324VALIGN="top"
325><A
326HREF="book1.htm"
327ACCESSKEY="H"
328>Home</A
329></TD
330><TD
331WIDTH="33%"
332ALIGN="right"
333VALIGN="top"
334><A
335HREF="x1904.htm"
336ACCESSKEY="N"
337>Next</A
338></TD
339></TR
340><TR
341><TD
342WIDTH="33%"
343ALIGN="left"
344VALIGN="top"
345>Extended Controls</TD
346><TD
347WIDTH="34%"
348ALIGN="center"
349VALIGN="top"
350><A
351HREF="c174.htm"
352ACCESSKEY="U"
353>Up</A
354></TD
355><TD
356WIDTH="33%"
357ALIGN="right"
358VALIGN="top"
359>Image Cropping, Insertion and Scaling</TD
360></TR
361></TABLE
362></DIV
363></BODY
364></HTML
365>
366