The sACN DMX Merger API; see Using the sACN DMX Merger API. More...

Data Structures
struct	SacnDmxMergerConfig

struct	SacnDmxMergerSource

Macros
#define	SACN_DMX_MERGER_INVALID -1

#define	SACN_DMX_MERGER_SOURCE_INVALID ((sacn_dmx_merger_source_t)-1)

#define	SACN_DMX_MERGER_CONFIG_INIT
	An initializer for an SacnDmxMergerConfig struct.

#define	SACN_DMX_MERGER_SOURCE_IS_VALID(owners_array, slot_index) (owners_array[slot_index] != SACN_DMX_MERGER_SOURCE_INVALID)
	Utility to see if a slot owner is valid.

Typedefs
typedef int	sacn_dmx_merger_t

typedef uint16_t	sacn_dmx_merger_source_t

typedef struct SacnDmxMergerConfig	SacnDmxMergerConfig

typedef struct SacnDmxMergerSource	SacnDmxMergerSource

Functions
etcpal_error_t	sacn_dmx_merger_create (const SacnDmxMergerConfig config, sacn_dmx_merger_t handle)
	Create a new merger instance.

etcpal_error_t	sacn_dmx_merger_destroy (sacn_dmx_merger_t handle)
	Destroy a merger instance.

etcpal_error_t	sacn_dmx_merger_add_source (sacn_dmx_merger_t merger, sacn_dmx_merger_source_t *source_id)
	Adds a new source to the merger.

etcpal_error_t	sacn_dmx_merger_remove_source (sacn_dmx_merger_t merger, sacn_dmx_merger_source_t source)
	Removes a source from the merger.

const SacnDmxMergerSource *	sacn_dmx_merger_get_source (sacn_dmx_merger_t merger, sacn_dmx_merger_source_t source)
	Gets a read-only view of the source data.

etcpal_error_t	sacn_dmx_merger_update_levels (sacn_dmx_merger_t merger, 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_t	sacn_dmx_merger_update_pap (sacn_dmx_merger_t merger, 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_t	sacn_dmx_merger_update_universe_priority (sacn_dmx_merger_t merger, sacn_dmx_merger_source_t source, uint8_t universe_priority)
	Updates a source's universe priority and recalculates outputs.

etcpal_error_t	sacn_dmx_merger_remove_pap (sacn_dmx_merger_t merger, sacn_dmx_merger_source_t source)
	Removes the per-address priority (PAP) data from the source and recalculate outputs.

Detailed Description

The sACN DMX Merger API; see Using the sACN DMX Merger API.

This API provides a software merger 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.

This API is thread-safe.

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

Macro Definition Documentation

◆ SACN_DMX_MERGER_CONFIG_INIT

#define SACN_DMX_MERGER_CONFIG_INIT

Value:

  {                                                              \
    NULL, NULL, NULL, NULL, NULL, SACN_RECEIVER_INFINITE_SOURCES \
  }

An initializer for an SacnDmxMergerConfig struct.

Usage:

// Create the struct
SacnDmxMergerConfig merger_config = SACN_DMX_MERGER_CONFIG_INIT;
// Now fill in the members of the struct

◆ SACN_DMX_MERGER_INVALID

#define SACN_DMX_MERGER_INVALID -1

An invalid sACN merger handle value.

◆ SACN_DMX_MERGER_SOURCE_INVALID

#define SACN_DMX_MERGER_SOURCE_INVALID ((sacn_dmx_merger_source_t)-1)

An invalid DMX merger source handle value.

◆ SACN_DMX_MERGER_SOURCE_IS_VALID

#define SACN_DMX_MERGER_SOURCE_IS_VALID	(		owners_array,
			slot_index ) (owners_array[slot_index] != SACN_DMX_MERGER_SOURCE_INVALID)

Utility to see if a slot owner is valid.

Given a buffer of owners, evaluate to true if the owner is != DMX_MERGER_SOURCE_INVALID.

Typedef Documentation

◆ sacn_dmx_merger_source_t

typedef uint16_t sacn_dmx_merger_source_t

A source handle used by the DMX merger, could represent a remote source or another logical source (e.g. a local DMX port).

◆ sacn_dmx_merger_t

typedef int sacn_dmx_merger_t

Each merger has a handle associated with it.

◆ SacnDmxMergerConfig

typedef struct SacnDmxMergerConfig SacnDmxMergerConfig

A set of configuration information for a merger instance.

◆ SacnDmxMergerSource

typedef struct SacnDmxMergerSource SacnDmxMergerSource

The current input data for a single source of the merge. This is exposed as read-only information.

Function Documentation

◆ sacn_dmx_merger_add_source()

etcpal_error_t sacn_dmx_merger_add_source	(	sacn_dmx_merger_t	merger,
		sacn_dmx_merger_source_t *	source_id )

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 filled in 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.

Parameters

[in]	merger	The handle to the merger.
[out]	source_id	Filled in on success with the source id.

Returns: kEtcPalErrOk: Source added successfully.; kEtcPalErrInvalid: Invalid parameter provided.; 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.

◆ sacn_dmx_merger_create()

etcpal_error_t sacn_dmx_merger_create	(	const SacnDmxMergerConfig *	config,
		sacn_dmx_merger_t *	handle )

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 dmx_merger_destroy before destroying the buffers.

Parameters

[in]	config	Configuration parameters for the DMX merger to be created.
[out]	handle	Filled in on success with a handle to the merger.

Returns: kEtcPalErrOk: Merger created successfully.; 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.

◆ sacn_dmx_merger_destroy()

etcpal_error_t sacn_dmx_merger_destroy ( sacn_dmx_merger_t handle )

Destroy a merger instance.

Tears down the merger and cleans up its resources.

Parameters

[in] handle Handle to the merger to destroy.

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.

◆ sacn_dmx_merger_get_source()

const SacnDmxMergerSource * sacn_dmx_merger_get_source	(	sacn_dmx_merger_t	merger,
		sacn_dmx_merger_source_t	source )

Gets a read-only view of the source data.

Looks up the source data and returns a pointer to the data or NULL 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]	merger	The handle to the merger.
[in]	source	The id of the source.

Returns: The pointer to the source data, or NULL if the source wasn't found.

◆ sacn_dmx_merger_remove_pap()

etcpal_error_t sacn_dmx_merger_remove_pap	(	sacn_dmx_merger_t	merger,
		sacn_dmx_merger_source_t	source )

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]	merger	The handle to the merger.
[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.

◆ sacn_dmx_merger_remove_source()

etcpal_error_t sacn_dmx_merger_remove_source	(	sacn_dmx_merger_t	merger,
		sacn_dmx_merger_source_t	source )

Removes a source from the merger.

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

Parameters

[in]	merger	The handle to the merger.
[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.

◆ sacn_dmx_merger_update_levels()

etcpal_error_t sacn_dmx_merger_update_levels	(	sacn_dmx_merger_t	merger,
		sacn_dmx_merger_source_t	source,
		const uint8_t *	new_levels,
		size_t	new_levels_count )

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]	merger	The handle to the merger.
[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.

◆ sacn_dmx_merger_update_pap()

etcpal_error_t sacn_dmx_merger_update_pap	(	sacn_dmx_merger_t	merger,
		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.

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

Parameters

[in]	merger	The handle to the merger.
[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.

◆ sacn_dmx_merger_update_universe_priority()

etcpal_error_t sacn_dmx_merger_update_universe_priority	(	sacn_dmx_merger_t	merger,
		sacn_dmx_merger_source_t	source,
		uint8_t	universe_priority )

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 sacn_dmx_merger_update_pap, then the universe priority can have no effect on the merge results until the application calls sacn_dmx_merger_remove_pap, 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]	merger	The handle to the merger.
[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.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SACN_DMX_MERGER_CONFIG_INIT

◆ SACN_DMX_MERGER_INVALID

◆ SACN_DMX_MERGER_SOURCE_INVALID

◆ SACN_DMX_MERGER_SOURCE_IS_VALID

Typedef Documentation

◆ sacn_dmx_merger_source_t

◆ sacn_dmx_merger_t

◆ SacnDmxMergerConfig

◆ SacnDmxMergerSource

Function Documentation

◆ sacn_dmx_merger_add_source()

◆ sacn_dmx_merger_create()

◆ sacn_dmx_merger_destroy()

◆ sacn_dmx_merger_get_source()

◆ sacn_dmx_merger_remove_pap()

◆ sacn_dmx_merger_remove_source()

◆ sacn_dmx_merger_update_levels()

◆ sacn_dmx_merger_update_pap()

◆ sacn_dmx_merger_update_universe_priority()