The main visualisation and interaction surface for Umsci. More...

#include <UmsciControlComponent.h>

Inheritance diagram for UmsciControlComponent:

Collaboration diagram for UmsciControlComponent:

Public Member Functions
	UmsciControlComponent ()

	~UmsciControlComponent () override

void	resized () override

void	paint (juce::Graphics &g) override

void	parentHierarchyChanged () override

std::unique_ptr< XmlElement >	createStateXml () override

bool	setStateXml (XmlElement *stateXml) override

const std::pair< int, int > &	getOcp1IOSize ()
	Sets the DS100 input/output channel count for this session.

void	setOcp1IOSize (const std::pair< int, int > &ioSize)

void	setDeviceName (const std::string &name)
	Updates the device name label (shown as a title/overlay in the UI).

void	triggerUpmixTransformApplied ()
	Fires live-mode position callbacks and `onUpmixTransformChanged` after a programmatic transform update (e.g. from MIDI control).

void	triggerUpmixFlashCheck ()
	Starts the flash animation on the upmix indicator if the ideal ring positions diverge from the current DS100 positions.

void	setShowAllSources (bool showAll)
	When false, only sound objects that are part of the upmix group (i.e. channels >= sourceStartId within the upmix channel count) are rendered; all others are hidden.

bool	getShowAllSources () const

void	setControlsSize (UmsciPaintNControlComponentBase::ControlsSize size)
	Sets the visual size of source/speaker icons (small / medium / large).

UmsciPaintNControlComponentBase::ControlsSize	getControlsSize () const

void	resetData ()
	Clears all cached source/speaker data and marks the database incomplete.

Sound-object (matrix input) setters
Called by `setRemoteObject()` when the corresponding DS100 notification arrives. `sourceId` is 1-based (DS100 channels 1–128).
void	setSourceName (std::int16_t sourceId, const std::string &name)

void	setSourceMute (std::int16_t sourceId, const std::uint8_t &mute)
	0 = unmuted, nonzero = muted.

void	setSourceGain (std::int16_t sourceId, const std::float_t &gain)
	Gain in dB.

void	setSourcePosition (std::int16_t sourceId, const std::array< std::float_t, 3 > &position)
	Sets the 3-component (X, Y, Z) absolute position in normalised real-world coordinates.

void	setSourceDelayMode (std::int16_t sourceId, const std::uint16_t &delayMode)
	Delay mode: 0 = off, 1 = compensate, 2 = reflect (DS100-specific enum).

void	setSourceSpread (std::int16_t sourceId, const std::float_t &spread)
	Spread factor 0.0–1.0 (0 = point source, 1 = full spread).

Loudspeaker (matrix output) setters
Called by `setRemoteObject()` when the corresponding DS100 notification arrives. `speakerId` is 1-based (DS100 outputs 1–64).
void	setSpeakerName (std::int16_t speakerId, const std::string &name)

void	setSpeakerMute (std::int16_t speakerId, const std::uint8_t &mute)

void	setSpeakerGain (std::int16_t speakerId, const std::float_t &gain)

void	setSpeakerPosition (std::int16_t speakerId, const std::array< std::float_t, 6 > &position)
	Sets the 6-component speaker position: {X, Y, Z, horizontal angle, vertical angle, rotation}.

Upmix configuration
Settings for the upmix indicator overlay (`UmsciUpmixIndicatorPaintNControlComponent`). The upmix indicator shows a ring of virtual speaker positions representing the target upmix channel configuration (e.g. 5.1, 7.1, Atmos). The ring can be rotated, scaled (radius), stretched per-angle, and shifted (offset) by the user via on-screen handles. `sourceStartId` identifies the first DS100 sound-object channel that is assigned to the upmix renderer inputs; subsequent channels are implicitly consecutive. `liveMode` controls whether the upmix indicator actively follows incoming DS100 position updates or shows a static reference layout. Note [MANUAL CONTEXT NEEDED] Describe the upmix workflow: what does the indicator represent, how does it relate to an external upmix renderer, and what the user is expected to do with the transform handles.
void	setUpmixChannelConfiguration (const juce::AudioChannelSet &upmixChannelConfig)

const juce::AudioChannelSet	getUpmixChannelConfiguration ()

void	setUpmixSourceStartId (int startId)
	1-based DS100 channel of the first upmix input.

int	getUpmixSourceStartId () const

void	setUpmixLiveMode (bool liveMode)
	true = follow live DS100 positions.

