| <HTML><HEAD> |
| <TITLE>Video4Linux Kernel API Reference v0.1:19990430</TITLE> |
| </HEAD> |
| <! Revision History: > |
| <! 4/30/1999 - Fred Gleason (fredg@wava.com)> |
| <! Documented extensions for the Radio Data System (RDS) extensions > |
| <BODY bgcolor="#ffffff"> |
| <H3>Devices</H3> |
| 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. |
| <P> |
| <TABLE> |
| <TR><TH>Device Name</TH><TH>Minor Range</TH><TH>Function</TH> |
| <TR><TD>/dev/video</TD><TD>0-63</TD><TD>Video Capture Interface</TD> |
| <TR><TD>/dev/radio</TD><TD>64-127</TD><TD>AM/FM Radio Devices</TD> |
| <TR><TD>/dev/vtx</TD><TD>192-223</TD><TD>Teletext Interface Chips</TD> |
| <TR><TD>/dev/vbi</TD><TD>224-239</TD><TD>Raw VBI Data (Intercast/teletext)</TD> |
| </TABLE> |
| <P> |
| 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. |
| <P> |
| <H3>Capability Query Ioctl</H3> |
| The <B>VIDIOCGCAP</B> ioctl call is used to obtain the capability |
| information for a video device. The <b>struct video_capability</b> object |
| passed to the ioctl is completed and returned. It contains the following |
| information |
| <P> |
| <TABLE> |
| <TR><TD><b>name[32]</b><TD>Canonical name for this interface</TD> |
| <TR><TD><b>type</b><TD>Type of interface</TD> |
| <TR><TD><b>channels</b><TD>Number of radio/tv channels if appropriate</TD> |
| <TR><TD><b>audios</b><TD>Number of audio devices if appropriate</TD> |
| <TR><TD><b>maxwidth</b><TD>Maximum capture width in pixels</TD> |
| <TR><TD><b>maxheight</b><TD>Maximum capture height in pixels</TD> |
| <TR><TD><b>minwidth</b><TD>Minimum capture width in pixels</TD> |
| <TR><TD><b>minheight</b><TD>Minimum capture height in pixels</TD> |
| </TABLE> |
| <P> |
| The type field lists the capability flags for the device. These are |
| as follows |
| <P> |
| <TABLE> |
| <TR><TH>Name</TH><TH>Description</TH> |
| <TR><TD><b>VID_TYPE_CAPTURE</b><TD>Can capture to memory</TD> |
| <TR><TD><b>VID_TYPE_TUNER</b><TD>Has a tuner of some form</TD> |
| <TR><TD><b>VID_TYPE_TELETEXT</b><TD>Has teletext capability</TD> |
| <TR><TD><b>VID_TYPE_OVERLAY</b><TD>Can overlay its image onto the frame buffer</TD> |
| <TR><TD><b>VID_TYPE_CHROMAKEY</b><TD>Overlay is Chromakeyed</TD> |
| <TR><TD><b>VID_TYPE_CLIPPING</b><TD>Overlay clipping is supported</TD> |
| <TR><TD><b>VID_TYPE_FRAMERAM</b><TD>Overlay overwrites frame buffer memory</TD> |
| <TR><TD><b>VID_TYPE_SCALES</b><TD>The hardware supports image scaling</TD> |
| <TR><TD><b>VID_TYPE_MONOCHROME</b><TD>Image capture is grey scale only</TD> |
| <TR><TD><b>VID_TYPE_SUBCAPTURE</b><TD>Capture can be of only part of the image</TD> |
| </TABLE> |
| <P> |
| 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. |
| <P> |
| <H3>Frame Buffer</H3> |
| 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. |
| <P> |
| The <b>VIDIOCSFBUF</b> 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 <b>VIDIOCGFBUF</b> ioctl returns the |
| currently used parameters. The structure used in both cases is a |
| <b>struct video_buffer</b>. |
| <P> |
| <TABLE> |
| <TR><TD><b>void *base</b></TD><TD>Base physical address of the buffer</TD> |
| <TR><TD><b>int height</b></TD><TD>Height of the frame buffer</TD> |
| <TR><TD><b>int width</b></TD><TD>Width of the frame buffer</TD> |
| <TR><TD><b>int depth</b></TD><TD>Depth of the frame buffer</TD> |
| <TR><TD><b>int bytesperline</b></TD><TD>Number of bytes of memory between the start of two adjacent lines</TD> |
| </TABLE> |
| <P> |
| 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. |
| <P> |
| <H3>Capture Windows</H3> |
| The capture area is described by a <b>struct video_window</b>. This defines |
| a capture area and the clipping information if relevant. The |
| <b>VIDIOCGWIN</b> ioctl recovers the current settings and the |
| <b>VIDIOCSWIN</b> sets new values. A successful call to <b>VIDIOCSWIN</b> |
| 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 <b>VIDIOCGWIN</b> to check if the nearest match was suitable. The |
| <b>struct video_window</b> contains the following fields. |
| <P> |
| <TABLE> |
| <TR><TD><b>x</b><TD>The X co-ordinate specified in X windows format.</TD> |
| <TR><TD><b>y</b><TD>The Y co-ordinate specified in X windows format.</TD> |
| <TR><TD><b>width</b><TD>The width of the image capture.</TD> |
| <TR><TD><b>height</b><TD>The height of the image capture.</TD> |
| <TR><TD><b>chromakey</b><TD>A host order RGB32 value for the chroma key.</TD> |
| <TR><TD><b>flags</b><TD>Additional capture flags.</TD> |
| <TR><TD><b>clips</b><TD>A list of clipping rectangles. <em>(Set only)</em></TD> |
| <TR><TD><b>clipcount</b><TD>The number of clipping rectangles. <em>(Set only)</em></TD> |
| </TABLE> |
| <P> |
| Clipping rectangles are passed as an array. Each clip consists of the following |
| fields available to the user. |
| <P> |
| <TABLE> |
| <TR><TD><b>x</b></TD><TD>X co-ordinate of rectangle to skip</TD> |
| <TR><TD><b>y</b></TD><TD>Y co-ordinate of rectangle to skip</TD> |
| <TR><TD><b>width</b></TD><TD>Width of rectangle to skip</TD> |
| <TR><TD><b>height</b></TD><TD>Height of rectangle to skip</TD> |
| </TABLE> |
| <P> |
| 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 <b>VIDIOCCAPTURE</b> ioctl a value of 1, and |
| disabled by passing it a value of 0. |
| <P> |
| 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. |
| <P> |
| <TABLE> |
| <TR><TD><b>x</b></TD><TD>X co-ordinate of source rectangle to grab</TD> |
| <TR><TD><b>y</b></TD><TD>Y co-ordinate of source rectangle to grab</TD> |
| <TR><TD><b>width</b></TD><TD>Width of source rectangle to grab</TD> |
| <TR><TD><b>height</b></TD><TD>Height of source rectangle to grab</TD> |
| <TR><TD><b>decimation</b></TD><TD>Decimation to apply</TD> |
| <TR><TD><b>flags</b></TD><TD>Flag settings for grabbing</TD> |
| </TABLE> |
| The available flags are |
| <P> |
| <TABLE> |
| <TR><TH>Name</TH><TH>Description</TH> |
| <TR><TD><b>VIDEO_CAPTURE_ODD</b><TD>Capture only odd frames</TD> |
| <TR><TD><b>VIDEO_CAPTURE_EVEN</b><TD>Capture only even frames</TD> |
| </TABLE> |
| <P> |
| <H3>Video Sources</H3> |
| Each video4linux video or audio device captures from one or more |
| source <b>channels</b>. Each channel can be queries with the |
| <b>VDIOCGCHAN</b> ioctl call. Before invoking this function the caller |
| must set the channel field to the channel that is being queried. On return |
| the <b>struct video_channel</b> is filled in with information about the |
| nature of the channel itself. |
| <P> |
| The <b>VIDIOCSCHAN</b> 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). |
| <P> |
| The <b>struct video_channel</b> consists of the following |
| <P> |
| <TABLE> |
| <TR><TD><b>channel</b></TD><TD>The channel number</TD> |
| <TR><TD><b>name</b></TD><TD>The input name - preferably reflecting the label |
| on the card input itself</TD> |
| <TR><TD><b>tuners</b></TD><TD>Number of tuners for this input</TD> |
| <TR><TD><b>flags</b></TD><TD>Properties the tuner has</TD> |
| <TR><TD><b>type</b></TD><TD>Input type (if known)</TD> |
| <TR><TD><b>norm</b><TD>The norm for this channel</TD> |
| </TABLE> |
| <P> |
| The flags defined are |
| <P> |
| <TABLE> |
| <TR><TD><b>VIDEO_VC_TUNER</b><TD>Channel has tuners.</TD> |
| <TR><TD><b>VIDEO_VC_AUDIO</b><TD>Channel has audio.</TD> |
| <TR><TD><b>VIDEO_VC_NORM</b><TD>Channel has norm setting.</TD> |
| </TABLE> |
| <P> |
| The types defined are |
| <P> |
| <TABLE> |
| <TR><TD><b>VIDEO_TYPE_TV</b><TD>The input is a TV input.</TD> |
| <TR><TD><b>VIDEO_TYPE_CAMERA</b><TD>The input is a camera.</TD> |
| </TABLE> |
| <P> |
| <H3>Image Properties</H3> |
| The image properties of the picture can be queried with the <b>VIDIOCGPICT</b> |
| ioctl which fills in a <b>struct video_picture</b>. The <b>VIDIOCSPICT</b> |
| ioctl allows values to be changed. All values except for the palette type |
| are scaled between 0-65535. |
| <P> |
| The <b>struct video_picture</b> consists of the following fields |
| <P> |
| <TABLE> |
| <TR><TD><b>brightness</b><TD>Picture brightness</TD> |
| <TR><TD><b>hue</b><TD>Picture hue (colour only)</TD> |
| <TR><TD><b>colour</b><TD>Picture colour (colour only)</TD> |
| <TR><TD><b>contrast</b><TD>Picture contrast</TD> |
| <TR><TD><b>whiteness</b><TD>The whiteness (greyscale only)</TD> |
| <TR><TD><b>depth</b><TD>The capture depth (may need to match the frame buffer depth)</TD> |
| <TR><TD><b>palette</b><TD>Reports the palette that should be used for this image</TD> |
| </TABLE> |
| <P> |
| The following palettes are defined |
| <P> |
| <TABLE> |
| <TR><TD><b>VIDEO_PALETTE_GREY</b><TD>Linear intensity grey scale (255 is brightest).</TD> |
| <TR><TD><b>VIDEO_PALETTE_HI240</b><TD>The BT848 8bit colour cube.</TD> |
| <TR><TD><b>VIDEO_PALETTE_RGB565</b><TD>RGB565 packed into 16 bit words.</TD> |
| <TR><TD><b>VIDEO_PALETTE_RGB555</b><TD>RGV555 packed into 16 bit words, top bit undefined.</TD> |
| <TR><TD><b>VIDEO_PALETTE_RGB24</b><TD>RGB888 packed into 24bit words.</TD> |
| <TR><TD><b>VIDEO_PALETTE_RGB32</b><TD>RGB888 packed into the low 3 bytes of 32bit words. The top 8bits are undefined.</TD> |
| <TR><TD><b>VIDEO_PALETTE_YUV422</b><TD>Video style YUV422 - 8bits packed 4bits Y 2bits U 2bits V</TD> |
| <TR><TD><b>VIDEO_PALETTE_YUYV</b><TD>Describe me</TD> |
| <TR><TD><b>VIDEO_PALETTE_UYVY</b><TD>Describe me</TD> |
| <TR><TD><b>VIDEO_PALETTE_YUV420</b><TD>YUV420 capture</TD> |
| <TR><TD><b>VIDEO_PALETTE_YUV411</b><TD>YUV411 capture</TD> |
| <TR><TD><b>VIDEO_PALETTE_RAW</b><TD>RAW capture (BT848)</TD> |
| <TR><TD><b>VIDEO_PALETTE_YUV422P</b><TD>YUV 4:2:2 Planar</TD> |
| <TR><TD><b>VIDEO_PALETTE_YUV411P</b><TD>YUV 4:1:1 Planar</TD> |
| </TABLE> |
| <P> |
| <H3>Tuning</H3> |
| 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. |
| <P> |
| Tuners are described by a <b>struct video_tuner</b> which can be obtained by |
| the <b>VIDIOCGTUNER</b> 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 <b>VIDIOCSTUNER</b> which takes an integer argument |
| giving the tuner to use. A struct tuner has the following fields |
| <P> |
| <TABLE> |
| <TR><TD><b>tuner</b><TD>Number of the tuner</TD> |
| <TR><TD><b>name</b><TD>Canonical name for this tuner (eg FM/AM/TV)</TD> |
| <TR><TD><b>rangelow</b><TD>Lowest tunable frequency</TD> |
| <TR><TD><b>rangehigh</b><TD>Highest tunable frequency</TD> |
| <TR><TD><b>flags</b><TD>Flags describing the tuner</TD> |
| <TR><TD><b>mode</b><TD>The video signal mode if relevant</TD> |
| <TR><TD><b>signal</b><TD>Signal strength if known - between 0-65535</TD> |
| </TABLE> |
| <P> |
| The following flags exist |
| <P> |
| <TABLE> |
| <TR><TD><b>VIDEO_TUNER_PAL</b><TD>PAL tuning is supported</TD> |
| <TR><TD><b>VIDEO_TUNER_NTSC</b><TD>NTSC tuning is supported</TD> |
| <TR><TD><b>VIDEO_TUNER_SECAM</b><TD>SECAM tuning is supported</TD> |
| <TR><TD><b>VIDEO_TUNER_LOW</b><TD>Frequency is in a lower range</TD> |
| <TR><TD><b>VIDEO_TUNER_NORM</b><TD>The norm for this tuner is settable</TD> |
| <TR><TD><b>VIDEO_TUNER_STEREO_ON</b><TD>The tuner is seeing stereo audio</TD> |
| <TR><TD><b>VIDEO_TUNER_RDS_ON</b><TD>The tuner is seeing a RDS datastream</TD> |
| <TR><TD><b>VIDEO_TUNER_MBS_ON</b><TD>The tuner is seeing a MBS datastream</TD> |
| </TABLE> |
| <P> |
| The following modes are defined |
| <P> |
| <TABLE> |
| <TR><TD><b>VIDEO_MODE_PAL</b><TD>The tuner is in PAL mode</TD> |
| <TR><TD><b>VIDEO_MODE_NTSC</b><TD>The tuner is in NTSC mode</TD> |
| <TR><TD><b>VIDEO_MODE_SECAM</b><TD>The tuner is in SECAM mode</TD> |
| <TR><TD><b>VIDEO_MODE_AUTO</b><TD>The tuner auto switches, or mode does not apply</TD> |
| </TABLE> |
| <P> |
| Tuning frequencies are an unsigned 32bit value in 1/16th MHz or if the |
| <b>VIDEO_TUNER_LOW</b> flag is set they are in 1/16th KHz. The current |
| frequency is obtained as an unsigned long via the <b>VIDIOCGFREQ</b> ioctl and |
| set by the <b>VIDIOCSFREQ</b> ioctl. |
| <P> |
| <H3>Audio</H3> |
| TV and Radio devices have one or more audio inputs that may be selected. |
| The audio properties are queried by passing a <b>struct video_audio</b> to <b>VIDIOCGAUDIO</b> ioctl. The |
| <b>VIDIOCSAUDIO</b> ioctl sets audio properties. |
| <P> |
| The structure contains the following fields |
| <P> |
| <TABLE> |
| <TR><TD><b>audio</b><TD>The channel number</TD> |
| <TR><TD><b>volume</b><TD>The volume level</TD> |
| <TR><TD><b>bass</b><TD>The bass level</TD> |
| <TR><TD><b>treble</b><TD>The treble level</TD> |
| <TR><TD><b>flags</b><TD>Flags describing the audio channel</TD> |
| <TR><TD><b>name</b><TD>Canonical name for the audio input</TD> |
| <TR><TD><b>mode</b><TD>The mode the audio input is in</TD> |
| <TR><TD><b>balance</b><TD>The left/right balance</TD> |
| <TR><TD><b>step</b><TD>Actual step used by the hardware</TD> |
| </TABLE> |
| <P> |
| The following flags are defined |
| <P> |
| <TABLE> |
| <TR><TD><b>VIDEO_AUDIO_MUTE</b><TD>The audio is muted</TD> |
| <TR><TD><b>VIDEO_AUDIO_MUTABLE</b><TD>Audio muting is supported</TD> |
| <TR><TD><b>VIDEO_AUDIO_VOLUME</b><TD>The volume is controllable</TD> |
| <TR><TD><b>VIDEO_AUDIO_BASS</b><TD>The bass is controllable</TD> |
| <TR><TD><b>VIDEO_AUDIO_TREBLE</b><TD>The treble is controllable</TD> |
| <TR><TD><b>VIDEO_AUDIO_BALANCE</b><TD>The balance is controllable</TD> |
| </TABLE> |
| <P> |
| The following decoding modes are defined |
| <P> |
| <TABLE> |
| <TR><TD><b>VIDEO_SOUND_MONO</b><TD>Mono signal</TD> |
| <TR><TD><b>VIDEO_SOUND_STEREO</b><TD>Stereo signal (NICAM for TV)</TD> |
| <TR><TD><b>VIDEO_SOUND_LANG1</b><TD>European TV alternate language 1</TD> |
| <TR><TD><b>VIDEO_SOUND_LANG2</b><TD>European TV alternate language 2</TD> |
| </TABLE> |
| <P> |
| <H3>Reading Images</H3> |
| Each call to the <b>read</b> 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. |
| <P> |
| 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. |
| <P> |
| The video_mbuf structure contains the following fields |
| <P> |
| <TABLE> |
| <TR><TD><b>size</b><TD>The number of bytes to map</TD> |
| <TR><TD><b>frames</b><TD>The number of frames</TD> |
| <TR><TD><b>offsets</b><TD>The offset of each frame</TD> |
| </TABLE> |
| <P> |
| 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 <em>not</em> |
| 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. |
| <p> |
| 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: |
| <pre> |
| /* 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 */ |
| } |
| </pre> |
| Note that you are <em>not</em> 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. |
| <p> |
| 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. |
| <P> |
| 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. |
| <P> |
| <TABLE> |
| <TR><TD><b>video</b><TD>Video capture device</TD> |
| <TR><TD><b>vbi</b><TD>VBI capture device</TD> |
| <TR><TD><b>radio</b><TD>Radio device</TD> |
| <TR><TD><b>audio</b><TD>Audio mixer</TD> |
| <TR><TD><b>teletext</b><TD>Teletext device</TD> |
| </TABLE> |
| <P> |
| <H3>RDS Datastreams</H3> |
| 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: |
| <TABLE> |
| <TR><TD>First Octet</TD><TD>Least Significant Byte of RDS Block</TD></TR> |
| <TR><TD>Second Octet</TD><TD>Most Significant Byte of RDS Block |
| <TR><TD>Third Octet</TD><TD>Bit 7:</TD><TD>Error bit. Indicates that |
| an uncorrectable error occurred during reception of this block.</TD></TR> |
| <TR><TD> </TD><TD>Bit 6:</TD><TD>Corrected bit. Indicates that |
| an error was corrected for this data block.</TD></TR> |
| <TR><TD> </TD><TD>Bits 5-3:</TD><TD>Received Offset. Indicates the |
| offset received by the sync system.</TD></TR> |
| <TR><TD> </TD><TD>Bits 2-0:</TD><TD>Offset Name. Indicates the |
| offset applied to this data.</TD></TR> |
| </TABLE> |
| </BODY> |
| </HTML> |
