Expand description
Rust bindings for libpd.
This crate is not meant to be used directly, but rather as a dependency of libpd-rs.
Support
-
Desktop
- macOS:
x86_64✅aarch64✅
- linux:
x86_64✅aarch64✅
- windows:
- msvc
x86_64✅aarch64(not tested but should work)
- gnu
x86_64(not tested but should work)aarch64(not tested but should work)
- msvc
- macOS:
-
Mobile
- iOS (not yet but will be addressed)
- Android (not yet but will be addressed)
-
Web (not yet but will be addressed)
Contribute
There is always room for more testing and improvement on build.rs. If you’re interested PRs are open.
Or if you wish you can add support for the unsupported platforms.
Structs
simple lock-free ring buffer implementation for one writer thread and one consumer thread
Constants
Statics
Functions
add a double to the current message in progress note: only full-precision when compiled with PD_FLOATSIZE=64
add a float to the current message in progress
add a symbol to the current message in progress
add a path to the libpd search paths relative paths are relative to the current working directory unlike desktop pd, no search paths are set by default (ie. extra)
send a MIDI after touch message to [touchin] objects channel is 0-indexed and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port returns 0 on success or -1 if an argument is out of range
get the size of an array by name returns size or negative error code if non-existent
send a bang to a destination receiver ex: libpd_bang(“foo”) will send a bang to [s foo] on the next tick returns 0 on success or -1 if receiver name is non-existent
subscribe to messages sent to a source receiver ex: libpd_bind(“foo”) adds a “virtual” [r foo] which forwards messages to the libpd message hooks returns an opaque receiver pointer or NULL on failure
return pd’s fixed block size: the number of sample frames per 1 pd tick
clear the libpd search path for abstractions and externals note: this is called by libpd_init()
close a patch by patch handle pointer
send a MIDI control change message to [ctlin] objects channel is 0-indexed, controller is 0-127, and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port returns 0 on success or -1 if an argument is out of range
send a double to a destination receiver ex: libpd_double(“foo”, 1.1) will send a 1.1 to [s foo] on the next tick note: only full-precision when compiled with PD_FLOATSIZE=64 returns 0 on success or -1 if receiver name is non-existent
check if a source receiver object exists with a given name returns 1 if the receiver exists, otherwise 0
finish current message and send as a list to a destination receiver returns 0 on success or -1 if receiver name is non-existent ex: send [list 1 2 bar( to [s foo] on the next tick with: libpd_start_message(3); libpd_add_float(1); libpd_add_float(2); libpd_add_symbol(“bar”); libpd_finish_list(“foo”);
finish current message and send as a typed message to a destination receiver note: typed message handling currently only supports up to 4 elements internally, additional elements may be ignored returns 0 on success or -1 if receiver name is non-existent ex: send [; pd dsp 1( on the next tick with: libpd_start_message(1); libpd_add_float(1); libpd_finish_message(“pd”, “dsp”);
send a float to a destination receiver ex: libpd_float(“foo”, 1) will send a 1.0 to [s foo] on the next tick returns 0 on success or -1 if receiver name is non-existent
free a pd instance does nothing when libpd is not compiled with PDINSTANCE
returns the double value of an atom note: no NULL or type checks are performed note: only full-precision when compiled with PD_FLOATSIZE=64
get the float value of an atom note: no NULL or type checks are performed
get a pd instance by index returns NULL if index is out of bounds or “this” instance when libpd is not compiled with PDINSTANCE
returns the symbol value of an atom note: no NULL or type checks are performed
get the verbose print state: 0 or 1
get the $0 id of the patch handle pointer returns $0 value or 0 if the patch is non-existent
initialize libpd; it is safe to call this more than once returns 0 on success or -1 if libpd was already initialized note: sets SIGFPE handler to keep bad pd patches from crashing due to divide by 0, set any custom handling after calling this function
initialize audio rendering returns 0 on success
check if an atom is a float type: 0 or 1 note: no NULL check is performed
check if an atom is a symbol type: 0 or 1 note: no NULL check is performed
send an atom array of a given length as a list to a destination receiver returns 0 on success or -1 if receiver name is non-existent ex: send [list 1 2 bar( to [r foo] on the next tick with: t_atom v[3]; libpd_set_float(v, 1); libpd_set_float(v + 1, 2); libpd_set_symbol(v + 2, “bar”); libpd_list(“foo”, 3, v);
send a atom array of a given length as a typed message to a destination receiver, returns 0 on success or -1 if receiver name is non-existent ex: send [; pd dsp 1( on the next tick with: t_atom v[1]; libpd_set_float(v, 1); libpd_message(“pd”, “dsp”, 1, v);
send a raw MIDI byte to [midiin] objects port is 0-indexed and byte is 0-256 returns 0 on success or -1 if an argument is out of range
create a new pd instance returns new instance or NULL when libpd is not compiled with PDINSTANCE
increment to the next atom in an atom vector returns next atom or NULL, assuming the atom vector is NULL-terminated
send a MIDI note on message to [notein] objects channel is 0-indexed, pitch is 0-127, and velocity is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port note: there is no note off message, send a note on with velocity = 0 instead returns 0 on success or -1 if an argument is out of range
get the number of pd instances returns number or 1 when libpd is not compiled with PDINSTANCE
open a patch by filename and parent dir path returns an opaque patch handle pointer or NULL on failure
send a MIDI pitch bend message to [bendin] objects channel is 0-indexed and value is -8192-8192 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port note: [bendin] outputs 0-16383 while [bendout] accepts -8192-8192 returns 0 on success or -1 if an argument is out of range
manually update and handle any GUI messages this is called automatically when using a libpd_process function, note: this also facilitates network message processing, etc so it can be useful to call repeatedly when idle for more throughput returns 1 if the poll found something, in which case it might be desirable to poll again, up to some reasonable limit
send a MIDI poly after touch message to [polytouchin] objects channel is 0-indexed, pitch is 0-127, and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port returns 0 on success or -1 if an argument is out of range
assign this function pointer to libpd_printhook or libpd_queued_printhook, depending on whether you’re using queued messages, to intercept and concatenate print messages: libpd_set_printhook(libpd_print_concatenator); or libpd_set_concatenated_printhook(your_print_handler); note: the char pointer argument is only good for the duration of the print callback; if you intend to use the argument after the callback has returned, you need to make a defensive copy
process interleaved double samples from inBuffer -> libpd -> outBuffer buffer sizes are based on # of ticks and channels where: size = ticks * libpd_blocksize() * (in/out)channels note: only full-precision when compiled with PD_FLOATSIZE=64 returns 0 on success
process interleaved float samples from inBuffer -> libpd -> outBuffer buffer sizes are based on # of ticks and channels where: size = ticks * libpd_blocksize() * (in/out)channels returns 0 on success
process non-interleaved float samples from inBuffer -> libpd -> outBuffer copies buffer contents to/from libpd without striping buffer sizes are based on a single tick and # of channels where: size = libpd_blocksize() * (in/out)channels returns 0 on success
process non-interleaved double samples from inBuffer -> libpd -> outBuffer copies buffer contents to/from libpd without striping buffer sizes are based on a single tick and # of channels where: size = libpd_blocksize() * (in/out)channels note: only full-precision when compiled with PD_FLOATSIZE=64 returns 0 on success
process non-interleaved short samples from inBuffer -> libpd -> outBuffer copies buffer contents to/from libpd without striping buffer sizes are based on a single tick and # of channels where: size = libpd_blocksize() * (in/out)channels float samples are converted to short by multiplying by 32767 and casting, so any values received from pd patches beyond -1 to 1 will result in garbage note: for efficiency, does not clip input returns 0 on success
process interleaved short samples from inBuffer -> libpd -> outBuffer buffer sizes are based on # of ticks and channels where: size = ticks * libpd_blocksize() * (in/out)channels float samples are converted to short by multiplying by 32767 and casting, so any values received from pd patches beyond -1 to 1 will result in garbage note: for efficiency, does not clip input returns 0 on success
send a MIDI program change message to [pgmin] objects channel is 0-indexed and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port returns 0 on success or -1 if an argument is out of range
initialize libpd and the queued ringbuffers, use in place of libpd_init() this is safe to call more than once returns 0 on success, -1 if libpd was already initialized, or -2 if ring buffer allocation failed
process and dispatch receive midi messages in MIDI message ringbuffer
process and dispatch received messages in message ringbuffer
free the queued ringbuffers
read n values from named src array and write into dest starting at an offset note: performs no bounds checking on dest returns 0 on success or a negative error code if the array is non-existent or offset + n exceeds range of array
read n values from named src array and write into dest starting at an offset note: performs no bounds checking on dest note: only full-precision when compiled with PD_FLOATSIZE=64 returns 0 on success or a negative error code if the array is non-existent or offset + n exceeds range of array double-precision variant of libpd_read_array()
(re)size an array by name; sizes <= 0 are clipped to 1 returns 0 on success or negative error code if non-existent
set the MIDI after touch hook to receive from [touchout] objects, NULL by default note: do not call this while DSP is running
set the bang receiver hook, NULL by default note: do not call this while DSP is running
assign the pointer to your print handler
set the MIDI control change hook to receive from [ctlout] objects, NULL by default note: do not call this while DSP is running
write a double value to the given atom note: only full-precision when compiled with PD_FLOATSIZE=64
set the double receiver hook, NULL by default note: avoid calling this while DSP is running note: you can either have a double receiver hook, or a float receiver hook (see above), but not both. calling this, will automatically unset the float receiver hook note: only full-precision when compiled with PD_FLOATSIZE=64
write a float value to the given atom
set the float receiver hook, NULL by default note: avoid calling this while DSP is running note: you can either have a float receiver hook, or a double receiver hook (see below), but not both. calling this, will automatically unset the double receiver hook note: only full-precision when compiled with PD_FLOATSIZE=64
set the current pd instance subsequent libpd calls will affect this instance only does nothing when libpd is not compiled with PDINSTANCE
set the list receiver hook, NULL by default note: do not call this while DSP is running
set the message receiver hook, NULL by default note: do not call this while DSP is running
set the raw MIDI byte hook to receive from [midiout] objects, NULL by default note: do not call this while DSP is running
set the MIDI note on hook to receive from [noteout] objects, NULL by default note: do not call this while DSP is running
set the MIDI pitch bend hook to receive from [bendout] objects, NULL by default note: do not call this while DSP is running
set the MIDI poly after touch hook to receive from [polytouchout] objects, NULL by default note: do not call this while DSP is running
set the print receiver hook, prints to stdout by default note: do not call this while DSP is running
set the MIDI program change hook to receive from [pgmout] objects, NULL by default note: do not call this while DSP is running
set the queued MIDI after touch hook, NULL by default note: do not call this while DSP is running
set the queued bang receiver hook, NULL by default note: do not call this while DSP is running
set the queued MIDI control change hook, NULL by default note: do not call this while DSP is running
set the queued double receiver hook, NULL by default note: avoid calling this while DSP is running note: you can either have a queued double receiver hook, or a queued float receiver hook (see above), but not both. calling this, will automatically unset the queued float receiver hook
set the queued float receiver hook, NULL by default note: avoid calling this while DSP is running note: you can either have a queued float receiver hook, or a queued double receiver hook (see below), but not both. calling this, will automatically unset the queued double receiver hook
set the queued list receiver hook, NULL by default note: do not call this while DSP is running
set the queued typed message receiver hook, NULL by default note: do not call this while DSP is running
set the queued raw MIDI byte hook, NULL by default note: do not call this while DSP is running
set the queued MIDI note on hook, NULL by default note: do not call this while DSP is running
set the queued MIDI pitch bend hook, NULL by default note: do not call this while DSP is running
set the queued MIDI poly after touch hook, NULL by default note: do not call this while DSP is running
set the queued print receiver hook, NULL by default note: do not call this while DSP is running
set the queued MIDI program change hook, NULL by default note: do not call this while DSP is running
set the queued symbol receiver hook, NULL by default note: do not call this while DSP is running
write a symbol value to the given atom
set the symbol receiver hook, NULL by default note: do not call this while DSP is running
set verbose print state: 0 or 1
open the current patches within a pd vanilla GUI requires the path to pd’s main folder that contains bin/, tcl/, etc for a macOS .app bundle: /path/to/Pd-#.#-#.app/Contents/Resources returns 0 on success
start composition of a new list or typed message of up to max element length messages can be of a smaller length as max length is only an upper bound note: no cleanup is required for unfinished messages returns 0 on success or nonzero if the length is too large
stop the pd vanilla GUI
send a symbol to a destination receiver ex: libpd_symbol(“foo”, “bar”) will send “bar” to [s foo] on the next tick returns 0 on success or -1 if receiver name is non-existent
send a raw MIDI byte to [sysexin] objects port is 0-indexed and byte is 0-256 returns 0 on success or -1 if an argument is out of range
send a raw MIDI byte to [realtimein] objects port is 0-indexed and byte is 0-256 returns 0 on success or -1 if an argument is out of range
get the current pd instance
unsubscribe and free a source receiver object created by libpd_bind()
read n values from src and write into named dest array starting at an offset note: performs no bounds checking on src returns 0 on success or a negative error code if the array is non-existent or offset + n exceeds range of array
read n values from src and write into named dest array starting at an offset note: performs no bounds checking on src note: only full-precision when compiled with PD_FLOATSIZE=64 returns 0 on success or a negative error code if the array is non-existent or offset + n exceeds range of array double-precision variant of libpd_write_array()
get the number of bytes that can currently be read this is safe to called from any thread
get the number of bytes that can currently be written this is safe to call from any thread
clears the contents of the ring buffer this is safe to call from any thread
read given number of bytes from the ring buffer to dest (if the ring buffer has enough data) note: call this from a single reader thread only returns 0 on success
write bytes from n sources to the ring buffer (if the ring buffer has enough space), varargs are pairs of type (const char*, int) giving a pointer to a buffer and the number of bytes to be copied note: call this from a single writer thread only returns 0 on success
writes single byte value n times to the ring buffer (if the ring buffer has enough space) note: call this from a single writer thread only returns 0 on success
Type Definitions
MIDI after touch receive hook signature channel is 0-indexed and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port note: out of range values from pd are clamped
bang receive hook signature, recv is the source receiver name
MIDI control change receive hook signature channel is 0-indexed, controller is 0-127, and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port note: out of range values from pd are clamped
double receive hook signature, recv is the source receiver name note: only full-precision when compiled with PD_FLOATSIZE=64
float receive hook signature, recv is the source receiver name
list receive hook signature, recv is the source receiver name argc is the list length and vector argv contains the list elements which can be accessed using the atom accessor functions, ex: int i; for (i = 0; i < argc; i++) { t_atom *a = &argv[n]; if (libpd_is_float(a)) { float x = libpd_get_float(a); // do something with float x } else if (libpd_is_symbol(a)) { char *s = libpd_get_symbol(a); // do something with c string s } } note: check for both float and symbol types as atom may also be a pointer
typed message hook signature, recv is the source receiver name and msg is the typed message name: a message like [; foo bar 1 2 a b( will trigger a function call like libpd_messagehook(“foo”, “bar”, 4, argv) argc is the list length and vector argv contains the list elements which can be accessed using the atom accessor functions, ex: int i; for (i = 0; i < argc; i++) { t_atom *a = &argv[n]; if (libpd_is_float(a)) { float x = libpd_get_float(a); // do something with float x } else if (libpd_is_symbol(a)) { char *s = libpd_get_symbol(a); // do something with c string s } } note: check for both float and symbol types as atom may also be a pointer
raw MIDI byte receive hook signature port is 0-indexed and byte is 0-256 note: out of range values from pd are clamped
MIDI note on receive hook signature channel is 0-indexed, pitch is 0-127, and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port note: there is no note off message, note on w/ velocity = 0 is used instead note: out of range values from pd are clamped
MIDI pitch bend receive hook signature channel is 0-indexed and value is -8192-8192 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port note: [bendin] outputs 0-16383 while [bendout] accepts -8192-8192 note: out of range values from pd are clamped
MIDI poly after touch receive hook signature channel is 0-indexed, pitch is 0-127, and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port note: out of range values from pd are clamped
print receive hook signature, s is the string to be printed note: default behavior returns individual words and spaces: line “hello 123” is received in 4 parts -> “hello”, “ “, “123\n”
MIDI program change receive hook signature channel is 0-indexed and value is 0-127 channels encode MIDI ports via: libpd_channel = pd_channel + 16 * pd_port note: out of range values from pd are clamped
symbol receive hook signature, recv is the source receiver name