QuickTime Effects Parameter File Format

Dispatch 24

QuickTime 4 introduced a file format to store the description of a QuickTime effect. Because a single effect can have dozens of parameters, these files provide a convenient way to maintain commonly used effect settings. They can be created using the Standard Effects Parameter dialog which contains "Load" and "Save" buttons for this purpose. QuickTime Effects parameter files have a Macintosh file type of 'qtfx' or a file name extension of ".qfx".

Some applications may find it useful to use these files to allow users to store commonly used effects settings in a file. An application can use the settings stored in this file to configure an effect instead of presenting the Standard Effects Parameter dialog to the user.

A QuickTime Effects parameter file consists of a series of classic QuickTime atoms. See QuickTime Movie File Format Specification for a description of classic atoms. The basic format of a classic QuickTime atom is as follows:

(4 bytes)   total atom size
(4 bytes)   atom type
(N bytes)   atom data, where N == total atom size - 8
   

Effects parameter files typically contain the following atoms:

'qtfx'    effect sample data  (QTAtomContainer)
'pnot'    preview atom        (see QuickTime Movie File Format Specification)
'PICT'    preview picture     (QuickDraw Picture)
   

Only the 'qtfx' atom is required for a properly formed Effects parameter file. The others are optional. The ordering of the atoms in the file is not predefined.

QuickTime doesn't provide an API to read or write this type of file. Instead, applications must read or write this type of file themselves. Effects parameter files will be made available to the user when they click the Load button of the Standard Effects Parameter dialogs. Applications that read Effects parameter files should make sure that they skip over any atoms that they do not understand, to allow for future extensions to the file format. Note that the file may or may not contain the preview atoms.

The following code demonstrates how to read the effect sample data from a QuickTime Effects parameter file. Once loaded into memory, the effect sample data can be used as input to a QuickTime Effect.

effectSample = nil;
anErr = FSpOpenDF(&reply.sfFile, fsRdPerm, &refNum);
if (anErr == noErr)
    {
    do
        {
        dataSize = sizeof(long)*2;
        anErr = FSRead(refNum, &dataSize, &aLong[0]);
        aLong[0] = EndianU32_BtoN(aLong[0]) - sizeof(long)*2;
        aLong[1] = EndianU32_BtoN(aLong[1]);
        if (aLong[1] == OSTypeConst('qtfx'))
            {
            effectSample = NewHandle(aLong[0]);
            anErr = MemError();
            if (anErr == noErr)
                {
                dataSize = aLong[0];
                anErr = FSRead(refNum, &dataSize, *effectSample);
                }
            }
        else
            SetFPos(refNum, fsFromMark, aLong[0]);
        } while ((anErr == noErr) && (effectSample == nil));
    
    FSClose(refNum);
   

The effect sample's 'what' atom indicates the type of the effect (such as dissolve or film noise). The following code demonstrates how to extract this atom:

    OSType whatContent = 0;
    QTAtom whatAtom = QTFindChildByID(effectSample, kParentAtomIsContainer, 
                         kParameterWhatName, kParameterWhatID, nil);
    if (whatAtom)
       {
       QTCopyAtomDataToPtr(effectSample, whatAtom, true, sizeof(whatContent), &whatContent, nil);
       whatContent = EndianU32_BtoN(whatContent);
       }
   

See Also

QuickTime 3 Reference - Imaging - Effects and Transitions

Inside Macintosh: QuickTime

QuickTime 3 Reference - Data Formats - QuickTime File Format

Change History

2/23/00 - ted - First published