From: Robin Gareus Date: Wed, 5 Oct 2016 02:38:08 +0000 (+0200) Subject: update lua class doc X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=32de311e4e18a06c21c5613578f4e590bef34b71;p=ardour-manual-diverged update lua class doc --- diff --git a/_manual/24_lua-scripting/02_class_reference.html b/_manual/24_lua-scripting/02_class_reference.html index d5f530c..01ec712 100644 --- a/_manual/24_lua-scripting/02_class_reference.html +++ b/_manual/24_lua-scripting/02_class_reference.html @@ -605,7 +605,7 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C Constructor ℂARDOUR.BackendVector () Methods - LuaTableadd (LuaTable {ARDOUR::AudioBackendInfo* }) + LuaTableadd (ARDOUR::AudioBackendInfo* ) AudioBackendInfoat (unsigned long) boolempty () LuaIteriter () @@ -1111,13 +1111,16 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C Constructor ℂARDOUR.LuaAPI.Vamp (std::string, float) Methods - intanalyze (Readable, unsigned int, --MISSING (luabridge::LuaRef)--) + intanalyze (Readable, unsigned int, Lua-Function) +

high-level abstraction to process a single channel of the given Readable.

If the plugin is not yet initialized, initialize() is called.

if is not nil, it is called with the immediate Vamp::Plugin::Features on every process call.

r
readable
channel
channel to process
fn
lua callback function

Returns 0 on success

boolinitialize () -

initialize the plugin for use with analyze().

This is equivalent to plugin():initialise (1, 8192, 8192) and prepares a plugin for analyze.

Manual initialization is only required to set plugin-parameters which depend on prior initialization of the plugin.

 vamp:reset ()
+

initialize the plugin for use with analyze().

This is equivalent to plugin():initialise (1, 512, 1024) and prepares a plugin for analyze.

Manual initialization is only required to set plugin-parameters which depend on prior initialization of the plugin.

 vamp:reset ()
  vamp:initialize ()
- vamp:plugin():setParameter (0, 1.5)
+ vamp:plugin():setParameter (0, 1.5, nil)
  vamp:analyze (r, 0)
- Pluginplugin () + Pluginplugin () + FeatureSetprocess (FloatArrayVector, RealTime) +

process given array of audio-samples.

This is a lua-binding for vamp:plugin():process ()

d
audio-data, the vector must match the configured channel count and hold a complete buffer for every channel as set during plugin():initialise()
rt
timestamp matching the provided buffer.

Returns features extracted from that data (if the plugin is causal)

voidreset ()

call plugin():reset() and clear intialization flag

@@ -1511,9 +1514,13 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C ℂEvoral.ParameterDescriptor () Data Members floatlower +

Minimum value (in Hz, for frequencies)

floatnormal +

Default value

booltoggled +

True iff parameter is boolean

floatupper +

Maximum value (in Hz, for frequencies)

 ARDOUR:PeakMeter

C‡: boost::shared_ptr< ARDOUR::PeakMeter >, boost::weak_ptr< ARDOUR::PeakMeter >

@@ -3064,7 +3071,7 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C - +
Methods
std::stringhttp_get (std::string)
ProcessorVectorprocessor_selection (--MISSING (lua_State*)--)
ProcessorVectorprocessor_selection ()

 ArdourUI:ArdourMarker

C‡: ArdourMarker

@@ -3083,7 +3090,7 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C Constructor ℂArdourUI.ArdourMarkerList () Methods - LuaTableadd (LuaTable {ArdourMarker* }) + LuaTableadd (ArdourMarker* ) boolempty () LuaIteriter () voidpush_back (ArdourMarker) @@ -3109,6 +3116,7 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C voiddeselect_all () LuaTable(...)do_embed (StringVector, ImportDisposition, ImportMode, long&, PluginInfo) LuaTable(...)do_import (StringVector, ImportDisposition, ImportMode, SrcQuality, long&, PluginInfo) +

Import existing media

booldragging_playhead ()

Returns true if the playhead is currently being dragged, otherwise false

