All Packages Class Hierarchy This Package Previous Next Index
Class quicktime.app.anim.SWCompositor
java.lang.Object
|
+----quicktime.app.spaces.SimpleSpace
|
+----quicktime.app.anim.SWCompositor
- public abstract class SWCompositor
- extends SimpleSpace
- implements QTDisplaySpace, DynamicImage
SWCompositor provides the capability to composit a complex image together of disparate
image sources and then treat the result as a single image which is presented to the user.
It uses the QuickTime SpriteWorld internally to perform the compositing tasks. Thus all
of the actual drawing of the members of a SWCompositor is handled through the interaction
between the SpriteWorld and Sprite classes of quicktime.
The SpriteWorld itself is wrapped by the SWCompositor class, and to represent the Sprite
class it uses the TwoDSprite. The TwoDSprite is a presenter - it presents image information
and the presenation of the image information within the context of the SWCompositor's SpriteWorld
is determined by the matrix, graphics mode, layer and visibility of the TwoDSprite's Sprite object.
To create a Sprite you need a valid SpriteWorld. To create a SpriteWorld you need a valid QDGraphics
destination. Depending on whether a SWCompositor is visible or not you may or may not have a valid
destination QDGraphics. The interaction between the SWCompositor and its TwoDSprite presenters
handles the saving and creating of SpriteWorlds and their Sprites - the application does not need to
deal specifically with this issue.
The SWCompositor has been designed without the requirement that its members be TwoDSprites. It maybe more
convenient for an application to add members of a Compositor that are a source of image data and
have the addMember method deal with the mechanics of creating the TwoDSprite presenter. Thus there are
also methods that must be defined by the subclass for getting a member's TwoDSprite, and getting a TwoDSprite's
member. This is important to understand for the following reason. Once a member
has been added to a SWCompositor, it is the presenter within the SWCompositor itself (the TwoDSprite) that must be
interacted with to effect the display characteristics of the member in the SWCompositor. Whilst a subclass
may provide the capability to create the TwoDSprite presenter with display characteristics like Matrix and
GraphicsMode, once the member is added altering the member's display characteristics directly may or may not effect
the display characteristics of the member in the SWCompositor. Thus an application is better to always interact
with the member's TwoDSprite presenter.
After a member is added to the SWCompositor the subclass should call the postProcessAdd (and remove in the case of
a removeMember call). This call will look at the member that is being added and will perform two services. If the
new member is an instance of the Notifier class then the SWCompositor registers the Notifer with the TwoDSprite presenter
as the NotifyListener. That way a Sprite who presents image data that is not available at the time the member is added
can still prepare itself for displaying an image when its Notifier notifies the TwoDSprite that its image data is valid.
If the new member is an instance of DynamicImage, then this method will also call that member's addedToCompositor method
to allow this new member to establish the invalidation mechanism it uses. Explicit invalidation is required for the SpriteWorld
to redraw a Sprite that presents image data that is changing (such as a Movie) when nothing about the Sprite's presentation
has changed.
The subclass defines completely the storage mechanism and protocols of its members.
- See Also:
- SpriteWorld, Sprite, TwoDSprite, Compositor
-
taskFlag
- This flag is used when the task method is called.
-
SWCompositor(QDGraphics, QDColor, QDGraphics, int, int, Protocol)
- Used by subclasses to construct a SWCompositor.
-
addedToCompositor(SWCompositor, TwoDSprite)
- Returns an object that invalidates a sprite.
-
addMember(Object, int)
- Adds a member to the QTDisplaySpace at the specified layer.
-
createMembers()
- This method is called after the Compositor has been added to a valid QDGraphics and the
sprites can be added to the spriteworld.
-
getBackLayer()
- Returns the layer of the backmost member in the display space.
-
getClip()
- Returns the current clipping region used by the sprite world
-
getCompositable(Object)
- This will return the TwoDSprite for the member as a Compositable object to enable
an application to get and set the graphics mode presentation of the member object.
-
getDescription()
- This method should return an ImageDescription that describes
the image data that the class contains.
-
getDisplayBounds()
- QTCanvas calls this method when it needs to get the client's
location, width and/or height.
-
getFrontLayer()
- Returns the layer of the frontmost member in the display space.
-
getGraphicsMode()
- Sets the graphics mode of the SpriteDisplay object - this will be restored
on each subsequent creation of the internal SpriteWorld.
-
getGWorld()
- QTCanvas calls this method to get the destination QDGraphics of its client.
-
getImage()
- This method returns the actual image data.
-
getInitialSize()
- This method returns the original size before the transformations
specified in the returned matrix are applied.
-
getInvalidatorList()
- Returns the list of invalidator objects for the Compositor's sprites
that have a dynamic image source.
-
getLayerable(Object)
- This will return the TwoDSprite for the member as a Layerable object to enable
an application to get and set the layer presentation of the member object.
-
getMatrix()
- This will return the client's current display transformations
-
getMemberInvalidator(Object)
- Returns the invalidator that is associated with the supplied
member if the member has an Invalidator.
-
getMemberSprite(Object)
- This method returns the TwoDSprite presenter that is presenting the image data
of the given member.
-
getParent()
- Returns the SWCompositor that this is the parent container of this SWCompositor.
-
getSpriteMember(TwoDSprite)
- This method returns the member that is being presented by the supplied TwoDSprite presenter.
-
getStatistics()
- The compositor's frame rate is calculated by the number of times it is tickled from
the time an application calls resetStatistics and is only valid if the rate of
the Compositor's Timer is not zero.
-
getTransformable(Object)
- This will return the TwoDSprite for the member as a Transformable object to enable
an application to get and set the display presentation (its location, scale, etc) of the member object.
-
hasRecordMovie()
- Returns true if the SWCompositor has a RecordMovie object.
-
idle()
- This method can be called to explicitly force the SWCompositor to
redraw itself.
-
isAutoRedrawing()
- Returns the current state of the auto redrawing flag.
-
postProcessAdd(Object, TwoDSprite)
- This method should be called by the subclass after the member has been added to the SWCompositor.
-
postProcessRemove(Object, TwoDSprite)
- This method should be called by the subclass before the member has been removed from the SWCompositor.
-
redraw(Region)
- QTCanvas calls this method when the client should redraw itself.
-
removedFromCompositor(SWCompositor)
- When a dynamic image class is removed from a SWCompositor this
method is called to allow the class to cleanup any of the invalidation
processes it had established in the addedToCompositor call.
-
resetStatistics()
- Resets the internal counters that are used to calculate the frame rate of the Compositor.
-
saveMembers()
-
This method is called if a SpriteWorld has previously been created and the destination
QDGraphics or QDGraphics is about to go away (such as removing a SpriteWorld from a QTCanvas).
-
setAutoRedrawing(boolean)
- If a SWCompositor's time rate is equal to zero, changing a property of a member's sprite
requires the SWCompositor to be redrawn to see this change.
-
setClip(Region)
- This method sets the sprite world's clip.
-
setDisplayBounds(QDRect)
- QTCanvas calls this method when it needs to tell the client to adjust
its location, width and/or height.
-
setGraphicsMode(GraphicsMode)
- Sets the current graphics mode.
-
setGWorld(QDGraphics)
- QTCanvas calls this method to give the client the QDGraphics object it should
use to do its drawing.
-
setLocation(int, int)
- A convenience method to set the position of a QTDrawable object.
-
setMatrix(Matrix)
- This method sets the current matrix of the Transformable object to
the new matrix.
-
setRecordMovie(RecordMovie)
- This method allows the application to register the intent to record a movie out of the
compositing output of the SWCompositor.
-
sprites()
- This returns an Enumeration that allows your application to iterate over the TwoDSprite
presenters that are responsible for presenting the image data within the Compositor.
-
tickle(float, int)
- The Timer invokes the tickle method when the invocation constraints of
the Timer are reached.
-
toString()
- Return a string representation of this object.
taskFlag
public int taskFlag
- This flag is used when the task method is called.
You can use any of the values from the idle in flags of the SpriteWorld
SWCompositor
protected SWCompositor(QDGraphics spriteGWorld,
QDColor backgroundColor,
QDGraphics background,
int scale,
int period,
Protocol defaultProtocol) throws QTException
- Used by subclasses to construct a SWCompositor. The subclass must specify a background or a backgroundColor
but not both.
- Parameters:
- spriteGWorld - this the buffer which the internal SpriteWorld uses to composit its image into.
- background - this is background that can be supplied to the SpriteWorld
- backgroundColor - this is background color that can be supplied to the SpriteWorld
- scale - the initial scale of the Space's timer
- period - the initial period of the Space's timer
- defaultProtocol - the minimal Protocol that members of the SWCompositor must meet
resetStatistics
public void resetStatistics()
- Resets the internal counters that are used to calculate the frame rate of the Compositor.
getStatistics
public float getStatistics()
- The compositor's frame rate is calculated by the number of times it is tickled from
the time an application calls resetStatistics and is only valid if the rate of
the Compositor's Timer is not zero. If this rate is zero this returns 0.
Thus an application uses these calls like:
myCompositor.resetStatistics();
Thread.sleep (2000); //sleep the stat's thread for 2 seconds to allow gathering of profile info
float fps = myCompositor.getStatistics();
This call does not reset the internal counters, so consequent calls of getStatistics
will return frames rendered over a longer period of time.
getInvalidatorList
public Enumeration getInvalidatorList()
- Returns the list of invalidator objects for the Compositor's sprites
that have a dynamic image source. If no members of the Compositor
are dynamic image sources this call returns null.
- Returns:
- an Enumeration
getMemberInvalidator
public synchronized Invalidator getMemberInvalidator(Object member)
- Returns the invalidator that is associated with the supplied
member if the member has an Invalidator. If the member doesn't
or the object is not a member of the Compositor this returns null.
- Parameters:
- member - a member of the Compositor
- Returns:
- an Invalidator
setRecordMovie
public void setRecordMovie(RecordMovie rm) throws QTException
- This method allows the application to register the intent to record a movie out of the
compositing output of the SWCompositor. After each composit cycle the SWCompositor will
call the frameReady of the RecordMovie object as long as the frameReady method returns true.
- Parameters:
- rm - the RecordMovie object
hasRecordMovie
public boolean hasRecordMovie()
- Returns true if the SWCompositor has a RecordMovie object.
- Returns:
- a boolean
getDescription
public ImageDescription getDescription() throws QTException
- This method should return an ImageDescription that describes
the image data that the class contains.
- Returns:
- the ImageDescription of an Image
getImage
public EncodedImage getImage() throws QTException, IndexOutOfBoundsException
- This method returns the actual image data.
- Returns:
- the image data
getParent
public SWCompositor getParent()
- Returns the SWCompositor that this is the parent container of this SWCompositor.
This call may return null if the calling object is the top level containing space.
- Returns:
- the parent SWCompositor or null
getMatrix
public Matrix getMatrix() throws StdQTException
- This will return the client's current display transformations
- Returns:
- the display transformations of the client
setMatrix
public void setMatrix(Matrix matrix) throws QTException
- This method sets the current matrix of the Transformable object to
the new matrix.
getInitialSize
public Dimension getInitialSize() throws QTException
- This method returns the original size before the transformations
specified in the returned matrix are applied.
getGWorld
public QDGraphics getGWorld()
- QTCanvas calls this method to get the destination QDGraphics of its client.
- Returns:
- a QDGraphics object or null
setGWorld
public synchronized void setGWorld(QDGraphics cgp) throws QTException
- QTCanvas calls this method to give the client the QDGraphics object it should
use to do its drawing. If the incoming QDGraphics is the QDGraphics.scratch then
the drawable will not be visible and can disable itself.
If a client is unable to set the graphics world it should throw an exception.
- Parameters:
- cgp - a QDGraphics object
setDisplayBounds
public synchronized void setDisplayBounds(QDRect bounds) throws StdQTException
- QTCanvas calls this method when it needs to tell the client to adjust
its location, width and/or height. All values are in pixels.
- Parameters:
- bounds - the new size and location.
setLocation
public void setLocation(int x,
int y) throws QTException
- A convenience method to set the position of a QTDrawable object.
- Parameters:
- x - the new x location
- y - the new y location
getDisplayBounds
public QDRect getDisplayBounds() throws QTException
- QTCanvas calls this method when it needs to get the client's
location, width and/or height. All values are in pixels.
- Returns:
- bounds the new size and location.
redraw
public final void redraw(Region invalidRgn) throws QTException
- QTCanvas calls this method when the client should redraw itself.
If the canvas is able to discern that only a part of the client's
drawing area needs to be redrawn - then this area shall be passed in
using the invalidRgn. Otherwise this will be null in which case the
client should redraw itself entirely.
- Parameters:
- invalidRgn - the invalidRgn that the client should redraw
isAutoRedrawing
public boolean isAutoRedrawing()
- Returns the current state of the auto redrawing flag.
- Returns:
- a boolean.
- See Also:
- setAutoRedrawing
setAutoRedrawing
public void setAutoRedrawing(boolean flag)
- If a SWCompositor's time rate is equal to zero, changing a property of a member's sprite
requires the SWCompositor to be redrawn to see this change. This is done automatically for
you by the TwoDSprite class. However, if an application wishes to change a number of properties of
a given sprite or sprites, redrawing the Compositor after each change can be an udesirable side-effect
of this automatic redrawing capability. The application can temporarily turn or or off this capability of
the SWCompositor, which is controlled by the TwoDSprite, by changing the setting of the auto redrawing flag.
If this auto redrawing flag is false, the TwoDSprite will not automatically redraw its parent SWCompositor,
if the flag is true then the TwoDSprite will redraw its parent.
Typically an application will set this flag to false, make the changes to its sprites, then reset the flag
to true. The application will still have to redraw the SWCompositor after making the changes to its
member sprites.
If the rate of the SWCompositor's TimeBase is not equal to zero, then this flag has no effect as the composite
cycle is being controlled by the time-based rendering cycle.
Regardless of the value of this flag, the SWCompositor will still redraw itself when the redraw method
is called. This flag only controls whether the SWCompositor's member sprites will automatically redraw their parents.
- Parameters:
- flag - controls the auto redrawing capability of a SWCompositor. By default the auto-redrawing is set to true.
idle
protected void idle() throws QTException
- This method can be called to explicitly force the SWCompositor to
redraw itself. It does not ticke the Compositor - so no ticklish or
invalidate actions will be performed. It will just force the internal
QuickTime SpriteWorld to do a composit cycle and redraw those areas
of the SpriteWorld which are invalid.
In the normal course of operations an application does not need to call this method
but it is particularly useful for profiling. It should only
be called if the SpriteWorld that is presenting the SWCompositor is NOT null - otherwise
a NullPointerException will be thrown.
setClip
public void setClip(Region clipRgn) throws QTException
- This method sets the sprite world's clip.
QuickTime::SetSpriteWorldClip()
- Parameters:
- clipRgn - Specifies the clipping region.
getClip
public Region getClip()
- Returns the current clipping region used by the sprite world
- Returns:
- the current clip region.
tickle
public boolean tickle(float er,
int time) throws QTException
- The Timer invokes the tickle method when the invocation constraints of
the Timer are reached.
- Overrides:
- tickle in class SimpleSpace
removedFromCompositor
public synchronized void removedFromCompositor(SWCompositor c) throws QTException
- When a dynamic image class is removed from a SWCompositor this
method is called to allow the class to cleanup any of the invalidation
processes it had established in the addedToCompositor call.
- Parameters:
- c - the SWCompositor it is being removed from
addedToCompositor
public Invalidator addedToCompositor(SWCompositor c,
TwoDSprite s) throws QTException
- Returns an object that invalidates a sprite. When a DynamicImage
is a member of a SWompositor and the DynamicImage presents a
changing image (for example a movie), the TwoDSprite that presents
that image in the SWCompositor must be invalidated so that it will
redraw the Sprites image in the next composit cycle. The Invalidator
object is used to perform this function by the SWCompositor if the object
itself cannot perform the invalidation.
Can return null if the DynamicImage does not require the SWCompositor
to invalidate it (or the object is in a state where its image won't change).
The Invalidators provided with objects that implement the DynamicImage
interface will execute at the scale and period of the Compositor
when they are created.
- Parameters:
- c - the Compositor in which the DynamicImage is a member
- s - the TwoDSprite that is presenting the DynamicImage's image in
the Compositor. This is the sprite that must be invalidated.
- Returns:
- an Invalidator or null if invalidation is not required
- See Also:
- SWCompositor
getGraphicsMode
public GraphicsMode getGraphicsMode()
- Sets the graphics mode of the SpriteDisplay object - this will be restored
on each subsequent creation of the internal SpriteWorld. This may be null
if not specified
- Returns:
- the current graphics mode or null
setGraphicsMode
public void setGraphicsMode(GraphicsMode mode) throws QTException
- Sets the current graphics mode.
- Parameters:
- mode - the new graphics mode
getMemberSprite
public abstract TwoDSprite getMemberSprite(Object member)
- This method returns the TwoDSprite presenter that is presenting the image data
of the given member. It returns null if the object is not a member.
- Parameters:
- member - the member object
- Returns:
- the member's TwoDSprite presenter
sprites
public abstract Enumeration sprites()
- This returns an Enumeration that allows your application to iterate over the TwoDSprite
presenters that are responsible for presenting the image data within the Compositor.
- Returns:
- an Enumeration;
getSpriteMember
public abstract Object getSpriteMember(TwoDSprite sprite)
- This method returns the member that is being presented by the supplied TwoDSprite presenter.
It returns null if the TwoDSprite is not present in the Compositor.
- Parameters:
- sprite - the TwoDSprite presenter
- Returns:
- the member that is being presented by the supplied TwoDSprite presenter
getCompositable
public Compositable getCompositable(Object member)
- This will return the TwoDSprite for the member as a Compositable object to enable
an application to get and set the graphics mode presentation of the member object.
- Parameters:
- member - the member object
- Returns:
- the member's TwoDSprite presenter
getLayerable
public Layerable getLayerable(Object member)
- This will return the TwoDSprite for the member as a Layerable object to enable
an application to get and set the layer presentation of the member object.
- Parameters:
- member - the member object
- Returns:
- the member's TwoDSprite presenter
getTransformable
public Transformable getTransformable(Object member)
- This will return the TwoDSprite for the member as a Transformable object to enable
an application to get and set the display presentation (its location, scale, etc) of the member object.
- Parameters:
- member - the member object
- Returns:
- the member's TwoDSprite presenter
postProcessAdd
protected synchronized void postProcessAdd(Object member,
TwoDSprite s) throws QTException
- This method should be called by the subclass after the member has been added to the SWCompositor.
If the member is itself a TwoDSprite the member and s arguments should be the TwoDSprite object.
If the member is an instance of the DynamicImage interface then the addedToCompositor method
will be called on the member and if required the member can return an Invalidator object which is then
added to the SWCompositor's Invalidator list. This list is the last list run before the SpriteWorld's
composit cycle is run. If the member is an instance of Notifier then the TwoDSprite will be set as
the NotifyListener of the member and the member can then notify the TwoDSprite when its image data
is valid and the TwoDSprite can present it.
- Parameters:
- member - the new member that has been added.
- s - the TwoDSprite that will present this member
postProcessRemove
protected synchronized void postProcessRemove(Object member,
TwoDSprite s) throws QTException
- This method should be called by the subclass before the member has been removed from the SWCompositor.
If the member is itself a TwoDSprite the member and s arguments should be the TwoDSprite object.
If the member is an instance of the DynamicImage interface then the removedFromCompositor method
will be called on the member allowing the member to cleanup its invalidation requirements.
If the member had required invalidation then its Invalidator object will be removed from the
Invalidator list.
- Parameters:
- member - the new member that has been removed.
- s - the TwoDSprite that presented this member
saveMembers
protected void saveMembers() throws QTException
- This method is called if a SpriteWorld has previously been created and the destination
QDGraphics or QDGraphics is about to go away (such as removing a SpriteWorld from a QTCanvas).
Any Spirte objects that were attached to the sprite world will be invalid
after this call so you should ensure that you remove any possibility of a method being called
on any of these sprites. If sprites and or an action list has been added to the Compositor
then those sprites will be saved and reinstantiated if a consequent createSprites method is received.
createMembers
protected void createMembers() throws QTException
- This method is called after the Compositor has been added to a valid QDGraphics and the
sprites can be added to the spriteworld. Any sprites that the Compositor knows about
through an action list or sprites being explicitly added, will be recreated at this
point. If a subclass overrides this method to create sprites on an initial call and add
them to the Compositor then on subsequent calls the subclass should call super.createSprites
to ensure that the previous sprites are recreated.
toString
public String toString()
- Return a string representation of this object.
- Returns:
- a String
- Overrides:
- toString in class Object
All Packages Class Hierarchy This Package Previous Next Index