aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/ns/ext/atom/atom.ttl
blob: c28b6107be44f3936c1489fbcb560b4325aa368d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
# LV2 Atom Extension
# Copyright 2007-2012 David Robillard <d@drobilla.net>
#
# Permission to use, copy, modify, and/or distribute this software for any
# purpose with or without fee is hereby granted, provided that the above
# copyright notice and this permission notice appear in all copies.
#
# THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

@prefix atom: <http://lv2plug.in/ns/ext/atom#> .
@prefix doap: <http://usefulinc.com/ns/doap#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix lv2:  <http://lv2plug.in/ns/lv2core#> .
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

<http://lv2plug.in/ns/ext/atom>
	a lv2:Specification ;
	doap:name "LV2 Atom" ;
	doap:shortdesc "A generic value container and several data types." ;
	doap:license <http://opensource.org/licenses/isc> ;
	rdfs:seeAlso <atom-buffer.h> ;
	doap:release [
		doap:revision "0.3" ;
		doap:created "2012-01-28"
	] ;
	doap:maintainer [
		a foaf:Person ;
		foaf:name "David Robillard" ;
		foaf:homepage <http://drobilla.net/> ;
		rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
	] ;
	lv2:documentation """
<p>This extension defines a generic format for a typed piece of data, called an
lv2:Atom (e.g. integers, strings, buffers, data structures,
etc).  Atoms allow LV2 plugins and hosts to communicate, process, serialise,
and store values of any type via a generic mechanism (e.g. LV2 ports, events,
disk, shared memory, network).  Atoms are, with one exception, Plain
Old Data (POD) and may be safely copied (e.g. with a simple call to
<code>memcpy</code>).</p>

<p>Since Atom communication can be implemented generically, plugins that
understand some type can be used together in a host that does not understand
that type, and plugins (e.g. routers, delays) can process atoms of unknown
type.</p>

<p>An Atom can be trivially constructed in-place from an
<a href="http://lv2plug.in/ns/ext/event#Event">Event</a> as defined by the
<a href="http://lv2plug.in/ns/ext/event">LV2 Event</a> extension.  In other
words, an Event is simply an Atom with a time stamp header.  Atoms SHOULD
be used anywhere a "value" needs to be stored or communicated, to allow
implementations to be polymorphic and extensible.</p>

<p>Atoms (the start of the LV2_Atom header) MUST be 32-bit aligned.</p>

<p>Atoms can be communicated in many ways.  Since an Atom is the payload of an
Event, an <a href="http://lv2plug.in/ns/ext/event#EventPort">EventPort</a> can
be used for communicating Atoms in realtime with sub-sample time stamp
accuracy.  This extension also defines two port types for connecting directly
to a single Atom: atom:ValuePort and atom:MessagePort, which both have the same
buffer format but different semantics (with respect to how the run() callback
interprets the Atom).</p>

<p>Implementing this extension requires a facility for mapping URIs to
integers, such as the <a href="http://lv2plug.in/ns/ext/urid">LV2 URID</a>
extension.</p>
""" .

atom:Atom
	a rdfs:Class ;
	rdfs:label "Atom" ;
	atom:cType "LV2_Atom" ;
	lv2:documentation """
<p>Abstract base class for all atoms.  An LV2_Atom has a 32-bit
<code>type</code> and <code>size</code> followed by a <code>body</code> of
<code>size</code> bytes.</p>

<p>All concrete Atom types (subclasses of this class) MUST define a precise
binary layout for <code>body</code>.</p>

<p>The <code>type</code> field is the URI of a subclass of Atom mapped to an
integer using the <a href="http://lv2plug.in/ns/ext/uri-map">URI Map</a>
extension's LV2_URI_Map_Feature::uri_to_id() with
<code>map = "http://lv2plug.in/ns/ext/event"</code>.  If a plugin or host
does not understand <code>type</code>, that atom SHOULD be gracefully ignored
(or copied if it does not have type 0).</p>

<p>All atoms are POD by definition except references, which as a special case
have <code>type = 0</code>.  An Atom MUST NOT contain a Reference.  It is safe
to copy any non-reference Atom with a simple <code>memcpy</code>, even if the
implementation does not understand <code>type</code>.  Though this extension reserves
the type 0 for references, actual specification of how references are used is left
to another extension.</p>
""" .

