From aeebfa8cf21973833f9bd4a6191f2e95dbf87109 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Mon, 16 Apr 2012 21:49:16 +0000
Subject: Make feature URI distinct from extension URI. Add return status
enumeration. Improve documentation.
---
lv2/lv2plug.in/ns/ext/resize-port/resize-port.h | 52 ++++++++++++++---------
lv2/lv2plug.in/ns/ext/resize-port/resize-port.ttl | 52 +++++++++++++----------
2 files changed, 60 insertions(+), 44 deletions(-)
(limited to 'lv2')
diff --git a/lv2/lv2plug.in/ns/ext/resize-port/resize-port.h b/lv2/lv2plug.in/ns/ext/resize-port/resize-port.h
index c1419e6..fa3abd7 100644
--- a/lv2/lv2plug.in/ns/ext/resize-port/resize-port.h
+++ b/lv2/lv2plug.in/ns/ext/resize-port/resize-port.h
@@ -20,7 +20,12 @@
#include <stddef.h>
#include <stdint.h>
-#define LV2_RESIZE_PORT_URI "http://lv2plug.in/ns/ext/resize-port"
+#define LV2_RESIZE_PORT_URI "http://lv2plug.in/ns/ext/resize-port"
+#define LV2_RESIZE_PORT_PREFIX LV2_RESIZE_PORT_URI "#"
+
+#define LV2_RESIZE_PORT__asLargeAs LV2_RESIZE_PORT_PREFIX "asLargeAs"
+#define LV2_RESIZE_PORT__minimumSize LV2_RESIZE_PORT_PREFIX "minimumSize"
+#define LV2_RESIZE_PORT__resize LV2_RESIZE_PORT_PREFIX "resize"
#ifdef __cplusplus
extern "C" {
@@ -28,31 +33,36 @@ extern "C" {
# include <stdbool.h>
#endif
+/** A status code for state functions. */
+typedef enum {
+ LV2_RESIZE_PORT_SUCCESS = 0, /**< Completed successfully. */
+ LV2_RESIZE_PORT_ERR_UNKNOWN = 1, /**< Unknown error. */
+ LV2_RESIZE_PORT_ERR_NO_SPACE = 2 /**< Insufficient space. */
+} LV2_Resize_Port_Status;
+
typedef void* LV2_Resize_Port_Feature_Data;
typedef struct {
LV2_Resize_Port_Feature_Data data;
- /** Resize a port buffer to at least @a size bytes.
- *
- * This function MAY return false, in which case the port buffer was
- * not resized and the port is still connected to the same location.
- * Plugins MUST gracefully handle this situation.
- *
- * This function MUST NOT be called from any context other than
- * the context associated with the port of the given index.
- *
- * The host MUST preserve the contents of the port buffer when
- * resizing.
- *
- * Plugins MAY resize a port many times in a single run callback.
- * Hosts SHOULD make this an inexpensive as possible (i.e. plugins
- * can liberally use this function in a similar way to realloc).
- */
- bool (*resize_port)(LV2_Resize_Port_Feature_Data data,
- uint32_t index,
- size_t size);
-} LV2_Resize_Port_Feature;
+ /**
+ Resize a port buffer to at least @a size bytes.
+
+ This function MAY return an error, in which case the port buffer was not
+ resized and the port is still connected to the same location. Plugins
+ MUST gracefully handle this situation.
+
+ This function is in the audio threading class.
+
+ The host MUST preserve the contents of the port buffer when resizing.
+
+ Plugins MAY resize a port many times in a single run callback. Hosts
+ SHOULD make this as inexpensive as possible.
+ */
+ LV2_Resize_Port_Status (*resize)(LV2_Resize_Port_Feature_Data data,
+ uint32_t index,
+ size_t size);
+} LV2_Resize_Port_Resize;
#ifdef __cplusplus
} /* extern "C" */
diff --git a/lv2/lv2plug.in/ns/ext/resize-port/resize-port.ttl b/lv2/lv2plug.in/ns/ext/resize-port/resize-port.ttl
index 0c77d00..5f5c73e 100644
--- a/lv2/lv2plug.in/ns/ext/resize-port/resize-port.ttl
+++ b/lv2/lv2plug.in/ns/ext/resize-port/resize-port.ttl
@@ -17,17 +17,23 @@
doap:created "2007-00-00" ;
doap:developer <http://drobilla.net/drobilla#me> ;
lv2:documentation """
-<p>An extension that allows LV2 plugins to request a resize of an output
-port.</p>
+<p>This extension defines a feature, rsz:resize, which allows plugins to
+dynamically resize their output port buffers.</p>
-<p>Any host which supports this extension must pass an LV2_Feature to the
-plugin's instantiate method with URI http://lv2plug.in/ns/ext/resize-port and a
-pointer to a LV2_Resize_Port_Feature structure. This structure provides a
-resize_port function which plugins may use to resize output port buffers as
-necessary.</p>
+<p>In addition to the dynamic feature, there are properties which describe the
+space required for a particular port buffer which can be used statically in
+data files.</p>
+""" .
+
+rsz:resize
+ a lv2:Feature ;
+ lv2:documentation """
+<p>A feature to resize output port buffers in LV2_Plugin_Descriptor::run().</p>
-<p>This extension also defines several predicates useful for describing the
-amount of space required for a particular port buffer.</p>
+<p>To support this feature, the host must pass an LV2_Feature to the plugin's
+instantiate method with URI LV2_RESIZE_PORT__resize and a pointer to a
+LV2_Resize_Port_Resize structure. This structure provides a resize_port
+function which plugins may use to resize output port buffers as necessary.</p>
""" .
rsz:asLargeAs
@@ -36,17 +42,17 @@ rsz:asLargeAs
rdfs:domain lv2:Port ;
rdfs:range lv2:Symbol ;
rdfs:label "as large as" ;
- rdfs:comment """
-Indicates that a port requires at least as much buffer space as the port
-with the given symbol on the same plugin instance. This may be used for
-any ports, but is generally most useful to indicate an output port must
-be at least as large as some input port (because it will copy from it).
-If a port is asLargeAs several ports, it is asLargeAs the largest such port
-(not the sum of those ports' sizes).
+ lv2:documentation """
+<p>Indicates that a port requires at least as much buffer space as the port
+with the given symbol on the same plugin instance. This may be used for any
+ports, but is generally most useful to indicate an output port must be at least
+as large as some input port (because it will copy from it). If a port is
+asLargeAs several ports, it is asLargeAs the largest such port (not the sum of
+those ports' sizes).</p>
-The host guarantees that whenever an ObjectPort's run method is called,
-any output O that is obj:asLargeAs an input I is connected to a buffer large
-enough to copy I, or NULL if the port is lv2:connectionOptional.
+<p>The host guarantees that whenever an ObjectPort's run method is called, any
+output O that is obj:asLargeAs an input I is connected to a buffer large enough
+to copy I, or NULL if the port is lv2:connectionOptional.</p>
""" .
rsz:minimumSize
@@ -57,9 +63,9 @@ rsz:minimumSize
rdfs:range xsd:nonNegativeInteger ;
rdfs:label "minimum size" ;
rdfs:comment """
-Indicates that a port requires a buffer at least this large, in bytes.
-Any host that supports the resize-port feature MUST connect any port with a
-minimumSize specified to a buffer at least as large as the value given for
-this property. Any host, especially those that do NOT support dynamic port
+Indicates that a port requires a buffer at least this large, in bytes. Any
+host that supports the resize-port feature MUST connect any port with a
+minimumSize specified to a buffer at least as large as the value given for this
+property. Any host, especially those that do NOT support dynamic port
resizing, SHOULD do so or reduced functionality may result.
""" .
--
cgit v1.2.1