Bartosz Firyn (SarXos)

com.github.sarxos.webcam
Class Webcam

java.lang.Object
  extended by com.github.sarxos.webcam.Webcam

public class Webcam
extends Object

Webcam class. It wraps webcam device obtained from webcam driver.

Author:
Bartosz Firyn (bfiryn)

Method Summary
static boolean addDiscoveryListener(WebcamDiscoveryListener l)
          Add new webcam discovery listener.
 boolean addWebcamListener(WebcamListener l)
          Add webcam listener.
 boolean close()
          Close the webcam.
 Dimension[] getCustomViewSizes()
           
static Webcam getDefault()
          Will discover and return first webcam available in the system.
static Webcam getDefault(long timeout)
          Will discover and return first webcam available in the system.
static Webcam getDefault(long timeout, TimeUnit tunit)
          Will discover and return first webcam available in the system.
 WebcamDevice getDevice()
          Return underlying webcam device.
static WebcamDiscoveryListener[] getDiscoveryListeners()
           
static WebcamDiscoveryService getDiscoveryService()
          Return discovery service.
static WebcamDriver getDriver()
          Return webcam driver.
 BufferedImage getImage()
          Capture image from webcam and return it.
 ByteBuffer getImageBytes()
          Get RAW image ByteBuffer.
 String getName()
          Get webcam name (device name).
 Dimension getViewSize()
          Get current webcam resolution in pixels.
 Dimension[] getViewSizes()
          Return list of supported view sizes.
 WebcamListener[] getWebcamListeners()
           
 int getWebcamListenersCount()
           
static List<Webcam> getWebcams()
          Get list of webcams to use.
static List<Webcam> getWebcams(long timeout)
          Get list of webcams to use.
static List<Webcam> getWebcams(long timeout, TimeUnit tunit)
          Get list of webcams to use.
static boolean isAutoOpenMode()
          Is auto open mode enabled.
static boolean isHandleTermSignal()
          Is TERM signal handler enabled.
 boolean isOpen()
          Is webcam open?
 boolean open()
          Open the webcam in blocking (synchronous) mode.
 boolean open(boolean async)
          Open the webcam in either blocking (synchronous) or non-blocking (asynchronous) mode.The difference between those two modes lies in the image acquisition mechanism.

In blocking mode, when user calls getImage() method, device is being queried for new image buffer and user have to wait for it to be available.

In non-blocking mode, there is a special thread running in the background which constantly fetch new images and cache them internally for further use.
static void registerDriver(Class<? extends WebcamDriver> clazz)
          Register new webcam video driver.
static void registerDriver(String clazzName)
          Register new webcam video driver.
static boolean removeDiscoveryListener(WebcamDiscoveryListener l)
          Remove discovery listener
 boolean removeWebcamListener(WebcamListener l)
          Removes webcam listener.
static void resetDriver()
          Reset webcam driver.

This method is not thread-safe!
static void setAutoOpenMode(boolean on)
          Switch all webcams to auto open mode.
 void setCustomViewSizes(Dimension[] sizes)
          Set custom resolution.
static void setDriver(Class<? extends WebcamDriver> driverClass)
          Set new video driver class to be used by webcam.
static void setDriver(WebcamDriver driver)
          Set new video driver to be used by webcam.

This method is not thread-safe!
static void setHandleTermSignal(boolean on)
          CAUTION!!!

This is experimental feature to be used mostly in in development phase.
 void setViewSize(Dimension size)
          Set new view size.
 String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

open

public boolean open()
Open the webcam in blocking (synchronous) mode.

See Also:
open(boolean)

open

public boolean open(boolean async)
Open the webcam in either blocking (synchronous) or non-blocking (asynchronous) mode.The difference between those two modes lies in the image acquisition mechanism.

In blocking mode, when user calls getImage() method, device is being queried for new image buffer and user have to wait for it to be available.

In non-blocking mode, there is a special thread running in the background which constantly fetch new images and cache them internally for further use. This cached instance is returned every time when user request new image. Because of that it can be used when timeing is very important, because all users calls for new image do not have to wait on device response. By using this mode user should be aware of the fact that in some cases, when two consecutive calls to get new image are executed more often than webcam device can serve them, the same image instance will be returned. User should use #isImageNew() method to distinguish if returned image is not the same as the previous one.

Parameters:
asynchronous - true for non-blocking mode, false for blocking

close

public boolean close()
Close the webcam.


isOpen

