From aeebfa8cf21973833f9bd4a6191f2e95dbf87109 Mon Sep 17 00:00:00 2001 From: David Robillard 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/lv2plug.in/ns/ext') 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 #include -#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 #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 ; lv2:documentation """ -

An extension that allows LV2 plugins to request a resize of an output -port.

+

This extension defines a feature, rsz:resize, which allows plugins to +dynamically resize their output port buffers.

-

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.

+

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.

+""" . + +rsz:resize + a lv2:Feature ; + lv2:documentation """ +

A feature to resize output port buffers in LV2_Plugin_Descriptor::run().

-

This extension also defines several predicates useful for describing the -amount of space required for a particular port buffer.

+

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.

""" . 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 """ +

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).

-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. +

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.

""" . 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