# LV2 Atom Port Extension
# Copyright (C) 2010 David Robillard <d@drobilla.net>
# 
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
# 
# The above copyright notice and this permission notice shall be included
# in all copies or substantial portions of the Software.
# 
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
# OTHER DEALINGS IN THE SOFTWARE.

@prefix aport: <http://lv2plug.in/ns/ext/atom-port#> .
@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 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-port>
	a lv2:Specification ;
    doap:name "LV2 Atom Port" ;
    doap:maintainer [
        a foaf:Person ;
        foaf:name     "David Robillard" ;
        foaf:homepage <http://drobilla.net/> ;
        rdfs:seeAlso  <http://drobilla.net/drobilla.rdf>
    ] ;
	rdfs:comment """
This extension describes port types that hold polymorphic values
(<a href="http://lv2plug.in/ns/ext/atom#Atom">atom:Atom</a>).  There are
two such port types with equivalent buffer formats but different semantics:
value ports (aport:ValuePort) and message ports (aport:MessagePort).
""" .


aport:AtomPort a rdfs:Class ;
    rdfs:label      "Atom Port" ;
    rdfs:subClassOf lv2:Port ;
    rdfs:comment    """
A port which contains a polymorphic value, or "atom".
Ports of this type will be connected to a 32-bit aligned <a
href="http://lv2plug.in/ns/ext/atom#Atom">atom:Atom</a> (i.e. a uint32_t type,
immediately followed by a uint32_t size, immediately followed by that many
bytes of data).

This is an abstract port type.  A port that is a aport:AtomPort MUST also
have a more descriptive type that is a subClassOf aport:AtomPort which
defines the port's semantics (typically aport:ValuePort or aport:MessagePort).

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 type and size equal to zero).
""" .


#aport:respondsWith a rdf:Property ;
#    rdfs:domain  aport:MessagePort ;
#    rdfs:range   lv2:Symbol ;
#    rdfs:label   "responds with" ;
#    rdfs:comment """
#Indicates that a message port responds to messages via the port with the
#given symbol on the same plugin instance.  If
#<pre>input aport:respondsWith output</pre> then after running the plugin with
#a message <em>m</em> in <code>input</code> the host SHOULD interpret the aport:
#in <code>output</code> as the response to <em>m</em>.
#""" .


aport:ValuePort a rdfs:Class ;
    rdfs:label      "Value Port" ;
    rdfs:subClassOf aport:AtomPort ;
    rdfs:comment    """
An AtomPort that interprets its data as a persistent and time-independent
"value".
<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 an aport:ValuePort contains a reference then the blob it refers to is
constant; plugin MUST NOT modify the blob in any way.</li>
</ul>
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.
""" .


aport:MessagePort a rdfs:Class ;
    rdfs:label      "Message Port" ;
    rdfs:subClassOf aport:AtomPort ;
    rdfs:comment    """
An AtomPort that consumes or executes its value as a "message".  The contents
of a MessagePort are considered transient and/or time-dependent, and only
apply for a single run invocation.  Unlike a ValuePort, a MessagePort may
be used to manipulate and access internal plugin state.

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

aport:supports a rdf:Property ;
	rdfs:domain  lv2:Port ;
	rdfs:range   atom:AtomType ;
	rdfs:label   "supports" ;
	rdfs:comment """
Indicates that an atom port supports a certain value 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 ``understands''.
""" .