← Back to branch summary

~ubuntu-branches/ubuntu/hoary/kdemultimedia/hoary

« back to all changes in this revision

Viewing changes to arts/midi/artsmidi.idl

  • Committer: Bazaar Package Importer
  • Author(s): Martin Schulze
  • Date: 2003-01-22 15:00:51 UTC
  • Revision ID: james.westby@ubuntu.com-20030122150051-uihwkdoxf15mi1tn
Tags: upstream-2.2.2
Import upstream version 2.2.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
arts/midi/artsmidi.idl
 
1
        /*
 
2
 
 
3
    Copyright (C) 2000 Stefan Westerfeld
 
4
                       stefan@space.twc.de
 
5
 
 
6
    This library is free software; you can redistribute it and/or
 
7
    modify it under the terms of the GNU Library General Public
 
8
    License as published by the Free Software Foundation; either
 
9
    version 2 of the License, or (at your option) any later version.
 
10
  
 
11
    This library is distributed in the hope that it will be useful,
 
12
    but WITHOUT ANY WARRANTY; without even the implied warranty of
 
13
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
14
    Library General Public License for more details.
 
15
   
 
16
    You should have received a copy of the GNU Library General Public License
 
17
    along with this library; see the file COPYING.LIB.  If not, write to
 
18
    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 
19
    Boston, MA 02111-1307, USA.
 
20
 
 
21
    */
 
22
 
 
23
/*
 
24
 * DISCLAIMER: The interfaces in artsmidi.idl (and the derived .cc/.h files)
 
25
 *             DO NOT GUARANTEE BINARY COMPATIBILITY YET.
 
26
 *
 
27
 * They are intended for developers. You shouldn't expect that applications in
 
28
 * binary form will be fully compatibile with further releases of these
 
29
 * interfaces.
 
30
 */
 
