au.edu.jcu.v4l4j

Class VideoDevice

java.lang.Object

au.edu.jcu.v4l4j.VideoDevice

public class VideoDevice
extends Object

An instance of a VideoDevice object represents an existing V4L video device. It is the starting point to use functionalities provided by v4l4j, which are divided in 3 categories:

• Information gathering about the video device,
• Capturing frames from the video device,
• Accessing and controlling tuners,
• and Adjusting values of available video controls.

Each of these categories is detailed in the following sections. To use features provided in any of these categories, a VideoDevice object must first be instantiated. This is done simply by calling the constructor and giving it the full path to the associated device file:
VideoDevice vd = new VideoDevice("/dev/video0");
It is important that, once the VideoDevice is no longer used, its resources are freed. This is done by calling the release() method:
vd.release();
Once the VideoDevice is released, neither itself nor any object references obtained through it must be used.

Information gathering

A VideoDevice object offers a single method (getDeviceInfo()) to return information about itself, encapsulated in a DeviceInfo object. DeviceInfo objects contain get-type methods only, and return details such as:

• List of all video inputs, their types & their supported standards
• Details about available tuners (type, frequency range & unit, ...)
• List of image formats & capture resolutions supported by the device

See the DeviceInfo class for an example on how to use it. Note that most video device drivers do not allow multiple processes to open the device at the same time. Depending on the driver, this restriction can be seen in different ways. One of them is getDeviceInfo() will throw a V4L4JException if a process is already using the device.

Capturing frames

In order to capture frames from a video device, you must first obtain an object implementing the FrameGrabber interface. The VideoDevice objects provides several methods for that, depending on the image format required:

• The getJPEGFrameGrabber() method returns a JPEGFrameGrabber object capable of capturing frames and converting them to JPEG before handing them out. This frame grabber cannot be used with all video sources. It requires images from the video source to be in some pre-defined formats in order to be converted to JPEG. If the video source is not capable of handing out images in one of the supported formats, then no JPEGFrameGrabber can be created.
• The getRGBFrameGrabber() & getBGRFrameGrabber() methods return either an RGBFrameGrabber or BGRFrameGrabber object capable of capturing frames and converting them to RGB24 / BGR24 before handing them out. Here again, these frame grabbers cannot be used with all video sources. They require images from the video source to be in some pre-defined formats in order to be converted to RGB24 or BGR24. If the video source is not capable of handing out images in one of the supported formats, then no RGBFrameGrabber / BGRFrameGrabber can be created.
• The getYUVFrameGrabber() & getYVUFrameGrabber() methods return either an YUVFrameGrabber or YVUFrameGrabber object capable of capturing frames and converting them to YUV420 / YVU420 before handing them out. Here again, these frame grabbers cannot be used with all video sources. They require images from the video source to be in some pre-defined formats in order to be converted to YUV420 or YVU420. If the video source is not capable of handing out images in one of the supported formats, then no YUVFrameGrabber / YVUFrameGrabber can be created.
• The getRawFrameGrabber() methods return a RawFrameGrabber object capable of capturing frames in one of the supported image formats, as reported by the getFormatList() method of DeviceInfo objects. Captured frames are handed out straight away to the caller, without any other form of processing.
• The getJPEGFrameGrabber() methods return a JPEGFrameGrabber object capable of capturing frames and JPEG-encoding them before handing them out.

To check whether JPEG, RGB, BGR, YUV or YVU conversion is supported by a VideoDevice object, call its supportJPEGConversion(), supportRGBConversion(), supportBGRConversion(), supportYUVConversion() or supportYVUConversion() method. Similarly to VideoDevice objects, once the frame grabber is no longer used, its resources must be released. This is achieved by calling the releaseFrameGrabber(). See the FrameGrabber interface for more information on how to capture frames.

Tuners

A list of available tuners can be obtained by calling the getTunerList() method. Each Tuner object in the list represents an individual tuner and allow getting/setting of various parameters, including the frequency.

Video controls

A list of available video controls can be obtained by calling the getControlList() method. Each control contains detailed information about its type and acceptable values. Controls have a pair of get & set methods to adjust their values. Once again, when no longer used, resources taken up by video controls must be released by calling releaseControlList(). See the ControlList and Control classes for more information on how to use them.

Author:

gilles

Constructor Summary

