quicktime.app.image
Class QTImageDrawer

java.lang.Object
  |
  +--quicktime.app.image.QTImageDrawer
All Implemented Interfaces:
Compositable, Drawable, DynamicImage, ImageSpec, Listener, Notifier, QTDrawable, Redrawable, Transformable

public class QTImageDrawer
extends java.lang.Object
implements Notifier, QTDrawable, DynamicImage, Redrawable

Enables standard java drawing commands and graphics objects to have their content rendered by QuickTime within a QuickTime graphics space. The QTImageDrawer is a parent container for an object that implements the Paintable interface - which is the object that actually does the drawing using standard java.awt paint commands and graphics objects. The QTImageDrawer implements the DynamicImage interface so can be added to the quicktime.app.display.Compositor object and thus used to draw into the same display space as other QuickTime generated content, or can be a direct client of a QTCanvas.

The isSingleFrame flag that is specified in the constructor allows optimisations to be made by the QTImageDrawer. If this flag is set to Redrawable.kSingleFrame then the QTImageDrawer will only call its Paintable object once to capture the image it Paintable draws. It will then discard all of the objects it has acquired to allow the paint call to the Paintable. If kMultiFrame is specified then on each redraw call the Paintable's paint call is called and the result is redrawn. If the QTImageDrawer is a member of the SWCompositor a similar efficiency can be achieved - if kSingleFrame is specified then when the drawer is added to the Compositor it does not require invalidation so does not create an invalidator as its image data is static. If kMultiFrame is specified then an invalidator is created.

An application can explicitly call prepaint - which is the method that calls the Paintable's paint method at any time. If the application is itself controlling the prepaint call then it will probably want to set and reset the isRedrawing flag as the redraw method determines whether to call prepaint or not based on the value of this flag. Once image data has been captured using the prepaint call to see the results in destination QDGraphics redraw must be called. Thus if an application is calling prepaint itself it will likely want to then setRedrawing to false and would only require redrawing to be set to true if it requires any consequent calls of the redraw method to re-capture image data from a call to prepaint.

The Invalidator determines if the QTImageDrawer requires redrawing and invalidation based on the value of the isRedrawing flag - it redraws and invalidates if isRedrawing returns true. If the application is controlling the prepaint calls (and thus would typically set redrawing to false) then it should invalidate the sprite presenter of the QTImageDrawer.

See Also:
quicktime.app.display.Compositor, quicktime.app.display.Paintable

Field Summary
static int kMultiFrameRetain
          This flag modifies the behaviour of the multiFrame flag in that it will retain resources that are used between invocations of the attached Paintables paint method.
 
Fields inherited from interface quicktime.app.image.Redrawable
kMultiFrame, kSingleFrame
 
Constructor Summary
QTImageDrawer(java.awt.Image image)
          This creates a QTImageDrawer that will grab the pixel data that results from drawing the specified image at its full size.
QTImageDrawer(java.awt.Image image, java.awt.Dimension initialSize)
          This creates a QTImageDrawer that will grab the pixel data that results from a scaled drawing of the specified image at the specified size.
QTImageDrawer(Paintable painter, java.awt.Dimension initialSize, int isSingleFrame)
          This creates the QTImageDrawer object which is the parent container of the Paintable object.
 
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.
 Invalidator addedToCompositor(SWCompositor c, TwoDSprite s)
          Returns an object that invalidates a sprite.
 boolean addNotifyListener(NotifyListener nl)
          This registers the deferred listener.
 int export(GraphicsExporter exporter)
          This method uses the supplied GraphicsExporter to export the current image that is being presented by the QTImageDrawer and its Paintable client.
 int export(GraphicsExporter exporter, QDGraphics offscreenGWorld)
          This method uses the supplied GraphicsExporter to export the current image that is being presented by the QTImageDrawer and its Paintable client.
 Region getClip()
          Returns a region that defines the current clipping region for the object.
 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.
 GraphicsMode getGraphicsMode()
          This gets the current GraphicsMode for the compositor.
 QDGraphics getGWorld()
          QTCanvas calls this method to get the destination QDGraphics of its client.
 EncodedImage getImage()
          This method returns the actual image data.
 java.awt.Dimension getInitialSize()
          Deprecated. since QTJava 4.0
 Matrix getMatrix()
          This will return the client's current display transformations
 QDDimension getOriginalSize()
          Deprecated. since QTJava 4.0
 Paintable getPaintable()
          Returns the Paintable object that is the client of the QTImageDrawer.
 java.awt.Dimension getSize()
          Returns the current size of the offscreen Image that the Painter object will draw into.
 boolean isRedrawing()
          Returns true if the image data may be altered or different upon different calls of the redraw method of the QTDrawable interface
 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.
 Region prepaint()
          This method is used to paint the painter object's image and to grab the resulting pixels into a format that the QTImageDrawer can then draw using the quicktime drawing commands.
 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 removedFromCompositor(SWCompositor c)
          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.
 void setClip(Region reg)
          Sets a region that will define the clipping region for the object
 void setDisplayBounds(QDRect bounds)
          QTCanvas calls this method when it needs to tell the client to adjust its location, width and/or height.
 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 assigns a mapping matrix to the sequence.
 void setRedrawing(boolean redrawFlag)
          If true then the redraw method of the object will fetch new image data from its image source.
 ImagePresenter toImagePresenter()
          This will return an ImagePresenter object from the drawing that has been done by the Paintable object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

kMultiFrameRetain

public static final int kMultiFrameRetain
This flag modifies the behaviour of the multiFrame flag in that it will retain resources that are used between invocations of the attached Paintables paint method. This setting is useful when using the QTImageDrawer frequently to produce of modify pixels, however if this production is only done spasmodically then the kMultiFrame flag is better used to ensure that objects are not held for no good reason.
Constructor Detail

QTImageDrawer

public QTImageDrawer(Paintable painter,
                     java.awt.Dimension initialSize,
                     int isSingleFrame)
This creates the QTImageDrawer object which is the parent container of the Paintable object. You supply an initial size - which defines the drawing area that the paintable object has to draw into. Once created a paintable object's drawing area cannot be resized as far as its relationship to its parent container. If the display area of the QTImageDrawer is changed then the iamge that the Paintable object paints will be scaled accordingly.
Parameters:
painter - the java object that will paint into the space reserved by the QTImageDrawer
initialSize - the size (with origin of 0, 0) that defines the drawing size available to the painter.
isSingleFrame - if the kSingleFrame flag is set the Redrawable will capture the the results of the Paintable's paint call and then discard all of the resources required to call its Paintable (and the Paintable itself). In this case the Paintable's paint method will only be called once. If kSingleFrame is not set the Paintable's paint call will be called whenever redraw() is called and the isRedrawing flag is true.

QTImageDrawer

public QTImageDrawer(java.awt.Image image)
              throws QTAppException
This creates a QTImageDrawer that will grab the pixel data that results from drawing the specified image at its full size. Only single frame java.awt.Images are supported.
Parameters:
image - the java.awt.Image to capture. The size of this image must be known before this constructor can be used.
See Also:
JImagePainter

QTImageDrawer

public QTImageDrawer(java.awt.Image image,
                     java.awt.Dimension initialSize)
This creates a QTImageDrawer that will grab the pixel data that results from a scaled drawing of the specified image at the specified size. Only single frame java.awt.Images are supported.
Parameters:
image - the java.awt.Image to capture.
initialSize - the scaled drawing size of the image.
See Also:
JImagePainter
Method Detail

getPaintable

public Paintable getPaintable()
Returns the Paintable object that is the client of the QTImageDrawer. This call may return null if the QTImageDrawer is a singleFrame based capture and the single frame has already been captured.
Returns:
a Paintable

export

public int export(GraphicsExporter exporter)
           throws QTException
This method uses the supplied GraphicsExporter to export the current image that is being presented by the QTImageDrawer and its Paintable client. The GraphicsExporter's output target must be set before this call is made.
Parameters:
exporter - the GraphicsExporter that will be used to export the pixel image
Returns:
the number of bytes that were written to the destination of the GraphicsExporter

export

public int export(GraphicsExporter exporter,
                  QDGraphics offscreenGWorld)
           throws QTException
This method uses the supplied GraphicsExporter to export the current image that is being presented by the QTImageDrawer and its Paintable client. The GraphicsExporter's output target must be set before this call is made.
Parameters:
exporter - the GraphicsExporter that will be used to export the pixel image
offscreenGWorld - the destination QDGraphics that is used to export (ie. the pixel image).
Returns:
the number of bytes that were written to the destination of the GraphicsExporter

getSize

public java.awt.Dimension getSize()
Returns the current size of the offscreen Image that the Painter object will draw into.
Returns:
the size

getClip

public final Region getClip()
                     throws QTException
Returns a region that defines the current clipping region for the object.
Specified by:
getClip in interface QTDrawable
Returns:
the clipping region

setClip

public final void setClip(Region reg)
                   throws StdQTException
Sets a region that will define the clipping region for the object
Specified by:
setClip in interface QTDrawable
Parameters:
reg - the new clipping region

toImagePresenter

public ImagePresenter toImagePresenter()
                                throws QTException
This will return an ImagePresenter object from the drawing that has been done by the Paintable object. This will copy the image data that has been created. You will have to have attached the QTImageDrawer object to a canvas and called redraw() before this will contain a valid image due to the restriction in java.awt 1.1 that offscreen java Images cannot be created unless the java.awt.Component is attached to a container with an existing native graphics environment.
Returns:
an ImagePresenter object of the drawn java image.

getDescription

public ImageDescription getDescription()
                                throws QTException
This method should return an ImageDescription that describes the image data that the class contains.
Specified by:
getDescription in interface ImageSpec
Returns:
the ImageDescription of an Image

getImage

public EncodedImage getImage()
                      throws QTException
This method returns the actual image data.
Specified by:
getImage in interface ImageSpec
Returns:
the image data

getMatrix

public final Matrix getMatrix()
                       throws StdQTException
This will return the client's current display transformations
Specified by:
getMatrix in interface Transformable
Returns:
the display transformations of the client

setMatrix

public final void setMatrix(Matrix matrix)
                     throws QTException
This method assigns a mapping matrix to the sequence.

QuickTime::SetDSequenceMatrix

Specified by:
setMatrix in interface Transformable
Parameters:
matrix - a Matrix object that specifies how to transform the image during decompression

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
Deprecated. since QTJava 4.0

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

getGWorld

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

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

setDisplayBounds

public 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.
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()
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 boundary of the client

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.

This call will just redraw the current image. If you want to have the Paintable client repaint itself then you must set the redrawing flag to true.

Specified by:
redraw in interface Drawable
Parameters:
invalidRgn - the invalidRgn that the client should redraw
See Also:
setRedrawing(boolean)

setRedrawing

public void setRedrawing(boolean redrawFlag)
If true then the redraw method of the object will fetch new image data from its image source.
Specified by:
setRedrawing in interface Redrawable
Parameters:
redrawFlag - boolean determining whether the current image is redrawn (false) of fresh or updated image data is first retrieved (true).

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

isRedrawing

public boolean isRedrawing()
Returns true if the image data may be altered or different upon different calls of the redraw method of the QTDrawable interface
Specified by:
isRedrawing in interface Redrawable

prepaint

public Region prepaint()
                throws QTException
This method is used to paint the painter object's image and to grab the resulting pixels into a format that the QTImageDrawer can then draw using the quicktime drawing commands. It returns a Region that defins the areas of the pixel data that were changed from the call. It will call the Paintable's paint method.
Returns:
a Region or null if the QTImageDrawer does not yet have an offscreen java.awt.Image object to paint too.

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).
Specified by:
setGraphicsMode in interface Compositable
Following copied from interface: quicktime.app.image.Compositable
Parameters:
gMode - Specifies the graphics mode.

getGraphicsMode

public GraphicsMode getGraphicsMode()
This gets the current GraphicsMode for the compositor.
Specified by:
getGraphicsMode in interface Compositable
Following copied from interface: quicktime.app.image.Compositable
Returns:
a Graphics mode object

addedToCompositor

public Invalidator addedToCompositor(SWCompositor c,
                                     TwoDSprite s)
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.

This call will not return an Invalidator if the QTImageDrawer is presenting a single frame image as the assumption is made that the image data is not changing.

Specified by:
addedToCompositor in interface DynamicImage
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:
quicktime.app.display.SWCompositor

removedFromCompositor

public void removedFromCompositor(SWCompositor c)
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.
Specified by:
removedFromCompositor in interface DynamicImage
Parameters:
c - the SWCompositor it is being removed from

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. If the object is a kind of java.awt.Component then an offscreen image is created from this Component and this Image is used as the pixel resource for a java.awt.Graphics object that is passed to the attached Paintable object. If not nothing is done.
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. If the object is a kind of java.awt.Component then the cached java.awt.Image object that was created in the addedTo method is disposed of.
Specified by:
removedFrom in interface Listener
Parameters:
interest - the object that was the source of interest for the the object that implements this interface.

addNotifyListener

public boolean addNotifyListener(NotifyListener nl)
This registers the deferred listener.
Specified by:
addNotifyListener in interface Notifier
Parameters:
dl - the listener that the DeferredListener notifies when its listen source becomes valid