Preferred Codec APIs

QuickTime has added two new APIs that help applications specify the codec or effects components that they prefer to use when playing a movie. This supplements the normal behavior of relying on performance and compatibility as the criteria for choosing the codecs to be used.

Applications can use these APIs to access components that all work together as a set (for example, decompressors and effects all working on the same hardware).

Third-party codec providers no longer need to use decompression speed as the only way to have their codecs used in preference -- the application is now able to specify the ones it prefers. Note that applications that don't use these APIs will continue to rely on the normal behavior of the ICM.

MediaSetUserPreferredCodecs

Requests that a media handler favor specified codec components when selecting components with which to play media.



 
pascal ComponentResult MediaSetUserPreferredCodecs( MediaHandler mh, CodecComponentHandle 

                     userPreferredCodecs );

mh: Specifies your connection to the media handler component. You can call the Movie Toolbox routine GetMediaHandler to obtain a connection to the media handler component for a track's media.
userPreferredCodecs: A handle containing component identifiers. The media handler component will make its own copy of this handle. Pass nil to invalidate the standing request without substituting another.

DISCUSSION

This method does not guarantee that the specified components will be used; other factors may take precedence. Components that are preferred may not be used if they can't be part of the chain required to play the media (for example, don't handle the pixel format, or the video output, and so on).

The components should be specified in order from most preferred to least preferred.

Errors:

noErr
memFullErr
badComponentSelector The media handler component does not support this call.

Example:



 
CodecComponentHandle userPreferredCodecs = nil;

ComponentDescription cd = { decompressorComponentType,

                            myPreferredCodecType,

                            myPreferredCodecManufacturer,

                            0, 0 };

CodecComponent      c = FindNextComponent( 0, &cd );

MediaHandler        myMedia;

OSErr               err;



PtrToHand( &c, (Handle*)&userPreferredCodecs, sizeof(c) );



myMedia = GetMediaHandler( GetTrackMedia( track ) );



err = MediaSetUserPreferredCodecs( myMedia, userPreferredCodecs );

DisposeHandle( (Handle)userPreferredCodecs );

MediaGetUserPreferredCodecs

Retrieves the list of components last passed to the media handler with MediaSetUserPreferredCodecs .



 
pascal ComponentResult MediaGetUserPreferredCodecs( MediaHandler mh, CodecComponentHandle 

                     *userPreferredCodecs );

mh: Specifies your connection to the media handler component. You can call the Movie Toolbox routine GetMediaHandler to obtain a connection to the media handler component for a track's media.
userPreferredCodecs: Points to a variable of type CodecComponentHandle . If the media handler currently has a preferred component list, it will copy that list into a new handle and store the new handle in this variable. The caller must dispose this handle. If the media handler does not currently have a preferred component list, it will store nil in this variable.

DISCUSSION

Errors:

noErr
memFullErr
paramErr
badComponentSelector The media handler component does not support this call.