/[svn]/linuxsampler/trunk/src/hostplugins/lv2/lv2_persist.h
ViewVC logotype

Contents of /linuxsampler/trunk/src/hostplugins/lv2/lv2_persist.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2174 - (show annotations) (download) (as text)
Tue Apr 12 15:19:56 2011 UTC (8 years, 9 months ago) by capela
File MIME type: text/x-c++hdr
File size: 9224 byte(s)
* plugin changes:
    - LV2 Persist + Files support (patch by David Robillard)

1 /*
2 Copyright 2010-2011 David Robillard <http://drobilla.net>
3 Copyright 2010 Leonard Ritter <paniq@paniq.org>
4
5 This header is free software; you can redistribute it and/or modify it
6 under the terms of the GNU Lesser General Public License as published
7 by the Free Software Foundation; either version 2 of the License, or
8 (at your option) any later version.
9
10 This header is distributed in the hope that it will be useful, but WITHOUT
11 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
13 License for more details.
14
15 You should have received a copy of the GNU Lesser General Public License
16 along with this header; if not, write to the Free Software Foundation,
17 Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA
18 */
19
20 /**
21 @file
22 C API for the LV2 Persist extension <http://lv2plug.in/ns/ext/persist>.
23 */
24
25 #ifndef LV2_PERSIST_H
26 #define LV2_PERSIST_H
27
28 #include <stdbool.h>
29 #include <stdint.h>
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 #define LV2_PERSIST_URI "http://lv2plug.in/ns/ext/persist"
36
37 /**
38 Flags describing value characteristics.
39
40 These flags are used along with the value's type URI to determine how to
41 (de-)serialise the value data, or whether it is even possible to do so.
42 */
43 typedef enum {
44
45 /**
46 Plain Old Data.
47
48 Values with this flag contain no references to non-persistent or
49 non-global resources (e.g. pointers, handles, local paths, etc.). It is
50 safe to copy POD values with a simple memcpy and store them for use at
51 any time in the future on a machine with a compatible architecture
52 (e.g. the same endianness and alignment).
53
54 Implementations MUST NOT attempt to copy or serialise a non-POD value if
55 they do not understand its type (and thus know how to correctly do so).
56 */
57 LV2_PERSIST_IS_POD = 1,
58
59 /**
60 Portable (architecture independent) data.
61
62 Values with this flag are in a format that is usable on any
63 architecture, i.e. if the value is saved on one machine it can safely be
64 restored on another machine regardless of endianness, alignment, etc.
65 */
66 LV2_PERSIST_IS_PORTABLE = 1 << 1
67
68 } LV2_Persist_Flags;
69
70 /**
71 A host-provided function to store a property.
72 @param callback_data Must be the callback_data passed to LV2_Persist.save().
73 @param key The key (predicate) to store @a value under (URI mapped integer).
74 @param value Pointer to the value (object) to be stored.
75 @param size The size of the data at @a value in bytes.
76 @param type The type of @a value (URI).
77 @param flags LV2_Persist_Flags for @a value.
78 @return 0 on success, otherwise a non-zero error code.
79
80 The host passes a callback of this type to LV2_Persist.save(). This callback
81 is called repeatedly by the plugin within LV2_Persist.save() to store all
82 the statements that describe its current state.
83
84 The host MAY fail to store a property if the type is not understood and is
85 not LV2_PERSIST_IS_POD and/or LV2_PERSIST_IS_PORTABLE. Implementations are
86 encouraged to use POD and portable values (e.g. string literals) wherever
87 possible, and use common types (e.g. types from
88 http://lv2plug.in/ns/ext/atom) regardless, since hosts are likely to already
89 contain the necessary implementation.
90
91 Note that @a size MUST be > 0, and @a value MUST point to a valid region of
92 memory @a size bytes long (this is required to make restore unambiguous).
93
94 The plugin MUST NOT attempt to use this function outside of the
95 LV2_Persist.restore() context.
96 */
97 typedef int (*LV2_Persist_Store_Function)(
98 void* callback_data,
99 uint32_t key,
100 const void* value,
101 size_t size,
102 uint32_t type,
103 uint32_t flags);
104
105 /**
106 A host-provided function to retrieve a property.
107 @param callback_data Must be the callback_data passed to LV2_Persist.restore().
108 @param key The key (predicate) of the property to retrieve (URI).
109 @param size (Output) If non-NULL, set to the size of the restored value.
110 @param type (Output) If non-NULL, set to the type of the restored value.
111 @param flags (Output) If non-NULL, set to the LV2_Persist_Flags for
112 the returned value.
113 @return A pointer to the restored value (object), or NULL if no value
114 has been stored under @a key.
115
116 A callback of this type is passed by the host to LV2_Persist.restore(). This
117 callback is called repeatedly by the plugin within LV2_Persist.restore() to
118 retrieve any properties it requires to restore its state.
119
120 The returned value MUST remain valid until LV2_Persist.restore() returns.
121
122 The plugin MUST NOT attempt to use this function, or any value returned from
123 it, outside of the LV2_Persist.restore() context. Returned values MAY be
124 copied for later use if necessary, assuming the plugin knows how to do so
125 correctly (e.g. the value is POD, or the plugin understands the type).
126 */
127 typedef const void* (*LV2_Persist_Retrieve_Function)(
128 void* callback_data,
129 uint32_t key,
130 size_t* size,
131 uint32_t* type,
132 uint32_t* flags);
133
134 /**
135 Persist Extension Data.
136
137 When the plugin's extension_data is called with argument LV2_PERSIST_URI,
138 the plugin MUST return an LV2_Persist structure, which remains valid for the
139 lifetime of the plugin.
140
141 The host can use the contained function pointers to save and restore the
142 state of a plugin instance at any time (provided the threading restrictions
143 for the given function are met).
144
145 The typical use case is to save the plugin's state when a project is saved,
146 and to restore the state when a project has been loaded. Other uses are
147 possible (e.g. cloning plugin instances or taking a snapshot of plugin
148 state).
149
150 Stored data is only guaranteed to be compatible between instances of plugins
151 with the same URI (i.e. if a change to a plugin would cause a fatal error
152 when restoring state saved by a previous version of that plugin, the plugin
153 URI MUST change just as it must when ports change incompatibly). Plugin
154 authors should consider this possibility, and always store sensible data
155 with meaningful types to avoid such compatibility issues in the future.
156 */
157 typedef struct _LV2_Persist {
158
159 /**
160 Save plugin state using a host-provided @a store callback.
161
162 @param instance The instance handle of the plugin.
163 @param store The host-provided store callback.
164 @param callback_data An opaque pointer to host data, e.g. the map or
165 file where the values are to be stored. If @a store is called,
166 this MUST be passed as its callback_data parameter.
167
168 The plugin is expected to store everything necessary to completely
169 restore its state later (possibly much later, in a different process, on
170 a completely different machine, etc.)
171
172 The @a callback_data pointer and @a store function MUST NOT be used
173 beyond the scope of save().
174
175 This function has its own special threading class: it may not be called
176 concurrently with any "Instantiation" function, but it may be called
177 concurrently with functions in any other class, unless the definition of
178 that class prohibits it (e.g. it may not be called concurrently with a
179 "Discovery" function, but it may be called concurrently with an "Audio"
180 function. The plugin is responsible for any locking or lock-free
181 techniques necessary to make this possible.
182
183 Note that in the simple case where state is only modified by restore(),
184 there are no synchronization issues since save() is never called
185 concurrently with restore() (though run() may read it during a save).
186
187 Plugins that dynamically modify state while running, however, must take
188 care to do so in such a way that a concurrent call to save() will save a
189 consistent representation of plugin state for a single instant in time.
190 */
191 void (*save)(LV2_Handle instance,
192 LV2_Persist_Store_Function store,
193 void* callback_data);
194
195 /**
196 Restore plugin state using a host-provided @a retrieve callback.
197
198 @param instance The instance handle of the plugin.
199 @param retrieve The host-provided retrieve callback.
200 @param callback_data An opaque pointer to host data, e.g. the map or
201 file from which the values are to be restored. If @a retrieve is
202 called, this MUST be passed as its callback_data parameter.
203
204 The plugin MAY assume a restored value was set by a previous call to
205 LV2_Persist.save() by a plugin with the same URI.
206
207 The plugin MUST gracefully fall back to a default value when a value can
208 not be retrieved. This allows the host to reset the plugin state with an
209 empty map.
210
211 The @a callback_data pointer and @a store function MUST NOT be used
212 beyond the scope of restore().
213
214 This function is in the "Instantiation" threading class as defined by
215 LV2. This means it MUST NOT be called concurrently with any other
216 function on the same plugin instance.
217 */
218 void (*restore)(LV2_Handle instance,
219 LV2_Persist_Retrieve_Function retrieve,
220 void* callback_data);
221
222 } LV2_Persist;
223
224 #ifdef __cplusplus
225 } /* extern "C" */
226 #endif
227
228 #endif /* LV2_PERSIST_H */

  ViewVC Help
Powered by ViewVC