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, 9 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

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