Current C++ patch conventions (for upcoming tutorial)

gc3 2018-10-16 22:19:23 UTC #1

Hi RT and community!

I've taken the liberty of drafting a quick Wizard-specific (but presumably Alchemist-compatible) tutorial for C++ patching, moving from a passthrough "hello world" patch and going through some simple stereo channel processing with button control. (The plan is to continue with a multi-part tutorial about drone synth design, starting with a test tone and getting rather elaborate; a drone synth is my first major Wizard project and I figured I might as well document the process in case it's helpful).

A few quick questions before I publish a draft of this thing. First, in the current (dynamic compilation) world, is there a reason to have patches in .hpp files as opposed to .cpp files? Similarly, are the #ifndef guards:

#ifndef __MyPatch_hpp__
#define __MyPatch_hpp__
...
#endif // __MyPatch_hpp__

still important?

Also, are there any other conventions (positive or negative) that I should be aware of for modern C++ OWL patches? (The Test LR patch I just put up at https://www.rebeltech.org/patch-library/patch/Test_LR is more or less my blueprint; I'll include any official or community suggestions/corrections in the tutorial).

bfabricius 2018-10-17 08:04:25 UTC #2

Hey @gc3

This is great stuff. Thanks for putting in the effort. I have a side project centered on teaching yourself DSP in order to develop some stock software fx. The tutorials focus on the mathematical theory, the design, development and testing of fx. I would love to add these to the tutorials that are growing here. Maybe I can even customize a spin of my written tutorials based on yours. Looking forward to reading the draft!

Cheers,
Ben

gc3 2018-10-17 18:10:20 UTC #3

Thanks, Ben! Your DSP tutorials sound awesome (I for one could really use an introduction like that) and I think the two projects would actually complement each other quite well--I'm hoping to focus on the Wizard as a platform, particularly one for live performance, so I'm focused more on control and interaction design stuff rather than any particular DSP algos.

Neat! I'll wait a bit for comments on the above to come through, and then I'll stick a draft of the first few parts up on the forum (unless anyone has a better idea about where to put it).

mars 2018-10-19 18:02:29 UTC #4

hi @gc3, this is a great initiative!

To quickly answer your questions:
- header guards should not be needed
- you still have to put the patch declaration in a .hpp file with the same name as your main patch class, in order to satisfy our build assumptions. These assumptions can be overridden if you use offline OwlProgram compilation, but not (currently) with our online compiler.

You can of course put the patch class declaration in a .hpp file, then put the implementation in a .cpp file as is commonly done. Any .c or .cpp file that is part of the patch will be compiled as a separate compilation unit.

Documentation: we used to have a wiki on the old hoxtonowl.com website, but it wasn't well maintained. We could set up a new wiki, but personally I'm thinking that first fleshing things out on the forum, then publishing documentation pages on the main website, could be a better process. What do you think?

gc3 2018-10-19 18:48:26 UTC #5

@mars ! Thanks again for your response and your kind words.

Extensions: Empirically, single .cpp files actually seem to work, for some reason (see that Test_LR patch I threw up the other day) but if that is not intended behavior I will stick with .hpp for the proposed tutorials.

Documentation: Sticking with the forum for the time being sounds good, and if you feel that anything is website-worthy that would be great! On the forum side, I'll keep some sort of version and date at the top of the post (and note if it hasn't been technically reviewed by you or someone else from RT).

bfabricius 2018-10-19 19:59:23 UTC #6

@mars, @gundy count me in! We can continue to use the forum until we think that its worth "releasing" any documentation officially. I personally think that attachment or linking to some shared (portable) docs could probably also help if we plan to publish any lengthy documentation or tutorials. Some meaningful topics and labels should be enough to differentiate DOC/Tutorial threads from others.

Good times, looking forward.

Cheers,
Ben

mars 2018-10-23 12:49:28 UTC #7

A potential problem is that the .cpp file will firstly be #included as the main patch file, and then compiled again on its own. It works in this case because no linker symbols, such as global variables or functions, are defined in that file.

So for guidelines I think we should recommend to put the patch class declaration in a header file, make that the patch main file, and then season to taste with supporting .cpp and header files.

gc3 2018-10-23 15:54:28 UTC #8

Makes good sense! Thanks again. I'll start with everything in a single .hpp file (incorporating your explanation) and plan to eventually work up to a multi-file example.