quicktime.app.image
Class QTEffect

java.lang.Object
  |
  +--quicktime.app.image.QTEffect
All Implemented Interfaces:
Drawable, Listener, QTDrawable, Redrawable, Transformable
Direct Known Subclasses:
CompositableEffect, QTFilter

public class QTEffect
extends java.lang.Object
implements QTDrawable, Redrawable

QTEffect forms the base class for visual effects that can be applied to images. Depending on the effect itself, visual effects can be applied over a length of time, or once only. They can be applied to no source images, a single image or multiple images.

The QTEffect class itself forms a base class that given a rectangular region will apply some visual effect (like fire/ripples). to its destination graphics. There are two subclasses - QTFilter which is an effect that is applied to a single source image and QTTransition which is an effect that is applied to two images, transitioning from the source image to the destination image.


Fields inherited from interface quicktime.app.image.Redrawable
kMultiFrame, kSingleFrame
 
Constructor Summary
QTEffect()
          Creates a QTEffect with kMultiFrame set with a default initial size of 0, 0.
QTEffect(java.awt.Dimension d)
          Deprecated. since QTJava 4.0
QTEffect(int multiFrameFlag)
          Creates a QTEffect with kMultiFrame set with a default initial size of 0, 0.
QTEffect(int multiFrameFlag, java.awt.Dimension d)
          Deprecated. since QTJava 4.0
QTEffect(int multiFrameFlag, QDDimension d)
          Creates a QTEffect.
 
Method Summary
 void addedTo(java.lang.Object interest)
          This method is called by the specified object when the instance of the class that implements this interface is added to the object that is the source of the interest.
 void checkForEffect(int effectType)
          This will make sure the component (effect) is there and can set its parameter list for display.
 Region getClip()
          Returns the current clipping region of the effect or null if the effect is not clipped
 int getCurrentFrame()
          This returns the current frame that the effect is rendering.
 ImageDescription getDescription()
          This method should return an ImageDescription that describes the image data that the class contains.
 QDRect getDisplayBounds()
          QTCanvas calls this method when it needs to ask the client for its boundary.
 DSequence getDSequence()
          Returns the DSequence that is used by the QTEffect.
 AtomContainer getEffect()
          This will return a copy of the AtomContainer that contains the current effect settings.
 int getFrames()
          Returns the current maximum number of frames that an effect will run for
 GraphicsMode getGraphicsMode()
          This gets the current GraphicsMode for the QTEffect.
 QDGraphics getGWorld()
          QTCanvas calls this method to get the destination QDGraphics of its client.
 EncodedImage getImage()
          This method returns the actual image data - in this case the effect's atom container.
 java.awt.Dimension getInitialSize()
          Deprecated. since QTJava 4.0
 Matrix getMatrix()
          This will return the client's current display transformations
 QDDimension getOriginalSize()
          This method returns the original size before the transformations specified in the returned matrix are applied.
 boolean isRedrawing()
          Returns the state of the redraw flag
 boolean isSingleFrame()
          Returns true if the Redrawable only has a single frame to render and thus will never need to re-acquire or redraw its image.
 void redraw(Region invalidRgn)
          QTCanvas calls this method when the client should redraw itself.
 void removedFrom(java.lang.Object interest)
          This method is called by the specified object when the instance of the class that implements this interface is removed from the object that is the source of the interest.
 void setClip(Region r)
          This will set the clipping of the effect - it defines the region of the source image that the effect will be applied to.
 void setDisplayBounds(QDRect bounds)
          QTCanvas calls this method when it needs to tell the client to adjust its location, width and/or height.
 void setEffect(AtomContainer effectParams)
          This method will take the incoming parameters and use this as the control parameters for the effect.
 void setGraphicsMode(GraphicsMode mode)
          This sets the GraphicsMode for the Compositor when it draws its composited contents to its destination QDGraphics (typically the QTCanvas).
 void setGWorld(QDGraphics cgp)
          QTCanvas calls this method to give the client the QDGraphics object it should use to do its drawing.
 void setLocation(int x, int y)
          A convenience method to set the position of a QTDrawable object.
 void setMatrix(Matrix matrix)
          This method sets the current matrix of the Transformable object to the new matrix.
 void setRedrawing(boolean redrawFlag)
          If true then the current frame of the effect is drawn on redraw.
