---

Processing Phase

The processing phase is when the plug-in does most of its work. iMovie controls the processing phase through a loop that calls the plug-in as many times as necessary, as specified by the value of HYPluginGetInfo.framesToBeRendered. These calls are made with the kPlugDoFrame selector, and with each call HYPluginParams.renderFrame is updated. The value of the first frame in the movie, HYPluginParams.startFrame, is expressed in global frame numbers. The value of renderFrame is a zero-based index relative to startFrame. This approach allows the plug-in to request frames relative to the current frame using the callbacks (for example, the previous frame would be renderFrame-1. The value of HYPluginParams.frameCount gives the plug-in the total number of frames to render. Thus, renderFrame can range from 0 to frameCount.

The plug-in can call back into iMovie using a variety of procedures that are provided through the HYPluginParams.procs pointer. These include procedures for drawing, working with frames, clips, and movies, and so forth. Memory allocation should be done through these procedure pointers, so that iMovie can keep track of plug-in memory use. See the HYPluginProcs.h header file for the details and prototypes.

In this section:

Drawing
Working With Clips
Working With Thumbnails
Working With Saved Files
The HYPluginGetInfo Data Structure
Video Standards: PAL versus NTSC
Video Compression Quality
API Release Versions

Drawing

With each kPlugDoFrame call, iMovie passes a pointer (in HYPluginParams.frame) to a gWorld that contains the current (uncompressed) frame of video. The plug-in performs its service and draws into the gWorld before returning. For example, an effect might use the GetFrame callback to get the pixels for its starting frame, perform its calculations, and then draw into the gWorld before returning. In the less complicated example of a title, for which only the current frame is of interest, the plug-in might simply compute the X,Y location based on the frame number, and draw some text into the gWorld.

It is important to note that the plug-in may be asked to draw in an arbitrary GWorld with a rectangle. Consequently, the scale of text is not fixed, but should be computed relative to the size of the rectangle. For example, the plug-in may be called to preview its results in the large video window, in a small preview window, or even in a thumbnail during rendering. The plug-in must also not assume that the rectangle passed starts at 0,0

Any frame may be drawn at any time; the plug-in must be able to draw frame N without having drawn frame N-1. This is so that arrow keys may be used to go forward and back in Preview mode, for example.

The plug-in can call GetFrame with arbitrary frame numbers relative to startFrame, but the requested frames may or may not exist.

iMovie creates an opaque pointer, HYFrameCookie, to keep track of a frame as it goes to and from the plug-in. The plug-in is expected to preserve this pointer unchanged and possibly to return it in some of the API calls.

Working With Clips

iMovie passes back the HYPluginClipInfo structure when the plug-in makes the GetClipInfo callback. This structure allows the plug-in to determine settings for a clip such as the clip name, its audio volume, and whether it has a fade-in or fade-out. The plug-in can change some of such settings and then pass them back in with SetClipInfo.

The HY2PluginClipInfo structure was introduced in iMovie version 2.0 to extend HYPluginClipInfo. This structure contains settings for reverse play, frame speed, and length (in frames) of a fade-in or fade-out.

Working With Thumbnails

The plug-in should set HYPluginGetInfo.bestThumbOffset to specify which frame is to be used for a thumbnail. Consider, for example, a title that scrolls on-screen; the first frame would contain no visible text. One simple approach might be to set bestThumbOffset to the middle frame (derived from HYPluginGetInfo.frameCount).

Working With Saved Files

The plug-in must specify a programmer name (as described above in the section “Initialization Phase”) to allow iMovie to associate the plug-in with a rendered file (title, transition, filter) created by that plug-in. These names are stored in the iMovie project file and are also loaded into the record stored in the menu so the application can select the proper plug-in if the user selects an existing rendered file.

The HYPluginGetInfo Data Structure

The plug-in provides setup information to iMovie primarily through the HYPluginGetInfo data structure, which includes the fields shown in Table 1-3.

The size of this structure is fixed. The functionality of the structure has been extended through the addition of the HY2PluginGetInfo for version 2 of the API (as shown in Table 1-4), HY3PluginGetInfo for version 3 of the API, as shown in Table 1-5, and the HY4PluginGetInfo for version 4 of the API, as shown in Table 1-6. This approach allows existing plug-ins to continue to work without limiting the access of newer plug-ins to new features.

Video Standards: PAL versus NTSC

Constants are defined in HYRefDigitalVideoStandard to differentiate between PAL and NTSC video streams: kRefNTSCStandard, and kRefPALStandard (as well as kRefUnknownStandard). The plug-in can use either one, but cannot mix them within a project.

Video Compression Quality

The DV standard calls for only a single quality level in compressed form, but DV can be decompressed into lower quality (faster) or higher quality (better) video. A plug-in might, for example, drive a small preview at lower quality to improve performance. HYRefDVQuality provides three constants used by some API calls to ask for different quality levels: kDVLowQuality, kDVHighQuality, kDVHighQualitySingleField.

API Release Versions

Extensions of the iMovie API have been designed so that all released versions of the iMovie API are backward and forward compatible. A plug-in should be able to claim to be built against version 1 of the interface, and adjust at runtime for changes in the API.

To enable this degree of flexibility, iMovie does not enforce version compatibility; the plug-in must determine whether it can run in a given version of iMovie. To this end, iMovie defines several version number constants (shown in Table 1-7), and it passes its version down to the plug-in.

In case of a version mismatch, the application can return one of two error codes: kPluginAppIsTooOld or kPluginAppIsTooNew. In either case, the plug-in won’t load.

---