Constructors

Constructor and Description
VideoDevice(String dev) This constructor builds a VideoDevice using the full path to its device file.

Method Summary

Modifier and Type	Method and Description
BGRFrameGrabber	getBGRFrameGrabber(int w, int h, int input, int std) This method returns a BGRFrameGrabber associated with this video device.
BGRFrameGrabber	getBGRFrameGrabber(int w, int h, int input, int std, ImageFormat imf) This method returns a BGRFrameGrabber associated with this video device.
ControlList	getControlList() This method returns a list of Controls associated with this video device.
String	getDevicefile() This method returns the full path to the device file associated with this video device.
DeviceInfo	getDeviceInfo() This method creates a DeviceInfo object which contains information about this video device.
JPEGFrameGrabber	getJPEGFrameGrabber(int w, int h, int input, int std, int q) This method returns a JPEGFrameGrabber associated with this video device.
JPEGFrameGrabber	getJPEGFrameGrabber(int w, int h, int input, int std, int q, ImageFormat imf) This method returns a JPEGFrameGrabber associated with this video device.
RawFrameGrabber	getRawFrameGrabber(int w, int h, int input, int std) This method returns a RawFrameGrabber associated with this video device.
RawFrameGrabber	getRawFrameGrabber(int w, int h, int input, int std, ImageFormat format) This method returns a RawFrameGrabber associated with this video device.
RGBFrameGrabber	getRGBFrameGrabber(int w, int h, int input, int std) This method returns a RGBFrameGrabber associated with this video device.
RGBFrameGrabber	getRGBFrameGrabber(int w, int h, int input, int std, ImageFormat imf) This method returns a RGBFrameGrabber associated with this video device.
TunerList	getTunerList() This method returns the TunerList of Tuners available on this VideoDevice.
YUVFrameGrabber	getYUVFrameGrabber(int w, int h, int input, int std) This method returns a YUVFrameGrabber associated with this video device.
YUVFrameGrabber	getYUVFrameGrabber(int w, int h, int input, int std, ImageFormat imf) This method returns a YUVFrameGrabber associated with this video device.
YVUFrameGrabber	getYVUFrameGrabber(int w, int h, int input, int std) This method returns a YVUFrameGrabber associated with this video device.
YVUFrameGrabber	getYVUFrameGrabber(int w, int h, int input, int std, ImageFormat imf) This method returns a YVUFrameGrabber associated with this video device.
void	release() This method releases resources used by this VideoDevice.
void	release(boolean wait) This method releases resources used by this VideoDevice.
void	releaseControlList() This method releases the list of Controls returned by getControlList().
void	releaseFrameGrabber() This method releases the FrameGrabber object allocated previously with getRGBFrameGrabber(), getBGRFrameGrabber(), getYUVFrameGrabber(), getYVUFrameGrabber(), getJPEGFrameGrabber() or getRawFrameGrabber().
void	setThreadFactory(ThreadFactory factory) This method sets the ThreadFactory to be used when new threads are created by frame grabbers created for this video device.
boolean	supportBGRConversion() This method specifies whether frames captured from this video device can be converted to BGR24 before being handed out.
boolean	supportJPEGConversion() This method specifies whether frames captured from this video device can be JPEG-encoded before being handed out.
boolean	supportRGBConversion() This method specifies whether frames captured from this video device can be converted to RGB24 before being handed out.
boolean	supportYUVConversion() This method specifies whether frames captured from this video device can be converted to YUV420 before being handed out.
boolean	supportYVUConversion() This method specifies whether frames captured from this video device can be converted to YVU420 before being handed out.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VideoDevice

public VideoDevice(String dev)
            throws V4L4JException

This constructor builds a VideoDevice using the full path to its device file. When finished, resources must be released by calling release().

Parameters:

dev - the path to the device file

Throws:

V4L4JException - if the device file is not accessible

Method Detail

release

public void release()

This method releases resources used by this VideoDevice. This method WILL wait() if a FrameGrabber or/and a ControlList is in use, until releaseFrameGrabber() or/and releaseControlList() have been called.

Throws:

StateException - if a call to release() is already in progress.

release

public void release(boolean wait)

