Abstract base class for all three overlaid visualisation layers in UmsciControlComponent. More...

#include <UmsciPaintNControlComponentBase.h>

Inheritance diagram for UmsciPaintNControlComponentBase:

Collaboration diagram for UmsciPaintNControlComponentBase:

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

Public Member Functions
	UmsciPaintNControlComponentBase ()

virtual	~UmsciPaintNControlComponentBase () override

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

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

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).

Public Attributes
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()`.

Protected Member Functions
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.

virtual void	onZoomChanged ()
	Called after any zoom state change.

Detailed Description

Abstract base class for all three overlaid visualisation layers in UmsciControlComponent.

Coordinate system

The DS100 reports positions in a normalised real-world space where both X and Y are in the range [0.0, 1.0] (origin at top-left when viewed from above, X = left→right, Y = top→bottom relative to the room). m_boundsRealRef defines which rectangle of that space is currently visible in the component's pixel bounds.

GetPointForRealCoordinate() and GetRealCoordinateForPoint() perform the two-way mapping between real-world coordinates and component pixel coordinates, taking the current zoom state into account.

Zoom

A viewport zoom is maintained as a scale factor and a normalised pan offset:

m_zoomFactor (1.0 = no zoom, clamped [0.1, 10.0]).
m_zoomPanOffset — centre offset expressed as a fraction of the base content width/height so that the pan survives component resizes without drifting.

Zoom input is accepted from multiple sources depending on platform:

Mouse-wheel (mouseWheelMove) — all desktop platforms.
Trackpad / Magic Mouse pinch (mouseMagnify) — macOS and iPadOS pointer devices.
Native two-finger touch pinch (simulatePinchZoom) — iOS/iPadOS touchscreens. UmsciControlComponent attaches a UIPinchGestureRecognizer to the JUCE peer UIView via parentHierarchyChanged(), then routes each incremental-scale callback to simulatePinchZoom(). This is required because JUCE 8's iOS peer routes each finger touch to whichever JUCE component passes hitTest() at that position, so both fingers of a pinch rarely land on the same component — making the JUCE-level fallback below unreliable.
JUCE-level two-touch fallback (processPinchGesture) — for platforms where neither mouseMagnify nor a native gesture recognizer is available (e.g. Android). Tracks the two lowest touch indices independently; activates only when both fingers arrive at the same component.

All paths ultimately call applyZoomAtScreenPoint() which keeps the focal point stationary in world space. Double-clicking any empty area resets zoom to 1.0.

setZoom() silently applies new zoom values (used when synchronising siblings). resetZoom() fires onViewportZoomChanged so all siblings reset together.

Sibling synchronisation

All three layers in UmsciControlComponent share the same m_boundsRealRef and must always show the same viewport. When the user zooms on any layer, that layer fires onViewportZoomChanged; UmsciControlComponent catches it and calls setZoom() on the other two layers (which does NOT re-fire the callback).

Derived class contract

Derived classes must override onZoomChanged() to re-run any pre-render pass (e.g. converting world positions to pixel positions) before repaint() is called. The base implementation just calls repaint().

Definition at line 77 of file UmsciPaintNControlComponentBase.h.

Member Enumeration Documentation

◆ ControlsSize

enum class UmsciPaintNControlComponentBase::ControlsSize

strong

Visual size of source/speaker icons. Multiplier accessible via getControlsSizeMultiplier().

Enumerator
S
M
L

Definition at line 81 of file UmsciPaintNControlComponentBase.h.

Constructor & Destructor Documentation

◆ UmsciPaintNControlComponentBase()

UmsciPaintNControlComponentBase::UmsciPaintNControlComponentBase ( )

Definition at line 22 of file UmsciPaintNControlComponentBase.cpp.

◆ ~UmsciPaintNControlComponentBase()

UmsciPaintNControlComponentBase::~UmsciPaintNControlComponentBase ( )

overridevirtual

Definition at line 27 of file UmsciPaintNControlComponentBase.cpp.

Member Function Documentation

◆ getControlsSize()

UmsciPaintNControlComponentBase::ControlsSize UmsciPaintNControlComponentBase::getControlsSize ( ) const

Definition at line 37 of file UmsciPaintNControlComponentBase.cpp.

◆ getControlsSizeMultiplier()

float UmsciPaintNControlComponentBase::getControlsSizeMultiplier ( ) const

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

Definition at line 42 of file UmsciPaintNControlComponentBase.cpp.

References L, M, and S.

Referenced by UmsciSoundobjectsPaintComponent::hitTest(), UmsciSoundobjectsPaintComponent::mouseDown(), UmsciLoudspeakersPaintComponent::paint(), UmsciSoundobjectsPaintComponent::paint(), UmsciUpmixIndicatorPaintNControlComponent::paint(), and UmsciLoudspeakersPaintComponent::setSpeakerPosition().

◆ GetPointForRealCoordinate()

juce::Point< float > UmsciPaintNControlComponentBase::GetPointForRealCoordinate ( const std::array< float, 3 > & realCoordinate )

protected

Converts a 3D real-world coordinate to a 2D screen pixel point.

Uses m_boundsRealRef and the current zoom state. The Z component of the real coordinate is ignored for 2D rendering (XY plane only).

Definition at line 244 of file UmsciPaintNControlComponentBase.cpp.

Referenced by UmsciSoundobjectsPaintComponent::setSourcePosition(), and UmsciLoudspeakersPaintComponent::setSpeakerPosition().

◆ GetRealCoordinateForPoint()

std::array< float, 3 > UmsciPaintNControlComponentBase::GetRealCoordinateForPoint ( const juce::Point< float > & screenPoint )

protected

Inverse of GetPointForRealCoordinate — converts a screen pixel point back to a 3D real-world coordinate (Z is set to 0).

Definition at line 228 of file UmsciPaintNControlComponentBase.cpp.

Referenced by UmsciSoundobjectsPaintComponent::mouseDrag().

◆ getZoomFactor()

float UmsciPaintNControlComponentBase::getZoomFactor ( ) const

Definition at line 210 of file UmsciPaintNControlComponentBase.cpp.

◆ mouseDoubleClick()

void UmsciPaintNControlComponentBase::mouseDoubleClick ( const juce::MouseEvent & )

overrideprotected

Double-click resets zoom to 1.0 via resetZoom().

Definition at line 105 of file UmsciPaintNControlComponentBase.cpp.

References resetZoom().

Referenced by UmsciUpmixIndicatorPaintNControlComponent::mouseDoubleClick().

◆ mouseMagnify()

void UmsciPaintNControlComponentBase::mouseMagnify	(	const juce::MouseEvent &	e,
		float	scaleFactor
	)

overrideprotected

Trackpad pinch-to-zoom (macOS).

Definition at line 122 of file UmsciPaintNControlComponentBase.cpp.

References onViewportZoomChanged, and onZoomChanged().

◆ mouseWheelMove()

void UmsciPaintNControlComponentBase::mouseWheelMove	(	const juce::MouseEvent &	e,
		const juce::MouseWheelDetails &	wheel
	)

overrideprotected

Mouse-wheel zooms about the cursor position.

Definition at line 110 of file UmsciPaintNControlComponentBase.cpp.

References onViewportZoomChanged, and onZoomChanged().

◆ onZoomChanged()

void UmsciPaintNControlComponentBase::onZoomChanged ( )

protectedvirtual

Called after any zoom state change.

Base implementation calls repaint(). Derived classes should override to re-run their prerender pass (world→pixel coordinate conversion) before painting, then call the base or call repaint() directly.

Definition at line 194 of file UmsciPaintNControlComponentBase.cpp.

Referenced by mouseMagnify(), mouseWheelMove(), processPinchGesture(), resetZoom(), setZoom(), and simulatePinchZoom().

◆ processPinchGesture()

bool UmsciPaintNControlComponentBase::processPinchGesture	(	const juce::MouseEvent &	e,
		bool	isDown,
		bool	isUp
	)

protected

JUCE-level two-touch pinch-zoom fallback for platforms where neither mouseMagnify nor a native gesture recognizer is available.

Tracks the two lowest source.getIndex() values independently. A pinch activates only when both touches are tracked by the same component — which requires both fingers to pass that component's hitTest(). On iOS this condition is rarely met (fingers land on different JUCE components), so the native UIPinchGestureRecognizer path via simulatePinchZoom() is preferred there. On Android or other platforms without a native recognizer this fallback remains the primary two-finger zoom mechanism.

Call this at the top of each derived-class mouseDown, mouseDrag, and mouseUp override, passing the event and the appropriate isDown/isUp flags. When the method returns true the event has been consumed by the pinch recogniser and the caller should return immediately without performing any normal single-touch interaction.

Parameters

e	The incoming mouse event.
isDown	True when called from `mouseDown`.
isUp	True when called from `mouseUp`.

Returns: True if the event was consumed by pinch tracking.

Definition at line 132 of file UmsciPaintNControlComponentBase.cpp.

References onViewportZoomChanged, and onZoomChanged().

Referenced by UmsciUpmixIndicatorPaintNControlComponent::mouseDown(), UmsciSoundobjectsPaintComponent::mouseDown(), UmsciUpmixIndicatorPaintNControlComponent::mouseDrag(), UmsciSoundobjectsPaintComponent::mouseDrag(), UmsciUpmixIndicatorPaintNControlComponent::mouseUp(), and UmsciSoundobjectsPaintComponent::mouseUp().

◆ resetZoom()

void UmsciPaintNControlComponentBase::resetZoom ( )

Resets zoom to 1.0 / no pan and fires onViewportZoomChanged.

Definition at line 215 of file UmsciPaintNControlComponentBase.cpp.

References onViewportZoomChanged, and onZoomChanged().

Referenced by mouseDoubleClick().

◆ setBoundsRealRef()

void UmsciPaintNControlComponentBase::setBoundsRealRef ( const juce::Rectangle< float > & boundsRealRef )

Sets the real-world rectangle that the component's pixel bounds map to.

Must be called on all three sibling layers whenever the bounding rectangle of the speaker/source data changes (e.g. after the DS100 reports speaker positions that extend beyond the previous bounds). All layers share the same reference.

Definition at line 56 of file UmsciPaintNControlComponentBase.cpp.

◆ setControlsSize()

void UmsciPaintNControlComponentBase::setControlsSize ( ControlsSize size )

virtual

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

Reimplemented in UmsciLoudspeakersPaintComponent, and UmsciUpmixIndicatorPaintNControlComponent.

Definition at line 31 of file UmsciPaintNControlComponentBase.cpp.

Referenced by UmsciLoudspeakersPaintComponent::setControlsSize(), and UmsciUpmixIndicatorPaintNControlComponent::setControlsSize().

◆ setZoom()

void UmsciPaintNControlComponentBase::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.

Parameters

factor	Zoom scale factor (clamped to [0.1, 10.0]).
normalizedPanOffset	Pan offset as a fraction of base content dimensions.

Definition at line 199 of file UmsciPaintNControlComponentBase.cpp.

References onZoomChanged().

◆ simulatePinchZoom()

void UmsciPaintNControlComponentBase::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).

Intended for use with a platform-native gesture recognizer (e.g. UIPinchGestureRecognizer on iOS) that delivers incremental scale factors. The call fires onViewportZoomChanged so that sibling layers are synchronised via the normal zoom-sync path.

Parameters

scaleFactor	Incremental scale factor since the previous callback (>0, 1.0 = no change).
centre	Focal point in component-local pixel space.

Definition at line 186 of file UmsciPaintNControlComponentBase.cpp.

References onViewportZoomChanged, and onZoomChanged().

Member Data Documentation

◆ onViewportZoomChanged

std::function<void(float, juce::Point<float>)> UmsciPaintNControlComponentBase::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().

Definition at line 121 of file UmsciPaintNControlComponentBase.h.

Referenced by mouseMagnify(), mouseWheelMove(), processPinchGesture(), resetZoom(), and simulatePinchZoom().

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

Source/UmsciPaintNControlComponents/UmsciPaintNControlComponentBase.h
Source/UmsciPaintNControlComponents/UmsciPaintNControlComponentBase.cpp

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Coordinate system

Zoom

Sibling synchronisation

Derived class contract

Member Enumeration Documentation

◆ ControlsSize

Constructor & Destructor Documentation

◆ UmsciPaintNControlComponentBase()

◆ ~UmsciPaintNControlComponentBase()

Member Function Documentation

◆ getControlsSize()

◆ getControlsSizeMultiplier()

◆ GetPointForRealCoordinate()

◆ GetRealCoordinateForPoint()

◆ getZoomFactor()

◆ mouseDoubleClick()

◆ mouseMagnify()

◆ mouseWheelMove()

◆ onZoomChanged()

◆ processPinchGesture()

◆ resetZoom()

◆ setBoundsRealRef()

◆ setControlsSize()

◆ setZoom()

◆ simulatePinchZoom()

Member Data Documentation

◆ onViewportZoomChanged