atom:String
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "String" ;
	atom:cType "LV2_Atom_String" ;
	lv2:documentation """
<p>A UTF-8 encoded string.</p>

<p>The body of an LV2_Atom_String is a C string in UTF-8 encoding, i.e. an
array of bytes (<code>uint8_t</code>) terminated with a NULL byte
(<code>'\\0'</code>).</p>

<p>This type can be used for free-form strings, but in most cases it is better to
use atom:Literal since this supports a language tag or datatype.  Implementations
SHOULD NOT use atom:String unless translating the string does not make sense and
the string has no meaningful datatype.</p>
""" .

atom:Literal
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "String Literal" ;
	atom:cType "LV2_Atom_Literal" ;
	lv2:documentation """
<p>A UTF-8 encoded string literal, with an optional datatype or language.</p>

<p>This type is compatible with rdf:Literal and is capable of expressing a
string in any language, or a value of any type.  A Literal has a
<code>datatype</code> and <code>lang</code> followed by string data in UTF-8
encoding.  The length of the string data in bytes is <code>size -
sizeof(LV2_Atom_Literal)</code>, including the terminating NULL character.  The
<code>lang</code> field SHOULD be a URI of the form
&lt;http://lexvo.org/id/term/LANG&gt; where LANG is an <a
href="http://www.loc.gov/standards/iso639-2/">ISO 693-2</a> or <a
href="http://www.loc.gov/standards/iso639-2/">ISO 693-3</a> language code.</p>

<p>A Literal may have a <code>datatype</code> OR a <code>lang</code>, but never
both.</p>

<p>For example, a Literal can be "Hello" in English:</p>
<pre class="c-code">
void set_to_hello_in_english(LV2_Atom_Literal* lit) {
     lit->type     = map(expand("atom:Literal"));
     lit->size     = 14;
     lit->datatype = 0;
     lit->lang     = map("http://lexvo.org/id/term/en");
     memcpy(lit->str, "Hello", sizeof("Hello"));  // Assumes enough space
}
</pre>

<p>or a Turtle string:</p>
<pre class="c-code">
void set_to_turtle_string(LV2_Atom_Literal* lit, const char* ttl) {
     lit->type     = map(expand("atom:Literal"));
     lit->size     = 64;
     lit->datatype = map("http://www.w3.org/2008/turtle#turtle");
     lit->lang     = 0;
     memcpy(lit->str, ttl, strlen(ttl) + 1);  // Assumes enough space
}
</pre>
""" .

atom:URID
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "Integer ID mapped from a URI" ;
	atom:cType "LV2_Atom_ID" ;
	lv2:documentation """
<p>An unsigned 32-bit integer mapped from a URI using the <a
href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's
LV2_URI_Map_Feature::uri_to_id() with <code>map = NULL</code>.</p>
""" .

atom:BlankID
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "Integer ID for a blank node" ;
	atom:cType "LV2_Atom_ID" ;
	lv2:documentation """
<p>An unsigned 32-bit integer identifier for a blank node.  A BlankID is only
meaningful within a limited scope (e.g. the Atom in which it appears), and
MUST NOT be used as a global identifier.  In particular, a BlankID is NOT a
URID, and can not be mapped to/from a URI.</p>
""" .

atom:Vector
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "Vector" ;
	atom:cType "LV2_Atom_Vector" ;
	lv2:documentation """
<p>A homogeneous sequence of atoms with equivalent type and size.</p>

<p>An LV2_Atom_Vector is a 32-bit <code>elem_count</code> and
<code>elem_type</code> followed by <code>elem_count</code> atom bodies of type
<code>elem_type</code>.  The element type must be a fixed size atom:Atom type,
i.e. the size of each element is the vector's <code>size /
elem_count</code>.</p>

<p>For example, an atom:Vector containing 42 elements of type atom:Float:</p>
<pre class="c-code">
struct VectorOf42Floats {
    uint32_t type;        // map(expand("atom:Vector"))
    uint32_t size;        // sizeof(LV2_Atom_Vector) + (42 * sizeof(float);
    uint32_t elem_count;  // 42
    uint32_t elem_type;   // map(expand("atom:Float"))
    float    elems[32];
};
</pre>

<p>Note that it is possible to construct a valid Atom for each element
of the vector, even by an implementation which does not understand
<code>elem_type</code>.</p>
""" .

