de.sciss.gui
Class PeakMeter

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              de.sciss.gui.PeakMeter

All Implemented Interfaces:

PeakMeterView, Disposable, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class PeakMeter
extends javax.swing.JComponent
implements PeakMeterView, Disposable

A level (volume) meter GUI component. The component is a vertical bar displaying a green-to-reddish bar for the peak amplitude and a blue bar for RMS value.

To animate the bar, call setPeakAndRMS at a regular interval, typically around every 30 milliseconds for a smooth look.

Version:

0.70, 03-Jul-08

Author:

Hanns Holger Rutz

See Also:

Serialized Form

Todo:

allow linear display (now it's hard coded logarithmic), add optional horizontal orientation

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

static int

DEFAULT_HOLD_DUR

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

PeakMeter()
Creates a new level meter with default ballistics and bounds.

Method Summary

void	clearHold() Clears the peak hold indicator.
void	clearMeter() Clears the peak, peak hold and rms values immediately (without ballistics).
void	dispose()
float	getHoldDecibels()
int	getNumChannels()
float	getPeakDecibels()
boolean	meterUpdate(float[] peakRMSPairs, int offset, long time)
void	paintComponent(java.awt.Graphics g)
protected void	recalcPrefSize()
void	setHoldDuration(int millis) Sets the peak indicator hold time.
void	setHoldPainted(boolean onOff) Decides whether the peak indicator should be painted or not.
boolean	setPeak(float peak) Updates the meter.
boolean	setPeakAndRMS(float peak, float rms) Updates the meter.
boolean	setPeakAndRMS(float peak, float rms, long time)
void	setRefreshParent(boolean onOff)
void	setRMSPainted(boolean onOff) Decides whether the blue RMS bar should be painted or not.
void	setTicks(int ticks)

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_HOLD_DUR

public static final int DEFAULT_HOLD_DUR

See Also:

Constant Field Values

Constructor Detail

PeakMeter

public PeakMeter()

Creates a new level meter with default ballistics and bounds.

Method Detail

getNumChannels

public int getNumChannels()

Specified by:

getNumChannels in interface PeakMeterView

meterUpdate

public boolean meterUpdate(float[] peakRMSPairs,
                           int offset,
                           long time)

Specified by:

meterUpdate in interface PeakMeterView

setHoldPainted

public void setHoldPainted(boolean onOff)

Decides whether the peak indicator should be painted or not. By default the indicator is painted.

Parameters:

onOff - true to have the indicator painted, false to switch it off

setRMSPainted

public void setRMSPainted(boolean onOff)

Decides whether the blue RMS bar should be painted or not. By default the bar is painted.

Parameters:

onOff - true to have the RMS values painted, false to switch them off

clearMeter

public void clearMeter()

Clears the peak, peak hold and rms values immediately (without ballistics). This way the component can be reset when the metering task is stopped without waiting for the bars to fall down.

Specified by:

clearMeter in interface PeakMeterView

setTicks

public void setTicks(int ticks)

setRefreshParent

public void setRefreshParent(boolean onOff)

setHoldDuration

public void setHoldDuration(int millis)

Sets the peak indicator hold time. Defaults to 1800 milliseconds.

Parameters:

millis - new peak hold time in milliseconds. Note that the special value -1 means infinite peak hold. In this case, to clear the indicator, call clearHold

clearHold

public void clearHold()

Clears the peak hold indicator. Note that you will need to call setPeakAndRMS successively for the graphics to be updated.

recalcPrefSize

protected void recalcPrefSize()

getPeakDecibels

public float getPeakDecibels()

getHoldDecibels

public float getHoldDecibels()

setPeakAndRMS

public boolean setPeakAndRMS(float peak,
                             float rms)

Updates the meter. This will call the component's paint method to visually reflect the new values. Call this method regularly for a steady animated meter.

If you have switched off RMS painted, you may want to call setPeak alternatively.

When your audio engine is idle, you may want to stop meter updates. You can use the following formula to calculate the maximum delay of the meter display to be safely at minimum levels after starting to send zero amplitudes:

• for peak hold indicator not painted : delay[sec] = abs(minAmplitude[dB]) / fallTime[dB/sec] + updatePeriod[sec]
• for painted peak hold : the maximum of the above value and delay[sec] = abs(minAmplitude[dB]) / holdFallTime[dB/sec] + holdTime[sec] + updatePeriod[sec]

Therefore, for the default values of 1.8 sec hold time, 15 dB/sec hold fall time and -40 dB minimum amplitude, at a display period of 30 milliseconds, this yields a delay of around 4.5 seconds. Accounting for jitter due to GUI slowdown, in ths case it should be safe to stop meter updates five seconds after the audio engine stopped.

Parameters:

peak - peak amplitude (linear) between zero and one.

rms - mean-square amplitude (linear). note : despite the name, this is considered mean-square, not root-mean-square. this method does the appropriate conversion on the fly!

Synchronization:

this method is thread safe

setPeakAndRMS

public boolean setPeakAndRMS(float peak,
                             float rms,
                             long time)

setPeak

public boolean setPeak(float peak)

Updates the meter. This will call the component's paint method to visually reflect the peak amplitude. Call this method regularly for a steady animated meter. The RMS value is not changed, so this method is appropriate when having RMS painting turned off.

Parameters:

peak - peak amplitude (linear) between zero and one.

Synchronization:

this method is thread safe

paintComponent

public void paintComponent(java.awt.Graphics g)

Overrides:

paintComponent in class javax.swing.JComponent

dispose

public void dispose()

Specified by:

dispose in interface Disposable