public interface DACChannel extends Peripheral<DACChannel>, BufferAccess<java.nio.IntBuffer>
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
PeripheralManager.open(id,...)
methods using its ID or by a call to one of the
PeripheralManager.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
PeripheralManager.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 DACChannel.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 ClosedPeripheralException
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.GenerationRoundListener
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN
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) . |
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. |
close, getDescriptor, isOpen, tryLock, unlock
getInputBuffer, getOutputBuffer
int getMaxValue() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
n
then the
min
value returned by getMinValue()
and the max
value returned by
getMaxValue()
are such that: (max - min) == (2^n - 1)
.
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getMinSamplingInterval() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
setSamplingInterval(int)
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getMinValue() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
n
then the
min
value returned by getMinValue()
and the max
value returned by
getMaxValue()
are such that: (max - min) == (2^n - 1)
.
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getSamplingInterval() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
setSamplingInterval(int)
the peripheral configuration-specific default value is returned.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.double getVRefValue() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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)
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void setSamplingInterval(int interval) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
interval
- the output sampling interval (in microseconds).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()
)).UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalArgumentException
- if interval
is negative or zero.void generate(int value) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
value
- the raw value to be output.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()
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if an asynchronous output generation is already active.void generate(java.nio.IntBuffer src) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.src
- the buffer from which the integer raw values can be retrieved.java.io.IOException
- if some other I/O error occurs.java.lang.NullPointerException
- If src
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if an asynchronous output generation is already active.void startGeneration(java.nio.IntBuffer src, GenerationRoundListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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, 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 raw output values (samples) will be converted according to the current output sampling interval as returned
by getSamplingInterval()
.
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.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.java.lang.NullPointerException
- If src
or listener
is null
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous output generation is already active.void startGeneration(java.nio.IntBuffer src1, java.nio.IntBuffer src2, GenerationRoundListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
startGeneration(IntBuffer, GenerationRoundListener)
excepts that it
uses double-buffering. Notification will happen when all the raw output values remaining in the working buffer
have been converted and conversion will proceed with the alternate buffer (which will become the working buffer).
Conversion will only be suspended if the previous event has not yet been handled.
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.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.java.lang.NullPointerException
- If src1
, src2
or listener
is null
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous output generation is already active.void stopGeneration() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
startGeneration
methods.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved.
Legal Notices