From 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 Mon Sep 17 00:00:00 2001 From: Linus Torvalds Date: Sat, 16 Apr 2005 15:20:36 -0700 Subject: Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip! --- Documentation/video4linux/API.html | 399 +++++++++++++++++++++++++++++++++++++ 1 file changed, 399 insertions(+) create mode 100644 Documentation/video4linux/API.html (limited to 'Documentation/video4linux/API.html') diff --git a/Documentation/video4linux/API.html b/Documentation/video4linux/API.html new file mode 100644 index 00000000000..4b3d8f640a4 --- /dev/null +++ b/Documentation/video4linux/API.html @@ -0,0 +1,399 @@ + +Video4Linux Kernel API Reference v0.1:19990430 + + + + + +

Devices

+Video4Linux provides the following sets of device files. These live on the +character device formerly known as "/dev/bttv". /dev/bttv should be a +symlink to /dev/video0 for most people. +

+ + + + + + +
Device NameMinor RangeFunction
/dev/video0-63Video Capture Interface
/dev/radio64-127AM/FM Radio Devices
/dev/vtx192-223Teletext Interface Chips
/dev/vbi224-239Raw VBI Data (Intercast/teletext)
+

+Video4Linux programs open and scan the devices to find what they are looking +for. Capability queries define what each interface supports. The +described API is only defined for video capture cards. The relevant subset +applies to radio cards. Teletext interfaces talk the existing VTX API. +

+

Capability Query Ioctl

+The VIDIOCGCAP ioctl call is used to obtain the capability +information for a video device. The struct video_capability object +passed to the ioctl is completed and returned. It contains the following +information +

+ + + + + + + + + +
name[32]Canonical name for this interface
typeType of interface
channelsNumber of radio/tv channels if appropriate
audiosNumber of audio devices if appropriate
maxwidthMaximum capture width in pixels
maxheightMaximum capture height in pixels
minwidthMinimum capture width in pixels
minheightMinimum capture height in pixels
+

+The type field lists the capability flags for the device. These are +as follows +

+ + + + + + + + + + + + +
NameDescription
VID_TYPE_CAPTURECan capture to memory
VID_TYPE_TUNERHas a tuner of some form
VID_TYPE_TELETEXTHas teletext capability
VID_TYPE_OVERLAYCan overlay its image onto the frame buffer
VID_TYPE_CHROMAKEYOverlay is Chromakeyed
VID_TYPE_CLIPPINGOverlay clipping is supported
VID_TYPE_FRAMERAMOverlay overwrites frame buffer memory
VID_TYPE_SCALESThe hardware supports image scaling
VID_TYPE_MONOCHROMEImage capture is grey scale only
VID_TYPE_SUBCAPTURECapture can be of only part of the image
+

+The minimum and maximum sizes listed for a capture device do not imply all +that all height/width ratios or sizes within the range are possible. A +request to set a size will be honoured by the largest available capture +size whose capture is no large than the requested rectangle in either +direction. For example the quickcam has 3 fixed settings. +

+

Frame Buffer

+Capture cards that drop data directly onto the frame buffer must be told the +base address of the frame buffer, its size and organisation. This is a +privileged ioctl and one that eventually X itself should set. +

+The VIDIOCSFBUF ioctl sets the frame buffer parameters for a capture +card. If the card does not do direct writes to the frame buffer then this +ioctl will be unsupported. The VIDIOCGFBUF ioctl returns the +currently used parameters. The structure used in both cases is a +struct video_buffer. +

+ + + + + + +
void *baseBase physical address of the buffer
int heightHeight of the frame buffer
int widthWidth of the frame buffer
int depthDepth of the frame buffer
int bytesperlineNumber of bytes of memory between the start of two adjacent lines
+

+Note that these values reflect the physical layout of the frame buffer. +The visible area may be smaller. In fact under XFree86 this is commonly the +case. XFree86 DGA can provide the parameters required to set up this ioctl. +Setting the base address to NULL indicates there is no physical frame buffer +access. +

