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
- bug⚠
- feof⚠
- ftom⚠
- getc⚠
- getw⚠
- 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()
- mtof⚠
- post⚠
- putc⚠
- puts⚠
- putw⚠
- 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
- create a ring buffer, size must be a multiple of 256 returns NULL on failure
- free a ring buffer
- 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 Aliases
- 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