Source : http://www.linuxtv.org/downloads/video4linux/API/V4L1_API.html
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 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.
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 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.
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 *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.
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.
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
The available flags are
Name Description VIDEO_CAPTURE_ODD Capture only odd frames VIDEO_CAPTURE_EVEN Capture 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
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.
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
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
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
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.
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
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
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
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
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 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. |
최근댓글