+

Capture Windows

+The capture area is described by a struct video_window. This defines +a capture area and the clipping information if relevant. The +VIDIOCGWIN ioctl recovers the current settings and the +VIDIOCSWIN sets new values. A successful call to VIDIOCSWIN +indicates that a suitable set of parameters have been chosen. They do not +indicate that exactly what was requested was granted. The program should +call VIDIOCGWIN to check if the nearest match was suitable. The +struct video_window contains the following fields. +

+ + + + + + + + + +
xThe X co-ordinate specified in X windows format.
yThe Y co-ordinate specified in X windows format.
widthThe width of the image capture.
heightThe height of the image capture.
chromakeyA host order RGB32 value for the chroma key.
flagsAdditional capture flags.
clipsA list of clipping rectangles. (Set only)
clipcountThe number of clipping rectangles. (Set only)
+

+Clipping rectangles are passed as an array. Each clip consists of the following +fields available to the user. +

+ + + + + +
xX co-ordinate of rectangle to skip
yY co-ordinate of rectangle to skip
widthWidth of rectangle to skip
heightHeight of rectangle to skip
+

+Merely setting the window does not enable capturing. Overlay capturing +(i.e. PCI-PCI transfer to the frame buffer of the video card) +is activated by passing the VIDIOCCAPTURE ioctl a value of 1, and +disabled by passing it a value of 0. +

+Some capture devices can capture a subfield of the image they actually see. +This is indicated when VIDEO_TYPE_SUBCAPTURE is defined. +The video_capture describes the time and special subfields to capture. +The video_capture structure contains the following fields. +

+ + + + + + + +
xX co-ordinate of source rectangle to grab
yY co-ordinate of source rectangle to grab
widthWidth of source rectangle to grab
heightHeight of source rectangle to grab
decimationDecimation to apply
flagsFlag settings for grabbing
+The available flags are +

+ + + + +
NameDescription
VIDEO_CAPTURE_ODDCapture only odd frames
VIDEO_CAPTURE_EVENCapture only even frames
+

+

Video Sources

+Each video4linux video or audio device captures from one or more +source channels. Each channel can be queries with the +VDIOCGCHAN ioctl call. Before invoking this function the caller +must set the channel field to the channel that is being queried. On return +the struct video_channel is filled in with information about the +nature of the channel itself. +

+The VIDIOCSCHAN ioctl takes an integer argument and switches the +capture to this input. It is not defined whether parameters such as colour +settings or tuning are maintained across a channel switch. The caller should +maintain settings as desired for each channel. (This is reasonable as +different video inputs may have different properties). +

+The struct video_channel consists of the following +

+ + + + + + + +
channelThe channel number
nameThe input name - preferably reflecting the label +on the card input itself
tunersNumber of tuners for this input
flagsProperties the tuner has
typeInput type (if known)
normThe norm for this channel
+

+The flags defined are +

+ + + + +
VIDEO_VC_TUNERChannel has tuners.
VIDEO_VC_AUDIOChannel has audio.
VIDEO_VC_NORMChannel has norm setting.
+

+The types defined are +

+ + + +
VIDEO_TYPE_TVThe input is a TV input.
VIDEO_TYPE_CAMERAThe input is a camera.
+

+

Image Properties

+The image properties of the picture can be queried with the VIDIOCGPICT +ioctl which fills in a struct video_picture. The VIDIOCSPICT +ioctl allows values to be changed. All values except for the palette type +are scaled between 0-65535. +

+The struct video_picture consists of the following fields +

+ + + + + + + + +
brightnessPicture brightness
huePicture hue (colour only)
colourPicture colour (colour only)
contrastPicture contrast
whitenessThe whiteness (greyscale only)
depthThe capture depth (may need to match the frame buffer depth)
paletteReports the palette that should be used for this image
+

+The following palettes are defined +

+ + + + + + + + + + + + + + + +
VIDEO_PALETTE_GREYLinear intensity grey scale (255 is brightest).
VIDEO_PALETTE_HI240The BT848 8bit colour cube.
VIDEO_PALETTE_RGB565RGB565 packed into 16 bit words.
VIDEO_PALETTE_RGB555RGV555 packed into 16 bit words, top bit undefined.
VIDEO_PALETTE_RGB24RGB888 packed into 24bit words.
VIDEO_PALETTE_RGB32RGB888 packed into the low 3 bytes of 32bit words. The top 8bits are undefined.
VIDEO_PALETTE_YUV422Video style YUV422 - 8bits packed 4bits Y 2bits U 2bits V
VIDEO_PALETTE_YUYVDescribe me
VIDEO_PALETTE_UYVYDescribe me
VIDEO_PALETTE_YUV420YUV420 capture
VIDEO_PALETTE_YUV411YUV411 capture
VIDEO_PALETTE_RAWRAW capture (BT848)
VIDEO_PALETTE_YUV422PYUV 4:2:2 Planar
VIDEO_PALETTE_YUV411PYUV 4:1:1 Planar
+

+

Tuning

+Each video input channel can have one or more tuners associated with it. Many +devices will not have tuners. TV cards and radio cards will have one or more +tuners attached. +

+Tuners are described by a struct video_tuner which can be obtained by +the VIDIOCGTUNER ioctl. Fill in the tuner number in the structure +then pass the structure to the ioctl to have the data filled in. The +tuner can be switched using VIDIOCSTUNER which takes an integer argument +giving the tuner to use. A struct tuner has the following fields +

+ + + + + + + + +
tunerNumber of the tuner
nameCanonical name for this tuner (eg FM/AM/TV)
rangelowLowest tunable frequency
rangehighHighest tunable frequency
flagsFlags describing the tuner
modeThe video signal mode if relevant
signalSignal strength if known - between 0-65535
+

+The following flags exist +

+ + + + + + + + + +
VIDEO_TUNER_PALPAL tuning is supported
VIDEO_TUNER_NTSCNTSC tuning is supported
VIDEO_TUNER_SECAMSECAM tuning is supported
VIDEO_TUNER_LOWFrequency is in a lower range
VIDEO_TUNER_NORMThe norm for this tuner is settable
VIDEO_TUNER_STEREO_ONThe tuner is seeing stereo audio
VIDEO_TUNER_RDS_ONThe tuner is seeing a RDS datastream
VIDEO_TUNER_MBS_ONThe tuner is seeing a MBS datastream
+

+The following modes are defined +

+ + + + + +
VIDEO_MODE_PALThe tuner is in PAL mode
VIDEO_MODE_NTSCThe tuner is in NTSC mode
VIDEO_MODE_SECAMThe tuner is in SECAM mode
VIDEO_MODE_AUTOThe tuner auto switches, or mode does not apply
+

+Tuning frequencies are an unsigned 32bit value in 1/16th MHz or if the +VIDEO_TUNER_LOW flag is set they are in 1/16th KHz. The current +frequency is obtained as an unsigned long via the VIDIOCGFREQ ioctl and +set by the VIDIOCSFREQ ioctl. +

+

Audio

+TV and Radio devices have one or more audio inputs that may be selected. +The audio properties are queried by passing a struct video_audio to VIDIOCGAUDIO ioctl. The +VIDIOCSAUDIO ioctl sets audio properties. +

+The structure contains the following fields +

+ + + + + + + + + + +
audioThe channel number
volumeThe volume level
bassThe bass level
trebleThe treble level
flagsFlags describing the audio channel
nameCanonical name for the audio input
modeThe mode the audio input is in
balanceThe left/right balance
stepActual step used by the hardware
+

+The following flags are defined +

