~pbatch/patchwerk

patchwerk/patchwerk.w -rw-r--r-- 4.6 KiB
9c265356 — paul plan9 additions from Sigrid 3 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
\input macros.tex

@** Introduction. This document describes {\it patchwerk}, a library for
creating audio signal chains and audio graphs. Patchwerk provides an interface
where DSP unit
generators can be created and interconnected in a highly modular fashion.
The goal of Patchwerk is to beat out the performance of Sporth, a stack
based audio language well suited for modular synthesis and a previous project
done by the author. There is also a desire to keep the focus on soley the
signal chain interface, deferring DSP algorithms to other software such as
Soundpipe or FAUST.

If reading this for the first time, it may be best to first read the
\linkref{general overview}{overview} found in the next section. There is also
a \linkref{table containing an overview of sections}{tableoverview} that
may also be useful.
If using this document as a reference manual, there
is a \linkref{generated table of contents}{toc} that can
be found at the end of the document, and above that a hyperlinked index for
looking up functions. Unfortunately, the document generated by CWEB does
not handle text search all too well. Sorry about that.


@* An Overview of the System.
\mkref{overview}
It is perhaps best to conceptualize Patchwerk into
three major components: \linkref{nodes}{node}, \linkref{cables}{cable},
and \linkref{patches}{patch}.

In graph theory, a {\it node} is the building block for which graphs are
formed. In the context of digital signal processing, a node is
{\it unit generator}, capable of reading and writing audio-rate signals.
In
digitally based modular environments, unit generators are strung together to
build a sound. The interface for a node consists of a few
user-defined callback functions, as well as data persistence.

Nodes communicate to one another through channels known as {\it cables}. A
cable contains a pointer to some numerical value in memory.
Cables, when they start out, point to an internal float value, providing a
constant value. This initial pointer address can be overridden to point to
other memory addresses. This allows nodes implicitly connected to one another.

A collection of interconnected nodes is known as a {\it patch}.

A node can have inputs that are fed by the outputs of other nodes.
Nodes that feed into inputs are dependencies, and therefore
their audio samples must be computed
beforehand. Furthermore, nodes in a modular setting must be called exactly
once.

Constructing an audio graph can be a very challenging problem. For instance,
it takes a non-trivial bit of software engineering to produce a node list given
a set of connections. Such complexities need not exist here! The
solution the author has chosen is to restrict the way graphs can be constructed
and connected. When a new node is created, it is appended to the end of a
linked list of nodes and given an incremental unique ID based the position
in the list (0, 1, 2, 3, etc.). A node can only connect to inputs of other nodes
with higher IDs.
This ensures that the node is guaranteed to be rendered beforehand.

@* Overview of Sections. The following section provides an overview of the
subsections of Patchwerk.
\medskip
{
\offinterlineskip
\tabskip=0pt
\halign{
\vrule height 2.75ex depth 1.25ex width 0.6pt
\hfil # \hfil & \vrule \hfil # \hfil \vrule width 0.6pt \cr
\noalign{\hrule}

\mkref{tableoverview}
{\bf Section Name} & {\bf Description} \cr
\noalign{\hrule}

\linkref{Header}{headerfile} &
The single |patchwerk.h| header file generated. \cr

\linkref{Node}{node} &
The |pw_node| interface for building nodes.  \cr

\linkref{Cable}{cable} &
The |pw_cable| interface for building cables.  \cr

\linkref{Error}{error} &
Error handling. \cr

\linkref{Pointer}{pointer} &
The |pw_pointer| and |pw_pointerlist| interfaces for handling
pointers and pointer lists. \cr

\linkref{Pool}{pool} &
The |pw_buffer| and |pw_bufferpool| interfaces for managing
buffers and buffer pools. \cr

\linkref{Stack}{stack} &
Describes the |pw_stack| interface, otherwise known as a buffer stack.\cr

\linkref{Patch}{patch} &
Describes the |pw_patch| interface, the top-level data structure for
describing a single audio graph.\cr

\linkref{Subpatch}{subpatch} &
Describes the |pw_subpatch| interface, which introduces the concept of
subpatches.
\cr
\linkref{Event Graph}{egraph} &
Event graphs in Patchwerk via the |pw_egraph| interface.
\cr
\noalign{\hrule}
}
}

@ The first few lines of code are the header declarations, followed by
the actual program, which boils down to a single top-level directive.
@c
#include <stdlib.h>
#include <stdio.h>
#include "patchwerk.h"
@<Top@>
@i header.w
@i node.w
@i cable.w
@i error.w
@i pointer.w
@i pool.w
@i stack.w
@i patch.w
@i subpatch.w
@i egraph.w
@i dump.w
@i memory.w
@i print.w