Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CLAP 1.2.0 #371

Merged
merged 100 commits into from
Jan 22, 2024
Merged
Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
100 commits
Select commit Hold shift + click to select a range
d5a81b9
Clarify the allowed usages of clap_plugin_entry's init() and deinit()
prokopyl Nov 28, 2023
2b5f760
Require plugins to support clap_plugin_entry's init() and deinit() be…
prokopyl Nov 28, 2023
b8c2e1d
require the plugin to be activated to get the latency
abique Nov 30, 2023
9a6e997
Implement entry init counter for the plugin template
abique Nov 30, 2023
0eb701a
Add some preprocessor checks before using threads.h
abique Nov 30, 2023
4e57e1f
msvc still doesn't know thread.h???
abique Nov 30, 2023
1e09a99
Let cmake find out if threads.h is available
abique Nov 30, 2023
80ed37b
Clean up active and processing state method labels in plugin.h
Trinitou Dec 5, 2023
d8b7bba
Merge pull request #367 from Trinitou/activeAndProcessingDocumentation
abique Dec 6, 2023
7300c18
Update referenced function name in comment
cubicvoid Dec 18, 2023
4c58070
Merge pull request #369 from cubicvoid/param-function-ref
abique Dec 18, 2023
3b79854
Expanded discussion of -1 wildcard note address mechanism
baconpaul Dec 18, 2023
12c6094
Address review feedback
baconpaul Dec 18, 2023
d865610
Merge pull request #370 from baconpaul/note-wildcards
abique Dec 20, 2023
8415273
Typo
abique Dec 20, 2023
bd62a29
Move extensions out of draft
abique Dec 20, 2023
1553a23
Update ChangeLog
abique Dec 20, 2023
9392788
ChangeLog update
abique Dec 20, 2023
4839565
Add a convention file for the extension id
abique Dec 20, 2023
252e9d7
Update the extension id convention
abique Dec 20, 2023
9029824
Update ChangeLog
abique Dec 20, 2023
73ee414
ChangeLog: fix typo
abique Dec 20, 2023
2d1ae7d
Various language fixes
abique Dec 20, 2023
6d59db2
Remove a TODO
abique Dec 20, 2023
f52dd86
This should be gone
abique Dec 20, 2023
56fa019
Expand a bit on the difference between init and create
baconpaul Dec 21, 2023
cd54084
Fix typo in conventions/extension-id.md
abique Dec 22, 2023
f17d956
Merge pull request #372 from baconpaul/expand-on-init
abique Dec 22, 2023
357f5bd
Move clap_plugin_id_t to its own file
abique Dec 22, 2023
992da92
Add a plugin state converter factory
abique Dec 22, 2023
c02f704
Update changelog
abique Dec 22, 2023
c306c1d
Missing include
abique Dec 22, 2023
b312b47
Update changelog as 1.1.11 was never released
abique Dec 22, 2023
b627a55
Update version.h to 1.2.0
abique Dec 22, 2023
b00a04e
Clarify that the extension's revision number should start at 1.
abique Dec 22, 2023
37bab41
Fix typedef and doc the return value
abique Dec 22, 2023
40bb780
Add error message to convert_state()
abique Dec 22, 2023
64addfb
Fix doc.
abique Dec 22, 2023
df6fc7b
Rework the plugin state converter
abique Dec 23, 2023
5e20b73
Include the state converter
abique Dec 23, 2023
71997ee
Update conventions/extension-id.md
abique Dec 23, 2023
29a0b08
Fix factory id identifier name
abique Dec 23, 2023
6f0a98e
added project load as explicit option
defiantnerd Dec 28, 2023
01296c4
changing state-context id to 'clap.state-context/2'
defiantnerd Dec 28, 2023
e8591df
do not include draft headers from clap.h
micahrj Jan 6, 2024
b9a6470
Merge pull request #375 from defiantnerd/next
abique Jan 8, 2024
aa670d1
Adjust state context's documentation
abique Jan 8, 2024
f5b0e68
Merge pull request #366 from prokopyl/entry-docs
abique Jan 8, 2024
ad76eb5
Update the documentation according to the latest discussions
abique Jan 8, 2024
863055d
Remove check for update extension
abique Jan 8, 2024
52552c5
Merge pull request #378 from abique/remove-check-for-update
abique Jan 8, 2024
5cdb92c
Remove midi mapping extension
abique Jan 8, 2024
a44b93b
Rework the extension list in the readme
abique Jan 8, 2024
dfcd4b5
Merge branch 'next' into draft-includes
abique Jan 8, 2024
06d6c85
Merge pull request #377 from glowcoil/draft-includes
abique Jan 8, 2024
e11e63b
Finish the exclusion of drafts from `clap.h`
abique Jan 8, 2024
190771a
Remove the cv ext
abique Jan 8, 2024
cbe6b6b
Update remaining drafts to use the new convention for extension id
abique Jan 8, 2024
a898dee
Update include/clap/entry.h
abique Jan 10, 2024
56f7f36
Update include/clap/entry.h
abique Jan 10, 2024
fb4937c
Update include/clap/entry.h
abique Jan 10, 2024
d850a7c
Update include/clap/entry.h
abique Jan 10, 2024
ea9cecf
Make ambisonic stable
abique Jan 10, 2024
12ca18f
Add a note regarding the extension id containing draft
abique Jan 10, 2024
3aa3165
Remove draft from the extension id
abique Jan 12, 2024
42a9ee2
Update changelog
abique Jan 12, 2024
abcd29b
Update preset-discovery extension id to follow the convention.
abique Jan 12, 2024
522e69d
Missing deprecation notice
abique Jan 12, 2024
17e1b52
Update ChangeLog.md
abique Jan 13, 2024
11ef4a1
Update conventions/extension-id.md
abique Jan 13, 2024
5373d31
Update include/clap/ext/remote-controls.h
abique Jan 13, 2024
5c52b38
Update extension-id.md
abique Jan 13, 2024
4e7622d
Merge pull request #379 from abique/1.2.0/ext-id-cleanup
abique Jan 15, 2024
fa2beac
Missed ext id cleanup
abique Jan 15, 2024
0fc394f
Expand some note and note expression doc
baconpaul Jan 15, 2024
a0f6859
small tweak
baconpaul Jan 15, 2024
1e41950
Update changelog per abique request
baconpaul Jan 15, 2024
f25dded
Merge pull request #381 from baconpaul/ne-doc
abique Jan 15, 2024
b237186
Expand note expression tuning description just a bit
baconpaul Jan 15, 2024
5652063
Merge pull request #382 from baconpaul/more-tuning
abique Jan 15, 2024
c52aeb2
Typo
abique Jan 15, 2024
f45f18c
Cleanups for state context so we're compat with pre 1.2.0
abique Jan 15, 2024
dd97ce3
Missing ID cleanup for ambisonic
abique Jan 16, 2024
a8b3f1e
state-context: we changed the enum values so no COMPAT here
abique Jan 16, 2024
71f05a7
doc
abique Jan 16, 2024
955046c
Add clarifications regarding foreign plugin id
abique Jan 16, 2024
583177d
Leave a note regarding endianness
abique Jan 16, 2024
498af28
Make the example code more robust
abique Jan 16, 2024
c53c0a7
Specify how to format foreign plugin id
abique Jan 17, 2024
43d80c5
use "type:subt:manu"
abique Jan 17, 2024
fd83c02
Rename clap_plugin_id_t to clap_universal_plugin_id_t
abique Jan 17, 2024
5e25da6
Add CLAP_CONSTEXPR to voice-info and preset-load id declarations
baconpaul Jan 17, 2024
03acdaa
Move clap_timestamp_t definition to separate header
Trinitou Jan 18, 2024
897dac4
Rename timestamp typedef to be consistent with clap_id etc.
Trinitou Jan 18, 2024
2ed82ac
Merge pull request #384 from baconpaul/missing-constexpr
abique Jan 18, 2024
2a98bd9
Merge pull request #385 from Trinitou/move-and_rename-timestamp
abique Jan 18, 2024
6055daa
Document null-terminated string members of clap_universal_plugin_id
Trinitou Jan 18, 2024
19a640b
Merge pull request #387 from Trinitou/document-null-termination
abique Jan 18, 2024
7feb350
Polish the plugin state converter
abique Jan 19, 2024
a470662
It is all.h, not draft.h
abique Jan 19, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ add_custom_target(clap-tests)

