dmPMProcessClip(3dm)

NAME
     dmPMProcessImageClip, dmPMProcessImageClipWithProgress - apply special
     effects to movies


SYNOPSIS
     #include <dmedia/fx_plugin_mgr.h>

     typedef struct __DMprocessop
     {
         DMoptype   type;
         MVid       movie;
         MVid       track;
         MVtime     startTime;
         DMeffect*  effect;
         int        totalFrames;
         int        startFrame;
     } DMprocessop;

     typedef DMboolean (DMprogresscallback)
           ( float fractionComplete,
             void* clientData );

     DMplugin* dmPMProcessImageClip
           ( DMprocessop* arrayOfoperations,
             int numberOfOperations,
             DMboolean callSetup,
             MVtimescale timescale,
             MVtime frameDuration,
             MVtime movieDuration,
             MVid destinationTrack,
             MVtime destinationStartTime )

     DMplugin* dmPMProcessImageClipWithProgress
           ( DMprocessop* arrayOfoperations,
             int numberOfOperations,
             DMboolean callSetup,
             MVtimescale timescale,
             MVtime frameDuration,
             MVtime movieDuration,
             MVid destinationTrack,
             MVtime destinationStartTime,
             DMprogresscallback* progressCallback,
             void* progressClientData )


PARAMETERS
     arrayOfOperations      an array of: source movies, filters, and
                            transitions

     numberOfOperations     The number of DMprocessops in arrayOfOperations.


     callSetup              If true, the setup function (dmPMSetupVideoFilter
                            or dmPMSetupVideoTransition) will be called once
                            for each effect before the movie is processed.


     frameDuration          The fraction frameDuration/timescale is the
                            duration, in seconds, of each frame generated.


     movieDuration          The fraction movieDuration/timescale is the
                            duration, in seconds, of the movie to be
                            processed.


     destinationTrack       A movie track into which the processed frames are
                            inserted.


     destinationStartTime   The location (time) in destinationTrack where the
                            processed images will be inserted.


     progressCallback       A function that will be called after each step in
                            the processing.


     timescale              Client data for progressCallback.


DESCRIPTION
     dmPMProcessImageClip applies video filters and transitions to movies,
     producing a new movie as the result.  For example, a blur filter could be
     applied to an entire movie to produce a new movie with blurred images.


     The input to dmPMProcessImage is a sequence of operations to be performed
     for each frame in the generated movie.  During the processing of each
     frame, a stack of images is maintained.  The operations add new images to
     the stack, replace the top-of-stack with a filtered image, or replace the
     top two images with a transition between them.


     The output is a sequence of images of duration movieDuration.  Each frame
     in the sequence has a duration of frameDuration.  Thus, the number of
     frames produced is:  movieDuration/frameDuration.  If the given
     movieDuration is not an event multiple of the frameDuration, the last
     frame will extend past movieDuration; in other words, the movieDuration
     is rounded up to a multiple of frameDuration. This sequence of frames is
     inserted into destinationTrack starting at time destinationStartTime.
     arrayOfOperations points to an array of DMprocessops.  The type field can
     be one of: DM_MOVIE, DM_TRACK, DM_FILTER, or DM_TRANSITION.


     The DM_MOVIE operation take a frame from a source movie and pushes it on
     the stack.  The first frame used is the one at time startTime.  The
     second frame used is the one at time startTime+frameDuration, etc.


     The DM_TRACK operation take a frame from one track of a movie and pushes
     it on the stack.  The first frame used is the one at time startTime.  The
     second frame used is the one at time startTime+frameDuration, etc.


     The DM_FILTER operation applies a video filter to the top image on the
     stack, replacing it with the filtered image.  If callSetup is true, an
     interactive dialog will pop up to get custom settings for the filter.


     Some filters animate over time.  startFrame and totalFrames allow control
     over which part of the animation is used.  For example, using a filter
     that starts with the original image and fades to black over time, a
     setting startFrame to a value other than 0 can render the first output
     frame partially faded.


     As an example, say you are rendering a clip with 10 frames, and you want
     to start with the first frame 50% faded, and end with the last frame 75%
     faded.  The number of frames needed to do a full fade at this rate from
     0% to 100% is 40, so totalFrames should be set to 40.  To start at 50% of
     a 40-frame fade, startFrame should be set to 20.


     The number of frames rendered to the output movie must not be greater
     than (totalFrames - startFrame).


     The DM_TRANSITION operation applies a video filter to the top two images
     on the stack, replacing them with the filtered image.  If callSetup is
     true, an interactive dialog will pop up to get custom settings for the
     filter.  Animation can be controlled with startFrame and totalFrames, as
     with filters (see above).


     dmPMProcessClipWithProgress does exactly the same thing.  In addition, it
     periodically calls progressCallback during the processing.  The value
     returned by progressCallback indicates whether or not to continue the
     processing.  DM_TRUE means to continue, DM_FALSE means to stop.

RETURN VALUES
     DM_SUCCESS is returned if the processing of all frames was completed.
     DM_FAILURE is returned otherwise; an error code can be obtained from
     dmGetError.


SEE ALSO
     dmPMCreateEffect(3dm), mvIntro(3dm), dmGetError(3dm).