Explanation on QuickTime component dispatcher macros

When you plan to build a QuickTime component, you can start from reading “QuickTime Component Creation Guide”. However, it is better to read “Introduction To QuickTime Overview” first.

Anyway, the chapter 2 of the “QuickTime Component Creation Guide” shows a sample codes. It is easy to understand.
There is also a good example, “EIComponentSample”.
It is a little more complicated and contains almost all kind of QuickTime components. It provides deeper information than the guide document. So, it is better to take a look at it and it is “have-to” sample code.

But you will have some question like :

  • How is “PictMediaDispatch” function registered? How does QuickTime system knows the existence of the overridden functions?
  • In EIComponentSample, where are those dispatch functions? is there any lines of codes which register those dispatch routines?

Apple doesn’t provide good and thorough example. So, try looking up the Perian source codes.

Then how they are registered?
Try opening “ff_MovieImport.c”.

#define MOVIEIMPORT_BASENAME()		FFAvi_MovieImport
#define MOVIEIMPORT_GLOBALS()		ff_global_ptr storage

#define CALLCOMPONENT_BASENAME()	MOVIEIMPORT_BASENAME()
#define CALLCOMPONENT_GLOBALS()		MOVIEIMPORT_GLOBALS()

#define COMPONENT_DISPATCH_FILE		"ff_MovieImportDispatch.h"
#define COMPONENT_UPP_SELECT_ROOT()	MovieImport

#include <CoreServices/Components.k.h>
#include <QuickTime/QuickTimeComponents.k.h>
#include <QuickTime/ComponentDispatchHelper.c>

The MACROs defined there are very important. MOVIEIMPORT_BASENAME(), for example, will be prepended to each registered function. So, as you can see from a list below,
a function name, for example, FFAvi_MovieImportSetSampleDescription can be composed.

The header file, “ff_MovieImportDispatch.h”, is included by QuickTime/ComponentDispatchHelper.c.

Then try opening “ff_MovieImportDispatch.h”

	ComponentSelectorOffset (-kComponentTargetSelect)

	ComponentRangeCount (1)
	ComponentRangeShift (7)
	ComponentRangeMask	(7F)

//	ComponentRangeBegin	(4)
	ComponentRangeBegin	(0)
		ComponentError	(Target)
		ComponentError  (Register)
		StdComponentCall(Version)
		StdComponentCall(CanDo)
		StdComponentCall(Close)
		StdComponentCall(Open)
	ComponentRangeEnd	(0)

	ComponentRangeBegin	(1)
		ComponentError	(0)
		ComponentError	(Handle)
		ComponentCall	(File)
		ComponentError	(SetSampleDuration)
		ComponentCall	(SetSampleDescription)
                ...
		ComponentCall	(SetIdleManager)
		ComponentError	(SetNewMovieFlags)
                ...
	ComponentRangeEnd	(1)

The number in ComponentRangeCount( number ) is the max. index of component range. It is not 1-based but 0-based.

Then, what is the range numbers? What functions are to be in range x?
Apple didn’t document it.
However I found this information at Apple’s mailing list.

Range 0 = -0xFF to -0x01 Standard Component Calls
Range 1 = 0x000 to 0x0FF Generic codecs
Range 2 = 0x100 to 0x1FF Specific to QT Photo JPEG codecs
Range 3 = 0x200 to 0x2FF Base Decompressor Client codecs
Range 4 = 0x300 to 0x3FF Effect codecs

For the whole explanation, try to visit here.

If you look up the header files, it will not be so difficult to understand them. However, it is better that Apple write good document on this issue. (Are they going to write this portion in Cocoa/Objective-C? )

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: