The top layer of the UmsciControlComponent stack — renders an interactive upmix speaker ring and lets the user adjust its spatial transform. More...

#include <UmsciUpmixIndicatorPaintNControlComponent.h>

Inheritance diagram for UmsciUpmixIndicatorPaintNControlComponent:

Collaboration diagram for UmsciUpmixIndicatorPaintNControlComponent:

Public Types
enum class	IndicatorShape { Circle , Rectangle }
	The geometric shape used to draw the upmix speaker ring. More...

Public Types inherited from UmsciPaintNControlComponentBase
enum class	ControlsSize { S , M , L }
	Visual size of source/speaker icons. Multiplier accessible via `getControlsSizeMultiplier()`. More...

Public Member Functions
	UmsciUpmixIndicatorPaintNControlComponent ()

	~UmsciUpmixIndicatorPaintNControlComponent () override

void	paint (Graphics &) override

void	resized () override

void	setControlsSize (ControlsSize size) override
	Updates the icon size; derived classes may override to re-prerender.

bool	hitTest (int x, int y) override

void	mouseDown (const juce::MouseEvent &) override

void	mouseDrag (const juce::MouseEvent &) override

void	mouseUp (const juce::MouseEvent &) override

void	mouseDoubleClick (const juce::MouseEvent &) override

void	timerCallback () override

bool	setChannelConfiguration (const juce::AudioChannelSet &channelLayout) override

void	setSpeakersRealBoundingCube (const std::array< float, 6 > &speakersRealBoundingCube)
	Provides the axis-aligned bounding cube of all loudspeaker positions.

void	setSourcePositions (const std::map< std::int16_t, std::array< std::float_t, 3 > > &sourcePositions)
	Provides live DS100 source positions for all upmix channels. Only rendered when `m_liveMode` is true.

void	setSourcePosition (std::int16_t sourceId, const std::array< std::float_t, 3 > &position)
	Updates a single source position (called on each OCP.1 notification).

void	setSourceStartId (int startId)
	Sets the first DS100 input channel (1-based) assigned to the upmix renderer.

int	getSourceStartId () const

void	setLiveMode (bool liveMode)
	When true, actual DS100 positions for the upmix channels are overlaid on the ideal indicator ring so the operator can see alignment errors.

bool	getLiveMode () const

void	setShape (IndicatorShape shape)
	Sets the indicator ring geometry (circle or rectangle).

IndicatorShape	getShape () const

void	setUpmixTransform (float rot, float trans, float heightTrans, float angleStretch=1.0f)
	Applies all four transform parameters and triggers a prerender + repaint.

float	getUpmixRot () const
	Ring rotation (normalised 0–1 = 0–360°).

float	getUpmixTrans () const
	Radial scale factor.

float	getUpmixHeightTrans () const
	Height ring radius as a fraction of floor radius.

float	getUpmixAngleStretch () const
	Front/rear angular compression factor.

void	setUpmixOffset (float x, float y)
	Sets the ring centre offset in units of base radius.

float	getUpmixOffsetX () const

float	getUpmixOffsetY () const

void	notifyTransformChanged ()
	Fires live-mode position callbacks and `onTransformChanged` after a programmatic transform change (e.g. from MIDI control).

void	triggerFlashCheck ()
	Checks whether the ideal ring positions diverge from the stored DS100 positions and starts the flash timer if they do.

Public Member Functions inherited from UmsciPaintNControlComponentBase
	UmsciPaintNControlComponentBase ()

virtual	~UmsciPaintNControlComponentBase () override

void	setBoundsRealRef (const juce::Rectangle< float > &boundsRealRef)
	Sets the real-world rectangle that the component's pixel bounds map to.

ControlsSize	getControlsSize () const

float	getControlsSizeMultiplier () const
	Returns a multiplier (e.g. 0.5 / 1.0 / 1.5) for S/M/L icon sizes.

void	setZoom (float factor, juce::Point< float > normalizedPanOffset={})
	Silently applies zoom without firing `onViewportZoomChanged`. Used by `UmsciControlComponent` to synchronise sibling layers after one of them fires the callback.

float	getZoomFactor () const

void	resetZoom ()
	Resets zoom to 1.0 / no pan and fires `onViewportZoomChanged`.

