Package au.edu.jcu.v4l4j

Video4Linux4java Main Package

See: Description

Interface Summary

Interface	Description
CaptureCallback	Objects implementing this interface receive notifications from frame grabbers when new captured frames become available, or an exception occurs during a capture.
FrameGrabber	Objects implementing this interface provide methods to capture frames from a VideoDevice.
VideoFrame	Objects implementing this interface represent a single video frame captured by v4l4j.

Class Summary

Class	Description
BGRFrameGrabber	Objects of this class are used to retrieve BGR24-encoded frames from a VideoDevice.
Control	Objects of this class represent a video source control of any nature.
ControlList	Objects of this class encapsulate a list of video source Control.
DeviceInfo	Objects of this class encapsulate the following information about a video device: its device file, the name of the video device, a list of InputInfo objects providing information about each video input, a list of ImageFormats, capture resolutions (ResolutionInfo) and frame intervals supported by the video device.
FrameInterval	This class encapsulates information about supported frame intervals for a given image format and resolution.
FrameInterval.DiscreteInterval	This class encapsulates information about a discrete frame interval, expressed as a numerator and denominator.
FrameInterval.StepwiseInterval	A continuous frame interval is a bounded frame interval.
ImageFormat	Objects of this class represent an image format (YUV, RGB, GREY, BGR, ...) and its supported capture resolutions and frame intervals.
ImageFormatList	ImageFormatList objects group together a list of native ImageFormats capture resolutions and frame intervals supported by a VideoDevice.
InputInfo	Objects of this class encapsulate information about a video input. The name of this input The supported standards (V4L4JConstants.STANDARD_PAL, V4L4JConstants.STANDARD_SECAM, V4L4JConstants.STANDARD_NTSC or V4L4JConstants.STANDARD_WEBCAM) The input type (V4L4JConstants.INPUT_TYPE_TUNER or V4L4JConstants.INPUT_TYPE_CAMERA) The TunerInfo object associated with this input if it is connected to a tuner. You do not directly instantiate InputInfo objects.
JPEGFrameGrabber	Objects of this class are used to retrieve JPEG-encoded frames from a VideoDevice.
RawFrameGrabber	This class provides methods to capture raw frames from a VideoDevice.
ResolutionInfo	This class encapsulates information about the supported capture resolutions and frame intervals for a given ImageFormat.
ResolutionInfo.DiscreteResolution	This class represents a possible resolution supported by a video device.
ResolutionInfo.StepwiseResolution	This class encapsulates information about supported capture resolutions for a video device.
RGBFrameGrabber	Objects of this class are used to retrieve RGB frames from a VideoDevice.
Tuner	Instances of this class are used to represent a tuner attached to a video input.
TunerInfo	Object of this class encapsulate information about a tuner: its type: V4L4JConstants.TUNER_TYPE_RADIO or V4L4JConstants.TUNER_TYPE_TV, the frequency unit: V4L4JConstants.FREQ_KHZ or V4L4JConstants.FREQ_MHZ, the name of the tuner, the index of the tuner, and the lowest and highest tunable frequencies.
TunerList	Objects of this class encapsulate a list of available Tuners.
V4L4JConstants
V4L4JRaster	We need our own implementation of a WritableRaster because we cannot create one with Raster.createInterleavedRaster(DataBuffer, int, int, int, int, int[], Point) as we cannot pass a V4L4JDataBuffer to it, it will throw an exception because it expects a DataBufferByte object.
VideoDevice	An instance of a VideoDevice object represents an existing V4L video device.
YUVFrameGrabber	Objects of this class are used to retrieve YUV420-encoded frames from a VideoDevice.
YVUFrameGrabber	Objects of this class are used to retrieve YVU420-encoded frames from a VideoDevice.

Enum Summary

Enum	Description
FrameInterval.Type
ResolutionInfo.Type	The Type enumeration defines how the supported resolutions are expressed.

Package au.edu.jcu.v4l4j Description

