sACN Source

The sACN Source API; see Using the sACN Source API. More...

Data Structures
struct	SacnSourceConfig
struct	SacnSourceUniverseConfig
struct	SacnSourceUniverseNetintList

Macros
#define	SACN_SOURCE_INVALID   -1
#define	SACN_SOURCE_INFINITE_UNIVERSES   0
	Constant for "infinite" when sending sACN universes. More...
#define	SACN_SOURCE_KEEP_ALIVE_INTERVAL_DEFAULT   800
#define	SACN_SOURCE_CONFIG_DEFAULT_INIT
#define	SACN_SOURCE_UNIVERSE_CONFIG_DEFAULT_INIT

Typedefs
typedef int	sacn_source_t
typedef struct SacnSourceConfig	SacnSourceConfig
typedef struct SacnSourceUniverseConfig	SacnSourceUniverseConfig
typedef struct SacnSourceUniverseNetintList	SacnSourceUniverseNetintList

Functions
void	sacn_source_config_init (SacnSourceConfig *config)
	Initialize an sACN Source Config struct to default values. More...
void	sacn_source_universe_config_init (SacnSourceUniverseConfig *config)
	Initialize an sACN Source Universe Config struct to default values. More...
etcpal_error_t	sacn_source_create (const SacnSourceConfig *config, sacn_source_t *handle)
	Create a new sACN source to send sACN data. More...
void	sacn_source_destroy (sacn_source_t handle)
	Destroy an sACN source instance. More...
etcpal_error_t	sacn_source_change_name (sacn_source_t handle, const char *new_name)
	Change the name of an sACN source. More...
etcpal_error_t	sacn_source_add_universe (sacn_source_t handle, const SacnSourceUniverseConfig *config, const SacnNetintConfig *netint_config)
	Add a universe to an sACN source. More...
void	sacn_source_remove_universe (sacn_source_t handle, uint16_t universe)
	Remove a universe from a source. More...
size_t	sacn_source_get_universes (sacn_source_t handle, uint16_t *universes, size_t universes_size)
	Obtain a list of a source's universes. More...
etcpal_error_t	sacn_source_add_unicast_destination (sacn_source_t handle, uint16_t universe, const EtcPalIpAddr *dest)
	Add a unicast destination for a source's universe. More...
void	sacn_source_remove_unicast_destination (sacn_source_t handle, uint16_t universe, const EtcPalIpAddr *dest)
	Remove a unicast destination on a source's universe. More...
size_t	sacn_source_get_unicast_destinations (sacn_source_t handle, uint16_t universe, EtcPalIpAddr *destinations, size_t destinations_size)
	Obtain a list of a universe's unicast destinations. More...
etcpal_error_t	sacn_source_change_priority (sacn_source_t handle, uint16_t universe, uint8_t new_priority)
	Change the priority of a universe on a sACN source. More...
etcpal_error_t	sacn_source_change_preview_flag (sacn_source_t handle, uint16_t universe, bool new_preview_flag)
	Change the send_preview option on a universe of a sACN source. More...
etcpal_error_t	sacn_source_change_synchronization_universe (sacn_source_t handle, uint16_t universe, uint16_t new_sync_universe)
	Changes the synchronization universe for a universe of a sACN source. More...
etcpal_error_t	sacn_source_send_now (sacn_source_t handle, uint16_t universe, uint8_t start_code, const uint8_t *buffer, size_t buflen)
	Immediately sends the provided sACN start code & data. More...
etcpal_error_t	sacn_source_send_synchronization (sacn_source_t handle, uint16_t universe)
	Indicate that a new synchronization packet should be sent on the given synchronization universe. More...
void	sacn_source_update_levels (sacn_source_t handle, uint16_t universe, const uint8_t *new_levels, size_t new_levels_size)
	Copies the universe's DMX levels into the packet to be sent on the next threaded or manual update. More...