void	simulatePinchZoom (float scaleFactor, juce::Point< float > centre)
	Applies an incremental pinch-zoom step, as if the user performed a native pinch gesture centred at `centre` (in component-local pixel coordinates).

Static Public Member Functions
static juce::String	getShapeName (IndicatorShape shape)

static IndicatorShape	getShapeForName (const juce::String &name)

Public Attributes
std::function< void(std::int16_t, std::array< std::float_t, 3 >)>	onSourcePositionChanged
	Fired when the user drags a source circle in live mode (pass-through from this component, analogous to `UmsciSoundobjectsPaintComponent`).

std::function< void()>	onTransformChanged
	Fired whenever any transform parameter changes via an interactive drag, so `UmsciControlComponent` can persist the new values.

Public Attributes inherited from UmsciPaintNControlComponentBase
std::function< void(float, juce::Point< float >)>	onViewportZoomChanged
	Fired after every user-initiated zoom/pan change (wheel, pinch, double-click). Parameters: (newFactor, newNormalisedPanOffset). `UmsciControlComponent` uses this to synchronise the other two layers via `setZoom()`.

Additional Inherited Members
Protected Member Functions inherited from UmsciPaintNControlComponentBase
juce::Point< float >	GetPointForRealCoordinate (const std::array< float, 3 > &realCoordinate)
	Converts a 3D real-world coordinate to a 2D screen pixel point.

std::array< float, 3 >	GetRealCoordinateForPoint (const juce::Point< float > &screenPoint)
	Inverse of `GetPointForRealCoordinate` — converts a screen pixel point back to a 3D real-world coordinate (Z is set to 0).

void	mouseDoubleClick (const juce::MouseEvent &) override
	Double-click resets zoom to 1.0 via `resetZoom()`.

void	mouseWheelMove (const juce::MouseEvent &, const juce::MouseWheelDetails &) override
	Mouse-wheel zooms about the cursor position.

void	mouseMagnify (const juce::MouseEvent &, float scaleFactor) override
	Trackpad pinch-to-zoom (macOS).

bool	processPinchGesture (const juce::MouseEvent &e, bool isDown, bool isUp)
	JUCE-level two-touch pinch-zoom fallback for platforms where neither `mouseMagnify` nor a native gesture recognizer is available.

Detailed Description

The top layer of the UmsciControlComponent stack — renders an interactive upmix speaker ring and lets the user adjust its spatial transform.

Purpose

Umsci is a monitoring tool for a DS100 that is being used as a upmix renderer: an external upmix algorithm feeds its virtual speaker outputs into consecutive DS100 sound objects (starting at m_sourceStartId). This component visualises where those virtual speakers are currently positioned in the real room (using live DS100 position data when m_liveMode is true), and lets the user interactively adjust the transform (rotation, scale, height, stretch, offset) that maps the ideal upmix geometry onto the physical room.

What is rendered

A floor ring (circle or rectangle path) with one labelled dot per channel of the selected juce::AudioChannelSet (e.g. L/C/R/Ls/Rs for 5.0).
A height ring (smaller, concentric) for height channels if the format includes them (e.g. Ltf/Rtf for 5.1.2).
A centre handle (draggable) to shift the entire ring in XY.
A stretch handle (draggable arc arrow) to adjust the m_upmixAngleStretch which compresses or expands the angular spacing of front/rear channels.
When m_liveMode is true, actual DS100 source positions for the upmix channels are overlaid so the operator can see how well the current transform matches the algorithm's output.
A "refit" button (top-right) that snaps the transform to best-fit the bounding cube of the connected loudspeaker system.

Transform parameters

Parameter	Meaning
`m_upmixRot`	Rotation of the ring around the Z axis (normalised 0–1 = 0–360°).
`m_upmixTrans`	Radial scale — 1.0 means the ring radius equals the base radius.
`m_upmixHeightTrans`	Ratio of height ring to floor ring radius (0.6 default).
`m_upmixAngleStretch`	Compresses front/rear angular spread (1.0 = uniform).
`m_upmixOffsetX/Y`	XY offset of the ring centre in units of base radius.

Drag gestures

Dragging the floor ring arc → rotation (m_upmixRot).
Dragging the height ring arc → height scale (m_upmixHeightTrans).
Dragging the stretch handle → angular stretch (m_upmixAngleStretch).
Dragging the centre handle → XY offset (m_upmixOffsetX/Y). Any transform change fires onTransformChanged so the caller can persist the values.