MouseModeeffective_mouse_mode () @@ -3199,7 +3207,7 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C Constructor ℂArdourUI.ArdourMarkerList () Methods - LuaTableadd (LuaTable {ArdourMarker* }) + LuaTableadd (ArdourMarker* ) boolempty () LuaIteriter () voidpush_back (ArdourMarker) @@ -3313,6 +3321,21 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C boolsameinstance (FloatArray) voidset_table (LuaTable {float}) +

 C:FloatArrayVector

+

C‡: std::vector<float* >

+
+ + + + + + + + + + + +
Constructor
C.FloatArrayVector ()
Methods
LuaTableadd (LuaTable {FloatArray})
FloatArrayat (unsigned long)
boolempty ()
LuaIteriter ()
voidpush_back (FloatArray)
unsigned longsize ()
LuaTabletable ()

 C:FloatVector

C‡: std::vector<float >

@@ -3431,6 +3454,7 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C voidscale (double, double)

Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by sx and sy respectively. The scaling of the axes takes place after any existing transformation of user space.

sx
scale factor for the X dimension
sy
scale factor for the Y dimension
voidset_dash (DoubleVector, double) +

Sets the dash pattern to be used by stroke(). A dash pattern is specified by dashes, an array of positive values. Each value provides the user-space length of altenate "on" and "off" portions of the stroke. The offset specifies an offset into the pattern at which the stroke begins.

Each "on" segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an "on" length of 0.0 with Cairo::LINE_CAP_ROUND or Cairo::LINE_CAP_SQUARE in order to distributed dots or squares along a path.

Note: The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of set_dash().

If dashes is empty dashing is disabled. If the size of dashes is 1, a symmetric pattern is assumed with alternating on and off portions of the size specified by the single value in dashes.

It is invalid for any value in dashes to be negative, or for all values to be 0. If this is the case, an exception will be thrown

dashes
an array specifying alternate lengths of on and off portions
offset
an offset into the dash pattern at which the stroke should start
voidset_font_size (double)

Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with set_font_size() or set_font_matrix(). This results in a font size of size user space units. (More precisely, this matrix will result in the font's em-square being a by size square in user space.)

If text is drawn without a call to set_font_size(), (nor set_font_matrix() nor set_scaled_font()), the default font size is 10.0.

size
the new font size, in user space units)
voidset_line_cap (LineCap) @@ -3611,9 +3635,13 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C ℂEvoral.ParameterDescriptor () Data Members floatlower +

Minimum value (in Hz, for frequencies)

floatnormal +

Default value

booltoggled +

True iff parameter is boolean

floatupper +

Maximum value (in Hz, for frequencies)

 Evoral:Range

C‡: Evoral::Range<long>

@@ -3632,7 +3660,7 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C Constructor ℂLuaSignal.Set () Methods - LuaTableadd (LuaTable {47ul}) + LuaTableadd (47ul) boolany () unsigned longcount () boolnone () @@ -3870,168 +3898,233 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C ℂTimecode.BBT_TIME (unsigned int, unsigned int, unsigned int)

 Vamp:Plugin

-

C‡: _VampPlugin::Vamp::Plugin

+

C‡: Vamp::Plugin

is-a: Vamp:PluginBase

+

Vamp::Plugin is a base class for plugin instance classes that provide feature extraction from audio or related data.

In most cases, the input will be audio and the output will be a stream of derived data at a lower sampling resolution than the input.

Note that this class inherits several abstract methods from PluginBase. These must be implemented by the subclass.

PLUGIN LIFECYCLE

Feature extraction plugins are managed differently from real-time plugins (such as VST effects). The main difference is that the parameters for a feature extraction plugin are configured before the plugin is used, and do not change during use.

1. Host constructs the plugin, passing it the input sample rate. The plugin may do basic initialisation, but should not do anything computationally expensive at this point. You must make sure your plugin is cheap to construct, otherwise you'll seriously affect the startup performance of almost all hosts. If you have serious initialisation to do, the proper place is in initialise() (step 5).