if (${CLAP_BUILD_TESTS})
message(STATUS "Including CLAP tests, compile tests, and versions")
include(CheckIncludeFile)

macro(clap_compile_cpp SUFFIX EXT STDC STDCPP)
add_executable(clap-compile-${SUFFIX} EXCLUDE_FROM_ALL src/main.${EXT})
Expand Down Expand Up @@ -84,11 +85,17 @@ if (${CLAP_BUILD_TESTS})
clap_compile_cpp(cpp17 cc 17 17)
clap_compile_cpp(cpp20 cc 17 20)

check_include_file(threads.h CLAP_HAS_THREADS_H)

add_library(clap-plugin-template MODULE EXCLUDE_FROM_ALL src/plugin-template.c)
target_link_libraries(clap-plugin-template PRIVATE clap)
set_target_properties(clap-plugin-template PROPERTIES C_STANDARD 11)
add_dependencies(clap-tests clap-plugin-template)

if(CLAP_HAS_THREADS_H)
target_compile_definitions(clap-plugin-template PRIVATE CLAP_HAS_THREADS_H)
endif()

if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
target_link_libraries(clap-plugin-template PRIVATE -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/src/linux-my_plug.version)
target_link_libraries(clap-plugin-template PRIVATE -Wl,-z,defs)
Expand Down
41 changes: 41 additions & 0 deletions ChangeLog.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,44 @@
# Changes in 1.2.0