hitTest and touch routing

hitTest() returns true only over the interactive elements (ring arc, sub-circles, handles, refit button, and the full area when the hint is flashing). Areas of the component outside those elements return false and pass touch/mouse events through to lower layers.

On iOS this means the two fingers of a pinch gesture may individually hit different components (or no component at all), making JUCE-level two-touch tracking unreliable. Pinch zoom on iOS is therefore handled by a native UIPinchGestureRecognizer at the UIKit layer (see UmsciControlComponent), which fires independently of per-component hitTest() results.

Timer

A JUCE Timer drives the m_flashState flag used to animate the live-mode overlay (flashing dots when source positions are updating).

Inherits JUCEAppBasics::TwoDFieldBase for the setChannelConfiguration() API which provides the per-channel angle and label data for the selected surround format.

Note: [MANUAL CONTEXT NEEDED] Document the exact angular convention for m_naturalFloorMaxAngleDeg (110°) — what does it mean physically for the front/rear extent of a standard surround layout?

Definition at line 94 of file UmsciUpmixIndicatorPaintNControlComponent.h.

Member Enumeration Documentation

◆ IndicatorShape

enum class UmsciUpmixIndicatorPaintNControlComponent::IndicatorShape

strong

The geometric shape used to draw the upmix speaker ring.

Enumerator
Circle
Rectangle

Definition at line 98 of file UmsciUpmixIndicatorPaintNControlComponent.h.

Constructor & Destructor Documentation

◆ UmsciUpmixIndicatorPaintNControlComponent()

UmsciUpmixIndicatorPaintNControlComponent::UmsciUpmixIndicatorPaintNControlComponent ( )

Definition at line 24 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References setChannelConfiguration().

◆ ~UmsciUpmixIndicatorPaintNControlComponent()

UmsciUpmixIndicatorPaintNControlComponent::~UmsciUpmixIndicatorPaintNControlComponent ( )

override

Definition at line 30 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

Member Function Documentation

◆ getLiveMode()

bool UmsciUpmixIndicatorPaintNControlComponent::getLiveMode ( ) const

Definition at line 833 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ getShape()

UmsciUpmixIndicatorPaintNControlComponent::IndicatorShape UmsciUpmixIndicatorPaintNControlComponent::getShape ( ) const

Definition at line 851 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ getShapeForName()

static IndicatorShape UmsciUpmixIndicatorPaintNControlComponent::getShapeForName ( const juce::String & name )

inlinestatic

Definition at line 110 of file UmsciUpmixIndicatorPaintNControlComponent.h.

References Circle, and Rectangle.

Referenced by MainComponent::onConfigUpdated().

◆ getShapeName()

static juce::String UmsciUpmixIndicatorPaintNControlComponent::getShapeName ( IndicatorShape shape )

inlinestatic

Definition at line 99 of file UmsciUpmixIndicatorPaintNControlComponent.h.

References Circle, and Rectangle.

Referenced by MainComponent::performConfigurationDump().

◆ getSourceStartId()

int UmsciUpmixIndicatorPaintNControlComponent::getSourceStartId ( ) const

Definition at line 823 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ getUpmixAngleStretch()

float UmsciUpmixIndicatorPaintNControlComponent::getUpmixAngleStretch ( ) const

Front/rear angular compression factor.

Definition at line 871 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ getUpmixHeightTrans()

float UmsciUpmixIndicatorPaintNControlComponent::getUpmixHeightTrans ( ) const

Height ring radius as a fraction of floor radius.

Definition at line 870 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ getUpmixOffsetX()

float UmsciUpmixIndicatorPaintNControlComponent::getUpmixOffsetX ( ) const

Definition at line 881 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ getUpmixOffsetY()

float UmsciUpmixIndicatorPaintNControlComponent::getUpmixOffsetY ( ) const

Definition at line 882 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ getUpmixRot()

float UmsciUpmixIndicatorPaintNControlComponent::getUpmixRot ( ) const

Ring rotation (normalised 0–1 = 0–360°).

Definition at line 868 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ getUpmixTrans()

float UmsciUpmixIndicatorPaintNControlComponent::getUpmixTrans ( ) const

