au.edu.jcu.v4l4j

Class Control

java.lang.Object

au.edu.jcu.v4l4j.Control

public class Control
extends Object

Objects of this class represent a video source control of any nature. Control objects are not directly instantiated. Instead a list of Controls associated with a VideoDevice can be obtained by calling getControlList(). Once the controls are no longer used, they must be released by calling releaseControlList(). Any attempt to use a control after it has been released will result in a StateException.
A control can be either of the following types:

• V4L4JConstants.CTRL_TYPE_BUTTON: Such controls take only 2 different values: 0 and 1
• V4L4JConstants.CTRL_TYPE_SLIDER: Controls of this type take a range of values between a minimum value (returned by getMinValue()) and a maximum value (returned by getMaxValue()) with an increment value (returned by getStepValue())
• V4L4JConstants.CTRL_TYPE_SWITCH: Switch controls do not take any specific value, and attempting to read its current value will always return 0. Setting any value will activate the switch.
• V4L4JConstants.CTRL_TYPE_DISCRETE: These controls accept only specific discrete values, which can be retrieved using getDiscreteValues(). Each discrete value may be accompanied by a description, which is returned by getDiscreteValueNames().
• V4L4JConstants.CTRL_TYPE_STRING: These controls accept string values, which can be retrieved using getStringValue() and set with setStringValue(String). Calls to any other get/set methods will result in UnsupportedMethod exceptions. getMinValue() & getMaxValue() return the smallest / largest string length (number of characters) this control will accept. getStepValue() specify the step length of the string.
• V4L4JConstants.CTRL_TYPE_LONG: These controls accept long values, between Long.MIN_VALUE and Long.MAX_VALUE with a step value of 1. The actual value is set / retrieved with setLongValue(long) and getLongValue(). Calls to any other get/set methods, getMinValue(), getMaxValue() and getStepValue() will result in UnsupportedMethod exceptions.
• V4L4JConstants.CTRL_TYPE_BITMASK: These controls accept bitmask values, between 0 and Integer.MAX_VALUE with a step value of 1. The actual value is set / retrieved with setValue(int) and getValue(). Calls to any other get/set methods will result in UnsupportedMethod exceptions.

Author:

gilles

Method Summary

Modifier and Type	Method and Description
int	decreaseValue() This method decreases this control's current value by its step (as returned by getStepValue().
int	getDefaultValue() This method returns the default value for this control
List<String>	getDiscreteValueNames() This method returns the list of names for each of the supported discrete values.
List<Integer>	getDiscreteValues() This method returns a list of the discrete values accepted by this control.
Map<String,Integer>	getDiscreteValuesMap() This method returns a map of all discrete value names and their values.
long	getLongValue() This method retrieves the current long value of this control.
int	getMaxValue() This method retrieves the maximum value this control will accept.
int	getMinValue() This method retrieves the minimum value this control will accept.
String	getName() This method retrieves the name of this control.
int	getStepValue() This method retrieves the increment to be used when setting a new value for this control.
String	getStringValue() This method retrieves the current string value of this control.
int	getType() This method retrieves the type of this control.
int	getValue() This method retrieves the current value of this control.
int	increaseValue() This method increases this control's current value by its step (as returned by getStepValue()).
long	setLongValue(long value) This method sets a new long value for this control.
String	setStringValue(String value) This method sets a new string value for this control.
int	setValue(int value) This method sets a new value for this control.

Methods inherited from class java.lang.Object

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

Method Detail

getValue

public int getValue()
             throws ControlException

This method retrieves the current value of this control. Some controls (for example relative values like pan or tilt) are write-only and getting their value does not make sense. Invoking this method on this kind of controls will trigger a ControlException.

Returns:

the current value of this control (0 if it is a button)

Throws:

ControlException - if the value cannot be retrieved

UnsupportedMethod - if this control is of type V4L4JConstants.CTRL_TYPE_STRING (and you should be using getStringValue() instead) or if this control is of type V4L4JConstants.CTRL_TYPE_LONG (and you should be using setLongValue(long) instead).

StateException - if this control has been released and must not be used anymore.

setValue

public int setValue(int value)
             throws ControlException

This method sets a new value for this control. The returned value is the new value of the control, which for normal controls will be identical to the one set. However, some controls (for example relative values like pan or tilt) are write-only and getting their value does not make sense. The return value in this case is the control's default value (as returned by getDefaultValue()).

Parameters:

value - the new value

Returns:

the new value of the control after setting it, or the control's default value

Throws:

ControlException - if the value can not be set.

UnsupportedMethod - if this control is of type V4L4JConstants.CTRL_TYPE_STRING (and you should be using setStringValue(String) instead) or if this control is of type V4L4JConstants.CTRL_TYPE_LONG (and you should be using setLongValue(long) instead).

StateException - if this control has been released and must not be used anymore.

getStringValue

public String getStringValue()
                      throws ControlException

This method retrieves the current string value of this control. Some controls may be write-only and getting their value does not make sense. Invoking this method on this kind of controls will trigger a ControlException.

Returns:

the current value of this control

Throws:

ControlException - if the value cannot be retrieved

UnsupportedMethod - if this control is not of type V4L4JConstants.CTRL_TYPE_STRING.

StateException - if this control has been released and must not be used anymore.

setStringValue

public String setStringValue(String value)
                      throws ControlException

This method sets a new string value for this control. The returned value is the new value of the control.

Parameters:

value - the new value

Returns:

the new value of the control after setting it

Throws:

ControlException - if the value can not be set, or if the new string value's length is under / over the minimum / maximum length.

UnsupportedMethod - if this control is not of type V4L4JConstants.CTRL_TYPE_STRING,

StateException - if this control has been released and must not be used anymore.

getLongValue

public long getLongValue()
                  throws ControlException

This method retrieves the current long value of this control. Some controls may be write-only and getting their value does not make sense. Invoking this method on this kind of controls will trigger a ControlException.

Returns:

the current value of this control

Throws:

ControlException - if the value cannot be retrieved

UnsupportedMethod - if this control is not of type V4L4JConstants.CTRL_TYPE_LONG.

StateException - if this control has been released and must not be used anymore.

setLongValue

public long setLongValue(long value)
                  throws ControlException

This method sets a new long value for this control. The returned value is the new value of the control.

Parameters:

value - the new value

Returns:

the new value of the control after setting it

Throws:

ControlException - if the value can not be set.

UnsupportedMethod - if this control is not of type V4L4JConstants.CTRL_TYPE_LONG,

StateException - if this control has been released and must not be used anymore.

increaseValue

public int increaseValue()
                  throws ControlException

This method increases this control's current value by its step (as returned by getStepValue()). The returned value is the new value of the control, which for normal controls will be identical to the old one plus the step value. However, some controls (for example relative values like pan or tilt) are write-only and getting their value does not make sense. In this case, this method sets the new value to the default one plus the step value. Note that, the return value in this case is still the control's default value (as returned by getDefaultValue()), not the default one plus the step value.

Returns:

the new value of the control after increasing its old value, or the control's default value

Throws:

ControlException - if the value cannot be increased

UnsupportedMethod - if this control is of type V4L4JConstants.CTRL_TYPE_STRING or V4L4JConstants.CTRL_TYPE_LONG

StateException - if this control has been released and must not be used anymore.

decreaseValue

public int decreaseValue()
                  throws ControlException

This method decreases this control's current value by its step (as returned by getStepValue(). The returned value is the new value of the control, which for normal controls will be identical to the old one minus the step value. However, some controls (for example relative values like pan or tilt) are write-only and getting their value does not make sense. In this case, this method sets the new value to the default one minus the step value. Note that, the return value in this case is still the control's default value (as returned by getDefaultValue()), not the default one plus the step value.