void	sacn_source_update_levels_and_pap (sacn_source_t handle, uint16_t universe, const uint8_t *new_levels, size_t new_levels_size, const uint8_t *new_priorities, size_t new_priorities_size)
	Copies the universe's DMX levels and per-address priorities into packets that are sent on the next threaded or manual update. More...
void	sacn_source_update_levels_and_force_sync (sacn_source_t handle, uint16_t universe, const uint8_t *new_levels, size_t new_levels_size)
	Like sacn_source_update_levels(), but also sets the force_sync flag on the packet. More...
void	sacn_source_update_levels_and_pap_and_force_sync (sacn_source_t handle, uint16_t universe, const uint8_t *new_levels, size_t new_levels_size, const uint8_t *new_priorities, size_t new_priorities_size)
	Like sacn_source_update_levels_and_pap(), but also sets the force_sync flag on the packet. More...
int	sacn_source_process_manual (void)
	Trigger the transmission of sACN packets for all universes of sources that were created with manually_process_source set to true. More...
etcpal_error_t	sacn_source_reset_networking (const SacnNetintConfig *sys_netint_config)
	Resets the underlying network sockets for all universes of all sources. More...
etcpal_error_t	sacn_source_reset_networking_per_universe (const SacnNetintConfig *sys_netint_config, const SacnSourceUniverseNetintList *per_universe_netint_lists, size_t num_per_universe_netint_lists)
	Resets the underlying network sockets and determines network interfaces for each universe of each source. More...
size_t	sacn_source_get_network_interfaces (sacn_source_t handle, uint16_t universe, EtcPalMcastNetintId *netints, size_t netints_size)
	Obtain a list of a universe's network interfaces. More...

Detailed Description

The sACN Source API; see Using the sACN Source API.

Components that send sACN are referred to as sACN Sources. Use this API to act as an sACN Source.

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

Macro Definition Documentation

SACN_SOURCE_CONFIG_DEFAULT_INIT

#define SACN_SOURCE_CONFIG_DEFAULT_INIT

Value:

  {                                                                                 \
    kEtcPalNullUuid, NULL, SACN_SOURCE_INFINITE_UNIVERSES, false, kSacnIpV4AndIpV6, \
        SACN_SOURCE_KEEP_ALIVE_INTERVAL_DEFAULT                                     \
  }

A default-value initializer for an SacnSourceConfig struct.

SACN_SOURCE_INFINITE_UNIVERSES

#define SACN_SOURCE_INFINITE_UNIVERSES   0

Constant for "infinite" when sending sACN universes.

When using dynamic memory, this constant can be passed in when creating a source. It represents an infinite number of universes that can be sent to.

SACN_SOURCE_INVALID

#define SACN_SOURCE_INVALID   -1

An invalid sACN source handle value.

SACN_SOURCE_KEEP_ALIVE_INTERVAL_DEFAULT

#define SACN_SOURCE_KEEP_ALIVE_INTERVAL_DEFAULT   800

The default keep-alive interval for sources, in milliseconds.

SACN_SOURCE_UNIVERSE_CONFIG_DEFAULT_INIT

#define SACN_SOURCE_UNIVERSE_CONFIG_DEFAULT_INIT

Value:

  {                                              \
    0, 100, false, false, NULL, 0, 0             \
  }

A default-value initializer for an SacnSourceUniverseConfig struct.

Typedef Documentation

sacn_source_t

typedef int sacn_source_t

A handle to a sACN source.

SacnSourceConfig

typedef struct SacnSourceConfig SacnSourceConfig

A set of configuration information for a sACN source.

SacnSourceUniverseConfig

typedef struct SacnSourceUniverseConfig SacnSourceUniverseConfig

A set of configuration information for a sACN universe.

SacnSourceUniverseNetintList

typedef struct SacnSourceUniverseNetintList SacnSourceUniverseNetintList

A set of network interfaces for a particular universe.

Function Documentation

sacn_source_add_unicast_destination()

etcpal_error_t sacn_source_add_unicast_destination	(	sacn_source_t	handle,
		uint16_t	universe,
		const EtcPalIpAddr *	dest
	)

