Component Resources

Dispatch 21

QuickTime components can contain resources which are simply pieces of data. The Component Manager has always provided support to help authors of components access their resources. Component resources have always been used as a way for components to store data which is accessed directly only by the component itself. QuickTime now contains significantly enhanced support making component resources easier to use, and more useful as well through the addition of public component resources.

Getting a Private Component Resource

The example below shows how a component would obtain one of its resources in the past.

OSErr err;
Handle resource = nil;
short saveResFile;
short resRef;
   
saveResFile = CurResFile();
err = OpenAComponentResFile((Component)store->self, &resRef);
if (err == noErr) {
  resource = Get1Resource('PICT', 128);
  if (resource) {
    LoadResource(resource);
    DetachResource(resource);
  }
  else {
    err = ResError();
    if (err == noErr)
      err = resNotFound;
  }
   
  CloseComponentResFile(resRef);
  UseResFile(saveResFile);
}
   

The above example is a relatively large amount of code to obtain a single resource. With QuickTime 3 and later, the Component Manager provides a single function which performs this same task.

err = GetComponentResource((Component)store->self, 'PICT', 128, &resource);
   

Besides avoiding the complexity for the caller, GetComponentResource has an advantage over the original example. The Component Manager maintains a cache of component resources. Therefore, the second time a given component resource is requested, it can usually be obtained very quickly from the cache.

Note that component resources are returned as Handles - not Resource Handles. This means that DisposeHandle should be used to dispose of the "resource", not ReleaseResource.

GetComponentResource takes care of opening and closing the component's resource file as necessary.

Getting a Private Component Resource String

Because it is very common to get strings from a resource, the Component Manager provides a version of GetIndString which can be used to get a single string from a STR# resource.

Str255 str;
   
err = GetComponentIndString((Component)store->self, str, 128, 1);
   

Since GetComponentIndString shares a resource cache with GetComponentResource, this allows GetComponentIndString to execute very quickly after the first string has been requested.

Component Public Resources

With QuickTime 4, the Component Manager has been enhanced to allow a Component to make some of its resources available to other software. Because these resources are not for use by the component's private implementation, but instead by other software in the system, these resources are called component public resources. Of course, a component may access its own public resources as well.

A component's private resources are identified by an OSType and an ID. The private resource's OSType and ID are the same as the Mac OS resource type and ID that the resource is identified with in the component's resource file.

A component's public resources are also identified by an OSType and an ID. The public resources OSType and ID do not have to be the same as the Mac OS resource type and ID that the resource is stored in. A component that provides public component resources must provide a Component Resource Map which indicates the mapping between the public resource OSType and ID and the private OSType and ID.

Here's an example of a Component Resource Map.

resource 'thnr' (512) {
	{
		'PICT', 1, 0,
		'pict', 128, 0,
   
		'PICT', 2, 0,
		'pict', 129, 0,
	}
}

This Component Resource Map makes available two public resource, 'PICT' 1 and 'PICT' 2. These two public resources are stored in the component as Mac OS resources 'pict' 128 and 'pict' 129.

To connect a Component Resource Map to a component, the component resource must be extended to include a references to the 'thnr' resource.

resource 'thng' (512) {
	// component type, subtype, manufacturer, etc
	//  go here
   
	'thnr', 512
};

Getting a Public Component Resource

An application can obtain a public resource from a component by using the Component Manager.

err = GetComponentPublicResource ((Component)store->self, 'PICT' , 1, &resource);
   

As with GetComponentResource, the resources returned by GetComponentPublicResource are cached. This means that successive calls to access the same resource are typically very fast.

Note that component public resources are returned as Handles - not Resource Handles. This means that DisposeHandle should be used to dispose of the "resource" and not ReleaseResource.

Also note that a component's public resources can be accessed without having to first open the component.

Some types of components provide information about themselves through public component resources. For example, Movie Export components can each contain a public resource which indicates the kinds of QuickTime media types that may be exported. QuickTime visual effects components can each contain a public resource that describes the list of parameters that can be used to configure the effect. With time, expect to see more and more usage of public component resources.

Getting Component Public Resources

To get the same component resource for each component is a simple matter of iterating through each component. The following example shows how to get a single resource from each Movie Exporter installed.

ComponentDescription cd;
Component c = 0;
   
cd.componentType = MovieExportType;
cd.componentSubType = 0;
cd.componentManufacturer = 0;
cd.componentFlags = 0;
cd.componentFlagsMask = 0;
   
while (c = FindNextComponent(nil, &cd)) {
  Handle resource;
   
  err = GetComponentPublicResource(c, 'PICT', 1, &resource);
  if (err == noErr) {
    // do something with the resource
    DisposeHandle(resource);
  }
}

The previous example is straightfoward, but it can be a little slow. For each call to GetComponentPublicResource, the Component Manager may have to open the component's resource file and load a resource. While resource caching may make this fast the second time this code is run, if many components are to be accessed the first pass may be unacceptably slow. Because often multiple components of the same type are stored in a single file (QuickTime itself contains nearly a dozen Movie Exporters), significant optimizations are possible. QuickTime provides a single optimized call to obtain a single public resource from each component that matches a component description. The following code shows how to get all the 'PICT' 1 public resources from all installed Movie Exporters.

QTAtomContainer resources;
ComponentDescription cd;
   
cd.componentType = MovieExportType;
cd.componentSubType = 0;
cd.componentManufacturer = 0;
cd.componentFlags = 0;
cd.componentFlagsMask = 0;
   
err = GetComponentPublicResourceList ('PICT', 1, 0, &cd, nil, nil, &resources); 

Once the call to GetComponentPublicResourceList has completed, the QTAtomContainer returned contains all the 'PICT' 1 component public resources for all Movie Exporters installed. The following code shows how to access these resources.

long i, count;
   
count = QTCountChildrenOfType(resources,
kParentAtomIsContainer, OSTypeConst('comp'));
for (i=1; i<=count; i++) {
	QTAtom compAtom, resourceAtom;
	Component c;
   
	compAtom = QTFindChildByIndex(resources, kParentAtomIsContainer, 
OSTypeConst('comp'), i, (long *)&c);
	resourceAtom = QTFindChildByID(resources, compAtom, 'PICT', 1, nil);
	if (resourceAtom) {
		Handle resource = NewHandle(0);
   
		QTCopyAtomDataToHandle(resources, resourceAtom, resource);
   
		// do something with the resource for Component c
   
		DisposeHandle(resource);
	}
}
   
QTDisposeAtomContainer(resources);
   

While using GetComponentPublicResourceList can take more code, it is often substantially faster. Application authors can use either approach, but using GetComponentPublicResourceList is recommended as its performance is likely to remain high, especially as more components are added to QuickTime.

You'll notice that the atom's ID is the Component reference.

Dynamic Component Public Resources

Component public resources provide a convenient way to get data from a component. Some components may need to be able to dynamically change the contents of their public component resources based on the capabilities of the current system. For example, the ColorSync visual effect's parameter list varies depending on what color matching methods are installed. In this case, its public component resource cannot be stored in its resource file, but instead must be dynamically created at runtime. The Component Manager allows for a component to be called to provide the components of one or more of its public resources. To indicate that a public resource cannot be loaded directly from a component's file, the cmpResourceCallComponent flag must be set for that resource in the component's resource map.

resource 'thnr' (128) {
	{
		'atms', 1, 0,
		'atms', 0, cmpResourceCallComponent
	}
};
   

When an attempt is made to load the 'atms' 1 public resource for this component, its ComponentGetPublicResource will be called. Here's an example of how a component might implement that function.

pascal ComponentResult ColorSyncGetPublicResource(ColorSyncGlobals store, OSType resourceType, short resourceID, Handle *theResource)
{
	if (resourceType == OSTypeConst('atms') && (resourceID == 1))
		return buildResource(store, theResource);
	else
		return resNotFound;
}
   

Whether a component public resource is stored in the component's resource file or created dynamically is completely transparent to the the software requesting the component public resource.

See Also

Inside Macintosh - QuickTime

Inside Macintosh - More Macintosh Toolbox - Component Manager

QuickTime 3 Reference

Change History

2/10/99 - jph - First written