Camstream: CamStream API documentation

Main Page Class Hierarchy Compound List File List Compound Members File Members

# CVideoDevice Class Reference

A device wrapper for Video4Linux devices. More...

`#include <VideoDevice.h>`

Inheritance diagram for CVideoDevice::

List of all members.

## Public Methods

- CVideoDevice (const QString &node_name)
- ~CVideoDevice ()
- bool IsValid ()
- int Open (int buffers=1)
- void Close ()
- int GetDescriptor () const
- void EnableRGB (bool isOn)
- void EnableYUV (bool isOn)
- QString GetNodeName () const
- QString GetIntfName () const
- QSize GetMinSize () const
- QSize GetSize ()
- QSize GetMaxSize () const
- bool SetSize (int width, int height)
- bool SetSize (const QSize &new_size)
- int GetFramerate () const
- bool SetFramerate (int fps)
- int GetMBuffers () const
- int GetBuffers () const
- int GetVideoInputs () const
- int GetCurrentVideoInput () const
- CVideoDeviceInput* GetVideoInput (int number=-1) const
- bool SelectVideoInput (int number)
- int GetAudioInputs () const
- CVideoAudioInput* GetAudioInput (int number=-1) const
- bool SelectAudioInput (int number)
- int GetBrightness () const
- bool SetBrightness (int val)
- int GetContrast () const
- bool SetContrast (int val)
- int GetHue () const
- bool SetHue (int val)
- int GetColour () const
- bool SetColour (int val)
- int GetWhiteness () const
- bool SetWhiteness (int val)
- int ReadImage ()
- QImage* GetRGB (int offset=0) const
- QImage* GetY (int offset=0) const
- QImage* GetU (int offset=0) const
- QImage* GetV (int offset=0) const

## Signals

- void Notify ()
- void Closed ()
- void Resized (const QSize &new_size)
- void FramerateChanged (int)
- void ChangedVideoInput (int input)
- void ChangedTunerNorm (int tuner, int norm)
- void Error (int err_num)

## Friends

- class CVideoDeviceInput
- class CVideoDeviceTuner
- class CVideoAudioInput

## Detailed Description

A device wrapper for Video4Linux devices.

This class wraps itself around a Video4Linux device; at the moment it is primarely oriented at webcams, but grabber cards are supported as well. This device can be 'opened' multiple times, so more than one class can use this device (of course they all get the same picture).

The class can return video images in RGB, YUV or both formats; it also has an optional buffer scheme for the images; this can prevent the otherwise deep copy that is needed when, for example, image diffs need to be calculated.

The class will use mmap() when it is supported by the device driver. Also some device support select(); if not, a QTimer is used. Use the Framerate functions to set the framerate or timer.

## Constructor & Destructor Documentation

CVideoDevice::CVideoDevice ( | const QString & node_name )

  | Parameters:
  node_name | The /dev device name of the video device
The constructor will do some basic checks to see if this is a valid device. If yes, IsValid() will return TRUE, otherwise FALSE.

CVideoDevice::~CVideoDevice ( | )

| Destroys the object; also closes the associated file descriptor

## Member Function Documentation

void CVideoDevice::ChangedTunerNorm ( | int tuner,
| int norm )`[signal]`

| The frequency or norm changed.

void CVideoDevice::ChangedVideoInput ( | int input )`[signal]`

| The video input channel has changed.

void CVideoDevice::Close ( | )

| Closes the device provisionally. This function decrements the usage counter of the VideoDevice. If the counter reaches 0, the device is really closed. See also Open().

void CVideoDevice::Closed ( | )`[signal]`

| The device is being closed by the last user; the device is not accessible

void CVideoDevice::EnableRGB ( | bool isOn )

| Enable/disable retrieval of RGB image(s). This tells the object if RGB images are desired. This will help in selecting the proper PALETTE for the device. Both RGB and YUV images may be enabled. See also EnableYUV. Multiple calls to EnableRGB(TRUE) will require the same amount of calls to EnableRGB(FALSE) to turn RGB retrieval completely off.

void CVideoDevice::EnableYUV ( | bool isOn )

| Enable/disable retrieval of YUV image(s). This tells the object if YUV (planar) images are desired. This will help in selecting the proper PALETTE for the device. Both YUV and RGB images may be enabled. See also EnableRGB. Multiple calls to EnableYUV(TRUE) will require the same amount of calls to EnableYUV(FALSE) to turn YUV retrieval completely off.

void CVideoDevice::Error ( | int err_num )`[signal]`

| An error occured. err_num is one of the errno values.

void CVideoDevice::FramerateChanged ( | int )`[signal]`

| The frame rate has been changed.

CVideoAudioInput * CVideoDevice::GetAudioInput ( | int number = -1 ) const

  | Returns an audio input channel (source) object. Parameters:
  number | The desired input channel; -1 for the current one
Returns: An object of type CVideoAudioInput, or NULL if number is out of range This returns a pointer to a CVideoAudioInput object; when number is -1 (the default value), it returns the current input.

int CVideoDevice::GetAudioInputs ( | ) const