Returns:

the new value of the control after decreasing it.

Throws:

ControlException - if the value can not be increased

UnsupportedMethod - if this control is of type V4L4JConstants.CTRL_TYPE_STRING or V4L4JConstants.CTRL_TYPE_LONG

StateException - if this control has been released and must not be used anymore.

getMaxValue

public int getMaxValue()

This method retrieves the maximum value this control will accept. If this control is a string control, this method returns the maximum string size that can be set on this control.

Returns:

the maximum value, or the largest string size

Throws:

StateException - if this control has been released and must not be used anymore.

UnsupportedMethod - if this control is of type V4L4JConstants.CTRL_TYPE_LONG

getMinValue

public int getMinValue()

This method retrieves the minimum value this control will accept. If this control is a string control, this method returns the minimum string size that can be set on this control.

Returns:

the minimum value or the smallest string size

Throws:

StateException - if this control has been released and must not be used anymore.

UnsupportedMethod - if this control is of type V4L4JConstants.CTRL_TYPE_LONG

getName

public String getName()

This method retrieves the name of this control.

Returns:

the name of this control

Throws:

StateException - if this control has been released and must not be used anymore.

getStepValue

public int getStepValue()

This method retrieves the increment to be used when setting a new value for this control. New values must be equal to getMin() + K*getStep() where K is an integer, and the result is less or equal to getMaxValue(). For string control, this method returns the step size of the string.

Returns:

the increment

Throws:

StateException - if this control has been released and must not be used anymore.

UnsupportedMethod - if this control is of type V4L4JConstants.CTRL_TYPE_LONG

getType

public int getType()

This method retrieves the type of this control. Values are V4L4JConstants.CTRL_TYPE_BUTTON, V4L4JConstants.CTRL_TYPE_SLIDER, V4L4JConstants.CTRL_TYPE_SWITCH, V4L4JConstants.CTRL_TYPE_DISCRETE, V4L4JConstants.CTRL_TYPE_STRING, V4L4JConstants.CTRL_TYPE_LONG, V4L4JConstants.CTRL_TYPE_BITMASK.

Returns:

the type of this controls

Throws:

StateException - if this control has been released and must not be used anymore.

getDefaultValue

public int getDefaultValue()

This method returns the default value for this control

Returns:

the default value for this control

Throws:

UnsupportedMethod - if this control is of type V4L4JConstants.CTRL_TYPE_STRING

StateException - if this control has been released and must not be used anymore

getDiscreteValues

public List<Integer> getDiscreteValues()

This method returns a list of the discrete values accepted by this control. The list is ordered in the same way as the list returned by getDiscreteValueNames(). So a value at index 'i' in the list returned by this method, matches the name at the same index in the list returned by getDiscreteValueNames().

Returns:

a list of the discrete values accepted by this control

Throws:

UnsupportedMethod - if this control does not support discrete values. Check this control's type (with getType()) and use the appropriate method.

StateException - if this control has been released and must not be used anymore

getDiscreteValueNames

public List<String> getDiscreteValueNames()

This method returns the list of names for each of the supported discrete values. The list is ordered in the same way as the list returned by getDiscreteValues(). So the name at index 'i' in the list returned by this method, matches the value at the same index in the list returned by getDiscreteValues().

Returns:

a list of names for each of the supported discrete values.

Throws:

UnsupportedMethod - if this control does not support discrete values. Check this control's type (with getType()) and use the appropriate method.

StateException - if this control has been released and must not be used anymore

getDiscreteValuesMap

public Map<String,Integer> getDiscreteValuesMap()

This method returns a map of all discrete value names and their values.

Returns:

a map of all discrete value names and their values.

Throws:

UnsupportedMethod - if this control does not support discrete values. Check this control's type (with getType()) and use the appropriate method.

StateException - if this control has been released and must not be used anymore