CoolEdit96/2000 SDK

Site hosted by Angelfire.com: Build your free website today!

CoolEdit96/2000 SDK

Last update: Feb. 14th, 2000

	NB. This tutorial was written for CoolEdit96 SDK. Recently Syntrillium substituted it with the new one - CoolEdit2000 SDK. It looks somewhat different, it's less organized, and the new documentation has lots of typos and obvious errors (the old one was very clean and well-written). Still, the new SDK provides more possibilities than the older one. You can still use my tutorial as a general guide, although some details (like TRANSFORMNAME) will be different in the new Syntrillium samples.
		How to Begin
		Customizing
		Functions and Data Fields
		After Compiling
		Back to plug-ins

How to Begin

o, you've downloaded the SDK ("32-bit Filter and Transform APIs") from Syntrillium site and you now wonder what do you do now to start using it. These small explanations may help. In those, I assume you are using Microsoft Visual C++ 5.x or 6.x; if you have something else, you'll have to figure out how to adapt my explanations for your compiler
First, unzip the SDK archive. You'll see two files (SAMPLES.TXT and APIS96.DOC) and three directories. Each of those directories contain some sample project that you can use as a starting point for your own plug-in.
Read the file SAMPLES.TXT. It basically states what directory contains what project. For doing the effects, transforms etc., you'll need to look into the XFMSAMPL project. It will be the one I'll use as an example here.
Let's say you want to write plug-in for some transformation that you call "Enhance" (whatever this may mean). Create your own project directory with the name like ENHANCE. Copy all files from XFMSAMPL to ENHANCE.
Next, I'll show you how to customize it (i.e. what strings should be changed so that your plug-in wouldn't be confused by CoolEdit (or by yourself) with their original sample plug-in). Then, I'll explain the important functions and fields in Syntrillium API data structures. Then, hopefully, figuring out the rest will be just piece of cake for you. :-)

Customizing

n MSVC (i.e. Microsoft Visual C++), open the project file DISTORT.MDP (all files I refer to here are located in your new ENHANCE directory). It was created by Syntrillium using MSVC 4.0, so it's the older project, and your MSVC will convert it to the newer format and will create the workspace file DISTORT.DSW which you will be using instead of DISTORT.MDP after that.
Open DEF file (DISTORT.DEF) and change the string

LIBRARY Cool32*Distort

LIBRARY ENHANCE

(or to whatever name your plug-in uses).

Now open the file DISTORT.C. Find the line

#define TRANSFORMNAME "Distortion"

and change it to

#define TRANSFORMNAME "Enhance"

Find the line

lstrcpy(cq->szCopyright,"");

and change it to

lstrcpy(cq->szCopyright,"John Doe");

(or whatever your name happens to be). :-)

Find the line

lstrcpy(cq->szToolHelp,"Add Distortion/Grunge/Overdrive effects");

and change it to

lstrcpy(cq->szToolHelp,"My Enhance plug-in");

Right-click on the line Distort files in the Workspace window of MSVC, select Settings... in the menu that shows up. Then click on the Link tab and change in the "Output file name" fiels the name "distort.xfm" to "enhance.xfm". Do this both in "Settings for Win32 Release" and in "Settings for Win32 Debug". The "enhance.xfm" file will be the one you'll copy to the CoolEdit installation directory to make it work with CoolEdit (see below). If you want to work with single channel (left or right) or mono data only, find the line

cq->wSupports=XFM_MONO16|XFM_STEREO16;

and change it to

cq->wSupports=XFM_MONO16;

If you write the simple plug-in just for your own use, you may not to want to bother to use the setting dialog (the one which sets parameters, shows presets etc.). In such case, you may delete all lines in the the body of the function XfmSetup and put there the single line:

return TRUE;

If you do this, delete also everything in the body of the function XfmDestroy and everything in the body of XfmInit except the line (in the latter):

return TRUE;