Add a unicast destination for a source's universe.

This will reset transmission suppression and include the new unicast destination in transmissions for the universe.

Parameters

[in]	handle	Handle to the source to change.
[in]	universe	Universe to change.
[in]	dest	The destination IP. May not be NULL.

Returns

kEtcPalErrOk: Address added successfully.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle does not correspond to a valid source or the universe is not on that source.

kEtcPalErrExists: The unicast destination was already added to this universe on this source.

kEtcPalErrNoMem: No room to allocate additional destination address.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_add_universe()

etcpal_error_t sacn_source_add_universe	(	sacn_source_t	handle,
		const SacnSourceUniverseConfig *	config,
		const SacnNetintConfig *	netint_config
	)

Add a universe to an sACN source.

Adds a universe to a source. After this call completes, the applicaton must call a variant of sacn_source_update_levels() to mark it ready for processing.

If the source is not marked as unicast_only, the source will add the universe to its sACN Universe Discovery packets once a variant of sacn_source_update_levels() is called.

Note that a universe is considered as successfully added if it is able to successfully use any of the network interfaces. This will only return kEtcPalErrNoNetints if none of the interfaces work.

Parameters

[in]	handle	Handle to the source to which to add a universe.
[in]	config	Configuration parameters for the universe to be added.
[in,out]	netint_config	Optional. If non-NULL, this is the list of interfaces the application wants to use, and the status codes are filled in. If NULL, all available interfaces are tried.

Returns

kEtcPalErrOk: Universe successfully added.

kEtcPalErrNoNetints: None of the network interfaces provided were usable by the library.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrExists: Universe given was already added to this source.

kEtcPalErrNotFound: Handle does not correspond to a valid source.

kEtcPalErrNoMem: No room to allocate additional universe.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_change_name()

etcpal_error_t sacn_source_change_name	(	sacn_source_t	handle,
		const char *	new_name
	)

Change the name of an sACN source.

The name is a UTF-8 string representing "a user-assigned name provided by the source of the packet for use in displaying the identity of a source to a user." If its length (including the null terminator) is longer than SACN_SOURCE_NAME_MAX_LEN, then kEtcPalErrInvalid will be returned.

This function will update the packet buffers of all this source's universes with the new name. For each universe that is transmitting NULL start code or PAP data, the logic that slows down packet transmission due to inactivity will be reset.

Parameters

[in]	handle	Handle to the source to change.
[in]	new_name	New name to use for this source.

Returns

kEtcPalErrOk: Name set successfully.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle does not correspond to a valid source.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_change_preview_flag()

etcpal_error_t sacn_source_change_preview_flag	(	sacn_source_t	handle,
		uint16_t	universe,
		bool	new_preview_flag
	)

Change the send_preview option on a universe of a sACN source.

Sets the state of a flag in the outgoing sACN packets that indicates that the data is (from E1.31) "intended for use in visualization or media server preview applications and shall not be used to generate live output."

This function will update the packet buffers with the new option. If this universe is transmitting NULL start code or PAP data, the logic that slows down packet transmission due to inactivity will be reset.

Parameters

[in]	handle	Handle to the source for which to set the Preview_Data option.
[in]	universe	The universe to change.
[in]	new_preview_flag	The new send_preview option.

Returns

kEtcPalErrOk: send_preview option set successfully.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle does not correspond to a valid source or the universe is not on that source.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_change_priority()

etcpal_error_t sacn_source_change_priority	(	sacn_source_t	handle,
		uint16_t	universe,
		uint8_t	new_priority
	)

Change the priority of a universe on a sACN source.

This function will update the packet buffers with the new priority. If this universe is transmitting NULL start code or PAP data, the logic that slows down packet transmission due to inactivity will be reset.

Parameters

[in]	handle	Handle to the source for which to set the priority.
[in]	universe	Universe to change.
[in]	new_priority	New priority of the data sent from this source. Valid range is 0 to 200, inclusive.

Returns