bool	getUpmixLiveMode () const

void	setUpmixShape (UmsciUpmixIndicatorPaintNControlComponent::IndicatorShape shape)

UmsciUpmixIndicatorPaintNControlComponent::IndicatorShape	getUpmixShape () const

Upmix spatial transform
Controls the rotation, radial scale, height translation, and angular stretch of the upmix indicator ring relative to its default position. All values are in normalised units consistent with the component's coordinate system (see `UmsciPaintNControlComponentBase`). Changing any of these fires the `onUpmixTransformChanged` callback so that the values can be persisted.
void	setUpmixTransform (float rot, float trans, float heightTrans, float angleStretch=1.0f)

float	getUpmixRot () const
	Ring rotation in normalised units (0–1 → 0–360°).

float	getUpmixTrans () const
	Radial scale factor.

float	getUpmixHeightTrans () const
	Height (Z) translation.

float	getUpmixAngleStretch () const
	Per-angle stretch factor (1.0 = uniform).

Upmix ring offset
Translates the entire upmix ring in the X/Y plane independently of rotation.
void	setUpmixOffset (float x, float y)

float	getUpmixOffsetX () const

float	getUpmixOffsetY () const

Public Attributes
std::function< void()>	onDatabaseComplete
	Fired on the message thread when all initially subscribed values have been received from the DS100 (i.e. the "database" is fully populated). Consumers use this to trigger a first full render or to enable UI controls.

std::function< void()>	onUpmixTransformChanged
	Fired on the message thread whenever the user changes any upmix transform parameter via the on-screen handles, so the caller can persist the new values.

Detailed Description

The main visualisation and interaction surface for Umsci.

Composition

Three transparent JUCE Components are stacked in z-order, all sharing the same pixel bounds, and all using the same normalised coordinate system managed by UmsciPaintNControlComponentBase:

Layer (z-order)	Class	Purpose
Bottom	`UmsciLoudspeakersPaintComponent`	Paints speaker SVG icons at their real-world positions (read-only).
Middle	`UmsciSoundobjectsPaintComponent`	Paints and lets the user drag source circles.
Top	`UmsciUpmixIndicatorPaintNControlComponent`	Paints the upmix ring with rotation/scale/stretch handles.

Data flow

DeviceController::onRemoteObjectReceived (message thread) → setRemoteObject().
setRemoteObject() stores the value in m_source* / m_speaker* maps and calls the appropriate setter on the relevant paint component.
The paint component marks itself dirty and repaints on the next message-thread cycle.

"Database complete" concept

On each new connection, UmsciControlComponent waits until initial values have been received for every subscribed object before signalling onDatabaseComplete. Until then the visualisation may show stale or partial data.

Coordinate system

All source and speaker positions received from the DS100 are in a normalised real-world space (roughly 0.0–1.0 for X/Y, see UmsciPaintNControlComponentBase for the exact transform). The paint components convert these to pixel coordinates for rendering.

Note: [MANUAL CONTEXT NEEDED] Document the exact real-world coordinate units used by the DS100 (e.g. metres, normalised 0-1) and how they relate to the stage/room geometry so that contributors understand what the displayed numbers mean physically.

Viewport zoom and sibling synchronisation

All three layers share a single zoom state (scale factor + pan offset). When the user zooms on any layer, that layer fires UmsciPaintNControlComponentBase::onViewportZoomChanged; the syncViewportZoom lambda (wired up in the constructor) forwards the new state to the other two layers via setZoom(), which does not re-fire the callback.

On iOS/iPadOS, JUCE 8's touch routing delivers each finger as a separate MouseEvent routed to whichever component passes hitTest() at that position. Both fingers of a pinch therefore rarely arrive at the same JUCE component, making the JUCE-level processPinchGesture() fallback unreliable. parentHierarchyChanged() therefore attaches a native UIPinchGestureRecognizer (via JUCEAppBasics::iOS_utils::registerNativePinchOnView()) to the JUCE peer UIView the first time a peer becomes available. The UIKit gesture fires at the gesture- recognizer layer before JUCE's per-component touch routing, so it works regardless of which components the individual fingers hit. The incremental scale and centre point are forwarded to simulatePinchZoom() on one of the paint layers, which fires onViewportZoomChanged and thus synchronises all three siblings normally.

Definition at line 91 of file UmsciControlComponent.h.

Constructor & Destructor Documentation

◆ UmsciControlComponent()

UmsciControlComponent::UmsciControlComponent ( )

Definition at line 30 of file UmsciControlComponent.cpp.

References onUpmixTransformChanged, DeviceController::RemoteObject::Positioning_SourcePosition, DeviceController::RemObjAddr::sc_INV, and setOcp1IOSize().

◆ ~UmsciControlComponent()

UmsciControlComponent::~UmsciControlComponent ( )

override

Definition at line 85 of file UmsciControlComponent.cpp.

Member Function Documentation

◆ createStateXml()

std::unique_ptr< XmlElement > UmsciControlComponent::createStateXml ( )

override

Definition at line 146 of file UmsciControlComponent.cpp.

References UmsciAppConfiguration::CONTROLCONFIG, UmsciAppConfiguration::getAttributeName(), getOcp1IOSize(), UmsciAppConfiguration::getTagName(), and UmsciAppConfiguration::IOSIZE.

◆ getControlsSize()

UmsciPaintNControlComponentBase::ControlsSize UmsciControlComponent::getControlsSize ( ) const

Definition at line 642 of file UmsciControlComponent.cpp.

References UmsciPaintNControlComponentBase::S.

◆ getOcp1IOSize()

const std::pair< int, int > & UmsciControlComponent::getOcp1IOSize ( )

Sets the DS100 input/output channel count for this session.

The pair is {inputChannels, outputChannels}. It is used to limit which channel IDs are subscribed to and rendered.

The DS100 supports M / L / XL software licenses that set different maximum input and output channel counts. The I/O size is configured by the user in Umsci's connection settings and must match (or be within) the device's licensed capacity — it is not auto-detected from the device.

Note: [MANUAL CONTEXT NEEDED] Confirm whether Umsci validates the configured size against what the device reports, or simply trusts the user entry.

Definition at line 168 of file UmsciControlComponent.cpp.

Referenced by createStateXml(), and setStateXml().

◆ getShowAllSources()

bool UmsciControlComponent::getShowAllSources ( ) const

Definition at line 721 of file UmsciControlComponent.cpp.

◆ getUpmixAngleStretch()

float UmsciControlComponent::getUpmixAngleStretch ( ) const

Per-angle stretch factor (1.0 = uniform).

Definition at line 676 of file UmsciControlComponent.cpp.

◆ getUpmixChannelConfiguration()

const juce::AudioChannelSet UmsciControlComponent::getUpmixChannelConfiguration ( )

Definition at line 584 of file UmsciControlComponent.cpp.

◆ getUpmixHeightTrans()

float UmsciControlComponent::getUpmixHeightTrans ( ) const

Height (Z) translation.

Definition at line 669 of file UmsciControlComponent.cpp.

◆ getUpmixLiveMode()

bool UmsciControlComponent::getUpmixLiveMode ( ) const

Definition at line 612 of file UmsciControlComponent.cpp.

◆ getUpmixOffsetX()

float UmsciControlComponent::getUpmixOffsetX ( ) const

Definition at line 701 of file UmsciControlComponent.cpp.

◆ getUpmixOffsetY()

float UmsciControlComponent::getUpmixOffsetY ( ) const

Definition at line 708 of file UmsciControlComponent.cpp.

◆ getUpmixRot()

float UmsciControlComponent::getUpmixRot ( ) const

Ring rotation in normalised units (0–1 → 0–360°).

Definition at line 655 of file UmsciControlComponent.cpp.

◆ getUpmixShape()

UmsciUpmixIndicatorPaintNControlComponent::IndicatorShape UmsciControlComponent::getUpmixShape ( ) const

Definition at line 625 of file UmsciControlComponent.cpp.

References UmsciUpmixIndicatorPaintNControlComponent::Circle.

◆ getUpmixSourceStartId()

int UmsciControlComponent::getUpmixSourceStartId ( ) const

Definition at line 599 of file UmsciControlComponent.cpp.

◆ getUpmixTrans()

float UmsciControlComponent::getUpmixTrans ( ) const

Radial scale factor.

Definition at line 662 of file UmsciControlComponent.cpp.

◆ paint()

void UmsciControlComponent::paint ( juce::Graphics & g )

override

Definition at line 93 of file UmsciControlComponent.cpp.

◆ parentHierarchyChanged()

void UmsciControlComponent::parentHierarchyChanged ( )

override

Definition at line 117 of file UmsciControlComponent.cpp.

◆ resetData()

