Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Sprite Hit-Testing Mode
When a sprite is clicked in a sprite track, it “receives” the mouse click. However, there are times when you may want to have sprites that do not receive a mouse click, and instead, you want the mouse click to “pass through” that sprite (and on to another sprite or perhaps another track behind the sprite track). In earlier versions of QuickTime, this was not possible.
In QuickTime 6, however, this behavior––passing a mouse click through a sprite––can be controlled through a new sprite property. In addition, you can control all the sprites in a sprite track through a new sprite track property.
In this section:
Controlling Hit-Testing Mode of an Individual Sprite
Controlling Hit-Testing Mode of a Sprite Track
Handling Mouse Clicks
Sprite Track Setting Enhancements
New Preferred Bit Depth Info Panel
Switching Between Modes
A New Sprite Track Property
Using the SpriteSetSpriteProperty API
New Wired Actions and Operands
Controlling Hit-Testing Mode of an Individual Sprite
In QuickTime 6, each sprite has a property:
canBeHitTested |
This property can have a Boolean value of either TRUE or FALSE.
When a sprite is created, this property is defaulted to TRUE.
The property is an actual property of sprites within a sprite world.
Thus, this property can be set and retrieved by means of sprite
world calls directly: SetSpriteProperty and GetSpriteProperty,
using the kSpritePropertyCanBeHitTested (defined
in Movies.h) constant
and passing and receiving the property value of TRUE or FALSE.
Further, when calling a sprite world’s SpriteHitTest or SpriteWorldHitTest routines,
you can pass the new flag spriteHitTestTreatAllSpritesAsHitTestable to
have SpriteWorld’s hit testing ignore the individual sprites’
own canBeHitTested property
and make all sprites hit testable. Note there is no flag for making
all sprites not hit testable.
Since sprite media uses sprite world, this property can also
be manipulated by means of SpriteMedia calls: SpriteSetSpriteProperty and SpriteGetSpriteProperty,
passing kSpritePropertyCanBeHitTested and
passing/receiving the property value of TRUE or FALSE.
Finally, this property can be manipulated by means of non-primary
source data using the kTrackModifierObjectCanBeHitTested (also
defined in Movies.h)
constant.
Controlling Hit-Testing Mode of a Sprite Track
Sprite Tracks in QuickTime have a property:
allSpritesHitTestingMode |
It can have three values, as defined in MovieToolbox.h:
kSpriteHitTestUseSpritesOwnPropertiesMode = 0, |
kSpriteHitTestTreatAllSpritesAsHitTestableMode = 1, |
kSpriteHitTestTreatAllSpritesAsNotHitTestableMode = 2 |
When a sprite track is created, this property defaults to kSpriteHitTestUseSpritesOwnPropertiesMode.
This property can be specified in the media by having a QTAtom of
type kSpriteTrackPropertyAllSpritesHitTestingMode,
a size of short, and
a value of 0, 1 or 2.
Also, this property can be set at runtime by means of SpriteSetSpriteProperty,
which normally is used to set properties of sprites, but has been
overloaded to now be able to set track properties. To do so, the
spriteID should be equal to FOUR_CHAR_CODE('Trck'),
the property type should be kSpriteTrackPropertyAllSpritesHitTestingMode and
then the property value should be 0, 1, or 2.
Correspondingly, the track property can be retrieved via SpriteGetSpriteProperty with
a sprite ID of FOUR_CHAR_CODE('Trck') and
a property type of kSpriteTrackPropertyAllSpritesHitTestingMode.
Handling Mouse Clicks
When a mouse click occurs within a sprite track, the sprite
media handler will first examine its kSpriteTrackPropertyAllSpritesHitTestingMode property
to see how to handle the click.
If the property is set to kSpriteHitTestUseSpritesOwnPropertiesMode,
the sprite media handler will then use the individual hit testing
property kSpritePropertyCanBeHitTested of
the sprite clicked on to determine if the sprite will “receive”
the click or not. If not (i.e., the sprite’s kSpritePropertyCanBeHitTested property
is FALSE), and the mouse
click is over another sprite, the media handler will then consider
that sprite’s kSpritePropertyCanBeHitTested property
and, if TRUE, will have
that sprite receive the mouse click. If FALSE,
then the process continues with other sprites under the mouse until
one receives it or there are no further sprites at the location
of the mouse click. If none, the sprite media handler will inform
QuickTime it does not wish to handle the mouse click at all, which
will then propagate the mouse click to the Track underneath it in
the movie.
If the kSpriteTrackPropertyAllSpritesHitTestingMode property
of a Sprite Track is set to kSpriteHitTestTreatAllSpritesAsHitTestableMode,
then the sprite media handler will ignore the kSpritePropertyCanBeHitTested sprite
properties of all sprites within the track and instead consider
all the sprites as being able to receive mouse clicks.
If the kSpriteTrackPropertyAllSpritesHitTestingMode property
of a Sprite Track is set to kSpriteHitTestTreatAllSpritesAsNotHitTestableMode,
then the sprite media handler will ignore the kSpritePropertyCanBeHitTested sprite
properties of all sprites within the track and instead consider
all the sprites as being unable to receive mouse clicks.
Sprite Track Setting Enhancements
A Sprite Track enhancement is provided in QuickTime 6 that gives content creators, primarily, and users, secondarily, greater flexibility and control over the pixel depth of the offscreen Graphics World (GWorld) that a Sprite Track utilizes for the composition and management of its sprites.
Limited Control of Offscreen Bit Depth
In earlier versions of QuickTime, there was a limited amount of control a content creator or user had over the offscreen bit depth. In the QuickTime Player Properties 2 Info Panel of a Sprite Track, you could choose one of these options:
Best Depth. (Have the Sprite Track determine empirically the best depth for the track)
256. (8-bit Pixels)
Thousands. (16-bit Pixels
Millions+. (32-bit Pixels)
Each option is at best a suggestion to the Sprite Track as to what the offscreen bit depth should be. Even though, for example, 256 is selected, the Sprite Track might, depending on various parameters––such as monitor bit depth, memory constraints, track or sprite graphics modes––create an 8-bit offscreen, a 16-bit offscreen or even a 32-bit offscreen graphics world.
While this may at times yield better visual results, it also may result in poor memory usage, degraded performance, or even worse––a visual result not intended by the content creator.
Although such a suggestive approach makes sense for the Best Depth setting where the user is explicitly asking the Sprite Track to make such a decision, it may be counter-productive for the other three available choices.
New Preferred Bit Depth Info Panel
QuickTime 6 now provides users with greater control and flexibility over the depth of the Sprite Track offscreen graphics world. To accomplish this, QuickTime 6 has added a new mode, called Actual Depth, that has the same four options as Best Depth, 256, Thousands and Millions+.
Note that for purposes of backward compatibility, QuickTime also maintains the old method, which is called Preferred Mode.
The difference between Actual and Preferred modes is that in Actual Mode, a choice of 256, Thousands or Millions+ dictates that the Sprite Track offscreen depth be exactly as chosen. This provides explicit choice and control over image quality, performance and memory usage.
The option of Best Depth under Actual Mode is analogous to Best Depth under preferred Mode: although the algorithms differ slightly, both modes allow the Sprite Track to determine the offscreen bit depth according to what is best under the current circumstances.
Switching Between Modes
A user can switch any sprite movie from Preferred Mode to Actual Mode and from Actual Mode to Preferred Mode by holding down the Option Key on Mac OS 9 or Mac OS X, or the Alt Key on Windows while clicking the Set button in the Properties 2 Info Panel and subsequently clicking the OK button in the dialog that comes up and allows you to choose a setting. If you choose Cancel in the dialog, there is no change in mode.
The user can tell if a Sprite Track is in Actual or Preferred mode, as the label in the Info Panel switches on the fly between “Actual Depth:” and “Preferred Depth:”.
A New Sprite Track Property
In order to support the new Actual Depth mode, a new Sprite Track Property has been added:
kSpriteTrackPropertyPreferredDepthInterpretationMode = 109 |
This property is optional. If the property is absent, the Sprite Track operates in Preferred Depth mode.
If this property is present, it has a single value, of size short, that can be one of these values:
kSpriteTrackPreferredDepthCompatibilityMode = 0kSpriteTrackPreferredDepthModernMode = 1
If the value of this property is kSpriteTrackPreferredDepthCompatibilityMode,
then the Sprite Track operates in Preferred Depth mode. However,
if the value is kSpriteTrackPreferredDepthModernMode, then
the Sprite Track operates in the new Actual Depth Mode.
Using the
SpriteSetSpriteProperty API
To programmatically set the Sprite Track depth mode, you use
the SpriteSetSpriteProperty call of
the Sprite Media Handler:
pascal ComponentResult SpriteSetSpriteProperty(Media media, |
QTAtomID spriteID, |
long propertyType, |
void *propertyValue); |
Pass a four character code of ‘Trck’ for
the spriteID and specify kSpriteTrackPropertyPreferredDepthInterpretationMode as
the property type. Finally, pass a value of kSpriteTrackPreferredDepthCompatibilityMode or KSpriteTrackPreferredDepthModernMode directly
as the propertyValue.
For example, to Set a Sprite Track to use the Actual Depth mode:
error = SpriteSetSpriteProperty(SpriteMedia, |
‘Trck’, |
kSpriteTrackPropertyPreferredDepthInterpretationMode |
kSpriteTrackPreferredDepthModernMode,); |
New Wired Actions and Operands
The following wired actions and operands are new in QuickTime 6.
New Sprite Actions
The following new actions enable interactive content creators to request, display, and manage images hosted outside of the Movie in which they are used.
kActionSpriteTrackNewImage = 7182, /* ( C string imageURL, QTAtomID |
desiredID) */ |
Loads an image and gives it the next available image index, and the desired ID, if available.
kActionSpriteTrackDisposeImage = 7183, /* (short imageIndex) */ |
Disposes of an image that has previously been loaded and has the supplied image index.
The two new actions, kActionSpriteTrackNewImage and kActionSpriteTrackDisposeImage,
always interact with the images loaded at runtime, and should always
be used to reference indexes higher than those of the images that
are integrated within the movie when it is created.
kActionSpriteTrackNewImage takes
as a parameter the URL of the image to be requested and an ID with
which you can reference that image. Passing an ID of 0 will prompt
this action to assign the next available (unique) ID greater than
the current image count. In comparison, the index assigned will
always be the integer one greater than the current image count.
For example, a target sprite track has 2 images with index/ID
pairs of 1/1 and 2/777, respectively, before this action is executed.
The new image action is called with “image.jpg” as
the URL and a desiredID of
6. Assuming the URL is valid, the new image action will be given
the index 3 and honor the requested ID of 6. If the URL is invalid,
or if ID 1 or 777 is requested, index 3 will not be assigned nor
will any ID, because the image has failed to load. A subsequent
call of kActionSpriteTrackNewImage will
attempt to use index 3 again. For this reason, it is advantageous
for the movie author to maintain a tally or query the number of images
in the Track (kOperandSpriteTrackNumImages)
to predict the new index.
kActionSpriteTrackDisposeImage takes
as a parameter the index of the image to be released from memory.
The image specified by the index is required to be one loaded through kActionSpriteTrackNewImage.
In other words, the index is required to be one previously assigned by
a kActionSpriteTrackNewImage.
Images authored into the movie, either as data or by reference, cannot
be disposed of in this way. Note also that subsequent calls to kActionSpriteTrackNewImage will
not fill the “holes” left by kActionSpriteTrackDisposeImage,
but will continue to increment the index. Thus, kActionSpriteTrackDisposeImage exists
to enable movie authors to manage the memory usage of a movie during
playback––for example, when the movie may only need an externally
referenced image temporarily.
Last updated: 2002-07-01
  |
||
|
|
|
|
| ||
Get information on Apple products.
Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice |