au.edu.jcu.v4l4j

Interface VideoFrame

public interface VideoFrame

Objects implementing this interface represent a single video frame captured by v4l4j. They provide access to image data through various objects, including byte arrays and DataBuffers. During capture, v4l4j creates VideoFrames and passes them the registered CaptureCallback object. Check the FrameGrabber class for more information on how to perform a capture.
When accessing the image data as a byte array, as returned by getBytes(), note that the size of returned byte array can be longer than the actual image size. What this means is that you should use getFrameLength() to figure out how many elements in the byte array are actually used by the image instead of relying on byte[].length.
From the moment a VideoFrame is returned by a frame grabber, the VideoFrame object itself as well as any of the objects obtained through its methods can be used. When the VideoFrame and any of the objects obtained through it) are dealt with and no longer used, the VideoFrame must be recycled, which marks it as being available to v4l4j to store an upcoming image. From the moment a VideoFrame is recycled, neither the VideoFrame nor objects obtained through it can be used. Bad things will happen if you violate this rule. It is recommended that you explicitly set all references to this object, as well as references to objects obtained through this frame, to null.
Note that not all video frames are capable of returning a raster or a buffered image. For example, rasters cannot be created for compressed image formats, which means VideoFrames returned by JPEGFrameGrabbers cannot return a buffered image, and calling getBufferedImage() will throw a UnsupportedMethod exception. In the same way, video frames returned by raw frame grabbers cannot create rasters and an UnsupportedMethod exception will be thrown if getRaster() is called.

Author:

gilles

Method Summary

Modifier and Type	Method and Description
BufferedImage	getBufferedImage() This method returns the image data encapsulated in a BufferedImage object.
byte[]	getBytes() This method returns the image data as a byte array.Please note that the size of the returned byte array can be greater than the actual frame size.
long	getCaptureTime() This method returns the OS time (number of microseconds elapsed since startup) at which this video frame was captured.
DataBuffer	getDataBuffer() This method returns the image data encapsulated in a DataBuffer object.
FrameGrabber	getFrameGrabber() This method returns the frame grabber object which captured this frame
int	getFrameLength() This method returns the length of this video frame in bytes.
Raster	getRaster() This method returns the image data encapsulated in a Raster object.
long	getSequenceNumber() This method returns this video frame's sequence number (a monotonically increasing number for each captured frame).
void	recycle() This method marks this video frame as being no longer used, and ready to be reused by v4l4j.

Method Detail

getFrameGrabber

FrameGrabber getFrameGrabber()

This method returns the frame grabber object which captured this frame

Returns:

the frame grabber object which captured this frame.

getFrameLength

int getFrameLength()

This method returns the length of this video frame in bytes.

Returns:

the length of this video frame in bytes.

Throws:

StateException - if this video frame has been recycled already.

getSequenceNumber

long getSequenceNumber()

This method returns this video frame's sequence number (a monotonically increasing number for each captured frame). This number can be used to find out when a frame was dropped: if currentSequenceNumber != (previousSequenceNumber + 1) then (currentSequenceNumber - previousSequenceNumber( frames were dropped.

Returns:

this video frame's sequence number

Throws:

StateException - if this video frame has been recycled already.

getCaptureTime

long getCaptureTime()

This method returns the OS time (number of microseconds elapsed since startup) at which this video frame was captured.

Returns:

the OS time (number of microseconds elapsed since startup) at which this video frame was captured.

Throws:

StateException - if this video frame has been recycled already.

getBytes

byte[] getBytes()

This method returns the image data as a byte array.Please note that the size of the returned byte array can be greater than the actual frame size. You should not use the byte array length (as returned by byte[].length) as the length of the image. Instead, use the value returned from getFrameLength().

Returns:

the image data as a byte array. The array may be longer than the actual frame length.

Throws:

StateException - if this video frame has been recycled already.

getDataBuffer

DataBuffer getDataBuffer()

This method returns the image data encapsulated in a DataBuffer object. The data is stored as bytes in the data buffer.

Returns:

the image data encapsulated in a DataBuffer

Throws:

StateException - if this video frame has been recycled already.

getRaster

Raster getRaster()

This method returns the image data encapsulated in a Raster object. Rasters cannot be created for some image formats (including compressed formats like JPEG). In this case this method will throw a UnsupportedMethod exception.

Returns:

the image data encapsulated in a Raster object

Throws:

{@link - UnsupportedMethod} exception if the image format this video frame uses cannot be encapsulated in a Raster.

StateException - if this video frame has been recycled already.

getBufferedImage

BufferedImage getBufferedImage()

This method returns the image data encapsulated in a BufferedImage object. Buffered images cannot be created for some image formats (including raw image formats). In this case this method will throw a UnsupportedMethod exception.

Returns:

the image data encapsulated in a BufferedImage object

Throws:

{@link - UnsupportedMethod} exception if the image format this video frame uses cannot be encapsulated in a BufferedImage.

StateException - if this video frame has been recycled already.

recycle

void recycle()

This method marks this video frame as being no longer used, and ready to be reused by v4l4j. After calling this method, do not use either this object or any of the objects obtained through it (byte array, data buffer, raster, buffered image, ...) or bad things WILL happen.