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.