-
| Device Name | Minor Range | Function | -
|---|---|---|
| /dev/video | 0-63 | Video Capture Interface | -
| /dev/radio | 64-127 | AM/FM Radio Devices | -
| /dev/vtx | 192-223 | Teletext Interface Chips | -
| /dev/vbi | 224-239 | Raw 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. -
-
-
| name[32] | Canonical name for this interface | -
| type | Type of interface | -
| channels | Number of radio/tv channels if appropriate | -
| audios | Number of audio devices if appropriate | -
| maxwidth | Maximum capture width in pixels | -
| maxheight | Maximum capture height in pixels | -
| minwidth | Minimum capture width in pixels | -
| minheight | Minimum capture height in pixels | -
-The type field lists the capability flags for the device. These are -as follows -
-
| Name | Description | -
|---|---|
| VID_TYPE_CAPTURE | Can capture to memory | -
| VID_TYPE_TUNER | Has a tuner of some form | -
| VID_TYPE_TELETEXT | Has teletext capability | -
| VID_TYPE_OVERLAY | Can overlay its image onto the frame buffer | -
| VID_TYPE_CHROMAKEY | Overlay is Chromakeyed | -
| VID_TYPE_CLIPPING | Overlay clipping is supported | -
| VID_TYPE_FRAMERAM | Overlay overwrites frame buffer memory | -
| VID_TYPE_SCALES | The hardware supports image scaling | -
| VID_TYPE_MONOCHROME | Image capture is grey scale only | -
| VID_TYPE_SUBCAPTURE | Capture 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. -
-
-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 *base | Base physical address of the buffer | -
| int height | Height of the frame buffer | -
| int width | Width of the frame buffer | -
| int depth | Depth of the frame buffer | -
| int bytesperline | Number 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. -
-
-
| x | The X co-ordinate specified in X windows format. | -
| y | The Y co-ordinate specified in X windows format. | -
| width | The width of the image capture. | -
| height | The height of the image capture. | -
| chromakey | A host order RGB32 value for the chroma key. | -
| flags | Additional capture flags. | -
| clips | A list of clipping rectangles. (Set only) | -
| clipcount | The number of clipping rectangles. (Set only) | -
-Clipping rectangles are passed as an array. Each clip consists of the following -fields available to the user. -
-
| x | X co-ordinate of rectangle to skip | -
| y | Y co-ordinate of rectangle to skip | -
| width | Width of rectangle to skip | -
| height | Height 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. -
-
| x | X co-ordinate of source rectangle to grab | -
| y | Y co-ordinate of source rectangle to grab | -
| width | Width of source rectangle to grab | -
| height | Height of source rectangle to grab | -
| decimation | Decimation to apply | -
| flags | Flag settings for grabbing | -
-
| Name | Description | -
|---|---|
| VIDEO_CAPTURE_ODD | Capture only odd frames | -
| VIDEO_CAPTURE_EVEN | Capture only even frames | -
-
-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 -
-
| channel | The channel number | -
| name | The input name - preferably reflecting the label -on the card input itself | -
| tuners | Number of tuners for this input | -
| flags | Properties the tuner has | -
| type | Input type (if known) | -
| norm | The norm for this channel | -
-The flags defined are -
-
| VIDEO_VC_TUNER | Channel has tuners. | -
| VIDEO_VC_AUDIO | Channel has audio. | -
| VIDEO_VC_NORM | Channel has norm setting. | -
-The types defined are -
-
| VIDEO_TYPE_TV | The input is a TV input. | -
| VIDEO_TYPE_CAMERA | The input is a camera. | -
-
-The struct video_picture consists of the following fields -
-
| brightness | Picture brightness | -
| hue | Picture hue (colour only) | -
| colour | Picture colour (colour only) | -
| contrast | Picture contrast | -
| whiteness | The whiteness (greyscale only) | -
| depth | The capture depth (may need to match the frame buffer depth) | -
| palette | Reports the palette that should be used for this image | -
-The following palettes are defined -
-
| VIDEO_PALETTE_GREY | Linear intensity grey scale (255 is brightest). | -
| VIDEO_PALETTE_HI240 | The BT848 8bit colour cube. | -
| VIDEO_PALETTE_RGB565 | RGB565 packed into 16 bit words. | -
| VIDEO_PALETTE_RGB555 | RGV555 packed into 16 bit words, top bit undefined. | -
| VIDEO_PALETTE_RGB24 | RGB888 packed into 24bit words. | -
| VIDEO_PALETTE_RGB32 | RGB888 packed into the low 3 bytes of 32bit words. The top 8bits are undefined. | -
| VIDEO_PALETTE_YUV422 | Video style YUV422 - 8bits packed 4bits Y 2bits U 2bits V | -
| VIDEO_PALETTE_YUYV | Describe me | -
| VIDEO_PALETTE_UYVY | Describe me | -
| VIDEO_PALETTE_YUV420 | YUV420 capture | -
| VIDEO_PALETTE_YUV411 | YUV411 capture | -
| VIDEO_PALETTE_RAW | RAW capture (BT848) | -
| VIDEO_PALETTE_YUV422P | YUV 4:2:2 Planar | -
| VIDEO_PALETTE_YUV411P | YUV 4:1:1 Planar | -
-
-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 -
-
| tuner | Number of the tuner | -
| name | Canonical name for this tuner (eg FM/AM/TV) | -
| rangelow | Lowest tunable frequency | -
| rangehigh | Highest tunable frequency | -
| flags | Flags describing the tuner | -
| mode | The video signal mode if relevant | -
| signal | Signal strength if known - between 0-65535 | -
-The following flags exist -
-
| VIDEO_TUNER_PAL | PAL tuning is supported | -
| VIDEO_TUNER_NTSC | NTSC tuning is supported | -
| VIDEO_TUNER_SECAM | SECAM tuning is supported | -
| VIDEO_TUNER_LOW | Frequency is in a lower range | -
| VIDEO_TUNER_NORM | The norm for this tuner is settable | -
| VIDEO_TUNER_STEREO_ON | The tuner is seeing stereo audio | -
| VIDEO_TUNER_RDS_ON | The tuner is seeing a RDS datastream | -
| VIDEO_TUNER_MBS_ON | The tuner is seeing a MBS datastream | -
-The following modes are defined -
-
| VIDEO_MODE_PAL | The tuner is in PAL mode | -
| VIDEO_MODE_NTSC | The tuner is in NTSC mode | -
| VIDEO_MODE_SECAM | The tuner is in SECAM mode | -
| VIDEO_MODE_AUTO | The 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. -
-
-The structure contains the following fields -
-
| audio | The channel number | -
| volume | The volume level | -
| bass | The bass level | -
| treble | The treble level | -
| flags | Flags describing the audio channel | -
| name | Canonical name for the audio input | -
| mode | The mode the audio input is in | -
| balance | The left/right balance | -
| step | Actual step used by the hardware | -
-The following flags are defined -
-
| VIDEO_AUDIO_MUTE | The audio is muted | -
| VIDEO_AUDIO_MUTABLE | Audio muting is supported | -
| VIDEO_AUDIO_VOLUME | The volume is controllable | -
| VIDEO_AUDIO_BASS | The bass is controllable | -
| VIDEO_AUDIO_TREBLE | The treble is controllable | -
| VIDEO_AUDIO_BALANCE | The balance is controllable | -
-The following decoding modes are defined -
-
| VIDEO_SOUND_MONO | Mono signal | -
| VIDEO_SOUND_STEREO | Stereo signal (NICAM for TV) | -
| VIDEO_SOUND_LANG1 | European TV alternate language 1 | -
| VIDEO_SOUND_LANG2 | European TV alternate language 2 | -
-
-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 -
-
| size | The number of bytes to map | -
| frames | The number of frames | -
| offsets | The 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. -
-
| video | Video capture device | -
| vbi | VBI capture device | -
| radio | Radio device | -
| audio | Audio mixer | -
| teletext | Teletext device | -
-
| First Octet | Least Significant Byte of RDS Block | |
| Second Octet | Most Significant Byte of RDS Block - | |
| Third Octet | Bit 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. |
| + +V4L original API + | +Obsoleted by V4L2 API + |
| + +V4L2 API + | +Should be used for new projects + |