mirror/JUCE
1
0
Fork 0
mirror of https://github.com/juce-framework/JUCE.git synced 2026-01-10 23:44:24 +00:00
Code Activity
JUCE/extras/audio plugins/How to use this framework.txt
jules eb5b9a7ac9
2007-08-22 15:01:06 +00:00

272 lines
15 KiB
Text
Raw Blame History

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_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\EffectClasses
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ProcessClasses
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ProcessClasses\Interfaces
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Utilities
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\RTASP_Adapt
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\CoreClasses
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Controls
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Meters
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ViewClasses
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\DSPClasses
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Interfaces
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\common
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\common\Platform
c:\yourdirectory\PT_73_SDK\AlturaPorts\TDMPlugins\SignalProcessing\Public
c:\yourdirectory\PT_73_SDK\AlturaPorts\SADriver\Interfaces
c:\yourdirectory\PT_73_SDK\AlturaPorts\DigiPublic\Interfaces
c:\yourdirectory\PT_73_SDK\AlturaPorts\Fic\Interfaces\DAEClient
c:\yourdirectory\PT_73_SDK\AlturaPorts\NewFileLibs\Cmn
c:\yourdirectory\PT_73_SDK\AlturaPorts\NewFileLibs\DOA
c:\yourdirectory\PT_73_SDK\AlturaPorts\AlturaSource\PPC_H
c:\yourdirectory\PT_73_SDK\AlturaPorts\AlturaSource\AppSupport
c:\yourdirectory\PT_73_SDK\AvidCode\AVX2sdk\AVX\avx2\avx2sdk\inc
- 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..
- IMPORTANT NOTE! If you're using MSVC2005 to build your plugin, the users will need to
have the Microsoft VC8 Runtime installed on their machines, otherwise the DLL will
silently fail to load. You should probably add the runtime to your plugin's installer,
and you can get a copy of it here:
http://www.microsoft.com/downloads/details.aspx?FamilyID=32bc1bee-a3f9-4c13-9c99-220b62a191ee&DisplayLang=en
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.
View git blame Copy permalink