atom:Tuple
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "Tuple" ;
	lv2:documentation """
<p>A sequence of lv2:Atom with varying <code>type</code>
and <code>size</code>.</p>

<p>The body of a Tuple is simply a sequence of complete atoms, each aligned to
32 bits.</p>
""" .

atom:Thing
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "Thing" ;
	atom:cType "LV2_Thing" ;
	lv2:documentation """
<p>Abstract base class for a "Thing", i.e. an atom:Atom with a number of
properties.  An LV2_Object is an unsigned 32-bit integer <code>context</code>
and <code>id</code> followed by a sequence of LV2_Atom_Property .</p>

<p>The <code>context</code> is mapped using the <a
href="http://lv2plug.in/ns/ext/uri-map">URI Map</a> extension's
LV2_URI_Map_Feature::uri_to_id() with <code>map = NULL</code>, and may be 0
(the default context).</p>

<p>Note this is an abstract class, i.e. no Atom can exist with <code>type =
uri_to_id(atom:Thing)</code>.  An Object is either an atom:Resource or an
atom:Blank, but the <code>body</code> always has the same binary format,
LV2_Object.  Thus, both named and anonymous objects can be handled with common
code using only a 64-bit header for both.</p>
""" .

atom:Resource
	a rdfs:Class ;
	rdfs:subClassOf atom:Thing ;
	atom:cType "LV2_Thing" ;
	lv2:documentation """
<p>An atom:Thing where <code>id</code> is the URI of the resource mapped to an
atom:URID.</p>
""" .

atom:Blank
	a rdfs:Class ;
	rdfs:subClassOf atom:Thing ;
	atom:cType "LV2_Thing" ;
	lv2:documentation """
<p>An atom:Thing where <code>id</code> is the blank node ID of the object,
which is only meaningful within a certain limited scope (e.g. the container of
the Blank) and MUST NOT be used as a global ID.  In particular, <code>id</code>
is NOT a URID.</p>
""" .

atom:Message
	a rdfs:Class ;
	rdfs:subClassOf atom:Thing ;
	atom:cType "LV2_Thing" ;
	lv2:documentation """
<p>A atom:Thing where <code>id</code> is a message type ID.  Conceptually, a
Message is identical to a Blank, but is a distinct type with a single type
field to allow simple and fast dispatch by handling code.</p>

<p>A Message may be serialised as a Blank by adding an rdf:type property with
the value <code>id</code> unmapped to a URI.</p>
""" .

atom:Event
	a rdfs:Class ;
	rdfs:label "Event" ;
	atom:cType "LV2_Atom_Event" ;
	lv2:documentation """
<p>An atom with a time stamp header prepended, typically for sample accurate
transmission via LV2 ports.  See struct LV2_Atom_Event.</p>
""" .

atom:Bang
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "Bang (activity) (size = 0)" .

atom:Number
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "Number (abstract class)." .

atom:Int32
	a rdfs:Class ;
	rdfs:subClassOf atom:Number ;
	rdfs:label "Signed 32-bit integer" ;
	atom:cType "LV2_Atom_Int32" .

atom:Int64
	a rdfs:Class ;
	rdfs:subClassOf atom:Number ;
	rdfs:label "Signed 64-bit integer" ;
	atom:cType "LV2_Atom_Int64" .

atom:Bool
	a rdfs:Class ;
	rdfs:subClassOf atom:Atom ;
	rdfs:label "An atom:Int32 where 0 is false and all other values true" ;
	atom:cType "LV2_Atom_Int32" .

atom:Float
	a rdfs:Class ;
	rdfs:subClassOf atom:Number ;
	rdfs:label "32-bit IEEE-754 floating point number" ;
	atom:cType "LV2_Atom_Float" .

atom:Double
	a rdfs:Class ;
	rdfs:subClassOf atom:Number ;
	rdfs:label "64-bit IEEE-754 floating point number" ;
	atom:cType "LV2_Atom_Double" .

atom:blobSupport
	a lv2:Feature ;
	rdfs:label "Blob support" ;
	lv2:documentation """
<p>Support for dynamically allocated blobs.  If a host supports this feature,
it MUST pass a LV2_Feature with <code>URI</code>
http://lv2plug.in/ns/ext/atom#blobSupport and <code>data</code> pointing to a
LV2_Blob_Support.</p>
""" .

atom:AtomPort
	a rdfs:Class ;
	rdfs:subClassOf lv2:Port ;
	rdfs:label "Atom Port" ;
	lv2:documentation """
<p>A port which contains an lv2:Atom.  Ports of this type will
be connected to a 32-bit aligned LV2_Atom immediately followed by
<code>size</code> bytes of data.</p>

<p>This is an abstract port type, i.e. a port MUST NOT only be an AtomPort,
but must be a more descriptive type that is a subclass of AtomPort which
defines the port's semantics (typically atom:ValuePort or atom:MessagePort).
</p>

<p>Before calling a method on the plugin that writes to an AtomPort output,
the host MUST set the size of the Atom in that output to the amount of
available memory immediately following the Atom header.  The plugin MUST
write a valid Atom to that port (leaving it untouched is illegal).  If there
is no reasonable value to write to the port, the plugin MUST write NULL
(the Atom with both <code>type = 0</code> and <code>size = 0</code>).</p>
""" .

atom:ValuePort
	a rdfs:Class ;
	rdfs:subClassOf atom:AtomPort ;
	rdfs:label "Value Port" ;
	lv2:documentation """
<p>An AtomPort that interprets its data as a persistent and time-independent
"value".</p>
<ul>
<li>If a plugin has fixed input values for all ports, all ValuePort outputs
are also fixed regardless of the number of times the plugin is run.</li>
<li>If a plugin has fixed input values for all ports except a ValuePort,
each value V of that ValuePort corresponds to a single set of outputs
for all ports.</li>
<li>If a ValuePort contains a reference then the blob it refers to is
constant; plugin MUST NOT modify the blob in any way.</li>
</ul>
<p>Value ports can be thought of as purely functional ports: if a plugin
callback has only value ports, then the plugin callback is a pure function.</p>
""" .

atom:MessagePort
	a rdfs:Class ;
	rdfs:subClassOf atom:AtomPort ;
	rdfs:label "Message Port" ;
	rdfs:comment """
An AtomPort that "receives", "consumes", "executes", or "sends" its value.
The Atom contained in a MessagePort is considered transient and/or
time-dependent, and is only valid for a single run invocation.  Unlike a
ValuePort, a MessagePort may be used to manipulate internal plugin state.

Intuitively, a MessagePort contains a "message" or "command" or "event"
which is reacted to, NOT a "value" or "signal" (which is computed with).
""" .

atom:cType
	a rdf:Property ,
		owl:DatatypeProperty ;
	rdfs:label "C type" ;
	rdfs:domain rdfs:Class ;
	rdfs:range xsd:string ;
	rdfs:comment """
The identifier for a C type describing the in-memory representation of
an instance of this class.
""" .

atom:EventPort
	a rdfs:Class ;
	rdfs:label "Event port" ;
	rdfs:subClassOf lv2:Port ;
	lv2:documentation """
<p>A port used for communicating time-stamped atoms in the audio context.
Ports of this type are connected to an LV2_Atom_Buffer, which contains a flat
time-stamped sequence of atom:Event.</p>

<p>This port type is intended as a simpler and atom compatible successor to <a
href="http://lv2plug.in/ns/ext/event#EventPort">ev:EventPort</a>.</p>
""" .

atom:supports
	a rdf:Property ;
	rdfs:domain lv2:Port ;
	rdfs:range atom:Atom ;
	rdfs:label "supports" ;
	lv2:documentation """
<p>Indicates that a Port supports a certain atom:Atom type.  This is distinct from
the port type - e.g. the port type ValuePort can hold atoms with many different
types.  This property is used to describe which Atom types a Port expects to
receive or send.</p>
""" .