| Return number of audio channels on the device. Note! There is no SelectAudioInput! I suppose it's switched together with the video input... Also there is no way to find out to which audio input is associated with which video input. It looks more like this class is meant for manipulating the FM sound decoder on the tuner than really setting anything on the input.

int CVideoDevice::GetBrightness ( | ) const

| Return brightness setting of device. Returns: unsigned integer in the range 0-65535. 65535 may indicate setting is not available.

int CVideoDevice::GetBuffers ( | ) const

| Return available buffers. Returns: The number of image buffers used internally. \condition The device must be opened. Returns the numbers of buffers in use for this device, regardless if it supports mmap() or not.

int CVideoDevice::GetColour ( | ) const

| Return colour saturation setting of device. Returns: unsigned integer in the range 0-65535. 65535 may indicate setting is not available. A colour saturation of 0 means no colour at all, so the returned images are grayscale.

int CVideoDevice::GetContrast ( | ) const

| Return contrast setting of device. Returns: unsigned integer in the range 0-65535. 65535 may indicate setting is not available.

int CVideoDevice::GetCurrentVideoInput ( | ) const

| Return current input. Returns: input number, or -1 if current input is unknown This will return the current input, if known. Unfortunately, there is no way to query the video device for the selected channel so until SelectInput() is called this function returns -1.

int CVideoDevice::GetDescriptor ( | ) const

| Returns: file descriptor. This functions returns the file descriptor for this device. If the device is not opened, -1 is returned.

int CVideoDevice::GetFramerate ( | ) const

| Returns the current framerate. Returns: The framerate in frames per second. This applies to some webcams that allow setting of a framerate. In case of a device that does not support select() we use the framerate to set the timer. By default the framerate is set to 10. Returns -1 in case of error.

int CVideoDevice::GetHue ( | ) const

| Return hue (color shift) setting of device. Returns: unsigned integer in the range 0-65535. 65535 may indicate setting is not available. Hue is a way to correct for colour deviations. It is something different than GetColour.

QString CVideoDevice::GetIntfName ( | ) const

| Returns internal name of device. This function returns the name of the device through the V4L interface.

int CVideoDevice::GetMBuffers ( | ) const

| Return number of mmaped() buffers. Returns: 0 if no mmap() support exists. \condition The device must be opened. In case the device supports mmap(), this returns the number of buffers that are available and mapped.

QSize CVideoDevice::GetMaxSize ( | ) const

| Return the maximum image size this device supports. Returns: an Object of type QSize With this function the maximum image size in pixels is retrieved. See also GetMinSize and SetSize Not all sizes between the minimum and maximum size may be allowed by the device; however, there is currently no way to retrieve a list of possible sizes. It's safest to stick to CIF (352x288) and SIF (320x240) formats and subsizes hereof, and VGA. Also it's wise to use to multiples of 8 in both directions. SetSize will return FALSE when the size was rejected by the driver.

QSize CVideoDevice::GetMinSize ( | ) const

| Return the minimum image size this device supports. Returns: an Object of type QSize With this function the minium image size in pixels is retrieved.

QString CVideoDevice::GetNodeName ( | ) const

| Returns device inode name. This function returns the name of the device inode, like /dev/video0, /dev/video1, etc.

QImage * CVideoDevice::GetRGB ( | int offset = 0 ) const

  | Get an RGB image. Parameters:
  offset | Offset in images buffer.
Retrieve pointer to an RGB image; note that this is a pointer, not a (shallow) copy. The QImage is a 32 bit deep image. When buffering is active any of the previous images in the buffer can be retrieved. The 'offset' parameter indicates the negative offset in the (circular) list of images. When offset = 0 (the default) the latest image is returned; when offset = 1 is the previous image, offset = 2 the image before that, etc. up to the number of Buffers - 1. If offset is outside the range a NULL pointer will be returned.

QSize CVideoDevice::GetSize ( | )

| Return current size from the driver. Returns: An object of type QSize. Returns the current image size as reported by the device. Returns a size of (0, 0) when the device is closed or an error occured.

QImage * CVideoDevice::GetU ( | int offset = 0 ) const

  | Get U (chrominance) component of image. Parameters:
  offset | Offset in circular buffer.
Retrieve pointer to a U image; note that this is a pointer, not a (shallow) copy. The QImage is an 8 bit deep image with grayscale palette. See GetRGB about double buffering.

QImage * CVideoDevice::GetV ( | int offset = 0 ) const

  | Get V (chrominance) component of image. Parameters:
  offset | Offset in circular buffer.
Retrieve pointer to a V image; note that this is a pointer, not a (shallow) copy. The QImage is an 8 bit deep image with grayscale palette. See GetRGB about double buffering.

CVideoDeviceInput * CVideoDevice::GetVideoInput ( | int number = -1 ) const

  | Returns an video input channel (source) object. Parameters:
  number | The desired input channel; -1 for the current one
Returns: An object of type CVideoDeviceInput, or NULL if number is out of range This returns a pointer to a CVideoDeviceInput object; when number is -1 (the default value), it returns the current input.

