readme-jai.txt

jai-1_1_2.rar

While still logged in to the remote server machine, set the CLASSPATH and
LD_LIBRARY_PATH environment variables as required for JAI (see the INSTALL
file) and start the remote imaging server:

$ CLASSPATH=$JAI/lib/jai_core.jar:$JAI/lib/jai_codec.jar:\
            $JAI/lib/mlibwrapper_jai.jar
$ export CLASSPATH
$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAI/lib
$ export LD_LIBRARY_PATH
$ java \
-Djava.rmi.server.codebase=\
"file:$JAI/lib/jai_core.jar file:$JAI/lib/jai_codec.jar" \
-Djava.rmi.server.useCodebaseOnly=false \
-Djava.security.policy=file:$JAI/policy \
com.sun.media.jai.rmi.RMIImageImpl

For example, when the above steps are executed on a machine with IP address
123.456.78.90 the following is printed:

Server: using host 123.456.78.90 port 1099
Registering image server as
  "rmi://123.456.78.90:1099/RemoteImageServer".
Server: Bound RemoteImageServer into
   the registry.

4. Run the Local Application

Run the local application making sure that the serverName parameter of any
RemoteImage constructors corresponds to the machine on which the remote
image server is running. For example, if the machine with IP address
123.456.78.90 above is named myserver the serverName parameter of any
RemoteImage() constructors should be "myserver".

What's New

This section describes the significant changes and improvements to the Java
Advanced Imaging API and its reference implementation since the previous
release.

