jdk.dio.dac

Interface DACChannel

All Superinterfaces:

java.lang.AutoCloseable, BufferAccess<java.nio.IntBuffer>, java.nio.channels.Channel, java.io.Closeable, Device<DACChannel>

public interface DACChannel
extends Device<DACChannel>, BufferAccess<java.nio.IntBuffer>

The DACChannel interface provides methods for controlling a DAC (Digital to Analog Converter) channel.

One DAC device can have several channels. Raw digital output values (samples) are converted to analog output values according to the DAC channel resolution. The raw digital output values may range from getMinValue to getMaxValue. Actual output voltage values can be calculated from the raw digital output values and the Reference Voltage value as returned by getVRefValue.

A DAC channel may be identified by the numerical ID and by the name (if any defined) that correspond to its registered configuration. A DACChannel instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name. When a DACChannel instance is opened with an ad-hoc DACChannelConfig configuration (which includes its hardware addressing information) using one of the DeviceManager.open(config,...) it is not assigned any ID nor name.

Once opened, an application can write an output value to a DAC channel by calling the generate(int) method or can write a series of output values to be converted over a period of time by calling the generate(IntBuffer) method.

An application can also asynchronously write a series of output values (samples) to be converted at a certain rate by calling the startGeneration method with a GenerationRoundListener instance which will get cyclicly and asynchronously invoked to fetch more values to be converted. Analog output generation can be stopped by calling the stopGeneration method.

Only one output generation (synchronous or asynchronous) can be going on at any time.

When an application is no longer using an DAC channel it should call the close method to close the DAC channel. Any further attempt to set or get the value of a DAC channel which has been closed will result in a ClosedDeviceException been thrown.

Note that asynchronous notification of output generation completion is only loosely tied to hardware-level interrupt requests. The platform does not guarantee notification in a deterministic/timely manner.

See Also:

GenerationRoundListener

Field Summary

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
void	generate(int value) Writes the provided raw output value to this channel.
void	generate(java.nio.IntBuffer src) Writes count raw output values from the provided buffer to this channel for conversion.
int	getMaxValue() Returns the maximum raw value this channel can convert.
int	getMinSamplingInterval() Gets the minimum output sampling interval (in microseconds) that can be set using setSamplingInterval.
int	getMinValue() Returns the minimum raw value this channel can convert.
int	getSamplingInterval() Gets the output sampling interval (in microseconds).
double	getVRefValue() Returns the Reference Voltage value of this DAC channel.
void	setSamplingInterval(int interval) Sets the output sampling interval (in microseconds).
void	startGeneration(java.nio.IntBuffer src, GenerationRoundListener listener) Starts asynchronous analog output generation on this channel from a series of raw output values (samples).
void	startGeneration(java.nio.IntBuffer src1, java.nio.IntBuffer src2, GenerationRoundListener listener) Starts asynchronous analog output generation on this channel from a series of raw output values (samples).
void	stopGeneration() Stops the asynchronous analog output generation on this channel as started by a call to one of the startGeneration methods.

Methods inherited from interface jdk.dio.Device

close, getDescriptor, isOpen, tryLock, unlock

Methods inherited from interface jdk.dio.BufferAccess

getInputBuffer, getOutputBuffer

Method Detail

getMaxValue

int getMaxValue()
                throws java.io.IOException,
                       UnavailableDeviceException,
                       ClosedDeviceException

Returns the maximum raw value this channel can convert. If the DAC device resolution is n then the min value returned by getMinValue and the max value returned by getMaxValue are such that:

 (max - min) == (2^n - 1).
 

Returns:

the maximum raw value this channel can convert.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getMinSamplingInterval

int getMinSamplingInterval()
                           throws java.io.IOException,
                                  UnavailableDeviceException,
                                  ClosedDeviceException

Gets the minimum output sampling interval (in microseconds) that can be set using setSamplingInterval.

Returns:

the minimum output sampling interval (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getMinValue

int getMinValue()
                throws java.io.IOException,
                       UnavailableDeviceException,
                       ClosedDeviceException

Returns the minimum raw value this channel can convert. If the DAC device resolution is n then the min value returned by getMinValue and the max value returned by getMaxValue are such that:

 (max - min) == (2^n - 1).
 

Returns:

the minimum raw value this channel can convert.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getSamplingInterval

int getSamplingInterval()
                        throws java.io.IOException,
                               UnavailableDeviceException,
                               ClosedDeviceException

Gets the output sampling interval (in microseconds). If the output sampling interval was not set previously using setSamplingInterval the device configuration-specific default value is returned.

Returns:

the output sampling interval (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getVRefValue

double getVRefValue()
                    throws java.io.IOException,
                           UnavailableDeviceException,
                           ClosedDeviceException

Returns the Reference Voltage value of this DAC channel. If the reference voltage is vRef and the DAC device resolution is n then the actual output voltage value corresponding to a raw value value written to this channel can be calculated as follows:

 vOutput = (value * vRef) / (2^n)
 

Returns:

the Reference Voltage value of this channel.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

setSamplingInterval

void setSamplingInterval(int interval)
                         throws java.io.IOException,
                                UnavailableDeviceException,
                                ClosedDeviceException

Sets the output sampling interval (in microseconds). Whether changing the sampling interval has an immediate effect or not on an active (synchronous or asynchronous) generation is device- as well as platform-dependent.

Parameters:

interval - the output sampling interval (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

InvalidOutputSamplingRateException - if the resulting sampling rate (i.e.: (1 / interval)) is higher than the maximum supported sampling rate (i.e.: (1 / getMinSamplingInterval )).

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalArgumentException - if interval is negative or zero.

generate

void generate(int value)
              throws java.io.IOException,
                     UnavailableDeviceException,
                     ClosedDeviceException

Writes the provided raw output value to this channel. The corresponding converted analog output value will be held until it is overwritten by another output generation.

This method may be invoked at any time. If another thread has already initiated a synchronous output generation upon this channel then an invocation of this method will block until the first operation is complete.

Only one output generation (synchronous or asynchronous) can be going on at any time.

Parameters:

value - the raw value to be output.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalArgumentException - if the provided raw value is not between the range defined by getMinValue and getMaxValue.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if an asynchronous output generation is already active.

generate

void generate(java.nio.IntBuffer src)
              throws java.io.IOException,
                     UnavailableDeviceException,
                     ClosedDeviceException

Writes count raw output values from the provided buffer to this channel for conversion.

The raw output values will be converted according to the current output sampling interval as returned by getSamplingInterval.

r integers will be written to this channel, where r is the number of integers remaining in the buffer, that is, src.remaining(), at the moment this method is invoked.

Suppose that an integer sequence of length n is written, where 0 <= n <= r . This integer sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is invoked; the index of the last integer written will be p + n - 1. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

The operation will return only after writing all of the r requested integers.

This method may be invoked at any time. If another thread has already initiated a synchronous output generation upon this channel, however, then an invocation of this method will block until the first operation is complete.

Only one output generation (synchronous or asynchronous) can be going on at any time.

Note that this method does not throw an IllegalArgumentException if any of the designated raw values is not between the range defined by getMinValue and getMaxValue. If a value is not within range the actual analog value output by the DAC device is hardware- or driver-specific: the output value may for example be equal to the maximum output value or it may correspond to the raw value where the most significant bits beyond the n bits of the DAC device resolution have been truncated.

Parameters:

src - the buffer from which the integer raw values can be retrieved.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.NullPointerException - If src is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if an asynchronous output generation is already active.

startGeneration

void startGeneration(java.nio.IntBuffer src,
                   GenerationRoundListener listener)
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Starts asynchronous analog output generation on this channel from a series of raw output values (samples). More values to be converted are asynchronously fetched by notifying the provided GenerationRoundListener instance once count raw output values have been converted. The raw output values to be converted are read from the provided buffer.

Analog output generation can be stopped by a call to stopGeneration.

r integers will be written to this channel, where r is the number of integers remaining in the buffer (possibly 0), that is, src.remaining(), at the moment this method is initially invoked and then subsequently when the listener is returning.

Suppose that an integer sequence of length n is written, where 0 <= n <= r . This integer sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is invoked and then subsequently when the listener is returning; the index of the last integer written will be p + n - 1. Upon invocation of the listener to fetch more values to convert the buffer's position will be equal to p + n; its limit will not have changed.
The buffer's position upon stopping this asynchronous operation by a call to stopGeneration is not predictable unless called from within the listener..

The raw output values (samples) will be converted according to the current output sampling interval as returned by getSamplingInterval.

Note that a buffer with 0 integers remaining to be written (that is a buffer already empty), at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the the the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched.

Interfering with the asynchronous operation by accessing and modifying the provided buffer concurrently may yield unpredictable results.

Only one output generation (synchronous or asynchronous) can be going on at any time.

Note that this method does not throw an IllegalArgumentException if any of the designated raw values is not between the range defined by getMinValue and getMaxValue. If a value is not within range the actual analog value output by the DAC device is hardware- or driver-specific: the output value may for example be equal to the maximum output value or it may correspond to the raw value where the most significant bits beyond the n bits of the DAC device resolution have been truncated.

Parameters:

src - the buffer from which the integer raw sampled input values are to be retrieved.

listener - the GenerationRoundListener instance to be notified when all the output values have been converted.

Throws:

java.lang.NullPointerException - If src or listener is null.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous output generation is already active.

startGeneration

void startGeneration(java.nio.IntBuffer src1,
                   java.nio.IntBuffer src2,
                   GenerationRoundListener listener)
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Starts asynchronous analog output generation on this channel from a series of raw output values (samples).

This method behaves identically to startGeneration(IntBuffer, GenerationRoundListener) excepts that it uses double-buffering. Notification will happen when all the raw output values remaining in the current working buffer (initially src1) have been converted and conversion will proceed with the alternate buffer (which will become the current working buffer). Conversion will only be suspended if the previous event has not yet been handled.

Note that a working buffer with 0 integers remaining to be written (that is a buffer already empty), at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched.

Only one output generation (synchronous or asynchronous) can be going on at any time.

Note that this method does not throw an IllegalArgumentException if any of the designated raw values is not between the range defined by getMinValue and getMaxValue. If a value is not within range the actual analog value output by the DAC device is hardware- or driver-specific: the output value may for example be equal to the maximum output value or it may correspond to the raw value where the most significant bits beyond the n bits of the DAC device resolution have been truncated.

Parameters:

src1 - the first buffer from which the integer raw sampled input values are to be retrieved.

src2 - the second buffer from which the integer raw sampled input values are to be retrieved.

listener - the GenerationRoundListener instance to be notified when all the output values have been converted.

Throws:

java.lang.NullPointerException - If src1, src2 or listener is null.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous output generation is already active.

stopGeneration

void stopGeneration()
                    throws java.io.IOException,
                           UnavailableDeviceException,
                           ClosedDeviceException

Stops the asynchronous analog output generation on this channel as started by a call to one of the startGeneration methods.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.