Creating Effects
Home Gallery Papers Creating Effects Download

This "getting started" guide tells you just enough to install Pan on your computer and get started making your own image effects.  The Functional Images paper goes into more detail, though the notation is not precise.

Pan's central principle is that images are functions from (continuous & infinite) 2D space to colors (with partial opacity). Images are not bitmaps (finite, discrete and rectangular), but may be reconstructed from bitmaps and rendered into bitmaps. Since images are functions, a functional language, and Haskell in particular, makes for a natural host language.  Here's are brief Pan language tutorial.

Pan is implemented as an optimizing compiler, generating C++ code, which is then compiled with a C++ compiler.  The Compiling Embedded Languages paper describes the ideas behind this implementation.  Currently, the only C++ compiler we support is Microsoft Visual C++ (MSVC).  If you add support for another, please let us know.  You will need to augment some of your environment variables, as follows, where "<msvc>" refers to your MSVC installation. (To change your environment variables in Win2000 go to Control Panel, Start/Settings/Control Panel/System/Advanced/Environment.  Similarly in WinNT.  For Win9x, modify your autoexec.bat.)

PATH  <msvc>\VC98\bin;<msvc>\Common\MSDev98\Bin
LIB  <msvc>\VC98\lib
INCLUDE  <msvc>\VC98\atl\include;<msvc>\VC98\include

It shouldn't be very hard to support compilers other than MSVC.  Less straightforward, but also doable would be to target platforms other than Windows.  We strongly invite such additions to the implementation.

You can get the full release here.

Compile some Pan demos

We will refer to your Pan installation directory as "<installdir>" below.
From Windows, double-click on  <installdir>/DemoSrc/Simple.hs.  Or after starting Hugs, :cd to <installdir>/DemoSrc, and type the following.
:load Simple
After Pan and the demo module load successfully, compile and run one example by typing the following at the Hugs prompt.  
compileFilterFor [Component] "ripple" rippleUI
If all goes well, you should get a window that looks something like the following:

Move the sliders and see what happens.  Also, try a different imported image file, using the "..." button.
See this description of how to pan & zoom in the display window. 

The Pan distribution contains many other examples in the DemoSrc directory.  Simple.hs is a good place to start.  It contains a few simple examples, including ripple, shown above.  In addition to defining the examples, each demo module ends by defining a command "makeAll", which compiles all of the module's examples for all of the backends, and "makeAllFor", which compiles all examples for a given list of backends.

Compiler variations

The Pan compiler handles several different types of image effects:

type Image   c     = PointE -> c
type ImageB  c     = TimeE  -> Image c
type Filter  c     = ImageC -> Image c
type FilterB c     = ImageC -> ImageB c
type ImageCombiner = ImageC -> ImageC -> ImageBC

where ImageC = Image ColorE.  For each of these effect types, there is a corresponding compiler entry point:

type Compiler a = String -> UI a -> IO ()

compileImage    :: ToColor c => Compiler (Image   c)
compileImageB   :: ToColor c => Compiler (ImageB  c)
compileFilter   :: ToColor c => Compiler (Filter  c)
compileFilterB  :: ToColor c => Compiler (FilterB c)
compileCombiner :: Compiler ImageCombiner

The ToColor type class contains types that can be converted to color.  Currently Pan provides instances for types ColorE, BoolE (black&white), and FloatE (really [0,1] for greyscale).  You can add more instances.

There are also four compiler backends, producing binaries suitable for different settings:

Component Produces a ".pef" (Pan effect) file containing display code used by the Pan Component Viewer, which instantiates the effect and can save & load parameter settings as ".pan" files.  Can also be used in the Pan Viewer ActiveX control for embedding in Web pages under Internet Explorer.
Standalone  Stand-alone executable.  Similar to Component, but less flexible.  Cannot load & save.  We're phasing this one out.
DXTransform DirectX transform, also embeddable in web pages for viewing in Internet Explorer 5.5 or later.
PhotoShopFilter PhotoShop plug-ins, to run with hosts like Adobe PhotoShop® and the less expensive JASC PaintShop Pro (PSP).  Requires the host program.  See PSP-specific usage info.
Control Self-contained ActiveX control.  Some but not all of the effect parameter types may be set via the HTML "object" tag.

 We recommend using the "component" backend.

Each of the compiler entry points listed above (compileImage, etc) runs all four backends, but there are variations for selecting just the desired backend subset.  

allBackends :: [Backend]
allBackends = [Standalone,Component,DXTransform,PhotoShopFilter]

type CompilerFor a = [Backend] -> Compiler a

compileImageFor    :: ToColor c => CompilerFor (Image c)
compileImageBFor   :: ToColor c => CompilerFor (ImageB c)
compileFilterFor   :: ToColor c => CompilerFor (Filter c)
compileFilterBFor  :: ToColor c => CompilerFor (FilterB c)
compileCombinerFor :: CompilerFor ImageCombiner

So, for example, to generate just a PhotoShop filter for our ripple example, type the following at the Hugs prompt.  

compileFilterFor [PhotoShopFilter] "ripple" rippleUI

Compiled demos are stored in the subdirectories of <installdir>/demos, called standalone, component, control, dxt, plugins.

Making your own effects

We do not yet have a manual on the Pan library/language, but here's a tutorial.  See the papers also.

 
Conal Elliott
Copyright © 1999,2000 Microsoft Corp. All rights reserved.
Revised: December 13, 2000.