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
|
/*
* This file is part of libplacebo.
*
* libplacebo is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* libplacebo 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 Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with libplacebo. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef LIBPLACEBO_OPTIONS_H_
#define LIBPLACEBO_OPTIONS_H_
#include <libplacebo/renderer.h>
PL_API_BEGIN
// High-level heap-managed struct containing storage for all options implied by
// pl_render_params, including a high-level interface for serializing,
// deserializing and interfacing with them in a programmatic way.
typedef const struct pl_opt_t *pl_opt;
typedef struct pl_options_t {
// Non-NULL `params.*_params` pointers must always point into this struct
struct pl_render_params params;
// Backing storage for all of the various rendering parameters. Whether
// or not these params are active is determined by whether or not
// `params.*_params` is set to this address or NULL.
struct pl_deband_params deband_params;
struct pl_sigmoid_params sigmoid_params;
struct pl_color_adjustment color_adjustment;
struct pl_peak_detect_params peak_detect_params;
struct pl_color_map_params color_map_params;
struct pl_dither_params dither_params;
struct pl_icc_params icc_params PL_DEPRECATED;
struct pl_cone_params cone_params;
struct pl_blend_params blend_params;
struct pl_deinterlace_params deinterlace_params;
struct pl_distort_params distort_params;
// Backing storage for "custom" scalers. `params.upscaler` etc. will
// always be a pointer either to a built-in pl_filter_config, or one of
// these structs. `name`, `description` and `allowed` will always be
// valid for the respective type of filter config.
struct pl_filter_config upscaler;
struct pl_filter_config downscaler;
struct pl_filter_config plane_upscaler;
struct pl_filter_config plane_downscaler;
struct pl_filter_config frame_mixer;
} *pl_options;
// Allocate a new set of render params, with internally backed storage for
// all parameters. Initialized to an "empty" config (PL_RENDER_DEFAULTS),
// equivalent to `&pl_render_fast_params`. To initialize the struct instead to
// the recommended default parameters, use `pl_options_reset` with
// `pl_render_default_params`.
//
// If `log` is provided, errors related to parsing etc. will be logged there.
PL_API pl_options pl_options_alloc(pl_log log);
PL_API void pl_options_free(pl_options *opts);
// Resets all options to their default values from a given struct. If `preset`
// is NULL, `opts` is instead reset back to the initial "empty" configuration,
// with all options disabled, as if it was freshly allocated.
//
// Note: This function will also reset structs which were not included in
// `preset`, such as any custom upscalers.
PL_API void pl_options_reset(pl_options opts, const struct pl_render_params *preset);
typedef const struct pl_opt_data_t {
// Original options struct.
pl_options opts;
// Triggering option for this callback invocation.
pl_opt opt;
// The raw data associated with this option. Always some pointer into
// `opts`. Note that only PL_OPT_BOOL, PL_OPT_INT and PL_OPT_FLOAT have
// a fixed representation, for other fields its usefulness is dubious.
const void *value;
// The underlying data, as a formatted, locale-invariant string. Lifetime
// is limited until the return of this callback.
const char *text;
} *pl_opt_data;
// Query a single option from `opts` by key, or NULL if none was found.
// The resulting pointer is only valid until the next pl_options_* call.
PL_API pl_opt_data pl_options_get(pl_options opts, const char *key);
// Update an option from a formatted value string (see `pl_opt_data.text`).
// This can be used for all type of options, even non-string ones. In this case,
// `value` will be parsed according to the option type.
//
// Returns whether successful.
PL_API bool pl_options_set_str(pl_options opts, const char *key, const char *value);
// Programmatically iterate over options set in a `pl_options`, running the
// provided callback on each entry.
PL_API void pl_options_iterate(pl_options opts,
void (*cb)(void *priv, pl_opt_data data),
void *priv);
// Serialize a `pl_options` structs to a comma-separated key/value string. The
// returned string has a lifetime valid until either the next call to
// `pl_options_save`, or until the `pl_options` is freed.
PL_API const char *pl_options_save(pl_options opts);
// Parse a `pl_options` struct from a key/value string, in standard syntax
// "key1=value1,key2=value2,...", and updates `opts` with the new values.
// Valid separators include whitespace, commas (,) and (semi)colons (:;).
//
// Returns true if no errors occurred.
PL_API bool pl_options_load(pl_options opts, const char *str);
// Helpers for interfacing with `opts->params.hooks`. Note that using any of
// these helpers will overwrite the array by an internally managed pointer,
// so care must be taken when combining them with external management of
// this memory. Negative indices are possible and are counted relative to the
// end of the list.
//
// Note: These hooks are *not* included in pl_options_save() and related.
PL_API void pl_options_add_hook(pl_options opts, const struct pl_hook *hook);
PL_API void pl_options_insert_hook(pl_options opts, const struct pl_hook *hook, int idx);
PL_API void pl_options_remove_hook_at(pl_options opts, int idx);
// Underlying options system and list
//
// Note: By necessity, this option list does not cover every single field
// present in `pl_render_params`. In particular, fields like `info_callback`,
// `lut` and `hooks` cannot be configured through the options system, as doing
// so would require interop with C code or I/O. (However, see
// `pl_options_add_hook` and related)
enum pl_option_type {
// Accepts `yes/no`, `on/off`, `true/false` and variants
PL_OPT_BOOL,
// Parsed as human-readable locale-invariant (C) numbers, scientific
// notation accepted for floats
PL_OPT_INT,
PL_OPT_FLOAT,
// Parsed as a short string containing only alphanumerics and _-,
// corresponding to some name/identifier. Catch-all bucket for several
// other types of options, such as presets, struct pointers, and functions
//
// Note: These options do not correspond to actual strings in C, the
// underlying type of option will determine the values of `size` and
// corresponding interpretation of pointers.
PL_OPT_STRING,
PL_OPT_TYPE_COUNT,
};
struct pl_opt_t {
// Programmatic key uniquely identifying this option.
const char *key;
// Longer, human readable friendly name
const char *name;
// Data type of option, affects how it is parsed. This field is purely
// informative for the user, the actual implementation may vary.
enum pl_option_type type;
// Minimum/maximum value ranges for numeric options (int / float)
// If both are 0.0, these limits are disabled/ignored.
float min, max;
// If true, this option is considered deprecated and may be removed
// in the future.
bool deprecated;
// If true, this option is considered a 'preset' (read-only), which can
// be loaded but not saved. (The equivalent underlying options this preset
// corresponds to will be saved instead)
bool preset;
// Internal implementation details (for parsing/saving), opaque to user
const void *priv;
};
// A list of options, terminated by {0} for convenience
PL_API extern const struct pl_opt_t pl_option_list[];
PL_API extern const int pl_option_count; // excluding terminating {0}
// Returns the `pl_option` associated with a given key, or NULL
PL_API pl_opt pl_find_option(const char *key);
PL_API_END
#endif // LIBPLACEBO_OPTIONS_H_
|