2. Host may query the plugin's available outputs.

3. Host queries programs and parameter descriptors, and may set some or all of them. Parameters that are not explicitly set should take their default values as specified in the parameter descriptor. When a program is set, the parameter values may change and the host will re-query them to check.

4. Host queries the preferred step size, block size and number of channels. These may all vary depending on the parameter values. (Note however that you cannot make the number of distinct outputs dependent on parameter values.)

5. Plugin is properly initialised with a call to initialise. This fixes the step size, block size, and number of channels, as well as all of the parameter and program settings. If the values passed in to initialise do not match the plugin's advertised preferred values from step 4, the plugin may refuse to initialise and return false (although if possible it should accept the new values). Any computationally expensive setup code should take place here.

6. Host finally checks the number of values, resolution, extents etc per output (which may vary depending on the number of channels, step size and block size as well as the parameter values).

7. Host will repeatedly call the process method to pass in blocks of input data. This method may return features extracted from that data (if the plugin is causal).

8. Host will call getRemainingFeatures exactly once, after all the input data has been processed. This may return any non-causal or leftover features.

9. At any point after initialise was called, the host may optionally call the reset method and restart processing. (This does not mean it can change the parameters, which are fixed from initialise until destruction.)

A plugin does not need to handle the case where setParameter or selectProgram is called after initialise has been called. It's the host's responsibility not to do that. Similarly, the plugin may safely assume that initialise is called no more than once.

- - + +
Methods
FeatureSetgetRemainingFeatures ()
FeatureSetprocess (--MISSING (float**)--, RealTime)
FeatureSetgetRemainingFeatures ()

After all blocks have been processed, calculate and return any remaining features derived from the complete input.

Inherited from Vamp:PluginBase

- - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + +
Methods
std::stringgetCopyright ()
std::stringgetCurrentProgram ()
std::stringgetDescription ()
std::stringgetIdentifier ()
std::stringgetMaker ()
std::stringgetName ()
floatgetParameter (std::string)
ParameterListgetParameterDescriptors ()
intgetPluginVersion ()
StringVectorgetPrograms ()
std::stringgetType ()
voidselectProgram (std::string)
voidsetParameter (std::string, float)
std::stringgetCopyright ()

Get the copyright statement or licensing summary for the plugin. This can be an informative text, without the same presentation constraints as mentioned for getMaker above.

std::stringgetCurrentProgram ()

Get the current program.

std::stringgetDescription ()

Get a human-readable description for the plugin, typically a line of text that may optionally be displayed in addition to the plugin's "name". May be empty if the name has said it all already.

Example: "Detect and count zero crossing points"

std::stringgetIdentifier ()

Get the computer-usable name of the plugin. This should be reasonably short and contain no whitespace or punctuation characters. It may only contain the characters [a-zA-Z0-9_-]. This is the authoritative way for a program to identify a plugin within a given library.

This text may be visible to the user, but it should not be the main text used to identify a plugin to the user (that will be the name, below).

Example: "zero_crossings"

std::stringgetMaker ()

Get the name of the author or vendor of the plugin in human-readable form. This should be a short identifying text, as it may be used to label plugins from the same source in a menu or similar.

std::stringgetName ()

Get a human-readable name or title of the plugin. This should be brief and self-contained, as it may be used to identify the plugin to the user in isolation (i.e. without also showing the plugin's "identifier").

Example: "Zero Crossings"

floatgetParameter (std::string)

Get the value of a named parameter. The argument is the identifier field from that parameter's descriptor.

ParameterListgetParameterDescriptors ()

Get the controllable parameters of this plugin.

intgetPluginVersion ()

Get the version number of the plugin.

StringVectorgetPrograms ()

Get the program settings available in this plugin. A program is a named shorthand for a set of parameter values; changing the program may cause the plugin to alter the values of its published parameters (and/or non-public internal processing parameters). The host should re-read the plugin's parameter values after setting a new program.

The programs must have unique names.

std::stringgetType ()

Get the type of plugin. This is to be implemented by the immediate subclass, not by actual plugins. Do not attempt to implement this in plugin code.

voidselectProgram (std::string)

Select a program. (If the given program name is not one of the available programs, do nothing.)

voidsetParameter (std::string, float)

Set a named parameter. The first argument is the identifier field from that parameter's descriptor.

 Vamp:Plugin:Feature

-

C‡: _VampPlugin::Vamp::Plugin::Feature

+

C‡: Vamp::Plugin::Feature

+ + + + + +
Data Members
Vamp:RealTimeduration

Duration of the output feature. This is mandatory if the output has VariableSampleRate or FixedSampleRate and hasDuration is true, and unused otherwise.

boolhasDuration

True if an output feature has a specified duration. This is optional if the output has VariableSampleRate or FixedSampleRate, and and unused if the output has OneSamplePerStep.

boolhasTimestamp

True if an output feature has its own timestamp. This is mandatory if the output has VariableSampleRate, optional if the output has FixedSampleRate, and unused if the output has OneSamplePerStep.

std::stringlabel

Label for the sample of this feature.

Vamp:RealTimetimestamp

Timestamp of the output feature. This is mandatory if the output has VariableSampleRate or if the output has FixedSampleRate and hasTimestamp is true, and unused otherwise.

C:FloatVectorvalues

Results for a single sample of this feature. If the output hasFixedBinCount, there must be the same number of values as the output's binCount count.

 Vamp:Plugin:FeatureList

-

C‡: std::vector<_VampPlugin::Vamp::Plugin::Feature >

+

C‡: std::vector<Vamp::Plugin::Feature >

- - + + - - + +
Constructor
Vamp.Plugin.FeatureList ()
Methods
LuaTableadd (LuaTable {Feature})
Featureat (unsigned long)
boolempty ()
Featureat (unsigned long)
boolempty ()
LuaIteriter ()
voidpush_back (Feature)
unsigned longsize ()
voidpush_back (Feature)
unsigned longsize ()
LuaTabletable ()

 Vamp:Plugin:FeatureSet

-

C‡: std::map<int, std::vector<_VampPlugin::Vamp::Plugin::Feature > > > >

+

C‡: std::map<int, std::vector<Vamp::Plugin::Feature > > > >

- - - + + + - +
Constructor
Vamp.Plugin.FeatureSet ()
Methods
LuaTableadd (LuaTable {Feature})
voidclear ()
unsigned longcount (int)
boolempty ()
voidclear ()
unsigned longcount (int)
boolempty ()
LuaIteriter ()
unsigned longsize ()
unsigned longsize ()
LuaTabletable ()

 Vamp:Plugin:OutputDescriptor

-

C‡: _VampPlugin::Vamp::Plugin::OutputDescriptor

+

C‡: Vamp::Plugin::OutputDescriptor

+ + + + + + + + + + + - + + + +
Data Members
unsigned longbinCount

The number of values per result of the output. Undefined if hasFixedBinCount is false. If this is zero, the output is point data (i.e. only the time of each output is of interest, the value list will be empty).

C:StringVectorbinNames

The (human-readable) names of each of the bins, if appropriate. This is always optional.

std::stringdescription

A human-readable short text describing the output. May be empty if the name has said it all already. Example: "The number of zero crossing points per processing block"

boolhasDuration

True if the returned results for this output are known to have a duration field.

boolhasFixedBinCount

True if the output has the same number of values per sample for every output sample. Outputs for which this is false are unlikely to be very useful in a general-purpose host.

boolhasKnownExtents

True if the results in each output bin fall within a fixed numeric range (minimum and maximum values). Undefined if binCount is zero.

std::stringidentifier

The name of the output, in computer-usable form. Should be reasonably short and without whitespace or punctuation, using the characters [a-zA-Z0-9_-] only. Example: "zero_crossing_count"

boolisQuantized

True if the output values are quantized to a particular resolution. Undefined if binCount is zero.

floatmaxValue

Maximum value of the results in the output. Undefined if hasKnownExtents is false or binCount is zero.

floatminValue

Minimum value of the results in the output. Undefined if hasKnownExtents is false or binCount is zero.

floatquantizeStep

Quantization resolution of the output values (e.g. 1.0 if they are all integers). Undefined if isQuantized is false or binCount is zero.

floatsampleRate
_VampPlugin.Vamp.Plugin.OutputDescriptor.SampleTypesampleType

Sample rate of the output results, as samples per second. Undefined if sampleType is OneSamplePerStep.

If sampleType is VariableSampleRate and this value is non-zero, then it may be used to calculate a resolution for the output (i.e. the "duration" of each sample, in time, will be 1/sampleRate seconds). It's recommended to set this to zero if that behaviour is not desired.

Vamp.Plugin.OutputDescriptor.SampleTypesampleType

Positioning in time of the output results.

std::stringunit

The unit of the output, in human-readable form.

 Vamp:Plugin:OutputList

-

C‡: std::vector<_VampPlugin::Vamp::Plugin::OutputDescriptor >

+

C‡: std::vector<Vamp::Plugin::OutputDescriptor >

- - + + - - + +
Constructor
Vamp.Plugin.OutputList ()
Methods
LuaTableadd (LuaTable {OutputDescriptor})
OutputDescriptorat (unsigned long)
boolempty ()
OutputDescriptorat (unsigned long)
boolempty ()
LuaIteriter ()
voidpush_back (OutputDescriptor)
unsigned longsize ()
voidpush_back (OutputDescriptor)
unsigned longsize ()
LuaTabletable ()

 Vamp:PluginBase

-

C‡: _VampPlugin::Vamp::PluginBase

-
- - - - - - - - - - - - - - - +

C‡: Vamp::PluginBase

+
+

A base class for plugins with optional configurable parameters, programs, etc. The Vamp::Plugin is derived from this, and individual Vamp plugins should derive from that.

This class does not provide the necessary interfaces to instantiate or run a plugin. It only specifies an interface for retrieving those controls that the host may wish to show to the user for editing. It could meaningfully be subclassed by real-time plugins or other sorts of plugin as well as Vamp plugins.

+
Methods
std::stringgetCopyright ()
std::stringgetCurrentProgram ()
std::stringgetDescription ()
std::stringgetIdentifier ()
std::stringgetMaker ()
std::stringgetName ()
floatgetParameter (std::string)
ParameterListgetParameterDescriptors ()
intgetPluginVersion ()
StringVectorgetPrograms ()
std::stringgetType ()
voidselectProgram (std::string)
voidsetParameter (std::string, float)
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Methods
std::stringgetCopyright ()

Get the copyright statement or licensing summary for the plugin. This can be an informative text, without the same presentation constraints as mentioned for getMaker above.

std::stringgetCurrentProgram ()

Get the current program.

std::stringgetDescription ()

Get a human-readable description for the plugin, typically a line of text that may optionally be displayed in addition to the plugin's "name". May be empty if the name has said it all already.

Example: "Detect and count zero crossing points"

std::stringgetIdentifier ()

Get the computer-usable name of the plugin. This should be reasonably short and contain no whitespace or punctuation characters. It may only contain the characters [a-zA-Z0-9_-]. This is the authoritative way for a program to identify a plugin within a given library.

This text may be visible to the user, but it should not be the main text used to identify a plugin to the user (that will be the name, below).

Example: "zero_crossings"

std::stringgetMaker ()

Get the name of the author or vendor of the plugin in human-readable form. This should be a short identifying text, as it may be used to label plugins from the same source in a menu or similar.

std::stringgetName ()

Get a human-readable name or title of the plugin. This should be brief and self-contained, as it may be used to identify the plugin to the user in isolation (i.e. without also showing the plugin's "identifier").

Example: "Zero Crossings"

floatgetParameter (std::string)

Get the value of a named parameter. The argument is the identifier field from that parameter's descriptor.

ParameterListgetParameterDescriptors ()

Get the controllable parameters of this plugin.

intgetPluginVersion ()

Get the version number of the plugin.

StringVectorgetPrograms ()

Get the program settings available in this plugin. A program is a named shorthand for a set of parameter values; changing the program may cause the plugin to alter the values of its published parameters (and/or non-public internal processing parameters). The host should re-read the plugin's parameter values after setting a new program.

The programs must have unique names.

std::stringgetType ()

Get the type of plugin. This is to be implemented by the immediate subclass, not by actual plugins. Do not attempt to implement this in plugin code.

voidselectProgram (std::string)

Select a program. (If the given program name is not one of the available programs, do nothing.)

voidsetParameter (std::string, float)

Set a named parameter. The first argument is the identifier field from that parameter's descriptor.

 Vamp:PluginBase:ParameterDescriptor

-

C‡: _VampPlugin::Vamp::PluginBase::ParameterDescriptor

+

C‡: Vamp::PluginBase::ParameterDescriptor

+ + + + + + + + + +
Data Members
floatdefaultValue

The default value of the parameter. The plugin should ensure that parameters have this value on initialisation (i.e. the host is not required to explicitly set parameters if it wants to use their default values).

std::stringdescription

A human-readable short text describing the parameter. May be empty if the name has said it all already.

std::stringidentifier

The name of the parameter, in computer-usable form. Should be reasonably short, and may only contain the characters [a-zA-Z0-9_-].

boolisQuantized

True if the parameter values are quantized to a particular resolution.

floatmaxValue

The maximum value of the parameter.

floatminValue

The minimum value of the parameter.

std::stringname

The human-readable name of the parameter.

floatquantizeStep

Quantization resolution of the parameter values (e.g. 1.0 if they are all integers). Undefined if isQuantized is false.

std::stringunit

The unit of the parameter, in human-readable form.

C:StringVectorvalueNames

Names for the quantized values. If isQuantized is true, this may either be empty or contain one string for each of the quantize steps from minValue up to maxValue inclusive. Undefined if isQuantized is false.

If these names are provided, they should be shown to the user in preference to the values themselves. The user may never see the actual numeric values unless they are also encoded in the names.

 Vamp:PluginBase:ParameterList

-

C‡: std::vector<_VampPlugin::Vamp::PluginBase::ParameterDescriptor >

+

C‡: std::vector<Vamp::PluginBase::ParameterDescriptor >

- - + + - - + +
Constructor
Vamp.PluginBase.ParameterList ()
Methods
LuaTableadd (LuaTable {ParameterDescriptor})
ParameterDescriptorat (unsigned long)
boolempty ()
ParameterDescriptorat (unsigned long)
boolempty ()
LuaIteriter ()
voidpush_back (ParameterDescriptor)
unsigned longsize ()
voidpush_back (ParameterDescriptor)
unsigned longsize ()
LuaTabletable ()

 Vamp:RealTime

-

C‡: _VampPlugin::Vamp::RealTime

+

C‡: Vamp::RealTime

+

RealTime represents time values to nanosecond precision with accurate arithmetic and frame-rate conversion functions.

- - - + + + + + + + + +
Constructor
Vamp.RealTime (int, int)
Methods
intmsec ()
std::stringtoString ()
intusec ()
RealTimeframe2RealTime (long, unsigned int)
intmsec ()
longrealTime2Frame (RealTime, unsigned int)
std::stringtoString ()

Return a human-readable debug-type string to full precision (probably not a format to show to a user directly)

intusec ()
Data Members
intnsec
intsec

Enum/Constants

 PBD.Controllable.GroupControlDisposition

@@ -4060,7 +4153,7 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C
  • Evoral.InterpolationStyle.Linear
  • Evoral.InterpolationStyle.Curved
  • -

     _VampPlugin.Vamp.Plugin.OutputDescriptor.SampleType

    +

     Vamp.Plugin.OutputDescriptor.SampleType

    - +
    -
    Ardour 5.4-3-g2607e15  -  Mon, 03 Oct 2016 04:29:09 +0200
    +
    Ardour 5.4-25-gb233a56  -  Wed, 05 Oct 2016 04:37:46 +0200