void UmsciControlComponent::resetData ( )

Clears all cached source/speaker data and marks the database incomplete.

Definition at line 474 of file UmsciControlComponent.cpp.

◆ resized()

void UmsciControlComponent::resized ( )

override

Definition at line 105 of file UmsciControlComponent.cpp.

Referenced by setSpeakerPosition().

◆ setControlsSize()

void UmsciControlComponent::setControlsSize ( UmsciPaintNControlComponentBase::ControlsSize size )

Sets the visual size of source/speaker icons (small / medium / large).

Definition at line 632 of file UmsciControlComponent.cpp.

◆ setDeviceName()

void UmsciControlComponent::setDeviceName ( const std::string & name )

Updates the device name label (shown as a title/overlay in the UI).

Definition at line 479 of file UmsciControlComponent.cpp.

◆ setOcp1IOSize()

void UmsciControlComponent::setOcp1IOSize ( const std::pair< int, int > & ioSize )

Definition at line 173 of file UmsciControlComponent.cpp.

Referenced by setStateXml(), and UmsciControlComponent().

◆ setShowAllSources()

void UmsciControlComponent::setShowAllSources ( bool showAll )

When false, only sound objects that are part of the upmix group (i.e. channels >= sourceStartId within the upmix channel count) are rendered; all others are hidden.

Definition at line 715 of file UmsciControlComponent.cpp.

◆ setSourceDelayMode()

void UmsciControlComponent::setSourceDelayMode	(	std::int16_t	sourceId,
		const std::uint16_t &	delayMode
	)

Delay mode: 0 = off, 1 = compensate, 2 = reflect (DS100-specific enum).

Definition at line 520 of file UmsciControlComponent.cpp.

◆ setSourceGain()

void UmsciControlComponent::setSourceGain	(	std::int16_t	sourceId,
		const std::float_t &	gain
	)

Gain in dB.

Definition at line 504 of file UmsciControlComponent.cpp.

◆ setSourceMute()

void UmsciControlComponent::setSourceMute	(	std::int16_t	sourceId,
		const std::uint8_t &	mute
	)

0 = unmuted, nonzero = muted.

Definition at line 489 of file UmsciControlComponent.cpp.

◆ setSourceName()

void UmsciControlComponent::setSourceName	(	std::int16_t	sourceId,
		const std::string &	name
	)

Definition at line 484 of file UmsciControlComponent.cpp.

◆ setSourcePosition()

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

Sets the 3-component (X, Y, Z) absolute position in normalised real-world coordinates.

Definition at line 509 of file UmsciControlComponent.cpp.

◆ setSourceSpread()

void UmsciControlComponent::setSourceSpread	(	std::int16_t	sourceId,
		const std::float_t &	spread
	)

Spread factor 0.0–1.0 (0 = point source, 1 = full spread).

Definition at line 525 of file UmsciControlComponent.cpp.

◆ setSpeakerGain()

void UmsciControlComponent::setSpeakerGain	(	std::int16_t	speakerId,
		const std::float_t &	gain
	)

Definition at line 549 of file UmsciControlComponent.cpp.

◆ setSpeakerMute()

void UmsciControlComponent::setSpeakerMute	(	std::int16_t	speakerId,
		const std::uint8_t &	mute
	)

Definition at line 535 of file UmsciControlComponent.cpp.

◆ setSpeakerName()

void UmsciControlComponent::setSpeakerName	(	std::int16_t	speakerId,
		const std::string &	name
	)

Definition at line 530 of file UmsciControlComponent.cpp.

◆ setSpeakerPosition()

void UmsciControlComponent::setSpeakerPosition	(	std::int16_t	speakerId,
		const std::array< std::float_t, 6 > &	position
	)

Sets the 6-component speaker position: {X, Y, Z, horizontal angle, vertical angle, rotation}.

Note: [MANUAL CONTEXT NEEDED] Document the exact units and axis conventions for each of the 6 components (e.g. metres vs. normalised, degrees vs. radians, coordinate handedness).

Definition at line 554 of file UmsciControlComponent.cpp.

References resized().

◆ setStateXml()

bool UmsciControlComponent::setStateXml ( XmlElement * stateXml )

override

Definition at line 155 of file UmsciControlComponent.cpp.

References UmsciAppConfiguration::CONTROLCONFIG, UmsciAppConfiguration::getAttributeName(), getOcp1IOSize(), UmsciAppConfiguration::getTagName(), UmsciAppConfiguration::IOSIZE, and setOcp1IOSize().