Radial scale factor.

Definition at line 869 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ hitTest()

bool UmsciUpmixIndicatorPaintNControlComponent::hitTest	(	int	x,
		int	y
	)

override

Definition at line 169 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ mouseDoubleClick()

void UmsciUpmixIndicatorPaintNControlComponent::mouseDoubleClick ( const juce::MouseEvent & e )

override

Definition at line 424 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References UmsciPaintNControlComponentBase::mouseDoubleClick(), onSourcePositionChanged, and Rectangle.

◆ mouseDown()

void UmsciUpmixIndicatorPaintNControlComponent::mouseDown ( const juce::MouseEvent & e )

override

Definition at line 202 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References onSourcePositionChanged, onTransformChanged, UmsciPaintNControlComponentBase::processPinchGesture(), and Rectangle.

◆ mouseDrag()

void UmsciUpmixIndicatorPaintNControlComponent::mouseDrag ( const juce::MouseEvent & e )

override

Definition at line 294 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References onSourcePositionChanged, UmsciPaintNControlComponentBase::processPinchGesture(), and Rectangle.

◆ mouseUp()

void UmsciUpmixIndicatorPaintNControlComponent::mouseUp ( const juce::MouseEvent & e )

override

Definition at line 416 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References onTransformChanged, UmsciPaintNControlComponentBase::processPinchGesture(), and Rectangle.

◆ notifyTransformChanged()

void UmsciUpmixIndicatorPaintNControlComponent::notifyTransformChanged ( )

Fires live-mode position callbacks and onTransformChanged after a programmatic transform change (e.g. from MIDI control).

setUpmixTransform() and setUpmixOffset() deliberately do not fire callbacks (to avoid side effects during config restore). Call this immediately after a programmatic update to produce the same side effects as an interactive drag.

Definition at line 884 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References onSourcePositionChanged, onTransformChanged, and Rectangle.

◆ paint()

void UmsciUpmixIndicatorPaintNControlComponent::paint ( Graphics & )

override

Definition at line 34 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References UmsciPaintNControlComponentBase::getControlsSizeMultiplier(), and Rectangle.

◆ resized()

void UmsciUpmixIndicatorPaintNControlComponent::resized ( )

override

Definition at line 141 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

◆ setChannelConfiguration()

bool UmsciUpmixIndicatorPaintNControlComponent::setChannelConfiguration ( const juce::AudioChannelSet & channelLayout )

override

Definition at line 915 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

Referenced by UmsciUpmixIndicatorPaintNControlComponent().

◆ setControlsSize()

void UmsciUpmixIndicatorPaintNControlComponent::setControlsSize ( ControlsSize size )

overridevirtual

Updates the icon size; derived classes may override to re-prerender.

Reimplemented from UmsciPaintNControlComponentBase.

Definition at line 838 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle, and UmsciPaintNControlComponentBase::setControlsSize().

◆ setLiveMode()

void UmsciUpmixIndicatorPaintNControlComponent::setLiveMode ( bool liveMode )

When true, actual DS100 positions for the upmix channels are overlaid on the ideal indicator ring so the operator can see alignment errors.

Definition at line 828 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ setShape()

void UmsciUpmixIndicatorPaintNControlComponent::setShape ( IndicatorShape shape )

Sets the indicator ring geometry (circle or rectangle).

Definition at line 844 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ setSourcePosition()

void UmsciUpmixIndicatorPaintNControlComponent::setSourcePosition	(	std::int16_t	sourceId,
		const std::array< std::float_t, 3 > &	position
	)

Updates a single source position (called on each OCP.1 notification).

Definition at line 160 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ setSourcePositions()

void UmsciUpmixIndicatorPaintNControlComponent::setSourcePositions ( const std::map< std::int16_t, std::array< std::float_t, 3 > > & sourcePositions )

Provides live DS100 source positions for all upmix channels. Only rendered when m_liveMode is true.

Definition at line 153 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ setSourceStartId()

void UmsciUpmixIndicatorPaintNControlComponent::setSourceStartId ( int startId )

Sets the first DS100 input channel (1-based) assigned to the upmix renderer.

Channels from startId to startId + channelCount - 1 are treated as upmix inputs, where channelCount is the number of channels in the selected juce::AudioChannelSet.