This method releases resources used by this VideoDevice. If the argument wait is true, this method will wait() if a FrameGrabber or/and a ControlList are in use, until releaseFrameGrabber() or/and releaseControlList() have been called. It is in effect identical to release(). If argument wait is false, this method will throw a ReleaseException if a FrameGrabber or/and a ControlList are in use. Otherwise, it will just proceed with the release of resources.

Parameters:

wait - whether or not this method should block and wait until releaseFrameGrabber() or/and releaseControlList() have been called

Throws:

StateException - if this video device has already been released, or is being released.

ReleaseException - if there either the releaseFrameGrabber() or the releaseControlList() have not been called, and we asked to not wait (argument wait is false)

getDeviceInfo

public DeviceInfo getDeviceInfo()
                         throws V4L4JException

This method creates a DeviceInfo object which contains information about this video device. This method (as well as getTunerList() does not have an equivalent release method. In other word, the returned DeviceInfo object does not need to be released before releasing the VideoDevice.

Returns:

a DeviceInfo object describing this video device.

Throws:

V4L4JException - if there was an error gathering information about the video device. This happens for example, when another application is currently using the device.

See Also:

DeviceInfo

getDevicefile

public String getDevicefile()

This method returns the full path to the device file associated with this video device.

Returns:

the full path to the device file

getControlList

public ControlList getControlList()

This method returns a list of Controls associated with this video device. The ControlList must be released when no longer used by calling releaseControlList().

Returns:

a list of available Controls

Throws:

StateException - if the VideoDevice has been released.

releaseControlList

public void releaseControlList()

This method releases the list of Controls returned by getControlList(). This method must be called when the list of Controls is no longer used, so low-level resources can be freed. This method does nothing if a list of Controls has never been allocated in the first place.

supportJPEGConversion

public boolean supportJPEGConversion()

This method specifies whether frames captured from this video device can be JPEG-encoded before being handed out. If this video device can capture frames in a native format that can be encoded in JPEG, then this method returns true, and calls to getJPEGFrameGrabber(int, int, int, int, int) and getJPEGFrameGrabber(int, int, int, int, int, ImageFormat) will succeed. If this method returns false,no JPEGFrameGrabbers can be instantiated. One alternative is to use a raw frame grabber, returned by getRawFrameGrabber(int, int, int, int) or getRawFrameGrabber(int, int, int, int, ImageFormat).
If JPEGFrameGrabbers cannot be created for your video device, please let the author know about it so JPEG-encoding can be added. See the README file on how to submit reports.

Returns:

whether or not frames captured by this video device can be JPEG-encoded.

supportRGBConversion

public boolean supportRGBConversion()

This method specifies whether frames captured from this video device can be converted to RGB24 before being handed out. If this video device can capture frames in a native format that can be converted to RGB24, then this method returns true, and calls to getRGBFrameGrabber(int, int, int, int) and getRGBFrameGrabber(int, int, int, int, ImageFormat) will succeed. If this method returns false,no RGBFrameGrabbers can be instantiated. One alternative is to use a raw frame grabber, returned by getRawFrameGrabber(int, int, int, int) or getRawFrameGrabber(int, int, int, int, ImageFormat).
If RGBFrameGrabbers cannot be created for your video device, please let the author know about it so RGB24-encoding can be added. See the README file on how to submit reports.

Returns:

whether or not frames captured by this video device can be RGB24-encoded.

supportBGRConversion

public boolean supportBGRConversion()

This method specifies whether frames captured from this video device can be converted to BGR24 before being handed out. If this video device can capture frames in a native format that can be converted to BGR24, then this method returns true, and calls to getBGRFrameGrabber(int, int, int, int) and getBGRFrameGrabber(int, int, int, int, ImageFormat) will succeed. If this method returns false,no BGRFrameGrabbers can be instantiated. One alternative is to use a raw frame grabber, returned by getRawFrameGrabber(int, int, int, int) or getRawFrameGrabber(int, int, int, int, ImageFormat).
If BGRFrameGrabbers cannot be created for your video device, please let the author know about it so BGR24-encoding can be added. See the README file on how to submit reports.

Returns:

whether or not frames captured by this video device can be BGR24-encoded.

supportYUVConversion

public boolean supportYUVConversion()

This method specifies whether frames captured from this video device can be converted to YUV420 before being handed out. If this video device can capture frames in a native format that can be converted to YUV420, then this method returns true, and calls to getYUVFrameGrabber(int, int, int, int) and getYUVFrameGrabber(int, int, int, int, ImageFormat) will succeed. If this method returns false, no YUVFrameGrabbers can be instantiated. One alternative is to use a raw frame grabber, returned by getRawFrameGrabber(int, int, int, int) or getRawFrameGrabber(int, int, int, int, ImageFormat).
If a YUVFrameGrabber cannot be created for your video device, please let the author know about it so YUV-encoding can be added. See the README file on how to submit reports.

Returns:

whether or not frames captured by this video device can be YUV420-encoded.

supportYVUConversion

public boolean supportYVUConversion()

This method specifies whether frames captured from this video device can be converted to YVU420 before being handed out. If this video device can capture frames in a native format that can be converted to YVU420, then this method returns true, and calls to getYVUFrameGrabber(int, int, int, int) and getYVUFrameGrabber(int, int, int, int, ImageFormat) will succeed. If this method returns false, no YVUFrameGrabbers can be instantiated. One alternative is to use a raw frame grabber, returned by getRawFrameGrabber(int, int, int, int) or getRawFrameGrabber(int, int, int, int, ImageFormat).
If a YVUFrameGrabber cannot be created for your video device, please let the author know about it so YVU-encoding can be added. See the README file on how to submit reports.

Returns:

whether or not frames captured by this video device can be YVU420-encoded.

getJPEGFrameGrabber

public JPEGFrameGrabber getJPEGFrameGrabber(int w,
                                            int h,
                                            int input,
                                            int std,
                                            int q,
                                            ImageFormat imf)
                                     throws V4L4JException

This method returns a JPEGFrameGrabber associated with this video device. Captured frames will be JPEG-encoded before being handed out. To obtain a JPEGFrameGrabber, this video device must support an appropriate image format that v4l4j can convert to JPEG. If it does not, this method will throw an ImageFormatException. To check if JPEG-encoding is possible, call supportJPEGConversion(). The list of image formats supported by this video device that can be JPEG-encoded is obtained by calling ImageFormatList.getJPEGEncodableFormats() (getDeviceInfo().getFormatList().getJPEGEncodableFormats()). The returned JPEGFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If JPEGFrameGrabbers cannot be created for your video device, please let the author know so support for it can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants)

