Video for Linux Two API Specification - V4L2 video for Linux

227 Pages·2006·1.7 MB·English

Video for Linux Two API Specification
Draft 0.12
Michael H Schimek
[email protected]
Bill Dirks
Hans Verkuil
VideoforLinuxTwoAPISpecification:Draft0.12
byMichaelHSchimek,BillDirks,andHansVerkuil
Copyright©1999,2000,2001,2002,2003,2004,2005,2006BillDirks,MichaelH.Schimek,HansVerkuil
Thisdocumentiscopyrighted©1999-2006byBillDirks,MichaelH.SchimekandHansVerkuil.
Permissionisgrantedtocopy,distributeand/ormodifythisdocumentunderthetermsoftheGNUFreeDocumentationLicense,Version1.1
oranylaterversionpublishedbytheFreeSoftwareFoundation;withnoInvariantSections,withnoFront-CoverTexts,andwithno
Back-CoverTexts.Acopyofthelicenseisincludedintheappendixentitled"GNUFreeDocumentationLicense".
Programmingexamplescanbeusedanddistributedwithoutrestrictions.
RevisionHistory
Revision0.122006-02-03Revisedby:mhs
Correctedthedescriptionofstructv4l2_captureparmandv4l2_outputparm.
Revision0.112006-01-27Revisedby:mhs
Improvedthedescriptionofstructv4l2_tuner.
Revision0.102006-01-10Revisedby:mhs
VIDIOC_G_INPUTandVIDIOC_S_PARMclarifications.
Revision0.9 2005-11-27Revisedby:mhs
Improvedthe525linenumberingdiagram.HansVerkuilandIrewrotetheslicedVBIsection.HealsocontributedaVIDIOC_LOG_STATUSpage.FixedVIDIOC_S_STDcallinthevideostandardselectionexample.Variousupdates.
Revision0.8 2004-10-04Revisedby:mhs
Somehowapieceofjunkslippedintothecaptureexample,removed.
Revision0.7 2004-09-19Revisedby:mhs
Fixedvideostandardselection,controlenumeration,downscalingandaspectexample.Addedreadanduserpointeri/otovideocaptureexample.
Revision0.6 2004-08-01Revisedby:mhs
v4l2_bufferchanges,addedvideocaptureexample,variouscorrections.
Revision0.5 2003-11-05Revisedby:mhs
Pixelformaterratum.
Revision0.4 2003-09-17Revisedby:mhs
CorrectedsourceandMakefiletogenerateaPDF.SGMLfixes.AddedlatestAPIchanges.Closedgapsinthehistorychapter.
Revision0.3 2003-02-05Revisedby:mhs
Anotherdraft,morecorrections.
Revision0.2 2003-01-15Revisedby:mhs
Seconddraft,withcorrectionspointedoutbyGerdKnorr.
Revision0.1 2002-12-01Revisedby:mhs
Firstdraft,basedondocumentationbyBillDirksanddiscussionsontheV4Lmailinglist.
Table of Contents
Introduction........................................................................................................................................ix
1.CommonAPIElements..................................................................................................................1
1.1.OpeningandClosingDevices..............................................................................................1
1.1.1.DeviceNaming........................................................................................................1
1.1.2.RelatedDevices.......................................................................................................2
1.1.3.MultipleOpens........................................................................................................2
1.1.4.SharedDataStreams................................................................................................3
1.1.5.Functions.................................................................................................................3
1.2.QueryingCapabilities..........................................................................................................3
1.3.ApplicationPriority..............................................................................................................3
1.4.VideoInputsandOutputs.....................................................................................................4
1.5.AudioInputsandOutputs....................................................................................................5
1.6.TunersandModulators.........................................................................................................6
1.6.1.Tuners......................................................................................................................6
1.6.2.Modulators...............................................................................................................6
1.6.3.RadioFrequency......................................................................................................7
1.6.4.SatelliteReceivers...................................................................................................7
1.7.VideoStandards...................................................................................................................7
1.8.Controls................................................................................................................................9
1.9.DataFormats......................................................................................................................13
1.9.1.DataFormatNegotiation.......................................................................................14
1.9.2.ImageFormatEnumeration...................................................................................14
1.10.CroppingandScaling.......................................................................................................15
1.11.StreamingParameters.......................................................................................................18
2.ImageFormats..............................................................................................................................21
2.1.StandardImageFormats....................................................................................................21
2.2.Colorspaces........................................................................................................................22
2.3.RGBFormats.....................................................................................................................25
2.4.YUVFormats.....................................................................................................................27
V4L2_PIX_FMT_GREY(’GREY’)...............................................................................27
V4L2_PIX_FMT_YUYV(’YUYV’)..............................................................................28
V4L2_PIX_FMT_UYVY(’UYVY’)..............................................................................29
V4L2_PIX_FMT_Y41P(’Y41P’)...................................................................................30
V4L2_PIX_FMT_YVU420(’YV12’),V4L2_PIX_FMT_YUV420(’YU12’)..............31
V4L2_PIX_FMT_YVU410(’YVU9’),V4L2_PIX_FMT_YUV410(’YUV9’)............32
V4L2_PIX_FMT_YUV422P(’422P’)............................................................................33
V4L2_PIX_FMT_YUV411P(’411P’)............................................................................34
V4L2_PIX_FMT_NV12(’NV12’),V4L2_PIX_FMT_NV21(’NV21’).......................35
2.5.CompressedFormats..........................................................................................................36
2.6.ReservedFormatIdentifiers...............................................................................................36
3.Input/Output.................................................................................................................................37
3.1.Read/Write.........................................................................................................................37
3.2.StreamingI/O(MemoryMapping)....................................................................................37
3.3.StreamingI/O(UserPointers)............................................................................................40
3.4.AsynchronousI/O..............................................................................................................41
3.5.Buffers................................................................................................................................41
3.5.1.Timecodes..............................................................................................................45
3.6.FieldOrder.........................................................................................................................46
iii
4.DeviceTypes..................................................................................................................................51
4.1.VideoCaptureInterface.....................................................................................................51
4.1.1.QueryingCapabilities............................................................................................51
4.1.2.SupplementalFunctions........................................................................................51
4.1.3.ImageFormatNegotiation.....................................................................................51
4.1.4.ReadingImages.....................................................................................................52
4.2.VideoOverlayInterface.....................................................................................................52
4.2.1.QueryingCapabilities............................................................................................52
4.2.2.SupplementalFunctions........................................................................................52
4.2.3.Setup......................................................................................................................52
4.2.4.OverlayWindow....................................................................................................53
4.2.5.EnablingOverlay...................................................................................................55
4.3.VideoOutputInterface.......................................................................................................55
4.3.1.QueryingCapabilities............................................................................................55
4.3.2.SupplementalFunctions........................................................................................55
4.3.3.ImageFormatNegotiation.....................................................................................56
4.3.4.WritingImages......................................................................................................56
4.4.CodecInterface..................................................................................................................56
4.5.EffectDevicesInterface.....................................................................................................56
4.6.RawVBIDataInterface.....................................................................................................57
4.6.1.QueryingCapabilities............................................................................................57
4.6.2.SupplementalFunctions........................................................................................57
4.6.3.RawVBIFormatNegotiation................................................................................57
4.6.4.ReadingandwritingVBIimages..........................................................................64
4.7.SlicedVBIDataInterface..................................................................................................64
4.7.1.QueryingCapabilities............................................................................................64
4.7.2.SupplementalFunctions........................................................................................65
4.7.3.SlicedVBIFormatNegotiation.............................................................................65
4.7.4.ReadingandwritingslicedVBIdata.....................................................................66
4.8.TeletextInterface................................................................................................................67
4.9.RadioInterface...................................................................................................................68
4.9.1.QueryingCapabilities............................................................................................68
4.9.2.SupplementalFunctions........................................................................................68
4.9.3.Programming.........................................................................................................68
4.10.RDSInterface...................................................................................................................68
I.FunctionReference.......................................................................................................................70
V4L2close().............................................................................................................................72
V4L2ioctl()...............................................................................................................................73
ioctlVIDIOC_CROPCAP.........................................................................................................75
ioctlVIDIOC_ENUMAUDIO..................................................................................................77
ioctlVIDIOC_ENUMAUDOUT..............................................................................................78
ioctlVIDIOC_ENUM_FMT.....................................................................................................79
ioctlVIDIOC_ENUMINPUT...................................................................................................81
ioctlVIDIOC_ENUMOUTPUT...............................................................................................84
ioctlVIDIOC_ENUMSTD.......................................................................................................86
ioctlVIDIOC_G_AUDIO,VIDIOC_S_AUDIO......................................................................90
ioctlVIDIOC_G_AUDOUT,VIDIOC_S_AUDOUT..............................................................92
ioctlVIDIOC_G_MPEGCOMP,VIDIOC_S_MPEGCOMP...................................................94
ioctlVIDIOC_G_CROP,VIDIOC_S_CROP...........................................................................95
ioctlVIDIOC_G_CTRL,VIDIOC_S_CTRL...........................................................................97
ioctlVIDIOC_G_FBUF,VIDIOC_S_FBUF............................................................................99
iv
ioctlVIDIOC_G_FMT,VIDIOC_S_FMT,VIDIOC_TRY_FMT..........................................102
ioctlVIDIOC_G_FREQUENCY,VIDIOC_S_FREQUENCY..............................................105
ioctlVIDIOC_G_INPUT,VIDIOC_S_INPUT......................................................................107
ioctlVIDIOC_G_JPEGCOMP,VIDIOC_S_JPEGCOMP.....................................................109
ioctlVIDIOC_G_MODULATOR,VIDIOC_S_MODULATOR...........................................111
ioctlVIDIOC_G_OUTPUT,VIDIOC_S_OUTPUT..............................................................114
ioctlVIDIOC_G_PARM,VIDIOC_S_PARM........................................................................116
ioctlVIDIOC_G_PRIORITY,VIDIOC_S_PRIORITY.........................................................120
ioctlVIDIOC_G_SLICED_VBI_CAP...................................................................................122
ioctlVIDIOC_G_STD,VIDIOC_S_STD..............................................................................124
ioctlVIDIOC_G_TUNER,VIDIOC_S_TUNER...................................................................125
ioctlVIDIOC_LOG_STATUS................................................................................................129
ioctlVIDIOC_OVERLAY......................................................................................................130
ioctlVIDIOC_QBUF,VIDIOC_DQBUF...............................................................................131
ioctlVIDIOC_QUERYBUF...................................................................................................133
ioctlVIDIOC_QUERYCAP...................................................................................................135
ioctlVIDIOC_QUERYCTRL,VIDIOC_QUERYMENU......................................................138
ioctlVIDIOC_QUERYSTD....................................................................................................141
ioctlVIDIOC_REQBUFS.......................................................................................................143
ioctlVIDIOC_STREAMON,VIDIOC_STREAMOFF.........................................................145
V4L2mmap()..........................................................................................................................147
V4L2munmap()......................................................................................................................149
V4L2open()............................................................................................................................150
V4L2poll().............................................................................................................................152
V4L2read().............................................................................................................................153
V4L2select()...........................................................................................................................155
V4L2write()...........................................................................................................................156
5.V4L2DriverProgramming........................................................................................................158
6.History.........................................................................................................................................159
6.1.DifferencesbetweenV4LandV4L2...............................................................................159
6.1.1.OpeningandClosingDevices.............................................................................159
6.1.2.QueryingCapabilities..........................................................................................159
6.1.3.VideoSources......................................................................................................161
6.1.4.Tuning..................................................................................................................161
6.1.5.ImageProperties..................................................................................................162
6.1.6.Audio...................................................................................................................163
6.1.7.FrameBufferOverlay..........................................................................................164
6.1.8.Cropping..............................................................................................................164
6.1.9.ReadingImages,MemoryMapping....................................................................165
6.1.9.1.Capturingusingthereadmethod............................................................165
6.1.9.2.Capturingusingmemorymapping..........................................................165
6.1.10.ReadingRawVBIData.....................................................................................166
6.1.11.Miscellaneous....................................................................................................167
6.2.HistoryoftheV4L2API..................................................................................................167
6.2.1.EarlyVersions......................................................................................................167
6.2.2.V4L2Version0.161999-01-31...........................................................................168
6.2.3.V4L2Version0.181999-03-16...........................................................................168
6.2.4.V4L2Version0.191999-06-05...........................................................................168
6.2.5.V4L2Version0.201999-09-10...........................................................................168
6.2.6.V4L2Version0.20incrementalchanges.............................................................170
6.2.7.V4L2Version0.202000-11-23...........................................................................171
v
6.2.8.V4L2Version0.202002-07-25...........................................................................171
6.2.9.V4L2inLinux2.5.46,2002-10...........................................................................171
6.2.10.V4L22003-06-19..............................................................................................175
6.2.11.V4L22003-11-05..............................................................................................175
6.2.12.V4L2inLinux2.6.6,2004-05-09.....................................................................176
6.2.13.V4L2inLinux2.6.8..........................................................................................176
6.2.14.V4L2specerratum2004-08-01.........................................................................176
6.2.15.V4L2inLinux2.6.14........................................................................................176
6.2.16.V4L2inLinux2.6.15........................................................................................177
6.2.17.V4L2specerratum2005-11-27.........................................................................177
6.2.18.V4L2specerratum2006-01-10.........................................................................177
6.2.19.V4L2specerratum2006-02-03.........................................................................177
6.3.RelationofV4L2tootherLinuxmultimediaAPIs.........................................................177
6.3.1.XVideoExtension...............................................................................................178
6.3.2.DigitalVideo.......................................................................................................178
6.3.3.AudioInterfaces..................................................................................................178
A.VideoForLinuxTwoHeaderFile............................................................................................179
B.VideoCaptureExample.............................................................................................................200
C.GNUFreeDocumentationLicense...........................................................................................212
C.1.0.PREAMBLE................................................................................................................212
C.2.1.APPLICABILITYANDDEFINITIONS....................................................................212
C.3.2.VERBATIMCOPYING..............................................................................................213
C.4.3.COPYINGINQUANTITY.........................................................................................213
C.5.4.MODIFICATIONS......................................................................................................214
C.6.5.COMBININGDOCUMENTS....................................................................................215
C.7.6.COLLECTIONSOFDOCUMENTS..........................................................................215
C.8.7.AGGREGATIONWITHINDEPENDENTWORKS.................................................216
C.9.8.TRANSLATION.........................................................................................................216
C.10.9.TERMINATION........................................................................................................216
C.11.10.FUTUREREVISIONSOFTHISLICENSE..........................................................216
C.12.Addendum.....................................................................................................................217
Bibliography....................................................................................................................................218
vi
List of Tables
1-1.ControlIDs..................................................................................................................................10
2-1.structv4l2_pix_format................................................................................................................21
2-2.enumv4l2_colorspace.................................................................................................................24
2-3.PackedRGBImageFormats.......................................................................................................25
2-4.ReservedImageFormats.............................................................................................................36
3-1.structv4l2_buffer........................................................................................................................42
3-2.enumv4l2_buf_type....................................................................................................................44
3-3.BufferFlags.................................................................................................................................44
3-4.enumv4l2_memory.....................................................................................................................45
3-5.structv4l2_timecode...................................................................................................................45
3-6.TimecodeTypes...........................................................................................................................46
3-7.TimecodeFlags...........................................................................................................................46
3-8.enumv4l2_field...........................................................................................................................47
4-1.structv4l2_window.....................................................................................................................54
4-2.structv4l2_clip2...........................................................................................................................54
4-3.structv4l2_rect............................................................................................................................55
4-4.structv4l2_vbi_format................................................................................................................58
4-5.RawVBIFormatFlags................................................................................................................59
4-6.structv4l2_sliced_vbi_format.....................................................................................................65
4-7.SlicedVBIservices.....................................................................................................................66
4-8.structv4l2_sliced_vbi_data.........................................................................................................66
1.structv4l2_cropcap.........................................................................................................................75
2.structv4l2_rect...............................................................................................................................76
1.structv4l2_fmtdesc.........................................................................................................................79
2.ImageFormatDescriptionFlags....................................................................................................80
1.structv4l2_input.............................................................................................................................81
2.InputTypes.....................................................................................................................................82
3.InputStatusFlags...........................................................................................................................82
1.structv4l2_output...........................................................................................................................84
2.OutputType....................................................................................................................................85
1.structv4l2_standard........................................................................................................................86
2.structv4l2_fract..............................................................................................................................87
3.typedefv4l2_std_id........................................................................................................................87
4.VideoStandards(basedon[ITU470>])..........................................................................................88
1.structv4l2_audio............................................................................................................................90
2.AudioCapabilityFlags...................................................................................................................91
3.AudioModes..................................................................................................................................91
1.structv4l2_audioout.......................................................................................................................92
1.structv4l2_mpeg_compression......................................................................................................94
1.structv4l2_crop..............................................................................................................................96
1.structv4l2_control..........................................................................................................................97
1.structv4l2_framebuffer..................................................................................................................99
2.FrameBufferCapabilityFlags.....................................................................................................100
3.FrameBufferFlags.......................................................................................................................101
1.structv4l2_format.........................................................................................................................103
1.structv4l2_frequency...................................................................................................................105
1.structv4l2_jpegcompression........................................................................................................109
2.JPEGMarkersFlags.....................................................................................................................110
1.structv4l2_modulator...................................................................................................................111
vii
2.ModulatorAudioTransmissionFlags..........................................................................................112
1.structv4l2_streamparm................................................................................................................116
2.structv4l2_captureparm...............................................................................................................117
3.structv4l2_outputparm.................................................................................................................117
4.StreamingParametersCapabilites................................................................................................118
5.CaptureParametersFlags.............................................................................................................118
1.enumv4l2_priority.......................................................................................................................120
1.structv4l2_sliced_vbi_cap...........................................................................................................122
2.SlicedVBIservices.......................................................................................................................123
1.structv4l2_tuner...........................................................................................................................125
2.enumv4l2_tuner_type..................................................................................................................126
3.TunerandModulatorCapabilityFlags.........................................................................................126
4.TunerAudioReceptionFlags.......................................................................................................127
5.TunerAudioModes......................................................................................................................127
6.TunerAudioMatrix......................................................................................................................128
1.structv4l2_capability....................................................................................................................135
2.DeviceCapabilitiesFlags.............................................................................................................136
1.structv4l2_queryctrl.....................................................................................................................138
2.structv4l2_querymenu.................................................................................................................139
3.enumv4l2_ctrl_type.....................................................................................................................139
4.ControlFlags................................................................................................................................140
1.structv4l2_requestbuffers.............................................................................................................143
6-1.V4LDeviceTypes,NamesandNumbers.................................................................................159
viii
Introduction
[todo]
IfyouhavequestionsorideasregardingtheAPI,pleasetrytheVideo4Linuxmailinglist:
https://listman.redhat.com/mailman/listinfo/video4linux-list
[e-mail]
(mailto:[email protected]).
ThelatestversionofthisdocumentandtheDocBookSGMLsourcesiscurrentlyhostedat
http://v4l2spec.bytesex.org,andhttp://linuxtv.org/downloads/video4linux/API/V4L2_API.
ix
Chapter 1. Common API Elements
ProgrammingaV4L2deviceconsistsofthesesteps:
• Openingthedevice
• Changingdeviceproperties,selectingavideoandaudioinput,videostandard,picturebrightness
a.o.
• Negotiatingadataformat
• Negotiatinganinput/outputmethod
• Theactualinput/outputloop
• Closingthedevice
Inpracticemoststepsareoptionalandcanbeexecutedoutoforder.ItdependsontheV4L2device
type,youcanreadaboutthedetailsinChapter4>.Inthischapterwewilldiscussthebasicconcepts
applicabletoalldevices.
1.1. Opening and Closing Devices
1.1.1. Device Naming
V4L2driversareimplementedaskernelmodules,loadedmanuallybythesystemadministratoror
automaticallywhenadeviceisfirstopened.Thedrivermodulesplugintothe"videodev"kernel
module.Itprovideshelperfunctionsandacommonapplicationinterfacespecifiedinthisdocument.
Eachdriverthusloadedregistersoneormoredevicenodeswithmajornumber81andaminor
numberbetween0and255.AssigningminornumberstoV4L2devicesisentirelyuptothesystem
administrator,thisisprimarilyintendedtosolveconflictsbetweendevices.1Themoduleoptionsto
selectminornumbersarenamedafterthedevicespecialfilewitha"_nr"suffix.Forexample
"video_nr"for/dev/videovideocapturedevices.Thenumberisanoffsettothebaseminor
numberassociatedwiththedevicetype.2Whenthedriversupportsmultipledevicesofthesame
typemorethanoneminornumbercanbeassigned,separatedbycommas:
> insmod mydriver.o video_nr=0,1 radio_nr=0,1
In/etc/modules.confthismaybewrittenas:
alias char-major-81-0 mydriver
alias char-major-81-1 mydriver
alias char-major-81-64 mydriver ˚>
options mydriver video_nr=0,1 radio_nr=0,1 ¸>
˚ Whenanapplicationattemptstoopenadevicespecialfilewithmajornumber81andminor
number0,1,or64,load"mydriver"(andthe"videodev"moduleitdependsupon).
¸ Registerthefirsttwovideocapturedeviceswithminornumber0and1(basenumberis0),the
firsttworadiodevicewithminornumber64and65(base64).
1