• 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>Image 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="PREVIOUS"
13TITLE="Streaming Parameters"
14HREF="x2009.htm"><LINK
15REL="NEXT"
16TITLE="Colorspaces"
17HREF="x2123.htm"></HEAD
18><BODY
19CLASS="CHAPTER"
20BGCOLOR="#FFFFFF"
21TEXT="#000000"
22LINK="#0000FF"
23VLINK="#840084"
24ALINK="#0000FF"
25><DIV
26CLASS="NAVHEADER"
27><TABLE
28SUMMARY="Header navigation table"
29WIDTH="100%"
30BORDER="0"
31CELLPADDING="0"
32CELLSPACING="0"
33><TR
34><TH
35COLSPAN="3"
36ALIGN="center"
37>Video for Linux Two API Specification: Revision 0.24</TH
38></TR
39><TR
40><TD
41WIDTH="10%"
42ALIGN="left"
43VALIGN="bottom"
44><A
45HREF="x2009.htm"
46ACCESSKEY="P"
47>Prev</A
48></TD
49><TD
50WIDTH="80%"
51ALIGN="center"
52VALIGN="bottom"
53></TD
54><TD
55WIDTH="10%"
56ALIGN="right"
57VALIGN="bottom"
58><A
59HREF="x2123.htm"
60ACCESSKEY="N"
61>Next</A
62></TD
63></TR
64></TABLE
65><HR
66ALIGN="LEFT"
67WIDTH="100%"></DIV
68><DIV
69CLASS="CHAPTER"
70><H1
71><A
72NAME="PIXFMT"
73></A
74>Chapter 2. Image Formats</H1
75><DIV
76CLASS="TOC"
77><DL
78><DT
79><B
80>Table of Contents</B
81></DT
82><DT
83>2.1. <A
84HREF="c2030.htm#AEN2113"
85>Standard Image Formats</A
86></DT
87><DT
88>2.2. <A
89HREF="x2123.htm"
90>Colorspaces</A
91></DT
92><DT
93>2.3. <A
94HREF="x2428.htm"
95>Indexed Format</A
96></DT
97><DT
98>2.4. <A
99HREF="x2490.htm"
100>RGB Formats</A
101></DT
102><DT
103>2.5. <A
104HREF="x3891.htm"
105>YUV Formats</A
106></DT
107><DT
108>2.6. <A
109HREF="x5634.htm"
110>Compressed Formats</A
111></DT
112><DT
113>2.7. <A
114HREF="x5665.htm"
115>Reserved Format Identifiers</A
116></DT
117></DL
118></DIV
119><P
120>The V4L2 API was primarily designed for devices exchanging
121image data with applications. The
122<CODE
123CLASS="STRUCTNAME"
124>v4l2_pix_format</CODE
125> structure defines the format
126and layout of an image in memory. Image formats are negotiated with
127the <A
128HREF="r10944.htm"
129><CODE
130CLASS="CONSTANT"
131>VIDIOC_S_FMT</CODE
132></A
133> ioctl. (The explanations here focus on video
134capturing and output, for overlay frame buffer formats see also
135<A
136HREF="r10595.htm"
137><CODE
138CLASS="CONSTANT"
139>VIDIOC_G_FBUF</CODE
140></A
141>.)</P
142><DIV
143CLASS="TABLE"
144><A
145NAME="V4L2-PIX-FORMAT"
146></A
147><P
148><B
149>Table 2-1. struct <CODE
150CLASS="STRUCTNAME"
151>v4l2_pix_format</CODE
152></B
153></P
154><TABLE
155BORDER="0"
156FRAME="void"
157WIDTH="100%"
158CLASS="CALSTABLE"
159><COL
160WIDTH="25%"
161TITLE="C1"><COL
162WIDTH="25%"
163TITLE="C2"><COL
164WIDTH="50%"
165TITLE="C3"><TBODY
166VALIGN="TOP"
167><TR
168><TD
169>__u32</TD
170><TD
171><CODE
172CLASS="STRUCTFIELD"
173>width</CODE
174></TD
175><TD
176>Image width in pixels.</TD
177></TR
178><TR
179><TD
180>__u32</TD
181><TD
182><CODE
183CLASS="STRUCTFIELD"
184>height</CODE
185></TD
186><TD
187>Image height in pixels.</TD
188></TR
189><TR
190><TD
191COLSPAN="3"
192>Applications set these fields to
193request an image size, drivers return the closest possible values. In
194case of planar formats the <CODE
195CLASS="STRUCTFIELD"
196>width</CODE
197> and
198<CODE
199CLASS="STRUCTFIELD"
200>height</CODE
201> applies to the largest plane. To
202avoid ambiguities drivers must return values rounded up to a multiple
203of the scale factor of any smaller planes. For example when the image
204format is YUV 4:2:0, <CODE
205CLASS="STRUCTFIELD"
206>width</CODE
207> and
208<CODE
209CLASS="STRUCTFIELD"
210>height</CODE
211> must be multiples of two.</TD
212></TR
213><TR
214><TD
215>__u32</TD
216><TD
217><CODE
218CLASS="STRUCTFIELD"
219>pixelformat</CODE
220></TD
221><TD
222>The pixel format or type of compression, set by the
223application. This is a little endian <A
224HREF="r8367.htm#V4L2-FOURCC"
225>four character code</A
226>. V4L2 defines
227standard RGB formats in <A
228HREF="r2492.htm#RGB-FORMATS"
229>Table 2-1</A
230>, YUV formats in <A
231HREF="x3891.htm"
232>Section 2.5</A
233>, and reserved codes in <A
234HREF="x5665.htm#RESERVED-FORMATS"
235>Table 2-8</A
236></TD
237></TR
238><TR
239><TD
240>enum&nbsp;<A
241HREF="x6386.htm#V4L2-FIELD"
242>v4l2_field</A
243></TD
244><TD
245><CODE
246CLASS="STRUCTFIELD"
247>field</CODE
248></TD
249><TD
250>Video images are typically interlaced. Applications
251can request to capture or output only the top or bottom field, or both
252fields interlaced or sequentially stored in one buffer or alternating
253in separate buffers. Drivers return the actual field order selected.
254For details see <A
255HREF="x6386.htm"
256>Section 3.6</A
257>.</TD
258></TR
259><TR
260><TD
261>__u32</TD
262><TD
263><CODE
264CLASS="STRUCTFIELD"
265>bytesperline</CODE
266></TD
267><TD
268>Distance in bytes between the leftmost pixels in two
269adjacent lines.</TD
270></TR
271><TR
272><TD
273COLSPAN="3"
274><P
275>Both applications and drivers
276can set this field to request padding bytes at the end of each line.
277Drivers however may ignore the value requested by the application,
278returning <CODE
279CLASS="STRUCTFIELD"
280>width</CODE
281> times bytes per pixel or a
282larger value required by the hardware. That implies applications can
283just set this field to zero to get a reasonable
284default.</P
285><P
286>Video hardware may access padding bytes,
287therefore they must reside in accessible memory. Consider cases where
288padding bytes after the last line of an image cross a system page
289boundary. Input devices may write padding bytes, the value is
290undefined. Output devices ignore the contents of padding
291bytes.</P
292><P
293>When the image format is planar the
294<CODE
295CLASS="STRUCTFIELD"
296>bytesperline</CODE
297> value applies to the largest
298plane and is divided by the same factor as the
299<CODE
300CLASS="STRUCTFIELD"
301>width</CODE
302> field for any smaller planes. For
303example the Cb and Cr planes of a YUV 4:2:0 image have half as many
304padding bytes following each line as the Y plane. To avoid ambiguities
305drivers must return a <CODE
306CLASS="STRUCTFIELD"
307>bytesperline</CODE
308> value
309rounded up to a multiple of the scale factor.</P
310></TD
311></TR
312><TR
313><TD
314>__u32</TD
315><TD
316><CODE
317CLASS="STRUCTFIELD"
318>sizeimage</CODE
319></TD
320><TD
321>Size in bytes of the buffer to hold a complete image,
322set by the driver. Usually this is
323<CODE
324CLASS="STRUCTFIELD"
325>bytesperline</CODE
326> times
327<CODE
328CLASS="STRUCTFIELD"
329>height</CODE
330>. When the image consists of variable
331length compressed data this is the maximum number of bytes required to
332hold an image.</TD
333></TR
334><TR
335><TD
336>enum&nbsp;<A
337HREF="x2123.htm#V4L2-COLORSPACE"
338>v4l2_colorspace</A
339></TD
340><TD
341><CODE
342CLASS="STRUCTFIELD"
343>colorspace</CODE
344></TD
345><TD
346>This information supplements the
347<CODE
348CLASS="STRUCTFIELD"
349>pixelformat</CODE
350> and must be set by the driver,
351see <A
352HREF="x2123.htm"
353>Section 2.2</A
354>.</TD
355></TR
356><TR
357><TD
358>__u32</TD
359><TD
360><CODE
361CLASS="STRUCTFIELD"
362>priv</CODE
363></TD
364><TD
365>Reserved for custom (driver defined) additional
366information about formats. When not used drivers and applications must
367set this field to zero.</TD
368></TR
369></TBODY
370></TABLE
371></DIV
372><DIV
373CLASS="SECTION"
374><H1
375CLASS="SECTION"
376><A
377NAME="AEN2113"
378>2.1. Standard Image Formats</A
379></H1
380><P
381>In order to exchange images between drivers and
382applications, it is necessary to have standard image data formats
383which both sides will interpret the same way. V4L2 includes several
384such formats, and this section is intended to be an unambiguous
385specification of the standard image data formats in V4L2.</P
386><P
387>V4L2 drivers are not limited to these formats, however.
388Driver-specific formats are possible. In that case the application may
389depend on a codec to convert images to one of the standard formats
390when needed. But the data can still be stored and retrieved in the
391proprietary format. For example, a device may support a proprietary
392compressed format. Applications can still capture and save the data in
393the compressed format, saving much disk space, and later use a codec
394to convert the images to the X Windows screen format when the video is
395to be displayed.</P
396><P
397>Even so, ultimately, some standard formats are needed, so
398the V4L2 specification would not be complete without well-defined
399standard formats.</P
400><P
401>The V4L2 standard formats are mainly uncompressed formats. The
402pixels are always arranged in memory from left to right, and from top
403to bottom. The first byte of data in the image buffer is always for
404the leftmost pixel of the topmost row. Following that is the pixel
405immediately to its right, and so on until the end of the top row of
406pixels. Following the rightmost pixel of the row there may be zero or
407more bytes of padding to guarantee that each row of pixel data has a
408certain alignment. Following the pad bytes, if any, is data for the
409leftmost pixel of the second row from the top, and so on. The last row
410has just as many pad bytes after it as the other rows.</P
411><P
412>In V4L2 each format has an identifier which looks like
413<CODE
414CLASS="CONSTANT"
415>PIX_FMT_XXX</CODE
416>, defined in the <A
417HREF="a16506.htm"
418>videodev.h</A
419> header file. These identifiers
420represent <A
421HREF="r8367.htm#V4L2-FOURCC"
422>four character codes</A
423>
424which are also listed below, however they are not the same as those
425used in the Windows world.</P
426></DIV
427></DIV
428><DIV
429CLASS="NAVFOOTER"
430><HR
431ALIGN="LEFT"
432WIDTH="100%"><TABLE
433SUMMARY="Footer navigation table"
434WIDTH="100%"
435BORDER="0"
436CELLPADDING="0"
437CELLSPACING="0"
438><TR
439><TD
440WIDTH="33%"
441ALIGN="left"
442VALIGN="top"
443><A
444HREF="x2009.htm"
445ACCESSKEY="P"
446>Prev</A
447></TD
448><TD
449WIDTH="34%"
450ALIGN="center"
451VALIGN="top"
452><A
453HREF="book1.htm"
454ACCESSKEY="H"
455>Home</A
456></TD
457><TD
458WIDTH="33%"
459ALIGN="right"
460VALIGN="top"
461><A
462HREF="x2123.htm"
463ACCESSKEY="N"
464>Next</A
465></TD
466></TR
467><TR
468><TD
469WIDTH="33%"
470ALIGN="left"
471VALIGN="top"
472>Streaming Parameters</TD
473><TD
474WIDTH="34%"
475ALIGN="center"
476VALIGN="top"
477>&nbsp;</TD
478><TD
479WIDTH="33%"
480ALIGN="right"
481VALIGN="top"
482>Colorspaces</TD
483></TR
484></TABLE
485></DIV
486></BODY
487></HTML
488>
489