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]
        Cannonical 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


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 is activatied by passing the VIDIOCCAPTURE ioctl a value of 1, and
disabled by passing it a value of 0. 

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 paramters 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)


The flags defined are 

 VIDEO_VC_TUNER
              Channel has tuners.
 VIDEO_VC_AUDIO
              Channel has audio.


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


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
       Cannonical 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_STEREO_ON
                     The tuner is seeing stereo audio


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 voume 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
      PROPOSED the left/right balance
 mixer
      PROPOSED the tied sound mixer number


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
                   PROPOSED The balance is controllable
 VIDEO_AUDIO_MIXER
                   PROPOSED The audio input has a tied OSS mixer


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 the format 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. This is currently not fully defined but will be defined before 2.2. 

