Patching Basics

​

Visual Programming with Pure Data

​

The Canvas

• Infinite Canvas: The canvas size is effectively unlimited (32,768 x 32,768 pixels internally)
• Origin Point: Located at the center, marked with dashed lines when visible
• Patch Boundaries: Configurable width and height that define your working area
• Grid System: Optional grid overlay for precise object placement

​

Objects: The Building Blocks

​

Object Types

• Process discrete events and values
• Operate at control rate (when events occur)
• Examples: [metro], [random], [print]

• Process continuous audio signals
• Operate at audio sample rate (typically 44.1kHz or 48kHz)
• Always end with a tilde (~) in their name
• Examples: [osc~], [dac~], [+~]

• Provide visual interfaces for interaction
• Examples: sliders, number boxes, toggles, canvases

[metro 500]  ← Message object (control rate)
|
[random 100]
|
[osc~ 440]   ← Signal object (audio rate)
|
[dac~]       ← Digital-to-analog converter (audio output)

​

Inlets and Outlets

​

Hot vs Cold Inlets

• Triggers the object to perform its operation
• Causes output to be sent from outlets
• Always processes immediately

• Store values without triggering execution
• Wait for the hot inlet to receive input
• Update internal state only

[50]  [10]   ← Send values
 |      |
 [+    ]     ← Addition object
 |
[print]      ← Output: 60

1. Sending 10 to the right (cold) inlet stores the value
2. Sending 50 to the left (hot) inlet triggers the addition and outputs 60

​

Execution Order

1. When an object fires, its outlets send messages
2. Rightmost connections are executed first
3. Objects higher on the canvas execute before lower objects
4. This creates a depth-first execution tree

[bang]
    |
    |----[print third]   ← Executes third
    |
    |----[print second]  ← Executes second
    |
    |----[print first]   ← Executes first (rightmost)

​

Signal vs Message Objects (~)

• Discrete values and events
• Processed only when triggered
• Lower CPU usage
• Examples: [+], [*], [random]

• Continuous audio-rate streams
• Processed every sample (e.g., 44,100 times per second)
• Higher CPU usage
• Examples: [+~], [*~], [osc~]

• [sig~] - Convert message to signal
• [snapshot~] - Sample a signal to get a message value
• [vsnapshot~] - Vector-based signal sampling

​

Subpatches

​

Creating Subpatches

[pd mysub]  ← Double-click to open

• Saved as separate .pd files
• Can be used across multiple patches
• Searchable in plugdata’s object library

if (auto const subpatch = gui->getPatch()) {
    cnv->pd->lockAudioThread();
    auto* subpatchPtr = subpatch->getPointer().get();
    // Process child objects for inlet/outlet detection
    for (auto obj : subpatch->getObjects()) {
        auto const name = String::fromUTF8((*obj.getRaw<t_pd>())->c_name->s_name);
        if (name == "inlet" || name == "inlet~") {
            // Handle inlet tooltip extraction
        }
    }
}

​

Inlet and Outlet Objects

• [inlet] / [inlet~] - Receive messages/signals from parent
• [outlet] / [outlet~] - Send messages/signals to parent

​

Abstractions

1. Create a patch with [inlet] and [outlet] objects
2. Save it with a unique name (e.g., myfilter.pd)
3. Use it in other patches by creating an object with that name

• Code reuse across projects
• Centralized updates (edit once, affects all instances)
• Cleaner main patches
• Can be shared with the community

[myfilter 440 0.5]  ← Pass arguments to abstraction

• [$1], [$2], etc. - Creation arguments
• [\$0] - Unique instance ID (for local send/receive)

​

Lock Mode vs Edit Mode

• Create and modify objects
• Make and remove connections
• Move and resize objects
• Objects are not interactive

• Interact with GUI objects (sliders, toggles, etc.)
• Objects and connections cannot be modified
• Optimized for performance
• No visual overhead from editing features

​

Connection Types

• Black/Base: Standard message connections
• Colored (when configured): Signal connections (~)
• Special (Gem): GEM rendering chain connections

• Segmented paths: Orthogonal routing with user-defined waypoints
• Curved paths: Smooth bezier curves (default)
• Straight paths: Direct lines between objects

float const width = std::max(start.x, end.x) - std::min(start.x, end.x);
float const height = std::max(start.y, end.y) - std::min(start.y, end.y);
float shiftY = std::min<float>(maxShiftY, max * 0.5);
// Cubic bezier for smooth connections
connectionPath.cubicTo(ctrlPoint1, ctrlPoint2, end);

​

Best Practices

1. Use meaningful object names: Comment your patches
2. Organize with subpatches: Keep main patch clean and readable
3. Follow right-to-left rule: Place objects to match execution order
4. Use trigger objects: Guarantee execution order when needed
5. Comment liberally: Use comment objects to document your patch
6. Test incrementally: Build and test small sections before combining
7. Watch CPU usage: Monitor DSP load in the status bar

​

Next Steps