1 |
cebix |
1.1 |
/* ================================================== |
2 |
|
|
SoundPlay plugin specification. |
3 |
|
|
================================================== */ |
4 |
|
|
|
5 |
|
|
#ifndef _PLUGIN_PROTO_H |
6 |
|
|
#define _PLUGIN_PROTO_H |
7 |
|
|
|
8 |
|
|
#include <SupportDefs.h> |
9 |
|
|
#include "Playlist.h" |
10 |
|
|
|
11 |
|
|
/* |
12 |
|
|
To let SoundPlay know which filetypes you support, you fill in an |
13 |
|
|
array of these. SoundPlay will add both an uppercase and a lowercase |
14 |
|
|
version of the extensions you specify to the mime database. |
15 |
|
|
*/ |
16 |
|
|
typedef struct supported_type |
17 |
|
|
{ |
18 |
|
|
char *mimetype; |
19 |
|
|
char *longdesc; |
20 |
|
|
char *shortdesc; |
21 |
|
|
char *extension1; |
22 |
|
|
char *extension2; |
23 |
|
|
} supported_type; |
24 |
|
|
|
25 |
|
|
|
26 |
|
|
/* |
27 |
|
|
Operations that can be performed before the plugin is really active. |
28 |
|
|
These functions globally affect and describe a plugin. They are |
29 |
|
|
used to identify and configure the plugin, and to instantiate one |
30 |
|
|
particular instance of the plugin. |
31 |
|
|
All types of plugins are handled through this interface. |
32 |
|
|
*/ |
33 |
|
|
|
34 |
|
|
class SoundPlayController; |
35 |
|
|
|
36 |
|
|
typedef struct plugin_info |
37 |
|
|
{ |
38 |
|
|
SoundPlayController *controller; |
39 |
|
|
entry_ref *ref; |
40 |
|
|
} plugin_info; |
41 |
|
|
|
42 |
|
|
typedef void op_about(); |
43 |
|
|
typedef BView* op_configure(BMessage *config); |
44 |
|
|
typedef void* op_instantiate(void **data, const char *name, const char *header, uint32 size, plugin_info *pluginfo); |
45 |
|
|
typedef void op_destroy(void *plugin_ops, void *data); |
46 |
|
|
|
47 |
|
|
/* And this structure contains the above functions. */ |
48 |
|
|
typedef struct plugin_descriptor |
49 |
|
|
{ |
50 |
|
|
// first some bookkeeping stuff |
51 |
|
|
uint32 desc_magic; // magic number |
52 |
|
|
uint32 desc_version; // version of this plugin structure |
53 |
|
|
|
54 |
|
|
const char* id; // a unique string identifying your plugin |
55 |
|
|
uint32 version; // distinguish between different version of the same plugin |
56 |
|
|
uint32 flags; // PLUGIN_IS_DECODER, PLUGIN_IS_FILTER, PLUGIN_IS_VISUAL |
57 |
|
|
|
58 |
|
|
const char* name; // MUST be filled in |
59 |
|
|
const char* aboutstring; // Simple about string, in case you don't want to implement the About() function. |
60 |
|
|
|
61 |
|
|
op_about (*About); // Leave NULL if not implemented |
62 |
|
|
op_configure (*Configure); // Leave NULL if not implemented |
63 |
|
|
|
64 |
|
|
op_instantiate (*Instantiate_Plugin); // MUST be implemented, instantiates all types of plugins, returns pointer to plugin struct (see below) |
65 |
|
|
op_destroy (*Destroy_Plugin); // MUST be implemented, destroys the plugin created by Instantiate_Plugin() |
66 |
|
|
} plugin_descriptor; |
67 |
|
|
|
68 |
|
|
|
69 |
|
|
/* |
70 |
|
|
Only these function need to be exported. |
71 |
|
|
They return a pointer to an array of pointers to plugin_descriptor, |
72 |
|
|
which lists all the plugins in this plugin-file, and a pointer to an |
73 |
|
|
array of supportedtypes. |
74 |
|
|
*/ |
75 |
|
|
extern "C" plugin_descriptor _EXPORT **get_plugin_list(void); |
76 |
|
|
extern "C" supported_type _EXPORT *get_supported_types(void); |
77 |
|
|
|
78 |
|
|
|
79 |
|
|
/* |
80 |
|
|
These are the operations that can be performed on a particular instance |
81 |
|
|
of a decoder-plugin, once it has been instantiated. |
82 |
|
|
The void* that each function gets as the first argument is the data pointer |
83 |
|
|
that was filled in by Instantiate_Plugin |
84 |
|
|
*/ |
85 |
|
|
|
86 |
|
|
struct file_info; |
87 |
|
|
|
88 |
|
|
typedef status_t op_decoder_open(void*,const char *name, const char *header, uint32 size, BMessage *config); |
89 |
|
|
typedef void op_decoder_close(void*); |
90 |
|
|
typedef status_t op_decoder_info(void*,file_info*); |
91 |
|
|
typedef int32 op_decoder_read(void *,char *buf, ulong count); |
92 |
|
|
typedef status_t op_decoder_play(void*); |
93 |
|
|
typedef status_t op_decoder_stop(void*); |
94 |
|
|
typedef status_t op_decoder_setvolume(void*,float); |
95 |
|
|
typedef status_t op_decoder_setspeed(void *,float speed); |
96 |
|
|
typedef status_t op_decoder_seek(void*, uint32 pos); |
97 |
|
|
typedef uint32 op_decoder_position(void*); |
98 |
|
|
typedef float op_decoder_bufferamount(void*); |
99 |
|
|
|
100 |
|
|
/* |
101 |
|
|
The following structure contains pointers to the above |
102 |
|
|
functions. Simply leave NULL if not implemented. |
103 |
|
|
*/ |
104 |
|
|
|
105 |
|
|
typedef struct decoder_plugin_ops |
106 |
|
|
{ |
107 |
|
|
// first some bookkeeping stuff |
108 |
|
|
uint32 ops_magic; // magic number |
109 |
|
|
uint32 ops_version; // version of this plugin structure |
110 |
|
|
|
111 |
|
|
// and the function pointers. |
112 |
|
|
op_decoder_open (*Open); // leave NULL if not implemented |
113 |
|
|
op_decoder_close (*Close); // leave NULL if not implemented |
114 |
|
|
op_decoder_info (*Info); // MUST be implemented |
115 |
|
|
|
116 |
|
|
op_decoder_read (*Read); // leave NULL for input filters that don't produce data |
117 |
|
|
|
118 |
|
|
op_decoder_play (*Play); // leave NULL if you do provide data |
119 |
|
|
op_decoder_stop (*Stop); // leave NULL if you do provide data |
120 |
|
|
op_decoder_setvolume (*SetVolume); // leave NULL if you do provide data |
121 |
|
|
op_decoder_setspeed (*SetSpeed); // leave NULL if you do provide data |
122 |
|
|
op_decoder_seek (*Seek); // leave NULL if seeking is not possible (streams) |
123 |
|
|
op_decoder_position (*Position); // leave NULL if you can't provide position-info |
124 |
|
|
op_decoder_bufferamount (*BufferAmount); // leave NULL if you don't want to display a buffer-indicator |
125 |
|
|
} decoder_plugin_ops; |
126 |
|
|
|
127 |
|
|
|
128 |
|
|
#define PLUGIN_STRING_LENGTH 256 |
129 |
|
|
|
130 |
|
|
typedef struct file_info |
131 |
|
|
{ |
132 |
|
|
char name[PLUGIN_STRING_LENGTH]; // a nicer name for the file, zero-length if none |
133 |
|
|
char typedesc[PLUGIN_STRING_LENGTH]; // a description of the file |
134 |
|
|
char mimetype[PLUGIN_STRING_LENGTH]; // mimetype |
135 |
|
|
|
136 |
|
|
float samplerate; |
137 |
|
|
float bitrate; |
138 |
|
|
uint32 numchannels; |
139 |
|
|
uint32 granularity; // in frames |
140 |
|
|
uint32 framecount; |
141 |
|
|
uint32 samplesize; |
142 |
|
|
int32 byteorder; |
143 |
|
|
int32 sampleformat; |
144 |
|
|
|
145 |
|
|
uint64 flags; // various flags |
146 |
|
|
} file_info; |
147 |
|
|
|
148 |
|
|
|
149 |
|
|
/* |
150 |
|
|
These are the operations that can be performed on a particular instance |
151 |
|
|
of a filter-plugin, once it has been instantiated. |
152 |
|
|
The void* that each function gets as the first argument is the data pointer |
153 |
|
|
that was filled in by Instantiate_Plugin |
154 |
|
|
*/ |
155 |
|
|
|
156 |
|
|
typedef void op_filter_filechange(void*, const char *name, const char *path); |
157 |
|
|
typedef status_t op_filter_filter(void*, short *buffer,int32 framecount, void *info); |
158 |
|
|
typedef status_t op_filter_filter_float(void*, float **input, float **output, int32 framecount, void *info); |
159 |
|
|
typedef BView* op_filter_configure(void*); |
160 |
|
|
typedef void op_filter_setconfig(void*,BMessage *config); |
161 |
|
|
typedef void op_filter_getconfig(void*,BMessage *config); |
162 |
|
|
|
163 |
|
|
// The following structure contains pointers to the above |
164 |
|
|
// functions. Simply leave NULL if not implemented. |
165 |
|
|
|
166 |
|
|
typedef struct filter_plugin_ops |
167 |
|
|
{ |
168 |
|
|
// first some bookkeeping stuff |
169 |
|
|
uint32 ops_magic; // magic number |
170 |
|
|
uint32 ops_version; // version of this plugin structure |
171 |
|
|
|
172 |
|
|
// and the function pointers. |
173 |
|
|
op_filter_filechange (*FileChange); // leave NULL if not implemented |
174 |
|
|
op_filter_filter (*Filter); // filter a buffer of data, leave NULL if you implement FilterFloat |
175 |
|
|
op_filter_configure (*Configure); // leave NULL if no run-time config |
176 |
|
|
op_filter_setconfig (*SetConfig); // leave NULL if no run-time config |
177 |
|
|
op_filter_getconfig (*GetConfig); // leave NULL if no run-time config |
178 |
|
|
op_filter_filter_float (*FilterFloat); // filter floats, leave NULL if you implement Filter |
179 |
|
|
} filter_plugin_ops; |
180 |
|
|
|
181 |
|
|
// User Interface Plugin classes |
182 |
|
|
|
183 |
|
|
enum { |
184 |
|
|
FILTER_HOTKEYS = 1, |
185 |
|
|
FILTER_REFS = 2 |
186 |
|
|
}; |
187 |
|
|
|
188 |
|
|
enum { |
189 |
|
|
CONTROLLER_ADD = 'ct\0\1', |
190 |
|
|
CONTROLLER_REMOVE = 'ct\0\2', |
191 |
|
|
CONTROLLER_PLAYLISTEDITOR = 'ct\0\3' |
192 |
|
|
}; |
193 |
|
|
|
194 |
|
|
class SoundPlayController |
195 |
|
|
{ |
196 |
|
|
public: |
197 |
|
|
int32 Version(); // soundplay version, encoded like this: X.Y.Z -> 0x000XYZ00 |
198 |
|
|
const char *VersionString(); // version as a string, e.g. "3.2" |
199 |
|
|
|
200 |
|
|
void Quit(void); |
201 |
|
|
void DisableInterface(const char *id); |
202 |
|
|
void HideMainInterface(void); |
203 |
|
|
void ShowMainInterface(void); |
204 |
|
|
bool IsMainInterfaceHidden(void); |
205 |
|
|
|
206 |
|
|
// You must lock the controller object before doing anything |
207 |
|
|
// with its tracks, and unlock it afterwards |
208 |
|
|
// Note that as long as you have a PlaylistPtr for a playlist, |
209 |
|
|
// that playlist will remain valid. Its associated controls |
210 |
|
|
// might go away (i.e. the playlist gets removed from the controller), |
211 |
|
|
// but you can still work with the files in the playlist, or add it |
212 |
|
|
// to the controller again. |
213 |
|
|
void Lock(void); |
214 |
|
|
void Unlock(void); |
215 |
|
|
uint32 CountPlaylists(void); |
216 |
|
|
PlaylistPtr PlaylistAt(uint32 index); |
217 |
|
|
PlaylistPtr AddPlaylist(); // create a new playlist+controls |
218 |
|
|
status_t AddPlaylist(PlaylistPtr playlist); // add an existing playlist to the controller |
219 |
|
|
status_t RemovePlaylist(PlaylistPtr playlist); |
220 |
|
|
void OpenEditor(PlaylistPtr playlist); |
221 |
|
|
|
222 |
|
|
void AddWindow(BWindow*, int32 filterflags=FILTER_HOTKEYS|FILTER_REFS); // tell SoundPlay about your window(s) so that SP can do some hotkey-management for it and accept dropped files |
223 |
|
|
status_t AddListener(BHandler *handler); |
224 |
|
|
status_t RemoveListener(BHandler *handler); |
225 |
|
|
|
226 |
|
|
// plugins can use these functions to store and retrieve preferences as BMessages |
227 |
|
|
status_t StorePreference(const char *name, const BMessage *message); |
228 |
|
|
status_t RetrievePreference(const char *name, BMessage *message); |
229 |
|
|
|
230 |
|
|
private: |
231 |
|
|
#ifdef CONTROLLER_SECRET_INNER_WORKINGS |
232 |
|
|
CONTROLLER_SECRET_INNER_WORKINGS |
233 |
|
|
#endif |
234 |
|
|
}; |
235 |
|
|
|
236 |
|
|
|
237 |
|
|
typedef status_t op_ui_show(void*); |
238 |
|
|
typedef void op_ui_hide(void*); |
239 |
|
|
typedef void op_ui_setconfig(void*,BMessage *config); |
240 |
|
|
typedef void op_ui_getconfig(void*,BMessage *config); |
241 |
|
|
|
242 |
|
|
// send a message with this constant to SoundPlay to enable |
243 |
|
|
// an interface. Specify the interface by adding a string |
244 |
|
|
// called "interface" containing the plugin-id to the message. |
245 |
|
|
const uint32 ENABLE_INTERFACE= '!int'; |
246 |
|
|
|
247 |
|
|
typedef struct interface_plugin_ops |
248 |
|
|
{ |
249 |
|
|
// first some bookkeeping stuff |
250 |
|
|
uint32 ops_magic; // magic number |
251 |
|
|
uint32 ops_version; // version of this plugin structure |
252 |
|
|
|
253 |
|
|
op_ui_show (*Show); |
254 |
|
|
op_ui_hide (*Hide); |
255 |
|
|
op_ui_setconfig (*SetConfig); // leave NULL if not implemented |
256 |
|
|
op_ui_getconfig (*GetConfig); // leave NULL if not implemented |
257 |
|
|
} interface_plugin_ops; |
258 |
|
|
|
259 |
|
|
|
260 |
|
|
|
261 |
|
|
/* |
262 |
|
|
Typical sequence of events for a decoder plugin: |
263 |
|
|
- get_plugin_list is called to get the list of plugins in the imagefile |
264 |
|
|
(typically returns a single plugin_descriptor, but could return multiple) |
265 |
|
|
- plugin_descriptor::SupportedTypes is called to find the supported types and add them to the mime database |
266 |
|
|
- plugin_descriptor::Instantiate_Plugin is called to get a new decoder_plugin_ops |
267 |
|
|
if successful: |
268 |
|
|
- decoder_plugin_ops::Open is called to open the file |
269 |
|
|
- decoder_plugin_ops::Info is called to get information about the file |
270 |
|
|
- decoder_plugin_ops::Read is called to read data from the file -OR- decoder_plugin_ops::Play is called to start playback of a non data-producing file |
271 |
|
|
- decoder_plugin_ops::Seek/Position/etcetera get called multiple times during the playback |
272 |
|
|
- decoder_plugin_ops::Close is called to close the file |
273 |
|
|
- plugin_descriptor::Destroy_Plugin is called to free the plugin_ops structure |
274 |
|
|
*/ |
275 |
|
|
|
276 |
|
|
|
277 |
|
|
/* |
278 |
|
|
Typical sequence of events for a filter plugin: |
279 |
|
|
- get_plugin_list is called to get the list of plugins in the imagefile |
280 |
|
|
(typically returns a single plugin_descriptor, but could return multiple) |
281 |
|
|
- plugin_descriptor::Instantiate_Plugin is called to get a new filter_plugin_ops |
282 |
|
|
- filter_plugin_ops::SetConfig is called to set the configuration |
283 |
|
|
- filter_plugin_ops::Filter is called a number of times to filter buffers of data |
284 |
|
|
- plugin_descriptor::Destroy_Plugin is called to free the filter_plugin_ops structure |
285 |
|
|
*/ |
286 |
|
|
|
287 |
|
|
|
288 |
|
|
// These are the "magic values" used to recognize structures |
289 |
|
|
enum plugin_magic { |
290 |
|
|
PLUGIN_DESCRIPTOR_MAGIC='desc', |
291 |
|
|
PLUGIN_DECODER_MAGIC='inpt', |
292 |
|
|
PLUGIN_FILTER_MAGIC='filt', |
293 |
|
|
PLUGIN_VISUAL_MAGIC='visu', |
294 |
|
|
PLUGIN_INTERFACE_MAGIC='face', |
295 |
|
|
PLUGIN_PLAYLIST_MAGIC='edit' |
296 |
|
|
}; |
297 |
|
|
|
298 |
|
|
// The current version of the structures |
299 |
|
|
enum plugin_version { |
300 |
|
|
PLUGIN_DESCRIPTOR_VERSION=3, |
301 |
|
|
PLUGIN_DECODER_VERSION=3, |
302 |
|
|
PLUGIN_FILTER_VERSION=4, |
303 |
|
|
PLUGIN_VISUAL_VERSION=3, |
304 |
|
|
PLUGIN_INTERFACE_VERSION=4, |
305 |
|
|
PLUGIN_PLAYLIST_VERSION=4 |
306 |
|
|
}; |
307 |
|
|
|
308 |
|
|
|
309 |
|
|
// flags for the plugin descriptor structures |
310 |
|
|
enum plugin_type { |
311 |
|
|
PLUGIN_IS_DECODER=1, |
312 |
|
|
PLUGIN_IS_FILTER=2, |
313 |
|
|
PLUGIN_IS_VISUAL=4, |
314 |
|
|
PLUGIN_IS_INTERFACE=16, // old interface (8) was dropped after 3.6 |
315 |
|
|
PLUGIN_IS_SINGLE_CONTEXT=0x10000000 |
316 |
|
|
}; |
317 |
|
|
|
318 |
|
|
// The following are reported in file_info::flags |
319 |
|
|
const uint64 PLUGIN_POSITION_IS_RELATIVE |
320 |
|
|
=0x0000000200000000LL; // Seek() and Position() are not absolute positions, but |
321 |
|
|
// relative to whatever the plugin reported as framecount. |
322 |
|
|
// Setting this bit implies that playing backwards is not |
323 |
|
|
// possible. |
324 |
|
|
const uint64 PLUGIN_REQUIRES_CONTIGUOUS_PHYSICAL_MEMORY |
325 |
|
|
=0x0000000100000000LL; // plugin cannot load into memory consisting of |
326 |
|
|
// multiple areas. Should only be needed by plugins that |
327 |
|
|
// do DMA. Doesn't work well with relative positioning |
328 |
|
|
// or granularity!=1 |
329 |
|
|
|
330 |
|
|
const uint64 PLUGIN_MINIMAL_BUFFERING |
331 |
|
|
=0x0000000400000000LL; // do less read-ahead. Use this only for "realtime" data, e.g. |
332 |
|
|
// data captured live from an audio input |
333 |
|
|
|
334 |
|
|
const uint64 PLUGIN_FILELENGTH_UNKNOWN |
335 |
|
|
=0x0000000000000001LL; // same as CL-Amp's INPLUG_NO_TOTTIME |
336 |
|
|
const uint64 PLUGIN_NO_ELAPSEDTIME |
337 |
|
|
=0x0000000000000002LL; // same as CL-Amp's INPLUG_NO_CURRTIME |
338 |
|
|
|
339 |
|
|
#endif |
340 |
|
|
|