au.edu.jcu.v4l4j

Interface FrameGrabber

All Known Implementing Classes:

BGRFrameGrabber, JPEGFrameGrabber, RawFrameGrabber, RGBFrameGrabber, YUVFrameGrabber, YVUFrameGrabber

public interface FrameGrabber

Objects implementing this interface provide methods to capture frames from a VideoDevice. FrameGrabbers are not instantiated directly. Instead, one of the getXXXFrameGrabber() methods must be called on a VideoDevice to obtain one. The requested height and width may be adjusted to the closest supported values. The adjusted width and height can be retrieved by calling getWidth() and getHeight().
Frame grabbers operate in push mode: you must give v4l4j an object implementing the CaptureCallback interface by calling setCaptureCallback(CaptureCallback). During capture, v4l4j will create a thread and deliver new frames to the capture callback object. By default, new threads are created by the thread factory returned by Executors.defaultThreadFactory(), but you can provide your own thread factory by calling VideoDevice.setThreadFactory(java.util.concurrent.ThreadFactory factory) prior to creating a FrameGrabber object.
A typical FrameGrabber use case is as follows:
Create the video device and frame grabber:

//create a new video device
VideoDevice vd = new VideoDevice("/dev/video0");
// vd.setThreadFactory(myThreadFactory); // set your own thread factory if required.
//Create an instance of FrameGrabber
FrameGrabber f = vd.getJPEGFrameGrabber(320, 240, 0, 0, 80);
//If supported, this frame grabber will capture frames and convert them
//to JPEG before delivering them to your application.

//Instantiate an object that implements the CaptureCallback
//interface which will receive captured frame
myCallbackObject = new MyCallbackObjectclass();

//pass it to the frame grabber.
f.setCaptureCallback(myCallbackObject);

//Now start the capture
f.startCapture();

//At this stage, myCallbackObject.nextFrame() will be called every time
//a new frame is available (see next paragraph).

//When appropriate, stop the capture
f.stopCapture();
//Release the frame grabber
vd.releaseFrameGrabber();
//Release the video device
vd.release();

In myCallbackObject, when the capture is started, the following method is called every time a new frame is available :

public void nextFrame(VideoFrame frame) {
//do something useful with frame. But make sure you recycle
//it when dealt with, so v4l4j can re-use it later on
frame.recycle();
}
For a concrete example of push mode capture which displays the video stream, see the au.edu.jcu.v4l4j.examples.SimpleViewer example application.
Again, you must recycle video frames when they are no longer used.

Only one frame grabber can be used at any one time on a given video device. Once a frame grabber is released with VideoDevice.releaseFrameGrabber(), another one can be obtained. However, when the capture is stopped with stopCapture(), it can be started again with stopCapture() without having to create a new frame grabber.

Author:

gilles

See Also:

RawFrameGrabber, JPEGFrameGrabber, RGBFrameGrabber, BGRFrameGrabber, YUVFrameGrabber, YVUFrameGrabber

Method Summary

Modifier and Type	Method and Description
int	getChannel() This method returns the video channel used to capture frames.
FrameInterval.DiscreteInterval	getFrameInterval() This method returns the current frame interval used for capture.
int	getHeight() This method returns the actual height of captured frames.
ImageFormat	getImageFormat() This method returns the native image format used by this FrameGrabber.
int	getNumberOfRecycledVideoFrames() This method returns the number of recycled video frames, ie.
int	getNumberOfVideoFrames() This method returns the number of buffers v4l4j has negotiated with the driver.
int	getStandard() This method returns the actual video standard: V4L4JConstants.STANDARD_NTSC, V4L4JConstants.STANDARD_PAL , V4L4JConstants.STANDARD_SECAM or V4L4JConstants.STANDARD_WEBCAM
Tuner	getTuner() This method returns the Tuner associated with the input of this FrameGrabber, or throws a NoTunerException if there is none.
int	getVideoInput() This method retrieves the current video input channel number.
int	getVideoStandard() This method retrieves the current video standard used by the current video input.
int	getWidth() This method returns the actual width of captured frames.
void	setCaptureCallback(CaptureCallback callback) setCaptureCallback sets the CaptureCallback object which will be notified by this grabber as soon as new frames become available. This method cannot be called while the capture is active, ie.
void	setFrameInterval(int num, int denom) This method sets the frame interval used for capture.
void	setVideoInputNStandard(int inputNumber, int standard) This method adjusts the current video input number and video standard.
void	startCapture() This method starts the capture.
void	stopCapture() This method stops the capture, and recycles all @link VideoFrames.

Method Detail

getImageFormat

ImageFormat getImageFormat()

This method returns the native image format used by this FrameGrabber. The returned format specifies the image format in which frames are obtained from the device.

Returns:

the native image format used by this FrameGrabber.

Throws:

StateException - if this FrameGrabber has been already released, and therefore must not be used anymore.

getNumberOfVideoFrames

int getNumberOfVideoFrames()

This method returns the number of buffers v4l4j has negotiated with the driver. The driver stores captured frames in these buffers and returns them to v4l4j. A VideoFrame represents (and encapsulates) one of these buffers. Hence, this number is an indication of how many video frames can be delivered by v4l4j to your application before the capture blocks until a buffer is returned to the driver. Practically speaking, this number specifies how many times v4l4j can call CaptureCallback.nextFrame(VideoFrame frame) and block waiting for one of the previous frames to be recycled through VideoFrame.recycle().
You can specify how many buffers the driver should use by setting the v4l4j.num_driver_buffers property to an integer value before creating a frame grabber object. The number you specify is only an indication, and the driver can decide to allocate a different number of buffers. Before setting this number, make sure you fully understand the implications of doing this.

Returns:

the number of frame buffers used to retrieve frames from the driver

getNumberOfRecycledVideoFrames

int getNumberOfRecycledVideoFrames()

This method returns the number of recycled video frames, ie. the number of video frames are currently available to v4l4j (and the driver) to store new incoming frames. This number indicates how many more frames can be captured by v4l4j before the capture stops until you recycle one of the previous frame that was delivered to your application by calling VideoFrame.recycle().

Returns:

the number of video frames currently recycled.

See Also:

getNumberOfVideoFrames()

setFrameInterval

void setFrameInterval(int num,
                      int denom)
               throws InvalidValue

This method sets the frame interval used for capture. The frame interval defined the lapse of time (in second) between two captured frames and is the inverse of the frame rate. It may or may not be supported by the underlying hardware/driver. If not supported, calling this method throws a UnsupportedMethod exception. This method will throw an InvalidValue exception if the given frame interval value is not supported. As a guide, you can check the ResolutionInfo objects associated with the video device to find out whether frame intervals are at all supported, and if they are, what values (or range of values) are accepted. ResolutionInfo objects can be obtained for each ImageFormat. See the ImageFormat and ResolutionInfo documentation for more information.

Parameters:

num - the numerator of the frame interval to be set

denom - the denominator of the frame interval to be set

Throws:

UnsupportedMethod - if setting the frame interval is not supported.

InvalidValue - if the given frame interval value is invalid.

StateException - if capture is ongoing (the frame interval must be set when not capturing), or if this FrameGrabber has been already released, and therefore must not be used anymore.

getFrameInterval

FrameInterval.DiscreteInterval getFrameInterval()

This method returns the current frame interval used for capture. It may or may not be supported by the underlying hardware/driver. If not supported, calling this method throws a UnsupportedMethod exception.

Throws:

UnsupportedMethod - if setting the frame interval is not supported.

StateException - if capture is ongoing (the frame interval must be queried when not capturing), or if this FrameGrabber has been already released, and therefore must not be used anymore.

setVideoInputNStandard

void setVideoInputNStandard(int inputNumber,
                            int standard)
                     throws VideoStandardException,
                            CaptureChannelException

This method adjusts the current video input number and video standard.

Throws:

VideoStandardException - if the chosen video standard is not supported

CaptureChannelException - if the given channel number value is not valid

getVideoInput

int getVideoInput()

This method retrieves the current video input channel number.

Returns:

the current input number

getVideoStandard

int getVideoStandard()

This method retrieves the current video standard used by the current video input.

Returns:

the current standard

getTuner

Tuner getTuner()
        throws NoTunerException

This method returns the Tuner associated with the input of this FrameGrabber, or throws a NoTunerException if there is none.

Returns:

the Tuner object associated with the chosen input.

Throws:

NoTunerException - if the selected input does not have a tuner

StateException - if this FrameGrabber has been already released, and therefore must not be used anymore.

setCaptureCallback

void setCaptureCallback(CaptureCallback callback)

setCaptureCallback sets the CaptureCallback object which will be notified by this grabber as soon as new frames become available.
This method cannot be called while the capture is active, ie. in between a call to startCapture() and stopCapture().

Parameters:

callback - an object implementing the CaptureCallback interface which will receive new frames and capture exceptions.

Throws:

StateException - if this method is invoked while capture is active, ie. after a call to startCapture() and prior a call to stopCapture().

startCapture

void startCapture()
           throws V4L4JException

This method starts the capture. Frames will be delivered to the provided CaptureCallback object.

Throws:

V4L4JException - if no valid CaptureCallback object was provided (call setCaptureCallback(CaptureCallback callback) OR if the capture cannot be started

StateException - if this FrameGrabber has been already released, and therefore must not be used anymore

stopCapture

void stopCapture()

This method stops the capture, and recycles all @link VideoFrames.

Throws:

StateException - if the capture has not been started, is already stopped, or if this FrameGrabber has been already released, and therefore must not be used anymore.

getHeight

int getHeight()

This method returns the actual height of captured frames.

Returns:

the height

Throws:

StateException - if this FrameGrabber has been already released, and therefore must not be used anymore.

getWidth

int getWidth()

This method returns the actual width of captured frames.

Returns:

the width

Throws:

StateException - if this FrameGrabber has been already released, and therefore must not be used anymore.

getChannel

int getChannel()

This method returns the video channel used to capture frames.

Returns:

the channel

Throws:

StateException - if this FrameGrabber has been already released, and therefore must not be used anymore.

getStandard

int getStandard()

This method returns the actual video standard: V4L4JConstants.STANDARD_NTSC, V4L4JConstants.STANDARD_PAL , V4L4JConstants.STANDARD_SECAM or V4L4JConstants.STANDARD_WEBCAM

Returns:

the video standard

Throws:

StateException - if this FrameGrabber has been already released, and therefore must not be used anymore.