README - Dimmer2 QuickTime Effect Framework

This sample shows how to build a custom effect component for QuickTime.
The structure of this sample is that of a "Framework" which can be used
to build new effects very quicly. Replace a few lines of code, write some
new blit code and you're done...easy as cake.

The sample effect this framework builds is called "Dimmer2". Dimmer2 uses
two sources as input and renders the first source with a dim value that starts
at full on, and ramps to full off. It then does the opposite for the second source
starting at full off and ramping up to full on using a QT Tween to produce the dim
values used to modify the pixels.

CodeWarrior and Project Builder projects are included:
- The CodeWarrior targets build a traditional PPC code resource, Carbon CFM component
and a Carbon Mach-O component. The last two for Mac OS X only.
- The Project Builder target will build a Mach-O dylib for Mac OS X.

Building this sample on Windows:

This sample can be built using Microsoft Visual C++ 6.0 or later. The Workspace is called
Dimmer2Effect.dsw.

You will need to install the QuickTime 5 or later Windows SDK (called QTDevWin) and set up
access paths to directories where VC++ can find the QuickTime includes, resource includes,
libraries and build tools. This can be done from the VC++ 'Tools->Options...' menu. Select the
'Directories' tab then add the correct paths for each. The 'QTDevWin' folder should be located
in the ..\Microsoft Visual Studio\VC98\ directory.

This project has been set up assuming the following paths have been added to VC++:

Executable File path added:
     ..\Microsoft Visual Studio\VC98\QTDevWin\Tools\

Include File paths added:
     ..\Microsoft Visual Studio\VC98\QTDevWin\CIncludes\
     ..\Microsoft Visual Studio\VC98\QTDevWin\ComponentIncludes\
     ..\Microsoft Visual Studio\VC98\QTDevWin\RIncludes

Library File path added:
     ..\Microsoft Visual Studio\VC98\QTDevWin\Libraries\

Rez and RezWack:

The EffectRezWin.r file has a custom build action associated with it which compiles the
components resource files together using Rez. You may need to change the access path to the
RIncludes directory for this stage of the build process so the Rez tool can find what it needs.

Currently the path is hard coded (because Rez if very touchy about such things).

Rez.exe -rd -i "C:\Program Files\Microsoft Visual Studio\VC98\QTDevWin\RIncludes" -i .\EffectFramework -o "$(TargetDir)\$(TargetName).qtr" <  "$(InputPath)"

There is also a custom Post-build step associated with the target which takes the compiled
resources (the .qtr file) and embeds them using the RezWack tool into the dll. You shouldn't
need to change anything for this step to work, it is mentioned here for completeness.

RezWack -f -d "$(OutDir)\$(TargetName).qtx" -r "$(OutDir)\$(TargetName).qtr" -o "$(ProjDir)\$(TargetName).qtx"

For a summary of the commands these tools can accept, please see RezDocs.txt.

To find things to change to implement your effect, seach for *** CHANGE ***.
Code that will require modification is bracketted by CHANGE/END CHANGE.
	
There are eleven places to change code, and one place where you write new
code that implements your actual effect.  MAKE SURE YOU LOOK AT ALL OF THEM.

*IMPORTANT*

You MUST also ensure that the Effect.r file is kept in sync with this code.
In particular it is very important that you update the 'atms' resource
description so that the parameters of your effect are correctly described.
Full details of the format of the 'atms' resource can be found in the Effects
chapter of the QuickTime documentation

ALSO PLEASE NOTE THAT THE LINK WARNING ABOUT THE COMPONENT DISPATCH ENTRY POINT
NOT BEING A ROUTINE DESCRIPTOR IS NORMAL AND CAN BE IGNORED WHEN BUILDING THE PPC
TARGET.

The files in this project are as follows:
 Effect.c -- effect source (you change this)
 Effect.r -- effect resources (you change this)
 EffectDefinitions.h -- effect resource IDs (you probably change this)
 EffectUtilities.c -- effect tween utilities (does not usually require change)
 EffectUtilities.h -- effect tween utilities (does not usually require change)
 EffectDispatch.h -- effect codec entry point definitions (does not usually require change)
 Dimmer2Effect.mcp -- Metrowerks project for the effect
 Dimmer2Effect.dsp -- VC++ Project
 Dimmer2Effect.dsw -- VC++ WorkSpace
 EffectFilter16.c - the 16-bit effect algorithm (you change this)
 EffectFilter32.c - the 32-bit effect algorithm (you change this)
 
Also included are various prefix files, symbol export files etc. which define the appropriate
flags etc. for each platform.

Finally, there is a pre-built 68k version of this component included for nostalgic reasons...
...nostalgia goes a long way...However, building a 68k version of this component is not supported,
after all, what would be the point.

Enjoy,
QuickTime Team &
QuickTime Developer Support
Have a good time all the time...moo!