31
 
 
32
module Arts {
 
33
 
 
34
/* This is modelled somewhat after
 
35
    - the AudioManager concept
 
36
        - the aRts-0.3.4.1 MidiPort concept
 
37
        - libkmid
 
38
 
 
39
   It adds timing as new feature compared to older implementation, and also
 
40
   tries to do the full set of midi operations.
 
41
 
 
42
   It's current state is "experimental", and "binary compatibility not kept".
 
43
 */
 
44
 
 
45
/**
 
46
 * an absolute timestamp
 
47
 */
 
48
struct TimeStamp {
 
49
        long sec,usec;
 
50
};
 
51
 
 
52
/**
 
53
 * different status of a midi command
 
54
 */
 
55
enum MidiCommandStatus {
 
56
// Masks:
 
57
        mcsCommandMask          = 0xf0,
 
58
        mcsChannelMask          = 0x0f,
 
59
 
 
60
// Commands:
 
61
        mcsNoteOff                      = 0x80,
 
62
        mcsNoteOn                       = 0x90,
 
63
        mcsKeyPressure          = 0xa0,
 
64
        mcsParameter            = 0xb0,
 
65
        mcsProgram                      = 0xc0,
 
66
        mcsChannelPressure      = 0xd0,
 
67
        mcsPitchWheel           = 0xe0
 
68
};
 
69
 
 
70
/**
 
71
 * the following are to be used once status is (mcsParameter|channel):
 
72
 */
 
73
enum MidiCommandParameter {
 
74
        mcpSustain                      = 0x40,
 
75
        mcpAllNotesOff          = 0x7b
 
76
};
 
77
 
 
78
/**
 
79
 * a midi command
 
80
 */
 
81
struct MidiCommand {
 
82
        byte status;
 
83
        byte data1;
 
84
        byte data2;
 
85
};
 
86
 
 
87
/**
 
88
 * a midi event
 
89
 */
 
90
 
 
91
struct MidiEvent {
 
92
        TimeStamp time;
 
93
        MidiCommand command;
 
94
};
 
95
 
 
96
/**
 
97
 * a midi port
 
98
 */
 
99
interface MidiPort {
 
100
        /**
 
101
         * the current absolute time (since the existence of the midi device)
 
102
         */
 
103
        readonly attribute TimeStamp time;
 
104
 
 
105
        /**
 
106
         * processes a midi command
 
107
         */
 
108
        oneway void processCommand(MidiCommand command);
 
109
 
 
110
        /**
 
111
         * processes a midi event
 
112
         */
 
113
        oneway void processEvent(MidiEvent event);
 
114
};
 
115
 
 
116
enum MidiClientDirection { mcdPlay, mcdRecord }; 
 
117
enum MidiClientType { mctDestination, mctApplication }; 
 
118
 
 
119
/**
 
120
 * information about a midi client
 
121
 */
 
122
struct MidiClientInfo {
 
123
        long ID;
 
124
        sequence<long> connections;
 
125
 
 
126
        MidiClientDirection direction;
 
127
        MidiClientType type;
 
128
        string title, autoRestoreID;
 
129
};
 
130
 
 
131
/**
 
132
 * a midi manager client
 
133
 */
 
134
interface MidiClient {
 
135
    readonly attribute MidiClientInfo info;
 
136
 
 
137
        /**
 
138
         * you can change the title of your client on the fly - everything else
 
139
         * (besides the actual assignment) is static
 
140
         */
 
141
    attribute string title;
 
142
 
 
143
        /**
 
144
         * creates a new port through which the client can receive data from
 
145
         * the midi manager
 
146
         */
 
147
        void addInputPort(MidiPort port);
 
148
 
 
149
        /**
 
150
         * creates a new port through which the client can send data to the
 
151
         * midi manager
 
152
         */
 
153
        MidiPort addOutputPort();
 
154
 
 
155
        /**
 
156
         * removes a port
 
157
         */
 
158
        void removePort(MidiPort port);
 
159
};
 
160
 
 
161
/**
 
162
 * Some general notes to the understanding of the midi manager. The midi
 
163
 * manager has the task to intelligently assign applications to destinations.
 
164
 *
 
165
 * It is important to understand what it actually does to understand the
 
166
 * distinction first, which is expressed through the "MidiClientType" of
 
167
 * each client.
 
168
 *
 
169
 * APPLICATIONS: An application is a user visible application, that produces
 
170
 *    or records midi data. It is important for the understanding of an
 
171
 *    application, that an application actually *wants* to be supplied with
 
172
 *    data, or wants to get its data played. Thus, adding an application to
 
173
 *    the midi manager is an implicit request: "go and find a place where to
 
174
 *    put the events to (or get the events from)".
 
175
 *
 
176
 *    Examples for applications would be games or midi players.
 
177
 *
 
178
 * DESTINATIONS: A destination is a system service that plays or supplies
 
179
 *    midi data. The characteristic here is that a destination is something
 
180
 *    that is there if you need it.
 
181
 *
 
182
 *    Examples for destinations might be might be a hardware device or an
 
183
 *    emulation of a hardware device (such as a virtual sampler).
 
184
 *
 
185
 * So the process is as follows:
 
186
 *  - destinations register themselves at the midi manager, and provide
 
187
 *    system services in that way
 
188
 *
 
189
 *  - when the user starts an application (such as a midi player), the midi
 
190
 *    manager's task is to assign it to a suitable destination
 
191
 *
 
192
 *  - the user can interact with the process by changing the way applications
 
193
 *    are assigned to destinations - the midi manager will try to learn
 
194
 *    what the user wants, and next time do a better job while assigning
 
195
 *
 
196
 * To actually record or play some data, you need to register a client first,
 
197
 * and after that, you can add Input or Output "MidiPort"s to your client,
 
198
 * so that you can actually send or receive events with them.
 
199
 */
 
200
interface MidiManager { // SINGLETON: Arts_MidiManager
 
201
    /**
 
202
     * a list of clients
 
203
     */
 
204
    readonly attribute sequence<MidiClientInfo> clients;
 
205
 
 
206
        /**
 
207
         * add a client
 
208
     *
 
209
         * this creates a new MidiManagerClient
 
210
         */ 
 
211
        MidiClient addClient(MidiClientDirection direction, MidiClientType type,
 
212
                                                        string title, string autoRestoreID);
 
213
 
 
214
        /**
 
215
         * connect two clients
 
216
         */
 
217
        void connect(long clientID, long destinationID);
 
218
 
 
219
        /**
 
220
         * disconnect two clients
 
221
         */
 
222
        void disconnect(long clientID, long destinationID);
 
223
};                                                                              
 
224
 
 
225
interface MidiTest : MidiPort {
 
226
};
 
227
 
 
228
interface RawMidiPort : MidiPort {
 
229
        attribute string device;
 
230
        attribute boolean input, output;
 
231
        attribute boolean running;
 
232
        boolean open();
 
233
};
 
234
 
 
235
/**
 
236
 * Midi Timer - can be used to provide timing for midi ports that have
 
237
 * no "native" timing.
 
238
 */
 
239
interface MidiTimer
 
240
{
 
241
        /**
 
242
         * the current time
 
243
         */
 
244
        readonly attribute TimeStamp time;
 
245
 
 
246
        /**
 
247
         * this will put the event into an event queue and send it to the port
 
248
         * once the time for the event has been reached
 
249
         */
 
250
        oneway void queueEvent(MidiPort port, MidiEvent event);
 
251
};
 
252
 
 
253
/**
 
254
 * Uses the system time (i.e. gettimeofday() and similar) to provide midi
 
255
 * timing
 
256
 */
 
257
interface SystemMidiTimer : MidiTimer
 
258
{
 
259
};
 
260
 
 
261
/**
 
262
 * Uses the audio time (i.e. samples rendered to /dev/dsp) to provide midi
 
263
 * timing
 
264
 */
 
265
interface AudioMidiTimer : MidiTimer
 
266
{
 
267
};
 
268
 
 
269
};