/usr/include/ableton/Link.hpp is in ableton-link-dev 1.0.0+dfsg-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 | /*! @file Link.hpp
* @copyright 2016, Ableton AG, Berlin. All rights reserved.
* @brief Library for cross-device shared tempo and quantized beat grid
*
* @license:
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* If you would like to incorporate Link into a proprietary software application,
* please contact <link-devs@ableton.com>.
*/
#pragma once
#include <ableton/platforms/Config.hpp>
#include <chrono>
#include <mutex>
namespace ableton
{
/*! @class Link
* @brief Class that represents a participant in a Link session.
*
* @discussion Each Link instance has its own beat timeline that
* starts running from beat 0 at the initial tempo when
* constructed. A Link instance is initially disabled after
* construction, which means that it will not communicate on the
* network. Once enabled, a Link instance initiates network
* communication in an effort to discover other peers. When peers are
* discovered, they immediately become part of a shared Link session.
*
* Each method of the Link type documents its thread-safety and
* realtime-safety properties. When a method is marked thread-safe,
* it means it is safe to call from multiple threads
* concurrently. When a method is marked realtime-safe, it means that
* it does not block and is appropriate for use in the thread that
* performs audio IO.
*
* Link provides one Timeline capture/commit method pair for use in the
* audio thread and one for all other application contexts. In
* general, modifying the Link timeline should be done in the audio
* thread for the most accurate timing results. The ability to modify
* the Link timeline from application threads should only be used in
* cases where an application's audio thread is not actively running
* or if it doesn't generate audio at all. Modifying the Link
* timeline from both the audio thread and an application thread
* concurrently is not advised and will potentially lead to
* unexpected behavior.
*/
class Link
{
public:
using Clock = link::platform::Clock;
class Timeline;
/*! @brief Construct with an initial tempo. */
Link(double bpm);
/*! @brief Link instances cannot be copied or moved */
Link(const Link&) = delete;
Link& operator=(const Link&) = delete;
Link(Link&&) = delete;
Link& operator=(Link&&) = delete;
/*! @brief Is Link currently enabled?
* Thread-safe: yes
* Realtime-safe: yes
*/
bool isEnabled() const;
/*! @brief Enable/disable Link.
* Thread-safe: yes
* Realtime-safe: no
*/
void enable(bool bEnable);
/*! @brief How many peers are currently connected in a Link session?
* Thread-safe: yes
* Realtime-safe: yes
*/
std::size_t numPeers() const;
/*! @brief Register a callback to be notified when the number of
* peers in the Link session changes.
* Thread-safe: yes
* Realtime-safe: no
*
* @discussion The callback is invoked on a Link-managed thread.
*
* @param callback The callback signature is:
* void (std::size_t numPeers)
*/
template <typename Callback>
void setNumPeersCallback(Callback callback);
/*! @brief Register a callback to be notified when the session
* tempo changes.
* Thread-safe: yes
* Realtime-safe: no
*
* @discussion The callback is invoked on a Link-managed thread.
*
* @param callback The callback signature is: void (double bpm)
*/
template <typename Callback>
void setTempoCallback(Callback callback);
/*! @brief The clock used by Link.
* Thread-safe: yes
* Realtime-safe: yes
*
* @discussion The Clock type is a platform-dependent
* representation of the system clock. It exposes a ticks() method
* that returns the current ticks of the system clock as well as
* micros(), which is a normalized representation of the current system
* time in std::chrono::microseconds. It also provides conversion
* functions ticksToMicros() and microsToTicks() to faciliate
* converting between these units.
*/
Clock clock() const;
/*! @brief Capture the current Link timeline from the audio thread.
* Thread-safe: no
* Realtime-safe: yes
*
* @discussion This method should ONLY be called in the audio thread
* and must not be accessed from any other threads. The returned
* Timeline stores a snapshot of the current Link state, so it
* should be captured and used in a local scope. Storing the
* Timeline for later use in a different context is not advised
* because it will provide an outdated view on the Link state.
*/
Timeline captureAudioTimeline() const;
/*! @brief Commit the given timeline to the Link session from the
* audio thread.
* Thread-safe: no
* Realtime-safe: yes
*
* @discussion This method should ONLY be called in the audio
* thread. The given timeline will replace the current Link
* timeline. Modifications to the session based on the new timeline
* will be communicated to other peers in the session.
*/
void commitAudioTimeline(Timeline timeline);
/*! @brief Capture the current Link timeline from an application
* thread.
* Thread-safe: yes
* Realtime-safe: no
*
* @discussion Provides a mechanism for capturing the Link timeline
* from an application thread (other than the audio thread). The
* returned Timeline stores a snapshot of the current Link state,
* so it should be captured and used in a local scope. Storing the
* Timeline for later use in a different context is not advised
* because it will provide an outdated view on the Link state.
*/
Timeline captureAppTimeline() const;
/*! @brief Commit the given timeline to the Link session from an
* application thread.
* Thread-safe: yes
* Realtime-safe: no
*
* @discussion The given timeline will replace the current Link
* timeline. Modifications to the session based on the new timeline
* will be communicated to other peers in the session.
*/
void commitAppTimeline(Timeline timeline);
/*! @class Timeline
* @brief Representation of a mapping between time and beats for
* varying quanta.
*
* @discussion A Timeline object is intended for use in a local
* scope within a single thread - none of its methods are
* thread-safe. All of its methods are non-blocking, so it is safe
* to use from a realtime thread.
*/
class Timeline
{
public:
Timeline(const link::Timeline timeline, const bool bRespectQuantum);
/*! @brief: The tempo of the timeline, in bpm */
double tempo() const;
/*! @brief: Set the timeline tempo to the given bpm value, taking
* effect at the given time.
*/
void setTempo(double bpm, std::chrono::microseconds atTime);
/*! @brief: Get the beat value corresponding to the given time
* for the given quantum.
*
* @discussion: The magnitude of the resulting beat value is
* unique to this Link instance, but its phase with respect to
* the provided quantum is shared among all session
* peers. For non-negative beat values, the following
* property holds: fmod(beatAtTime(t, q), q) == phaseAtTime(t, q)
*/
double beatAtTime(std::chrono::microseconds time, double quantum) const;
/*! @brief: Get the session phase at the given time for the given
* quantum.
*
* @discussion: The result is in the interval [0, quantum). The
* result is equivalent to fmod(beatAtTime(t, q), q) for
* non-negative beat values. This method is convenient if the
* client is only interested in the phase and not the beat
* magnitude. Also, unlike fmod, it handles negative beat values
* correctly.
*/
double phaseAtTime(std::chrono::microseconds time, double quantum) const;
/*! @brief: Get the time at which the given beat occurs for the
* given quantum.
*
* @discussion: The inverse of beatAtTime, assuming a constant
* tempo. beatAtTime(timeAtBeat(b, q), q) === b.
*/
std::chrono::microseconds timeAtBeat(double beat, double quantum) const;
/*! @brief: Attempt to map the given beat to the given time in the
* context of the given quantum.
*
* @discussion: This method behaves differently depending on the
* state of the session. If no other peers are connected,
* then this instance is in a session by itself and is free to
* re-map the beat/time relationship whenever it pleases. In this
* case, beatAtTime(time, quantum) == beat after this method has
* been called.
*
* If there are other peers in the session, this instance
* should not abruptly re-map the beat/time relationship in the
* session because that would lead to beat discontinuities among
* the other peers. In this case, the given beat will be mapped
* to the next time value greater than the given time with the
* same phase as the given beat.
*
* This method is specifically designed to enable the concept of
* "quantized launch" in client applications. If there are no other
* peers in the session, then an event (such as starting
* transport) happens immediately when it is requested. If there
* are other peers, however, we wait until the next time at which
* the session phase matches the phase of the event, thereby
* executing the event in-phase with the other peers in the
* session. The client only needs to invoke this method to
* achieve this behavior and should not need to explicitly check
* the number of peers.
*/
void requestBeatAtTime(double beat, std::chrono::microseconds time, double quantum);
/*! @brief: Rudely re-map the beat/time relationship for all peers
* in a session.
*
* @discussion: DANGER: This method should only be needed in
* certain special circumstances. Most applications should not
* use it. It is very similar to requestBeatAtTime except that it
* does not fall back to the quantizing behavior when it is in a
* session with other peers. Calling this method will
* unconditionally map the given beat to the given time and
* broadcast the result to the session. This is very anti-social
* behavior and should be avoided.
*
* One of the few legitimate uses of this method is to
* synchronize a Link session with an external clock source. By
* periodically forcing the beat/time mapping according to an
* external clock source, a peer can effectively bridge that
* clock into a Link session. Much care must be taken at the
* application layer when implementing such a feature so that
* users do not accidentally disrupt Link sessions that they may
* join.
*/
void forceBeatAtTime(double beat, std::chrono::microseconds time, double quantum);
private:
friend Link;
link::Timeline mOriginalTimeline;
bool mbRespectQuantum;
link::Timeline mTimeline;
};
private:
std::mutex mCallbackMutex;
link::PeerCountCallback mPeerCountCallback;
link::TempoCallback mTempoCallback;
Clock mClock;
link::platform::Controller mController;
};
} // ableton
#include <ableton/Link.ipp>
|