kEtcPalErrOk: Priority set successfully.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle does not correspond to a valid source or the universe is not on that source.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_change_synchronization_universe()

etcpal_error_t sacn_source_change_synchronization_universe	(	sacn_source_t	handle,
		uint16_t	universe,
		uint16_t	new_sync_universe
	)

Changes the synchronization universe for a universe of a sACN source.

This will change the synchronization universe used by a sACN universe on the source. If this value is 0, synchronization is turned off for that universe.

This function will update the packet buffers with the new sync universe. If this universe is transmitting NULL start code or PAP data, the logic that slows down packet transmission due to inactivity will be reset.

Todo:

At this time, synchronization is not supported by this library.

Parameters

[in]	handle	Handle to the source to change.
[in]	universe	The universe to change.
[in]	new_sync_universe	The new synchronization universe to set.

Returns

kEtcPalErrOk: sync_universe set successfully.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle does not correspond to a valid source or the universe is not on that source.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_config_init()

void sacn_source_config_init

(

SacnSourceConfig *

config

)

Initialize an sACN Source Config struct to default values.

Parameters

[out]

config

Config struct to initialize.

sacn_source_create()

etcpal_error_t sacn_source_create	(	const SacnSourceConfig *	config,
		sacn_source_t *	handle
	)

Create a new sACN source to send sACN data.

This creates the instance of the source and begins sending universe discovery packets for it (which will list no universes until start code data begins transmitting). No start code data is sent until sacn_source_add_universe() and a variant of sacn_source_update_levels() is called.

Parameters

[in]	config	Configuration parameters for the sACN source to be created. If any of these parameters are invalid, kEtcPalErrInvalid will be returned. This includes if the source name's length (including the null terminator) is beyond SACN_SOURCE_NAME_MAX_LEN.
[out]	handle	Filled in on success with a handle to the sACN source.

Returns

kEtcPalErrOk: Source successfully created.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNoMem: No room to allocate an additional source.

kEtcPalErrSys: An internal library or system call error occurred.

Other codes translated from system error codes are possible.

sacn_source_destroy()

void sacn_source_destroy

(

sacn_source_t

handle

)

Destroy an sACN source instance.

Stops sending all universes for this source. This removes the source and queues the sending of termination packets to all of the source's universes, which takes place either on the thread or on calls to sacn_source_process_manual(). The source will also stop transmitting sACN universe discovery packets.

Parameters

[in]

handle

Handle to the source to destroy. This handle will no longer be usable with the source API.

sacn_source_get_network_interfaces()

size_t sacn_source_get_network_interfaces	(	sacn_source_t	handle,
		uint16_t	universe,
		EtcPalMcastNetintId *	netints,
		size_t	netints_size
	)

Obtain a list of a universe's network interfaces.

Parameters

[in]	handle	Handle to the source that includes the universe.
[in]	universe	The universe for which to obtain the list of network interfaces.
[out]	netints	A pointer to an application-owned array where the network interface list will be written.
[in]	netints_size	The size of the provided netints array.

Returns

The total number of network interfaces for the universe. If this is greater than netints_size, then only netints_size entries were written to the netints array. If the source or universe were not found, 0 is returned.

sacn_source_get_unicast_destinations()

size_t sacn_source_get_unicast_destinations	(	sacn_source_t	handle,
		uint16_t	universe,
		EtcPalIpAddr *	destinations,
		size_t	destinations_size
	)

Obtain a list of a universe's unicast destinations.

Parameters

[in]	handle	Handle to the source of the universe in question.
[in]	universe	The universe for which to obtain the list of unicast destinations.
[out]	destinations	A pointer to an application-owned array where the unicast destination list will be written.
[in]	destinations_size	The size of the provided destinations array.

Returns

The total number of unicast destinations for the given universe. If this is greater than destinations_size, then only destinations_size addresses were written to the destinations array. If the source was not found, 0 is returned.

sacn_source_get_universes()

size_t sacn_source_get_universes	(	sacn_source_t	handle,
		uint16_t *	universes,
		size_t	universes_size
	)

Obtain a list of a source's universes.

Parameters

[in]	handle	Handle to the source for which to obtain the list of universes.
[out]	universes	A pointer to an application-owned array where the universe list will be written.
[in]	universes_size	The size of the provided universes array.

Returns

The total number of the source's universes. If this is greater than universes_size, then only universes_size universes were written to the universes array. If the source was not found, 0 is returned.

sacn_source_process_manual()

int sacn_source_process_manual

(

void

)

Trigger the transmission of sACN packets for all universes of sources that were created with manually_process_source set to true.

Note: Unless you created the source with manually_process_source set to true, similar functionality will be automatically called by an internal thread of the module. Otherwise, this must be called at the maximum rate at which the application will send sACN.

Sends the current data for universes which have been updated, and sends keep-alive data for universes which haven't been updated. Also destroys sources & universes that have been marked for termination after sending the required three terminated packets.

Returns

Current number of manual sources tracked by the library, including sources that have been destroyed but are still sending termination packets. This can be useful on shutdown to track when destroyed sources have finished sending the terminated packets and actually been destroyed.

sacn_source_remove_unicast_destination()

void sacn_source_remove_unicast_destination	(	sacn_source_t	handle,
		uint16_t	universe,
		const EtcPalIpAddr *	dest
	)

Remove a unicast destination on a source's universe.

This removes a unicast destination address and queues the sending of termination packets to the address, which takes place either on the thread or on calls to sacn_source_process_manual().

Parameters

[in]	handle	Handle to the source to change.
[in]	universe	Universe to change.
[in]	dest	The destination IP to remove. May not be NULL, and must match the address passed to sacn_source_add_unicast_destination().

sacn_source_remove_universe()

void sacn_source_remove_universe	(	sacn_source_t	handle,
		uint16_t	universe
	)

Remove a universe from a source.

This removes a universe and queues the sending of termination packets to the universe, which takes place either on the thread or on calls to sacn_source_process_manual().

The source will also stop including the universe in sACN universe discovery packets.

Parameters

[in]	handle	Handle to the source from which to remove the universe.
[in]	universe	Universe to remove. The source API functions will no longer recognize this universe for this source unless the universe is re-added to the source.

sacn_source_reset_networking()

etcpal_error_t sacn_source_reset_networking

(

const SacnNetintConfig *

sys_netint_config

)

Resets the underlying network sockets for all universes of all sources.

This is typically used when the application detects that the list of networking interfaces has changed. This changes the list of system interfaces the source API will be limited to (the list passed into sacn_init(), if any, is overridden for the source API, but not the other APIs). Then all universes of all sources will be configured to use all of those interfaces.

After this call completes successfully, all universes of all sources are considered to be updated and have new levels and priorities. It's as if every source just started sending levels on all their universes.

If this call fails, the caller must call sacn_source_destroy() on all sources, because the source API may be in an invalid state.

Note that the networking reset is considered successful if it is able to successfully use any of the network interfaces passed in. This will only return kEtcPalErrNoNetints if none of the interfaces work.

Parameters

[in,out]

sys_netint_config

Optional. If non-NULL, this is the list of system interfaces the source API will be limited to, and the status codes are filled in. If NULL, the source API is allowed to use all available system interfaces.

Returns

kEtcPalErrOk: Networking reset successfully.

kEtcPalErrNoNetints: None of the network interfaces provided were usable by the library.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_reset_networking_per_universe()

etcpal_error_t sacn_source_reset_networking_per_universe	(	const SacnNetintConfig *	sys_netint_config,
		const SacnSourceUniverseNetintList *	per_universe_netint_lists,
		size_t	num_per_universe_netint_lists
	)

Resets the underlying network sockets and determines network interfaces for each universe of each source.

This is typically used when the application detects that the list of networking interfaces has changed. This changes the list of system interfaces the source API will be limited to (the list passed into sacn_init(), if any, is overridden for the source API, but not the other APIs). Then the network interfaces are specified for each universe of each source.

After this call completes successfully, all universes of all sources are considered to be updated and have new levels and priorities. It's as if every source just started sending levels on all their universes.

If this call fails, the caller must call sacn_source_destroy() on all sources, because the source API may be in an invalid state.

Note that the networking reset is considered successful if it is able to successfully use any of the network interfaces passed in for each universe. This will only return kEtcPalErrNoNetints if none of the interfaces work for a universe.

Parameters

[in,out]	sys_netint_config	Optional. If non-NULL, this is the list of system interfaces the source API will be limited to, and the status codes are filled in. If NULL, the source API is allowed to use all available system interfaces.
[in,out]	per_universe_netint_lists	Lists of interfaces the application wants to use for each universe. Must not be NULL. Must include all universes of all sources, and nothing more. The status codes are filled in whenever SacnSourceUniverseNetintList::netints is non-NULL.
[in]	num_per_universe_netint_lists	The size of netint_lists. Must not be 0.

Returns

kEtcPalErrOk: Networking reset successfully.

kEtcPalErrNoNetints: None of the network interfaces provided for a universe were usable by the library.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_send_now()

etcpal_error_t sacn_source_send_now	(	sacn_source_t	handle,
		uint16_t	universe,
		uint8_t	start_code,
		const uint8_t *	buffer,
		size_t	buflen
	)

Immediately sends the provided sACN start code & data.

Immediately sends a sACN packet with the provided start code and data. This function is intended for sACN packets that have a startcode other than 0 or 0xdd, since those start codes are taken care of by either the thread or sacn_source_process_manual().

Parameters

[in]	handle	Handle to the source.
[in]	universe	Universe to send on.
[in]	start_code	The start code to send.
[in]	buffer	The buffer to send. Must not be NULL.
[in]	buflen	The size of buffer.

Returns

kEtcPalErrOk: Message successfully sent.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle does not correspond to a valid source, or the universe was not found on this source.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_send_synchronization()

etcpal_error_t sacn_source_send_synchronization	(	sacn_source_t	handle,
		uint16_t	sync_universe
	)

Indicate that a new synchronization packet should be sent on the given synchronization universe.

This will cause the source to transmit a synchronization packet on the given synchronization universe.

Todo:

At this time, synchronization is not supported by this library, so this function is not implemented.

Parameters

[in]	handle	Handle to the source.
[in]	sync_universe	The synchronization universe to send on.

Returns

kEtcPalErrOk: Message successfully sent.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle does not correspond to a valid source, or the universe was not found on this source.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_source_universe_config_init()

void sacn_source_universe_config_init

(

SacnSourceUniverseConfig *

config

)

Initialize an sACN Source Universe Config struct to default values.

Parameters

[out]

config

Config struct to initialize.

sacn_source_update_levels()

void sacn_source_update_levels	(	sacn_source_t	handle,
		uint16_t	universe,
		const uint8_t *	new_levels,
		size_t	new_levels_size
	)

Copies the universe's DMX levels into the packet to be sent on the next threaded or manual update.

This function will update the outgoing packet data, and reset the logic that slows down packet transmission due to inactivity.

When you don't have per-address priority changes to make, use this function. Otherwise, use sacn_source_update_levels_and_pap().

Parameters

[in]	handle	Handle to the source to update.
[in]	universe	Universe to update.
[in]	new_levels	A buffer of DMX levels to copy from. If this pointer is NULL, the source will terminate DMX transmission without removing the universe.
[in]	new_levels_size	Size of new_levels. This must be no larger than DMX_ADDRESS_COUNT.

sacn_source_update_levels_and_force_sync()

void sacn_source_update_levels_and_force_sync	(	sacn_source_t	handle,
		uint16_t	universe,
		const uint8_t *	new_levels,
		size_t	new_levels_size
	)

Like sacn_source_update_levels(), but also sets the force_sync flag on the packet.

This function will update the outgoing packet data to be sent on the next threaded or manual update, and will reset the logic that slows down packet transmission due to inactivity. Additionally, the packet to be sent will have its force_synchronization option flag set.

If no synchronization universe is configured, this function acts like a direct call to sacn_source_update_levels().

Todo:

At this time, synchronization is not supported by this library.

Parameters

[in]	handle	Handle to the source to update.
[in]	universe	Universe to update.
[in]	new_levels	A buffer of DMX levels to copy from. If this pointer is NULL, the source will terminate DMX transmission without removing the universe.
[in]	new_levels_size	Size of new_levels. This must be no larger than DMX_ADDRESS_COUNT.

sacn_source_update_levels_and_pap()

void sacn_source_update_levels_and_pap	(	sacn_source_t	handle,
		uint16_t	universe,
		const uint8_t *	new_levels,
		size_t	new_levels_size,
		const uint8_t *	new_priorities,
		size_t	new_priorities_size
	)

Copies the universe's DMX levels and per-address priorities into packets that are sent on the next threaded or manual update.

This function will update the outgoing packet data for both DMX and per-address priority data, and reset the logic that slows down packet transmission due to inactivity.

The application should adhere to the rules for per-address priority (PAP) specified in Per Address Priority. This API will adhere to the rules within the scope of the implementation. This includes handling transmission suppression and the order in which DMX and PAP packets are sent. This also includes automatically setting levels to 0, even if the application specified a different level, for each slot that the application assigns a PAP of 0 (by setting the PAP to 0 or reducing the PAP count).

Parameters

[in]	handle	Handle to the source to update.
[in]	universe	Universe to update.
[in]	new_levels	A buffer of DMX levels to copy from. If this pointer is NULL, the source will terminate DMX transmission without removing the universe.
[in]	new_levels_size	Size of new_levels. This must be no larger than DMX_ADDRESS_COUNT.
[in]	new_priorities	A buffer of per-address priorities to copy from. This will only be sent when DMX is also being sent. Setting this to NULL will stop the transmission of per-address priorities, in which case receivers will revert to the universe priority after PAP times out.
[in]	new_priorities_size	Size of new_priorities. This must be no larger than DMX_ADDRESS_COUNT.

sacn_source_update_levels_and_pap_and_force_sync()

void sacn_source_update_levels_and_pap_and_force_sync	(	sacn_source_t	handle,
		uint16_t	universe,
		const uint8_t *	new_levels,
		size_t	new_levels_size,
		const uint8_t *	new_priorities,
		size_t	new_priorities_size
	)

Like sacn_source_update_levels_and_pap(), but also sets the force_sync flag on the packet.

This function will update the outgoing packet data to be sent on the next threaded or manual update, and will reset the logic that slows down packet transmission due to inactivity. Additionally, both packets to be sent by this call will have their force_synchronization option flags set.

The application should adhere to the rules for per-address priority (PAP) specified in Per Address Priority. This API will adhere to the rules within the scope of the implementation. This includes handling transmission suppression and the order in which DMX and PAP packets are sent. This also includes automatically setting levels to 0, even if the application specified a different level, for each slot that the application assigns a PAP of 0 (by setting the PAP to 0 or reducing the PAP count).

If no synchronization universe is configured, this function acts like a direct call to sacn_source_update_levels_and_pap().

Todo:

At this time, synchronization is not supported by this library.

Parameters

[in]	handle	Handle to the source to update.
[in]	universe	Universe to update.
[in]	new_levels	A buffer of DMX levels to copy from. If this pointer is NULL, the source will terminate DMX transmission without removing the universe.
[in]	new_levels_size	Size of new_levels. This must be no larger than DMX_ADDRESS_COUNT.
[in]	new_priorities	A buffer of per-address priorities to copy from. This will only be sent when DMX is also being sent. Setting this to NULL will stop the transmission of per-address priorities, in which case receivers will revert to the universe priority after PAP times out.
[in]	new_priorities_size	Size of new_priorities. This must be no larger than DMX_ADDRESS_COUNT.