## Stabilize extensions

* `CLAP_EXT_AUDIO_PORTS_ACTIVATION`
* `CLAP_EXT_CONFIGURABLE_AUDIO_PORTS`
* `CLAP_EXT_CONTEXT_MENU`
* `CLAP_EXT_PARAM_INDICATION`
* `CLAP_EXT_PRESET_LOAD`
* `CLAP_EXT_REMOTE_CONTROLS`
* `CLAP_EXT_STATE_CONTEXT`
* `CLAP_EXT_SURROUND`
* `CLAP_EXT_TRACK_INFO`

Note: we kept the last draft extension ID in order to not break plugin already using it.
abique marked this conversation as resolved.
Show resolved Hide resolved

## Stabilize factory
* `CLAP_PRESET_DISCOVERY_FACTORY_ID`

Note: we kept the last draft factory ID in order to not break plugin already using it.
abique marked this conversation as resolved.
Show resolved Hide resolved

## Documentation

* [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works
* [plugin.h](include/clap/plugin.h): Style cleanup
* [params.h](include/clap/ext/params.h): Fix incorrect function name reference
* [latency.h](include/clap/ext/latency.h): Precise that the latency can only be fetched when the plugin is activated
abique marked this conversation as resolved.
Show resolved Hide resolved

## Conventions

* [extension-id](conventions/extension-id.md): introduce some rules about extension ID naming.

## Plugin Template

* [plugin-template.c](src/plugin-template.c): Add exemple code for safer clap entry initialization
abique marked this conversation as resolved.
Show resolved Hide resolved

# Changes in 1.1.11

* [latency.h](include/clap/ext/latency.h): require the plugin to be activated to get the latency
* [plugin-template.c](src/plugin-template.c): implement thread-safe entry init counter

# Changes in 1.1.10

* [params.h](include/clap/ext/params.h): add `CLAP_PARAM_IS_ENUM` flag.
Expand Down
30 changes: 30 additions & 0 deletions conventions/extension-id.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Extension ID

## Naming

The extension shall be named in the form: `clap.$NAME/$REV`.
Where:
- `$NAME` is the name of the exension.
- `$REV` is the revision of the extension. This is an integer that is incremented for each iteration.

For extensions made by third-parties and not officially published by the CLAP project, please use the following form: `$REVERSE_URI.$NAME/$REV`.
Where:
- `$REVERSE_URI` would be something like `com.bitwig`.

## Draft

An extension is considered a draft extension if it is in the [draft](../include/clap/ext/draft/) folder.

When the extension is migrating from draft to stable, its extension ID must not change.

All extensions must go first though a draft phase.
abique marked this conversation as resolved.
Show resolved Hide resolved

## For factory ID

Everything about the extension id simetrically applies to factory id.
abique marked this conversation as resolved.
Show resolved Hide resolved

## History

Before this document was written, existing extension didn't honor those rules.
Some stable extension include the string `draft` in their ID.
We decided to keep those in order to maintain the binary compatibility.
abique marked this conversation as resolved.
Show resolved Hide resolved
21 changes: 11 additions & 10 deletions include/clap/clap.h
Original file line number Diff line number Diff line change
Expand Up @@ -28,44 +28,45 @@
#include "entry.h"

#include "factory/plugin-factory.h"
#include "factory/preset-discovery.h"

#include "factory/draft/plugin-invalidation.h"
#include "factory/draft/preset-discovery.h"

#include "plugin.h"
#include "plugin-features.h"
#include "host.h"

#include "ext/audio-ports-activation.h"
#include "ext/audio-ports-config.h"
#include "ext/audio-ports.h"
#include "ext/configurable-audio-ports.h"
#include "ext/context-menu.h"
#include "ext/event-registry.h"
#include "ext/gui.h"
#include "ext/latency.h"
#include "ext/log.h"
#include "ext/note-name.h"
#include "ext/note-ports.h"
#include "ext/param-indication.h"
#include "ext/params.h"
#include "ext/posix-fd-support.h"
#include "ext/preset-load.h"
#include "ext/remote-controls.h"
#include "ext/render.h"
#include "ext/state-context.h"
#include "ext/state.h"
#include "ext/surround.h"
#include "ext/tail.h"
#include "ext/thread-check.h"
#include "ext/thread-pool.h"
#include "ext/timer-support.h"
#include "ext/track-info.h"
#include "ext/voice-info.h"

#include "ext/draft/ambisonic.h"
#include "ext/draft/audio-ports-activation.h"
#include "ext/draft/context-menu.h"
#include "ext/draft/cv.h"
#include "ext/draft/midi-mappings.h"
#include "ext/draft/param-indication.h"
#include "ext/draft/preset-load.h"
#include "ext/draft/remote-controls.h"
#include "ext/draft/resource-directory.h"
#include "ext/draft/state-context.h"
#include "ext/draft/surround.h"
#include "ext/draft/track-info.h"
#include "ext/draft/triggers.h"
#include "ext/draft/tuning.h"
#include "ext/draft/configurable-audio-ports.h"
#include "ext/draft/extensible-audio-ports.h"
39 changes: 35 additions & 4 deletions include/clap/events.h
Original file line number Diff line number Diff line change
Expand Up @@ -117,9 +117,37 @@ enum {
};

// Note on, off, end and choke events.
//
// Clap addresses notes and voices using the 4-value tuple
// (port, channel, key, note_id). Note on/off/end/choke
// events and parameter modulation messages are delivered with
// these values populated.
//
// Values in a note and voice address are either >= 0 if they
// are specified, or -1 to indicate a wildcard. A wildcard
// means a voice with any value in that part of the tuple
// matches the message.
//
// For instance, a (PCKN) of (0, 3, -1, -1) will match all voices
// on channel 3 of port 0. And a PCKN of (-1, 0, 60, -1) will match
// all channel 0 key 60 voices, independent of port or note id.
//
// Especially in the case of note-on note-off pairs, and in the
// absence of voice stacking or polyphonic modulation, a host may
// choose to issue a note id only at note on. So you may see a
// message stream like
//
// CLAP_EVENT_NOTE_ON [0,0,60,184]
// CLAP_EVENT_NOTE_OFF [0,0,60,-1]
//
// and the host will expect the first voice to be released.
// Well constructed plugins will search for voices and notes using
// the entire tuple.
//
// In the case of note choke or end events:
// - the velocity is ignored.
// - key and channel are used to match active notes, a value of -1 matches all.
// - key and channel are used to match active notes
// - note_id is optionally provided by the host
typedef struct clap_event_note {
clap_event_header_t header;

Expand Down Expand Up @@ -153,7 +181,8 @@ typedef struct clap_event_note_expression {

clap_note_expression expression_id;

// target a specific note_id, port, key and channel, -1 for global
// target a specific note_id, port, key and channel, with
// -1 meaning wildcard, per the wildcard discussion above
int32_t note_id;
int16_t port_index;
int16_t channel;
Expand All @@ -169,7 +198,8 @@ typedef struct clap_event_param_value {
clap_id param_id; // @ref clap_param_info.id
void *cookie; // @ref clap_param_info.cookie

// target a specific note_id, port, key and channel, -1 for global
// target a specific note_id, port, key and channel, with
// -1 meaning wildcard, per the wildcard discussion above
int32_t note_id;
int16_t port_index;
int16_t channel;
Expand All @@ -185,7 +215,8 @@ typedef struct clap_event_param_mod {
clap_id param_id; // @ref clap_param_info.id
void *cookie; // @ref clap_param_info.cookie

// target a specific note_id, port, key and channel, -1 for global
// target a specific note_id, port, key and channel, with
// -1 meaning wildcard, per the wildcard discussion above
int32_t note_id;
int16_t port_index;
int16_t channel;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#pragma once

#include "../../plugin.h"
#include "../plugin.h"

/// @page Audio Ports Activation
///
Expand Down
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

static CLAP_CONSTEXPR const char CLAP_EXT_CONFIGURABLE_AUDIO_PORTS[] = "clap.configurable-audio-ports.draft1";
refers still to "draft"

Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#pragma once

#include "../audio-ports.h"
#include "audio-ports.h"

#ifdef __cplusplus
extern "C" {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#pragma once

#include "../../plugin.h"
#include "../plugin.h"

// This extension lets the host and plugin exchange menu items and let the plugin ask the host to
// show its context menu.
Expand Down
2 changes: 1 addition & 1 deletion include/clap/ext/latency.h
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ extern "C" {
// The audio ports scan has to be done while the plugin is deactivated.
abique marked this conversation as resolved.
Show resolved Hide resolved
typedef struct clap_plugin_latency {
// Returns the plugin latency in samples.
// [main-thread]
// [main-thread & active]
uint32_t(CLAP_ABI *get)(const clap_plugin_t *plugin);
} clap_plugin_latency_t;

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#pragma once

#include "../params.h"
#include "../../color.h"
#include "params.h"
#include "../color.h"

// This extension lets the host tell the plugin to display a little color based indication on the
// parameter. This can be used to indicate:
Expand Down
2 changes: 1 addition & 1 deletion include/clap/ext/params.h
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
/// The plugin is responsible for keeping its audio processor and its GUI in sync.
///
/// The host can at any time read parameters' value on the [main-thread] using
/// @ref clap_plugin_params.value().
/// @ref clap_plugin_params.get_value().
///
/// There are two options to communicate parameter value changes, and they are not concurrent.
/// - send automation points during clap_plugin.process()
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#pragma once

#include "../../plugin.h"
#include "../plugin.h"

static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/2";

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#pragma once

#include "../../plugin.h"
#include "../../string-sizes.h"
#include "../plugin.h"
#include "../string-sizes.h"

// This extension let the plugin provide a structured way of mapping parameters to an hardware
// controller.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#pragma once

#include "../../plugin.h"
#include "../../stream.h"
#include "../plugin.h"
#include "../stream.h"

/// @page state-context extension
/// @brief extended state handling
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#pragma once

#include "../../plugin.h"
#include "../plugin.h"

// This extension can be used to specify the channel mapping used by the plugin.
//
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
#pragma once

#include "../../plugin.h"
#include "../../color.h"
#include "../../string-sizes.h"
#include "../plugin.h"
#include "../color.h"
#include "../string-sizes.h"

// This extension let the plugin query info about the track it's in.
// It is useful when the plugin is created, to initialize some parameters (mix, dry, wet)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@

#pragma once

#include "../../private/std.h"
#include "../../private/macros.h"
#include "../../version.h"
#include "../private/std.h"
#include "../private/macros.h"
#include "../version.h"

// Use it to retrieve const clap_preset_discovery_factory_t* from
// clap_plugin_entry.get_factory()
Expand Down
12 changes: 6 additions & 6 deletions include/clap/plugin.h
Original file line number Diff line number Diff line change
Expand Up @@ -60,35 +60,35 @@ typedef struct clap_plugin {
// the [min, max] range, which is bounded by [1, INT32_MAX].
// Once activated the latency and port configuration must remain constant, until deactivation.
// Returns true on success.
// [main-thread & !active_state]
// [main-thread & !active]
bool(CLAP_ABI *activate)(const struct clap_plugin *plugin,
double sample_rate,
uint32_t min_frames_count,
uint32_t max_frames_count);
// [main-thread & active_state]
// [main-thread & active]
void(CLAP_ABI *deactivate)(const struct clap_plugin *plugin);

// Call start processing before processing.
// Returns true on success.
// [audio-thread & active_state & !processing_state]
// [audio-thread & active & !processing]
bool(CLAP_ABI *start_processing)(const struct clap_plugin *plugin);

// Call stop processing before sending the plugin to sleep.
// [audio-thread & active_state & processing_state]
// [audio-thread & active & processing]
void(CLAP_ABI *stop_processing)(const struct clap_plugin *plugin);

// - Clears all buffers, performs a full reset of the processing state (filters, oscillators,
// envelopes, lfo, ...) and kills all voices.
// - The parameter's value remain unchanged.
// - clap_process.steady_time may jump backward.
//
// [audio-thread & active_state]
// [audio-thread & active]
void(CLAP_ABI *reset)(const struct clap_plugin *plugin);

// process audio, events, ...
// All the pointers coming from clap_process_t and its nested attributes,
// are valid until process() returns.
// [audio-thread & active_state & processing_state]
// [audio-thread & active & processing]
clap_process_status(CLAP_ABI *process)(const struct clap_plugin *plugin,
const clap_process_t *process);

Expand Down
Loading