1 |
/************************************************************************ |
2 |
* |
3 |
* Save/Restore extension for LV2 |
4 |
* |
5 |
* Copyright (C) 2007-2008 Lars Luthman <lars.luthman@gmail.com> |
6 |
* |
7 |
* This header is free software; you can redistribute it and/or modify it |
8 |
* under the terms of the GNU Lesser General Public License as published |
9 |
* by the Free Software Foundation; either version 2.1 of the License, |
10 |
* or (at your option) any later version. |
11 |
* |
12 |
* This header is distributed in the hope that it will be useful, |
13 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 |
* Lesser General Public License for more details. |
16 |
* |
17 |
* You should have received a copy of the GNU Lesser General Public |
18 |
* License along with this library; if not, write to the Free Software |
19 |
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 |
20 |
* USA. |
21 |
* |
22 |
***********************************************************************/ |
23 |
|
24 |
#ifndef LV2_SAVERESTORE |
25 |
#define LV2_SAVERESTORE |
26 |
|
27 |
#include <lv2.h> |
28 |
|
29 |
#define LV2_SAVERESTORE_URI "http://ll-plugins.nongnu.org/lv2/ext/saverestore" |
30 |
|
31 |
#ifdef __cplusplus |
32 |
extern "C" { |
33 |
#endif |
34 |
|
35 |
/** @file |
36 |
|
37 |
This extension defines a way to save and restore the internal state |
38 |
of an LV2 plugin instance. The internal state does not include input |
39 |
port values, which are visible to the host, but rather things that |
40 |
the host has no way of knowing, such as loaded sample buffers that have |
41 |
been modified using GUI commands, or internal variables that have been |
42 |
updated and modified as a reaction to the input streams. A plugin that |
43 |
implements this extension must list |
44 |
<http://ll-plugins.nongnu.org/lv2/ext/saverestore> as an optional |
45 |
or required Feature in its RDF data, and it must have an |
46 |
extension_data() function pointer in its descriptor that returns a |
47 |
pointer to a LV2SR_Descriptor, defined below, when called with the same |
48 |
URI. The data pointer for the host feature passed to the plugin's |
49 |
instantiate() function should be NULL. |
50 |
|
51 |
The function pointer members in the LV2SR_Descriptor struct belong to the |
52 |
Instantiation class, and they must not be NULL. |
53 |
|
54 |
For the host, the typical use of this extension would go like this: |
55 |
|
56 |
* To save a plugin instance that has not been saved previously: |
57 |
- Create a directory /home/foo/mysession/myplugininstance |
58 |
- LV2SR_File* files; |
59 |
lv2srdesc->save(myplugin_handle, |
60 |
"/home/foo/mysession/myplugininstance", |
61 |
&files); |
62 |
- for each element in 'files' that has the 'must_copy' flag set, copy |
63 |
that file into /home/foo/mysession/myplugininstance if isn't already |
64 |
there and change the 'path' member to reflect the new location |
65 |
- save the names and paths for all elements in 'files' somewhere as |
66 |
part of the session |
67 |
|
68 |
* To restore a plugin instance that has been saved: |
69 |
- instantiate a new instance of that plugin |
70 |
- load the file paths and names from your session, allocate an array of |
71 |
LV2SR_File pointers, allocate the LV2SR_File objects and fill in the |
72 |
'name' and 'path' members |
73 |
- lv2srdesc->restore(myplugin_handle, files); |
74 |
|
75 |
* To save a plugin instance that already has been saved earlier: |
76 |
- LV2SR_File* files; |
77 |
lv2srdesc->save(myplugin_handle, |
78 |
"/home/foo/mysession/myplugininstance", |
79 |
&files); |
80 |
- erase all files in /home/foo/mysession/myplugininstance that aren't |
81 |
listed in the new 'files' array |
82 |
- for each element in 'files' that has the 'must_copy' flag set, copy |
83 |
that file into /home/foo/mysession/myplugininstance if isn't already |
84 |
there and change the 'path' member to reflect the new location |
85 |
- save the names and paths for all elements in 'files' somewhere as |
86 |
part of the session |
87 |
|
88 |
This extension allows for two "levels" of saving a plugin's state - |
89 |
the host can either just copy the files with the 'must_copy' flag set |
90 |
into its session directory and rely on the other files staying at the |
91 |
same paths in the filesystem (a "shallow" save) or it can copy every |
92 |
mentioned file into its session directory (a "deep" save). The latter |
93 |
may be useful when moving sessions between machines. |
94 |
|
95 |
Most simple plugins whose behaviour is completely defined by the current |
96 |
values in its control input ports should not need to implement this |
97 |
extension. |
98 |
|
99 |
*/ |
100 |
|
101 |
|
102 |
/** A simple struct that represents a file used by a plugin instance. */ |
103 |
typedef struct _LV2SR_File { |
104 |
|
105 |
/** A '\0'-terminated string that the plugin uses to identify the file (it |
106 |
can't use the file path since the host may move the file). The host |
107 |
should copy this verbatim and not try to interpret it in any way. */ |
108 |
char* name; |
109 |
|
110 |
/** The absolute path to the file. */ |
111 |
char* path; |
112 |
|
113 |
/** This is set to 1 by the plugin in the save() callback if this file must |
114 |
be copied by the host into persistent storage, 0 otherwise. Its value |
115 |
is not significant in the restore() callback. */ |
116 |
uint32_t must_copy; |
117 |
|
118 |
} LV2SR_File; |
119 |
|
120 |
|
121 |
/** A pointer to an object of this type is returned by extension_data() when |
122 |
called with the URI for this host feature. */ |
123 |
typedef struct _LV2SR_Descriptor { |
124 |
|
125 |
/** This function tells the plugin instance to save its current state. |
126 |
|
127 |
The files parameter should be a pointer to a valid LV2SR_File**. After |
128 |
the call to save() has returned, files MUST point to the start of |
129 |
a NULL-terminated array of LV2SR_File pointers allocated by |
130 |
the plugin, that the host should store as part of the plugin's saved |
131 |
state. The path members of the elements of this array MUST all be |
132 |
valid filesystem paths. If the member must_copy of an element of this |
133 |
array is nonzero, the host MUST copy the file at the associated path |
134 |
into some sort of persistant storage as a part of the plugin's state. |
135 |
If must_copy is zero, the host is free to choose whether to copy the |
136 |
file, or rely on the file staying in the same place until the plugin |
137 |
state is restored again. This array as well as all the name and path |
138 |
members of its elements should be deallocated by the host. |
139 |
|
140 |
The parameter directory MUST be a path to an existing directory. If |
141 |
the plugin creates any new must_copy files as a part of its save |
142 |
process it SHOULD create the new files in that directory. This is to |
143 |
help the host avoid unnecessary copying of files. |
144 |
|
145 |
A plugin that creates new files as a part of its save process must NOT |
146 |
overwrite or delete existing files in that directory, even if it knows |
147 |
that it created them itself for an earlier save. The host may want to |
148 |
keep them around for reverting back to an earlier state. |
149 |
|
150 |
This function should return NULL if the plugin has successfully saved |
151 |
its state and a dynamically allocated error message if not (e.g. not |
152 |
enough room on the disk). Any returned error message should be |
153 |
deallocated by the host using free(). If NULL is returned the host |
154 |
should not try to access or deallocate the array pointed to by the |
155 |
files parameter, or it's elements. |
156 |
|
157 |
This function pointer must not be set to NULL. |
158 |
*/ |
159 |
char* (*save)(LV2_Handle handle, |
160 |
const char* directory, |
161 |
LV2SR_File*** files); |
162 |
|
163 |
/** This function tells the plugin instance to restore to a saved state. |
164 |
|
165 |
The files parameter must be a pointer to a NULL-terminated array of |
166 |
LV2SR_File pointers, which should be identical to an array produced by |
167 |
an instance of the same plugin in an earlier call to save(), with the |
168 |
exception that the file paths may be changed to reflect the new |
169 |
locations of the files (the session may have been moved to some other |
170 |
part of the filesystem, the host may have reorganised its file |
171 |
hierarchy etc). |
172 |
|
173 |
This function should return NULL if it successfully restores a state |
174 |
from the given parameters and an error message otherwise. Any returned |
175 |
error message should be deallocated by the host. |
176 |
|
177 |
This function pointer must not be set to NULL. |
178 |
*/ |
179 |
char* (*restore)(LV2_Handle handle, |
180 |
const LV2SR_File** files); |
181 |
|
182 |
} LV2SR_Descriptor; |
183 |
|
184 |
|
185 |
#ifdef __cplusplus |
186 |
} |
187 |
#endif |
188 |
|
189 |
|
190 |
#endif |