File: Option.h

package info (click to toggle)
freespace2 24.2.0%2Brepack-1
  • links: PTS, VCS
  • area: non-free
  • in suites: forky, sid
  • size: 43,716 kB
  • sloc: cpp: 595,001; ansic: 21,741; python: 1,174; sh: 457; makefile: 248; xml: 181
file content (587 lines) | stat: -rw-r--r-- 17,679 bytes parent folder | download
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
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
#pragma once

#include "globalincs/flagset.h"
#include "globalincs/pstypes.h"
#include "libs/jansson.h"
#include "options/OptionsManager.h"
#include "localization/localize.h"

#include <functional>
#include <utility>
#include <mpark/variant.hpp>
#include <tl/optional.hpp>

namespace options {

enum class OptionType { Range, Selection };

enum class ExpertLevel { Beginner, Advanced, Expert };

enum class PresetKind { Basic, Low, Medium, High, Ultra };

// clang-format off
FLAG_LIST(OptionFlags) {
	/**
	 * @brief Force the option menu to display this as a multi value selection.
	 *
	 * This can be useful if an option typically has multiple values but it is also possible for
	 * this option to have exactly two values which may cause the option menu to display it as a
	 * boolean option even though the option is not designed for that.
	 */
	ForceMultiValueSelection = 0,
	/**
	 * @brief Whether or not the option is built-in to FSO's retail Options UI
	 *
	 * This can be useful if an option should be ignored in cases like the SCP Options UI where
	 * it's only appropriate to display options that are not otherwise accessible to retail players.
	 */
	RetailBuiltinOption = 1,
	/**
	 * @brief Forces the range type slider to use an integer instead of a float
	 *
	 * This can be useful if an option cannot accept float values.
	 */
	RangeTypeInteger = 2,

	NUM_VALUES
};
// clang-format on

struct ValueDescription {
	const SCP_string display;
	const SCP_string serialized;

	ValueDescription(SCP_string _display, SCP_string _serialized);
};

class OptionBase {
	template <typename T>
	friend class OptionBuilder;

  protected:
	OptionsManager* _parent   = nullptr;
	ExpertLevel _expert_level = ExpertLevel::Expert;

	SCP_string _config_key;

	std::pair<const char*, int> _category = {"Other", 1829};

	SCP_string _title;
	SCP_string _description;

	int _importance = 0;

	float _min = 0;
	float _max = 1;

	bool _is_once = false;

	SCP_unordered_map<PresetKind, SCP_string> _preset_values;

	flagset<OptionFlags> _flags;

	tl::optional<std::unique_ptr<json_t>> getConfigValue() const;

	OptionBase(SCP_string config_key, SCP_string title, SCP_string description);

  public:
	virtual ~OptionBase() = 0;

	ExpertLevel getExpertLevel() const;
	void setExpertLevel(ExpertLevel expert_level);

	const SCP_string getCategory() const;
	void setCategory(const std::pair<const char*, int>& category);

	int getImportance() const;
	void setImportance(int importance);

	std::pair<float, float> getRangeValues() const;
	void setRangeValues(float min, float max);

	const flagset<OptionFlags>& getFlags() const;
	void setFlags(const flagset<OptionFlags>& flags);

	bool getIsOnce() const;
	void setIsOnce(bool is_once);

	const SCP_string& getConfigKey() const;
	const SCP_string& getTitle() const;
	const SCP_string& getDescription() const;

	void setPreset(PresetKind preset, const SCP_string& value);

	bool persistChanges() const;

	virtual bool valueChanged(const json_t* val) const = 0;

	virtual ValueDescription getCurrentValueDescription() const = 0;

	virtual void setValueDescription(const ValueDescription& desc) const = 0;

	virtual OptionType getType() const = 0;

	virtual SCP_vector<ValueDescription> getValidValues() const = 0;

	virtual ValueDescription getValueFromRange(float interpolant) const = 0;

