An instance of sACN DMX Merger functionality; see Using the sACN DMX Merger API. More...

#include <dmx_merger.h>

Data Structures
struct	Settings
	A set of configuration settings that a merger needs to initialize. More...

Public Types
using	Handle = etcpal::OpaqueId<detail::DmxMergerHandleType, sacn_dmx_merger_t, SACN_DMX_MERGER_INVALID>

Public Member Functions
	DmxMerger (const DmxMerger &other)=delete

DmxMerger &	operator= (const DmxMerger &other)=delete

	DmxMerger (DmxMerger &&other)=default

DmxMerger &	operator= (DmxMerger &&other)=default

etcpal::Error	Startup (const Settings &settings)
	Create a new merger instance.

void	Shutdown ()
	Destroy a merger instance.

etcpal::Expected< sacn_dmx_merger_source_t >	AddSource ()
	Adds a new source to the merger.

etcpal::Error	RemoveSource (sacn_dmx_merger_source_t source)
	Removes a source from the merger.

const SacnDmxMergerSource *	GetSourceInfo (sacn_dmx_merger_source_t source) const
	Gets a read-only view of the source data.

etcpal::Error	UpdateLevels (sacn_dmx_merger_source_t source, const uint8_t *new_levels, size_t new_levels_count)
	Updates a source's levels and recalculates outputs.

etcpal::Error	UpdatePap (sacn_dmx_merger_source_t source, const uint8_t *pap, size_t pap_count)
	Updates a source's per-address priorities (PAP) and recalculates outputs.

etcpal::Error	UpdateUniversePriority (sacn_dmx_merger_source_t source, uint8_t universe_priority)
	Updates a source's universe priority and recalculates outputs.

etcpal::Error	RemovePap (sacn_dmx_merger_source_t source)
	Removes the per-address priority (PAP) data from the source and recalculate outputs.

constexpr Handle	handle () const
	Get the current handle to the underlying C DMX merger.

Detailed Description

An instance of sACN DMX Merger functionality; see Using the sACN DMX Merger API.

This class instantiates software mergers for buffers containing DMX512-A start code 0 packets. It also uses buffers containing DMX512-A start code 0xdd packets to support per-address priority.

When asked to calculate the merge, the merger will evaluate the current source buffers and update two result buffers:

512 bytes for the merged data levels (i.e. "winning level"). These are calculated by using a Highest-Level-Takes-Precedence(HTP) algorithm for all sources that share the highest per-address priority.
512 source identifiers (i.e. "winning source") to indicate which source was considered the source of the merged data level, or that no source currently owns this address.

See Using the sACN DMX Merger API for a detailed description of how to use this API.

Member Typedef Documentation

◆ Handle

using Handle = etcpal::OpaqueId<detail::DmxMergerHandleType, sacn_dmx_merger_t, SACN_DMX_MERGER_INVALID>

A handle type used by the sACN library to identify merger instances.

Constructor & Destructor Documentation

◆ DmxMerger()

DmxMerger ( DmxMerger && other )

default

Move a dmx merger instance.

Member Function Documentation

◆ AddSource()

etcpal::Expected< sacn_dmx_merger_source_t > AddSource ( )

inline

Adds a new source to the merger.

Adds a new source to the merger, if the maximum number of sources hasn't been reached. The returned source id is used for two purposes:

It is the handle for calls that need to access the source data.
It is the source identifer that is put into the owners buffer that was passed in the DmxMergerUniverseConfig structure when creating the merger.

Returns: The successfully added source_id.; kEtcPalErrInvalid: The merger was not started correctly.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: No room to allocate memory for this source, or the max number of sources has been reached.; kEtcPalErrSys: An internal library or system call error occurred.

◆ GetSourceInfo()

const SacnDmxMergerSource * GetSourceInfo ( sacn_dmx_merger_source_t source ) const

inline

Gets a read-only view of the source data.

Looks up the source data and returns a pointer to the data or nullptr if it doesn't exist. This pointer is owned by the library, and must not be modified by the application. The pointer will only be valid until the source or merger is removed.

Parameters

[in] source The id of the source.

Returns: The reference to the source data, otherwise kEtcPalErrInvalid.

◆ handle()

DmxMerger::Handle handle ( ) const

inlineconstexpr

Get the current handle to the underlying C DMX merger.

Returns: The handle, which will only be valid if the DMX merger has been successfully created using Startup().

◆ operator=()

DmxMerger & operator= ( DmxMerger && other )

default

Move a dmx merger instance.

◆ RemovePap()

etcpal::Error RemovePap ( sacn_dmx_merger_source_t source )

inline

Removes the per-address priority (PAP) data from the source and recalculate outputs.

Per-address priority data can time out in sACN just like levels. This is a convenience function to immediately turn off the per-address priority data for a source and recalculate the outputs.

Parameters

[in] source The id of the source to modify.

Returns: kEtcPalErrOk: Source updated and merge completed.; kEtcPalErrNotFound: Handle does not correspond to a valid source or merger.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrSys: An internal library or system call error occurred.

◆ RemoveSource()

etcpal::Error RemoveSource ( sacn_dmx_merger_source_t source )

inline

Removes a source from the merger.

Removes the source from the merger. This causes the merger to recalculate the outputs.

Parameters

[in] source The id of the source to remove.

Returns: kEtcPalErrOk: Source removed successfully.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Shutdown()

void Shutdown ( )

inline

Destroy a merger instance.

Tears down the merger and cleans up its resources.

Returns: kEtcPalErrOk: Merger destroyed successfully.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle does not correspond to a valid merger.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Startup()

etcpal::Error Startup ( const Settings & settings )

inline

Create a new merger instance.

Creates a new merger that uses the passed in config data. The application owns all buffers in the config, so be sure to call Shutdown() before destroying the buffers.

Parameters

[in] settings Configuration parameters for the DMX merger to be created.

Returns: kEtcPalErrOk: Merger created successful.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: No room to allocate memory for this merger, or maximum number of mergers has been reached.; kEtcPalErrSys: An internal library or system call error occurred.

◆ UpdateLevels()

etcpal::Error UpdateLevels	(	sacn_dmx_merger_source_t	source,
		const uint8_t *	new_levels,
		size_t	new_levels_count )

inline

Updates a source's levels and recalculates outputs.

This function updates the levels of the specified source, and then triggers the recalculation of each slot. For each slot, the source will only be included in the merge if it has a priority at that slot. Otherwise the level will be saved for when a priority is eventually inputted.

Parameters

[in]	source	The id of the source to modify.
[in]	new_levels	The new DMX levels to be copied in, starting from the first slot.
[in]	new_levels_count	The length of new_levels. If this is less than DMX_ADDRESS_COUNT, the levels for all remaining levels will be set to 0.

Returns: kEtcPalErrOk: Source updated and merge completed.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle does not correspond to a valid source or merger.; kEtcPalErrSys: An internal library or system call error occurred.

◆ UpdatePap()

etcpal::Error UpdatePap	(	sacn_dmx_merger_source_t	source,
		const uint8_t *	pap,
		size_t	pap_count )

inline

Updates a source's per-address priorities (PAP) and recalculates outputs.

This function updates the per-address priorities (PAP) of the specified source, and then triggers the recalculation of each slot. For each slot, the source will only be included in the merge if it has a priority at that slot.

If PAP is not specified for all levels, then the remaining levels will default to a PAP of 0. To remove PAP for this source and revert to the universe priority, call DmxMerger::RemovePap.

Parameters

[in]	source	The id of the source to modify.
[in]	pap	The per-address priorities to be copied in, starting from the first slot.
[in]	pap_count	The length of pap.

Returns: kEtcPalErrOk: Source updated and merge completed.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle does not correspond to a valid source or merger.; kEtcPalErrSys: An internal library or system call error occurred.

◆ UpdateUniversePriority()

etcpal::Error UpdateUniversePriority	(	sacn_dmx_merger_source_t	source,
		uint8_t	universe_priority )

inline

Updates a source's universe priority and recalculates outputs.

This function updates the universe priority of the specified source, and then triggers the recalculation of each slot. For each slot, the source will only be included in the merge if it has a priority at that slot.

If this source currently has per-address priorities (PAP) via DmxMerger::UpdatePap, then the universe priority can have no effect on the merge results until the application calls DmxMerger::RemovePap, at which point the priorities of each slot will revert to the universe priority passed in here.

If this source doesn't have PAP, then the universe priority is converted into PAP for each slot. These are the priorities used for the merge. This means a universe priority of 0 will be converted to a PAP of 1.

Parameters

[in]	source	The id of the source to modify.
[in]	universe_priority	The universe-level priority of the source.

Returns: kEtcPalErrOk: Source updated and merge completed.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle does not correspond to a valid source or merger.; kEtcPalErrSys: An internal library or system call error occurred.

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

include/sacn/cpp/dmx_merger.h

Data Structures

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Handle

Constructor & Destructor Documentation

◆ DmxMerger()

Member Function Documentation

◆ AddSource()

◆ GetSourceInfo()

◆ handle()

◆ operator=()

◆ RemovePap()

◆ RemoveSource()

◆ Shutdown()

◆ Startup()

◆ UpdateLevels()

◆ UpdatePap()

◆ UpdateUniversePriority()