Chapter 5: CPS SDK's
5.1 Overview
This chapter gives a very short introduction into the SDK's (Software Developer Kit) that CPS
has.
By using one of the SDK's, you can extend CPS or use it in other ways than only running
the program itsself.
If you want to know more about the different parts, you must read the documentation which
is included with the specific SDK's in the doc/ folders. This chapter only gives a
global overview to introduce you into the specific topics.
For most SDK's, you need to be able to program a little bit and use sourcecode. You
do not always have
to be a programmer (for example to use the Director/Shockwave Xtra, and to run CPS as VST
plugin), but you must understand what is going on. There is extensive help available in the
specific documentations to help you with all problems.
5.2 VST
You can use CPS as a VST plugin, or as a VST Instrument. It's a matter of dragging a .dll
file to
the VST plugins folder of a VST Host. You can use currently use up to 8 in- and outputs from
and to your VST host.
It is also possible to run CPS-plugins (which you can create with the plugin-SDK,
see further) inside a VST-host. You do not have to recompile the CPS-plugin, but only
rename the plugin. In this way, you can (educationally) first create a CPS-plugin, and create
more-difficult VST plugins later.
A third way of using VST technology inside CPS, is running VST plugins inside the CPS program.
Because this VST hosting is build-in in the CPS program, there is nothing in the SDK
which is needed to host VST plugins. The default VST-folder (by Steinberg) is scanned when
CPS is started, so if your plugin is inside there, it is automaticly listed in the 'Plugin'
objectlist of CPS. If not, you must copy your VST plugin to the /plugins folder of CPS.
Note that these functionalities are not really typically part of a 'SDK', but altogether
this section does include every way to use CPS besides running the CPS program itsself.
5.3 Director
A CPS patch can completely run as big multimedia engine under MacroMedia Director/Shockwave
7 or higher. This is probably the easiest way to use CPS as a game engine.
The Director Xtra is actually part of the CPS standAlone facility, because it is in fact
another appearance of the same SDK (read that paragraph for more information!).
You can save a complete patch as Lingo (the scripting language inside the Director studio)
code, and insert it in a director movie. In this way you can manipulate audio, midi, and more,
inside your running Director movie.
As with the standAlone SDK, you can control CPS by sending value's to seperate objects
(like you can put numbers in objects in the graphical interface of CPS) for example to
change a preset, or by talking to seperate objects with text. You can also get parameters
back from the running engine (for example for visual midi input signaling).
A very small set of commands is introduced to completely control
CPS with Lingo. As mentioned, the functions look similar to the C++/Java standAlone SDK,
in fact with this set of Lingo-functions, you can do exactly the same. This
includes a function to create an object, one to create or delete a wire,
sending or receiving parameters, etc.
A Director file which contains CPS lingo code, is automaticly ready to be used in a browser.
To prepare your browser, download the CPS2Browser add-on at the CPS homepage
(or copy the requested files from the Director SDK manually, as described in the documentation).
A check for weither or not the CPSBrowser is installed on a computer, is automaticly
generated at the beginning of the 'Save as Director/Shockwave' lingo code.
Like mentioned above: specific documentation, use cases and examples, are all included in
the SDK, not in this main documentation.
5.4 StandAlone
You can use CPS 'standAlone', without it's graphical interface, inside your own
application (see further to use 'application' for having the graphical interface available
while your program is running). Currently that's possible inside a C++ or inside a Java
program (and inside MacroMedia Director/Shockwave, see further).
If you save your patch as .cpp or as .java code, then
all calls to load that CPS-file, are translated into sourcecode. The sourcecode
uses a small library that you must include with your program.
It is also possible to start from scratch and build a CPS patch yourself with
the standAlone SDK, because with the standAlone SDK you can do exactly the
same as with the graphical interface. The standAlone SDK
contains classes for objects, wires, and runtime erors. The classes are identical
for as well ANSI C++ as Java. Any Java 1.0 compliant development environment can be used.
You can set and get variables to any object at any time to influence the patch as it is
running (for example changing a preset number, or giving specific value's into objects).
It is also possible to conversate text with each object specificly, to change
specific options. When a
patch is saved, it clearly shows you how to communicate with objects to set parameters
which are set by the graphical interface of CPS (for example the command "setport 2"
for 'audioOut'). The names of the objects in the generated sourcecode can be predefined
for several 'Display'-objects (for example, hold the shift key and doubleclick on a fader).
5.5 Plugin
With the plugin SDK you can write objects for CPS yourself. The language for the
plugin part in which the processing of realtime data is done, is C++.
It is extremely easy
to write a C++ plugin, several examples in the SDK show you step by step how to program them.
You do not need to learn anything platform dependent too, the code is pure ANSI C++.
Because writing CPS plugins is more clear and easier than
writing a VST plugin, making CPS plugins is educationally usefull (CPS plugins can also
run directly inside any VST-host after renaming the custom plugin).
As a bonus, it is possible to use any build-in CPS object (including the MPEG-4 Structured
Audio ones), right inside your new plugin too if needed (for example a filter).
As with VST plugins, there is one function in which as well the output as
the input audio buffers are given. Making a dynamic number of in- and outputs is as easy as increasing a
variable; generating an error message is as easy as throwing an 'exception'.
The plugin SDK also has a Java part. That is, for the graphical interface. You can write
a graphical interface for your plugin, which is being loaded when a user doubleclicks on
your object inside CPS.
You can communicate with the C++ plugin part in a simple way to as well get and receive
information from your plugin. You can also show information in the 'System Messages' field
for debugging or simple notifying.
If needed, you can also store information inside the CPS patch. You can access a
'Vector' which can be filled with any data, even with custom classes defined by you.
In this way, settings are stored within a .cps file and loaded in automaticly if necessary.
All the objects and graphical interfaces of CPS are build using this plugin architecture.
Examples of CPS plugins are: all the objects of CPS! Examples of graphical CPS
Java-plugins are: 'table', 'audioFromDisk', 'serialPort', etc.
The SDK includes several Java interface examples.
5.6 'application'
With 'application' you can run CPS and a CPS patch, and then start your application in which
you want to run the CPS engine standAlone eventually. This can be done with as well C++ as
Java Programs. In this way you can as well edit your CPS patch and test your program; without
'application' this is not possible because the patch is simply saved as sourcecode.
It is possible to send runtime value's into the running CPS path. In this way, you can simulate
that CPS is the engine which is used standAlone. There's a small buffering for the outputs,
and a way of sending a few value's to CPS at once.
5.7 QuickTime
There is a small set of CPS objects which represent the use of Apple's Quicktime to show
movies and pictures, layered inside one output screen, which you can for example put
out on a beamer. This is not an SDK feature of CPS, but it falls in the same category.
Because there
are several things to install first, it is released as a seperate .zip file with CPS and is
not included by default (in fact, it is, but hidden). There are also several
irritating restrictions by Apple,
which makes it extremely less interesting to use Apple Quicktime for Java as the
technology to
manipulate movies and pictures in realtime. By not including this by default, it is easier
to shift to an other technology in the future.
All movies and pictures inside the output screen have several properties (like position,
transparancy, etc), which can all be
manipulated in realtime. There are several macro's included to make this easier.