	virtual float getInterpolantFromValue(const ValueDescription& val) const = 0;

	virtual void loadInitial() const = 0;

	friend bool operator<(const OptionBase& lhs, const OptionBase& rhs);
	friend bool operator>(const OptionBase& lhs, const OptionBase& rhs);
	friend bool operator<=(const OptionBase& lhs, const OptionBase& rhs);
	friend bool operator>=(const OptionBase& lhs, const OptionBase& rhs);
};

template <typename T>
using ValueEnumerator = std::function<SCP_vector<T>()>;
template <typename T>
using ValueDeserializer = std::function<T(const json_t*)>;
template <typename T>
using ValueSerializer = std::function<json_t*(const T&)>;
template <typename T>
using ValueDisplay = std::function<SCP_string(const T&)>;
template <typename T>
using DefaultValueFunctor = std::function<T()>;
template <typename T>
using ValueChangeListener = std::function<bool(const T&, bool initial)>;
template <typename T>
using ValueInterpolator = std::function<T(float)>;
template <typename T>
using ValueDeinterpolator = std::function<float(const T&)>;

template <typename T>
class ValueFunctor {
	T _value;

  public:
	ValueFunctor() = default;
	explicit ValueFunctor(T value) : _value(value) {}

	T operator()() { return _value; }
};

template <typename T>
class Option : public OptionBase {
  protected:
	ValueEnumerator<T> _valueEnumerator;
	ValueDeserializer<T> _deserializer;
	ValueSerializer<T> _serializer;
	ValueDisplay<T> _displayFunc;
	DefaultValueFunctor<T> _defaultValueFunc = ValueFunctor<T>();
	ValueChangeListener<T> _changeListener;
	ValueInterpolator<T> _interpolator;
	ValueDeinterpolator<T> _deinterpolator;

	OptionType _type = OptionType::Selection; // By default the generic type is always a selection

	ValueDescription toDescription(const T& val) const
	{
		auto json     = _serializer(val);
		auto json_str = json_dump_string_new(json, JSON_COMPACT | JSON_ENSURE_ASCII | JSON_ENCODE_ANY);
		if (_displayFunc) {
			return ValueDescription(_displayFunc(val), json_str);
		} else {
			return ValueDescription(json_str, json_str);
		}
	}
	std::unique_ptr<json_t> fromDescription(const ValueDescription& desc) const
	{
		json_error_t err;
		std::unique_ptr<json_t> el(json_loads(desc.serialized.c_str(), JSON_DECODE_ANY, &err));
		if (el == nullptr) {
			// Shouldn't really happen...
			throw json_exception(err);
		}
		return el;
	}

  public:
	Option(const SCP_string& config_key, const SCP_string& title, const SCP_string& description)
	    : OptionBase(config_key, title, description)
	{
	}
	~Option() override = default;

	OptionType getType() const override { return _type; }
	void setType(OptionType type) { _type = type; }

	SCP_vector<ValueDescription> getValidValues() const override
	{
		Assertion(_valueEnumerator, "Invalid value enumerator detected!");
		Assertion(_type == OptionType::Selection, "getValidValues may only be called on selection option!");

		auto values = _valueEnumerator();
		SCP_vector<ValueDescription> descriptions;
		descriptions.reserve(values.size());

		for (const auto& val : values) {
			descriptions.emplace_back(toDescription(val));
		}

		return descriptions;
	}