◆ setUpmixChannelConfiguration()

void UmsciControlComponent::setUpmixChannelConfiguration ( const juce::AudioChannelSet & upmixChannelConfig )

Definition at line 577 of file UmsciControlComponent.cpp.

◆ setUpmixLiveMode()

void UmsciControlComponent::setUpmixLiveMode ( bool liveMode )

true = follow live DS100 positions.

Definition at line 606 of file UmsciControlComponent.cpp.

◆ setUpmixOffset()

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

Definition at line 683 of file UmsciControlComponent.cpp.

◆ setUpmixShape()

void UmsciControlComponent::setUpmixShape ( UmsciUpmixIndicatorPaintNControlComponent::IndicatorShape shape )

Definition at line 619 of file UmsciControlComponent.cpp.

◆ setUpmixSourceStartId()

void UmsciControlComponent::setUpmixSourceStartId ( int startId )

1-based DS100 channel of the first upmix input.

Definition at line 592 of file UmsciControlComponent.cpp.

◆ setUpmixTransform()

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

Definition at line 649 of file UmsciControlComponent.cpp.

◆ triggerUpmixFlashCheck()

void UmsciControlComponent::triggerUpmixFlashCheck ( )

Starts the flash animation on the upmix indicator if the ideal ring positions diverge from the current DS100 positions.

Call this after a programmatic transform update when live mode is off, so the operator sees a visual cue that the device positions are out of sync.

Definition at line 695 of file UmsciControlComponent.cpp.

◆ triggerUpmixTransformApplied()

void UmsciControlComponent::triggerUpmixTransformApplied ( )

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

Call this after setUpmixTransform() / setUpmixOffset() when the change originates outside the UI (MIDI, automation) to ensure DS100 positions are updated in live mode and the config is marked dirty.

Definition at line 689 of file UmsciControlComponent.cpp.

Member Data Documentation

◆ onDatabaseComplete

std::function<void()> UmsciControlComponent::onDatabaseComplete

Fired on the message thread when all initially subscribed values have been received from the DS100 (i.e. the "database" is fully populated). Consumers use this to trigger a first full render or to enable UI controls.

Definition at line 267 of file UmsciControlComponent.h.

◆ onUpmixTransformChanged

std::function<void()> UmsciControlComponent::onUpmixTransformChanged

Fired on the message thread whenever the user changes any upmix transform parameter via the on-screen handles, so the caller can persist the new values.

Definition at line 273 of file UmsciControlComponent.h.

Referenced by UmsciControlComponent().

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

Source/UmsciControlComponent.h
Source/UmsciControlComponent.cpp

Public Member Functions

Public Attributes

Detailed Description

Composition

Data flow

"Database complete" concept

Coordinate system

Viewport zoom and sibling synchronisation

Constructor & Destructor Documentation

◆ UmsciControlComponent()

◆ ~UmsciControlComponent()

Member Function Documentation

◆ createStateXml()

◆ getControlsSize()

◆ getOcp1IOSize()

◆ getShowAllSources()

◆ getUpmixAngleStretch()

◆ getUpmixChannelConfiguration()

◆ getUpmixHeightTrans()

◆ getUpmixLiveMode()

◆ getUpmixOffsetX()

◆ getUpmixOffsetY()

◆ getUpmixRot()

◆ getUpmixShape()

◆ getUpmixSourceStartId()

◆ getUpmixTrans()

◆ paint()

◆ parentHierarchyChanged()

◆ resetData()

◆ resized()

◆ setControlsSize()

◆ setDeviceName()

◆ setOcp1IOSize()

◆ setShowAllSources()

◆ setSourceDelayMode()

◆ setSourceGain()

◆ setSourceMute()

◆ setSourceName()

◆ setSourcePosition()

◆ setSourceSpread()

◆ setSpeakerGain()

◆ setSpeakerMute()

◆ setSpeakerName()

◆ setSpeakerPosition()

◆ setStateXml()

◆ setUpmixChannelConfiguration()

◆ setUpmixLiveMode()

◆ setUpmixOffset()

◆ setUpmixShape()

◆ setUpmixSourceStartId()

◆ setUpmixTransform()

◆ triggerUpmixFlashCheck()

◆ triggerUpmixTransformApplied()

Member Data Documentation

◆ onDatabaseComplete

◆ onUpmixTransformChanged