Boolean ICMCompressionSessionSupportsMultiPassEncoding(ICMCompressionSessionRef session,

                                                       UInt32 multiPassStyleFlags,

                                                       ICMCompressionPassModeFlags *firstPassModeFlagsOut)

Discussion:

The client should make this call before starting a multipass compression operation to query whether

a compression session supports multipass encoding. If it does, this call returns the initial state of

the pass mode flags in the firstPassModeFlagsOut parameter.

Parameters:

multiPassStyleFlags - Reserved, set to 0

firstPassModeFlagsOut ( read ) - A pointer to a variable to receive the session’s recommended mode

flags for the first pass. The client may modify these flags, but should not set

kICMCompressionPassMode_NoSourceFrames. Pass NULL if you do not want this information.

OSStatus ICMCompressionSessionBeginPass(ICMCompressionSessionRef session,

                                        ICMCompressionPassModeFlags passModeFlags,

                                        UInt32 flags)

Discussion:

The client must make this call to signal the start of a specific compression pass. The client can

describe how the compressor should behave in this pass by passing in the pass mode flags in the

parameter passModeFlags.

Parameters:

passModeFlags ( write ) - Flags that describe how the compressor should behave in this pass.

flags - Reserved. Set to 0.

OSStatus ICMCompressionSessionProcessBetweenPasses(ICMCompressionSessionRef session,

                                                   UInt32 flags,

                                                   Boolean *interpassProcessingDoneOut,

                                                   ICMCompressionPassModeFlags *requestedNextPassModeFlagsOut)

Discussion:

The client must make this call after calling ICMCompressionSessionEndPass to let the compressor perform

processing between passes, but only if kICMCompressionPassMode_OutputEncodedFrames has not been set.

Parameters:

session - A compression session reference. This reference is returned by ICMCompressionSessionCreate.

flags - Reserved. Set to 0.

interpassProcessingDoneOut - A pointer to a Boolean that will be set to FALSE if this function

should be called again, TRUE if it should not be called again.

requestedNextPassModeFlagsOut ( read ) - A pointer to a variable that will be set to the

compressors recommended mode flags for the next pass. kICMCompressionPassMode_OutputEncodedFrames will

be set only if it recommends that the next pass be the final one.

ICMCompressionPassModeFlags passModeFlags = 0;

Boolean multipassYES = false;

Boolean done = false;

...

// passModeFlags recieve the session's requested mode flags for the first pass

multipassYES = ICMCompressionSessionSupportsMultiPassEncoding(session,

                                                              0,

                                                              &passModeFlags);

while(!done) {

    if (multipassYES) {

        // passModeFlags describe how the compressor should behave in this pass

        // the client may modify the pass mode flags and set

        // kICMCompressionPassMode_OutputEncodedFrames to force frames to be output

        // prematurely if desired in this pass once the codec has cleared the

        // kICMCompressionPassMode_NotReadyToOutputEncodedFrames flag

        ICMCompressionSessionBeginPass(session, passModeFlags, 0);

    }

    // Feed all the frames to the compression session

    // The source frames and frame options for each display timestamp

    // must be the same across passes

    for (frameNumber = 1; frameNumber <= kFrameCount; frameNumber++) {

        if (0 == (passModeFlags & kICMCompressionPassMode_NoSourceFrames)) {

            // provide the source frames here - kICMCompressionPassMode_NoSourceFrames

            // is NOT set -- if it was set, then don't provide source frames to

            // ICMCompressionSessionEncodeFrame pass NULL for the pixelBuffer

            // parameter but make sure to supplying all the other information

            // consistently between passes

            ...

        }

        ICMCompressionSessionEncodeFrame(...)

    }

    ICMCompressionSessionCompleteFrames(...)

    if (multipassYES) {

        ICMCompressionSessionEndPass(session);

        if (passModeFlags & kICMCompressionPassMode_OutputEncodedFrames) {

             // the compressor has output encoded frames in this pass so we choose to be done

             // NOTE: a client could add code to provide an early preview and continue as documented in QA1457

             done = true;

        } else {

            Boolean interpassDone = false;

            while(!interpassDone) {

                // passModeFlags will be set to the sessions recommended mode flags

                // for the next pass. kICMCompressionPassMode_OutputEncodedFrames will

                // only be set if the codec recommends that the next pass be the last

                ICMCompressionSessionProcessBetweenPasses(session,

                                                          0,

                                                          &interpassDone,

                                                          &passModeFlags);

            }

        }

    } else {

        done = true;

    }

}