	ValueDescription getValueFromRange(float interpolant) const override
	{
		Assertion(_interpolator, "Need a valid interpolator!");
		Assertion(_type == OptionType::Range, "getValidValues may only be called on range option!");
		try {
			return toDescription(_interpolator(interpolant));
		} catch (const std::exception&) {
			return toDescription(_defaultValueFunc());
		}
	}
	float getInterpolantFromValue(const ValueDescription& val) const override
	{
		Assertion(_deinterpolator, "Need a valid deinterpolator!");
		Assertion(_type == OptionType::Range, "getInterpolantFromValue may only be called on range option!");
		try {
			auto el = fromDescription(val);
			return _deinterpolator(_deserializer(el.get()));
		} catch (const std::exception&) {
			return 0.0f;
		}
	}
	T getValue() const
	{
		try {
			tl::optional<std::unique_ptr<json_t>> config_value = getConfigValue();
			//missing keys are signalled via the optional
			if (!config_value.has_value()) {
				return _defaultValueFunc();
			}
			return _deserializer(config_value->get());
		} catch (const std::exception&) {
			// deserializers are allowed to throw on error
			return _defaultValueFunc();
		}
	}
	ValueDescription getCurrentValueDescription() const override
	{
		auto val = getValue();
		return toDescription(val);
	}
	void setValueDescription(const ValueDescription& desc) const override
	{
		std::unique_ptr<json_t> el;
		try {
			el = fromDescription(desc);
		} catch (const std::exception&) {
			// Functions are allowed to throw
		}
		if (el) {
			_parent->setConfigValue(_config_key, std::move(el));
		}
	}
	bool valueChanged(const json_t* val) const override
	{
		try {
			if (_changeListener) {
				return _changeListener(_deserializer(val), false);
			}
			return false; // Value not changed, requires restart
		} catch (const std::exception&) {
			// Functions are allowed to throw
			return false;
		}
	}

	void loadInitial() const override
	{
		if (!_changeListener) {
			// This requires a change listener
			return;
		}

		try {
			_changeListener(getValue(), true);
		} catch (const std::exception&) {
		}
	}

	const DefaultValueFunctor<T>& getDefaultValueFunc() const { return _defaultValueFunc; }
	void setDefaultValueFunc(const DefaultValueFunctor<T>& defaultValueFunc) { _defaultValueFunc = defaultValueFunc; }

	const ValueDeserializer<T>& getDeserializer() const { return _deserializer; }
	void setDeserializer(const ValueDeserializer<T>& converter) { _deserializer = converter; }

	const ValueSerializer<T>& getSerializer() const { return _serializer; }
	void setSerializer(const ValueSerializer<T>& serializer) { _serializer = serializer; }

	const ValueDisplay<T>& getDisplayFunc() const { return _displayFunc; }
	void setDisplayFunc(const ValueDisplay<T>& displayFunc) { _displayFunc = displayFunc; }

	const ValueEnumerator<T>& getValueEnumerator() const { return _valueEnumerator; }
	void setValueEnumerator(const ValueEnumerator<T>& valueEnumerator)
	{
		_valueEnumerator = valueEnumerator;
		_type            = OptionType::Selection;
	}

	const ValueChangeListener<T>& getChangeListener() const { return _changeListener; }
	void setChangeListener(const ValueChangeListener<T>& changeListener) { _changeListener = changeListener; }

	const ValueInterpolator<T>& getInterpolator() const { return _interpolator; }
	const ValueDeinterpolator<T>& getDeinterpolator() const { return _deinterpolator; }
	void setInterpolator(const ValueInterpolator<T>& interpolator, const ValueDeinterpolator<T>& deinterpolator)
	{
		_interpolator   = interpolator;
		_deinterpolator = deinterpolator;
		_type           = OptionType::Range;
	}
};

template <typename T>
class VectorEnumerator {
	SCP_vector<T> _values;

  public:
	explicit VectorEnumerator(SCP_vector<T> values) : _values(std::move(values)) {}

	SCP_vector<T> operator()() { return _values; }
};

template <typename T>
class MapValueDisplay {
	SCP_unordered_map<T, std::pair<const char*, int>> _mapping;

  public:
	explicit MapValueDisplay(SCP_unordered_map<T, std::pair<const char*, int>> mapping)
	    : _mapping(std::move(mapping))
	{
	}

