com.github.sarxos.webcam
Class Webcam

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

public class Webcam
extends Object

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

Author:

Bartosz Firyn (bfiryn)

Constructor Summary

protected

Webcam(WebcamDevice device) Webcam class.

Method Summary

static boolean	addDiscoveryListener(WebcamDiscoveryListener l) Add new webcam discovery listener.
boolean	addWebcamListener(WebcamListener l) Add webcam listener.
void	close() Close the webcam.
protected void	dispose() Completely dispose capture device.
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.
String	getName() Get webcam name (device name).
protected WebcamProcessor	getProcessor()
Dimension	getViewSize() Get current webcam resolution in pixels.
Dimension[]	getViewSizes() Return list of supported view sizes.
WebcamListener[]	getWebcamListeners()
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?
void	open() Open the webcam.
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

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

Constructor Detail

Webcam

protected Webcam(WebcamDevice device)

Webcam class.

Parameters:

device - - device to be used as webcam

Throws:

IllegalArgumentException - when argument is null

Method Detail

open

public void open()

Open the webcam.

close

public void 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

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

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

getProcessor

protected WebcamProcessor getProcessor()

dispose

protected void dispose()

Completely dispose capture device. After this operation webcam cannot be used any more and full reinstantiation is required.

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