int CVideoDevice::GetVideoInputs ( | ) const

| Return number of input channels (sources). See CVideoDeviceInput. A device should report at least one channel, but buggy device drivers may choose to return 0.

int CVideoDevice::GetWhiteness ( | ) const

| Return gamma setting of device. Returns: unsigned integer in the range 0-65535. 65535 may indicate setting is not available. Sometimes used as a brightness contrast, but more generally this returns the gamma correction the device applies to the image.

QImage * CVideoDevice::GetY ( | int offset = 0 ) const

  | Get Y (luminance) component of image. Parameters:
  offset | Offset in circular buffer.
Retrieve pointer to a Y image; note that this is a pointer, not a (shallow) copy. The QImage is an 8 bit deep image with grayscale palette. See GetRGB about double buffering.

bool CVideoDevice::IsValid ( | )

void CVideoDevice::Notify ( | )`[signal]`

| A new image is available.

int CVideoDevice::Open ( | int bufs = 1 )

  | Open the device, even multiple times. Parameters:
  bufs | Number of image buffers; -1 use device maximum
Returns: 0 upon success, otherwise -errno . This function increments the usage counter of the device; the first time this function is called the device is really opened and initialized; all subsequent calls will return 0. You will need as many calls to Close() as you placed to Open() to get the device really closed. Open() will also start the automatic loading of images. In case the device supports select() a QSocketNotifier is installed, otherwise a timer is used. For double buffering purposes, use a buf value > 1. The buf parameter can only be set at the first Open(); subsequent calls will have no effect on the number of buffers. When bufs < 0, the device will be queried for the maximum number of buffers and that amount will be used.

int CVideoDevice::ReadImage ( | )

| Read image into Buffers. Returns: 0 on success, -errno otherwise. This function reads the raw data from the device and transforms it into RGB and/or YUV images, doing all necessary conversions.

void CVideoDevice::Resized ( | const QSize & new_size )`[signal]`

| The size has been changed.

bool CVideoDevice::SelectAudioInput ( | int number )

bool CVideoDevice::SelectVideoInput ( | int number )

| Select a new input channel. This function will program the card/chip to use the selected input channel. Return TRUE if the call succeeded, otherwise FALSE.

bool CVideoDevice::SetBrightness ( | int val )

  | Set brightness in device. Parameters:
  val | An integer in the range 0-65535.
Returns: FALSE if the device is closed or the call failed. The value returned by GetBrightness may be slightly different from what is set with SetBrightness.

bool CVideoDevice::SetColour ( | int val )

  | Set colour saturation in device. Parameters:
  val | An integer in the range 0-65535.
Returns: FALSE if the device is closed or the call failed. Colour saturation sets how bright colours should appear. A saturation of 0 yields grayscale images. The value returned by GetColour may be slightly different from what is set with SetColour.

bool CVideoDevice::SetContrast ( | int val )

  | Set contrast in device. Parameters:
  val | An integer in the range 0-65535.
Returns: FALSE if the device is closed or the call failed. The value returned by GetContrast may be slightly different from what is set with SetContrast.

bool CVideoDevice::SetFramerate ( | int fps )

  | Try to set a framerate. Parameters:
  fps | The framerate, in frames per second.
Returns: TRUE if the framerate was accepted, FALSE otherwise Some webcams allow their framerate to be set; this functions tries to do just that; in general, the camera will use the framerate closest to what it supports. In case a device does not support framerates or only a fixed framerate (grabber cards!) we use the framerate to set the timer.

bool CVideoDevice::SetHue ( | int val )

  | Set hue in device. Parameters:
  val | An integer in the range 0-65535.
Returns: FALSE if the device is closed or the call failed. Hue is a way to correct for colour deviations. The value returned by GetHue may be slightly different from what is set with SetHue.

bool CVideoDevice::SetSize ( | const QSize & new_size )

| \override

bool CVideoDevice::SetSize ( | int width,
| int height )

| Set a new image size. Returns: FALSE when the call failed, TRUE when the new size was accepted by the device. This function will attempt to set a new image size; not all sizes between the minimum and maximum size may be allowed by the device; however, there is currently no way to retrieve a list of possible sizes. It is safest to stick to CIF (352x288) and SIF (320x240) formats and subsizes hereof, and VGA. Also it's wise to use to multiples of 8 in both directions. SetSize will return FALSE when the size was rejected by the driver.

bool CVideoDevice::SetWhiteness ( | int val )

  | Set gamma value in device. Parameters:
  val | An integer in the range 0-65535.
Returns: FALSE if the device is closed or the call failed. Whiteness is sometimes used as brightness, but usually this sets the gamma correction the device will apply to the image. The value returned by GetWhiteness may be slightly different from what is set with SetWhiteness.

## Friends And Related Function Documentation

friend class CVideoAudioInput`[friend]`

friend class CVideoDeviceInput`[friend]`

friend class CVideoDeviceTuner`[friend]`

The documentation for this class was generated from the following files:

- VideoDevice.cc
- VideoDevice.h