+ + + + + + + +
VIDEO_AUDIO_MUTEThe audio is muted
VIDEO_AUDIO_MUTABLEAudio muting is supported
VIDEO_AUDIO_VOLUMEThe volume is controllable
VIDEO_AUDIO_BASSThe bass is controllable
VIDEO_AUDIO_TREBLEThe treble is controllable
VIDEO_AUDIO_BALANCEThe balance is controllable
+

+The following decoding modes are defined +

+ + + + + +
VIDEO_SOUND_MONOMono signal
VIDEO_SOUND_STEREOStereo signal (NICAM for TV)
VIDEO_SOUND_LANG1European TV alternate language 1
VIDEO_SOUND_LANG2European TV alternate language 2
+

+

Reading Images

+Each call to the read syscall returns the next available image +from the device. It is up to the caller to set format and size (using +the VIDIOCSPICT and VIDIOCSWIN ioctls) and then to pass a suitable +size buffer and length to the function. Not all devices will support +read operations. +

+A second way to handle image capture is via the mmap interface if supported. +To use the mmap interface a user first sets the desired image size and depth +properties. Next the VIDIOCGMBUF ioctl is issued. This reports the size +of buffer to mmap and the offset within the buffer for each frame. The +number of frames supported is device dependent and may only be one. +

+The video_mbuf structure contains the following fields +

+ + + + +
sizeThe number of bytes to map
framesThe number of frames
offsetsThe offset of each frame
+

+Once the mmap has been made the VIDIOCMCAPTURE ioctl starts the +capture to a frame using the format and image size specified in the +video_mmap (which should match or be below the initial query size). +When the VIDIOCMCAPTURE ioctl returns the frame is not +captured yet, the driver just instructed the hardware to start the +capture. The application has to use the VIDIOCSYNC ioctl to wait +until the capture of a frame is finished. VIDIOCSYNC takes the frame +number you want to wait for as argument. +

+It is allowed to call VIDIOCMCAPTURE multiple times (with different +frame numbers in video_mmap->frame of course) and thus have multiple +outstanding capture requests. A simple way do to double-buffering +using this feature looks like this: +

+/* setup everything */
+VIDIOCMCAPTURE(0)
+while (whatever) {
+   VIDIOCMCAPTURE(1)
+   VIDIOCSYNC(0)
+   /* process frame 0 while the hardware captures frame 1 */
+   VIDIOCMCAPTURE(0)
+   VIDIOCSYNC(1)
+   /* process frame 1 while the hardware captures frame 0 */
+}
+
+Note that you are not limited to only two frames. The API +allows up to 32 frames, the VIDIOCGMBUF ioctl returns the number of +frames the driver granted. Thus it is possible to build deeper queues +to avoid loosing frames on load peaks. +

+While capturing to memory the driver will make a "best effort" attempt +to capture to screen as well if requested. This normally means all +frames that "miss" memory mapped capture will go to the display. +

+A final ioctl exists to allow a device to obtain related devices if a +driver has multiple components (for example video0 may not be associated +with vbi0 which would cause an intercast display program to make a bad +mistake). The VIDIOCGUNIT ioctl reports the unit numbers of the associated +devices if any exist. The video_unit structure has the following fields. +

+ + + + + + +
videoVideo capture device
vbiVBI capture device
radioRadio device
audioAudio mixer
teletextTeletext device
+

+

RDS Datastreams

+For radio devices that support it, it is possible to receive Radio Data +System (RDS) data by means of a read() on the device. The data is packed in +groups of three, as follows: + + + + + + +
First OctetLeast Significant Byte of RDS Block
Second OctetMost Significant Byte of RDS Block +
Third OctetBit 7:Error bit. Indicates that +an uncorrectable error occurred during reception of this block.
 Bit 6:Corrected bit. Indicates that +an error was corrected for this data block.
 Bits 5-3:Received Offset. Indicates the +offset received by the sync system.
 Bits 2-0:Offset Name. Indicates the +offset applied to this data.
+ + -- cgit v1.2.3