mirror of
https://github.com/juce-framework/JUCE.git
synced 2026-01-10 23:44:24 +00:00
265 lines
14 KiB
Text
265 lines
14 KiB
Text
|
|
The Juce Audio Plugin project!
|
|
==============================
|
|
|
|
(c) 2005-6 by Raw Material Software, visit www.rawmaterialsoftware.com for more info.
|
|
|
|
The idea behind this is to create a framework which lets you write a platform-independent
|
|
audio plugin using Juce, which can be easily rebuilt to target multiple different plugin
|
|
formats and platforms.
|
|
|
|
|
|
How does it work?
|
|
=================
|
|
|
|
There's a generic audio plugin base class defined in juce_AudioFilterBase.h, and to write
|
|
your plugin, you just need to create a sub-class of this.
|
|
|
|
You can then compile your class against one or more of the platform-specific projects,
|
|
so that it gets wrapped as a VST, AudioUnit, RTAS, etc. - hopefully without changing any
|
|
of your code at all, or having to go anywhere near any platform-specific stuff.
|
|
|
|
|
|
How do I use it?
|
|
================
|
|
|
|
Under the 'wrapper/formats' directory are a bunch of different sets of files containing the
|
|
wrapper code for each different plugin type.
|
|
|
|
There is also a 'demo' folder - this shows an example plugin which can be built in all
|
|
the different formats. The demo folder contains:
|
|
|
|
- a 'src' directory containing the common, platform-independent code that defines this
|
|
plugin's behaviour
|
|
- a 'build' directory which contains projects for building the demo for each different
|
|
platform and format.
|
|
|
|
Have a look at the demo classes to see how it works, and then to create a real plugin,
|
|
you'll need to replace the demo files with your own code.
|
|
|
|
I've tried to add helpful comments where you might run across common compile errors, to
|
|
help describe what you might be doing wrong, as getting a build set-up for some of these
|
|
formats can be a bit of a pain. Please let me know if you find there's anything missing
|
|
from these instructions or anything I could change to help smooth the build process along
|
|
a bit.
|
|
|
|
I'd recommend NOT putting your own plugin code inside the JuceAudioPlugin directory - it's
|
|
much neater to keep it somewhere separate and to alter the projects to point to your
|
|
files instead of the demo ones. That way when new versions of this library come out, it'll
|
|
make it easier to update to the latest code.
|
|
|
|
For details about how to create your own projects for the various formats, see below.
|
|
|
|
|
|
Sending feedback:
|
|
=================
|
|
|
|
- if you spot a bug or some kind of host incompatibility, tell me, of course!
|
|
|
|
- the plan is that no-one should need to change any of the platform-specific code, or the base-class
|
|
code.. So if you find that your plugin can't do something you want it to, then rather than just
|
|
jumping in and hacking things to get the functionality you need, why not contact me and we'll
|
|
figure out a nice generic way of doing it. That way it'll benefit all the users, and you won't
|
|
have to hack it all over again when the next version comes out.
|
|
|
|
- if you're really determined to rewrite large chunks of my code and send it to me to look at,
|
|
*please* don't reformat anything in your own preferred style, or change the format of the
|
|
comments, etc.. It's bad enough looking at people's code and trying to figure out why they've
|
|
done something, but if everything's moved around I can't even diff it..
|
|
|
|
|
|
What are the licensing issues?
|
|
==============================
|
|
|
|
Juce is released under the GPL (Gnu Public License) - this means that you're free to use
|
|
and redistribute it as long as your products are also released under the GPL. Basically
|
|
this means that if you use it, you also have to give away your source code.
|
|
If you want to release a closed-source application, you can buy a commercial license
|
|
that lets you avoid this restriction - see http://www.rawmaterialsoftware.com/juce for more info,
|
|
or see the comments at the top of all the Juce source files.
|
|
|
|
If you're building the VST projects or releasing a VST, you'll need have a look at Steinberg's
|
|
developer site to see what licensing rules apply these days. Their website's at
|
|
http://www.steinberg.net
|
|
|
|
If you're building an RTAS then you'll need to sign Digidesign's developer license to get
|
|
their SDK. Visit http://www.digidesign.com for more info.
|
|
|
|
|
|
-----------------------------------------------------------------------------------------------------
|
|
|
|
How to create your own VST project
|
|
==================================
|
|
|
|
- Visit http://www.steinberg.net and jump through whatever hoops are necessary to download
|
|
and install the VST SDK.
|
|
- Make sure your include path contains an entry for the "vstsdk2.4" folder containing
|
|
the SDK.
|
|
- First try loading the VST demo project in JuceAudioPlugin/demo/build. Hopefully this
|
|
should build correctly.
|
|
- To create your own project for a VST, the simplest way is to take a copy of
|
|
the demo project and go through it carefully, changing any relevent settings to reflect
|
|
your own project.
|
|
|
|
N.B. On the Mac, there's an important point to note about exported symbols.. When XCode builds
|
|
the plugin, I've had unpredictable results when trying to stop it from exporting all of
|
|
the internal functions as public symbols. There are some flags that are supposed to turn this
|
|
off, but sometimes they don't seem to have any effect, and using an explicit exports file also
|
|
seems a bit hit-and-miss. (If anyone knows better and can get this working, please let me know!)
|
|
Anyway, as well as being wasteful and showing everyone what's inside your plugin, leaving all
|
|
the symbols in there will cause fatal crashes when used with Tracktion, or alongside any other
|
|
Juce-based plugins. A way of making sure your plugin is stripped is to use the command
|
|
"strip -x -S YourPlugin.vst/Contents/MacOS/YourPlugin" after bulding it, which removes the
|
|
unnecessary symbols (although in my experience this also doesn't seem to work all the time,
|
|
so it's a good idea to check it using the unix "nm" command).
|
|
|
|
|
|
-----------------------------------------------------------------------------------------------------
|
|
|
|
How to create your own AudioUnit project
|
|
========================================
|
|
|
|
- If you've got XCode installed, the demo project in JuceAudioPlugin/demo/build/AudioUnit
|
|
should just build. You may need to tweak a few paths to make sure it can find the
|
|
juce.h include file and juce library.
|
|
- When copying this project to make your own, a good plan is to open up a view of the settings
|
|
for the project and target, viewing the "customised settings" to see those values that
|
|
have to be deliberately set for the plugin to work.
|
|
|
|
N.B. For the Mac there can be an issue with exported symbols - see the note about this for
|
|
VSTs, as the same solution can be used for AudioUnits.
|
|
|
|
|
|
-----------------------------------------------------------------------------------------------------
|
|
|
|
How to create your own RTAS project
|
|
===================================
|
|
|
|
|
|
RTAS is a bit more of a pain to build than VSTs or AUs. To begin with:
|
|
|
|
- Contact Digidesign, ask to become a Digidesign Development Partner, sign the relevent
|
|
agreements and NDAs.
|
|
- From the Digidesign website, download their latest Plug-In SDK
|
|
- Install the SDK and build some of the demo plugins to make sure it all works.
|
|
|
|
Compiling the juce demo RTAS on the PC:
|
|
=======================================
|
|
|
|
- Using the Digidesign demo projects in the SDK, make sure you've built debug and release
|
|
versions of these static libraries: DAE.lib, DigiExt.lib, DSI.lib, PlugInLib.lib.
|
|
|
|
- In Visual Studio, add all of this lot to your include path:
|
|
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\EffectClasses
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ProcessClasses
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ProcessClasses\Interfaces
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Utilities
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\RTASP_Adapt
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\CoreClasses
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Controls
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Meters
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ViewClasses
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\DSPClasses
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Interfaces
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\common
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\common\Platform
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\TDMPlugins\SignalProcessing\Public
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\SADriver\Interfaces
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\DigiPublic\Interfaces
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\Fic\Interfaces\DAEClient
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\NewFileLibs\Cmn
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\NewFileLibs\DOA
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\AlturaSource\PPC_H
|
|
c:\yourdirectory\PT_711_SDK\AlturaPorts\AlturaSource\AppSupport
|
|
|
|
- The Visual Studio juce_RTAS project contains a folder called "libs", with "debug" and
|
|
"release" subdirectories - these should contain links to the Digidesign lib files
|
|
DAE.lib, DigiExt.lib, DSI.lib, PlugInLib.lib - you'll need to update these links to
|
|
point to the correct locations according to where you've installed the SDK.
|
|
|
|
- Fingers crossed, this should now compile..
|
|
|
|
|
|
Creating a project for your own RTAS on the PC:
|
|
=================================================
|
|
|
|
- start a new empty project in Developer Studio, as a "Windows DLL"
|
|
- in the source tree, create the same folders and add to them the same list of
|
|
cpp files that are in the demo project's "wrapper code" folder.
|
|
- select all the CPP files in the "wrapper code/RTAS specific" folder, and also
|
|
the juce_RTASWrapper.cpp file, (but NOT the juce_RTASUtilities.cpp file or any
|
|
other files!), and in their properties dialog, under C++/Advanced, change their
|
|
"Calling convention" setting to "__stdcall".
|
|
Remember to do this for both your debug and release builds!
|
|
- in your project's C++/General settings, add an additional include path so that
|
|
it will be able find your JucePluginCharacteristics.h file.
|
|
- Under "linker settings", change the output file name to have the suffix ".dpm"
|
|
instead of ".dll"
|
|
- Under "linker settings/input/ignore specific library", you'll probably need to
|
|
add "libcmtd.lib" for debug, and "libcmt.lib" for release.
|
|
- Under "linkey settings", set the Module definition file to be
|
|
JuceAudioPlugin/wrapper/formats/RTAS/juce_RTAS_dlldefs.def
|
|
- You might want to change the output directory to "\Program Files\Common Files\Digidesign\DAE\Plug-Ins\"
|
|
if you want the built plugin to go directly into the PT plugins folder
|
|
- Add a custom build step to copy the dummy resource file "JuceAudioPlugin\wrapper\formats\RTAS\DefaultResourceFile"
|
|
to your target directory, renaming to to be the same as your .dpm file, but with
|
|
".rsr" on the end of the name. The demo project does this with the command
|
|
"copy /Y ..\..\..\wrapper\formats\RTAS\DefaultResourceFile "$(TargetPath)".rsr"
|
|
- Under the "general" properties, make sure that the character set is not unicode, as
|
|
this seems to stop some of the Digi code building. Hopefully this will be fixed
|
|
in future SDK releases
|
|
- add a "libs" folder to your project, and copy the set of libraries from the
|
|
equivalent folder in the demo project. Make sure you enable the debug/release
|
|
versions of these libraries appropriately.
|
|
|
|
There are quite a few things that you need to get right for an RTAS to compile correctly -
|
|
the Digi SDK documentation has a full list of tips on setting up a project, but the
|
|
main ones to note are:
|
|
|
|
- the SDK uses __stdcall as its calling convention, but JUCE uses __cdecl. I've got
|
|
around this by leaving the project's default setting as __cdecl, but changing it
|
|
specifically for those files that include or build files from the SDK - i.e. for
|
|
most of the files in the "wrapper code/RTAS specific" folder of the demo project.
|
|
- the default struct alignment for the SDK is 2 bytes, wheras the default as used in
|
|
juce is 8 bytes. Again, I've left this at the default setting, and have explicitly
|
|
changed it with pragmas when including/building SDK files.
|
|
- even though it's not used, each xx.dpm file needs to have a corresponding
|
|
xx.dpm.rsr file next to it, or PT will refuse to load it. The demo project currently
|
|
does this by using a custom build step to copy and rename a small dummy rsr file called
|
|
JuceAudioPlugin/wrapper/formats/RTAS/DefaultResourceFile
|
|
|
|
|
|
Compiling the juce demo RTAS on the Mac:
|
|
========================================
|
|
|
|
- After installing the Digidesign SDK, make sure you've run the config_SDK_for_Mac command in
|
|
its root directory. This sets up some of the tools that it needs.
|
|
- Load the juce_RTASDemo.xcodeproject and look through the project in XCode to find
|
|
all the broken links to Digidesign files. You'll need to repair these to make them
|
|
point to the location of the SDK files on your machine.
|
|
- Open the project's settings, and look for the "MacBag" setting - this defines the location
|
|
of the MacBag folder in the Digidesign SDK. You'll need to update this to point to
|
|
its location on your machine.
|
|
- It should all compile now, fingers crossed..
|
|
|
|
- Building a universal binary on the Mac: for this, you'll need to recompile the Digidesign
|
|
PluginLibrary project as a universal binary. The easiest way to do this is to add the
|
|
following lines to the top of the CommonDebugSettings.xcconfig and CommonReleaseSettings.xcconfig
|
|
files (these are found deep in the PT SDK tree somewhere, and are used for config by both the
|
|
Digi projects and the juce plugin projects):
|
|
ARCHS = ppc i386
|
|
SDKROOT = /Developer/SDKs/MacOSX10.4u.sdk
|
|
MACOSX_DEPLOYMENT_TARGET_ppc = 10.3
|
|
|
|
|
|
Creating a new project for your own RTAS plugin on the Mac:
|
|
===========================================================
|
|
|
|
It's probably easiest to take a copy of the juce demo project and go through it changing
|
|
its settings to those of your plugin.
|
|
|
|
If you decide to start from scratch, use the juce demo project as a reference to see
|
|
what needs to go in there. Looking at its project info for "customised settings" is a good
|
|
way to see what values have been set deliberately.
|
|
|