TweetFollow Us on Twitter

After Effects Plugins

Volume Number: 15 (1999)
Issue Number: 9
Column Tag: Programming Techniques

How to Write Plug-Ins for Adobe After Effects

by Kas Thomas

Creating custom video f/x for Adobe's bestselling video-compositing program is surprisingly easy

If you've ever marveled at the stunning visuals in those 15-second bumpers for shows on the Discovery Channel, A&E, or MTV, it may surprise you to know that many of them were created on the Mac, using off-the-shelf software - namely, Adobe After Effects.

After Effects is the Swiss Army knife of video post-production, offering a powerful, intuitive, layer-based approach to compositing in which variable-opacity masks and keyframe-based motion control can be used to create stunning video effects.

As with Photoshop (Adobe's 2D graphics editor), much of the power of After Effects comes from its extensive use of plug-ins - external code resources that augment the functionality of the core program. Plug-ins for After Effects are similar to plug-ins for Photoshop in that most are image filters that batch-process pixels to achieve effects like blurring, sharpening, contrast enhancement, etc. The big difference, of course, is that plug-ins for After Effects operate not only in the image domain but the time domain as well. An After Effects filter may be invoked dozens, hundreds, or even thousands of times, sequentially, as frames of video are processed into final footage. An effect may last a split-second, or several minutes. During that time, individual filter parameters may ramp up or down or undergo any number of changes (or no change at all).

Since After Effects filtering occurs entirely offline, the effect can be as simple - or as computationally intense - as the programmer wants it to be; the calculations don't have to occur in real time. (This is in contrast to QuickTime-API effects, which are implemented as image decompressors and must occur in real time.) This means an After Effects filter can tackle some fairly lofty tasks, such as:

  • Synthesis of complex, animated textures for use as backgrounds. (This is a so-called zero-source type of effect.)
  • Traditional single-source image filtering. (Blurring, sharpening, contrast enhancement, gamma adjustment, color-shifting, addition or removal of noise, etc.)
  • Dual-source image filtering. (Wipes, fades, dissolves; complex matte effects.)
  • Warping, morphing, and distortion-mapping effects.
  • 3D effects.
  • Particle systems and physics simulations.
  • Audio processing. (New in version 4.0.)

As with Photoshop plug-ins, writing plug-ins for After Effects offers a number of advantages for the graphics programmer, including rapid development time, a stable host-program environment, freedom from having to worry about file I/O or format conversions, automatic Undo, automatic data buffering, and good code portability (thanks to a cross-platform API in which device and OS dependencies have been abstracted out). In addition, the After Effects plug-in API lets you build a solid, cross-platform user interface in minimal time, with minimal code. And you don't have to know a thing about QuickTime. The net result is that you're free to concentrate on special effects programming instead of worrying about event-loop code, file I/O, and other non-graphics issues.

But beyond all that, writing After Effects plug-ins is just plain fun. Creating Photoshop filters can be a blast, but the first time you see a custom video effect of your own design come alive on the screen, you'll be transfixed, like a deer in headlights. In fact, you may never look at video the same way again.

The After Effects SDK

To develop plug-ins for After Effects, you'll need a copy of the After Effects plug-in SDK, which is available from Adobe's web site (see <>); or you can get it on CD-ROM by joining the Adobe Solutions Network Developer Program (formerly the Adobe Developers Association). Joining the ASN Developer Program is worth considering, because for $195/yr. you not only get CD-ROM updates for all the current Graphics & Publishing SDKs (i.e., SDKs for Photoshop, Premiere, After Effects, Illustrator, InDesign, etc.), but you also qualify to obtain a full version of any Adobe product for just $99 - including After Effects itself.

If you can't get the SDK on CD, plan on downloading several megabytes of material from Adobe's web site. You'll end up with around four megs of quite useful .pdf documentation, plus an equal amount of C/C++ sample code and headers. Most of what you need to know is covered in the 82-page AE 4.0 SDK Guide, updated in January '99 to reflect the changes that occurred with After Effects 4.0. Additional docfiles talk about Adobe's Plug-In Component Architecture (PICA), 'PiPL' resources, and sundry other matters.

Compared to the Photoshop plug-in specification (which has become quite complex; see my two-part article in the April and May 1999 issues of MacTech), the After Effects API is lean and mean - a Porsche 911 in a world of London double-decker buses. "But don't Photoshop and After Effects use the same basic plug-in API?" you may be asking. Actually, the two programs have entirely different plug-in architectures. After Effects does emulate the Photoshop 3.0 plug-in API, but native After Effects plug-ins use a dedicated API which is not recognized by Photoshop. (This shouldn't come as a surprise, since video effects have a time domain and respond to keyframe and track data - things a Photoshop plug-in wouldn't know anything about.) Technically, it is possible to make a Photoshop plug-in respond to After Effects keyframes, using a kluge called the 'ANIM' resource. The 'ANIM' resource spec is described on pages 21-24 of Adobe's Plug-In Resource Guide (see the SDK), if you're interested. The advantage of the 'ANIM' resource is that if you've already written and debugged a Photoshop filter, you can convert it to a video filter by merely crafting a resource rather than writing more code. But in most cases you should write to the After Effects API, which allows access to standard AE user controls and a variety of callbacks that aren't present in the Photoshop API.

Two Basic Components

There are two basic components to an After Effects plug-in: a 'PiPL' resource, and executable code. The 'PiPL' (or plug-in property list) resource, as you may recall from my article on Photoshop plug-ins (MacTech, April '99), is an extensible structure for representing a plug-in's metadata - information about the plug-in's version, mode of operation, menu and submenu names, image modes supported (RGB, CMYK, etc.), how the host program should interpret alpha channel data, etc. The detailed specification is given in Adobe's Plug-In Resource Guide. In addition, the SDK contains Rez scripts and compiled resources for the example projects. Resorcerer recognizes 'PiPL' resources and will be a help in editing them. ResEdit is no help at all.

The reason the 'PiPL' resource is so important is that this is the first thing the host (After Effects) examines when it scans available plug-ins. It's how the host locates the plug-in's entry point and also how it determines whether the file is a legitimate plug-in at all (and if so, which menu it belongs in). Years ago, the plug-in's filetype was the determining factor in identifying plug-ins, but that's not how it works any more. For a plug-in to work right, the 'PiPL' has to be correct.

After Effects now supports three main plug-in types: Filter, Input/Output, and (with version 4.0) Foreign Project File plug-ins. (The latter was created so that After Effects could import Premiere projects.) The 'PiPL' tells After Effects what kind of plug-in it is dealing with, which menu or submenu it should appear in, and what name to give it in the submenu.

In terms of filetypes, a native After Effects plug-in will have a filetype of 'eFKT' (and a creator type of 'FXTC'), but this is merely a convention, not a requirement. In terms of code, an After Effects plug-in is compiled as a Shared Library module on the Mac or a DLL under Windows, with an entry point of main; and as a practical matter all After Effects filters for the Mac are now compiled as PPC-native, since the After Effects SDK no longer supports 68K code (as of version 4.0).

How a Plug-in Works

When After Effects is launched, it looks for plug-ins in all subdirectories of its path, recursively descending up to 10 levels deep. MacOS aliases are resolved and all folders are checked except any with names surrounded in parentheses, such as "(Old Plug-ins)". Note that no executables are actually loaded at this point; rather, After Effects caches a list of available plug-ins and loads them dynamically as the needarises. Unlike Photoshop, however, After Effects doesn't unload a plug-in after it is used. That's because in a piece of video footage, a plug-in might have to be invoked hundreds or even thousands of times, sequentially, and to unload and reload it thousands of times would be inefficient. (Tip: During development, if you need to flush After Effects' plug-in cache so that you can load a new version of your plug-in at program run time, without having to quit and relaunch After Effects, hold down the Control and Clear keys.)

All After Effects plug-ins have a single entry point, main(), which is called repeatedly with selectors indicating the desired action. The prototype for main() looks like this:

PF_Err main (PF_Cmd  cmd,
		PF_InData  *in_data,
		PF_OutData *out_data,
		PF_ParamList params,
		PF_LayerDef *output,
		void 		 *extra);

The first argument is a selector whose value represents the stage of execution that the plug-in is about to enter.

The second argument to main is a pointer to a large data structure containing host-application state information and hooks to callbacks.

The third parameter is a pointer to a structure that serves as a way for the plug-in to communicate its needs to the host. For example, error messages can be passed back to the host via the return_msg field. (See AE_Effect.h for the complete typedef.)

The params argument is where the plug-in gets access to its user-specified parameter values - for example, the value of sliders or controls in the Effects Control Window (ECW). In other words, all of your user interface info is cached here. We'll have more to say about this is a minute.

The output parameter points to a PF_LayerDef struct, which contains information about the output image (including a pointer to its data): its dimensions, its rowbytes value, and the extent_hint, which is a Rect giving the bounds of the area that actually needs rendering. (This is often just a subset of the overall image.) Don't confuse the PF_InData and PF_OutData structs with pointers to pixel data; images are represented by the PF_LayerDef, also sometimes called a PF_World.

Finally, the extra pointer is a special-use parameter that went largely unused prior to After Effects 4.0. It points to different data structures at different times (and garbage, at other times). You'll only deal with this parameter if you decide to implement custom user interface elements and/or complex custom data types.

The possible selector values for cmd are:

enum {		
	PF_Cmd_ABOUT = 0,			

Of these, most plug-ins will only ever have to respond to PF_Cmd_ABOUT, PF_Cmd_GLOBAL_SETUP, PF_Cmd_PARAMS_SETUP, and PF_Cmd_RENDER. All plug-ins are expected to respond to these four selectors. (The usage of the other selectors is well-documented not only in the SDK docfiles but in the header files as well.) We'll go over some of these as we step through our code, below.

Code Project: Warbler

Because of the power and sophistication of the API, it's possible to create a useful After Effects plug-in with less than 400 lines of C code; hence, in this article we're going to present the entire code for a complete plug-in (also available online at Our sample plug-in, called Warbler, duplicates the function of Adobe's Displacement Map plug-in, which is not included in the $995 retail distribution suite for After Effects but is included in the $2,195 Production Bundle. Warbler is a displacement-map effect that uses one image layer to distort another layer. The key concept here is that for every pixel of our source image, we check the corresponding pixel of a "map" image, and if the map-image pixel is white, we displace our source-image pixel in one direction, while if the map pixel is black, we displace the source pixel in the opposite direction. (In reality, we don't push any source pixels around; rather, we index into different parts of the source image - i.e., we displace the offset into our image, rather than the pixel. Also, we don't rely on black or white pixels in the map image. Instead, we look at the luminance of each pixel, and calculate a displacement value that is proportional to the map pixel's luminance.) To give a good visual result requires that we resample pixels with subpixel accuracy, which means we need to perform between-pixels interpolation (as discussed in the Photoshop plug-ins article in the May '99 MacTech). Fortunately, the After Effects API offers a ready-made function that accomplishes this for us.

The effect produced by Warbler is best understood by referring to Figures 1, 2, and 3. Figure 1 shows a test image consisting of a large number of horizontal lines. Figure 2 shows an image of bullseye-style concentric rings which vary sinusoidally in pixel intensity. If we let Figure 2 be our map image (which determines how we "push the pixels around" in Figure 1), the result of applying our Warbler plug-in is the image in Figure 3. Note how the formerly parallel horizontal lines now seem to show concentric waves, like ripples in a pond. This is diplacement mapping.

Bear in mind, of course, that in After Effects, each image is actually a frame in a sequence, which can change over time. By animating the map image, distortions in the source image can be made to animate as well - which means that if you're clever, you can achieve a variety of interesting visual effects (pond ripples, flag ruffles, puckering, bulging, bending) in the visible layer(s) of a video just by animating an invisible map layer.

Figure 1. Source image.

Figure 2. Map image.

Figure 3. Warbled source image.

Code Walkthrough

Listing 1 gives all the #defines and #includes for our project, along with code for our About handler. By convention, all handler functions are prototyped as

static PF_Err FunctionName (
	PF_InData		 *in_data,
	PF_OutData		 *out_data,
	PF_ParamDef		*params[],
	PF_LayerDef		*output );

even though, in many cases, the passed-in pointers are not used. The return value is always a PF_Err (long) so that user aborts and other error conditions can be passed back, through main(), to the host.

In About(), we make use of the PF_SPRINTF macro (defined in AE_EffectCB.h) to send a DESCRIPTION string back to the host. After Effects responds by putting up a simple modal dialog containing our "about" information. No 'DITL' or 'ALRT' resources are needed.

Listing 1: About() and #defines

Constants, macros, and includes for our plug-in, plus our About handler.

#include "AE_EffectCB.h"
#include "AE_Macros.h"

#define	NAME	"Warbler"
#define	MAJOR_VERSION		2
#define	MINOR_VERSION		1
#define	BUG_VERSION			0
#define	BUILD_VERSION		0

#define LONG2FIX(x) (((long)x)<<16)
#define LUMA(p) \
	(double)(p->red + 2*p->green + p->blue)/(255. * 4.)
#define bias(a,b) \
	PF_POW( (a), PF_LOG(b) / PF_LOG(0.5) )
#define ANGLE_MIN		(-180L << 16)
#define ANGLE_MAX		( 180L << 16)
#define	BIAS_MIN		(655)	// 0.01 Fixed 
#define	BIAS_MAX		(1L << 16)
#define	BIAS_BIG_MAX	(10L << 16)
#define	BIAS_DFLT		(6553*5) // about 0.5 Fixed
#define	SHIFT_BLEND_MAX	(1L << 16)

enum {

"Displacement mapping based on luminance."

// --------------- About() --------------
static PF_Err About (
	PF_InData		*in_data,
	PF_OutData		*out_data,
	PF_ParamDef		*params[],
	PF_LayerDef		*output )

	PF_SPRINTF(out_data->return_msg, "%s,v%d.%d\r%s",
	return PF_Err_NONE;

Listing 2 shows the plug-in's entry point, main(). This routine simply cases out the selector value and dispatches to the appropriate handler function. Warbler responds to just the five selector values shown, ignoring any others that are sent.

Listing 2: main()

main() Dispatch to the appropriate handler and report any errors to the host.
PF_Err main (
	PF_Cmd				cmd,
	PF_InData		*in_data,
	PF_OutData		*out_data,
	PF_ParamDef	*params[],
	PF_LayerDef	*output,
	void					*extra )
	PF_Err		err = PF_Err_NONE;
	switch (cmd) {
	case PF_Cmd_ABOUT:
		err = About(in_data,out_data,params,output);
		err = GlobalSetup(in_data,out_data,params,output);
		err = ParamsSetup(in_data,out_data,params,output);
		err = GlobalSetdown(in_data,out_data,params,output);
	case PF_Cmd_RENDER:
		err = Render(in_data,out_data,params,output);

	return err;

It turns out, our plug-in is comprised of only seven functions altogether: main() itself, the five dispatch functions shown inside main(), and an iteration function called DisplaceImage(), where the real work takes place. We've already talked about two of the seven functions. Two more are shown in Listing 3 - namely, GlobalSetup() and GlobalSetdown().

In GlobalSetup(), which gets called when the plug-in is first loaded, we need to do three things: allocate any global data we might need (attaching it to the global_data Handle in the PF_OutData struct), report our version information to the host (via the my_version field of the PF_OutData struct), and set any flags that might be needed to convey our preferences to the host (via out_flags). Warbler doesn't allocate any memory, so all we do in GlobalSetup() is report the version info and set a flag. It's necessary to report the version information because After Effects will check this information against the version numbers given in our 'PiPL' resource, and if the two don't match, the plug-in won't load. (Remember this when debugging!)

The out_flag field of our PF_OutData record can be set to indicate a number of special requests. In our case, we want the image's output extent, which is the Rect giving the bounds of the portion of the image that's actually visible. This can save a lot of unnecessary computation when the source image is larger than the active screen area. Other flags can be set to let the host know that (for example) your plug-in wants to receive event messages, generate audio effects, overwrite the input buffer, etc. See the SDK documentation for details.

Listing 3: GlobalSetup() and GlobalSetdown()

GlobalSetup() and GlobalSetdown()
static PF_Err GlobalSetup (
	PF_InData		*in_data,
	PF_OutData		*out_data,
	PF_ParamDef	*params[],
	PF_LayerDef	*output )
	PF_Err	err = PF_Err_NONE;

	// We need to let AE know what version we are: 
	out_data->my_version = 

	// We are going to iterate over the output extent,
	// so we need to specify that flag...
	out_data->out_flags |= 

	return err;

//---------------- GlobalSetdown() ----------------
// This is empty since we haven't allocated any global data.

static PF_Err GlobalSetdown (
	PF_InData		*in_data,
	PF_OutData		*out_data,
	PF_ParamDef	*params[],
	PF_LayerDef	*output )
	return PF_Err_NONE;

The User Interface

In order to enforce consistent behavior and a consistent appearance among plug-ins, After Effects imposes certain user-interface requirements on filters (which you can certainly circumvent if you want to, although in 99% of cases you'd be foolish to do so). All user interfaces for all effects in a given layer show up in that layer's Effects Control Window (ECW), which is a kind of master view window in which individual filters appear as vertically stacked panes, with the flow of control going top-to-bottom. (The output of each effect is pipelined to the next effect in the stack - and the Comp Window continuously updates to show the net effect of the stack of filters. No preview pane is necessary inside a filter, because the Comp Window already serves that purpose.) Control elements like checkboxes, sliders, etc. look identical (except for labelling) from one effect to another.

At first blush, all this may sound rather stifling, but in fact there are compensating benefits for the programmer. The main benefit is that you get a user interface virtually for free, because the After Effects plug-in API has provisions for setting up sliders, checkboxes, color pickers, drop-down menus, etc., with very little code. After Effects takes care of all the details of intercepting mouse hits, making sure controls operate correctly, caching all the control settings, linking control settings to keyframes, bounds-checking all parameter values (and presenting validation alerts to the user), and so on. All you have to do is tell After Effects how many of each kind of control you'd like, and in what order they should appear - then at render time, the bounds-checked parameter values are handed to you.

Listing 4 shows how UI controls and their default settings are specified, in the ParamsSetup() function. (This function will be entered whenever a new instance of the plug-in is requested by the user.) The drill here is to declare a PF_ParamDef, zero it out, then start filling in the appropriate fields, starting with the param_type, then call the macro PF_ADD_PARAM(), which tells After Effects to add this parameter to an array of parameters for our plug-in.

The API allows for eleven different types of controls (or parameters), including not only checkboxes and sliders but popup menus, "angle" controls (which give angles in degrees), "point" controls (which give an x, y offset into the image), color pickers, and provisions for custom control types. The one glaring omission in this list is the radio button. (For modal choices, you're evidently supposed to use a popup menu.)

In Warbler, we specify a Layer parameter (which is a popup menu containing the names of all available image layers, including the one to which the effect is being applied), an Angle picker, and three sliders. Figure 4 shows what the final user interface looks like.

Figure 4. The Warbler user interface includes a popup menu, an angle picker, and three sliders.

Before starting, we zero out our PF_ParamDef by means of an Adobe-supplied macro called AEFX_CLR_STRUCT(). Failure to do this can result in unpredictable behavior.

Next, we create the Layer parameter. This will be a popup menu enabling the user to select an image layer to act as the displacement map. The choices offered here will represent all available layers (including those not visible) in the current project; After Effects builds and updates the menu for us dynamically.

The Angle control (the circular-shaped object in Figure 4) is created next, by specifying the PF_Param_ANGLE control type, a name for the control, a default value (zero), minimum and maximum valid values, and calling PF_ADD_PARAM. This control lets the user specify (either by dragging a dot around a circle, or by entering a text value) an arbitrary angle for the displacement effect.

All three of our sliders are of type PF_Param_FIX_SLIDER, which returns a Fixed value (with however many decimal points of precision we want the user to see). You can also specify a PF_Param_SLIDER, which returns a long value. The first of our sliders controls the amount of displacement effect, from zero to 100%, in tenths of a percent. Our second slider will let the user adjust the gamma of the map image, so as to sharpen or widen out the displacement effect. For this, we specify a valid range of zero to 1.0, with a default value of 0.5.

Our third slider governs the degree to which the filtered image should be blended with the original (unfiltered) image. This control is one that Adobe says every plug-in should support. Certainly, most users expect it.

Listing 4: ParamsSetup()

This function tells After Effects what kinds of controls we want to
have in our user interface, and their default values.

static PF_Err ParamsSetup (
	PF_InData		*in_data,
	PF_OutData		*out_data,
	PF_ParamDef	*params[],
	PF_LayerDef	*output)
	PF_Err				err = PF_Err_NONE;
	PF_ParamDef	def;	

	// Always clear out the PF_ParamDef
	// before adding your parameters.

	// Create the LAYER parameter... 
	def.param_type = PF_Param_LAYER;
	PF_STRCPY(, "Displacement Layer:");
	def.u.ld.dephault = PF_LayerDefault_NONE;
	if (err = PF_ADD_PARAM(in_data, -1, &def)) 
		return err;
	// Create the ANGLE parameter...	
	def.param_type = PF_Param_ANGLE;
	PF_STRCPY(, "Angle of Displacement");
	def.flags = 0;
	def.u.fd.value_str[0] = 
		def.u.fd.value_desc[0] = '\0';
	def.u.fd.value = def.u.fd.dephault = 0;
	def.u.fd.valid_min = 
		def.u.fd.slider_min = ANGLE_MIN;
	def.u.fd.valid_max = 
		def.u.fd.slider_max = ANGLE_MAX;
	def.u.fd.precision = 0;
	def.u.fd.display_flags = 0;	
	if (err = PF_ADD_PARAM(in_data, -1, &def))
		 return err;
	// Create the DISPLACEMENT SLIDER...	
	def.param_type = PF_Param_FIX_SLIDER;
	PF_STRCPY(, "Amount of Displacement");
	def.flags = 0;
	def.u.fd.value_str[0] = 
		def.u.fd.value_desc[0] = '\0';
	def.u.fd.value = 
		def.u.fd.dephault = SHIFT_BLEND_DFLT;
	def.u.fd.valid_min = 
		def.u.fd.slider_min = SHIFT_BLEND_MIN;
	def.u.fd.valid_max = 
		def.u.fd.slider_max = SHIFT_BLEND_MAX;
	def.u.fd.precision = 1;
	def.u.fd.display_flags = 1;	// display as percent 
	if (err = PF_ADD_PARAM(in_data, -1, &def)) 
		return err;

	// GAMMA slider...
	def.param_type = PF_Param_FIX_SLIDER;
	PF_STRCPY(, "Source Gamma");
	def.u.fd.value_str[0] = 
		def.u.fd.value_desc[0] = '\0';
	def.u.fd.value = 
		def.u.fd.dephault = BIAS_DFLT;
	def.u.fd.valid_min = 
		def.u.fd.slider_min = BIAS_MIN;
	def.u.fd.slider_max = BIAS_MAX;
	def.u.fd.valid_max = BIAS_BIG_MAX;
	def.u.fd.precision = 1;
	def.u.fd.display_flags = 0;
	if (err = PF_ADD_PARAM(in_data, -1, &def)) 
		return err;

	// Create the FIXED SLIDER parameter...	
	def.param_type = PF_Param_FIX_SLIDER;
	PF_STRCPY(, "Blend With Original");
	def.flags = 0;
	def.u.fd.value_str[0] = 
		def.u.fd.value_desc[0] = '\0';
	def.u.fd.value = 
		def.u.fd.dephault = SHIFT_BLEND_DFLT;
	def.u.fd.valid_min = 
		def.u.fd.slider_min = SHIFT_BLEND_MIN;
	def.u.fd.valid_max = 
		def.u.fd.slider_max = SHIFT_BLEND_MAX;
	def.u.fd.precision = 1;
	def.u.fd.display_flags = 1;	// display as percent 
	if (err = PF_ADD_PARAM(in_data, -1, &def)) 
		return err;

	// Set number of parameters...
	out_data->num_params = SHIFT_NUM_PARAMS;

	return err;

The Render Function

When a filter is actually applied to a frame or a portion of an frame, After Effects calls the plug-in with a selector value of PF_Cmd_RENDER. At this point, it's the plug-in's responsibility to retrieve the current parameter values, filter the image, and return control to the host. We accomplish this in our Render() function, shown in Listing 5.

Once we know our slider values, we should be able to loop over all the pixels in the image and perform the necessary filtering. We'll be doing essentially that, but with a twist. It turns out the API will set up a pixel-iteration loop for us, and perform our filtering for us, if we'll simply provide a pointer to our main pixel-modification routine. (You'll see how this works in a minute.) Our plan of action, therefore, will be to put our user parameters (and pointers to a few other items) into a custom data struct, then pass a pointer to that struct to our iteration function. The custom data struct will look like this:

typedef struct {

	Fixed				x_off;		// displacement in x
	Fixed				y_off;		// displacement in y
	double				gamma;
	long					width;
	long 				height;
	PF_World 	 *p;

	// structures and function pointer 
	// needed for for image resampling:

	PF_SampPB	 	samp_pb;
	PF_InData	 *in_data;
	PF_ParamDef *checkedOutLayer;	

} ShiftInfo;

Prior to telling us to render, After Effects will have cached our user's parameter values for us, internally, in an array of ParamDefs. After Effects gives us access to that array via a pointer provided as the fourth argument to main(). It's up to us to index into that array to retrieve our user params.

The ParamDef is an After Effects data record that contains a data type called a PF_ParamDefUnion. That union, in turn, looks like this:

typedef union {
	PF_LayerDef			ld;
	PF_SliderDef			sd;
	PF_FixedSliderDef	fd;
	PF_AngleDef			ad;
	PF_CheckBoxDef		bd;
	PF_ColorDef			cd;
	PF_PointDef			td;
	PF_PopupDef			pd;
	PF_CustomDef			md;
} PF_ParamDefUnion;

The interesting thing about this union is that all of the members are user-interface control types - except the first item, which is a PF_LayerDef. We've already mentioned that a PF_LayerDef is equivalent to a PF_World, which is a representation of an image. Up to this point, we've been using the terms "parameter" and "control" more or less interchangeably, but in fact we now see that, to After Effects, a parameter can be a slider, checkbox, etc., or it can be an image. And in the ParamDef array that After Effects maintains for us (containing slider values and other user parameters), the first entry - array item zero - is always a PF_LayerDef: specifically, the PF_LayerDef for the image layer we're operating on (the input image). This will be important in a minute.

Now let's look at the first few lines of code in Listing 5. The first user control is an angle picker - a PF_AngleDef. To retrieve the value of this control, we do:

angle = (double)params[DISP_ANGLE]->;

Recall from Listing 1 that at the top of our file, we declared an enum with DISP_ANGLE as one of the constants. This lets us index into the ParamDef array at the proper point. The 'u' field in the line of code above refers to the PF_ParamDefUnion mentioned above. The 'ad' field is for AngleDef. And finally, the value of the AngleDef is in a field called (what else?) value.

It turns out that AngleDef values are typed as Fixed, so in order to convert that representation to a long or double, we have to divide by 65,536. (You'll find that the After Effects API uses a lot of Fixed numbers.) The result is in degrees, which means that in order to convert the value to radians, we have to multiply by the predefined constant PF_RAD_PER_DEGREE. Then it's a simple matter to convert the angle to sine/cosine representation. Notice that we rely on the API macros PF_SIN and PF_COS, rather than calling math routines. That way, we don't have to include any ANSI math libraries in our project.

The sine and cosine numbers are ultimately converted to x-offset and y-offset values, which we will use in our displacement routine. The magnitude of the offset values is dependent not only on the sine/cosine of the user-chosen displacement angle, but also the value of the SHIFT_DISPLACE_AMT slider. To get this slider value, we index into the ParamDef array at an offset of SHIFT_DISPLACE_AMT (per the enum from Listing 1), where we expect to be able to find a PF_FixedSliderDef ('fd') in the PF_ParamDefUnion 'u'. Again, the 'value' field is what we're after.

To get our gamma slider value, we index into the ParamDef array at an offset of SHIFT_GAMMA (per the enum from Listing 1), and for the blend amount, we similarly check the ParamDef array at an offset of SHIFT_BLEND. The gamma value has to be converted from Fixed to double, but the blend amount is left as Fixed, because we'll be using it in a callback that expects a Fixed value.

For convenience, we want to cache the source-image dimensions in our custom data struct, which we accomplish with the lines of code:

	si.width = params[0]->u.ld.width;
	si.height = params[0]->u.ld.height;

Here, we're indexing into the ParamDef array at an offset of zero. (Remember earlier when we said that the first array entry is always a LayerDef representing the input image?) At this offset, the union 'u' has a LayerDef 'ld' containing our source image's height and width.

To make life easier in our iteration function, we'll cache the address of the input LayerDef as well as the in_data pointer provided as the first argument to Render(). The latter will be needed by several API callbacks.

Listing 5: Render()

Grab our user parameters, store them in a custom data struct, and iterate or blend.

static PF_Err Render ( 
	PF_InData			*in_data,
	PF_OutData			*out_data,
	PF_ParamDef		*params[],
	PF_LayerDef		*output )
	PF_Err				err = PF_Err_NONE;
	ShiftInfo		si;
	Fixed				blend;
	short				lines;
	PF_World			*input;
	PF_ParamDef	checkout;
	double				angle,sin_angle,cos_angle;
	angle = (double)params[DISP_ANGLE]->;
	angle /= (double)(1L << 16); 
	angle *= PF_RAD_PER_DEGREE;
	sin_angle = PF_SIN(angle);
	cos_angle = PF_COS(angle);
	si.x_off = 
		params[SHIFT_DISPLACE_AMT]->u.fd.value * sin_angle * 100.;
	si.y_off = 
		params[SHIFT_DISPLACE_AMT]->u.fd.value * cos_angle * 100.;
	si.gamma = 
		(double) params[SHIFT_GAMMA]->u.fd.value / (double)(1L << 16);
	blend = params[SHIFT_BLEND]->u.fd.value;

	si.width = params[0]->u.ld.width;
	si.height = params[0]->u.ld.height;
	si.p = input = 
		si.samp_pb.src = &params[0]->u.ld;
	si.in_data = in_data;

	// get access to our map layer
	err = PF_CHECKOUT_PARAM(in_data, 

	if (err) 
		return err;
	si.checkedOutLayer = &checkout;
	if (! {		// nothing to do
		err = PF_COPY(input, output, NULL, NULL);

	} else { 		// otherwise, iterate and blend

		// calculate how many lines we'll iterate over
		lines = 
			output->extent_hint.bottom - output->;

		err = PF_ITERATE(0, lines, input, &output->extent_hint,
			(long)&si, DisplaceImage, output);
		// PF_ITERATE checks for user aborts, so...
		if (err) return err;
		err = PF_BLEND(output, input, blend, output);

	err = PF_CHECKIN_PARAM(in_data, &checkout);
	return err;

Checkout Time

Many times, in a plug-in you'll want to be able to have access not only to the image or frame you're modifying, but frames from other layers, possibly at different time offsets in the track. This is possible via a "check-out/check-in" mechanism provided by the After Effects API. The following line of code from Listing 5 shows how it works:

err = PF_CHECKOUT_PARAM(in_data, 

Here, we're calling an API macro, PF_CHECKOUT_PARAM, that exploits the checkout_param() callback routine, which is accessible through the in_data pointer. In this particular case, we're using it to access the layer selected by the user via a popup menu. The layer info we need will be returned to us in checkout, the final argument. (It's returned as a ParamDef instead of a LayerDef, but you'll recall that a ParamDef can contain not only controls but images.) If you look at the other arguments to the callback, you may surmise - correctly - that this callback can be used to gain access to the contents of any frame, at any time in any track. Thus, if you're writing a plug-in that needs to do motion blurs, echoes, frame differencing, track blending, etc., you would use this callback.

The important thing to remember is that after you've checked a layer (image; frame) out, you'll eventually need to check it back in again, with PF_CHECKIN_PARAM. Failure to do this will cause colossal (read: fatal) memory leakage.

Before using a checked-out layer, it's important to check the data field of the LayerDef to make sure it's not NULL. If it does happen to be NULL for some reason (like, the footage ended before that of the track you're working on), just PF_COPY your input image to the output and be done with it. (You still have to check the layer back in, though.)

The Iteration Callback

Normally, in an image filter, you expect at some point to set up a nested double loop and process all the pixels in the source image, one at a time. There are a couple ways to do that in an After Effects filter. The simplest and easiest way is to use the API's iterate() callback. The API provides a macro, PF_ITERATE, that performs the messy indirections needed to get at and use the callback. We use it as follows:

err = PF_ITERATE(0, lines, input, 
			(long)&si, DisplaceImage, output);

The first two arguments tell After Effects our starting and ending indices, so that a progress bar can be displayed and updated automatically, for us. The third argument is a pointer to our source image. The fourth argument is a pointer to a bounds Rect (so that we can just process a portion of an image, if we need to), while the fifth argument is a refcon that can be anything we want. In this case, we want it to point to our custom data structure with all our user-param values. The sixth argument is a pointer to our main pixel-manipulation function (where all the work takes place), and the last argument is a pointer to the output.

When we call PF_ITERATE, After Effects sets up a pixel-processing loop for us and calls our main crunch routine for each pixel. At first blush, this may sound like a terribly inefficient way to go, but it turns out to be surprisingly fast, because After Effects sets up an unrolled loop using line-start pointers (for speed). Also, RAM permitting, After Effects will actually do frame differencing and apply our effect only to pixels that have changed between scenes (carrying over unchanged output pixels from the last frame), automatically. (This behavior can be overridden.) If multiple CPUs are present, processing will be split up among them. Some impressive optimizations, in other words, are available with the iterate callback. It's by no means slow.

Since PF_ITERATE takes care of progress-bar updating and monitors for user aborts, it's important that we check the return value. A user abort should be passed back through main() to the host.

Pixel Processing

Listing 6 shows the pixel-processing function, DisplaceImage(), which is called by the iteration callback. The arguments include a refcon (which in this case stores the address of our ShiftInfo struct), the absolute x-y coordinates of the pixel currently being processed, a pointer to the input pixel, and a pointer to the output pixel. In After Effects, all pixels - regardless of bit depth - are represented in PF_Pixel format, which is simply four unsigned characters representing alpha, red, green, and blue channels, in that order.

The crux of this routine is the subpixel_sample() callback, which again - for clarity and convenience - we invoke by means of a macro:

	err = 

The first two arguments are absolute 'x' and 'y' pixel coordinates for the point in the image that we want to sample, given in Fixed format. That is to say, they are decimal (fractional-pixel) values. After Effects will do the necessary interpolation for us and hand us back a pointer to the PF_Pixel in the "out" argument (above). It can only do this, though, if you provide a pointer to a PF_SampPB struct containing a pointer to the image data (in the third argument). We arranged for this back in Render().

Listing 6: DisplaceImage()

This is where the real work is done. This function will be called for every
pixel in the source image.

static PF_Err DisplaceImage (long refcon, 
		long x, long y, 
		PF_Pixel *in, PF_Pixel *out)
	register ShiftInfo	*si = (ShiftInfo *)refcon;
	PF_InData					*in_data = si->in_data;
	PF_Err							err;
	Fixed							new_x, new_y;
	double 						luma,tmpx,tmpy;
	// check to see if we're near the edge...
	if ( LONG2FIX(x) < si->x_off || 
		 LONG2FIX(y) < si->y_off ||
		 LONG2FIX(si->width - x) < si->x_off ||
		 LONG2FIX(si->height - y) < si->y_off)
			*out = *in;	// just copy input & return
			return 0;
	// what fraction are we thru the image?
	tmpx = (double)x/(double)si->width;
	tmpy = (double)y/(double)si->height;
	// interpolate to the same spot in map layer image (Fixed)
	tmpx *= (double)si->checkedOutLayer->u.ld.width;
	new_x = LONG2FIX(tmpx);
	tmpy *= (double)si->checkedOutLayer->u.ld.height;
	new_y = LONG2FIX(tmpy);
	// set src pointer to map layer:
	si->samp_pb.src = &si->checkedOutLayer->u.ld; 
	// sample into the map layer:
	err = PF_SUBPIXEL_SAMPLE(new_x, new_y, &si->samp_pb, out);
	// reset src to INPUT layer:
	si->samp_pb.src = si->p;					 
	// get map-layer pixel luminance
	luma = LUMA(out);
	// apply gamma correction	
	luma = bias(si->gain,luma);	

	// make the displacement "grey-pt relative"
	// so map-layer pixels that are white move 
	// the input one way, black the other way...
	luma -= 0.5;
	new_x = ((long)x << 16);		// convert to Fixed
	new_y = ((long)y << 16); 	// convert to Fixed
	if (luma > 0.5)	{			// dark? move up or left
		new_x -= (si->x_off * luma);
		new_y -= (si->y_off * luma);
	else {								// light? move down or right
		new_x += (si->x_off * luma);
		new_y += (si->y_off * luma);
	// resample original image at the offset point
	// and write to output...
	err = PF_SUBPIXEL_SAMPLE(new_x, new_y, &si->samp_pb, out);

	return err;

In Listing 6, we begin by checking for edge conditions (so that we don't accidentally offset outside the valid image area). Next, we divide our absolute x-y coords by the image width and height to get a normalized floating-point index of how deep we are in the image, both horizontally and vertically. If we multiply this index by the absolute width/height of the map image, we can obtain absolute x-y coordinates at which to sample the map image. Everything is done in floating point and converted to Fixed, because the subpixel_sample callback does partial-pixel interpolation for us. (But only if After Effects is rendering in high-resolution mode. Draft mode defaults to integral-pixel sampling.)

After fetching our map pixel, we need to get its luminance, which we do with a macro (from Listing 1). The luminance is a floating-point number in the range of zero to one - which makes it very easy for us to apply a gamma correction, using the bias macro (Listing 1). Bias was discussed in the May '99 article on Photoshop filters. Basically, it's a simple, intuitive replacement for gamma that works by remapping the unit interval to itself non-linearly. For more gamma, you supply an input value in the range of 0.5 to 1.0. For less gamma, you supply an input value of from zero to 0.5. A value of exactly 0.5 simply remaps the data to itself unchanged.

Once our gamma-adjusted luminance has been calculated, we use it to scale our x- or y-offsets prior to resampling into the source image. Recall that the point of this whole exercise is to push pixels around in the source image based on luminance values in the map image. Rather than pushing pixels, we reindex into the source image at new locations determined by map-layer luminance values. We use the subpixel_sample callback again (this time on the source image) to do this.

And that, believe it or not, completes our code walkthrough of the complete source code for the plug-in.

The Result

The compiled plug-in is only 3,787 bytes in size, yet it implements every behavior required of an After Effects plug-in and has a fully functional user interface (with sliders and drop-down menu, no less). And the effect it implements - sophisticated layer-based displacement mapping - duplicates that of a plug-in found in Adobe's $2,195 Production Bundle. (For an example of the effect applied to a real image, see Figure 5.)

Figure 5. The bullseye map image from Fig. 2 has been applied to this image to give a pond-ripple type of effect using the Warbler plug-in.

By this point, I hope I've managed to convince you that writing video effects is not difficult at all (much easier than writing a Photoshop filter, in fact), and yet the rewards are immense. The After Effects API essentially gives your plug-in a GUI for free, which means you can devote more time to video effects and less time to dialogs, controls, event filters, etc. As a side benefit, all of your code is portable to Windows. (If you go back and look through the source code for Warbler, you'll see that no MacOS functions or managers were used.) Adobe has provided a tremendous API here for graphics effects developers - one that deserves to be more fully exploited by Mac programmers.

Look out, Discovery Channel!

Kas Thomas ( has been programming in C on the Mac since 1989 and has a shareware plug-ins page at


Community Search:
MacTech Search:

Software Updates via MacUpdate

FotoMagico 6.2.2 - Powerful slideshow cr...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
Default Folder X 5.7 - Enhances Open and...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click on... Read more
f.lux 42.1 - Adjusts the color of your d...
f.lux makes the color of your computer's display adapt to the time of day, warm at night and like sunlight during the day. Ever notice how people texting at night have that eerie blue glow? Or wake... Read more
Spotify - Stream music, creat...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
Vitamin-R 4.15 - Personal productivity t...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
OfficeTime 2.0.628 - Easy time and expen...
OfficeTime is time and expense tracking that is easy, elegant and focused. Other time keepers are clumsy or oversimplified. OfficeTime balances features and ease of use, allowing you to easily track... Read more
Slack 4.28.182 - Collaborative communica...
Slack brings team communication and collaboration into one place so you can get more work done, whether you belong to a large enterprise or a small business. Check off your to-do list and move your... Read more
DEVONthink Pro 3.8.6 - Knowledge base, i...
DEVONthink is DEVONtechnologies' document and information management solution. It supports a large variety of file formats and stores them in a database enhanced by artificial intelligence (AI). Many... Read more
FileMaker Pro 19.5.4 - Quickly build cus...
FileMaker Pro is the tool you use to create a custom app. You also use FileMaker Pro to access your app on a computer. Start by importing data from a spreadsheet or using a built-in Starter app to... Read more
Backblaze - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac. With unlimited storage available for $6 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more

Latest Forum Discussions

See All

SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for September 26th, 2022. In today’s article, we kick off the week with a bang. And by “bang", I mean four reviews. Family Man, Radiant Silvergun, The Legend of Heroes: Trails from Zero... | Read more »
‘Romancing SaGa: Minstrel Song Remastere...
Following its showing at TGS 2022, Square Enix has released a new gameplay trailer for the previously announced remaster of the PS2 remake of the Super Famicom original (yes) Romancing SaGa game, Romancing SaGa: Minstrel Song Remastered. | Read more »
Gamabilis reveal release date for realis...
Realistic Sims are very fun experiences and give gamers an excellent chance to experience other walks of life, and Gamabilis has released its hyper-real farm management game Roots of Tomorrow. Whilst the more arcade-type games like Stardew Valley... | Read more »
Best iPhone Game Updates: ‘Streets of Ra...
Hello everyone, and welcome to the week! It’s time once again for our look back at the noteworthy updates of the last seven days. We’ve got a nice mix of Apple Arcade, free-to-play, and even a proper paid game. We don’t see those often! So yes, a... | Read more »
The House of Da Vinci 3 launches on Andr...
Following its earlier release on iOS this year, The House of Da Vinci 3 has also officially launched on Android devices. Blue Brain Games' 3D puzzle adventure boasts an average rating of 4.9/5 and will give players the much-awaited conclusion to... | Read more »
‘Oxenfree: Netflix Edition’ Is Out Now o...
Over the weekend, Netflix and Nightschool Studio announced and released Oxenfree: Netflix Edition (Free) worldwide on iOS and Android. This new version of Oxenfree: Netflix Edition is a separate release, and the prior version that I own, is no... | Read more »
‘Genshin Impact’ Version 3.1 Update Pre-...
Genshin Impact (Free) version 3.1 ‘King Deshret and the Three Magi’ goes live in a few days across iOS, Android, PC, PS5, and PS4. As with prior updates, pre-installation for the upcate has just gone live a few days before release. | Read more »
We’re Digging ‘Shovel Knight Dig’ – The...
We spend the bulk of this week’s podcast talking about the new iPhone 14. Specifically, the iPhone 14 Pro Max which both Eli and myself picked up. The consensus seems to be: They’re great! They’re iPhones! We do lay down our hot takes on all the new... | Read more »
TouchArcade Game of the Week: ‘Loose Noz...
There aren’t a lot of stories like that of the development of Loose Nozzles, and of those games that do have an interesting development story, even fewer are actually decent games to play. Loose Nozzles nails both, though. The way it was created is... | Read more »
SwitchArcade Round-Up: ‘Shovel Knight Di...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for September 23rd, 2022. In today’s article, we’ve got the rest of this week’s releases to look at. There are actually a few big games today, including the hot-hot-hot Shovel Knight Dig... | Read more »

Price Scanner via

13-inch Apple MacBook Airs with M2 processors...
Amazon has 13″ MacBook Airs with M2 CPUs in stock today and on sale for $1099. Shipping is free. Their prices are $100 off Apple’s MSRP, and they are the lowest prices available for M2-powered Macs... Read more
AR Glasses That Work With Apple’s Hardware? T...
NEWS – Lenovo has created quite the spectacle(s) with its latest product. “Apple Glass” — the purported name of Apple’s forthcoming AR glasses — is not expected to be released until 2025 (at the... Read more
New today at Apple: 13-inch M2 MacBook Pros f...
Apple 13″ MacBook Pros with M2 CPUs in stock and available today starting at $1169, Certified Refurbished, and ranging up to $150 off original MSRP. These are the cheapest 13″ M2 MacBook Pros for... Read more
Sunday Sale: 13″ Apple M1 MacBook Air availab...
Amazon has Space Gray Apple 13″ M1 MacBook Airs on sale for $690.95 for an extremely limited time. Other models are on sale for $849. Their price for the Space Gray model is the cheapest we’ve ever... Read more
Use our exclusive Apple Price Trackers to fin...
Our Apple award-winning price trackers are the best place to look for the lowest prices and latest sales on all the latest Apple gear this season. Scan our price trackers for the latest information... Read more
New promo at Verizon: Get Apple Watch Series...
Purchase a new iPhone 14 at Verizon, and get an Apple Watch Series 8 for as low as $5 per month. $120 in promo credits for the Watch are spread over a 36 month term, reducing the price of the Watch... Read more
Visible drops prices on Apple iPhone 13 model...
Verizon’s low-cost wireless cell service, Visible has dropped prices on iPhone 13 models to new low prices starting at $599: – iPhone 13 Pro Max: starting at $980 + free $200 gift card – iPhone 13... Read more
Back in stock! 14″ MacBook Pros with Apple M1...
Amazon has restocked 14″ MacBook Pros M1 Pro CPUs for $400 off MSRP, starting at only $1599. Shipping is free. Be sure to make your purchase from Amazon rather than a third-party seller. Their prices... Read more
This is the final week to take advantage of A...
Apple’s Back to School promotion for 2022 ends on September 26, 2022. As part of this promotion, Apple will include a free $150 Apple Gift Card with the purchase of any MacBook Air, MacBook Pro, or... Read more
Mac Studio with M1 Max CPU back in stock toda...
Apple has the base standard-configuration Mac Studio available again in their Certified Refurbished section for $1799, and it’s in stock today. Each Mac Studio comes with Apple’s one-year warranty,... Read more

Jobs Board

Physician Assistant, Primary Care, *Apple*...
Physician Assistant, Primary Care, Apple Valley (1.07FTE) + Job ID: 65766 + Department: AV Primary Care + City: Apple Valley, MN + Location: HP - Apple Read more
Operations Manager - Mac/ *Apple* Engineerin...
…Responsible for the day-to-day activities relating to the engineering of Apple Macs in a complex, multi-platform environment. Demonstrates strong leadership, Read more
Lead Developer - *Apple* tvOS - Rumble (Uni...
…earnings, and positive sentiment About the role: We are looking for a Lead Apple tvOS Developer to join our application engineering team to expand our video centric Read more
Systems Administrator - *Apple* Devices / J...
…Administration **Duties and Responsibilities** + Configure and maintain the client's Apple Device Management (ADM) solution. The current solution is JAMF supporting Read more
Sr Product Manager, *Apple* TV Platforms -...
…an experienced senior product manager to drive the strategy and requirements for our Apple TV devices, acting as the champion and owner of the holistic experience in Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.