	SCP_string operator()(const T& value) const
	{
		auto iter = _mapping.find(value);
		if (iter == _mapping.end()) {
			throw std::runtime_error("Display called with invalid value!");
		}
		return XSTR(iter->second.first, iter->second.second);
	}
};

namespace internal {
// This would be so much easier with Concepts...
template <typename T>
typename std::enable_if<!std::is_enum<T>::value, void>::type set_defaults(Option<T>& /*opt*/)
{
	// No defaults for the generic case since we don't know anything about this
}

template <>
void set_defaults<SCP_string>(Option<SCP_string>& opt);

template <>
void set_defaults<float>(Option<float>& opt);

template <>
void set_defaults<int>(Option<int>& opt);

template <>
void set_defaults<bool>(Option<bool>& opt);

template <typename T>
typename std::enable_if<std::is_enum<T>::value, void>::type set_defaults(Option<T>& opt)
{
	opt.setSerializer([](T val) { return json_pack("I", static_cast<json_int_t>(val)); });
	opt.setDeserializer([](const json_t* value) {
		json_int_t i;

		json_error_t err;
		if (json_unpack_ex((json_t*)value, &err, 0, "I", &i) != 0) {
			throw json_exception(err);
		}

		return static_cast<T>(i);
	});
}

template <typename T, size_t N>
void set_defaults(Option<flagset<T, N>>& opt)
{
	opt.setSerializer([](const flagset<T, N>& val) { return json_pack("I", static_cast<json_int_t>(val.to_u64())); });
	opt.setDeserializer([](const json_t* value) {
		json_int_t i;

		json_error_t err;
		if (json_unpack_ex((json_t*)value, &err, 0, "I", &i) != 0) {
			throw json_exception(err);
		}

		flagset<T, N> out;
		out.from_u64((std::uint64_t)i);
		return out;
	});
}

} // namespace internal

template <typename T>
class OptionBuilder {
	Option<T> _instance;

	SCP_unordered_map<PresetKind, T> _preset_values;
	const mpark::variant<SCP_string, std::pair<const char*, int>>&_title, &_description;

  public:
	  OptionBuilder(const SCP_string& config_key, const mpark::variant<SCP_string, std::pair<const char*, int>>& title, const mpark::variant<SCP_string, std::pair<const char*, int>>& description)
		  : _instance(
			  config_key,
			  mpark::holds_alternative<SCP_string>(title) ? mpark::get<SCP_string>(title) : mpark::get<std::pair<const char*, int>>(title).first,
			  mpark::holds_alternative<SCP_string>(description) ? mpark::get<SCP_string>(description) : mpark::get<std::pair<const char*, int>>(description).first),
		    _title(title),
		    _description(description)
	{
		internal::set_defaults(_instance);
	}

	OptionBuilder(const OptionBuilder&) = delete;
	OptionBuilder& operator=(const OptionBuilder&) = delete;

