---

Sprite API Changes

QuickTime 6 introduces a new group of APIs that enable software application developers to request, display, and manage images that are hosted outside of the Movie in which they are used.

In this section:

Loading Images into a Sprite Track
New Sprite APIs

Loading Images into a Sprite Track

Each sprite in a sprite track has an image associated to it. Typically, that image is visible to the user when the movie is presented. A Sprite track can have a number of images in it and you can assign another image to a sprite by setting its image index.

In general, many of the images that could be used in interactive Web content are simultaneously being integrated into HTML, perhaps updated by server-side scripts, created by art departments in larger production teams, or are simply not available during the Movie authorship process. In earlier versions of QuickTime, it was not possible for a movie author to manage the dynamic loading and processing of sprite images. Images had to be integrated into the movie when it was generated.

Now, in QuickTime 6, with two simple sprite track wired actions (discussed in the section “New Sprite Actions”), the movie author can load any image format supported by QuickTime, either from a local or remote source, and manage its display and persistence during the playback of a movie. Sprite images, like sprites before them, now have two unique identifiers associated with them to help movie creators manage many images over the course of a movie’s lifetime, index and ID.

New Sprite APIs

The following APIs, discussed in this section, are new in QuickTime 6.

SpriteMediaNewImage

Creates a new sprite image.

ComponentResult  SpriteMediaNewImage (                     // IV-2677
   MediaHandler   mh,   // IV-2677
   Handle dataRef,      // IV-2683
   OSType dataRefType,  // IV-2695
   QTATomID desiredID );// IV-2675

Parameters

mh

The sprite media handler for this operation.

dataRef

A pointer to the url dataRef or an alias that references the image to be added to the sprite track.

dataRefType

A FourCharCode describing the dataRef parameter. For example, you can use URLDataHandlerSubType if the dataRef is a URL.

QTAtomID

A long used to request a unique ID identifier for the image. If the requested ID is in use, the call fails. If a 0 is passed in, NewImage will assign the next available (incremental) integer ID––which is usually the same as the next available index, unless that ID has been previously assigned.

Return Value

If successful, the new image can be used by the target sprite track like any other sprite image. The image is referenced by the next available image index, equal to the number of images in the track before the call was made + 1, and by the ID that was requested via parameter or was automatically assigned.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

Movies.h

SpriteMediaDisposeImage

Frees the memory allocated for a new sprite image, and removes that image from the track.

ComponentResult  SpriteMediaDisposeImage (                   // IV-2677
   MediaHandler mh,   // IV-2677
   short imageIndex );// IV-2687

Parameters

mh

The sprite media handler for this operation.

imageIndex

The index of a sprite image previously acquired via a SpriteMediaNewImage call.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

Movies.h

Function Result: The image disposed of is no longer available to the sprite track, and the image index location will remain “empty” for the duration of the current key sample.

Introduced in QuickTime 6.

C interface file: Movies.h

SpriteMediaImageIndexToID

Returns the ID of a particular image given the index of that image.

ComponentResult  SpriteMediaImage  (                         // IV-2677
   MediaHandler mh,         // IV-2677
   short imageIndex,
   QTAtomID *imageID );     // IV-2687

Parameters

mh

The sprite media handler for this operation.

imageIndex

The index of a sprite image.

imageID

On return, a pointer to the ID of the image.

Return Value

You can access Movie Toolbox error returns through GetMoviesError (I-505) and GetMoviesStickyError (I-506), as well as in the function result. See Error Codes (IV-2718).

Availability

• Available in Mac OS X v10.2 and later.

Declared In

Movies.h

Introduced in QuickTime 6.

SpriteMediaImageIDToIndex

Returns the index of a particular image, given the ID of that image.

ComponentResult  SpriteMediaImage  (                         // IV-2677
   MediaHandler mh,         // IV-2677
   QTAtomID imageID,        // IV-2687
   short *imageIndex );

Parameters

mh

The sprite media handler for this operation.

imageID

The ID of a sprite image.

imageIndex

On return, a pointer to the index of the image.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

Movies.h

Function Result: If no image is found with a corresponding ID, the image index returned will be 0.

Introduced in QuickTime 6.

---