Next Previous

Creating a Derived Media Handler Component

This chapter describes the process of creating a derived media handler component. It provides an example of creating a derived media handler component and defines its component and request flags. The functional interface that your derived media handler component must support is described in Derived Media Handler Support.

Before reading this section, you should be familiar with how to create components.

Apple has defined the MediaHandlerType component type value ('mhlr') for media handler components. All components of this type have the same type value.

Apple has also defined a functional interface for derived media handler components. For information about the functions that your component must support, see Derived Media Handler Support.

A Sample Derived Media Handler Component

This section supplies a sample program that implements a derived media handler component for PICT images.

Implementing the Required Component Functions

Listing 2-1 supplies the component dispatchers for the media handler component for PICT images together with the required functions.

Listing 2-1 Implementing the required media handler component functions

typedef struct {

    ComponentInstance       self;

    ComponentInstance       parent;

    ComponentInstance       delegateComponent;

    Fixed                   width;

    Fixed                   height;

    MatrixRecord            matrix;

    Media                   media;

    Track                   track;

} PictGlobalsRecord, *PictGlobals;

pascal ComponentResult PictMediaDispatch (ComponentParameters *params,

                                             Handle storage)

    OSErr err = badComponentSelector;

    ComponentFunction componentProc = 0;

    switch (params->what) {

        case kComponentOpenSelect:

            componentProc = PictOpen; break;

        case kComponentCloseSelect:

            componentProc = PictClose; break;

        case kComponentCanDoSelect:

            componentProc = PictCanDo; break;

        case kComponentVersionSelect:

            componentProc = PictVersion; break;

        case kComponentTargetSelect:

            componentProc = PictVersion; break;

        case kMediaInitializeSelect:

            componentProc = PictInitialize; break;

        case kMediaIdleSelect:

            componentProc = PictIdle; break;

        case kMediaSetDimensionsSelect:

            componentProc = PictSetDimensions; break;

        case kMediaSetMatrixSelect:

            componentProc = PictSetMatrix; break;

    if (componentProc)

        err = CallComponentFunctionWithStorage (storage, params,

                                                             componentProc);

    else

        err = DelegateComponentCall (params, ((PictGlobals)

                                                 storage)->delegateComponent);

    return err;

pascal ComponentResult PictCanDo (PictGlobals globals,

                                            short ftnNumber)

    switch (ftnNumber) {

        case kComponentOpenSelect:

        case kComponentCloseSelect:

        case kComponentCanDoSelect:

        case kComponentVersionSelect:

        case kComponentTargetSelect:

        case kMediaInitializeSelect:

        case kMediaIdleSelect:

        case kMediaSetDimensionsSelect:

        case kMediaSetMatrixSelect:

            return true;

        default:

            return ComponentFunctionImplemented

                                (globals->delegateComponent, ftnNumber);

pascal ComponentResult PictVersion (PictGlobals globals)

    return 0x00020001;

pascal ComponentResult PictOpen(PictGlobals globals,

                                             ComponentInstance self)

    OSErr err;

    /* allocate storage */

    globals = (PictGlobals)NewPtrClear(sizeof(PictGlobalsRecord));

    if (err = MemError()) return err;

    SetComponentInstanceStorage(self, (Handle)globals);

    globals->self = self;

    globals->parent = self;

    /* find a base media handler to serve as a delegate */

    globals->delegateComponent =

                OpenDefaultComponent (MediaHandlerType,

                                             BaseMediaType);

    if (globals->delegateComponent)

        PictTarget(globals, self); /* set up the calling chain */

    else {

        DisposePtr((Ptr)globals);

        err = cantOpenHandler;

    return err;

pascal ComponentResult PictClose (PictGlobals globals,

                                             ComponentInstance self)

    if (globals) {

        if (globals->delegateComponent)

            CloseComponent(globals->delegateComponent);

        DisposePtr((Ptr)globals);

    return noErr;

pascal ComponentResult PictTarget(PictGlobals store,

                                         ComponentInstance parentComponent)

    /* remember who is at the top of your calling chain */

    store->parent = parentComponent;

    /* and inform your delegate component of the change */

    ComponentSetTarget(store->delegateComponent, parentComponent);

    return noErr;

Initializing a Derived Media Handler Component

The derived media handler component is initialized by the Movie Toolbox’s calling of the MediaInitialize function. You should then report the derived media handler capabilities to the base media handler before the Movie Toolbox starts working with your media by calling the MediaSetHandlerCapabilities function from your MediaInitialize function.

Listing 2-2 is the initialization function for a derived media handler. The PictInitialize function stores the initial height, width, track movie matrix, media, and track of the derived media handler component. From PictInitialize, the MediaSetHandlerCapabilities function is called to inform the base media handler of its existence and features.

Listing 2-2 Initializing a derived media handler

pascal ComponentResult PictInitialize (PictGlobals store,

                                          GetMovieCompleteParams *gmc)

    /* remember some useful parameters */

    store->width = gmc->width;

    store->height = gmc->height;

    store->matrix = gmc->trackMovieMatrix;

    store->media = gmc->theMedia;

    store->track = gmc->theTrack;

    /* tell the base media handler about your derived

        media handler */

    MediaSetHandlerCapabilities(store->delegateComponent,

    handlerHasSpatial, handlerHasSpatial);

    return noErr;

Drawing the Media Sample

The Movie Toolbox provides processing time to your derived media handler to display samples by calling the MediaIdle function. Your media handler may use this time to play its media sample. The code in Listing 2-3 allows the derived media handler component to draw the current media sample (in this case, a PICT image).

Listing 2-3 Drawing the media sample

pascal ComponentResult PictIdle (PictGlobals store,

                                   TimeValue atMediaTime,

                                   long flagsIn, long *flagsOut,

                                   const TimeValue *tr)

    OSErr err;

    Rect r;

    Handle sample = NewHandle (0);

    if (err = MemError()) goto bail;

    /* get the current sample */

    err = GetMediaSample (store->media, sample, 0, nil,

                                atMediaTime, nil, 0, 0, 0, 0, 0, 0);

    if (err) goto bail;

    /* draw it using the current matrix */

    SetRect (&r, 0, 0, FixRound (store->width),

                FixRound (store->height));

    TransformRect (&store->matrix, &r, nil);

    EraseRect (&r);

    DrawPicture ((PicHandle)sample, &r);

bail:

    DisposeHandle (sample);

    *flagsOut |= mDidDraw;          /* let Movie Toolbox know you drew

                                        something */

    return err;

pascal ComponentResult PictSetDimensions (PictGlobals store,

                                             Fixed width,

                                             Fixed height)

    /* remember the new track */

    store->width = width;

    store->height = height;

    return noErr;

pascal ComponentResult PictSetMatrix (PictGlobals store,

                                         MatrixRecord *trackMovieMatrix)

    /* remember the new display matrix */

    store->matrix = *trackMovieMatrix;

    return noErr;

Request Processing

Because your derived media handler is based on the base media handler component, you avoid many of the details involved in creating a media handler. However, your derived media handler must observe a few rules when processing service requests. These rules are as follows:

When you receive an open request from the Component Manager, in addition to the other processing you perform on your own behalf, you must also open a connection to the base media handler component. You should save the component instance that is returned by the Component Manager so that your media handler can use the services of the base media handler.
The base media handler has a component type of MediaHandlerType (which is set to 'mhlr') and a component subtype of BaseMediaType (which is set to 'gnrc'). You can use these values with the Component Manager’s OpenDefaultComponent function to open a connection to the base media handler.
At this time, you must also tell the base media handler that your handler is derived from it. Use the Component Manager’s OpenComponent function to create a component instance of your media handler as a descendant of the base media handler. After calling that function, you should send the kComponentSetTargetSelect request to the base media handler, so that it knows your media handler is derived from it. Use the Component Manager’s ComponentSetTarget function to send a target request.
When you receive a close request from the Component Manager, be sure to close your handler’s connection to the base media handler component. Use the Component Manager’s CloseComponent function.
Your derived media handler must support the target request, so that your component can be used by other media handlers.
Be sure to pass all unsupported service requests to the base media handler component. Use the Component Manager’s DelegateComponentCall function to pass these requests to the base media handler.
If your media handler component competes for potentially scarce system resources, your component should release those resources when you aren’t using them. For example, if you are creating a media handler that uses sound, you might use sound channels. Because there are a limited number of sound channels available, your component should free its channels whenever your media is not playing or has been stopped. You can reallocate the channels when you start playing or your component’s MediaPreroll function is called.

Next Previous