public boolean isOpen()
Is webcam open?

Returns:
true if open, false otherwise

getViewSize

public Dimension getViewSize()
Get current webcam resolution in pixels.

Returns:
Webcam resolution (picture size) in pixels.

getViewSizes

public Dimension[] getViewSizes()
Return list of supported view sizes. It can differ between vary webcam data sources.

Returns:

setCustomViewSizes

public void setCustomViewSizes(Dimension[] sizes)
Set custom resolution. If you are using this method you have to make sure that your webcam device can support this specific resolution.

Parameters:
sizes - the array of custom resolutions to be supported by webcam

getCustomViewSizes

public Dimension[] getCustomViewSizes()

setViewSize

public void setViewSize(Dimension size)
Set new view size. New size has to exactly the same as one of the default sized or exactly the same as one of the custom ones.

Parameters:
size - the new view size to be set
See Also:
setCustomViewSizes(Dimension[]), getViewSizes()

getImage

public BufferedImage getImage()
Capture image from webcam and return it. Will return image object or null if webcam is closed or has been already disposed by JVM.

IMPORTANT NOTE!!!

There are two possible behaviors of what webcam should do when you try to get image and webcam is actually closed. Normally it will return null, but there is a special flag which can be statically set to switch all webcams to auto open mode. In this mode, webcam will be automatically open, when you try to get image from closed webcam. Please be aware of some side effects! In case of multi-threaded applications, there is no guarantee that one thread will not try to open webcam even if it was manually closed in different thread.

Returns:
Captured image or null if webcam is closed or disposed by JVM

getImageBytes

public ByteBuffer getImageBytes()
Get RAW image ByteBuffer. It will always return buffer with 3 x 1 bytes per each pixel, where RGB components are on (0, 1, 2) and color space is sRGB.

IMPORTANT!
Some drivers can return direct ByteBuffer, so there is no guarantee that underlying bytes will not be released in next read image operation. Therefore, to avoid potential bugs you should convert this ByteBuffer to bytes array before you fetch next image.

Returns:
Byte buffer

getWebcams

public static List<Webcam> getWebcams()
                               throws WebcamException
Get list of webcams to use. This method will wait predefined time interval for webcam devices to be discovered. By default this time is set to 1 minute.

Returns:
List of webcams existing in the ssytem
Throws:
WebcamException - when something is wrong
See Also:
getWebcams(long, TimeUnit)

getWebcams

public static List<Webcam> getWebcams(long timeout)
                               throws TimeoutException,
                                      WebcamException
Get list of webcams to use. This method will wait given time interval for webcam devices to be discovered. Time argument is given in milliseconds.

Parameters:
timeout - the time to wait for webcam devices to be discovered
Returns:
List of webcams existing in the ssytem
Throws:
WebcamException - when something is wrong
TimeoutException
See Also:
getWebcams(long, TimeUnit)

getWebcams

public static List<Webcam> getWebcams(long timeout,
                                      TimeUnit tunit)
                               throws TimeoutException,
                                      WebcamException
Get list of webcams to use. This method will wait given time interval for webcam devices to be discovered.

Parameters:
timeout - the devices discovery timeout
tunit - the time unit
Returns:
List of webcams
Throws:
TimeoutException - when timeout has been exceeded
WebcamException - when something is wrong

getDefault

public static Webcam getDefault()
                         throws WebcamException
Will discover and return first webcam available in the system.

Returns:
Default webcam (first from the list)
Throws:
WebcamException - if something is really wrong
See Also:
getWebcams()

getDefault

public static Webcam getDefault(long timeout)
                         throws TimeoutException,
                                WebcamException
Will discover and return first webcam available in the system.

Parameters:
timeout - the webcam discovery timeout (1 minute by default)
Returns:
Default webcam (first from the list)
Throws:
TimeoutException - when discovery timeout has been exceeded
WebcamException - if something is really wrong
See Also:
getWebcams(long)

getDefault

public static Webcam getDefault(long timeout,
                                TimeUnit tunit)
                         throws TimeoutException,
                                WebcamException
Will discover and return first webcam available in the system.

Parameters:
timeout - the webcam discovery timeout (1 minute by default)
tunit - the time unit
Returns:
Default webcam (first from the list)
Throws:
TimeoutException - when discovery timeout has been exceeded
WebcamException - if something is really wrong
See Also:
getWebcams(long, TimeUnit)

getName