q - the JPEG image quality (the higher, the better the quality), within the range V4L4JConstants.MIN_JPEG_QUALITY, V4L4JConstants.MAX_JPEG_QUALITY.

imf - the ImageFormat the frames should be captured in before being JPEG-encoded. This image format must be one that v4l4j can convert to JPG, ie it must be in the list returned by this video device's ImageFormatList.getJPEGEncodableFormats(). You can get this video device's ImageFormatList by calling getDeviceInfo().getFormatList(). If this argument is null, v4l4j will pick the first image format it knows how to JPEG-encode.

Returns:

a JPEGFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if the chosen image format can not be JPEG-encoded. If no image format was specified (null), then this video device does not have an image format that can be JPEG encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before a JPEGFrameGrabber can be allocated, or if the VideoDevice has been released.

getJPEGFrameGrabber

public JPEGFrameGrabber getJPEGFrameGrabber(int w,
                                            int h,
                                            int input,
                                            int std,
                                            int q)
                                     throws V4L4JException

This method returns a JPEGFrameGrabber associated with this video device. Captured frames will be JPEG-encoded before being handed out. The video device must support an appropriate image format that v4l4j can convert to JPEG. If it does not, this method will throw an ImageFormatException. To check if JPEG-encoding is possible, call supportJPEGConversion(). Among all the image formats the video device supports, v4l4j will choose the first one that can be JPEG encoded. If you prefer to specify which image format is to be used, call getJPEGFrameGrabber(int, int, int, int, int, ImageFormat) instead. This is sometimes required because some video devices may have a lower frame rate with some image formats, and a higher one with others. So far, testing is the only way to find out. The returned JPEGFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If a JPEGFrameGrabber cannot be created for your video device, please let the author know so support for it can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants)

q - the JPEG image quality (the higher, the better the quality), within the range V4L4JConstants.MIN_JPEG_QUALITY, V4L4JConstants.MAX_JPEG_QUALITY.

Returns:

a JPEGFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if the video device does not have any image formats which can be JPEG-encoded.If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before a JPEGFrameGrabber can be allocated, or if the VideoDevice has been released.

getRGBFrameGrabber

public RGBFrameGrabber getRGBFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std,
                                          ImageFormat imf)
                                   throws V4L4JException

This method returns a RGBFrameGrabber associated with this video device. Captured frames will be converted to RGB24 before being handed out. The video device must support an appropriate image format that v4l4j can convert to RGB24. If it does not, this method will throw an ImageFormatException. To check if RGB24 conversion is possible, call supportRGBConversion(). The returned RGBFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If RGBFrameGrabbers cannot be created for your video device, please let the author know about it so RGB24-encoding can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants)

imf - the ImageFormat the frames should be captured in before being converted to RGB24. This image format must be one that v4l4j can convert to RGB24, ie it must be in the list returned by this video device's ImageFormatList.getRGBEncodableFormats(). You can get this video device's ImageFormatList by calling getDeviceInfo().getFormatList(). If this argument is null, v4l4j will pick the first image format it can RGB24-encode.

Returns:

a RGBFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if the chosen image format can not be RGB24-encoded. If no image format was specified (null), then this video device does not have an image format that can be RGB24-encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before another FrameGrabber can be allocated, or if the VideoDevice has been released.

getRGBFrameGrabber

public RGBFrameGrabber getRGBFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std)
                                   throws V4L4JException

This method returns a RGBFrameGrabber associated with this video device. Captured frames will be RGB24-encoded before being handed out. The video device must support an appropriate image format that v4l4j can convert to RGB24. If it does not, this method will throw an ImageFormatException. To check if RGB24-encoding is possible, call supportRGBConversion(). Among all the image formats the video device supports, v4l4j will choose the first one that can be RGB24 encoded. If you prefer to specify which image format is to be used, call getRGBFrameGrabber(int, int, int, int, ImageFormat) instead. This is sometimes required because some video device have a lower frame rate with some image formats, and a higher one with others. So far, testing is the only way to find out. The returned RGBFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If RGBFrameGrabbers cannot be created for your video device, please let the author know about it so RGB24-encoding can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants).

Returns:

a RGBFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if this video device does not have an image format that can be RGB24-encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before a RGBFrameGrabber can be allocated, or if the VideoDevice has been released.

getBGRFrameGrabber

public BGRFrameGrabber getBGRFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std,
                                          ImageFormat imf)
                                   throws V4L4JException

This method returns a BGRFrameGrabber associated with this video device. Captured frames will be converted to BGR24 before being handed out. The video device must support an appropriate image format that v4l4j can convert to BGR24. If it does not, this method will throw an ImageFormatException. To check if BGR24 conversion is possible, call supportBGRConversion(). The returned BGRFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If BGRFrameGrabbers cannot be created for your video device, please let the author know about it so BGR24-encoding can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants)

imf - the ImageFormat the frames should be captured in before being converted to BGR24. This image format must be one that v4l4j can convert to BGR24, ie it must be in the list returned by this video device's ImageFormatList.getBGREncodableFormats(). You can get this video device's ImageFormatList by calling getDeviceInfo().getFormatList(). If this argument is null, v4l4j will pick the first image format it can BGR24-encode.

Returns:

a BGRFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if the chosen image format can not be BGR24-encoded. If no image format was specified (null), then this video device does not have an image format that can be BGR24-encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before another FrameGrabber can be allocated, or if the VideoDevice has been released.

getBGRFrameGrabber

public BGRFrameGrabber getBGRFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std)
                                   throws V4L4JException

This method returns a BGRFrameGrabber associated with this video device. Captured frames will be BGR24-encoded before being handed out. The video device must support an appropriate image format that v4l4j can convert to BGR24. If it does not, this method will throw an ImageFormatException. To check if BGR24-encoding is possible, call supportBGRConversion(). Among all the image formats the video device supports, v4l4j will choose the first one that can be BGR24 encoded. If you prefer to specify which image format is to be used, call getBGRFrameGrabber(int, int, int, int, ImageFormat) instead. This is sometimes required because some video device have a lower frame rate with some image formats, and a higher one with others. So far, testing is the only way to find out. The returned BGRFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If BGRFrameGrabbers cannot be created for your video device, please let the author know about it so BGR24-encoding can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants).

Returns:

a BGRFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if this video device does not have an image format that can be BGR24-encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before a BGRFrameGrabber can be allocated, or if the VideoDevice has been released.

getYUVFrameGrabber

public YUVFrameGrabber getYUVFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std,
                                          ImageFormat imf)
                                   throws V4L4JException

This method returns a YUVFrameGrabber associated with this video device. Captured frames will be converted to YUV420 before being handed out. The video device must support an appropriate image format that v4l4j can convert to YUV420. If it does not, this method will throw an ImageFormatException. To check if YUV420 conversion is possible, call supportYUVConversion(). The returned YUVFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If YUVFrameGrabbers cannot be created for your video device, please let the author know about it so YUV420-encoding can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants)

imf - the ImageFormat the frames should be captured in before being converted to YUV420. This image format must be one that v4l4j can convert to YUV420, ie it must be in the list returned by this video device's ImageFormatList.getYUVEncodableFormats(). You can get this video device's ImageFormatList by calling getDeviceInfo().getFormatList(). If this argument is null, v4l4j will pick the first image format it can YUV420-encode.

Returns:

a YUVFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if the chosen image format can not be YUV420-encoded. If no image format was specified (null), then this video device does not have an image format that can be YUV420-encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before another FrameGrabber can be allocated, or if the VideoDevice has been released.

getYUVFrameGrabber

public YUVFrameGrabber getYUVFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std)
                                   throws V4L4JException

This method returns a YUVFrameGrabber associated with this video device. Captured frames will be YUV420-encoded before being handed out. The video device must support an appropriate image format that v4l4j can convert to YUV420. If it does not, this method will throw an ImageFormatException. To check if YUV420-encoding is possible, call supportYUVConversion(). Among all the image formats the video device supports, v4l4j will choose the first one that can be YUV420 encoded. If you prefer to specify which image format is to be used, call getYUVFrameGrabber(int, int, int, int, ImageFormat) instead. This is sometimes required because some video device have a lower frame rate with some image formats, and a higher one with others. So far, testing is the only way to find out. The returned YUVFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If YUVFrameGrabbers cannot be created for your video device, please let the author know about it so YUV420-encoding can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants).

Returns:

a YUVFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if this video device does not have an image format that can be YUV420-encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before a YUVFrameGrabber can be allocated, or if the VideoDevice has been released.

getYVUFrameGrabber

public YVUFrameGrabber getYVUFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std,
                                          ImageFormat imf)
                                   throws V4L4JException

This method returns a YVUFrameGrabber associated with this video device. Captured frames will be converted to YVU420 before being handed out. The video device must support an appropriate image format that v4l4j can convert to YVU420. If it does not, this method will throw an ImageFormatException. To check if YVU420 conversion is possible, call supportYVUConversion(). The returned YVUFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If YVUFrameGrabbers cannot be created for your video device, please let the author know about it so YVU420-encoding can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants)

imf - the ImageFormat the frames should be captured in before being converted to YVU420. This image format must be one that v4l4j can convert to YVU420, ie it must be in the list returned by this video device's ImageFormatList.getYVUEncodableFormats(). You can get this video device's ImageFormatList by calling getDeviceInfo().getFormatList(). If this argument is null, v4l4j will pick the first image format it can YVU420-encode.

Returns:

a YVUFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if the chosen image format can not be YVU420-encoded. If no image format was specified (null), then this video device does not have an image format that can be YVU420-encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a AbstractGrabber already exists and must be released before another FrameGrabber can be allocated, or if the VideoDevice has been released.

getYVUFrameGrabber

public YVUFrameGrabber getYVUFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std)
                                   throws V4L4JException

This method returns a YVUFrameGrabber associated with this video device. Captured frames will be YVU420-encoded before being handed out. The video device must support an appropriate image format that v4l4j can convert to YVU420. If it does not, this method will throw an ImageFormatException. To check if YVU420-encoding is possible, call supportYVUConversion(). Among all the image formats the video device supports, v4l4j will choose the first one that can be YVU420 encoded. If you prefer to specify which image format is to be used, call getYVUFrameGrabber(int, int, int, int, ImageFormat) instead. This is sometimes required because some video device have a lower frame rate with some image formats, and a higher one with others. So far, testing is the only way to find out. The returned YVUFrameGrabber must be released when no longer used by calling releaseFrameGrabber().
If YUVFrameGrabbers cannot be created for your video device, please let the author know about it so YVU420-encoding can be added. See the README file on how to submit reports.

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex()

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants).

Returns:

a YVUFrameGrabber associated with this video device, if supported.

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - if this video device does not have an image format that can be YVU420-encoded. If you encounter such device, please let the author know so support for it can be added. See the README file on how to submit reports.

CaptureChannelException - if the given channel number value is not valid

ImageDimensionException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists and must be released before a YVUFrameGrabber can be allocated, or if the VideoDevice has been released.

getRawFrameGrabber

public RawFrameGrabber getRawFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std,
                                          ImageFormat format)
                                   throws V4L4JException

This method returns a RawFrameGrabber associated with this video device. Captured frames will be handed out in the same format as received from the driver and can be chosen amongst the ones supported by this video device. To enumerate the supported ImageFormats, check the ImageFormatList returned by DeviceInfo.getFormatList(). The returned RawFrameGrabber must be released when no longer used by calling releaseFrameGrabber().

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex().

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants)

format - the desired image format. A list of supported ImageFormats can be obtained by calling getDeviceInfo().getFormatList(). If this argument is null, an ImageFormatException is thrown.

Returns:

the FrameGrabber associated with this video device

Throws:

VideoStandardException - if the chosen video standard is not supported

ImageFormatException - If the image format argument is null

CaptureChannelException - if the given channel number value is not valid

ImageDimensionsException - if the given image dimensions are not supported

InitialisationException - if the video device file can not be initialised

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists or if the VideoDevice has been released.

getRawFrameGrabber

public RawFrameGrabber getRawFrameGrabber(int w,
                                          int h,
                                          int input,
                                          int std)
                                   throws V4L4JException

This method returns a RawFrameGrabber associated with this video device. Captured frames will be handed out in the same format as received from the driver. The chosen format is the one returned by getDeviceInfo().getFormatList().getNativeFormats().get(0). The RawFrameGrabber must be released when no longer used by calling releaseFrameGrabber().

Parameters:

w - the desired frame width. This value may be adjusted to the closest supported by hardware.

h - the desired frame height. This value may be adjusted to the closest supported by hardware.

input - the input index, as returned by InputInfo.getIndex().

std - the video standard, as returned by InputInfo.getSupportedStandards() (see V4L4JConstants)

Returns:

a RawFrameGrabber associated with this video device.

Throws:

VideoStandardException - if the chosen video standard is not supported.

CaptureChannelException - if the given channel number value is not valid.

ImageDimensionException - if the given image dimensions are not supported.

InitialisationException - if the video device file can not be initialised.

ImageFormatException - if no image format could be found because the DeviceInfo object could not be obtained. Check if the device is not already used by another application.

V4L4JException - if there is an error applying capture parameters

StateException - if a FrameGrabber already exists or if the VideoDevice has been released.

releaseFrameGrabber

public void releaseFrameGrabber()

This method releases the FrameGrabber object allocated previously with getRGBFrameGrabber(), getBGRFrameGrabber(), getYUVFrameGrabber(), getYVUFrameGrabber(), getJPEGFrameGrabber() or getRawFrameGrabber(). This method must be called when the FrameGrabber object is no longer used, so low-level resources can be freed. This method does nothing if no FrameGrabber object has been allocated in the first place.

getTunerList

public TunerList getTunerList()
                       throws NoTunerException

This method returns the TunerList of Tuners available on this VideoDevice. Tuners in this list can be used to control individual physical tuners on the video device and get signal information form them. Check the documentation of the Tuner class for more information. This method (as well as getDeviceInfo() does not have an equivalent release method. In other word, the returned TunerList object does not need to be released before releasing the VideoDevice.

Returns:

a TunerList

Throws:

NoTunerException - if this video device does not have any tuners.

setThreadFactory

public void setThreadFactory(ThreadFactory factory)

This method sets the ThreadFactory to be used when new threads are created by frame grabbers created for this video device. By default, a video device instance will use the thread factory returned by Executors#defaultThreadFactory(). If this is not suitable, you can specify your own thread factory using this method.

Parameters:

factory - the ThreadFactory to use when creating new threads. If null, the default factory returned by Executors#defaultThreadFactory() will be used.