1 : /* SLV2
2 : * Copyright (C) 2007-2009 Dave Robillard <http://drobilla.net>
3 : *
4 : * This library is free software; you can redistribute it and/or modify it
5 : * under the terms of the GNU General Public License as published by the Free
6 : * Software Foundation; either version 2 of the License, or (at your option)
7 : * any later version.
8 : *
9 : * This library is distributed in the hope that it will be useful, but WITHOUT
10 : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 : * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 : * for more details.
13 : *
14 : * You should have received a copy of the GNU General Public License along
15 : * with this program; if not, write to the Free Software Foundation, Inc.,
16 : * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17 : */
18 :
19 : #ifndef __SLV2_PLUGININSTANCE_H__
20 : #define __SLV2_PLUGININSTANCE_H__
21 :
22 : #ifdef __cplusplus
23 : extern "C" {
24 : #endif
25 :
26 : #include <stddef.h>
27 : #include <stdlib.h>
28 : #include "lv2.h"
29 : #include "slv2/plugin.h"
30 : #include "slv2/port.h"
31 :
32 : typedef struct _InstanceImpl* SLV2InstanceImpl;
33 :
34 : /** \cond IGNORE */
35 :
36 : /* Instance of a plugin.
37 : *
38 : * The LV2 descriptor and handle of this are exposed to allow inlining of
39 : * performance critical functions like slv2_instance_run (which are exposed
40 : * in lv2.h anyway). This is for performance only, this struct is not
41 : * documented and should not be used directly. The remaining implementation
42 : * details are in the opaque pimpl member.
43 : */
44 : typedef struct _Instance {
45 : const LV2_Descriptor* lv2_descriptor;
46 : LV2_Handle lv2_handle;
47 : SLV2InstanceImpl pimpl; ///< Private implementation
48 : }* SLV2Instance;
49 :
50 : /** \endcond */
51 :
52 :
53 : /** \defgroup slv2_library Plugin library access
54 : *
55 : * An SLV2Instance is an instantiated SLV2Plugin (ie a loaded dynamic
56 : * library). These functions interact with the binary library code only,
57 : * they do not read data files in any way.
58 : *
59 : * @{
60 : */
61 :
62 : /** Instantiate a plugin.
63 : *
64 : * The returned object represents shared library objects loaded into memory,
65 : * it must be cleaned up with slv2_instance_free when no longer
66 : * needed.
67 : *
68 : * \a plugin is not modified or directly referenced by the returned object
69 : * (instances store only a copy of the plugin's URI).
70 : *
71 : * \a host_features NULL-terminated array of features the host supports.
72 : * NULL may be passed if the host supports no additional features (unlike
73 : * the LV2 specification - SLV2 takes care of it).
74 : *
75 : * \return NULL if instantiation failed.
76 : */
77 : SLV2Instance
78 : slv2_plugin_instantiate(SLV2Plugin plugin,
79 : double sample_rate,
80 : const LV2_Feature*const* features);
81 :
82 :
83 : /** Free a plugin instance.
84 : *
85 : * \a instance is invalid after this call.
86 : */
87 : void
88 : slv2_instance_free(SLV2Instance instance);
89 :
90 : #ifndef LIBSLV2_SOURCE
91 :
92 : /** Get the URI of the plugin which \a instance is an instance of.
93 : *
94 : * Returned string is shared and must not be modified or deleted.
95 : */
96 : static inline const char*
97 : slv2_instance_get_uri(SLV2Instance instance)
98 0 : {
99 0 : return instance->lv2_descriptor->URI;
100 : }
101 :
102 :
103 : /** Connect a port to a data location.
104 : *
105 : * This may be called regardless of whether the plugin is activated,
106 : * activation and deactivation does not destroy port connections.
107 : */
108 : static inline void
109 : slv2_instance_connect_port(SLV2Instance instance,
110 : uint32_t port_index,
111 : void* data_location)
112 0 : {
113 0 : instance->lv2_descriptor->connect_port
114 : (instance->lv2_handle, port_index, data_location);
115 0 : }
116 :
117 :
118 : /** Activate a plugin instance.
119 : *
120 : * This resets all state information in the plugin, except for port data
121 : * locations (as set by slv2_instance_connect_port). This MUST be called
122 : * before calling slv2_instance_run.
123 : */
124 : static inline void
125 : slv2_instance_activate(SLV2Instance instance)
126 0 : {
127 0 : if (instance->lv2_descriptor->activate)
128 0 : instance->lv2_descriptor->activate(instance->lv2_handle);
129 0 : }
130 :
131 :
132 : /** Run \a instance for \a sample_count frames.
133 : *
134 : * If the hint lv2:hardRtCapable is set for this plugin, this function is
135 : * guaranteed not to block.
136 : */
137 : static inline void
138 : slv2_instance_run(SLV2Instance instance,
139 : uint32_t sample_count)
140 0 : {
141 : /*if (instance->lv2_descriptor->run)*/
142 0 : instance->lv2_descriptor->run(instance->lv2_handle, sample_count);
143 0 : }
144 :
145 :
146 : /** Deactivate a plugin instance.
147 : *
148 : * Note that to run the plugin after this you must activate it, which will
149 : * reset all state information (except port connections).
150 : */
151 : static inline void
152 : slv2_instance_deactivate(SLV2Instance instance)
153 0 : {
154 0 : if (instance->lv2_descriptor->deactivate)
155 0 : instance->lv2_descriptor->deactivate(instance->lv2_handle);
156 0 : }
157 :
158 :
159 : /** Get extension data from the plugin instance.
160 : *
161 : * The type and semantics of the data returned is specific to the particular
162 : * extension, though in all cases it is shared and must not be deleted.
163 : */
164 : static inline const void*
165 : slv2_instance_get_extension_data(SLV2Instance instance,
166 : const char* uri)
167 0 : {
168 0 : if (instance->lv2_descriptor->extension_data)
169 0 : return instance->lv2_descriptor->extension_data(uri);
170 : else
171 0 : return NULL;
172 : }
173 :
174 :
175 : /** Get the LV2_Descriptor of the plugin instance.
176 : *
177 : * Normally hosts should not need to access the LV2_Descriptor directly,
178 : * use the slv2_instance_* functions.
179 : *
180 : * The returned descriptor is shared and must not be deleted.
181 : */
182 : static inline const LV2_Descriptor*
183 : slv2_instance_get_descriptor(SLV2Instance instance)
184 0 : {
185 0 : return instance->lv2_descriptor;
186 : }
187 :
188 :
189 : /** Get the LV2_Handle of the plugin instance.
190 : *
191 : * Normally hosts should not need to access the LV2_Handle directly,
192 : * use the slv2_instance_* functions.
193 : *
194 : * The returned handle is shared and must not be deleted.
195 : */
196 : static inline LV2_Handle
197 : slv2_instance_get_handle(SLV2Instance instance)
198 0 : {
199 0 : return instance->lv2_handle;
200 : }
201 :
202 : #endif /* LIBSLV2_SOURCE */
203 :
204 : /** @} */
205 :
206 : #ifdef __cplusplus
207 : } /* extern "C" */
208 : #endif
209 :
210 :
211 : #endif /* __SLV2_PLUGININSTANCE_H__ */
212 :
|
