--- zzzz-none-000/linux-2.4.17/Documentation/video4linux/API.html 2000-01-06 22:46:18.000000000 +0000 +++ sangam-fb-401/linux-2.4.17/Documentation/video4linux/API.html 2004-07-09 15:05:46.000000000 +0000 @@ -1,374 +1,374 @@ -
--
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 -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 sets the image size -you wish to use (which should match or be below the initial query size). -Having done so it will begin capturing to the memory mapped buffer. Whenever -a buffer is "used" by the program it should called VIDIOCSYNC to free this -frame up and continue. to add:VIDIOCSYNC takes the frame number -you are freeing as its argument. When the buffer is unmapped or all the -buffers are full capture ceases. 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. |
+
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 +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 sets the image size +you wish to use (which should match or be below the initial query size). +Having done so it will begin capturing to the memory mapped buffer. Whenever +a buffer is "used" by the program it should called VIDIOCSYNC to free this +frame up and continue. to add:VIDIOCSYNC takes the frame number +you are freeing as its argument. When the buffer is unmapped or all the +buffers are full capture ceases. 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. |