(Of course, it's kind of un-clean way of doing this. If you'd do a good job, you'd find and delete the functions that are called from the original XfmInit only, and get rid of unneeded data types definitions and memory allocations/deallocations. But this will only optimize things, it won't change anything in a critical way, so I'll leave it to the reader as an exercise :-) .)

The main function that does the actual transform is called XfmDo. You may wish to delete (or comment out) everything in it's body except the line:

return 0;

You'll be writing then your own code there, probably consulting the original text (which you still have in the XFMSAMPL directory).

Functions and Data Fields

he API functions you will be using most often (and probably the only ones you'll be using at all) are these:

ReadData - to get the wave data from CoolEdit
WriteData - to write back your changed wave data to CoolEdit
ProgressCreate - to create the progress indicator that shows how much time is left
ProgressMeter - to update the progress indicator (hint: if you call this function on every data point, it's going to slow down the processing noticeably; you'd wish to call it on every 100th or 1000th point instead)
ProgressDestroy - to close the progress indicator after the processing is finished.

Read the descriptions of these functions in the Syntrillium APIS96.DOC file. Actually, it would be a good idea at this point to read the beginning of the chapter "Making your own effects modules" in APIS96.DOC.

Now, the data structures.

The main one (and probably the only one you'll need) is COOLINFO structure. See it's description either in APIS96.DOC or in XFMS.H file. The pointer to this structure is passed to XfmDo, and then you pass the same pointer to the API functions.

The field ci->wChannels will be set to either 1 or 2. If it equals 1, then the mono data has been passed to you (that is, the user selected the wave only in one channel); if it's 2, then the stereo data.

You get that data by calling ReadData. Before calling it, though, you have to allocate the memory buffer big enough to hold the data. If, for example, you use 16-bit wave data (i.e. if ci->wBitsPerSample==16) then the size of the buffer may be determined as

sizeof(short) * ci->wChannels * (ci->dwHiSample-ci->dwLoSample+1)

The more universal way of determining the data buffer size would be

ci->wBlockAlign * (ci->dwHiSample-ci->dwLoSample+1)

ci->wBlockAlign is the size of data for one sample (either stereo or mono, 8 or 16 bits); it will be set by CoolEdit and passed into XfmDo.
ci->dwLoSampl and ci->dwLoSampl are the indexes of wave points in the file being edited in CoolEdit - the first one and the last one in the selection; they will be set by CoolEdit and passed into XfmDo. Of course, CoolEdit copies to you only the selected part of the wave, so the index 0 in the buffer will correspond to the index ci->dwLoSampl in the wave data for the whole file.

Interpretation of the wave data (i.e. the contents of the data buffer filled by the call to ReadData) is simple.

If it's mono data, then the wave points are stored sequentially, each word (for 16-bit wave) or each byte (for 8-bit wave) representing the sample. It's the signed value, ranging for 16-bit wave from -32767 to +32767.

If it's stereo data, then the pairs are stored sequentially, first in the pair being the value for the left channel, second - for the right one. You may wish to define the structure like this:

typedef struct { short l; short r; } SAMPLE16S, *pSAMPLE16S;

then cast the pointer to your data buffer to (pSAMPLE16S) for convenient access to the points.

For more advanced details, look into APIS96.DOC file and the original Syntrillium sample code. Their samples are written in quite readable way, not hard to understand once you know the basics I described here.

After Compiling

ow to make CoolEdit recognize your plug-in after you've compiled it? It's simple.
In the sub-directory Debug (if you did a debug build) or Release (if you did a release build) of your ENHANCE directory you will find the file ENHANCE.XFM. (I assume here that you did change the project settings as described above). Copy this file to your CoolEdit installation directory and restart CoolEdit.
If you did everything I told about in the "Customizing" chapter, you will see the new item "Enhance..." in CoolEdit's "Transform" menu. It will be grayed out if you don't have any wave selected.

One last thing. If you'd wish to set the button on the CoolEdit toolbar for your plug-in, you'd also have to edit the bitmap used for the button. It may be found in the project resources. Click on the "ResourceView" tab in MSVC workspace window to find the bitmap to edit.

	Good luck!
	Copyright 1999, Evgueni Tchetchetkine Mail to che@parascript.com