public String getName()
Get webcam name (device name). The name of device depends on the value returned by the underlying data source, so in some cases it can be human-readable value and sometimes it can be some strange number.

Returns:
Name

toString

public String toString()
Overrides:
toString in class Object

addWebcamListener

public boolean addWebcamListener(WebcamListener l)
Add webcam listener.

Parameters:
l - the listener to be added
Throws:
IllegalArgumentException - when argument is null

getWebcamListeners

public WebcamListener[] getWebcamListeners()
Returns:
All webcam listeners

getWebcamListenersCount

public int getWebcamListenersCount()
Returns:
Number of webcam listeners

removeWebcamListener

public boolean removeWebcamListener(WebcamListener l)
Removes webcam listener.

Parameters:
l - the listener to be removed
Returns:
True if listener has been removed, false otherwise

getDriver

public static WebcamDriver getDriver()
Return webcam driver. Perform search if necessary.

This method is not thread-safe!

Returns:
Webcam driver

setDriver

public static void setDriver(WebcamDriver driver)
Set new video driver to be used by webcam.

This method is not thread-safe!

Parameters:
driver - new webcam driver to be used (e.g. LtiCivil, JFM, FMJ, QTJ)
Throws:
IllegalArgumentException - when argument is null

setDriver

public static void setDriver(Class<? extends WebcamDriver> driverClass)
Set new video driver class to be used by webcam. Class given in the argument shall extend WebcamDriver interface and should have public default constructor, so instance can be created by reflection.

This method is not thread-safe!

Parameters:
driver - new video driver class to use
Throws:
IllegalArgumentException - when argument is null

resetDriver

public static void resetDriver()
Reset webcam driver.

This method is not thread-safe!


registerDriver

public static void registerDriver(Class<? extends WebcamDriver> clazz)
Register new webcam video driver.

Parameters:
clazz - webcam video driver class
Throws:
IllegalArgumentException - when argument is null

registerDriver

public static void registerDriver(String clazzName)
Register new webcam video driver.

Parameters:
clazzName - webcam video driver class name
Throws:
IllegalArgumentException - when argument is null

getDevice

public WebcamDevice getDevice()
Return underlying webcam device. Depending on the driver used to discover devices, this method can return instances of different class. By default WebcamDefaultDevice is returned when no external driver is used.

Returns:
Underlying webcam device instance

setHandleTermSignal

public static void setHandleTermSignal(boolean on)
CAUTION!!!

This is experimental feature to be used mostly in in development phase. After you set handle term signal to true, and fetch capture devices, Webcam Capture API will listen for TERM signal and try to close all devices after it has been received. This feature can be unstable on some systems!

Parameters:
on - signal handling will be enabled if true, disabled otherwise

isHandleTermSignal

public static boolean isHandleTermSignal()
Is TERM signal handler enabled.

Returns:
True if enabled, false otherwise

setAutoOpenMode

public static void setAutoOpenMode(boolean on)
Switch all webcams to auto open mode. In this mode, each webcam will be automatically open whenever user will try to get image from instance which has not yet been open. Please be aware of some side effects! In case of multi-threaded applications, there is no guarantee that one thread will not try to open webcam even if it was manually closed in different thread.

Parameters:
on - true to enable, false to disable

isAutoOpenMode

public static boolean isAutoOpenMode()
Is auto open mode enabled. Auto open mode will will automatically open webcam whenever user will try to get image from instance which has not yet been open. Please be aware of some side effects! In case of multi-threaded applications, there is no guarantee that one thread will not try to open webcam even if it was manually closed in different thread.

Returns:
True if mode is enabled, false otherwise

addDiscoveryListener

public static boolean addDiscoveryListener(WebcamDiscoveryListener l)
Add new webcam discovery listener.

Parameters:
l - the listener to be added
Returns:
True, if listeners list size has been changed, false otherwise
Throws:
IllegalArgumentException - when argument is null

getDiscoveryListeners

public static WebcamDiscoveryListener[] getDiscoveryListeners()

removeDiscoveryListener

public static boolean removeDiscoveryListener(WebcamDiscoveryListener l)
Remove discovery listener

Parameters:
l - the listener to be removed
Returns:
True if listeners list contained the specified element

getDiscoveryService

public static WebcamDiscoveryService getDiscoveryService()
Return discovery service.

Returns:
Discovery service

Bartosz Firyn (SarXos)

Copyright © 2012-2013 Bartosz Firyn (SarXos). All Rights Reserved.