123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992 |
- <title>Image Formats</title>
- <para>The V4L2 API was primarily designed for devices exchanging
- image data with applications. The
- <structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane
- </structname> structures define the format and layout of an image in memory.
- The former is used with the single-planar API, while the latter is used with the
- multi-planar version (see <xref linkend="planar-apis"/>). Image formats are
- negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
- capturing and output, for overlay frame buffer formats see also
- &VIDIOC-G-FBUF;.)</para>
- <section>
- <title>Single-planar format structure</title>
- <table pgwide="1" frame="none" id="v4l2-pix-format">
- <title>struct <structname>v4l2_pix_format</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Image width in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Image height in pixels. If <structfield>field</structfield> is
- one of <constant>V4L2_FIELD_TOP</constant>, <constant>V4L2_FIELD_BOTTOM</constant>
- or <constant>V4L2_FIELD_ALTERNATE</constant> then height refers to the
- number of lines in the field, otherwise it refers to the number of
- lines in the frame (which is twice the field height for interlaced
- formats).</entry>
- </row>
- <row>
- <entry spanname="hspan">Applications set these fields to
- request an image size, drivers return the closest possible values. In
- case of planar formats the <structfield>width</structfield> and
- <structfield>height</structfield> applies to the largest plane. To
- avoid ambiguities drivers must return values rounded up to a multiple
- of the scale factor of any smaller planes. For example when the image
- format is YUV 4:2:0, <structfield>width</structfield> and
- <structfield>height</structfield> must be multiples of two.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pixelformat</structfield></entry>
- <entry>The pixel format or type of compression, set by the
- application. This is a little endian <link
- linkend="v4l2-fourcc">four character code</link>. V4L2 defines
- standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref
- linkend="yuv-formats" />, and reserved codes in <xref
- linkend="reserved-formats" /></entry>
- </row>
- <row>
- <entry>&v4l2-field;</entry>
- <entry><structfield>field</structfield></entry>
- <entry>Video images are typically interlaced. Applications
- can request to capture or output only the top or bottom field, or both
- fields interlaced or sequentially stored in one buffer or alternating
- in separate buffers. Drivers return the actual field order selected.
- For more details on fields see <xref linkend="field-order" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>bytesperline</structfield></entry>
- <entry>Distance in bytes between the leftmost pixels in two
- adjacent lines.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>Both applications and drivers
- can set this field to request padding bytes at the end of each line.
- Drivers however may ignore the value requested by the application,
- returning <structfield>width</structfield> times bytes per pixel or a
- larger value required by the hardware. That implies applications can
- just set this field to zero to get a reasonable
- default.</para><para>Video hardware may access padding bytes,
- therefore they must reside in accessible memory. Consider cases where
- padding bytes after the last line of an image cross a system page
- boundary. Input devices may write padding bytes, the value is
- undefined. Output devices ignore the contents of padding
- bytes.</para><para>When the image format is planar the
- <structfield>bytesperline</structfield> value applies to the first
- plane and is divided by the same factor as the
- <structfield>width</structfield> field for the other planes. For
- example the Cb and Cr planes of a YUV 4:2:0 image have half as many
- padding bytes following each line as the Y plane. To avoid ambiguities
- drivers must return a <structfield>bytesperline</structfield> value
- rounded up to a multiple of the scale factor.</para>
- <para>For compressed formats the <structfield>bytesperline</structfield>
- value makes no sense. Applications and drivers must set this to 0 in
- that case.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>sizeimage</structfield></entry>
- <entry>Size in bytes of the buffer to hold a complete image,
- set by the driver. Usually this is
- <structfield>bytesperline</structfield> times
- <structfield>height</structfield>. When the image consists of variable
- length compressed data this is the maximum number of bytes required to
- hold an image.</entry>
- </row>
- <row>
- <entry>&v4l2-colorspace;</entry>
- <entry><structfield>colorspace</structfield></entry>
- <entry>This information supplements the
- <structfield>pixelformat</structfield> and must be set by the driver for
- capture streams and by the application for output streams,
- see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>priv</structfield></entry>
- <entry><para>This field indicates whether the remaining fields of the
- <structname>v4l2_pix_format</structname> structure, also called the extended
- fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it
- indicates that the extended fields have been correctly initialized. When set to
- any other value it indicates that the extended fields contain undefined values.
- </para>
- <para>Applications that wish to use the pixel format extended fields must first
- ensure that the feature is supported by querying the device for the
- <link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link>
- capability. If the capability isn't set the pixel format extended fields are not
- supported and using the extended fields will lead to undefined results.</para>
- <para>To use the extended fields, applications must set the
- <structfield>priv</structfield> field to
- <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, initialize all the extended fields
- and zero the unused bytes of the <structname>v4l2_format</structname>
- <structfield>raw_data</structfield> field.</para>
- <para>When the <structfield>priv</structfield> field isn't set to
- <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> drivers must act as if all the
- extended fields were set to zero. On return drivers must set the
- <structfield>priv</structfield> field to
- <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> and all the extended fields to
- applicable values.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags set by the application or driver, see <xref
- linkend="format-flags" />.</entry>
- </row>
- <row>
- <entry>&v4l2-ycbcr-encoding;</entry>
- <entry><structfield>ycbcr_enc</structfield></entry>
- <entry>This information supplements the
- <structfield>colorspace</structfield> and must be set by the driver for
- capture streams and by the application for output streams,
- see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>&v4l2-quantization;</entry>
- <entry><structfield>quantization</structfield></entry>
- <entry>This information supplements the
- <structfield>colorspace</structfield> and must be set by the driver for
- capture streams and by the application for output streams,
- see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>&v4l2-xfer-func;</entry>
- <entry><structfield>xfer_func</structfield></entry>
- <entry>This information supplements the
- <structfield>colorspace</structfield> and must be set by the driver for
- capture streams and by the application for output streams,
- see <xref linkend="colorspaces" />.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>Multi-planar format structures</title>
- <para>The <structname>v4l2_plane_pix_format</structname> structures define
- size and layout for each of the planes in a multi-planar format.
- The <structname>v4l2_pix_format_mplane</structname> structure contains
- information common to all planes (such as image width and height) and
- an array of <structname>v4l2_plane_pix_format</structname> structures,
- describing all planes of that format.</para>
- <table pgwide="1" frame="none" id="v4l2-plane-pix-format">
- <title>struct <structname>v4l2_plane_pix_format</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>sizeimage</structfield></entry>
- <entry>Maximum size in bytes required for image data in this plane.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>bytesperline</structfield></entry>
- <entry>Distance in bytes between the leftmost pixels in two adjacent
- lines. See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>__u16</entry>
- <entry><structfield>reserved[6]</structfield></entry>
- <entry>Reserved for future extensions. Should be zeroed by drivers and
- applications.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table pgwide="1" frame="none" id="v4l2-pix-format-mplane">
- <title>struct <structname>v4l2_pix_format_mplane</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Image width in pixels. See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Image height in pixels. See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pixelformat</structfield></entry>
- <entry>The pixel format. Both single- and multi-planar four character
- codes can be used.</entry>
- </row>
- <row>
- <entry>&v4l2-field;</entry>
- <entry><structfield>field</structfield></entry>
- <entry>See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>&v4l2-colorspace;</entry>
- <entry><structfield>colorspace</structfield></entry>
- <entry>See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>&v4l2-plane-pix-format;</entry>
- <entry><structfield>plane_fmt[VIDEO_MAX_PLANES]</structfield></entry>
- <entry>An array of structures describing format of each plane this
- pixel format consists of. The number of valid entries in this array
- has to be put in the <structfield>num_planes</structfield>
- field.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>num_planes</structfield></entry>
- <entry>Number of planes (i.e. separate memory buffers) for this format
- and the number of valid entries in the
- <structfield>plane_fmt</structfield> array.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags set by the application or driver, see <xref
- linkend="format-flags" />.</entry>
- </row>
- <row>
- <entry>&v4l2-ycbcr-encoding;</entry>
- <entry><structfield>ycbcr_enc</structfield></entry>
- <entry>This information supplements the
- <structfield>colorspace</structfield> and must be set by the driver for
- capture streams and by the application for output streams,
- see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>&v4l2-quantization;</entry>
- <entry><structfield>quantization</structfield></entry>
- <entry>This information supplements the
- <structfield>colorspace</structfield> and must be set by the driver for
- capture streams and by the application for output streams,
- see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>&v4l2-xfer-func;</entry>
- <entry><structfield>xfer_func</structfield></entry>
- <entry>This information supplements the
- <structfield>colorspace</structfield> and must be set by the driver for
- capture streams and by the application for output streams,
- see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>reserved[7]</structfield></entry>
- <entry>Reserved for future extensions. Should be zeroed by drivers
- and applications.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>Standard Image Formats</title>
- <para>In order to exchange images between drivers and
- applications, it is necessary to have standard image data formats
- which both sides will interpret the same way. V4L2 includes several
- such formats, and this section is intended to be an unambiguous
- specification of the standard image data formats in V4L2.</para>
- <para>V4L2 drivers are not limited to these formats, however.
- Driver-specific formats are possible. In that case the application may
- depend on a codec to convert images to one of the standard formats
- when needed. But the data can still be stored and retrieved in the
- proprietary format. For example, a device may support a proprietary
- compressed format. Applications can still capture and save the data in
- the compressed format, saving much disk space, and later use a codec
- to convert the images to the X Windows screen format when the video is
- to be displayed.</para>
- <para>Even so, ultimately, some standard formats are needed, so
- the V4L2 specification would not be complete without well-defined
- standard formats.</para>
- <para>The V4L2 standard formats are mainly uncompressed formats. The
- pixels are always arranged in memory from left to right, and from top
- to bottom. The first byte of data in the image buffer is always for
- the leftmost pixel of the topmost row. Following that is the pixel
- immediately to its right, and so on until the end of the top row of
- pixels. Following the rightmost pixel of the row there may be zero or
- more bytes of padding to guarantee that each row of pixel data has a
- certain alignment. Following the pad bytes, if any, is data for the
- leftmost pixel of the second row from the top, and so on. The last row
- has just as many pad bytes after it as the other rows.</para>
- <para>In V4L2 each format has an identifier which looks like
- <constant>PIX_FMT_XXX</constant>, defined in the <link
- linkend="videodev">videodev2.h</link> header file. These identifiers
- represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link>
- which are also listed below, however they are not the same as those
- used in the Windows world.</para>
- <para>For some formats, data is stored in separate, discontiguous
- memory buffers. Those formats are identified by a separate set of FourCC codes
- and are referred to as "multi-planar formats". For example, a YUV422 frame is
- normally stored in one memory buffer, but it can also be placed in two or three
- separate buffers, with Y component in one buffer and CbCr components in another
- in the 2-planar version or with each component in its own buffer in the
- 3-planar case. Those sub-buffers are referred to as "planes".</para>
- </section>
- <section id="colorspaces">
- <title>Colorspaces</title>
- <para>'Color' is a very complex concept and depends on physics, chemistry and
- biology. Just because you have three numbers that describe the 'red', 'green'
- and 'blue' components of the color of a pixel does not mean that you can accurately
- display that color. A colorspace defines what it actually <emphasis>means</emphasis>
- to have an RGB value of e.g. (255, 0, 0). That is, which color should be
- reproduced on the screen in a perfectly calibrated environment.</para>
- <para>In order to do that we first need to have a good definition of
- color, i.e. some way to uniquely and unambiguously define a color so that someone
- else can reproduce it. Human color vision is trichromatic since the human eye has
- color receptors that are sensitive to three different wavelengths of light. Hence
- the need to use three numbers to describe color. Be glad you are not a mantis shrimp
- as those are sensitive to 12 different wavelengths, so instead of RGB we would be
- using the ABCDEFGHIJKL colorspace...</para>
- <para>Color exists only in the eye and brain and is the result of how strongly
- color receptors are stimulated. This is based on the Spectral
- Power Distribution (SPD) which is a graph showing the intensity (radiant power)
- of the light at wavelengths covering the visible spectrum as it enters the eye.
- The science of colorimetry is about the relationship between the SPD and color as
- perceived by the human brain.</para>
- <para>Since the human eye has only three color receptors it is perfectly
- possible that different SPDs will result in the same stimulation of those receptors
- and are perceived as the same color, even though the SPD of the light is
- different.</para>
- <para>In the 1920s experiments were devised to determine the relationship
- between SPDs and the perceived color and that resulted in the CIE 1931 standard
- that defines spectral weighting functions that model the perception of color.
- Specifically that standard defines functions that can take an SPD and calculate
- the stimulus for each color receptor. After some further mathematical transforms
- these stimuli are known as the <emphasis>CIE XYZ tristimulus</emphasis> values
- and these X, Y and Z values describe a color as perceived by a human unambiguously.
- These X, Y and Z values are all in the range [0…1].</para>
- <para>The Y value in the CIE XYZ colorspace corresponds to luminance. Often
- the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace:</para>
- <para>x = X / (X + Y + Z)</para>
- <para>y = Y / (X + Y + Z)</para>
- <para>The x and y values are the chromaticity coordinates and can be used to
- define a color without the luminance component Y. It is very confusing to
- have such similar names for these colorspaces. Just be aware that if colors
- are specified with lower case 'x' and 'y', then the CIE xyY colorspace is
- used. Upper case 'X' and 'Y' refer to the CIE XYZ colorspace. Also, y has nothing
- to do with luminance. Together x and y specify a color, and Y the luminance.
- That is really all you need to remember from a practical point of view. At
- the end of this section you will find reading resources that go into much more
- detail if you are interested.
- </para>
- <para>A monitor or TV will reproduce colors by emitting light at three
- different wavelengths, the combination of which will stimulate the color receptors
- in the eye and thus cause the perception of color. Historically these wavelengths
- were defined by the red, green and blue phosphors used in the displays. These
- <emphasis>color primaries</emphasis> are part of what defines a colorspace.</para>
- <para>Different display devices will have different primaries and some
- primaries are more suitable for some display technologies than others. This has
- resulted in a variety of colorspaces that are used for different display
- technologies or uses. To define a colorspace you need to define the three
- color primaries (these are typically defined as x, y chromaticity coordinates
- from the CIE xyY colorspace) but also the white reference: that is the color obtained
- when all three primaries are at maximum power. This determines the relative power
- or energy of the primaries. This is usually chosen to be close to daylight which has
- been defined as the CIE D65 Illuminant.</para>
- <para>To recapitulate: the CIE XYZ colorspace uniquely identifies colors.
- Other colorspaces are defined by three chromaticity coordinates defined in the
- CIE xyY colorspace. Based on those a 3x3 matrix can be constructed that
- transforms CIE XYZ colors to colors in the new colorspace.
- </para>
- <para>Both the CIE XYZ and the RGB colorspace that are derived from the
- specific chromaticity primaries are linear colorspaces. But neither the eye,
- nor display technology is linear. Doubling the values of all components in
- the linear colorspace will not be perceived as twice the intensity of the color.
- So each colorspace also defines a transfer function that takes a linear color
- component value and transforms it to the non-linear component value, which is a
- closer match to the non-linear performance of both the eye and displays. Linear
- component values are denoted RGB, non-linear are denoted as R'G'B'. In general
- colors used in graphics are all R'G'B', except in openGL which uses linear RGB.
- Special care should be taken when dealing with openGL to provide linear RGB colors
- or to use the built-in openGL support to apply the inverse transfer function.</para>
- <para>The final piece that defines a colorspace is a function that
- transforms non-linear R'G'B' to non-linear Y'CbCr. This function is determined
- by the so-called luma coefficients. There may be multiple possible Y'CbCr
- encodings allowed for the same colorspace. Many encodings of color
- prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the human
- eye is more sensitive to differences in luminance than in color this encoding
- allows one to reduce the amount of color information compared to the luma
- data. Note that the luma (Y') is unrelated to the Y in the CIE XYZ colorspace.
- Also note that Y'CbCr is often called YCbCr or YUV even though these are
- strictly speaking wrong.</para>
- <para>Sometimes people confuse Y'CbCr as being a colorspace. This is not
- correct, it is just an encoding of an R'G'B' color into luma and chroma
- values. The underlying colorspace that is associated with the R'G'B' color
- is also associated with the Y'CbCr color.</para>
- <para>The final step is how the RGB, R'G'B' or Y'CbCr values are
- quantized. The CIE XYZ colorspace where X, Y and Z are in the range
- [0…1] describes all colors that humans can perceive, but the transform to
- another colorspace will produce colors that are outside the [0…1] range.
- Once clamped to the [0…1] range those colors can no longer be reproduced
- in that colorspace. This clamping is what reduces the extent or gamut of the
- colorspace. How the range of [0…1] is translated to integer values in the
- range of [0…255] (or higher, depending on the color depth) is called the
- quantization. This is <emphasis>not</emphasis> part of the colorspace
- definition. In practice RGB or R'G'B' values are full range, i.e. they
- use the full [0…255] range. Y'CbCr values on the other hand are limited
- range with Y' using [16…235] and Cb and Cr using [16…240].</para>
- <para>Unfortunately, in some cases limited range RGB is also used
- where the components use the range [16…235]. And full range Y'CbCr also exists
- using the [0…255] range.</para>
- <para>In order to correctly interpret a color you need to know the
- quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr encoding
- and the colorspace.
- From that information you can calculate the corresponding CIE XYZ color
- and map that again to whatever colorspace your display device uses.</para>
- <para>The colorspace definition itself consists of the three
- chromaticity primaries, the white reference chromaticity, a transfer
- function and the luma coefficients needed to transform R'G'B' to Y'CbCr. While
- some colorspace standards correctly define all four, quite often the colorspace
- standard only defines some, and you have to rely on other standards for
- the missing pieces. The fact that colorspaces are often a mix of different
- standards also led to very confusing naming conventions where the name of
- a standard was used to name a colorspace when in fact that standard was
- part of various other colorspaces as well.</para>
- <para>If you want to read more about colors and colorspaces, then the
- following resources are useful: <xref linkend="poynton" /> is a good practical
- book for video engineers, <xref linkend="colimg" /> has a much broader scope and
- describes many more aspects of color (physics, chemistry, biology, etc.).
- The <ulink url="http://www.brucelindbloom.com">http://www.brucelindbloom.com</ulink>
- website is an excellent resource, especially with respect to the mathematics behind
- colorspace conversions. The wikipedia <ulink url="http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space">CIE 1931 colorspace</ulink> article
- is also very useful.</para>
- </section>
- <section>
- <title>Defining Colorspaces in V4L2</title>
- <para>In V4L2 colorspaces are defined by four values. The first is the colorspace
- identifier (&v4l2-colorspace;) which defines the chromaticities, the default transfer
- function, the default Y'CbCr encoding and the default quantization method. The second
- is the transfer function identifier (&v4l2-xfer-func;) to specify non-standard
- transfer functions. The third is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;)
- to specify non-standard Y'CbCr encodings and the fourth is the quantization identifier
- (&v4l2-quantization;) to specify non-standard quantization methods. Most of the time
- only the colorspace field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to
- be filled in. Note that the default R'G'B' quantization is full range for all
- colorspaces except for BT.2020 which uses limited range R'G'B' quantization.</para>
- <table pgwide="1" frame="none" id="v4l2-colorspace">
- <title>V4L2 Colorspaces</title>
- <tgroup cols="2" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_COLORSPACE_DEFAULT</constant></entry>
- <entry>The default colorspace. This can be used by applications to let the
- driver fill in the colorspace.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry>
- <entry>See <xref linkend="col-smpte-170m" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_REC709</constant></entry>
- <entry>See <xref linkend="col-rec709" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry>
- <entry>See <xref linkend="col-srgb" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_ADOBERGB</constant></entry>
- <entry>See <xref linkend="col-adobergb" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_BT2020</constant></entry>
- <entry>See <xref linkend="col-bt2020" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_DCI_P3</constant></entry>
- <entry>See <xref linkend="col-dcip3" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry>
- <entry>See <xref linkend="col-smpte-240m" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry>
- <entry>See <xref linkend="col-sysm" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry>
- <entry>See <xref linkend="col-sysbg" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry>
- <entry>See <xref linkend="col-jpeg" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_RAW</constant></entry>
- <entry>The raw colorspace. This is used for raw image capture where
- the image is minimally processed and is using the internal colorspace
- of the device. The software that processes an image using this
- 'colorspace' will have to know the internals of the capture device.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table pgwide="1" frame="none" id="v4l2-xfer-func">
- <title>V4L2 Transfer Function</title>
- <tgroup cols="2" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_XFER_FUNC_DEFAULT</constant></entry>
- <entry>Use the default transfer function as defined by the colorspace.</entry>
- </row>
- <row>
- <entry><constant>V4L2_XFER_FUNC_709</constant></entry>
- <entry>Use the Rec. 709 transfer function.</entry>
- </row>
- <row>
- <entry><constant>V4L2_XFER_FUNC_SRGB</constant></entry>
- <entry>Use the sRGB transfer function.</entry>
- </row>
- <row>
- <entry><constant>V4L2_XFER_FUNC_ADOBERGB</constant></entry>
- <entry>Use the AdobeRGB transfer function.</entry>
- </row>
- <row>
- <entry><constant>V4L2_XFER_FUNC_SMPTE240M</constant></entry>
- <entry>Use the SMPTE 240M transfer function.</entry>
- </row>
- <row>
- <entry><constant>V4L2_XFER_FUNC_NONE</constant></entry>
- <entry>Do not use a transfer function (i.e. use linear RGB values).</entry>
- </row>
- <row>
- <entry><constant>V4L2_XFER_FUNC_DCI_P3</constant></entry>
- <entry>Use the DCI-P3 transfer function.</entry>
- </row>
- <row>
- <entry><constant>V4L2_XFER_FUNC_SMPTE2084</constant></entry>
- <entry>Use the SMPTE 2084 transfer function.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table pgwide="1" frame="none" id="v4l2-ycbcr-encoding">
- <title>V4L2 Y'CbCr Encodings</title>
- <tgroup cols="2" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_YCBCR_ENC_DEFAULT</constant></entry>
- <entry>Use the default Y'CbCr encoding as defined by the colorspace.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_601</constant></entry>
- <entry>Use the BT.601 Y'CbCr encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_709</constant></entry>
- <entry>Use the Rec. 709 Y'CbCr encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_XV601</constant></entry>
- <entry>Use the extended gamut xvYCC BT.601 encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_XV709</constant></entry>
- <entry>Use the extended gamut xvYCC Rec. 709 encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_SYCC</constant></entry>
- <entry>Use the extended gamut sYCC encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_BT2020</constant></entry>
- <entry>Use the default non-constant luminance BT.2020 Y'CbCr encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant></entry>
- <entry>Use the constant luminance BT.2020 Yc'CbcCrc encoding.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table pgwide="1" frame="none" id="v4l2-quantization">
- <title>V4L2 Quantization Methods</title>
- <tgroup cols="2" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_QUANTIZATION_DEFAULT</constant></entry>
- <entry>Use the default quantization encoding as defined by the colorspace.
- This is always full range for R'G'B' (except for the BT.2020 colorspace) and usually
- limited range for Y'CbCr.</entry>
- </row>
- <row>
- <entry><constant>V4L2_QUANTIZATION_FULL_RANGE</constant></entry>
- <entry>Use the full range quantization encoding. I.e. the range [0…1]
- is mapped to [0…255] (with possible clipping to [1…254] to avoid the
- 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to [0…255]
- (with possible clipping to [1…254] to avoid the 0x00 and 0xff values).</entry>
- </row>
- <row>
- <entry><constant>V4L2_QUANTIZATION_LIM_RANGE</constant></entry>
- <entry>Use the limited range quantization encoding. I.e. the range [0…1]
- is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to [16…240].
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>Detailed Colorspace Descriptions</title>
- <section id="col-smpte-170m">
- <title>Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title>
- <para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV
- in general. The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>.
- The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
- The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and
- the white reference are:</para>
- <table frame="none">
- <title>SMPTE 170M Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.630</entry>
- <entry>0.340</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.310</entry>
- <entry>0.595</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.155</entry>
- <entry>0.070</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The red, green and blue chromaticities are also often referred to
- as the SMPTE C set, so this colorspace is sometimes called SMPTE C as well.</para>
- <variablelist>
- <varlistentry>
- <term>The transfer function defined for SMPTE 170M is the same as the
- one defined in Rec. 709.</term>
- <listitem>
- <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para>
- <para>L' = 4.5L for -0.018 < L < 0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para>
- <para>L = L' / 4.5 for -0.081 < L' < 0.081</para>
- <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with
- the following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term>
- <listitem>
- <para>Y' = 0.299R' + 0.587G' + 0.114B'</para>
- <para>Cb = -0.169R' - 0.331G' + 0.5B'</para>
- <para>Cr = 0.5R' - 0.419G' - 0.081B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are
- clamped to the range [-0.5…0.5]. This conversion to Y'CbCr is identical to the one
- defined in the <xref linkend="itu601" /> standard and this colorspace is sometimes called BT.601 as well, even
- though BT.601 does not mention any color primaries.</para>
- <para>The default quantization is limited range, but full range is possible although
- rarely seen.</para>
- </section>
- <section id="col-rec709">
- <title>Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title>
- <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general.
- The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. The default
- Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is
- limited range. The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>Rec. 709 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.640</entry>
- <entry>0.330</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.300</entry>
- <entry>0.600</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.150</entry>
- <entry>0.060</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The full name of this standard is Rec. ITU-R BT.709-5.</para>
- <variablelist>
- <varlistentry>
- <term>Transfer function. Normally L is in the range [0…1], but for the extended
- gamut xvYCC encoding values outside that range are allowed.</term>
- <listitem>
- <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para>
- <para>L' = 4.5L for -0.018 < L < 0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para>
- <para>L = L' / 4.5 for -0.081 < L' < 0.081</para>
- <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following
- <constant>V4L2_YCBCR_ENC_709</constant> encoding:</term>
- <listitem>
- <para>Y' = 0.2126R' + 0.7152G' + 0.0722B'</para>
- <para>Cb = -0.1146R' - 0.3854G' + 0.5B'</para>
- <para>Cr = 0.5R' - 0.4542G' - 0.0458B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are
- clamped to the range [-0.5…0.5].</para>
- <para>The default quantization is limited range, but full range is possible although
- rarely seen.</para>
- <para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default
- for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which
- case the BT.601 Y'CbCr encoding is used.</para>
- <para>Two additional extended gamut Y'CbCr encodings are also possible with this colorspace:</para>
- <variablelist>
- <varlistentry>
- <term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />)
- is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range
- [0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term>
- <listitem>
- <para>Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256)</para>
- <para>Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B')</para>
- <para>Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B')</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar
- to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range
- [0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term>
- <listitem>
- <para>Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256)</para>
- <para>Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B')</para>
- <para>Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B')</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped
- to the range [-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be used by
- selecting <constant>V4L2_YCBCR_ENC_XV709</constant> or <constant>V4L2_YCBCR_ENC_XV601</constant>.
- The xvYCC encodings always use full range quantization.</para>
- </section>
- <section id="col-srgb">
- <title>Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title>
- <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams
- and computer graphics. The default transfer function is <constant>V4L2_XFER_FUNC_SRGB</constant>.
- The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr
- quantization is full range. The chromaticities of the primary colors and the white
- reference are:</para>
- <table frame="none">
- <title>sRGB Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.640</entry>
- <entry>0.330</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.300</entry>
- <entry>0.600</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.150</entry>
- <entry>0.060</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>These chromaticities are identical to the Rec. 709 colorspace.</para>
- <variablelist>
- <varlistentry>
- <term>Transfer function. Note that negative values for L are only used by the Y'CbCr conversion.</term>
- <listitem>
- <para>L' = -1.055(-L)<superscript>1/2.4</superscript> + 0.055 for L < -0.0031308</para>
- <para>L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308</para>
- <para>L' = 1.055L<superscript>1/2.4</superscript> - 0.055 for 0.0031308 < L ≤ 1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = -((-L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' < -0.04045</para>
- <para>L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045</para>
- <para>L = ((L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' > 0.04045</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following
- <constant>V4L2_YCBCR_ENC_SYCC</constant> encoding as defined by <xref linkend="sycc" />:</term>
- <listitem>
- <para>Y' = 0.2990R' + 0.5870G' + 0.1140B'</para>
- <para>Cb = -0.1687R' - 0.3313G' + 0.5B'</para>
- <para>Cr = 0.5R' - 0.4187G' - 0.0813B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped
- to the range [-0.5…0.5]. The <constant>V4L2_YCBCR_ENC_SYCC</constant> quantization is always
- full range. Although this Y'CbCr encoding looks very similar to the <constant>V4L2_YCBCR_ENC_XV601</constant>
- encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and offsets the Y'CbCr
- values before quantization, but this encoding does not do that.</para>
- </section>
- <section id="col-adobergb">
- <title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title>
- <para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics
- that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard.
- The default transfer function is <constant>V4L2_XFER_FUNC_ADOBERGB</constant>.
- The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr
- quantization is limited range. The chromaticities of the primary colors and the white reference
- are:</para>
- <table frame="none">
- <title>Adobe RGB Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.6400</entry>
- <entry>0.3300</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.2100</entry>
- <entry>0.7100</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.1500</entry>
- <entry>0.0600</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <variablelist>
- <varlistentry>
- <term>Transfer function:</term>
- <listitem>
- <para>L' = L<superscript>1/2.19921875</superscript></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L'<superscript>2.19921875</superscript></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
- following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term>
- <listitem>
- <para>Y' = 0.299R' + 0.587G' + 0.114B'</para>
- <para>Cb = -0.169R' - 0.331G' + 0.5B'</para>
- <para>Cr = 0.5R' - 0.419G' - 0.081B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are
- clamped to the range [-0.5…0.5]. This transform is identical to one defined in
- SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para>
- </section>
- <section id="col-bt2020">
- <title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title>
- <para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition
- television (UHDTV). The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>.
- The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>.
- The default R'G'B' quantization is limited range (!), and so is the default Y'CbCr quantization.
- The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>BT.2020 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.708</entry>
- <entry>0.292</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.170</entry>
- <entry>0.797</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.131</entry>
- <entry>0.046</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <variablelist>
- <varlistentry>
- <term>Transfer function (same as Rec. 709):</term>
- <listitem>
- <para>L' = 4.5L for 0 ≤ L < 0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L' / 4.5 for L' < 0.081</para>
- <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
- following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term>
- <listitem>
- <para>Y' = 0.2627R' + 0.6780G' + 0.0593B'</para>
- <para>Cb = -0.1396R' - 0.3604G' + 0.5B'</para>
- <para>Cr = 0.5R' - 0.4598G' - 0.0402B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are
- clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para>
- <para>There is also an alternate constant luminance R'G'B' to Yc'CbcCrc
- (<constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant>) encoding:</para>
- <variablelist>
- <varlistentry>
- <term>Luma:</term>
- <listitem>
- <para>Yc' = (0.2627R + 0.6780G + 0.0593B)'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>B' - Yc' ≤ 0:</term>
- <listitem>
- <para>Cbc = (B' - Yc') / 1.9404</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>B' - Yc' > 0:</term>
- <listitem>
- <para>Cbc = (B' - Yc') / 1.5816</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>R' - Yc' ≤ 0:</term>
- <listitem>
- <para>Crc = (R' - Y') / 1.7184</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>R' - Yc' > 0:</term>
- <listitem>
- <para>Crc = (R' - Y') / 0.9936</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Yc' is clamped to the range [0…1] and Cbc and Crc are
- clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para>
- </section>
- <section id="col-dcip3">
- <title>Colorspace DCI-P3 (<constant>V4L2_COLORSPACE_DCI_P3</constant>)</title>
- <para>The <xref linkend="smpte431" /> standard defines the colorspace used by cinema
- projectors that use the DCI-P3 colorspace.
- The default transfer function is <constant>V4L2_XFER_FUNC_DCI_P3</constant>.
- The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. Note that this
- colorspace does not specify a Y'CbCr encoding since it is not meant to be encoded
- to Y'CbCr. So this default Y'CbCr encoding was picked because it is the HDTV
- encoding. The default Y'CbCr quantization is limited range. The chromaticities of
- the primary colors and the white reference are:</para>
- <table frame="none">
- <title>DCI-P3 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.6800</entry>
- <entry>0.3200</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.2650</entry>
- <entry>0.6900</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.1500</entry>
- <entry>0.0600</entry>
- </row>
- <row>
- <entry>White Reference</entry>
- <entry>0.3140</entry>
- <entry>0.3510</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <variablelist>
- <varlistentry>
- <term>Transfer function:</term>
- <listitem>
- <para>L' = L<superscript>1/2.6</superscript></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L'<superscript>2.6</superscript></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.</para>
- </section>
- <section id="col-smpte-240m">
- <title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title>
- <para>The <xref linkend="smpte240m" /> standard was an interim standard used during
- the early days of HDTV (1988-1998). It has been superseded by Rec. 709.
- The default transfer function is <constant>V4L2_XFER_FUNC_SMPTE240M</constant>.
- The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>.
- The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the
- white reference are:</para>
- <table frame="none">
- <title>SMPTE 240M Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.630</entry>
- <entry>0.340</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.310</entry>
- <entry>0.595</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.155</entry>
- <entry>0.070</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>These chromaticities are identical to the SMPTE 170M colorspace.</para>
- <variablelist>
- <varlistentry>
- <term>Transfer function:</term>
- <listitem>
- <para>L' = 4L for 0 ≤ L < 0.0228</para>
- <para>L' = 1.1115L<superscript>0.45</superscript> - 0.1115 for 0.0228 ≤ L ≤ 1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L' / 4 for 0 ≤ L' < 0.0913</para>
- <para>L = ((L' + 0.1115) / 1.1115)<superscript>1/0.45</superscript> for L' ≥ 0.0913</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
- following <constant>V4L2_YCBCR_ENC_SMPTE240M</constant> encoding:</term>
- <listitem>
- <para>Y' = 0.2122R' + 0.7013G' + 0.0865B'</para>
- <para>Cb = -0.1161R' - 0.3839G' + 0.5B'</para>
- <para>Cr = 0.5R' - 0.4451G' - 0.0549B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Yc' is clamped to the range [0…1] and Cbc and Crc are
- clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para>
- </section>
- <section id="col-sysm">
- <title>Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title>
- <para>This standard defines the colorspace used by NTSC in 1953. In practice this
- colorspace is obsolete and SMPTE 170M should be used instead.
- The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>.
- The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
- The default Y'CbCr quantization is limited range.
- The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>NTSC 1953 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.67</entry>
- <entry>0.33</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.21</entry>
- <entry>0.71</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.14</entry>
- <entry>0.08</entry>
- </row>
- <row>
- <entry>White Reference (C)</entry>
- <entry>0.310</entry>
- <entry>0.316</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>Note that this colorspace uses Illuminant C instead of D65 as the
- white reference. To correctly convert an image in this colorspace to another
- that uses D65 you need to apply a chromatic adaptation algorithm such as the
- Bradford method.</para>
- <variablelist>
- <varlistentry>
- <term>The transfer function was never properly defined for NTSC 1953. The
- Rec. 709 transfer function is recommended in the literature:</term>
- <listitem>
- <para>L' = 4.5L for 0 ≤ L < 0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L' / 4.5 for L' < 0.081</para>
- <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
- following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term>
- <listitem>
- <para>Y' = 0.299R' + 0.587G' + 0.114B'</para>
- <para>Cb = -0.169R' - 0.331G' + 0.5B'</para>
- <para>Cr = 0.5R' - 0.419G' - 0.081B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are
- clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.
- This transform is identical to one defined in SMPTE 170M/BT.601.</para>
- </section>
- <section id="col-sysbg">
- <title>Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title>
- <para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this
- colorspace is obsolete and SMPTE 170M should be used instead.
- The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>.
- The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
- The default Y'CbCr quantization is limited range.
- The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>EBU Tech. 3213 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.64</entry>
- <entry>0.33</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.29</entry>
- <entry>0.60</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.15</entry>
- <entry>0.06</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <variablelist>
- <varlistentry>
- <term>The transfer function was never properly defined for this colorspace.
- The Rec. 709 transfer function is recommended in the literature:</term>
- <listitem>
- <para>L' = 4.5L for 0 ≤ L < 0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L' / 4.5 for L' < 0.081</para>
- <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
- following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term>
- <listitem>
- <para>Y' = 0.299R' + 0.587G' + 0.114B'</para>
- <para>Cb = -0.169R' - 0.331G' + 0.5B'</para>
- <para>Cr = 0.5R' - 0.419G' - 0.081B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are
- clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.
- This transform is identical to one defined in SMPTE 170M/BT.601.</para>
- </section>
- <section id="col-jpeg">
- <title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title>
- <para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities
- of the primary colors and the white reference are identical to sRGB. The transfer
- function use is <constant>V4L2_XFER_FUNC_SRGB</constant>. The Y'CbCr encoding is
- <constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where
- Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and
- then clipped to [-128…127].</para>
- <para>Note that the JPEG standard does not actually store colorspace information.
- So if something other than sRGB is used, then the driver will have to set that information
- explicitly. Effectively <constant>V4L2_COLORSPACE_JPEG</constant> can be considered to be
- an abbreviation for <constant>V4L2_COLORSPACE_SRGB</constant>, <constant>V4L2_YCBCR_ENC_601</constant>
- and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para>
- </section>
- </section>
- <section>
- <title>Detailed Transfer Function Descriptions</title>
- <section id="xf-smpte-2084">
- <title>Transfer Function SMPTE 2084 (<constant>V4L2_XFER_FUNC_SMPTE2084</constant>)</title>
- <para>The <xref linkend="smpte2084" /> standard defines the transfer function used by
- High Dynamic Range content.</para>
- <variablelist>
- <varlistentry>
- <term>Constants:</term>
- <listitem>
- <para>m1 = (2610 / 4096) / 4</para>
- <para>m2 = (2523 / 4096) * 128</para>
- <para>c1 = 3424 / 4096</para>
- <para>c2 = (2413 / 4096) * 32</para>
- <para>c3 = (2392 / 4096) * 32</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Transfer function:</term>
- <listitem>
- <para>L' = ((c1 + c2 * L<superscript>m1</superscript>) / (1 + c3 * L<superscript>m1</superscript>))<superscript>m2</superscript></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = (max(L'<superscript>1/m2</superscript> - c1, 0) / (c2 - c3 * L'<superscript>1/m2</superscript>))<superscript>1/m1</superscript></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- </section>
- <section id="pixfmt-indexed">
- <title>Indexed Format</title>
- <para>In this format each pixel is represented by an 8 bit index
- into a 256 entry ARGB palette. It is intended for <link
- linkend="osd">Video Output Overlays</link> only. There are no ioctls to
- access the palette, this must be done with ioctls of the Linux framebuffer API.</para>
- <table pgwide="0" frame="none">
- <title>Indexed Image Format</title>
- <tgroup cols="37" align="center">
- <colspec colname="id" align="left" />
- <colspec colname="fourcc" />
- <colspec colname="bit" />
- <colspec colnum="4" colname="b07" align="center" />
- <colspec colnum="5" colname="b06" align="center" />
- <colspec colnum="6" colname="b05" align="center" />
- <colspec colnum="7" colname="b04" align="center" />
- <colspec colnum="8" colname="b03" align="center" />
- <colspec colnum="9" colname="b02" align="center" />
- <colspec colnum="10" colname="b01" align="center" />
- <colspec colnum="11" colname="b00" align="center" />
- <spanspec namest="b07" nameend="b00" spanname="b0" />
- <spanspec namest="b17" nameend="b10" spanname="b1" />
- <spanspec namest="b27" nameend="b20" spanname="b2" />
- <spanspec namest="b37" nameend="b30" spanname="b3" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry> </entry>
- <entry spanname="b0">Byte 0</entry>
- </row>
- <row>
- <entry> </entry>
- <entry> </entry>
- <entry>Bit</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="V4L2-PIX-FMT-PAL8">
- <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry>
- <entry>'PAL8'</entry>
- <entry></entry>
- <entry>i<subscript>7</subscript></entry>
- <entry>i<subscript>6</subscript></entry>
- <entry>i<subscript>5</subscript></entry>
- <entry>i<subscript>4</subscript></entry>
- <entry>i<subscript>3</subscript></entry>
- <entry>i<subscript>2</subscript></entry>
- <entry>i<subscript>1</subscript></entry>
- <entry>i<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section id="pixfmt-rgb">
- <title>RGB Formats</title>
- &sub-packed-rgb;
- &sub-sbggr8;
- &sub-sgbrg8;
- &sub-sgrbg8;
- &sub-srggb8;
- &sub-sbggr16;
- &sub-srggb10;
- &sub-srggb10p;
- &sub-srggb10alaw8;
- &sub-srggb10dpcm8;
- &sub-srggb12;
- </section>
- <section id="yuv-formats">
- <title>YUV Formats</title>
- <para>YUV is the format native to TV broadcast and composite video
- signals. It separates the brightness information (Y) from the color
- information (U and V or Cb and Cr). The color information consists of
- red and blue <emphasis>color difference</emphasis> signals, this way
- the green component can be reconstructed by subtracting from the
- brightness component. See <xref linkend="colorspaces" /> for conversion
- examples. YUV was chosen because early television would only transmit
- brightness information. To add color in a way compatible with existing
- receivers a new signal carrier was added to transmit the color
- difference signals. Secondary in the YUV format the U and V components
- usually have lower resolution than the Y component. This is an analog
- video compression technique taking advantage of a property of the
- human visual system, being more sensitive to brightness
- information.</para>
- &sub-packed-yuv;
- &sub-grey;
- &sub-y10;
- &sub-y12;
- &sub-y10b;
- &sub-y16;
- &sub-y16-be;
- &sub-uv8;
- &sub-yuyv;
- &sub-uyvy;
- &sub-yvyu;
- &sub-vyuy;
- &sub-y41p;
- &sub-yuv420;
- &sub-yuv420m;
- &sub-yvu420m;
- &sub-yuv410;
- &sub-yuv422p;
- &sub-yuv411p;
- &sub-nv12;
- &sub-nv12m;
- &sub-nv12mt;
- &sub-nv16;
- &sub-nv16m;
- &sub-nv24;
- &sub-m420;
- </section>
- <section>
- <title>Compressed Formats</title>
- <table pgwide="1" frame="none" id="compressed-formats">
- <title>Compressed Image Formats</title>
- <tgroup cols="3" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="V4L2-PIX-FMT-JPEG">
- <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry>
- <entry>'JPEG'</entry>
- <entry>TBD. See also &VIDIOC-G-JPEGCOMP;,
- &VIDIOC-S-JPEGCOMP;.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MPEG">
- <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry>
- <entry>'MPEG'</entry>
- <entry>MPEG multiplexed stream. The actual format is determined by
- extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
- <xref linkend="mpeg-control-id" />.</entry>
- </row>
- <row id="V4L2-PIX-FMT-H264">
- <entry><constant>V4L2_PIX_FMT_H264</constant></entry>
- <entry>'H264'</entry>
- <entry>H264 video elementary stream with start codes.</entry>
- </row>
- <row id="V4L2-PIX-FMT-H264-NO-SC">
- <entry><constant>V4L2_PIX_FMT_H264_NO_SC</constant></entry>
- <entry>'AVC1'</entry>
- <entry>H264 video elementary stream without start codes.</entry>
- </row>
- <row id="V4L2-PIX-FMT-H264-MVC">
- <entry><constant>V4L2_PIX_FMT_H264_MVC</constant></entry>
- <entry>'M264'</entry>
- <entry>H264 MVC video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-H263">
- <entry><constant>V4L2_PIX_FMT_H263</constant></entry>
- <entry>'H263'</entry>
- <entry>H263 video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MPEG1">
- <entry><constant>V4L2_PIX_FMT_MPEG1</constant></entry>
- <entry>'MPG1'</entry>
- <entry>MPEG1 video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MPEG2">
- <entry><constant>V4L2_PIX_FMT_MPEG2</constant></entry>
- <entry>'MPG2'</entry>
- <entry>MPEG2 video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MPEG4">
- <entry><constant>V4L2_PIX_FMT_MPEG4</constant></entry>
- <entry>'MPG4'</entry>
- <entry>MPEG4 video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-XVID">
- <entry><constant>V4L2_PIX_FMT_XVID</constant></entry>
- <entry>'XVID'</entry>
- <entry>Xvid video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-VC1-ANNEX-G">
- <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_G</constant></entry>
- <entry>'VC1G'</entry>
- <entry>VC1, SMPTE 421M Annex G compliant stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-VC1-ANNEX-L">
- <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_L</constant></entry>
- <entry>'VC1L'</entry>
- <entry>VC1, SMPTE 421M Annex L compliant stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-VP8">
- <entry><constant>V4L2_PIX_FMT_VP8</constant></entry>
- <entry>'VP80'</entry>
- <entry>VP8 video elementary stream.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section id="sdr-formats">
- <title>SDR Formats</title>
- <para>These formats are used for <link linkend="sdr">SDR</link>
- interface only.</para>
- &sub-sdr-cu08;
- &sub-sdr-cu16le;
- &sub-sdr-cs08;
- &sub-sdr-cs14le;
- &sub-sdr-ru12le;
- </section>
- <section id="pixfmt-reserved">
- <title>Reserved Format Identifiers</title>
- <para>These formats are not defined by this specification, they
- are just listed for reference and to avoid naming conflicts. If you
- want to register your own format, send an e-mail to the linux-media mailing
- list &v4l-ml; for inclusion in the <filename>videodev2.h</filename>
- file. If you want to share your format with other developers add a
- link to your documentation and send a copy to the linux-media mailing list
- for inclusion in this section. If you think your format should be listed
- in a standard format section please make a proposal on the linux-media mailing
- list.</para>
- <table pgwide="1" frame="none" id="reserved-formats">
- <title>Reserved Image Formats</title>
- <tgroup cols="3" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="V4L2-PIX-FMT-DV">
- <entry><constant>V4L2_PIX_FMT_DV</constant></entry>
- <entry>'dvsd'</entry>
- <entry>unknown</entry>
- </row>
- <row id="V4L2-PIX-FMT-ET61X251">
- <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry>
- <entry>'E625'</entry>
- <entry>Compressed format of the ET61X251 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-HI240">
- <entry><constant>V4L2_PIX_FMT_HI240</constant></entry>
- <entry>'HI24'</entry>
- <entry><para>8 bit RGB format used by the BTTV driver.</para></entry>
- </row>
- <row id="V4L2-PIX-FMT-HM12">
- <entry><constant>V4L2_PIX_FMT_HM12</constant></entry>
- <entry>'HM12'</entry>
- <entry><para>YUV 4:2:0 format used by the
- IVTV driver, <ulink url="http://www.ivtvdriver.org/">
- http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the
- kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename>
- </para></entry>
- </row>
- <row id="V4L2-PIX-FMT-CPIA1">
- <entry><constant>V4L2_PIX_FMT_CPIA1</constant></entry>
- <entry>'CPIA'</entry>
- <entry>YUV format used by the gspca cpia1 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-JPGL">
- <entry><constant>V4L2_PIX_FMT_JPGL</constant></entry>
- <entry>'JPGL'</entry>
- <entry>JPEG-Light format (Pegasus Lossless JPEG)
- used in Divio webcams NW 80x.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SPCA501">
- <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry>
- <entry>'S501'</entry>
- <entry>YUYV per line used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SPCA505">
- <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry>
- <entry>'S505'</entry>
- <entry>YYUV per line used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SPCA508">
- <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry>
- <entry>'S508'</entry>
- <entry>YUVY per line used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SPCA561">
- <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry>
- <entry>'S561'</entry>
- <entry>Compressed GBRG Bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-PAC207">
- <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry>
- <entry>'P207'</entry>
- <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MR97310A">
- <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry>
- <entry>'M310'</entry>
- <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-JL2005BCD">
- <entry><constant>V4L2_PIX_FMT_JL2005BCD</constant></entry>
- <entry>'JL20'</entry>
- <entry>JPEG compressed RGGB Bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-OV511">
- <entry><constant>V4L2_PIX_FMT_OV511</constant></entry>
- <entry>'O511'</entry>
- <entry>OV511 JPEG format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-OV518">
- <entry><constant>V4L2_PIX_FMT_OV518</constant></entry>
- <entry>'O518'</entry>
- <entry>OV518 JPEG format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-PJPG">
- <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry>
- <entry>'PJPG'</entry>
- <entry>Pixart 73xx JPEG format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SE401">
- <entry><constant>V4L2_PIX_FMT_SE401</constant></entry>
- <entry>'S401'</entry>
- <entry>Compressed RGB format used by the gspca se401 driver</entry>
- </row>
- <row id="V4L2-PIX-FMT-SQ905C">
- <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry>
- <entry>'905C'</entry>
- <entry>Compressed RGGB bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MJPEG">
- <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry>
- <entry>'MJPG'</entry>
- <entry>Compressed format used by the Zoran driver</entry>
- </row>
- <row id="V4L2-PIX-FMT-PWC1">
- <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry>
- <entry>'PWC1'</entry>
- <entry>Compressed format of the PWC driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-PWC2">
- <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry>
- <entry>'PWC2'</entry>
- <entry>Compressed format of the PWC driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SN9C10X">
- <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry>
- <entry>'S910'</entry>
- <entry>Compressed format of the SN9C102 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SN9C20X-I420">
- <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry>
- <entry>'S920'</entry>
- <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SN9C2028">
- <entry><constant>V4L2_PIX_FMT_SN9C2028</constant></entry>
- <entry>'SONX'</entry>
- <entry>Compressed GBRG bayer format of the gspca sn9c2028 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-STV0680">
- <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry>
- <entry>'S680'</entry>
- <entry>Bayer format of the gspca stv0680 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-WNVA">
- <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry>
- <entry>'WNVA'</entry>
- <entry><para>Used by the Winnov Videum driver, <ulink
- url="http://www.thedirks.org/winnov/">
- http://www.thedirks.org/winnov/</ulink></para></entry>
- </row>
- <row id="V4L2-PIX-FMT-TM6000">
- <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry>
- <entry>'TM60'</entry>
- <entry><para>Used by Trident tm6000</para></entry>
- </row>
- <row id="V4L2-PIX-FMT-CIT-YYVYUY">
- <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry>
- <entry>'CITV'</entry>
- <entry><para>Used by xirlink CIT, found at IBM webcams.</para>
- <para>Uses one line of Y then 1 line of VYUY</para>
- </entry>
- </row>
- <row id="V4L2-PIX-FMT-KONICA420">
- <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry>
- <entry>'KONI'</entry>
- <entry><para>Used by Konica webcams.</para>
- <para>YUV420 planar in blocks of 256 pixels.</para>
- </entry>
- </row>
- <row id="V4L2-PIX-FMT-YYUV">
- <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry>
- <entry>'YYUV'</entry>
- <entry>unknown</entry>
- </row>
- <row id="V4L2-PIX-FMT-Y4">
- <entry><constant>V4L2_PIX_FMT_Y4</constant></entry>
- <entry>'Y04 '</entry>
- <entry>Old 4-bit greyscale format. Only the most significant 4 bits of each byte are used,
- the other bits are set to 0.</entry>
- </row>
- <row id="V4L2-PIX-FMT-Y6">
- <entry><constant>V4L2_PIX_FMT_Y6</constant></entry>
- <entry>'Y06 '</entry>
- <entry>Old 6-bit greyscale format. Only the most significant 6 bits of each byte are used,
- the other bits are set to 0.</entry>
- </row>
- <row id="V4L2-PIX-FMT-S5C-UYVY-JPG">
- <entry><constant>V4L2_PIX_FMT_S5C_UYVY_JPG</constant></entry>
- <entry>'S5CI'</entry>
- <entry>Two-planar format used by Samsung S5C73MX cameras. The
- first plane contains interleaved JPEG and UYVY image data, followed by meta data
- in form of an array of offsets to the UYVY data blocks. The actual pointer array
- follows immediately the interleaved JPEG/UYVY data, the number of entries in
- this array equals the height of the UYVY image. Each entry is a 4-byte unsigned
- integer in big endian order and it's an offset to a single pixel line of the
- UYVY image. The first plane can start either with JPEG or UYVY data chunk. The
- size of a single UYVY block equals the UYVY image's width multiplied by 2. The
- size of a JPEG chunk depends on the image and can vary with each line.
- <para>The second plane, at an offset of 4084 bytes, contains a 4-byte offset to
- the pointer array in the first plane. This offset is followed by a 4-byte value
- indicating size of the pointer array. All numbers in the second plane are also
- in big endian order. Remaining data in the second plane is undefined. The
- information in the second plane allows to easily find location of the pointer
- array, which can be different for each frame. The size of the pointer array is
- constant for given UYVY image height.</para>
- <para>In order to extract UYVY and JPEG frames an application can initially set
- a data pointer to the start of first plane and then add an offset from the first
- entry of the pointers table. Such a pointer indicates start of an UYVY image
- pixel line. Whole UYVY line can be copied to a separate buffer. These steps
- should be repeated for each line, i.e. the number of entries in the pointer
- array. Anything what's in between the UYVY lines is JPEG data and should be
- concatenated to form the JPEG stream. </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table frame="none" pgwide="1" id="format-flags">
- <title>Format Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_PIX_FMT_FLAG_PREMUL_ALPHA</constant></entry>
- <entry>0x00000001</entry>
- <entry>The color values are premultiplied by the alpha channel
- value. For example, if a light blue pixel with 50% transparency was described by
- RGBA values (128, 192, 255, 128), the same pixel described with premultiplied
- colors would be described by RGBA values (64, 96, 128, 128) </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
|