Core Classes

   * Internal Data Array Recycling

     To improve memory usage, the concept of "array recycling" was developed
     and implemented. Array recycling effectively traps tiles which will no
     longer be used. Subsequent tile, i.e., Raster creation attempts first
     to use the memory "salvaged" from these recycled tiles. Only if this is
     not possible will new data arrays be allocated.

     The internal arrays from recycled tiles are stored in a mapping from
     derived key values to References to the arrays. Thus these arrays are
     subject to garbage collection. The keys in the mapping are derived from
     the data type of the array, the number of data banks, and the size of
     the data banks. Maximal recycling therefore will occur when tiles
     having the same characteristics are used throughout an application.

     The only tiles which are recycled by default are those which are
     created within JAI and also go out of scope within JAI. This occurs for
     example in OpImage implementations which create Rasters to contain data
     cobbled from sources.

     In order to get more tile recycling, some action is required on the
     part of the developer:

       1. Set a RenderingHint.

          A mapping of the key JAI.KEY_CACHED_TILE_RECYCLING_ENABLED should
          be provided to the appropriate rendering hint, e.g., as

              // Enable recycling of cached tiles for all ops in this instance.
              JAI.getDefaultInstance().setRenderingHint(
                  JAI.KEY_CACHED_TILE_RECYCLING_ENABLED,
                  Boolean.TRUE);

              // Enable recycling of tiles for this op alone.
              ParameterBlock paramBlock;
              RenderingHints hints;
              hints.put(JAI.KEY_CACHED_TILE_RECYCLING_ENABLED, Boolean.TRUE);
              RenderedOp someOp = JAI.create("mosaic", paramBlock, hints);

          The effect of this will be to allow all tiles stored in a
          TileCache for a given image to be recycled when that image is
          finalized by the garbage collector.

       2. Invoke dispose() on defunct PlanarImages

          Invoking dispose() will cause the tiles to be flushed from the
          cache and recycled. Care should be taken when performing this
          procedure since unexpected results may occur if an application
          subsequently refers to a disposed image.

          For more information please refer to the documentation of the
          RenderingHints.Key definitions KEY_TILE_FACTORY,
          KEY_TILE_RECYCLER, and KEY_CACHED_TILE_RECYCLING_ENABLED in the
          JAI class, the interface definitions of TileRecycler and
          TileFactory and the class definition of RecyclingTileFactory, as
          well as the constructors of OpImage and PlanarImage, and finally
          the dispose() methods of PlanarImage, RenderedOp and OpImage.

   * Exception Handling

     To improve exception handling, an interface ImagingListener and a new
     class ImagingException are added in the package javax.media.jai.util.
     An ImagingListener provides the possibility to monitor, process,
     recover and log abnormal situations. An ImagingException holds its
     cause, so that its (root) cause can be retrieved. The class
     javax.media.jai.remote.RemoteImagingException is reparented from
     RuntimeException to ImagingException.

     These changes were made in response to customer comments observed on
     the jai-interest mailing list.

   * Type-safe Image create() Methods

     To each OperationDescriptor in the javax.media.jai.operator package was
     added a type-safe static create method for each supported mode of
     operation. The methods added are named as follows:

              Mode                   Method
      rendered            create()
      renderable          createRenderable()
      Collection          createCollection()
      renderableCollectioncreateRenderableCollection()

     These convenience methods behave as the identically named static
     methods in the JAI class. Please refer to
     javax.media.jai.operator.*Descriptor for more details.

     These changes were made in response to customer comments observed on
     the jai-interest mailing list.

   * Expansion of IndexColor Data

     In the previous versions of JAI, the operators provided by JAI operated
     on the image's pixel data only. No color translation was performed
     prior to the actual computation by the operator, regardless of the type
     of the ColorModel an image had. If it was intended to have an operation
     performed on the color data, the color translation needed to be
     performed explicitly by the user prior to invoking the operation.

     This policy has been changed in JAI 1.1.2 to make handling sources with
     IndexColorModels more straightforward. A new RenderingHint
     JAI.KEY_REPLACE_INDEX_COLOR_MODEL has been provided that allows for
     automatic color translation for colormapped imagery in those situations
     where not doing so would result in unexpected / incorrect results (such
     as geometric operations). Operations that are implemented as subclasses
     of javax.media.jai.AreaOpImage and javax.media.jai.GeometricOpImage set
     this RenderingHint to true, such that these operations are performed
     correctly on the colormapped imagery, not treating the indices into the
     color map as pixel data. The user no longer needs to perform color
     translation before invoking such operations.

     For further details, please refer to Javadoc comments for the
     KEY_REPLACE_INDEX_COLOR_MODEL RenderingHints defined in
     javax.media.jai.JAI, Javadoc comments for the javax.media.jai.OpImage
     constructor, class comments for javax.media.jai.AreaOpImage,
     javax.media.jai.GeometricOpImage, and javax.media.jai.ScaleOpImage etc.

     The affected operations are affine, convolve, dilate, erode,
     filteredsubsample, gradientmagnitude, max, median, min, rotate, scale,
     shear, translate, transpose and warp. For further details, please refer
     to the class comments for the OperationDescriptors for these
     operations.

     One of the common uses of the format operator is to cast the pixel
     values of an image to a given data type. In such a case, the format
     operation adds a RenderingHints object for
     JAI.KEY_REPLACE_INDEX_COLOR_MODEL with the value of Boolean.TRUE, if
     the source image provided has an IndexColorModel. Due to the addition
     of this new RenderingHint, using the "format" operation with source(s)
     that have an IndexColorModel will cause the destination to have an
     expanded non-IndexColorModel ColorModel. This expansion ensures that
     the conversion to a different data type, ColorModel or SampleModel
     happens correctly such that the indices into the color map (for
     IndexColorModel images) are not treated as pixel data.

     These changes were made in response to customer comments observed on
     the jai-interest mailing list.

   * Real-valued DataBuffer Portability

     Some problems interoperating with JavaTM 2 version 1.4 were observed
     due to the classes DataBufferFloat and DataBufferDouble which are found
     in Java2D and in JAI. Internal changes in JAI were made such that
     floating point DataBuffers are handled using the reflection API. Users
     of JavaTM 2 v1.4 should use the floating point DataBuffer classes in
     java.awt.image while users of earlier versions of JavaTM 2 should use
     those in JAI. Both should function equivalently.

     These changes were made in response to customer comments observed on
     the jai-interest mailing list.

   * Tile Dimension Clamping

     To optimize storage requirements for the results of an imaging
     operation, as of JAI 1.1.2, the destination image's tile dimensions are
     by default clamped to it's image dimensions when these are smaller, if
     the tile dimensions were not specified by the user or the operation
     itself.

     This change was made in response to customer comments observed on the
     jai-interest mailing list.

   * Suppression of Colormap Acceleration

     In the previous versions of JAI, to accelerate the ColormapOpImages,
     the transform is performed on the color map if the source and
     destination images are both color-indexed. To suppress the
     acceleration, a new type of rendering hint key,
     KEY_TRANSFORM_ON_COLORMAP, is defined. Operations to which this is
     pertinent are

     AddConst
     AndConst
     DivideIntoConst
     Exp
     Invert
     Log
     Lookup
     MultiplyConst
     Not
     OrConst
     Piecewise
     Rescale
     SubtractFromConst
     Threshold
     XorConst

     These changes were made in response to customer comments observed on
     the jai-interest mailing list.

   * Image Coordinate Mapping

     Forward and inverse coordinate mapping methods mapSourcePoint() and
     mapDestPoint(), respectively were added to RenderedOp, OpImage and its
     subclasses, and Warp and its subclasses. These are intended to allow
     mapping from destination to source images within rendered operation
     chains and from source to destination images depending on the
     invertibility of the transformation.

   * Destination Rectangle Mapping

     The specification of the method OpImage.mapDestRect() was clarified in
     general and specifically with respect to the case wherein the source
     rectangle can be determined but has an empty intersection with the
     actual source image bounds.

   * ColorSpaceJAI and IHSColorSpace

     The non-linear transformation of the sRGB color space conversion was
     implemented and the overall specification of the sRGB-CIEXYZ color
     conversion was clarified. The implementation was changed to match this
     specification change.

   * ColorModelFactory

     A new interface javax.media.jai.ColorModelFactory was added to provide
     more fine-grained control over creating the ColorModel of an OpImage.
     For more information please refer to the ColorModelFactory class
     documentation as well as the links to be found to therein.

   * TileCache and TileCache Key Properties

     Properties named "tile_cache_key" and "tile_cache" were added to the
     list of synthetic properties emitted by a RenderedOp. These properties
     have values which are instances of RenderedImage and TileCache,
     respectively. For more information please refer to the class
     documentation of RenderedOp. The purpose of these properties is to
     provide a reliable mechanism for obtaining the cache used by the
     rendering of a RenderedOp as well as the key used therewith.

   * TileScheduler ThreadGroups

     ThreadGroups were added to allow observation of the scheduler threads.
     There is a single ThreadGroup named

     "SunTileScheduler"+instanceIndex

     where instanceIndex is initially zero and is incremented for each
     instance, and a thread group for standard and prefetch threads which
     are respectively named

     "SunTileScheduler"+instanceIndex+"Standard"
     "SunTileScheduler"+instanceIndex+"Prefetch"

   * ImageAdapter Classes

     Added getWrappedImage() method to each of RenderedImageAdapter,
     RenderableImageAdapter, and WritableRenderedImageAdapter.

   * BorderExtenderConstant

     Added getConstants() method.

   * getImageID()

     A new public method getImageID() was added to PlanarImage and