sACN
2.0.2
Implementation of ANSI E1.31 (Streaming ACN)
|
View other versions:
|
An instance of sACN Source functionality; see Using the sACN Source API. More...
#include <source.h>
Data Structures | |
struct | Settings |
A set of configuration settings that a source needs to initialize. More... | |
struct | UniverseNetintList |
A set of network interfaces for a particular universe. More... | |
struct | UniverseSettings |
A set of configuration settings for a new universe on a source. More... | |
Public Types | |
using | Handle = etcpal::OpaqueId<detail::SourceHandleType, sacn_source_t, SACN_SOURCE_INVALID> |
Public Member Functions | |
Source (const Source &other)=delete | |
Source & | operator= (const Source &other)=delete |
Source (Source &&other)=default | |
Source & | operator= (Source &&other)=default |
etcpal::Error | Startup (const Settings &settings) |
Create a new sACN source to send sACN data. | |
void | Shutdown () |
Destroy an sACN source instance. | |
etcpal::Error | ChangeName (const std::string &new_name) |
Change the name of an sACN source. | |
etcpal::Error | AddUniverse (const UniverseSettings &settings) |
Add a universe to an sACN source, which will use all network interfaces. | |
etcpal::Error | AddUniverse (const UniverseSettings &settings, std::vector< SacnMcastInterface > &netints) |
Add a universe to an sACN source, which will use the network interfaces passed in. | |
void | RemoveUniverse (uint16_t universe) |
Remove a universe from a source. | |
std::vector< uint16_t > | GetUniverses () |
Obtain a vector of this source's universes. | |
etcpal::Error | AddUnicastDestination (uint16_t universe, const etcpal::IpAddr &dest) |
Add a unicast destination for a universe. | |
void | RemoveUnicastDestination (uint16_t universe, const etcpal::IpAddr &dest) |
Remove a unicast destination on a universe. | |
std::vector< etcpal::IpAddr > | GetUnicastDestinations (uint16_t universe) |
Obtain a vector of a universe's unicast destinations. | |
etcpal::Error | ChangePriority (uint16_t universe, uint8_t new_priority) |
Change the priority of a universe. | |
etcpal::Error | ChangePreviewFlag (uint16_t universe, bool new_preview_flag) |
Change the send_preview option on a universe. | |
etcpal::Error | ChangeSynchronizationUniverse (uint16_t universe, uint16_t new_sync_universe) |
Changes the synchronization universe for a universe. | |
etcpal::Error | SendNow (uint16_t universe, uint8_t start_code, const uint8_t *buffer, size_t buflen) |
Immediately sends the provided sACN start code & data. | |
etcpal::Error | SendSynchronization (uint16_t universe) |
Indicate that a new synchronization packet should be sent on the given synchronization universe. | |
void | UpdateLevels (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. | |
void | UpdateLevelsAndPap (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. | |
void | UpdateLevelsAndForceSync (uint16_t universe, const uint8_t *new_levels, size_t new_levels_size) |
Like UpdateLevels(), but also sets the force_sync flag on the packet. | |
void | UpdateLevelsAndPapAndForceSync (uint16_t universe, const uint8_t *new_levels, size_t new_levels_size, const uint8_t *new_priorities, size_t new_priorities_size) |
Like UpdateLevelsAndPap(), but also sets the force_sync flag on the packet. | |
std::vector< EtcPalMcastNetintId > | GetNetworkInterfaces (uint16_t universe) |
Obtain a vector of a universe's network interfaces. | |
constexpr Handle | handle () const |
Get the current handle to the underlying C source. | |
Static Public Member Functions | |
static int | ProcessManual () |
Trigger the transmission of sACN packets for all universes of sources that were created with manually_process_source set to true. | |
static etcpal::Error | ResetNetworking () |
Resets the underlying network sockets for all universes of all sources. | |
static etcpal::Error | ResetNetworking (std::vector< SacnMcastInterface > &netints) |
Resets the underlying network sockets for all universes of all sources. | |
static etcpal::Error | ResetNetworking (std::vector< SacnMcastInterface > &sys_netints, std::vector< UniverseNetintList > &netint_lists) |
Resets the underlying network sockets and determines network interfaces for each universe of each source. | |
An instance of sACN Source functionality; 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.
A handle type used by the sACN library to identify source instances.
|
inline |
Add a unicast destination for a universe.
This will reset transmission suppression and include the new unicast destination in transmissions for the universe.
[in] | universe | Universe to change. |
[in] | dest | The destination IP. |
|
inline |
Add a universe to an sACN source, which will use all network interfaces.
Adds a universe to a source. All network interfaces will be used. After this call completes, the applicaton must call one of the Update functions 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 one of the Update functions are 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.
[in] | settings | Configuration parameters for the universe to be added. |
|
inline |
Add a universe to an sACN source, which will use the network interfaces passed in.
Adds a universe to a source. Only the network interfaces passed in will be used. After this call completes, the applicaton must call one of the Update functions 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 one of the Update functions are called.
Note that a universe is considered as successfully added 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.
[in] | settings | Configuration parameters for the universe to be added. |
[in,out] | netints | Optional. If !empty, this is the list of interfaces the application wants to use, and the status codes are filled in. If empty, all available interfaces are tried and this vector isn't modified. |
|
inline |
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.
[in] | new_name | New name to use for this source. |
|
inline |
Change the send_preview option on a universe.
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.
[in] | universe | The universe to change. |
[in] | new_preview_flag | The new send_preview option. |
|
inline |
Change the priority of a universe.
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.
[in] | universe | Universe to change. |
[in] | new_priority | New priority of the data sent from this source. Valid range is 0 to 200, inclusive. |
|
inline |
Changes the synchronization universe for a universe.
This will change the synchronization universe used by a sACN universe on this 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.
[in] | universe | The universe to change. |
[in] | new_sync_universe | The new synchronization universe to set. |
|
inline |
Obtain a vector of a universe's network interfaces.
[in] | universe | The universe for which to obtain the vector of network interfaces. |
|
inline |
Obtain a vector of a universe's unicast destinations.
[in] | universe | The universe for which to obtain the list of unicast destinations. |
|
inline |
Obtain a vector of this source's universes.
|
inlineconstexpr |
Get the current handle to the underlying C source.
|
inlinestatic |
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.
|
inline |
Remove a unicast destination on a 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 ProcessManual().
[in] | universe | Universe to change. |
[in] | dest | The destination IP to remove. Must match the address passed to AddUnicastDestination(). |
|
inline |
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 ProcessManual().
The source will also stop including the universe in sACN universe discovery packets.
[in] | universe | Universe to remove. This source's functions will no longer recognize this universe unless the universe is re-added. |
|
inlinestatic |
Resets the underlying network sockets for all universes of all sources.
This is the overload of ResetNetworking that uses all network interfaces.
This is typically used when the application detects that the list of networking interfaces has changed. The source API will no longer be limited to specific interfaces (the list passed into sacn::Init(), if any, is overridden for the source API, but not the other APIs). Every universe of every source is set to all system 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 Shutdown() 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. This will only return kEtcPalErrNoNetints if none of the interfaces work.
|
inlinestatic |
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 Shutdown() 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.
sys_netints | If !empty, this is the list of system interfaces the source API will be limited to, and the status codes are filled in. If empty, the source API is allowed to use all available system interfaces. |
|
inlinestatic |
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 Shutdown() 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.
sys_netints | If !empty, this is the list of system interfaces the source API will be limited to, and the status codes are filled in. If empty, the source API is allowed to use all available system interfaces. | |
[in,out] | per_universe_netint_lists | Vector of lists of interfaces the application wants to use for each universe. Must not be empty. Must include all universes of all sources, and nothing more. The status codes are filled in whenever UniverseNetintList::netints is !empty. |
|
inline |
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 ProcessManual().
[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. |
|
inline |
Indicate that a new synchronization packet should be sent on the given synchronization universe.
This will cause this 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.
[in] | sync_universe | The synchronization universe to send on. |
|
inline |
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 ProcessManual(). The source will also stop transmitting sACN universe discovery packets.
|
inline |
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 AddUniverse() and one of the Update functions are called.
[in] | settings | 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. |
|
inline |
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 UpdateLevelsAndPap().
[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. |
|
inline |
Like UpdateLevels(), 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 UpdateLevels().
TODO: At this time, synchronization is not supported by this library.
[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. |
|
inline |
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).
[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. This may be NULL if you are not using per-address priorities or want to stop using per-address priorities. |
[in] | new_priorities_size | Size of new_priorities. This must be no larger than DMX_ADDRESS_COUNT. |
|
inline |
Like UpdateLevelsAndPap(), 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 UpdateLevelsAndPap().
TODO: At this time, synchronization is not supported by this library.
[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. This may be NULL if you are not using per-address priorities or want to stop using per-address priorities. |
[in] | new_priorities_size | Size of new_priorities. This must be no larger than DMX_ADDRESS_COUNT. |