Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD