ApplyEffect implementation

doc/code/curves.md

@@ -18,6 +18,7 @@ Curves are an integral part of openage's event-based game simulation.
       1. [Queue](#queue)
       2. [Unordered Map](#unordered-map)
       3. [Array](#array)
+4. [Compression](#compression)
 
 
 ## Motivation
@@ -133,6 +134,9 @@ Modify operations insert values for a specific point in time.
 | `set_insert(t, value)`  | Insert a new keyframe value at time `t`                                           |
 | `set_last(t, value)`    | Insert a new keyframe value at time `t`; delete all keyframes after time `t`      |
 | `set_replace(t, value)` | Insert a new keyframe value at time `t`; remove all other keyframes with time `t` |
+| `compress(t)`           | Remove redundant keyframes at and after time `t`; see [Compression] for more info |
+
+[Compression]: #compression
 
 **Copy**
 
@@ -292,3 +296,28 @@ Modify operations insert values for a specific point in time.
 | Method           | Description                                                                                      |
 | ---------------- | ------------------------------------------------------------------------------------------------ |
 | `sync(Curve, t)` | Replace all keyframes from self after time `t` with keyframes from source `Curve` after time `t` |
+
+
+## Compression
+
+Curves support basic lossless compression by removing redundant keyframes from the curve.
+Keyframes are considered redundant if they do not change any interpolation results, i.e.
+the result of `get(t)` does not change.
+
+The most straight-forward way to use compression with primitive curves is the `compress(t)`
+method. `compress(t)` iterates over the curve and removes all redundant keyframes after
+or at time `t`. The runtime has linear complexity `O(n)` based on the number of elements
+in the keyframe container.
+
+Furthermore, primitive curves support incremental compression during insertion for the
+`set_insert(t, value)`  and `set_last(t, value)` methods via their `compress` argument.
+If compression is active, `(t, value)` is only inserted when it is not a redundant
+keyframe. `sync(Curve, t)` also supports compression with a flag `compress` passed as
+an argument.
+
+Compression may be used in cases where the size should be kept small, e.g. when the curve
+is tranferred via network or recorded in a replay file. Another application of compression
+is in the [renderer](/doc/code/renderer/README.md) for the discrete curves storing an object's
+animations. Since compression removes redundant animation entries, the renderer can determine
+when the current animation has started much easier as this is then returned by the keyframe
+time in `frame(t)`.

doc/code/game_simulation/activity.md

@@ -48,11 +48,12 @@ you can use available [BPMN tools](https://bpmn.io/) to draw activity node graph
 ## Node Types
 
 
-| Type             | Inputs | Outputs | Description               |
-| ---------------- | ------ | ------- | ------------------------- |
-| `START`          | 0      | 1       | Start of activity         |
-| `END`            | 1      | 0       | End of activity           |
-| `TASK_SYSTEM`    | 1      | 1       | Run built-in system       |
-| `TASK_CUSTOM`    | 1      | 1       | Run custom function       |
-| `XOR_EVENT_GATE` | 1      | 1+      | Wait for event and branch |
-| `XOR_GATE`       | 1      | 1+      | Branch on condition       |
+| Type              | Inputs | Outputs | Description               |
+| ----------------- | ------ | ------- | ------------------------- |
+| `START`           | 0      | 1       | Start of activity         |
+| `END`             | 1      | 0       | End of activity           |
+| `TASK_SYSTEM`     | 1      | 1       | Run built-in system       |
+| `TASK_CUSTOM`     | 1      | 1       | Run custom function       |
+| `XOR_EVENT_GATE`  | 1      | 1+      | Wait for event and branch |
+| `XOR_GATE`        | 1      | 1+      | Branch on condition       |
+| `XOR_SWITCH_GATE` | 1      | 1+      | Branch on value           |

libopenage/curve/CMakeLists.txt

@@ -1,5 +1,6 @@
 add_sources(libopenage
 	base_curve.cpp
+    concept.cpp
 	continuous.cpp
 	discrete.cpp
 	discrete_mod.cpp

libopenage/curve/base_curve.h

@@ -1,7 +1,8 @@
-// Copyright 2017-2025 the openage authors. See copying.md for legal info.
+// Copyright 2017-2024 the openage authors. See copying.md for legal info.
 
 #pragma once
 
+#include <concepts>
 #include <cstddef>
 #include <functional>
 #include <memory>
@@ -13,6 +14,7 @@
 #include "log/log.h"
 #include "log/message.h"
 
+#include "curve/concept.h"
 #include "curve/keyframe_container.h"
 #include "event/evententity.h"
 #include "time/time.h"
@@ -26,7 +28,7 @@ class EventLoop;
 
 namespace curve {
 
-template <typename T>
+template <KeyframeValueLike T>
 class BaseCurve : public event::EventEntity {
 public:
 	BaseCurve(const std::shared_ptr<event::EventLoop> &loop,
@@ -74,30 +76,62 @@ class BaseCurve : public event::EventEntity {
 	/**
 	 * Insert/overwrite given value at given time and erase all elements
 	 * that follow at a later time.
+	 *
 	 * If multiple elements exist at the given time,
 	 * overwrite the last one.
+	 *
+	 * @param at Time the keyframe is inserted at.
+	 * @param value Value of the keyframe.
+	 * @param compress If true, only insert the keyframe if the value at time \p at
+	 *                 is different from the given value.
 	 */
-	virtual void set_last(const time::time_t &at, const T &value);
+	virtual void set_last(const time::time_t &at,
+	                      const T &value,
+	                      bool compress = false);
 
 	/**
 	 * Insert a value at the given time.
+	 *
 	 * If there already is a value at this time,
 	 * the value is inserted directly after the existing one.
+	 *
+	 * @param at Time the keyframe is inserted at.
+	 * @param value Value of the keyframe.
+	 * @param compress If true, only insert the keyframe if the value at time \p at
+	 *                 is different from the given value.
 	 */
-	virtual void set_insert(const time::time_t &at, const T &value);
+	virtual void set_insert(const time::time_t &at,
+	                        const T &value,
+	                        bool compress = false);
 
 	/**
 	 * Insert a value at the given time.
+	 *
 	 * If there already is a value at this time,
 	 * the given value will replace the first value with the same time.
+	 *
+	 * @param at Time the keyframe is inserted at.
+	 * @param value Value of the keyframe.
 	 */
-	virtual void set_replace(const time::time_t &at, const T &value);
+	virtual void set_replace(const time::time_t &at,
+	                         const T &value);
 
 	/**
 	 * Remove all values that have the given time.
 	 */
 	virtual void erase(const time::time_t &at);
 
+	/**
+	 * Compress the curve by removing redundant keyframes.
+	 *
+	 * A keyframe is redundant if it doesn't change the value calculation of the curve
+	 * at any given time, e.g. duplicate keyframes.
+	 *
+	 * @param start Start time at which keyframes are compressed (default = -INF).
+	 *              Using the default value compresses ALL keyframes of the curve.
+	 */
+	virtual void compress(const time::time_t &start = time::TIME_MIN) = 0;
+
 	/**
 	 * Integrity check, for debugging/testing reasons only.
 	 */
@@ -113,9 +147,13 @@ class BaseCurve : public event::EventEntity {
 	 * @param start Start time at which keyframes are replaced (default = -INF).
 	 *              Using the default value replaces ALL keyframes of \p this with
 	 *              the keyframes of \p other.
+	 * @param compress If true, redundant keyframes are not copied during the sync.
+	 *                 Redundant keyframes are keyframes that don't change the value
+	 *                 calculaton of the curve at any given time, e.g. duplicate keyframes.
 	 */
 	void sync(const BaseCurve<T> &other,
-	          const time::time_t &start = time::TIME_MIN);
+	          const time::time_t &start = time::TIME_MIN,
+	          bool compress = false);
 
 	/**
 	 * Copy keyframes from another curve (with a different element type) to this curve.
@@ -130,11 +168,15 @@ class BaseCurve : public event::EventEntity {
 	 * @param start Start time at which keyframes are replaced (default = -INF).
 	 *              Using the default value replaces ALL keyframes of \p this with
 	 *              the keyframes of \p other.
+	 * @param compress If true, redundant keyframes are not copied during the sync.
+	 *                 Redundant keyframes are keyframes that don't change the value
+	 *                 calculaton of the curve at any given time, e.g. duplicate keyframes.
 	 */
-	template <typename O>
+	template <KeyframeValueLike O>
 	void sync(const BaseCurve<O> &other,
 	          const std::function<T(const O &)> &converter,
-	          const time::time_t &start = time::TIME_MIN);
+	          const time::time_t &start = time::TIME_MIN,
+	          bool compress = false);
 
 	/**
 	 * Get the identifier of this curve.
@@ -199,8 +241,10 @@ class BaseCurve : public event::EventEntity {
 };
 
 
-template <typename T>
-void BaseCurve<T>::set_last(const time::time_t &at, const T &value) {
+template <KeyframeValueLike T>
+void BaseCurve<T>::set_last(const time::time_t &at,
+                            const T &value,
+                            bool compress) {
 	auto hint = this->container.last(at, this->last_element);
 
 	// erase max one same-time value
@@ -210,55 +254,72 @@ void BaseCurve<T>::set_last(const time::time_t &at, const T &value) {
 
 	hint = this->container.erase_after(hint);
 
+	if (compress and this->get(at) == value) {
+		// skip insertion if the value is the same as the last one
+		// erasure still happened, so we need to notify about the change
+		this->changes(at);
+		return;
+	}
+
 	this->container.insert_before(at, value, hint);
 	this->last_element = hint;
 
 	this->changes(at);
 }
 
 
-template <typename T>
-void BaseCurve<T>::set_insert(const time::time_t &at, const T &value) {
+template <KeyframeValueLike T>
+void BaseCurve<T>::set_insert(const time::time_t &at,
+                              const T &value,
+                              bool compress) {
+	if (compress and this->get(at) == value) {
+		// skip insertion if the value is the same as the last one
+		return;
+	}
+
 	auto hint = this->container.insert_after(at, value, this->last_element);
+
 	// check if this is now the final keyframe
 	if (this->container.get(hint).time() > this->container.get(this->last_element).time()) {
 		this->last_element = hint;
 	}
+
 	this->changes(at);
 }
 
 
-template <typename T>
-void BaseCurve<T>::set_replace(const time::time_t &at, const T &value) {
+template <KeyframeValueLike T>
+void BaseCurve<T>::set_replace(const time::time_t &at,
+                               const T &value) {
 	this->container.insert_overwrite(at, value, this->last_element);
 	this->changes(at);
 }
 
 
-template <typename T>
+template <KeyframeValueLike T>
 void BaseCurve<T>::erase(const time::time_t &at) {
 	this->last_element = this->container.erase(at, this->last_element);
 	this->changes(at);
 }
 
 
-template <typename T>
+template <KeyframeValueLike T>
 std::pair<time::time_t, const T> BaseCurve<T>::frame(const time::time_t &time) const {
 	auto e = this->container.last(time, this->container.size());
 	auto elem = this->container.get(e);
 	return elem.as_pair();
 }
 
 
-template <typename T>
+template <KeyframeValueLike T>
 std::pair<time::time_t, const T> BaseCurve<T>::next_frame(const time::time_t &time) const {
 	auto e = this->container.last(time, this->container.size());
 	e++;
 	auto elem = this->container.get(e);
 	return elem.as_pair();
 }
 
-template <typename T>
+template <KeyframeValueLike T>
 std::string BaseCurve<T>::str() const {
 	std::stringstream ss;
 	ss << "Curve[" << this->idstr() << "]{" << std::endl;
@@ -270,7 +331,7 @@ std::string BaseCurve<T>::str() const {
 	return ss.str();
 }
 
-template <typename T>
+template <KeyframeValueLike T>
 void BaseCurve<T>::check_integrity() const {
 	time::time_t last_time = time::TIME_MIN;
 	for (const auto &keyframe : this->container) {
@@ -281,9 +342,10 @@ void BaseCurve<T>::check_integrity() const {
 	}
 }
 
-template <typename T>
+template <KeyframeValueLike T>
 void BaseCurve<T>::sync(const BaseCurve<T> &other,
-                        const time::time_t &start) {
+                        const time::time_t &start,
+                        bool compress) {
 	// Copy keyframes between containers for t >= start
 	this->last_element = this->container.sync(other.container, start);
 
@@ -294,15 +356,20 @@ void BaseCurve<T>::sync(const BaseCurve<T> &other,
 		this->set_insert(start, get_other);
 	}
 
+	if (compress) {
+		this->compress(start);
+	}
+
 	this->changes(start);
 }
 
 
-template <typename T>
-template <typename O>
+template <KeyframeValueLike T>
+template <KeyframeValueLike O>
 void BaseCurve<T>::sync(const BaseCurve<O> &other,
                         const std::function<T(const O &)> &converter,
-                        const time::time_t &start) {
+                        const time::time_t &start,
+                        bool compress) {
 	// Copy keyframes between containers for t >= start
 	this->last_element = this->container.sync(other.get_container(), converter, start);
 
@@ -313,6 +380,10 @@ void BaseCurve<T>::sync(const BaseCurve<O> &other,
 		this->set_insert(start, get_other);
 	}
 
+	if (compress) {
+		this->compress(start);
+	}
+
 	this->changes(start);
 }
 

libopenage/curve/concept.cpp

@@ -0,0 +1,9 @@
+// Copyright 2024-2024 the openage authors. See copying.md for legal info.
+
+#include "concept.h"
+
+
+namespace openage::curve {
+
+
+} // namespace openage::curve

libopenage/curve/concept.h

@@ -0,0 +1,15 @@
+// Copyright 2024-2024 the openage authors. See copying.md for legal info.
+
+#pragma once
+
+#include <concepts>
+
+namespace openage::curve {
+
+/**
+ * Concept for keyframe values.
+ */
+template <typename T>
+concept KeyframeValueLike = std::copyable<T> && std::equality_comparable<T>;
+
+} // namespace openage::curve

libopenage/curve/container/iterator.h

@@ -1,7 +1,8 @@
-// Copyright 2017-2025 the openage authors. See copying.md for legal info.
+// Copyright 2017-2024 the openage authors. See copying.md for legal info.
 
 #pragma once
 
+#include "curve/concept.h"
 #include "time/time.h"
 #include "util/fixed_point.h"
 
@@ -11,7 +12,7 @@ namespace openage::curve {
 /**
  * Default interface for curve containers
  */
-template <typename val_t,
+template <KeyframeValueLike val_t,
           typename container_t,
           typename iterator_t = typename container_t::const_iterator>
 class CurveIterator {