protected  boolean setUpSequence()
          This method is called by a number of other methods to create the DSequence that is used to render the QTEffect.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

QTEffect

public QTEffect()
         throws QTException
Creates a QTEffect with kMultiFrame set with a default initial size of 0, 0.

QTEffect

public QTEffect(java.awt.Dimension d)
         throws QTException
Deprecated. since QTJava 4.0

Creates a QTEffect with kMultiFrame set and the specified initial size.
Parameters:
d - the initialSize of the effect.

QTEffect

public QTEffect(int multiFrameFlag)
         throws QTException
Creates a QTEffect with kMultiFrame set with a default initial size of 0, 0.
Parameters:
multiFrameFlag - is normally set to kMultiFrame. The setting of this flag will also set the initial setting of the redrawing flag. QTEffects require redrawing so the default value is kMultiFrame. Typically the QTFilters do not require redrawing so their default value is kSingleFrame. QTTransitions are multiframes and so do require redrawing.

QTEffect

public QTEffect(int multiFrameFlag,
                java.awt.Dimension d)
         throws QTException
Deprecated. since QTJava 4.0

Creates a QTEffect. The specified multiFrameFlag parameter should be set to Redrawable.kMultiFrame as all of the existing QTEffects require redrawing for their visual effect to be apparent.
Parameters:
multiFrameFlag - is normally set to kMultiFrame. The setting of this flag will also set the initial setting of the redrawing flag. QTEffects require redrawing so the default value is kMultiFrame. Typically the QTFilters do not require redrawing so their default value is kSingleFrame. QTTransitions are multiframes and so do require redrawing.
d - the initialSize of the effect.
See Also:
()

QTEffect

public QTEffect(int multiFrameFlag,
                QDDimension d)
         throws QTException
Creates a QTEffect. The specified multiFrameFlag parameter should be set to Redrawable.kMultiFrame as all of the existing QTEffects require redrawing for their visual effect to be apparent.
Parameters:
multiFrameFlag - is normally set to kMultiFrame. The setting of this flag will also set the initial setting of the redrawing flag. QTEffects require redrawing so the default value is kMultiFrame. Typically the QTFilters do not require redrawing so their default value is kSingleFrame. QTTransitions are multiframes and so do require redrawing.
d - the initialSize of the effect.
Method Detail

setRedrawing

public void setRedrawing(boolean redrawFlag)
If true then the current frame of the effect is drawn on redraw. If false then the effect is only applied when you explicitly apply it For an effect or a filter the default setting for this flag is true - the effect is redrawn on redraw. For a Transition the default setting for this flag is false - the source of the effect only is redrawn.
Specified by:
setRedrawing in interface Redrawable
Parameters:
redrawFlag - boolean indicating redraw behaviour

isRedrawing

public boolean isRedrawing()
Returns the state of the redraw flag
Specified by:
isRedrawing in interface Redrawable
Returns:
boolean

isSingleFrame

public boolean isSingleFrame()
Returns true if the Redrawable only has a single frame to render and thus will never need to re-acquire or redraw its image. Certain Redrawable objects are able to optimise their resources knowing this constraint.
Specified by:
isSingleFrame in interface Redrawable
Following copied from interface: quicktime.app.image.Redrawable
Returns:
a boolean

setGraphicsMode

public void setGraphicsMode(GraphicsMode mode)
                     throws QTException
This sets the GraphicsMode for the Compositor when it draws its composited contents to its destination QDGraphics (typically the QTCanvas).

getGraphicsMode

public GraphicsMode getGraphicsMode()
This gets the current GraphicsMode for the QTEffect.

setClip

public void setClip(Region r)
             throws StdQTException
This will set the clipping of the effect - it defines the region of the source image that the effect will be applied to.
Specified by:
setClip in interface QTDrawable
Parameters:
r - the clipping region

getClip

public Region getClip()
Returns the current clipping region of the effect or null if the effect is not clipped
Specified by:
getClip in interface QTDrawable
Following copied from interface: quicktime.app.display.QTDrawable
Returns:
the clipping region

getEffect

public AtomContainer getEffect()
                        throws StdQTException
This will return a copy of the AtomContainer that contains the current effect settings. You can alter the values of this container but you must call setEffect for those new values to be used by the effect.

setEffect

public void setEffect(AtomContainer effectParams)
               throws QTException
This method will take the incoming parameters and use this as the control parameters for the effect. The container will be locked for the duration of the effect object's life or until another effect is set.
Parameters:
effectParams - the parameters that determine the effect that is run

setUpSequence

protected boolean setUpSequence()
                         throws QTException
This method is called by a number of other methods to create the DSequence that is used to render the QTEffect. When called the method will create a new DSequence if the required state has been established to enable the creation of the DSequence.
Returns:
true if a new DSequence was created, otherwise false.

getFrames

public int getFrames()
Returns the current maximum number of frames that an effect will run for

getCurrentFrame

public int getCurrentFrame()
This returns the current frame that the effect is rendering.
Returns:
the current frame

checkForEffect

public void checkForEffect(int effectType)
                    throws QTException
This will make sure the component (effect) is there and can set its parameter list for display. If the effect is not present then an exception with a paramErr will be thrown
Parameters:
effectType - the effect type to check for

addedTo

public void addedTo(java.lang.Object interest)
This method is called by the specified object when the instance of the class that implements this interface is added to the object that is the source of the interest.
Specified by:
addedTo in interface Listener
Parameters:
interest - the object that is to be the source of interest for the the object that implements this interface.

removedFrom

public void removedFrom(java.lang.Object interest)
This method is called by the specified object when the instance of the class that implements this interface is removed from the object that is the source of the interest.
Specified by:
removedFrom in interface Listener
Parameters:
interest - the object that was the source of interest for the the object that implements this interface.

setGWorld

public 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.
Specified by:
setGWorld in interface QTDrawable
Parameters:
cgp - a QDGraphics object

getGWorld

public QDGraphics getGWorld()
                     throws QTException
QTCanvas calls this method to get the destination QDGraphics of its client.
Specified by:
getGWorld in interface QTDrawable
Returns:
a QDGraphics object or null

setDisplayBounds

public void setDisplayBounds(QDRect bounds)
                      throws QTException
QTCanvas calls this method when it needs to tell the client to adjust its location, width and/or height. All values are in pixels.
Specified by:
setDisplayBounds in interface Drawable
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.
Specified by:
setLocation in interface QTDrawable
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 ask the client for its boundary. All values are in pixels.
Specified by:
getDisplayBounds in interface Drawable
Returns:
the display boundary of the client

getDSequence

public DSequence getDSequence()
Returns the DSequence that is used by the QTEffect. This object may be null if the QTEffect is not currently attached to a valid destination QDGraphics. The application should not cache this sequence object for any length of time - as if the destination QDGraphics is changed the DSequence is thrown away and a new one is created.

getImage

public EncodedImage getImage()
This method returns the actual image data - in this case the effect's atom container.
Returns:
the image data

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

getInitialSize

public java.awt.Dimension getInitialSize()
                                  throws QTException
Deprecated. since QTJava 4.0

This method returns the original size before the transformations specified in the returned matrix are applied.
See Also:
()

getOriginalSize

public QDDimension getOriginalSize()
                            throws QTException
This method returns the original size before the transformations specified in the returned matrix are applied.
Specified by:
getOriginalSize in interface Transformable
Returns:
a Dimension

getMatrix

public Matrix getMatrix()
                 throws QTException
This will return the client's current display transformations
Specified by:
getMatrix in interface Transformable
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.
Specified by:
setMatrix in interface Transformable

redraw

public 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.
Specified by:
redraw in interface Drawable
Parameters:
invalidRgn - the invalidRgn that the client should redraw