# LV2 Buf Size

Access to, and restrictions on, buffer sizes.

ID | http://lv2plug.in/ns/ext/buf-size
Version | 1.4
Date | 2020-04-26
Discuss | devel@lists.lv2plug.in (subscribe)

- Index
- History
- API

This extension defines a facility for plugins to get information about the block length (the sample_count parameter of LV2_Descriptor::run) and port buffer sizes, as well as several features which can be used to restrict the block length.

This extension defines features and properties but has no special purpose API of its own. The host provides all the relevant information to the plugin as options.

To require restrictions on the block length, plugins can require additional features: boundedBlockLength, powerOf2BlockLength, and fixedBlockLength. These features are data-only, that is they merely indicate a restriction and do not carry any data or API.

## Index

Properties | Instances
--- | ---
maxBlockLength minBlockLength nominalBlockLength sequenceSize | boundedBlockLength coarseBlockLength fixedBlockLength powerOf2BlockLength

## Properties

### maxBlockLength

Property

Label | maximum block length
Range | xsd:nonNegativeInteger
Type | Datatype Property

Block length has an upper bound.

The maximum block length the host will ever request the plugin to process at once, that is, the maximum `sample_count` parameter that will ever be passed to LV2_Descriptor::run().

### minBlockLength

Property

Label | minimum block length
Range | xsd:nonNegativeInteger
Type | Datatype Property

Block length has a lower bound.

The minimum block length the host will ever request the plugin to process at once, that is, the minimum `sample_count` parameter that will ever be passed to LV2_Descriptor::run().

### nominalBlockLength

Property

Label | nominal block length
Range | xsd:nonNegativeInteger
Type | Datatype Property

Typical block length that will most often be processed.

The typical block length the host will request the plugin to process at once, that is, the typical `sample_count` parameter that will be passed to LV2_Descriptor::run(). This will usually be equivalent, or close to, the maximum block length, but there are no strong guarantees about this value whatsoever. Plugins may use this length for optimization purposes, but MUST NOT assume the host will always process blocks of this length. In particular, the host MAY process longer blocks.

### sequenceSize

Property

Label | sequence size
Range | xsd:nonNegativeInteger
Type | Datatype Property

The maximum size of a sequence, in bytes.

This should be provided as an option by hosts that support event ports (including but not limited to MIDI), so plugins have the ability to allocate auxiliary buffers large enough to copy the input.

## Instances

### boundedBlockLength

Instance

Label | bounded block length
Type | lv2:Feature

Block length has lower and upper bounds.

A feature that indicates the host will provide both the minBlockLength and maxBlockLength options to the plugin. Plugins that copy data from audio inputs can require this feature to ensure they know how much space is required for auxiliary buffers. Note the minimum may be zero, this feature is mainly useful to ensure a maximum is available.

All hosts SHOULD support this feature, since it is simple to support and necessary for any plugins that may need to copy the input.

### coarseBlockLength

Instance

Label | coarse block length
Type | lv2:Feature

Plugin prefers coarse block length without buffer splitting.

A feature that indicates the plugin prefers coarse, regular block lengths. For example, plugins that do not implement sample-accurate control use this feature to indicate that the host should not split the run cycle because controls have changed.

Note that this feature is merely a hint, and does not guarantee a fixed block length. The run cycle may be split for other reasons, and the blocksize itself may change anytime.

### fixedBlockLength

Instance

Label | fixed block length
Type | lv2:Feature

Block length never changes.

A feature that indicates the host will always call LV2_Descriptor::run() with the same value for sample_count. This length MUST be provided as the value of both the minBlockLength and maxBlockLength options.

Note that requiring this feature may severely limit the number of hosts capable of running the plugin.

### powerOf2BlockLength

Instance

Label | power of 2 block length
Type | lv2:Feature

Block length is a power of 2.

A feature that indicates the host will always call LV2_Descriptor::run() with a power of two sample_count. Note that this feature does not guarantee the value is the same each call, to guarantee a fixed power of two block length plugins must require both this feature and fixedBlockLength.

Note that requiring this feature may severely limit the number of hosts capable of running the plugin.

## History

Version 1.4 (2015-09-18)
  - Add bufsz:nominalBlockLength option.
  - Add bufsz:coarseBlockLength feature.
Version 1.2 (2012-12-21)
  - Fix typo in bufsz:sequenceSize label.
Version 1.0 (2012-10-14)
  - Initial release.