Definition at line 816 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ setSpeakersRealBoundingCube()

void UmsciUpmixIndicatorPaintNControlComponent::setSpeakersRealBoundingCube ( const std::array< float, 6 > & speakersRealBoundingCube )

Provides the axis-aligned bounding cube of all loudspeaker positions.

Used by the "refit" button to snap the upmix ring transform so the ring fits neatly inside the physical speaker array.

Parameters

speakersRealBoundingCube {minX, minY, minZ, maxX, maxY, maxZ}.

Definition at line 146 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ setUpmixOffset()

void UmsciUpmixIndicatorPaintNControlComponent::setUpmixOffset	(	float	x,
		float	y
	)

Sets the ring centre offset in units of base radius.

Definition at line 873 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ setUpmixTransform()

void UmsciUpmixIndicatorPaintNControlComponent::setUpmixTransform	(	float	rot,
		float	trans,
		float	heightTrans,
		float	angleStretch = `1.0f`
	)

Applies all four transform parameters and triggers a prerender + repaint.

Definition at line 856 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ timerCallback()

void UmsciUpmixIndicatorPaintNControlComponent::timerCallback ( )

override

Definition at line 452 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

References Rectangle.

◆ triggerFlashCheck()

void UmsciUpmixIndicatorPaintNControlComponent::triggerFlashCheck ( )

Checks whether the ideal ring positions diverge from the stored DS100 positions and starts the flash timer if they do.

Use this after a programmatic transform update in manual mode (live mode off) to give the operator a visual cue that the device positions are out of sync and need to be sent manually. In live mode notifyTransformChanged() should be called instead (it sends the positions immediately).

Definition at line 910 of file UmsciUpmixIndicatorPaintNControlComponent.cpp.

Member Data Documentation

◆ onSourcePositionChanged

std::function<void(std::int16_t, std::array<std::float_t, 3>)> UmsciUpmixIndicatorPaintNControlComponent::onSourcePositionChanged

Fired when the user drags a source circle in live mode (pass-through from this component, analogous to UmsciSoundobjectsPaintComponent).

Definition at line 223 of file UmsciUpmixIndicatorPaintNControlComponent.h.

Referenced by mouseDoubleClick(), mouseDown(), mouseDrag(), and notifyTransformChanged().

◆ onTransformChanged

std::function<void()> UmsciUpmixIndicatorPaintNControlComponent::onTransformChanged

Fired whenever any transform parameter changes via an interactive drag, so UmsciControlComponent can persist the new values.

Definition at line 229 of file UmsciUpmixIndicatorPaintNControlComponent.h.

Referenced by mouseDown(), mouseUp(), and notifyTransformChanged().

The documentation for this class was generated from the following files:

Source/UmsciPaintNControlComponents/UmsciUpmixIndicatorPaintNControlComponent.h
Source/UmsciPaintNControlComponents/UmsciUpmixIndicatorPaintNControlComponent.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Purpose

What is rendered

Transform parameters

Drag gestures

hitTest and touch routing

Timer

Member Enumeration Documentation

◆ IndicatorShape

Constructor & Destructor Documentation

◆ UmsciUpmixIndicatorPaintNControlComponent()

◆ ~UmsciUpmixIndicatorPaintNControlComponent()

Member Function Documentation

◆ getLiveMode()

◆ getShape()

◆ getShapeForName()

◆ getShapeName()

◆ getSourceStartId()

◆ getUpmixAngleStretch()

◆ getUpmixHeightTrans()

◆ getUpmixOffsetX()

◆ getUpmixOffsetY()

◆ getUpmixRot()

◆ getUpmixTrans()

◆ hitTest()

◆ mouseDoubleClick()

◆ mouseDown()

◆ mouseDrag()

◆ mouseUp()

◆ notifyTransformChanged()

◆ paint()

◆ resized()

◆ setChannelConfiguration()

◆ setControlsSize()

◆ setLiveMode()

◆ setShape()

◆ setSourcePosition()

◆ setSourcePositions()

◆ setSourceStartId()

◆ setSpeakersRealBoundingCube()

◆ setUpmixOffset()

◆ setUpmixTransform()

◆ timerCallback()

◆ triggerFlashCheck()

Member Data Documentation

◆ onSourcePositionChanged

◆ onTransformChanged