Video4Linux4java Main Package

Introduction

The Video4Linux (V4L) API provides data structures & methods to access and control video input & output hardware, as well as radio tuners. The API is divided into several interfaces, including video capture, video overlay, video output & teletext interfaces. v4l4j provides access to the video capture interface of V4L only. v4l4j allows you to retrieve information about a video device, access its video controls & tuners and grab images from it.

Examples

v4l4j comes with many simple, easy-to-follow example applications in the au.edu.jcu.v4l4j.examples package. It is strongly suggested you take a look at them as you read these JavaDoc pages as they help illustrate concepts crucial to a correct use of this API.

Usage

Video device object

To use v4l4j, the first step is to create a VideoDevice object, which represents a physical video input hardware device. This includes webcams and capture / tuner cards. The only pre-requisite is that your hardware must be supported and its driver loaded. Creating a VideoDevice is simple. You only need the path to a valid device file to create this object:
VideoDevice vd = new VideoDevice("/dev/video0");
As it is the case most of the time when interacting with hardware, you must release resources and data structures when finished. All v4l4j classes follow this rule, including VideoDevices. The rare exceptions are clearly identified in their java documentation.
vd.release();
Once an object has been release()d, it must not be reused, and all references to it must be discarded, by explicitly setting them to null for example. Calling any release() method more than once will throw a StateException.
VideoDevice objects give you access to 4 broad categories:

• information about the underlying hardware through DeviceInfo objects,
• a variety of controls through ControlList objects, and
• a frame capture facility using FrameGrabber objects.
• an interface to control any tuners, using TunerList objects.

Each of these can be obtained independently from each other, by calling the appropriate method on a VideoDevice instance. This flexibility allows an application to create a GUI which provides access to video controls, while another application is streaming video from the device. For this to work, the device driver must allows multiple applications to open the device file simultaneously. As an example, the UVC driver works this way.

Video hardware information

With a valid VideoDevice object, you can retrieve information about the underlying hardware and find out, for example how many video inputs the device has, how many tuners are available, the set of supported video standards and capture resolutions. This kind of information is contained in a DeviceInfo object. You can get a reference to a DeviceInfo object for a given video device by calling VideoDevice.getDeviceInfo() on the VideoDevice object. See the documentation of the VideoDevice and DeviceInfo classes for more information.

Video controls

Video capture devices usually have a set of controls which influence various parameters related to the video stream. Examples are brightness, contrast, gamma & white balance. A single control is represented by Control object. The set of supported controls for a given video device hardware-dependent and is embedded into a ControlList object, which can be obtained by calling VideoDevice.getControlList(). The ControlList object must be released when controls are no longer needed. This is done by calling VideoDevice.releaseControlList(). Again, once released, neither the ControlList nor individual Controls must be used, and any reference to them must be discarded, by explicitly setting them to null for example. For more information, check the documentation of the Control and ControlList classes.

Video capture

Capture in v4l4j is extremely simple. v4l4j hands out captured frames in a VideoFrame object, either in a native image format ( also referred to as raw format in v4l4j's documentation) or one of the 5 convenience image formats (JPEG, RGB24, BGR24, YUV420 or YVU420). Each of these 6 image formats is output by a dedicated frame grabber object, which will grab frames and convert them to that format if required. The set of native ImageFormats supported by a video device can be obtained using the DeviceInfo object (see paragraph "Video hardware information" above). When capturing in a native format, v4l4j simply hands out the captured frame without further processing. When capturing in one of the convenience formats, v4l4j will transparently convert the image.
Frame grabbers operate in push mode: the frame grabber delivers captured frames to a callback object you provide. Frame capture in v4l4j is done using objects implementing the FrameGrabber interface. Check the documentation of the FrameGrabber class for more information.

Tuners

v4l4j provides access to tuners if present in the video device. A TunerList object can be obtained by calling VideoDevice.getTunerList(). Note that the tuner list need not be released when finished.