ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/cebix/SIDPlayer/src/soundplay_includes/pluginproto.h
Revision: 1.1
Committed: 2001-01-14T13:17:35Z (23 years, 6 months ago) by cebix
Content type: text/plain
Branch: MAIN
CVS Tags: HEAD
Log Message:
now also works as a SoundPlay plugin under BeOS

File Contents

# Content
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