	OptionBuilder(OptionBuilder&&) noexcept = delete;
	OptionBuilder& operator=(OptionBuilder&&) noexcept = delete;
	//Set the category of the option
	OptionBuilder& category(const std::pair<const char*, int>& category)
	{
		_instance.setCategory(category);
		return *this;
	}
	//Set the level value of the option. Can be "Beginniner", "Advanced", or "Expert"
	OptionBuilder& level(ExpertLevel level)
	{
		_instance.setExpertLevel(level);
		return *this;
	}
	//Directly set the default value of an option
	OptionBuilder& default_val(const T& val)
	{
		_instance.setDefaultValueFunc(ValueFunctor<T>(val));
		return *this;
	}
	//Function to find the default value of the option
	OptionBuilder& default_func(const DefaultValueFunctor<T>& func)
	{
		_instance.setDefaultValueFunc(func);
		return *this;
	}
	//Deserialize an option for persisting changes
	OptionBuilder& deserializer(const ValueDeserializer<T>& converter)
	{
		_instance.setDeserializer(converter);
		return *this;
	}
	//Serialize an option value for display
	OptionBuilder& serializer(const ValueSerializer<T>& serializer)
	{
		_instance.setSerializer(serializer);
		return *this;
	}
	//Builds an enum list of values for the optoin
	OptionBuilder& enumerator(const ValueEnumerator<T>& enumerator)
	{
		_instance.setValueEnumerator(enumerator);
		return *this;
	}
	//The valid values for the option
	OptionBuilder& values(const SCP_vector<std::pair<T, std::pair<const char*, int>>>& value_display_pairs)
	{
		SCP_vector<T> values;
		SCP_unordered_map<T, std::pair<const char*, int>> display_mapping;

		for (auto& p : value_display_pairs) {
			values.push_back(p.first);
			display_mapping.emplace(p.first, p.second);
		}

		_instance.setValueEnumerator(VectorEnumerator<T>(values));
		_instance.setDisplayFunc(MapValueDisplay<T>(display_mapping));
		return *this;
	}
	//The string to display for the option values, usually a function that returns a string
	OptionBuilder& display(const ValueDisplay<T>& display)
	{
		_instance.setDisplayFunc(display);
		return *this;
	}
	//The code to run if the option value is changed
	OptionBuilder& change_listener(const ValueChangeListener<T>& listener)
	{
		_instance.setChangeListener(listener);
		return *this;
	}
	//The global variable to bind the option to immediately.
	OptionBuilder& bind_to(T* dest)
	{
		return change_listener([dest](const T& val, bool) {
			*dest = val;
			return true;
		});
	}
	//The global variable to bind the option to once. Will require game restart to persist changes.
	OptionBuilder& bind_to_once(T* dest)
	{
		_instance.setIsOnce(true);
		return change_listener([dest](const T& val, bool initial) {
			if (initial) {
				*dest = val;
			}
			return initial;
		});
	}
	//Set the minimum and maximum range for a "slider" type option
	OptionBuilder& range(T min, T max)
	{
		Assertion(min <= max, "Invalid number range!");
		_instance.setRangeValues(static_cast<float>(min), static_cast<float>(max));
		_instance.setInterpolator(
		    [min, max](float f) { return min + static_cast<T>((max - min) * f); },
		    [min, max](T f) { return static_cast<float>(f - min) / static_cast<float>(max - min); });
		return *this;
	}
	//Set the preset value for the option
	OptionBuilder& preset(PresetKind kind, const T& value)
	{
		_preset_values.emplace(kind, value);
		return *this;
	}
	//Set the option importance, used for sorting
	OptionBuilder& importance(int value)
	{
		_instance.setImportance(value);
		return *this;
	}
	//Set the option flags
	OptionBuilder& flags(const flagset<OptionFlags>& flags)
	{
		_instance.setFlags(flags);
		return *this;
	}
	//Finishes building the option and returns a pointer to it
	std::shared_ptr<const Option<T>> finish()
	{
		for (auto& val : _preset_values) {
			_instance.setPreset(val.first, json_dump_string_new(_instance.getSerializer()(val.second),
			                                                    JSON_COMPACT | JSON_ENSURE_ASCII | JSON_ENCODE_ANY));
		}
		auto opt_ptr = make_shared<Option<T>>(_instance);

		if (mpark::holds_alternative<std::pair<const char*, int>>(_title)) {
			const auto& xstr_info = mpark::get<std::pair<const char*, int>>(_title);
			lcl_delayed_xstr(opt_ptr->_title, xstr_info.first, xstr_info.second);
		}

		if (mpark::holds_alternative<std::pair<const char*, int>>(_description)) {
			const auto& xstr_info = mpark::get<std::pair<const char*, int>>(_description);
			lcl_delayed_xstr(opt_ptr->_description, xstr_info.first, xstr_info.second);
		}

		OptionsManager::instance()->addOption(opt_ptr);
		return opt_ptr;
	}
};

} // namespace options