0001: /*
0002: * $RCSfile: JAI.java,v $
0003: *
0004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
0005: *
0006: * Use is subject to license terms.
0007: *
0008: * $Revision: 1.3 $
0009: * $Date: 2005/11/23 22:53:09 $
0010: * $State: Exp $
0011: */
0012: package javax.media.jai;
0013:
0014: import com.sun.media.jai.util.SunTileCache;
0015: import com.sun.media.jai.util.SunTileScheduler;
0016: import java.awt.Dimension;
0017: import java.awt.RenderingHints;
0018: import java.awt.image.RenderedImage;
0019: import java.awt.image.renderable.ParameterBlock;
0020: import java.awt.image.renderable.RenderableImage;
0021: import java.io.BufferedReader;
0022: import java.io.BufferedWriter;
0023: import java.io.File;
0024: import java.io.IOException;
0025: import java.io.InputStream;
0026: import java.io.InputStreamReader;
0027: import java.io.StringWriter;
0028: import java.lang.reflect.Method;
0029: import java.util.Collection;
0030: import java.util.Iterator;
0031: import java.util.Map;
0032: import java.util.Vector;
0033: import javax.media.jai.remote.NegotiableCapabilitySet;
0034: import javax.media.jai.tilecodec.TileCodecParameterList;
0035: import javax.media.jai.util.ImagingListener;
0036: import com.sun.media.jai.util.ImagingListenerImpl;
0037: import com.sun.media.jai.util.PropertyUtil;
0038:
0039: /**
0040: * A convenience class for instantiating operations.
0041: *
0042: * <p> This class allows programmers to use the syntax:
0043: *
0044: * <pre>
0045: * import javax.media.jai.JAI;
0046: * RenderedOp im = JAI.create("convolve", paramBlock, renderHints);
0047: * </pre>
0048: *
0049: * to create new images or collections by applying operators.
0050: * The <code>create()</code> method returns a <code>RenderedOp</code>
0051: * encapsulating the operation name, parameter block, and rendering
0052: * hints. Additionally, it performs validity checking on the operation
0053: * parameters. Programmers may also refer to
0054: * <code>JAI.createCollection("opname", paramBlock, renderHints)</code>,
0055: * <code>JAI.createRenderable("opname", paramBlock, renderHints)</code>, and
0056: * <code>JAI.createRenderableCollection("opname", paramBlock,
0057: * renderHints)</code>.
0058: *
0059: * <p> If the <code>OperationDescriptor</code> associated with the
0060: * named operation returns <code>true</code> from its
0061: * <code>isImmediate()</code> method, the <code>JAI.createNS()</code>
0062: * method will ask the <code>RenderedOp</code> it constructs to render
0063: * itself immediately. If this rendering is <code>null</code>,
0064: * <code>createNS()</code> will itself return <code>null</code>
0065: * rather than returning an instance of <code>RenderedOp</code> as it
0066: * normally does.
0067: *
0068: * <p> It is possible to create new instances of the<code>JAI</code>class in
0069: * order to control each instance's registry, tile cache, and tile scheduler
0070: * individually. Most users will want to use only the static methods
0071: * of this class, which perform all operations on a default instance,
0072: * which in turn makes use of a default registry. To create a new
0073: * image or collection on a non-default <code>JAI</code> instance,
0074: * the <code>createNS()</code> and <code>createCollectionNS</code>
0075: * (NS being short for "non-static") methods are used.
0076: *
0077: * <p> The <code>JAI</code> class contains convenience methods for a
0078: * number of common argument list formats. These methods perform the
0079: * work of constructing a <code>ParameterBlock</code> automatically.
0080: * The convenience methods are available only in <code>static</code>
0081: * form and make use of the default instance. When operating with a
0082: * specific instance, the general, non-static functions
0083: * <code>createNS()</code> and <code>createCollectionNS()</code>
0084: * should be used. All of the convenience methods operate by calling
0085: * <code>createNS()</code> on the default <code>JAI</code> instance,
0086: * and thus inherit the semantics of that method with regard to immediate
0087: * rendering.
0088: *
0089: * <p> The registry being used by a particular instance may be
0090: * retrieved or set using the <code>getOperationRegistry()</code> and
0091: * <code>setOperationRegistry()</code> methods, respectively. Only
0092: * advanced users should attempt to set the registry. The tile cache and
0093: * tile scheduler being used by a particular instance may likewise be set
0094: * or retrieved using the methods <code>setTileCache()</code>,
0095: * <code>setTileScheduler()</code>, <code>getTileCache()</code>, or
0096: * <code>getTileScheduler()</code>.
0097: *
0098: * <p> Each instance of <code>JAI</code> contains a set of rendering
0099: * hints which will be used for all image or collection creations.
0100: * These hints are merged with any hints supplied to the
0101: * <code>create</code> method; directly supplied hints take precedence
0102: * over the common hints. When a new <code>JAI</code> instance is
0103: * constructed, its hints are initialized to a copy of the hints
0104: * associated with the default instance. When the default instance is
0105: * constructed, hints for the default registry, tile cache, and tile
0106: * scheduler are added to the set of common rendering hints. Similarly,
0107: * invoking <code>setOperationRegistry()</code>, <code>setTileCache()</code>,
0108: * or <code>setTileScheduler()</code> on a <code>JAI</code> instance will
0109: * cause the respective entity to be added to the common rendering hints.
0110: * The hints associated with any instance, including the default instance,
0111: * may be manipulated using the <code>getRenderingHints()</code>,
0112: * <code>setRenderingHints()</code>, and <code>clearRenderingHints()</code>
0113: * methods.
0114: *
0115: * <p> An <code>ImagingListener</code> will reside in each instance of
0116: * <code>JAI</code>. It can be used to listen to (and
0117: * process) the exceptional situations that occur in the
0118: * operations and JAI. A default <code>ImagingListener</code> is
0119: * initially registered which re-throws <code>RuntimeException</code>s
0120: * and prints the error message and
0121: * the stack trace of other types to <code>System.err</code>. To override this
0122: * default behavior an instance of an alternate <code>ImagingListener</code>
0123: * implementation should be registered using
0124: * {@link JAI#setImagingListener}.
0125: *
0126: * <p> An <code>ImagingListener</code> also can be attached to a node as
0127: * a rendering hint, which maps the key <code>KEY_IMAGING_LISTENER</code>.
0128: * The <code>Throwable</code>s which arise in the creation
0129: * and the rendering of this node will be sent to this
0130: * <code>ImagingListener</code> (note that those thrown at the top levels
0131: * such as node creation failure will be handled by the listener registered
0132: * to the <code>JAI</code> instead.) The default value for this hint will
0133: * be the one registered to the instance of <code>JAI</code>.</p>
0134: *
0135: * @see OperationRegistry
0136: * @see RenderingHints
0137: * @see TileScheduler
0138: * @see TileCache
0139: * @see ImagingListener
0140: */
0141: public final class JAI {
0142:
0143: //
0144: // Private hint keys. Each of these keys must be assigned a unique value.
0145: //
0146:
0147: // JAI Core
0148: private static final int HINT_IMAGE_LAYOUT = 101;
0149: private static final int HINT_INTERPOLATION = 102;
0150: private static final int HINT_OPERATION_REGISTRY = 103;
0151: private static final int HINT_OPERATION_BOUND = 104;
0152: private static final int HINT_BORDER_EXTENDER = 105;
0153: private static final int HINT_TILE_CACHE = 106;
0154: private static final int HINT_TILE_SCHEDULER = 107;
0155: private static final int HINT_DEFAULT_COLOR_MODEL_ENABLED = 108;
0156: private static final int HINT_DEFAULT_COLOR_MODEL_METHOD = 109;
0157: private static final int HINT_TILE_CACHE_METRIC = 110;
0158: private static final int HINT_SERIALIZE_DEEP_COPY = 111;
0159: private static final int HINT_TILE_CODEC_FORMAT = 112;
0160: private static final int HINT_TILE_ENCODING_PARAM = 113;
0161: private static final int HINT_TILE_DECODING_PARAM = 114;
0162: private static final int HINT_RETRY_INTERVAL = 115;
0163: private static final int HINT_NUM_RETRIES = 116;
0164: private static final int HINT_NEGOTIATION_PREFERENCES = 117;
0165: private static final int HINT_DEFAULT_RENDERING_SIZE = 118;
0166: private static final int HINT_COLOR_MODEL_FACTORY = 119;
0167: private static final int HINT_REPLACE_INDEX_COLOR_MODEL = 120;
0168: private static final int HINT_TILE_FACTORY = 121;
0169: private static final int HINT_TILE_RECYCLER = 122;
0170: private static final int HINT_CACHED_TILE_RECYCLING_ENABLED = 123;
0171: private static final int HINT_TRANSFORM_ON_COLORMAP = 124;
0172: private static final int HINT_IMAGING_LISTENER = 125;
0173:
0174: //
0175: // Public keys
0176: //
0177:
0178: /**
0179: * Key for {@link ImageLayout} object values.
0180: * The common <code>RenderingHints</code> do not contain a default
0181: * hint corresponding to this key.
0182: */
0183: public static RenderingHints.Key KEY_IMAGE_LAYOUT = new RenderingKey(
0184: HINT_IMAGE_LAYOUT, ImageLayout.class);
0185:
0186: /**
0187: * Key for {@link Interpolation} object values.
0188: * The common <code>RenderingHints</code> do not contain a default
0189: * hint corresponding to this key.
0190: *
0191: * @see MultiResolutionRenderableImage#createScaledRendering
0192: * @see MultiResolutionRenderableImage#createRendering
0193: */
0194: public static RenderingHints.Key KEY_INTERPOLATION = new RenderingKey(
0195: HINT_INTERPOLATION, Interpolation.class);
0196:
0197: /**
0198: * Key for {@link OperationRegistry} object values.
0199: * The common <code>RenderingHints</code> by default contain a hint
0200: * corresponding to this key the value of which is equal to the value
0201: * returned by <code>getOperationRegistry()</code>. The hint is
0202: * automatically set by <code>setOperationRegistry()</code>.
0203: */
0204: public static RenderingHints.Key KEY_OPERATION_REGISTRY = new RenderingKey(
0205: HINT_OPERATION_REGISTRY, OperationRegistry.class);
0206:
0207: /**
0208: * Key for <code>Integer</code> object values representing whether
0209: * the operation is compute, network, or I/O bound. The values
0210: * come from the constants <code>OpImage.OP_COMPUTE_BOUND</code>,
0211: * <code>OpImage.OP_IO_BOUND</code>, and
0212: * <code>OpImage.OP_NETWORK_BOUND</code>.
0213: * The common <code>RenderingHints</code> do not contain a default
0214: * hint corresponding to this key.
0215: */
0216: public static RenderingHints.Key KEY_OPERATION_BOUND = new RenderingKey(
0217: HINT_OPERATION_BOUND, Integer.class);
0218:
0219: /**
0220: * Key for {@link BorderExtender} object values.
0221: * The common <code>RenderingHints</code> do not contain a default
0222: * hint corresponding to this key.
0223: */
0224: public static RenderingHints.Key KEY_BORDER_EXTENDER = new RenderingKey(
0225: HINT_BORDER_EXTENDER, BorderExtender.class);
0226:
0227: /**
0228: * Key for {@link TileCache} object values.
0229: * The common <code>RenderingHints</code> by default contain a hint
0230: * corresponding to this key the value of which is equal to the value
0231: * returned by <code>getTileCache()</code>. The hint is
0232: * automatically set by <code>setTileCache()</code>.
0233: *
0234: * @see #createTileCache(long)
0235: * @see #createTileCache()
0236: *
0237: * @see OpImage#OpImage
0238: */
0239: public static RenderingHints.Key KEY_TILE_CACHE = new RenderingKey(
0240: HINT_TILE_CACHE, TileCache.class);
0241:
0242: /**
0243: * Key for Tile ordering metric.
0244: * The common <code>RenderingHints</code> do not contain a default
0245: * hint corresponding to this key.
0246: *
0247: * @see OpImage#OpImage
0248: * @see TileCache
0249: *
0250: * @since JAI 1.1
0251: */
0252: public static RenderingHints.Key KEY_TILE_CACHE_METRIC = new RenderingKey(
0253: HINT_TILE_CACHE_METRIC, Object.class);
0254:
0255: /**
0256: * Key for {@link TileScheduler} object values.
0257: * The common <code>RenderingHints</code> by default contain a hint
0258: * corresponding to this key the value of which is equal to the value
0259: * returned by <code>getTileScheduler()</code>. The hint is
0260: * automatically set by <code>setTileScheduler()</code>.
0261: *
0262: * @see OpImage#OpImage
0263: *
0264: * @since JAI 1.1
0265: */
0266: public static RenderingHints.Key KEY_TILE_SCHEDULER = new RenderingKey(
0267: HINT_TILE_SCHEDULER, TileScheduler.class);
0268:
0269: /**
0270: * Key for enabling default <code>ColorModel</code> initialization
0271: * when a valid <code>ColorModel</code> may not be derived by
0272: * inheritance. The corresponding object must be a <code>Boolean</code>.
0273: * The common <code>RenderingHints</code> do not contain a default
0274: * hint corresponding to this key which is equivalent to its being
0275: * set to <code>TRUE</code>.
0276: *
0277: * @see OpImage#OpImage
0278: *
0279: * @since JAI 1.1
0280: */
0281: public static RenderingHints.Key KEY_DEFAULT_COLOR_MODEL_ENABLED = new RenderingKey(
0282: HINT_DEFAULT_COLOR_MODEL_ENABLED, Boolean.class);
0283:
0284: /**
0285: * Key for specifying a method to be used as for default
0286: * <code>ColorModel</code> initialization. The corresponding object
0287: * must be a <code>java.lang.reflect.Method</code> which is static
0288: * and accepts a single <code>SampleModel</code> parameter and returns a
0289: * <code>ColorModel</code> or <code>null</code>.
0290: * The common <code>RenderingHints</code> do not contain a default
0291: * hint corresponding to this key which is equivalent to its being
0292: * set to the <code>Method</code> corresponding to
0293: * {@link PlanarImage#createColorModel(SampleModel)}.
0294: *
0295: * @see OpImage#OpImage
0296: *
0297: * @since JAI 1.1
0298: */
0299: public static RenderingHints.Key KEY_DEFAULT_COLOR_MODEL_METHOD = new RenderingKey(
0300: HINT_DEFAULT_COLOR_MODEL_METHOD, Method.class);
0301:
0302: /**
0303: * Key for the dimensions of a <code>RenderedImage</code> created by
0304: * invoking <code>createDefaultRendering()</code> on a node of type
0305: * <code>RenderableOp</code> in a renderable processing chain. The
0306: * type of the associated value is <code>java.awt.Dimension</code>.
0307: *
0308: * @see RenderableOp#createDefaultRendering()
0309: *
0310: * @since JAI 1.1
0311: */
0312: public static final RenderingHints.Key KEY_DEFAULT_RENDERING_SIZE = new RenderingKey(
0313: HINT_DEFAULT_RENDERING_SIZE, Dimension.class);
0314:
0315: /**
0316: * Key for {@link ColorModelFactory} object values.
0317: * The common <code>RenderingHints</code> do not contain a default
0318: * hint corresponding to this key.
0319: *
0320: * @see OpImage#OpImage
0321: *
0322: * @since JAI 1.1.2
0323: */
0324: public static RenderingHints.Key KEY_COLOR_MODEL_FACTORY = new RenderingKey(
0325: HINT_COLOR_MODEL_FACTORY, ColorModelFactory.class);
0326:
0327: /**
0328: * Key for enabling changing of destination image's <code>ColorModel</code>
0329: * to a <code>ComponentColorModel</code>, when the source image has
0330: * an <code>IndexColorModel</code>. The corresponding object must be
0331: * a <code>Boolean</code>. If the source image has an
0332: * <code>IndexColorModel</code>, and the user or the operation itself
0333: * does not set the <code>ColorModel</code> of the destination image,
0334: * the destination image's <code>ColorModel</code> would be copied
0335: * from the source and would therefore also be an
0336: * <code>IndexColorModel</code>. A <code>Boolean.TRUE</code> value
0337: * set for this key causes the destination image's
0338: * <code>ColorModel</code> to be changed to a
0339: * <code>ComponentColorModel</code>. The advantage of changing the
0340: * destination's <code>ColorModel</code> comes in the usage of
0341: * <code>RasterAccessor</code>. When a <code>RasterAccessor</code>
0342: * is created using this source and destination pair, the source
0343: * <code>IndexColorModel</code> will be automatically expanded,
0344: * allowing operations that depend on the pixel value (as opposed
0345: * to the index into the <code>ColorModel</code>) to function correctly.
0346: *
0347: * Note that the JAI provided dithering operations
0348: * (<code>errordiffusion</code>, <code>ordereddither</code>) along with
0349: * the color quantization operator, <code>colorquantizer</code> can be
0350: * used for the inverse operation, i.e. converting from an RGB image
0351: * to an indexed image.
0352: *
0353: * The common <code>RenderingHints</code> do not contain a default
0354: * hint corresponding to this key which is equivalent to its being
0355: * set to <code>FALSE</code>. Certain operators, however, change the
0356: * default for themselves to <code>Boolean.TRUE</code>.
0357: *
0358: * @see javax.media.jai.OpImage#OpImage
0359: * @see javax.media.jai.RasterAccessor
0360: * @see javax.media.jai.operator.ColorQuantizerDescriptor
0361: *
0362: * @since JAI 1.1.2
0363: */
0364: public static RenderingHints.Key KEY_REPLACE_INDEX_COLOR_MODEL = new RenderingKey(
0365: HINT_REPLACE_INDEX_COLOR_MODEL, Boolean.class);
0366:
0367: /**
0368: * Key for <code>TileFactory</code> object values.
0369: * The common <code>RenderingHints</code> contain a
0370: * {@link RecyclingTileFactory}-valued hint corresponding
0371: * to this key. The value is the same as that to which
0372: * {@link #KEY_TILE_RECYCLER} is initially mapped.
0373: *
0374: * @see PlanarImage#PlanarImage(ImageLayout,Vector,Map)
0375: * @see OpImage#OpImage(Vector,ImageLayout,Map,boolean)
0376: *
0377: * @since JAI 1.1.2
0378: */
0379: public static RenderingHints.Key KEY_TILE_FACTORY = new RenderingKey(
0380: HINT_TILE_FACTORY, TileFactory.class);
0381:
0382: /**
0383: * Key for <code>TileRecycler</code> object values.
0384: * The common <code>RenderingHints</code> contain a
0385: * {@link RecyclingTileFactory}-valued hint corresponding
0386: * to this key. The value is the same as that to which
0387: * {@link #KEY_TILE_FACTORY} is initially mapped.
0388: *
0389: * @see OpImage#OpImage(Vector,ImageLayout,Map,boolean)
0390: *
0391: * @since JAI 1.1.2
0392: */
0393: public static RenderingHints.Key KEY_TILE_RECYCLER = new RenderingKey(
0394: HINT_TILE_RECYCLER, TileRecycler.class);
0395:
0396: /**
0397: * Key for <code>Boolean</code> object values which specify
0398: * whether automatic recycling of application-visible tiles
0399: * should occur. The common <code>RenderingHints</code> contain
0400: * a <code>FALSE</code>-valued hint corresponding to this key.
0401: *
0402: * @see OpImage#OpImage(Vector,ImageLayout,Map,boolean)
0403: *
0404: * @since JAI 1.1.2
0405: */
0406: public static RenderingHints.Key KEY_CACHED_TILE_RECYCLING_ENABLED = new RenderingKey(
0407: HINT_CACHED_TILE_RECYCLING_ENABLED, Boolean.class);
0408:
0409: /**
0410: * Key for specifying whether a deep copy of the image data should
0411: * be used when serializing images. The corresponding
0412: * object must be a <code>Boolean</code>.
0413: * The common <code>RenderingHints</code> do not contain a default
0414: * hint corresponding to this key.
0415: *
0416: * @since JAI 1.1
0417: */
0418: public static RenderingHints.Key KEY_SERIALIZE_DEEP_COPY = new RenderingKey(
0419: HINT_SERIALIZE_DEEP_COPY, Boolean.class);
0420:
0421: /**
0422: * Key for specifying the default format to be used for tile
0423: * serialization via <code>TileCodec</code>s. The corresponding
0424: * object must be a <code>String</code>.
0425: * The common <code>RenderingHints</code> do not contain a default
0426: * hint corresponding to this key.
0427: *
0428: * @since JAI 1.1
0429: */
0430: public static RenderingHints.Key KEY_TILE_CODEC_FORMAT = new RenderingKey(
0431: HINT_TILE_CODEC_FORMAT, String.class);
0432:
0433: /**
0434: * Key for specifying the default encoding parameters to be used for
0435: * tile serialization via <code>TileCodec</code>s. The corresponding
0436: * object must be a <code>TileCodecParameterList</code>.
0437: * The common <code>RenderingHints</code> do not contain a default
0438: * hint corresponding to this key.
0439: *
0440: * @since JAI 1.1
0441: */
0442: public static RenderingHints.Key KEY_TILE_ENCODING_PARAM = new RenderingKey(
0443: HINT_TILE_ENCODING_PARAM, TileCodecParameterList.class);
0444:
0445: /**
0446: * Key for specifying the default decoding parameters to be used for
0447: * tile serialization via <code>TileCodec</code>s. The corresponding
0448: * object must be a <code>TileCodecParameterList</code>.
0449: * The common <code>RenderingHints</code> do not contain a default
0450: * hint corresponding to this key.
0451: *
0452: * @since JAI 1.1
0453: */
0454: public static RenderingHints.Key KEY_TILE_DECODING_PARAM = new RenderingKey(
0455: HINT_TILE_DECODING_PARAM, TileCodecParameterList.class);
0456:
0457: /**
0458: * Key for the retry interval value to be used for dealing with
0459: * network errors during remote imaging. The corresponding
0460: * object must be an <code>Integer</code>.
0461: * The common <code>RenderingHints</code> do not contain a default
0462: * hint corresponding to this key.
0463: *
0464: * @see javax.media.jai.remote.RemoteJAI
0465: *
0466: * @since JAI 1.1
0467: */
0468: public static RenderingHints.Key KEY_RETRY_INTERVAL = new RenderingKey(
0469: HINT_RETRY_INTERVAL, Integer.class);
0470:
0471: /**
0472: * Key for the number of retries to be used for dealing with
0473: * network errors during remote imaging. The corresponding
0474: * object must be an <code>Integer</code>.
0475: * The common <code>RenderingHints</code> do not contain a default
0476: * hint corresponding to this key.
0477: *
0478: * @see javax.media.jai.remote.RemoteJAI
0479: *
0480: * @since JAI 1.1
0481: */
0482: public static RenderingHints.Key KEY_NUM_RETRIES = new RenderingKey(
0483: HINT_NUM_RETRIES, Integer.class);
0484:
0485: /**
0486: * Key for the negotiation preferences to be used to negotiate
0487: * capabilities to be used in the remote communication. The
0488: * corresponding object must be a <code>NegotiableCapabilitySet</code>.
0489: * The common <code>RenderingHints</code> do not contain a default
0490: * hint corresponding to this key.
0491: *
0492: * @see javax.media.jai.remote.RemoteJAI
0493: *
0494: * @since JAI 1.1
0495: */
0496: public static RenderingHints.Key KEY_NEGOTIATION_PREFERENCES = new RenderingKey(
0497: HINT_NEGOTIATION_PREFERENCES, NegotiableCapabilitySet.class);
0498:
0499: /**
0500: * Key that indicates whether the {@link ColormapOpImage}s do
0501: * the transform on the color map or on the pixels when the source
0502: * image and destination images are all color-indexed. The
0503: * corresponding object must be a <code>Boolean</code>. The
0504: * common <code>RenderingHints</code> do not contain a default
0505: * hint corresponding to this key. The default behavior is
0506: * equivalent to setting a hint with a value of
0507: * <code>Boolean.TRUE</code>.
0508: *
0509: * @since JAI 1.1.2
0510: */
0511: public static RenderingHints.Key KEY_TRANSFORM_ON_COLORMAP = new RenderingKey(
0512: HINT_TRANSFORM_ON_COLORMAP, Boolean.class);
0513:
0514: /**
0515: * Key for the {@link ImagingListener} registered to a rendering node.
0516: * The default mapping of this key in each JAI instance rethrows
0517: * <code>RuntimeException</code>s and prints the error message and
0518: * stack trace of other exceptions to <code>System.err</code>.
0519: *
0520: * @since JAI 1.1.2
0521: */
0522: public static RenderingHints.Key KEY_IMAGING_LISTENER = new RenderingKey(
0523: HINT_IMAGING_LISTENER, ImagingListener.class);
0524:
0525: /**
0526: * Initial default tile size. Applies to both dimensions.
0527: */
0528: private static final int DEFAULT_TILE_SIZE = 512;
0529:
0530: /**
0531: * Default tile size. Null signifies no default.
0532: */
0533: private static Dimension defaultTileSize = new Dimension(
0534: DEFAULT_TILE_SIZE, DEFAULT_TILE_SIZE);
0535:
0536: /**
0537: * Default <code>RenderableOp</code> rendering size.
0538: * Null signifies no default.
0539: */
0540: private static Dimension defaultRenderingSize = new Dimension(0,
0541: 512);
0542:
0543: private OperationRegistry operationRegistry;
0544: private TileScheduler tileScheduler;
0545: private TileCache tileCache;
0546: private RenderingHints renderingHints;
0547:
0548: /**
0549: * A <code>ImagingListener</code> to listen and/or process the special
0550: * situations in the operations registered in this
0551: * <code>JAI</code>.
0552: *
0553: * @since JAI 1.1.2
0554: */
0555: private ImagingListener imagingListener = ImagingListenerImpl
0556: .getInstance();
0557:
0558: private static JAI defaultInstance = new JAI(OperationRegistry
0559: .initializeRegistry(), new SunTileScheduler(),
0560: new SunTileCache(), new RenderingHints(null));
0561:
0562: /** Returns a new instance of the JAI class. */
0563: private JAI(OperationRegistry operationRegistry,
0564: TileScheduler tileScheduler, TileCache tileCache,
0565: RenderingHints renderingHints) {
0566: this .operationRegistry = operationRegistry;
0567: this .tileScheduler = tileScheduler;
0568: this .tileCache = tileCache;
0569: this .renderingHints = renderingHints;
0570:
0571: this .renderingHints.put(KEY_OPERATION_REGISTRY,
0572: operationRegistry);
0573: this .renderingHints.put(KEY_TILE_CACHE, tileCache);
0574: this .renderingHints.put(KEY_TILE_SCHEDULER, tileScheduler);
0575:
0576: TileFactory rtf = new RecyclingTileFactory();
0577: this .renderingHints.put(KEY_TILE_FACTORY, rtf);
0578: this .renderingHints.put(KEY_TILE_RECYCLER, rtf);
0579: this .renderingHints.put(KEY_CACHED_TILE_RECYCLING_ENABLED,
0580: Boolean.FALSE);
0581: this .renderingHints.put(KEY_IMAGING_LISTENER, imagingListener);
0582: }
0583:
0584: /**
0585: * Returns JAI version information as a <code>String</code>
0586: *
0587: * @since JAI 1.1
0588: */
0589: public static final String getBuildVersion() {
0590: try {
0591: InputStream is = JAI.class
0592: .getResourceAsStream("buildVersion");
0593: if (is == null)
0594: is = PropertyUtil
0595: .getFileFromClasspath("javax/media/jai/buildVersion");
0596:
0597: BufferedReader reader = new BufferedReader(
0598: new InputStreamReader(is));
0599:
0600: StringWriter sw = new StringWriter();
0601: BufferedWriter writer = new BufferedWriter(sw);
0602:
0603: String str;
0604: boolean append = false;
0605:
0606: while ((str = reader.readLine()) != null) {
0607: if (append)
0608: writer.newLine();
0609:
0610: writer.write(str);
0611: append = true;
0612: }
0613:
0614: writer.close();
0615: return sw.getBuffer().toString();
0616:
0617: } catch (Exception e) {
0618: return JaiI18N.getString("JAI13");
0619: }
0620: }
0621:
0622: /**
0623: * Disable use of default tile cache. Tiles are not stored.
0624: *
0625: * @since JAI 1.1
0626: */
0627: public static final void disableDefaultTileCache() {
0628: TileCache tmp = defaultInstance.getTileCache();
0629: if (tmp != null) {
0630: tmp.flush();
0631: }
0632: defaultInstance.renderingHints.remove(KEY_TILE_CACHE);
0633: }
0634:
0635: /**
0636: * Enable use of default tile cache. Tiles are stored.
0637: *
0638: * @since JAI 1.1
0639: */
0640: public static final void enableDefaultTileCache() {
0641: defaultInstance.renderingHints.put(KEY_TILE_CACHE,
0642: defaultInstance.getTileCache());
0643: }
0644:
0645: /**
0646: * Sets the default tile dimensions to the clone of the provided parameter.
0647: * If <code>null</code> there are no default dimensions.
0648: *
0649: * @param tileDimensions The default tile dimensions or <code>null</code>.
0650: *
0651: * @throws <code>IllegalArgumentException</code> if
0652: * <code>tileDimensions</code> is non-<code>null</code> and
0653: * has non-positive width or height.
0654: *
0655: * @since JAI 1.1
0656: */
0657: public static final void setDefaultTileSize(Dimension tileDimensions) {
0658: if (tileDimensions != null
0659: && (tileDimensions.width <= 0 || tileDimensions.height <= 0)) {
0660: throw new IllegalArgumentException();
0661: }
0662:
0663: defaultTileSize = tileDimensions != null ? (Dimension) tileDimensions
0664: .clone()
0665: : null;
0666: }
0667:
0668: /**
0669: * Retrieves the clone of the default tile dimensions.
0670: * If <code>null</code> there are no default dimensions set.
0671: *
0672: * @return The default tile dimensions or <code>null</code>.
0673: *
0674: * @since JAI 1.1
0675: */
0676: public static final Dimension getDefaultTileSize() {
0677: return defaultTileSize != null ? (Dimension) defaultTileSize
0678: .clone() : null;
0679: }
0680:
0681: /**
0682: * Sets the default size of the rendering created by invoking
0683: * <code>createDefaultRendering()</code> on a <code>RenderableOp</code>.
0684: * This default size may be overruled by setting a hint with key
0685: * <code>KEY_DEFAULT_RENDERING_SIZE</code> on the node.
0686: * If <code>null</code> there are no default dimensions.
0687: * Either dimension may be non-positive in which case the other
0688: * dimension and the renderable aspect ratio will be used to compute
0689: * the rendered image size. The intial value of this setting is
0690: * <pre>
0691: * new Dimension(0, 512)
0692: * </pre>
0693: * which produces a default rendering of height 512 and width
0694: * 512*aspect_ratio.
0695: *
0696: * @param defaultSize The default rendering size or <code>null</code>.
0697: *
0698: * @throws <code>IllegalArgumentException</code> if
0699: * <code>defaultSize</code> is non-<code>null</code> and
0700: * both the width and height are non-positive.
0701: *
0702: * @since JAI 1.1
0703: */
0704: public static final void setDefaultRenderingSize(
0705: Dimension defaultSize) {
0706: if (defaultSize != null && defaultSize.width <= 0
0707: && defaultSize.height <= 0) {
0708: throw new IllegalArgumentException(JaiI18N
0709: .getString("JAI8"));
0710: }
0711:
0712: defaultRenderingSize = defaultSize == null ? null
0713: : new Dimension(defaultSize);
0714: }
0715:
0716: /**
0717: * Retrieves a copy of the default rendering size.
0718: * If <code>null</code> there is no default size set.
0719: *
0720: * @return The default rendering size or <code>null</code>.
0721: *
0722: * @since JAI 1.1
0723: */
0724: public static final Dimension getDefaultRenderingSize() {
0725: return defaultRenderingSize == null ? null : new Dimension(
0726: defaultRenderingSize);
0727: }
0728:
0729: /**
0730: * Returns the default<code>JAI</code>instance. This instance is used
0731: * by all of the static methods of this class. It uses the default
0732: * <code>OperationRegistry</code> and, in the Sun Microsystems, Inc.
0733: * implementation, the Sun implementations of <code>TileCache</code> and
0734: * <code>TileScheduler</code>. The <code>RenderingHints</code> will
0735: * contain hints only for these three entities.
0736: *
0737: * <p>Unless otherwise changed through a <code>setOperationRegistry
0738: * </code> the <code>OperationRegistry</code> used by the default
0739: * instance is thread-safe.
0740: */
0741: public static JAI getDefaultInstance() {
0742: return defaultInstance;
0743: }
0744:
0745: /**
0746: * Merge one <code>RenderingHints</code> into another.
0747: *
0748: * @param defaultHints The default <code>RenderingHints</code>.
0749: * @param hints The superseding <code>RenderingHints</code>; hints in
0750: * this mapping take precedence over any in
0751: * <code>defaultHints</code>.
0752: */
0753: static RenderingHints mergeRenderingHints(
0754: RenderingHints defaultHints, RenderingHints hints) {
0755: RenderingHints mergedHints;
0756: if (hints == null || hints.isEmpty()) {
0757: mergedHints = defaultHints;
0758: } else if (defaultHints == null || defaultHints.isEmpty()) {
0759: mergedHints = hints;
0760: } else { // Both parameters are non-null and non-empty.
0761: mergedHints = new RenderingHints((Map) defaultHints);
0762: mergedHints.add(hints);
0763: }
0764:
0765: return mergedHints;
0766: }
0767:
0768: /**
0769: * Returns a new instance of the<code>JAI</code>class. The
0770: * <code>OperationRegistry</code>, <code>TileScheduler</code>, and
0771: * <code>TileCache</code> will initially be references to those of
0772: * the default instance. The rendering hints will be set to a
0773: * clone of those of the default instance.
0774: */
0775: public JAI() {
0776: this .operationRegistry = defaultInstance.operationRegistry;
0777: this .tileScheduler = defaultInstance.tileScheduler;
0778: this .tileCache = defaultInstance.tileCache;
0779: this .renderingHints = (RenderingHints) defaultInstance.renderingHints
0780: .clone();
0781: }
0782:
0783: /**
0784: * Returns the<code>OperationRegistry</code> being used by
0785: * this<code>JAI</code>instance.
0786: *
0787: * <p>Unless otherwise changed through a <code>setOperationRegistry
0788: * </code> the <code>OperationRegistry</code> returned by <code>
0789: * getDefaultInstance().getOperationRegistry()</code> is thread-safe.
0790: */
0791: public OperationRegistry getOperationRegistry() {
0792: return operationRegistry;
0793: }
0794:
0795: /**
0796: * Sets the<code>OperationRegistry</code> to be used by this<code>JAI</code>instance.
0797: *
0798: *@throws IllegalArgumentException if <code>operationRegistry</code> is <code>null</code>.
0799: */
0800: public void setOperationRegistry(OperationRegistry operationRegistry) {
0801: if (operationRegistry == null) {
0802: throw new IllegalArgumentException(JaiI18N
0803: .getString("Generic0"));
0804: }
0805: this .operationRegistry = operationRegistry;
0806: this .renderingHints.put(KEY_OPERATION_REGISTRY,
0807: operationRegistry);
0808: }
0809:
0810: /** Returns the <code>TileScheduler</code> being used by this<code>JAI</code>instance. */
0811: public TileScheduler getTileScheduler() {
0812: return tileScheduler;
0813: }
0814:
0815: /**
0816: * Sets the <code>TileScheduler</code> to be used by this<code>JAI</code>
0817: * instance. The
0818: * <code>tileScheduler</code> parameter will be added to the
0819: * <code>RenderingHints</code> of this <code>JAI</code> instance.
0820: * @throws IllegalArgumentException if <code>tileScheduler</code> is <code>null</code>.
0821: */
0822: public void setTileScheduler(TileScheduler tileScheduler) {
0823: if (tileScheduler == null) {
0824: throw new IllegalArgumentException(JaiI18N
0825: .getString("Generic0"));
0826: }
0827: this .tileScheduler = tileScheduler;
0828: renderingHints.put(KEY_TILE_SCHEDULER, tileScheduler);
0829: }
0830:
0831: /** Returns the <code>TileCache</code> being used by this<code>JAI</code>instance. */
0832: public TileCache getTileCache() {
0833: return tileCache;
0834: }
0835:
0836: /**
0837: * Sets the <code>TileCache</code> to be used by this<code>JAI</code>
0838: * instance. The
0839: * <code>tileCache</code> parameter will be added to the
0840: * <code>RenderingHints</code> of this <code>JAI</code> instance.
0841: *
0842: * @throws IllegalArgumentException if <code>tileCache</code> is <code>null</code>.
0843: */
0844: public void setTileCache(TileCache tileCache) {
0845: if (tileCache == null) {
0846: throw new IllegalArgumentException(JaiI18N
0847: .getString("Generic0"));
0848: }
0849: this .tileCache = tileCache;
0850: renderingHints.put(KEY_TILE_CACHE, tileCache);
0851: }
0852:
0853: /**
0854: * The default implementation constructs a <code>TileCache</code>
0855: * with the given memory capacity in bytes. Users may supply an
0856: * instance of <code>TileCache</code> to an operation by
0857: * supplying a <code>RenderingHint</code> with a
0858: * JAI.KEY_TILE_CACHE key and the desired <code>TileCache</code>
0859: * instance as its value. Note that the absence of a tile cache
0860: * hint will result in the use of the <code>TileCache</code>
0861: * belonging to the default<code>JAI</code>instance. To force an operation
0862: * not to perform caching, a <code>TileCache</code> instance with
0863: * a tile capacity of 0 may be used.
0864: * An exception will be thrown if memCapacity is negative.
0865: * Attempting to set either value larger than the JVM size may result in an
0866: * OutOfMemory exception.
0867: *
0868: * @deprecated as of JAI 1.1 Refer to createTileCache(long memCapacity).
0869: */
0870: public static TileCache createTileCache(int tileCapacity,
0871: long memCapacity) {
0872: if (memCapacity < 0) {
0873: throw new IllegalArgumentException(JaiI18N
0874: .getString("JAI10"));
0875: }
0876: return new SunTileCache(memCapacity);
0877: }
0878:
0879: /**
0880: * Constructs a <code>TileCache</code> with the given memory capacity
0881: * in bytes. Users may supply an instance of <code>TileCache</code>
0882: * to an operation by supplying a <code>RenderingHint</code> with a
0883: * JAI.KEY_TILE_CACHE key and the desired <code>TileCache</code>
0884: * instance as its value. Note that the absence of a tile cache
0885: * hint will result in the use of the <code>TileCache</code>
0886: * belonging to the default<code>JAI</code>instance. To force an operation
0887: * not to perform caching, a <code>TileCache</code> instance with
0888: * a tile capacity of 0 may be used.
0889: * An exception will be thrown if memCapacity is negative.
0890: * Attempting to set either value larger than the JVM size may result in an
0891: * OutOfMemory exception.
0892: *
0893: * @since JAI 1.1
0894: */
0895: public static TileCache createTileCache(long memCapacity) {
0896: if (memCapacity < 0) {
0897: throw new IllegalArgumentException(JaiI18N
0898: .getString("JAI10"));
0899: }
0900: return new SunTileCache(memCapacity);
0901: }
0902:
0903: /**
0904: * Constructs a <code>TileCache</code> with the default memory
0905: * capacity in bytes. Users may supply an instance of
0906: * <code>TileCache</code> to an operation by
0907: * supplying a <code>RenderingHint</code> with a
0908: * JAI.KEY_TILE_CACHE key and the desired <code>TileCache</code>
0909: * instance as its value. Note that the absence of a tile cache
0910: * hint will result in the use of the <code>TileCache</code>
0911: * belonging to the default<code>JAI</code>instance. To force an operation
0912: * not to perform caching, a <code>TileCache</code> instance with
0913: * a tile capacity of 0 may be used.
0914: */
0915: public static TileCache createTileCache() {
0916: return new SunTileCache();
0917: }
0918:
0919: /**
0920: * Constructs a <code>TileScheduler</code> with the default parallelism
0921: * and priorities.
0922: *
0923: * <p> In the Sun Microsystems reference implementation of TileScheduler
0924: * the default parallelism is 2, default priority is
0925: * <code>THREAD.NORM_PRIORITY</code>, default prefetch parallelism is 1,
0926: * and default prefetch priority is <code>THREAD.MIN_PRIORITY</code>.
0927: *
0928: * @since JAI 1.1
0929: */
0930: public static TileScheduler createTileScheduler() {
0931: return new SunTileScheduler();
0932: }
0933:
0934: // Create methods for Rendered mode.
0935:
0936: /**
0937: * Creates a <code>RenderedOp</code> which represents the named
0938: * operation, using the source(s) and/or parameter(s) specified in
0939: * the <code>ParameterBlock</code>, and applying the specified
0940: * hints to the destination. This method should only be used when
0941: * the final result returned is a single
0942: * <code>RenderedImage</code>.
0943: *
0944: * <p> The default<code>JAI</code>instance is used as the source of the
0945: * registry and tile scheduler; that is, this method is equivalent
0946: * to <code>getDefaultInstance().createNS(opName, args, hints)</code>.
0947: * The functionality of this method is the same as its corresponding
0948: * non-static method <code>createNS()</code>.
0949: *
0950: * @param opName The name of the operation.
0951: * @param args The source(s) and/or parameter(s) for the operation.
0952: * @param hints The hints for the operation.
0953: *
0954: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
0955: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
0956: * @throws IllegalArgumentException if no
0957: * <code>OperationDescriptor</code> is registered under the
0958: * specified operation name in the default operation registry.
0959: * @throws IllegalArgumentException if the
0960: * <code>OperationDescriptor</code> registered under the specified
0961: * operation name in the default operation registry does not
0962: * support rendered image mode.
0963: * @throws IllegalArgumentException if the specified operation does
0964: * not produce a
0965: * <code>java.awt.image.RenderedImage</code>.
0966: * @throws IllegalArgumentException if the specified operation is
0967: * unable to handle the sources and parameters specified in
0968: * <code>args</code>.
0969: *
0970: * @return A <code>RenderedOp</code> that represents the named
0971: * operation, or <code>null</code> if the specified operation
0972: * is in the "immediate" mode and the rendering of the
0973: * <code>PlanarImage</code> failed.
0974: */
0975: public static RenderedOp create(String opName, ParameterBlock args,
0976: RenderingHints hints) {
0977: return defaultInstance.createNS(opName, args, hints);
0978: }
0979:
0980: /**
0981: * Creates a <code>RenderedOp</code> which represents the named
0982: * operation, using the source(s) and/or parameter(s) specified in
0983: * the <code>ParameterBlock</code>, and applying the specified
0984: * hints to the destination. This method should only be used when
0985: * the final result returned is a single
0986: * <code>RenderedImage</code>. However, the source(s) supplied
0987: * may be a collection of rendered images or a collection of
0988: * collections that at the very basic level include rendered
0989: * images.
0990: *
0991: * <p> The supplied operation name is validated against the
0992: * operation registry. The source(s) and/or parameter(s) in the
0993: * <code>ParameterBlock</code> are validated against the named
0994: * operation's descriptor, both in their numbers and types.
0995: * Additional restrictions placed on the sources and parameters
0996: * by an individual operation are also validated by calling its
0997: * <code>OperationDescriptor.validateArguments()</code> method.
0998: *
0999: * <p><code>JAI</code>allows a parameter to have a <code>null</code> input
1000: * value, if that particular parameter has a default value specified
1001: * in its operation's descriptor. In this case, the default value
1002: * will replace the <code>null</code> input.
1003: *
1004: * <p><code>JAI</code>also allows unspecified tailing parameters, if these
1005: * parameters have default values specified in the operation's
1006: * descriptor. However, if a parameter, which has a default value,
1007: * is followed by one or more parameters that
1008: * have no default values, this parameter must be specified in the
1009: * <code>ParameterBlock</code>, even if it only has a value of
1010: * code>null</code>.
1011: *
1012: * <p> The rendering hints associated with this instance of
1013: * <code>JAI</code> are overlaid with the hints passed to this
1014: * method. That is, the set of keys will be the union of the
1015: * keys from the instance's hints and the hints parameter.
1016: * If the same key exists in both places, the value from the
1017: * hints parameter will be used.
1018: *
1019: * <p> This version of <code>create</code> is non-static; it may
1020: * be used with a specific instance of the<code>JAI</code>class.
1021: * All of the static <code>create()</code> methods ultimately call this
1022: * method, thus inheriting this method's error handling.
1023: *
1024: * <p> Since this method performs parameter checking, it may not
1025: * be suitable for creating <code>RenderedOp</code> nodes meant to
1026: * be passed to another host using the <code>RemoteImage</code>
1027: * interface. For example, it might be necessary to refer to a
1028: * file that is present only on the remote host. In such cases,
1029: * it is possible to instantiate a <code>RenderedOp</code>
1030: * directly, avoiding all checks.
1031: *
1032: * @param opName The name of the operation.
1033: * @param args The source(s) and/or parameter(s) for the operation.
1034: * @param hints The hints for the operation.
1035: *
1036: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
1037: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
1038: * @throws IllegalArgumentException if no
1039: * <code>OperationDescriptor</code> is registered under the
1040: * specified operation name in the current operation registry.
1041: * @throws IllegalArgumentException if the
1042: * <code>OperationDescriptor</code> registered under the specified
1043: * operation name in the current operation registry does not
1044: * support rendered image mode.
1045: * @throws IllegalArgumentException if the specified operation does
1046: * not produce a
1047: * <code>java.awt.image.RenderedImage</code>.
1048: * @throws IllegalArgumentException if the specified operation is
1049: * unable to handle the sources and parameters specified in
1050: * <code>args</code>.
1051: *
1052: * @return A <code>RenderedOp</code> that represents the named
1053: * operation, or <code>null</code> if the specified operation
1054: * is in the "immediate" mode and the rendering of the
1055: * <code>PlanarImage</code> failed.
1056: */
1057: public RenderedOp createNS(String opName, ParameterBlock args,
1058: RenderingHints hints) {
1059:
1060: if (opName == null) {
1061: throw new IllegalArgumentException(JaiI18N
1062: .getString("JAI14"));
1063: } else if (args == null) {
1064: throw new IllegalArgumentException(JaiI18N
1065: .getString("JAI15"));
1066: }
1067:
1068: String modeName = "rendered";
1069:
1070: // Get the OperationDescriptor registered under the specified name.
1071: OperationDescriptor odesc = (OperationDescriptor) operationRegistry
1072: .getDescriptor(modeName, opName);
1073:
1074: if (odesc == null) {
1075: throw new IllegalArgumentException(opName + ": "
1076: + JaiI18N.getString("JAI0"));
1077: }
1078:
1079: if (!RenderedImage.class.isAssignableFrom(odesc
1080: .getDestClass(modeName))) {
1081: throw new IllegalArgumentException(opName + ": "
1082: + JaiI18N.getString("JAI2"));
1083: }
1084:
1085: // Validate input arguments. The ParameterBlock is cloned here
1086: // because OperationDescriptor.validateArguments() may change
1087: // its content.
1088:
1089: StringBuffer msg = new StringBuffer();
1090: args = (ParameterBlock) args.clone();
1091: if (!odesc.validateArguments(modeName, args, msg)) {
1092: throw new IllegalArgumentException(msg.toString());
1093: }
1094:
1095: // Merge rendering hints. Hints passed in take precedence.
1096: RenderingHints mergedHints = mergeRenderingHints(
1097: renderingHints, hints);
1098:
1099: RenderedOp op = new RenderedOp(operationRegistry, opName, args,
1100: mergedHints);
1101:
1102: // If the operation requests immediate rendering, do so.
1103: if (odesc.isImmediate()) {
1104: PlanarImage im = null;
1105: im = op.getRendering();
1106: if (im == null) {
1107: // Op could not be rendered, return null.
1108: return null;
1109: }
1110: }
1111:
1112: // Return the RenderedOp associated with this operation.
1113: return op;
1114: }
1115:
1116: /**
1117: * Creates a <code>Collection</code> which represents the named
1118: * operation, using the source(s) and/or parameter(s) specified in
1119: * the <code>ParameterBlock</code>, and applying the specified
1120: * hints to the destination. This method should only be used when
1121: * the final result returned is a <code>Collection</code>. (This
1122: * includes <code>javax.media.jai.CollectionOp</code>s.)
1123: *
1124: * <p> The default<code>JAI</code>instance is used as the source of the
1125: * registry and tile scheduler; that is, this method is equivalent
1126: * to <code>getDefaultInstance().createCollectionNS(opName, args,
1127: * hints)</code>. The functionality of this method is the same as
1128: * its corresponding non-static method <code>createCollectionNS()</code>.
1129: *
1130: * @param opName The name of the operation.
1131: * @param args The source(s) and/or parameter(s) for the operation.
1132: * @param hints The hints for the operation.
1133: *
1134: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
1135: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
1136: * @throws IllegalArgumentException if no
1137: * <code>OperationDescriptor</code> is registered under the
1138: * specified operation name in the default operation registry.
1139: * @throws IllegalArgumentException if the
1140: * <code>OperationDescriptor</code> registered under the specified
1141: * operation name in the default operation registry does not
1142: * support rendered image mode.
1143: * @throws IllegalArgumentException if the specified operation does
1144: * not produce a
1145: * <code>java.awt.image.RenderedImage</code> or a
1146: * <code>javax.media.jai.CollectionImage</code>.
1147: * @throws IllegalArgumentException if the specified operation is
1148: * unable to handle the sources and parameters specified in
1149: * <code>args</code>.
1150: *
1151: * @return A <code>Collection</code> that represents the named
1152: * operation, or <code>null</code> if the specified operation
1153: * is in the "immediate" mode and the rendering of the
1154: * <code>PlanarImage</code> failed.
1155: */
1156: public static Collection createCollection(String opName,
1157: ParameterBlock args, RenderingHints hints) {
1158: return defaultInstance.createCollectionNS(opName, args, hints);
1159: }
1160:
1161: /**
1162: * Creates a <code>Collection</code> which represents the named
1163: * operation, using the source(s) and/or parameter(s) specified in
1164: * the <code>ParameterBlock</code>, and applying the specified
1165: * hints to the destination. This method should only be used when
1166: * the final result returned is a <code>Collection</code>. (This
1167: * includes <code>javax.media.jai.CollectionOp</code>s.) The
1168: * source(s) supplied may be a collection of rendered images or a
1169: * collection of collections that at the very basic level include
1170: * rendered images.
1171: * The source(s) supplied are unwrapped to create a single collection
1172: * that contains RenderedOps and collections as many as the size of
1173: * the smallest collection supplied in the sources. The nth collection
1174: * is created using all supplied rendered images and the nth element of
1175: * each of the collections supplied in the source.
1176: *
1177: * <p> The supplied operation name is validated against the
1178: * operation registry. The source(s) and/or parameter(s) in the
1179: * <code>ParameterBlock</code> are val>idated against the named
1180: * operation's descriptor, both in their numbers and types.
1181: * Additional restrictions placed on the sources and parameters
1182: * by an individual operation are also validated by calling its
1183: * <code>OperationDescriptor.validateArguments()</code> method.
1184: *
1185: * <p><code>JAI</code>allows a parameter to have a <code>null</code> input
1186: * value, if that particular parameter has a default value specified
1187: * in its operation's descriptor. In this case, the default value
1188: * will replace the <code>null</code> input.
1189: *
1190: * <p><code>JAI</code>also allows unspecified tailing parameters, if these
1191: * parameters have default values specified in the operation's
1192: * descriptor. However, if a parameter, which
1193: * has a default value, is followed by one or more parameters that
1194: * have no default values, this parameter must be specified in the
1195: * <code>ParameterBlock</code>, even if it only has a value of
1196: * code>null</code>.
1197: *
1198: * <p> The rendering hints associated with this instance of
1199: * <code>JAI</code> are overlaid with the hints passed to this
1200: * method. That is, the set of keys will be the union of the
1201: * keys from the instance's hints and the hints parameter.
1202: * If the same key exists in both places, the value from the
1203: * hints parameter will be used.
1204: *
1205: * <p> This version of <code>createCollection</code> is
1206: * non-static; it may be used with a specific instance of the JAI
1207: * class.
1208: *
1209: * @param opName The name of the operation.
1210: * @param args The source(s) and/or parameter(s) for the operation.
1211: * @param hints The hints for the operation.
1212: *
1213: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
1214: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
1215: * @throws IllegalArgumentException if no
1216: * <code>OperationDescriptor</code> is registered under the
1217: * specified operation name in the current operation registry.
1218: * @throws IllegalArgumentException if the
1219: * <code>OperationDescriptor</code> registered under the specified
1220: * operation name in the current operation registry does not
1221: * support rendered image mode.
1222: * @throws IllegalArgumentException if the specified operation does
1223: * not produce a
1224: * <code>java.awt.image.RenderedImage</code> or a
1225: * <code>javax.media.jai.CollectionImage</code>.
1226: * @throws IllegalArgumentException if the specified operation is
1227: * unable to handle the sources and parameters specified in
1228: * <code>args</code>.
1229: *
1230: * @return A <code>Collection</code> that represents the named
1231: * operation, or <code>null</code> if the specified operation
1232: * is in the "immediate" mode and the rendering of the
1233: * <code>PlanarImage</code> failed.
1234: */
1235: public Collection createCollectionNS(String opName,
1236: ParameterBlock args, RenderingHints hints) {
1237:
1238: if (opName == null) {
1239: throw new IllegalArgumentException(JaiI18N
1240: .getString("JAI14"));
1241: } else if (args == null) {
1242: throw new IllegalArgumentException(JaiI18N
1243: .getString("JAI15"));
1244: }
1245:
1246: String modeName = "collection";
1247:
1248: // Get the OperationDescriptor registered under the specified name.
1249: OperationDescriptor odesc = (OperationDescriptor) operationRegistry
1250: .getDescriptor(modeName, opName);
1251:
1252: if (odesc == null) {
1253: throw new IllegalArgumentException(opName + ": "
1254: + JaiI18N.getString("JAI0"));
1255: }
1256:
1257: Class destClass = odesc.getDestClass(modeName);
1258:
1259: if (!RenderedImage.class.isAssignableFrom(destClass)
1260: && !CollectionImage.class.isAssignableFrom(destClass)) {
1261: throw new IllegalArgumentException(opName + ": "
1262: + JaiI18N.getString("JAI5"));
1263: }
1264:
1265: // Merge rendering hints. Hints passed in take precedence.
1266: RenderingHints mergedHints = mergeRenderingHints(
1267: renderingHints, hints);
1268:
1269: // Validate input arguments. The ParameterBlock is cloned here
1270: // because OperationDescriptor.validateArguments() may change
1271: // its content.
1272:
1273: StringBuffer msg = new StringBuffer();
1274: args = (ParameterBlock) args.clone();
1275: if (odesc.validateArguments(modeName, args, msg)) {
1276: if (RenderedImage.class.isAssignableFrom(destClass)) {
1277: Vector v = new Vector(1);
1278: v.add(new RenderedOp(operationRegistry, opName, args,
1279: mergedHints));
1280: return v;
1281: } else {
1282: CollectionOp cOp = new CollectionOp(operationRegistry,
1283: opName, args, mergedHints);
1284:
1285: // If the operation requests immediate rendering, do so.
1286: if (odesc.isImmediate()) {
1287: Collection coll = null;
1288: coll = cOp.getCollection();
1289: if (coll == null) {
1290: return null;
1291: }
1292: }
1293:
1294: return cOp;
1295: }
1296:
1297: } else {
1298: int numSources = odesc.getNumSources();
1299: Vector sources = args.getSources();
1300:
1301: // Get the iterator of all the sources that are collection.
1302: // Get the iterator for the collection that has the least elements.
1303:
1304: Iterator[] iters = new Iterator[numSources];
1305: Iterator iter = null;
1306: int size = Integer.MAX_VALUE;
1307: for (int i = 0; i < numSources; i++) {
1308: Object s = sources.elementAt(i);
1309: if (s instanceof Collection) {
1310: iters[i] = ((Collection) s).iterator();
1311: if (iter == null || ((Collection) s).size() < size) {
1312: iter = iters[i];
1313: size = ((Collection) s).size();
1314: }
1315: }
1316: }
1317:
1318: if (iter == null) {
1319:
1320: // None of the sources is a collection. The error is
1321: // with the input arguments.
1322:
1323: throw new IllegalArgumentException(msg.toString());
1324: }
1325:
1326: // Some sources are of type collection. Need to unwrap them.
1327: Collection col = null;
1328: for (int i = 0; i < numSources; i++) {
1329: Object s = sources.elementAt(i);
1330: if (s instanceof Collection) {
1331: try {
1332: col = (Collection) s.getClass().newInstance();
1333: break;
1334: } catch (Exception e) {
1335: // Unable to create this collection type, try next.
1336: sendExceptionToListener(JaiI18N
1337: .getString("JAI16")
1338: + s.getClass().getName(), e);
1339: }
1340: }
1341: }
1342: if (col == null) {
1343: col = new Vector();
1344: }
1345:
1346: // Get the source types.
1347: Class[] sourceClasses = odesc.getSourceClasses(modeName);
1348:
1349: while (iter.hasNext()) {
1350: ParameterBlock pb = new ParameterBlock();
1351: pb.setParameters(args.getParameters());
1352:
1353: for (int i = 0; i < numSources; i++) {
1354: // Get the next source.
1355: Object nextSource = null;
1356: if (iters[i] == null) {
1357: nextSource = sources.elementAt(i);
1358: } else {
1359: nextSource = iters[i].next();
1360: }
1361:
1362: // If the source is not of a compatible type and
1363: // is not a Collection then the 'false' value
1364: // returned by validateArguments() above must indicate
1365: // a real error.
1366: if (!sourceClasses[i].isAssignableFrom(nextSource
1367: .getClass())
1368: && !(nextSource instanceof Collection)) {
1369: throw new IllegalArgumentException(msg
1370: .toString());
1371: }
1372: pb.addSource(nextSource);
1373: }
1374:
1375: Collection c = createCollectionNS(opName, pb,
1376: mergedHints);
1377: if (c instanceof Vector
1378: && c.size() == 1
1379: && ((Vector) c).elementAt(0) instanceof RenderedOp) {
1380: col.add(((Vector) c).elementAt(0));
1381: } else {
1382: col.add(c);
1383: }
1384: }
1385:
1386: return col;
1387: }
1388: }
1389:
1390: // Convenience create methods for rendered mode.
1391:
1392: /**
1393: * Creates a <code>RenderedOp</code> with <code>null</code>
1394: * rendering hints.
1395: *
1396: * @param opName The name of the operation.
1397: * @param args The source(s) and/or parameter(s) for the operation.
1398: */
1399: public static RenderedOp create(String opName, ParameterBlock args) {
1400: return create(opName, args, null);
1401: }
1402:
1403: /**
1404: * Creates a <code>RenderedOp</code> that takes 1 <code>Object</code> parameter.
1405: *
1406: * @param opName The name of the operation.
1407: * @param param The <code>Object</code> parameter.
1408: */
1409: public static RenderedOp create(String opName, Object param) {
1410: ParameterBlock args = new ParameterBlock();
1411: args.add(param);
1412: return create(opName, args, null);
1413: }
1414:
1415: /**
1416: * Creates a <code>RenderedOp</code> that takes 2 <code>Object</code> parameters.
1417: *
1418: * @param opName The name of the operation.
1419: * @param param1 The first <code>Object</code> parameter.
1420: * @param param2 The second <code>Object</code> parameter.
1421: */
1422: public static RenderedOp create(String opName, Object param1,
1423: Object param2) {
1424: ParameterBlock args = new ParameterBlock();
1425: args.add(param1);
1426: args.add(param2);
1427: return create(opName, args, null);
1428: }
1429:
1430: /**
1431: * Creates a <code>RenderedOp</code> that takes 1 <code>Object</code> parameter and
1432: * 1 <code>int</code> parameter
1433: *
1434: * @param opName The name of the operation.
1435: * @param param1 The <code>Object</code> parameter.
1436: * @param param2 The <code>int</code> parameter.
1437: * @deprecated as of JAI 1.1. Instead use
1438: * <code>create(String,ParameterBlock)</code>.
1439: */
1440: public static RenderedOp create(String opName, Object param1,
1441: int param2) {
1442: ParameterBlock args = new ParameterBlock();
1443: args.add(param1);
1444: args.add(param2);
1445: return create(opName, args, null);
1446: }
1447:
1448: /**
1449: * Creates a <code>RenderedOp</code> that takes 3 <code>Object</code> parameters.
1450: *
1451: * @param opName The name of the operation.
1452: * @param param1 The first <code>Object</code> parameter.
1453: * @param param2 The second <code>Object</code> parameter.
1454: * @param param3 The third <code>Object</code> parameter.
1455: * @deprecated as of JAI 1.1. Instead use
1456: * <code>create(String,ParameterBlock)</code>.
1457: */
1458: public static RenderedOp create(String opName, Object param1,
1459: Object param2, Object param3) {
1460: ParameterBlock args = new ParameterBlock();
1461: args.add(param1);
1462: args.add(param2);
1463: args.add(param3);
1464: return create(opName, args, null);
1465: }
1466:
1467: /**
1468: * Creates a <code>RenderedOp</code> that takes 2 <code>int</code> parameters
1469: * and one <code>Object</code> parameter
1470: *
1471: * @param opName The name of the operation.
1472: * @param param1 The first <code>int</code> parameter.
1473: * @param param2 The second <code>int</code> parameter.
1474: * @param param3 The <code>Object</code> parameter.
1475: * @deprecated as of JAI 1.1. Instead use
1476: * <code>create(String,ParameterBlock)</code>.
1477: */
1478: public static RenderedOp create(String opName, int param1,
1479: int param2, Object param3) {
1480: ParameterBlock args = new ParameterBlock();
1481: args.add(param1);
1482: args.add(param2);
1483: args.add(param3);
1484: return create(opName, args, null);
1485: }
1486:
1487: /**
1488: * Creates a <code>RenderedOp</code> that takes 4 <code>Object</code> parameters.
1489: *
1490: * @param opName The name of the operation.
1491: * @param param1 The first <code>Object</code> parameter.
1492: * @param param2 The second <code>Object</code> parameter.
1493: * @param param3 The third <code>Object</code> parameter.
1494: * @param param4 The fourth <code>Object</code> parameter.
1495: * @deprecated as of JAI 1.1. Instead use
1496: * <code>create(String,ParameterBlock)</code>.
1497: */
1498: public static RenderedOp create(String opName, Object param1,
1499: Object param2, Object param3, Object param4) {
1500: ParameterBlock args = new ParameterBlock();
1501: args.add(param1);
1502: args.add(param2);
1503: args.add(param3);
1504: args.add(param4);
1505: return create(opName, args, null);
1506: }
1507:
1508: /**
1509: * Creates a <code>RenderedOp</code> that takes 2 <code>Object</code> and 2 <code>int</code> parameters.
1510: *
1511: * @param opName The name of the operation.
1512: * @param param1 The first <code>Object</code> parameter.
1513: * @param param2 The first <code>int</code> parameter.
1514: * @param param3 The second <code>Object</code> parameter.
1515: * @param param4 The second <code>int</code> parameter.
1516: * @deprecated as of JAI 1.1. Instead use
1517: * <code>create(String,ParameterBlock)</code>.
1518: */
1519: public static RenderedOp create(String opName, Object param1,
1520: int param2, Object param3, int param4) {
1521: ParameterBlock args = new ParameterBlock();
1522: args.add(param1);
1523: args.add(param2);
1524: args.add(param3);
1525: args.add(param4);
1526: return create(opName, args, null);
1527: }
1528:
1529: /**
1530: * Creates a <code>RenderedOp</code> that takes 1 <code>RenderedImage</code> source.
1531: *
1532: * @param opName The name of the operation.
1533: * @param src The <code>RenderedImage</code> src parameter.
1534: */
1535: public static RenderedOp create(String opName, RenderedImage src) {
1536: ParameterBlock args = new ParameterBlock();
1537: args.addSource(src);
1538: return create(opName, args, null);
1539: }
1540:
1541: /**
1542: * Creates a <code>RenderedOp</code> that takes 1 Collection source.
1543: *
1544: * @param opName The name of the operation.
1545: * @param srcCol The Collection src parameter.
1546: * @deprecated as of JAI 1.1. Instead use
1547: * <code>create(String,ParameterBlock)</code>.
1548: */
1549: public static RenderedOp create(String opName, Collection srcCol) {
1550: ParameterBlock args = new ParameterBlock();
1551: args.addSource(srcCol);
1552: return create(opName, args, null);
1553: }
1554:
1555: /**
1556: * Creates a <code>RenderedOp</code> that takes 1
1557: * <code>RenderedImage</code> source and
1558: * 1 <code>Object</code> parameter.
1559: *
1560: * @param opName The name of the operation.
1561: * @param src The <code>RenderedImage</code> src parameter.
1562: * @param param The <code>Object</code> parameter.
1563: */
1564: public static RenderedOp create(String opName, RenderedImage src,
1565: Object param) {
1566: ParameterBlock args = new ParameterBlock();
1567: args.addSource(src);
1568: args.add(param);
1569: return create(opName, args, null);
1570: }
1571:
1572: /**
1573: * Creates a <code>RenderedOp</code> that takes 1
1574: * <code>RenderedImage</code> source and
1575: * 1 <code>int</code> parameter.
1576: *
1577: * @param opName The name of the operation.
1578: * @param src The <code>RenderedImage</code> src parameter.
1579: * @param param The <code>int</code> parameter.
1580: * @deprecated as of JAI 1.1. Instead use
1581: * <code>create(String,ParameterBlock)</code>.
1582: */
1583: public static RenderedOp create(String opName, RenderedImage src,
1584: int param) {
1585: ParameterBlock args = new ParameterBlock();
1586: args.addSource(src);
1587: args.add(param);
1588: return create(opName, args, null);
1589: }
1590:
1591: /**
1592: * Creates a <code>RenderedOp</code> that takes 1
1593: * <code>RenderedImage</code> source
1594: * and 2 <code>Object</code> parameters.
1595: *
1596: * @param opName The name of the operation.
1597: * @param src The <code>RenderedImage</code> src parameter.
1598: * @param param1 The first <code>object</code> parameter.
1599: * @param param2 The second <code>Object</code> parameter.
1600: */
1601: public static RenderedOp create(String opName, RenderedImage src,
1602: Object param1, Object param2) {
1603: ParameterBlock args = new ParameterBlock();
1604: args.addSource(src);
1605: args.add(param1);
1606: args.add(param2);
1607: return create(opName, args, null);
1608: }
1609:
1610: /**
1611: * Creates a <code>RenderedOp</code> that takes 1
1612: * <code>RenderedImage</code> source,
1613: * 1 <code>Object</code> and 1 <code>float</code> parameter.
1614: *
1615: * @param opName The name of the operation.
1616: * @param src The <code>RenderedImage</code> src parameter.
1617: * @param param1 The <code>Object</code> parameter.
1618: * @param param2 The <code>float</code> parameter.
1619: * @deprecated as of JAI 1.1. Instead use
1620: * <code>create(String,ParameterBlock)</code>.
1621: */
1622: public static RenderedOp create(String opName, RenderedImage src,
1623: Object param1, float param2) {
1624: ParameterBlock args = new ParameterBlock();
1625: args.addSource(src);
1626: args.add(param1);
1627: args.add(param2);
1628: return create(opName, args, null);
1629: }
1630:
1631: /**
1632: * Creates a <code>RenderedOp</code> that takes 1
1633: * <code>RenderedImage</code> source
1634: * and 3 <code>Object</code> parameters.
1635: *
1636: * @param opName The name of the operation.
1637: * @param src The <code>RenderedImage</code> src parameter.
1638: * @param param1 The first <code>Object</code> parameter.
1639: * @param param2 The second <code>Object</code> parameter.
1640: * @param param3 The third <code>Object</code> parameter.
1641: */
1642: public static RenderedOp create(String opName, RenderedImage src,
1643: Object param1, Object param2, Object param3) {
1644: ParameterBlock args = new ParameterBlock();
1645: args.addSource(src);
1646: args.add(param1);
1647: args.add(param2);
1648: args.add(param3);
1649: return create(opName, args, null);
1650: }
1651:
1652: /**
1653: * Creates a <code>RenderedOp</code> that takes 1
1654: * <code>RenderedImage</code> source,
1655: * 1 <code>Object</code> and 2 <code>int</code> parameters.
1656: *
1657: * @param opName The name of the operation.
1658: * @param src The <code>RenderedImage</code> src parameter.
1659: * @param param1 The <code>Object</code> parameter.
1660: * @param param2 The first <code>int</code> parameter.
1661: * @param param3 The second <code>int</code> parameter.
1662: * @deprecated as of JAI 1.1. Instead use
1663: * <code>create(String,ParameterBlock)</code>.
1664: */
1665: public static RenderedOp create(String opName, RenderedImage src,
1666: Object param1, int param2, int param3) {
1667: ParameterBlock args = new ParameterBlock();
1668: args.addSource(src);
1669: args.add(param1);
1670: args.add(param2);
1671: args.add(param3);
1672: return create(opName, args, null);
1673: }
1674:
1675: /**
1676: * Creates a <code>RenderedOp</code> that takes 1
1677: * <code>RenderedImage</code> source,
1678: * 2 <code>float</code> and 1 <code>Object</code> parameters.
1679: *
1680: * @param opName The name of the operation.
1681: * @param src The <code>RenderedImage</code> src parameter.
1682: * @param param1 The first <code>float</code> parameter.
1683: * @param param2 The second <code>float</code> parameter.
1684: * @param param3 The <code>Object</code> parameter.
1685: * @deprecated as of JAI 1.1. Instead use
1686: * <code>create(String,ParameterBlock)</code>.
1687: */
1688: public static RenderedOp create(String opName, RenderedImage src,
1689: float param1, float param2, Object param3) {
1690: ParameterBlock args = new ParameterBlock();
1691: args.addSource(src);
1692: args.add(param1);
1693: args.add(param2);
1694: args.add(param3);
1695: return create(opName, args, null);
1696: }
1697:
1698: /**
1699: * Creates a <code>RenderedOp</code> that takes 1
1700: * <code>RenderedImage</code> source and
1701: * 4 <code>Object</code> parameters.
1702: *
1703: * @param opName The name of the operation.
1704: * @param src The <code>RenderedImage</code> src parameter.
1705: * @param param1 The first <code>Object</code> parameter.
1706: * @param param2 The second <code>Object</code> parameter.
1707: * @param param3 The third <code>Object</code> parameter.
1708: * @param param4 The fourth <code>Object</code> parameter.
1709: * @deprecated as of JAI 1.1. Instead use
1710: * <code>create(String,ParameterBlock)</code>.
1711: */
1712: public static RenderedOp create(String opName, RenderedImage src,
1713: Object param1, Object param2, Object param3, Object param4) {
1714: ParameterBlock args = new ParameterBlock();
1715: args.addSource(src);
1716: args.add(param1);
1717: args.add(param2);
1718: args.add(param3);
1719: args.add(param4);
1720: return create(opName, args, null);
1721: }
1722:
1723: /**
1724: * Creates a <code>RenderedOp</code> that takes 1
1725: * <code>RenderedImage</code> source and
1726: * 2 <code>Object</code> parameters and 2 <code>int</code> parameters
1727: *
1728: * @param opName The name of the operation.
1729: * @param src The <code>RenderedImage</code> src parameter.
1730: * @param param1 The first <code>Object</code> parameter.
1731: * @param param2 The second <code>Object</code> parameter.
1732: * @param param3 The first <code>int</code> parameter.
1733: * @param param4 The second <code>int</code> parameter.
1734: * @deprecated as of JAI 1.1. Instead use
1735: * <code>create(String,ParameterBlock)</code>.
1736: */
1737: public static RenderedOp create(String opName, RenderedImage src,
1738: Object param1, Object param2, int param3, int param4) {
1739: ParameterBlock args = new ParameterBlock();
1740: args.addSource(src);
1741: args.add(param1);
1742: args.add(param2);
1743: args.add(param3);
1744: args.add(param4);
1745: return create(opName, args, null);
1746: }
1747:
1748: /**
1749: * Creates a <code>RenderedOp</code> that takes 1
1750: * <code>RenderedImage</code> source and
1751: * 4 <code>int</code> parameters.
1752: *
1753: * @param opName The name of the operation.
1754: * @param src The <code>RenderedImage</code> src parameter.
1755: * @param param1 The first <code>int</code> parameter.
1756: * @param param2 The second <code>int</code> parameter.
1757: * @param param3 The third <code>int</code> parameter.
1758: * @param param4 The fourth <code>int</code> parameter.
1759: * @deprecated as of JAI 1.1. Instead use
1760: * <code>create(String,ParameterBlock)</code>.
1761: */
1762: public static RenderedOp create(String opName, RenderedImage src,
1763: int param1, int param2, int param3, int param4) {
1764: ParameterBlock args = new ParameterBlock();
1765: args.addSource(src);
1766: args.add(param1);
1767: args.add(param2);
1768: args.add(param3);
1769: args.add(param4);
1770: return create(opName, args, null);
1771: }
1772:
1773: /**
1774: * Creates a <code>RenderedOp</code> that takes 1
1775: * <code>RenderedImage</code> source,
1776: * 3 <code>float</code> and 1 <code>Object</code> parameters.
1777: *
1778: * @param opName The name of the operation.
1779: * @param src The <code>RenderedImage</code> src parameter.
1780: * @param param1 The first <code>float</code> parameter.
1781: * @param param2 The second <code>float</code> parameter.
1782: * @param param3 The third <code>float</code> parameter.
1783: * @param param4 The <code>Object</code> parameter.
1784: * @deprecated as of JAI 1.1. Instead use
1785: * <code>create(String,ParameterBlock)</code>.
1786: */
1787: public static RenderedOp create(String opName, RenderedImage src,
1788: float param1, float param2, float param3, Object param4) {
1789: ParameterBlock args = new ParameterBlock();
1790: args.addSource(src);
1791: args.add(param1);
1792: args.add(param2);
1793: args.add(param3);
1794: args.add(param4);
1795: return create(opName, args, null);
1796: }
1797:
1798: /**
1799: * Creates a <code>RenderedOp</code> that takes 1
1800: * <code>RenderedImage</code> source and
1801: * 5 <code>Object</code> parameters.
1802: *
1803: * @param opName The name of the operation.
1804: * @param src The <code>RenderedImage</code> src parameter.
1805: * @param param1 The first <code>Object</code> parameter.
1806: * @param param2 The second <code>Object</code> parameter.
1807: * @param param3 The third <code>Object</code> parameter.
1808: * @param param4 The fourth <code>Object</code> parameter.
1809: * @param param5 The fifth <code>Object</code> parameter.
1810: * @deprecated as of JAI 1.1. Instead use
1811: * <code>create(String,ParameterBlock)</code>.
1812: */
1813: public static RenderedOp create(String opName, RenderedImage src,
1814: Object param1, Object param2, Object param3, Object param4,
1815: Object param5) {
1816: ParameterBlock args = new ParameterBlock();
1817: args.addSource(src);
1818: args.add(param1);
1819: args.add(param2);
1820: args.add(param3);
1821: args.add(param4);
1822: args.add(param5);
1823: return create(opName, args, null);
1824: }
1825:
1826: /**
1827: * Creates a <code>RenderedOp</code> that takes 1 <code>RenderedImage</code> source,
1828: * 4 <code>float</code> parameters and one <code>Object</code> parameter.
1829: *
1830: * @param opName The name of the operation.
1831: * @param src The <code>RenderedImage</code> src parameter.
1832: * @param param1 The first <code>float</code> parameter.
1833: * @param param2 The second <code>float</code> parameter.
1834: * @param param3 The third <code>float</code> parameter.
1835: * @param param4 The fourth <code>float</code> parameter.
1836: * @param param5 The <code>Object</code> parameter.
1837: * @deprecated as of JAI 1.1. Instead use
1838: * <code>create(String,ParameterBlock)</code>.
1839: */
1840: public static RenderedOp create(String opName, RenderedImage src,
1841: float param1, float param2, float param3, float param4,
1842: Object param5) {
1843: ParameterBlock args = new ParameterBlock();
1844: args.addSource(src);
1845: args.add(param1);
1846: args.add(param2);
1847: args.add(param3);
1848: args.add(param4);
1849: args.add(param5);
1850: return create(opName, args, null);
1851: }
1852:
1853: /**
1854: * Creates a <code>RenderedOp</code> that takes 1
1855: * <code>RenderedImage</code> source,
1856: * 3 <code>float</code> parameters, 1 <code>int</code> parameter and 1 <code>Object</code> parameter.
1857: *
1858: * @param opName The name of the operation.
1859: * @param src The <code>RenderedImage</code> src parameter.
1860: * @param param1 The first <code>float</code> parameter.
1861: * @param param2 The <code>int</code> parameter.
1862: * @param param3 The second <code>float</code> parameter.
1863: * @param param4 The third <code>float</code> parameter.
1864: * @param param5 The <code>Object</code> parameter.
1865: * @deprecated as of JAI 1.1. Instead use
1866: * <code>create(String,ParameterBlock)</code>.
1867: */
1868: public static RenderedOp create(String opName, RenderedImage src,
1869: float param1, int param2, float param3, float param4,
1870: Object param5) {
1871: ParameterBlock args = new ParameterBlock();
1872: args.addSource(src);
1873: args.add(param1);
1874: args.add(param2);
1875: args.add(param3);
1876: args.add(param4);
1877: args.add(param5);
1878: return create(opName, args, null);
1879: }
1880:
1881: /**
1882: * Creates a <code>RenderedOp</code> that takes 1
1883: * <code>RenderedImage</code> source and
1884: * 6 <code>Object</code> parameters.
1885: *
1886: * @param opName The name of the operation.
1887: * @param src The <code>RenderedImage</code> src parameter.
1888: * @param param1 The first <code>Object</code> parameter.
1889: * @param param2 The second <code>Object</code> parameter.
1890: * @param param3 The third <code>Object</code> parameter.
1891: * @param param4 The fourth <code>Object</code> parameter.
1892: * @param param5 The fifth <code>Object</code> parameter.
1893: * @param param6 The sixth <code>Object</code> parameter.
1894: * @deprecated as of JAI 1.1. Instead use
1895: * <code>create(String,ParameterBlock)</code>.
1896: */
1897: public static RenderedOp create(String opName, RenderedImage src,
1898: Object param1, Object param2, Object param3, Object param4,
1899: Object param5, Object param6) {
1900: ParameterBlock args = new ParameterBlock();
1901: args.addSource(src);
1902: args.add(param1);
1903: args.add(param2);
1904: args.add(param3);
1905: args.add(param4);
1906: args.add(param5);
1907: args.add(param6);
1908: return create(opName, args, null);
1909: }
1910:
1911: /**
1912: * Creates a <code>RenderedOp</code> that takes 1 <code>RenderedImage</code> source,
1913: * 5 <code>int</code> parameters and 1 <code>Object</code> parameter.
1914: *
1915: * @param opName The name of the operation.
1916: * @param src The <code>RenderedImage</code> src parameter.
1917: * @param param1 The first <code>int</code> parameter.
1918: * @param param2 The second <code>int</code> parameter.
1919: * @param param3 The third <code>int</code> parameter.
1920: * @param param4 The fourth <code>int</code> parameter.
1921: * @param param5 The fifth <code>int</code> parameter.
1922: * @param param6 The <code>Object</code> parameter.
1923: * @deprecated as of JAI 1.1. Instead use
1924: * <code>create(String,ParameterBlock)</code>.
1925: */
1926: public static RenderedOp create(String opName, RenderedImage src,
1927: int param1, int param2, int param3, int param4, int param5,
1928: Object param6) {
1929: ParameterBlock args = new ParameterBlock();
1930: args.addSource(src);
1931: args.add(param1);
1932: args.add(param2);
1933: args.add(param3);
1934: args.add(param4);
1935: args.add(param5);
1936: args.add(param6);
1937: return create(opName, args, null);
1938: }
1939:
1940: /**
1941: * Creates a <code>RenderedOp</code> that takes 2
1942: * <code>RenderedImage</code> sources.
1943: *
1944: * @param opName The name of the operation.
1945: * @param src1 The first <code>RenderedImage</code> src.
1946: * @param src2 The second <code>RenderedImage</code> src.
1947: */
1948: public static RenderedOp create(String opName, RenderedImage src1,
1949: RenderedImage src2) {
1950: ParameterBlock args = new ParameterBlock();
1951: args.addSource(src1);
1952: args.addSource(src2);
1953: return create(opName, args, null);
1954: }
1955:
1956: /**
1957: * Creates a <code>RenderedOp</code> that takes 2
1958: * <code>RenderedImage</code> sources and
1959: * 4 <code>Object</code> parameters.
1960: *
1961: * @param opName The name of the operation.
1962: * @param src1 The first <code>RenderedImage</code> src.
1963: * @param src2 The second <code>RenderedImage</code> src.
1964: * @param param1 The first <code>Object</code> parameter.
1965: * @param param2 The second <code>Object</code> parameter.
1966: * @param param3 The third <code>Object</code> parameter.
1967: * @param param4 The fourth <code>Object</code> parameter.
1968: * @deprecated as of JAI 1.1. Instead use
1969: * <code>create(String,ParameterBlock)</code>.
1970: */
1971: public static RenderedOp create(String opName, RenderedImage src1,
1972: RenderedImage src2, Object param1, Object param2,
1973: Object param3, Object param4) {
1974: ParameterBlock args = new ParameterBlock();
1975: args.addSource(src1);
1976: args.addSource(src2);
1977: args.add(param1);
1978: args.add(param2);
1979: args.add(param3);
1980: args.add(param4);
1981: return create(opName, args, null);
1982: }
1983:
1984: /**
1985: * Creates a <code>Collection</code> with <code>null</code>
1986: * rendering hints.
1987: *
1988: * @param opName The name of the operation.
1989: * @param args The source(s) and/or parameter(s) for the operation.
1990: */
1991: public static Collection createCollection(String opName,
1992: ParameterBlock args) {
1993: return createCollection(opName, args, null);
1994: }
1995:
1996: // Create methods for Renderable mode.
1997:
1998: /**
1999: * Creates a <code>RenderableOp</code> that represents the named
2000: * operation, using the source(s) and/or parameter(s) specified
2001: * in the <code>ParameterBlock</code>. This method should only
2002: * be used when the final result returned is a single
2003: * <code>RenderdableImage</code>.
2004: *
2005: * <p> The default<code>JAI</code>instance is used as the source of the
2006: * registry and tile scheduler; that is, this method is equivalent to
2007: * <code>getDefaultInstance().createRenderableNS(opName, args, hints)</code>.
2008: * The functionality of this method is the same as its corresponding
2009: * non-static method <code>createRenderableNS()</code>.
2010: *
2011: * @param opName The name of the operation.
2012: * @param args The source(s) and/or parameter(s) for the operation.
2013: * @param hints The hints for the operation.
2014: *
2015: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
2016: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
2017: * @throws IllegalArgumentException if no
2018: * <code>OperationDescriptor</code> is registered under the
2019: * specified operation name in the default operation registry.
2020: * @throws IllegalArgumentException if the
2021: * <code>OperationDescriptor</code> registered under the specified
2022: * operation name in the default operation registry does not
2023: * support renderable image mode.
2024: * @throws IllegalArgumentException if the specified operation does
2025: * not produce a
2026: * <code>java.awt.image.renderable.RenderableImage</code>.
2027: * @throws IllegalArgumentException if the specified operation is
2028: * unable to handle the sources and parameters specified in
2029: * <code>args</code>.
2030: *
2031: * @return A <code>RenderableOp</code> that represents the named
2032: * operation.
2033: *
2034: * @since JAI 1.1
2035: */
2036: public static RenderableOp createRenderable(String opName,
2037: ParameterBlock args, RenderingHints hints) {
2038: return defaultInstance.createRenderableNS(opName, args, hints);
2039: }
2040:
2041: /**
2042: * Creates a <code>RenderableOp</code> that represents the named
2043: * operation, using the source(s) and/or parameter(s) specified
2044: * in the <code>ParameterBlock</code>. This method should only
2045: * be used when the final result returned is a single
2046: * <code>RenderdableImage</code>.
2047: *
2048: * <p> The default<code>JAI</code>instance is used as the source of the
2049: * registry and tile scheduler; that is, this method is equivalent to
2050: * <code>getDefaultInstance().createRenderableNS(opName, args, null)</code>.
2051: * The functionality of this method is the same as its corresponding
2052: * non-static method <code>createRenderableNS()</code>.
2053: *
2054: * @param opName The name of the operation.
2055: * @param args The source(s) and/or parameter(s) for the operation.
2056: *
2057: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
2058: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
2059: * @throws IllegalArgumentException if no
2060: * <code>OperationDescriptor</code> is registered under the
2061: * specified operation name in the default operation registry.
2062: * @throws IllegalArgumentException if the
2063: * <code>OperationDescriptor</code> registered under the specified
2064: * operation name in the default operation registry does not
2065: * support renderable image mode.
2066: * @throws IllegalArgumentException if the specified operation does
2067: * not produce a
2068: * <code>java.awt.image.renderable.RenderableImage</code>.
2069: * @throws IllegalArgumentException if the specified operation is
2070: * unable to handle the sources and parameters specified in
2071: * <code>args</code>.
2072: *
2073: * @return A <code>RenderableOp</code> that represents the named
2074: * operation.
2075: */
2076: public static RenderableOp createRenderable(String opName,
2077: ParameterBlock args) {
2078: return defaultInstance.createRenderableNS(opName, args, null);
2079: }
2080:
2081: /**
2082: * Creates a <code>RenderableOp</code> that represents the named
2083: * operation, using the source(s) and/or parameter(s) specified
2084: * in the <code>ParameterBlock</code>. This method should only
2085: * be used when the final result returned is a single
2086: * <code>RenderableImage</code>. However, the source(s) supplied
2087: * may be a collection of renderable images or a collection of
2088: * collections that at the very basic level include renderable
2089: * images.
2090: *
2091: * <p> The supplied operation name is validated against the
2092: * operation registry. The source(s) and/or parameter(s) in the
2093: * <code>ParameterBlock</code> are validated against the named
2094: * operation's descriptor, both in their numbers and types.
2095: * Additional restrictions placed on the sources and parameters
2096: * by an individual operation are also validated by calling its
2097: * <code>OperationDescriptor.validateRenderableArguments()</code>
2098: * method.
2099: *
2100: * <p><code>JAI</code>allows a parameter to have a <code>null</code> input
2101: * value, if that particular parameter has a default value specified
2102: * in its operation's descriptor. In this case, the default value
2103: * will replace the <code>null</code> input.
2104: *
2105: * <p><code>JAI</code>also allows unspecified tailing parameters, if these
2106: * parameters have default values specified in the operation's
2107: * descriptor. However, if a parameter, which
2108: * has a default value, is followed by one or more parameters that
2109: * have no default values, this parameter must be specified in the
2110: * <code>ParameterBlock</code>, even if it only has a value of
2111: * code>null</code>.
2112: *
2113: * <p> The rendering hints associated with this instance of
2114: * <code>JAI</code> are overlaid with the hints passed to this
2115: * method. That is, the set of keys will be the union of the
2116: * keys from the instance's hints and the hints parameter.
2117: * If the same key exists in both places, the value from the
2118: * hints parameter will be used.
2119: *
2120: * <p> This version of the "createRenderable" is non-static; it
2121: * may be used with a specific instance of the<code>JAI</code>class.
2122: *
2123: * @param opName The name of the operation.
2124: * @param args The source(s) and/or parameter(s) for the operation.
2125: * @param hints The hints for the operation.
2126: *
2127: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
2128: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
2129: * @throws IllegalArgumentException if no
2130: * <code>OperationDescriptor</code> is registered under the
2131: * specified operation name in the current operation registry.
2132: * @throws IllegalArgumentException if the
2133: * <code>OperationDescriptor</code> registered under the specified
2134: * operation name in the current operation registry does not
2135: * support renderable image mode.
2136: * @throws IllegalArgumentException if the specified operation does
2137: * not produce a
2138: * <code>java.awt.image.renderable.RenderableImage</code>.
2139: * @throws IllegalArgumentException if the specified operation is
2140: * unable to handle the sources and parameters specified in
2141: * <code>args</code>.
2142: *
2143: * @return A <code>RenderableOp</code> that represents the named
2144: * operation.
2145: *
2146: * @since JAI 1.1
2147: */
2148: public RenderableOp createRenderableNS(String opName,
2149: ParameterBlock args, RenderingHints hints) {
2150:
2151: if (opName == null) {
2152: throw new IllegalArgumentException(JaiI18N
2153: .getString("JAI14"));
2154: } else if (args == null) {
2155: throw new IllegalArgumentException(JaiI18N
2156: .getString("JAI15"));
2157: }
2158:
2159: String modeName = "renderable";
2160:
2161: // Get the OperationDescriptor registered under the specified name.
2162: OperationDescriptor odesc = (OperationDescriptor) operationRegistry
2163: .getDescriptor(modeName, opName);
2164:
2165: if (odesc == null) {
2166: throw new IllegalArgumentException(opName + ": "
2167: + JaiI18N.getString("JAI0"));
2168: }
2169:
2170: if (!RenderableImage.class.isAssignableFrom(odesc
2171: .getDestClass(modeName))) {
2172: throw new IllegalArgumentException(opName + ": "
2173: + JaiI18N.getString("JAI4"));
2174: }
2175:
2176: // Validate input arguments. The ParameterBlock is cloned here
2177: // because OperationDescriptor.validateRenderableArguments()
2178: // may change its content.
2179:
2180: StringBuffer msg = new StringBuffer();
2181: args = (ParameterBlock) args.clone();
2182: if (!odesc.validateArguments(modeName, args, msg)) {
2183: throw new IllegalArgumentException(msg.toString());
2184: }
2185:
2186: // Create a RenderableOp.
2187: RenderableOp op = new RenderableOp(operationRegistry, opName,
2188: args, mergeRenderingHints(renderingHints, hints));
2189:
2190: // Return the RenderableOp.
2191: return op;
2192: }
2193:
2194: /**
2195: * Creates a <code>RenderableOp</code> that represents the named
2196: * operation, using the source(s) and/or parameter(s) specified
2197: * in the <code>ParameterBlock</code>. This method should only
2198: * be used when the final result returned is a single
2199: * <code>RenderableImage</code>. However, the source(s) supplied
2200: * may be a collection of renderable images or a collection of
2201: * collections that at the very basic level include renderable
2202: * images.
2203: *
2204: * <p> The supplied operation name is validated against the
2205: * operation registry. The source(s) and/or parameter(s) in the
2206: * <code>ParameterBlock</code> are validated against the named
2207: * operation's descriptor, both in their numbers and types.
2208: * Additional restrictions placed on the sources and parameters
2209: * by an individual operation are also validated by calling its
2210: * <code>OperationDescriptor.validateRenderableArguments()</code>
2211: * method.
2212: *
2213: * <p><code>JAI</code>allows a parameter to have a <code>null</code> input
2214: * value, if that particular parameter has a default value specified
2215: * in its operation's descriptor. In this case, the default value
2216: * will replace the <code>null</code> input.
2217: *
2218: * <p><code>JAI</code>also allows unspecified tailing parameters, if these
2219: * parameters have default values specified in the operation's
2220: * descriptor. However, if a parameter, which
2221: * has a default value, is followed by one or more parameters that
2222: * have no default values, this parameter must be specified in the
2223: * <code>ParameterBlock</code>, even if it only has a value of
2224: * code>null</code>.
2225: *
2226: * <p> The rendering hints associated with this instance of
2227: * <code>JAI</code> are overlaid with the hints passed to this
2228: * method. That is, the set of keys will be the union of the
2229: * keys from the instance's hints and the hints parameter.
2230: * If the same key exists in both places, the value from the
2231: * hints parameter will be used.
2232: *
2233: * <p> This version of the "createRenderable" is non-static; it
2234: * may be used with a specific instance of the<code>JAI</code>class.
2235: *
2236: * @param opName The name of the operation.
2237: * @param args The source(s) and/or parameter(s) for the operation.
2238: *
2239: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
2240: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
2241: * @throws IllegalArgumentException if no
2242: * <code>OperationDescriptor</code> is registered under the
2243: * specified operation name in the current operation registry.
2244: * @throws IllegalArgumentException if the
2245: * <code>OperationDescriptor</code> registered under the specified
2246: * operation name in the current operation registry does not
2247: * support renderable image mode.
2248: * @throws IllegalArgumentException if the specified operation does
2249: * not produce a
2250: * <code>java.awt.image.renderable.RenderableImage</code>.
2251: * @throws IllegalArgumentException if the specified operation is
2252: * unable to handle the sources and parameters specified in
2253: * <code>args</code>.
2254: *
2255: * @return A <code>RenderableOp</code> that represents the named
2256: * operation.
2257: *
2258: * @deprecated as of JAI 1.1 in favor of
2259: * <code>createRenderableNS(String,ParameterBlock,RenderingHints)</code>.
2260: * @see JAI#createRenderableNS(String,ParameterBlock,RenderingHints)
2261: */
2262: public RenderableOp createRenderableNS(String opName,
2263: ParameterBlock args) {
2264: return createRenderableNS(opName, args, null);
2265: }
2266:
2267: /**
2268: * Creates a <code>Collection</code> which represents the named
2269: * operation, using the source(s) and/or parameter(s) specified in
2270: * the <code>ParameterBlock</code>. This method should only be used
2271: * when the final result returned is a <code>Collection</code>.
2272: * (This includes <code>javax.media.jai.CollectionOp</code>s.)
2273: *
2274: * <p> The default<code>JAI</code>instance is used as the source of the
2275: * registry and tile scheduler; that is, this method is equivalent
2276: * to <code>getDefaultInstance().createRenderableCollectionNS(opName,
2277: * args,hints)</code>. The functionality of this method is the same as
2278: * its corresponding non-static method
2279: * <code>createRenderableCollectionNS()</code>.
2280: *
2281: * @param opName The name of the operation.
2282: * @param args The source(s) and/or parameter(s) for the operation.
2283: * @param hints The hints for the operation.
2284: *
2285: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
2286: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
2287: * @throws IllegalArgumentException if no
2288: * <code>OperationDescriptor</code> is registered under the
2289: * specified operation name in the default operation registry.
2290: * @throws IllegalArgumentException if the
2291: * <code>OperationDescriptor</code> registered under the specified
2292: * operation name in the default operation registry does not
2293: * support renderable image mode.
2294: * @throws IllegalArgumentException if the specified operation does
2295: * not produce a
2296: * <code>java.awt.image.renderable.RenderableImage</code> or a
2297: * <code>javax.media.jai.CollectionImage</code>.
2298: * @throws IllegalArgumentException if the specified operation is
2299: * unable to handle the sources and parameters specified in
2300: * <code>args</code>.
2301: *
2302: * @return A <code>Collection</code> that represents the named
2303: * operation.
2304: *
2305: * @since JAI 1.1
2306: */
2307: public static Collection createRenderableCollection(String opName,
2308: ParameterBlock args, RenderingHints hints) {
2309: return defaultInstance.createRenderableCollectionNS(opName,
2310: args, hints);
2311: }
2312:
2313: /**
2314: * Creates a <code>Collection</code> which represents the named
2315: * operation, using the source(s) and/or parameter(s) specified in
2316: * the <code>ParameterBlock</code>. This method should only be used
2317: * when the final result returned is a <code>Collection</code>.
2318: * (This includes <code>javax.media.jai.CollectionOp</code>s.)
2319: *
2320: * <p> The default<code>JAI</code>instance is used as the source of the
2321: * registry and tile scheduler; that is, this method is equivalent
2322: * to <code>getDefaultInstance().createRenderableCollectionNS(opName,
2323: * args,null)</code>. The functionality of this method is the same as
2324: * its corresponding non-static method
2325: * <code>createRenderableCollectionNS()</code>.
2326: *
2327: * @param opName The name of the operation.
2328: * @param args The source(s) and/or parameter(s) for the operation.
2329: *
2330: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
2331: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
2332: * @throws IllegalArgumentException if no
2333: * <code>OperationDescriptor</code> is registered under the
2334: * specified operation name in the default operation registry.
2335: * @throws IllegalArgumentException if the
2336: * <code>OperationDescriptor</code> registered under the specified
2337: * operation name in the default operation registry does not
2338: * support renderable image mode.
2339: * @throws IllegalArgumentException if the specified operation does
2340: * not produce a
2341: * <code>java.awt.image.renderable.RenderableImage</code> or a
2342: * <code>javax.media.jai.CollectionImage</code>.
2343: * @throws IllegalArgumentException if the specified operation is
2344: * unable to handle the sources and parameters specified in
2345: * <code>args</code>.
2346: *
2347: * @return A <code>Collection</code> that represents the named
2348: * operation.
2349: */
2350: public static Collection createRenderableCollection(String opName,
2351: ParameterBlock args) {
2352: return defaultInstance.createRenderableCollectionNS(opName,
2353: args, null);
2354: }
2355:
2356: /**
2357: * Creates a <code>Collection</code> which represents the named
2358: * operation, using the source(s) and/or parameter(s) specified in
2359: * the <code>ParameterBlock</code>. This method should only be used
2360: * when the final result returned is a <code>Collection</code>.
2361: * (This includes <code>javax.media.jai.CollectionOp</code>s.) The
2362: * source(s) supplied may be a collection of renderable images or a
2363: * collection of collections that at the very basic level include
2364: * renderable images.
2365: * The source(s) supplied are unwrapped to create a single collection
2366: * that contains RenderableOps and collections as many as the size of
2367: * the smallest collection supplied in the sources. The nth collection
2368: * is created using all supplied renderable images and the nth element of
2369: * each of the collections supplied in the source.
2370: *
2371: * <p> This method should be used to create a <code>Collection</code>
2372: * in the renderable image mode.
2373: *
2374: * <p> The supplied operation name is validated against the
2375: * operation registry. The source(s) and/or parameter(s) in the
2376: * <code>ParameterBlock</code> are validated against the named
2377: * operation's descriptor, both in their numbers and types.
2378: * Additional restrictions placed on the sources and parameters
2379: * by an individual operation are also validated by calling its
2380: * <code>OperationDescriptor.validateRenderableArguments()</code>
2381: * method.
2382: *
2383: * <p><code>JAI</code>allows a parameter to have a <code>null</code> input
2384: * value, if that particular parameter has a default value specified
2385: * in its operation's descriptor. In this case, the default value
2386: * will replace the <code>null</code> input.
2387: *
2388: * <p><code>JAI</code>also allows unspecified tailing parameters, if these
2389: * parameters have default values specified in the operation's
2390: * descriptor. However, if a parameter, which
2391: * has a default value, is followed by one or more parameters that
2392: * have no default values, this parameter must be specified in the
2393: * <code>ParameterBlock</code>, even if it only has a value of
2394: * code>null</code>.
2395: *
2396: * <p> This version of <code>createRenderableCollection</code> is
2397: * non-static; it may be used with a specific instance of the JAI
2398: * class.
2399: *
2400: * @param opName The name of the operation.
2401: * @param args The source(s) and/or parameter(s) for the operation.
2402: *
2403: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
2404: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
2405: * @throws IllegalArgumentException if no
2406: * <code>OperationDescriptor</code> is registered under the
2407: * specified operation name in the current operation registry.
2408: * @throws IllegalArgumentException if the
2409: * <code>OperationDescriptor</code> registered under the specified
2410: * operation name in the current operation registry does not
2411: * support renderable image mode.
2412: * @throws IllegalArgumentException if the specified operation does
2413: * not produce a
2414: * <code>java.awt.image.renderable.RenderableImage</code> or a
2415: * <code>javax.media.jai.CollectionImage</code>.
2416: * @throws IllegalArgumentException if the specified operation is
2417: * unable to handle the sources and parameters specified in
2418: * <code>args</code>.
2419: *
2420: * @return A <code>Collection</code> that represents the named
2421: * operation.
2422: *
2423: * @deprecated as of JAI 1.1 in favor of
2424: * <code>createRenderableCollectionNS(String,ParameterBlock,RenderingHints)</code>.
2425: * @see JAI#createRenderableCollectionNS(String,ParameterBlock,RenderingHints)
2426: */
2427: public Collection createRenderableCollectionNS(String opName,
2428: ParameterBlock args) {
2429: return createRenderableCollectionNS(opName, args, null);
2430: }
2431:
2432: /**
2433: * Creates a <code>Collection</code> which represents the named
2434: * operation, using the source(s) and/or parameter(s) specified in
2435: * the <code>ParameterBlock</code>. This method should only be used
2436: * when the final result returned is a <code>Collection</code>.
2437: * (This includes <code>javax.media.jai.CollectionOp</code>s.) The
2438: * source(s) supplied may be a collection of renderable images or a
2439: * collection of collections that at the very basic level include
2440: * renderable images.
2441: * The source(s) supplied are unwrapped to create a single collection
2442: * that contains RenderableOps and collections as many as the size of
2443: * the smallest collection supplied in the sources. The nth collection
2444: * is created using all supplied renderable images and the nth element of
2445: * each of the collections supplied in the source.
2446: *
2447: * <p> This method should be used to create a <code>Collection</code>
2448: * in the renderable image mode.
2449: *
2450: * <p> The supplied operation name is validated against the
2451: * operation registry. The source(s) and/or parameter(s) in the
2452: * <code>ParameterBlock</code> are validated against the named
2453: * operation's descriptor, both in their numbers and types.
2454: * Additional restrictions placed on the sources and parameters
2455: * by an individual operation are also validated by calling its
2456: * <code>OperationDescriptor.validateRenderableArguments()</code>
2457: * method.
2458: *
2459: * <p><code>JAI</code>allows a parameter to have a <code>null</code> input
2460: * value, if that particular parameter has a default value specified
2461: * in its operation's descriptor. In this case, the default value
2462: * will replace the <code>null</code> input.
2463: *
2464: * <p><code>JAI</code>also allows unspecified tailing parameters, if these
2465: * parameters have default values specified in the operation's
2466: * descriptor. However, if a parameter, which
2467: * has a default value, is followed by one or more parameters that
2468: * have no default values, this parameter must be specified in the
2469: * <code>ParameterBlock</code>, even if it only has a value of
2470: * code>null</code>.
2471: *
2472: * <p> The rendering hints associated with this instance of
2473: * <code>JAI</code> are overlaid with the hints passed to this
2474: * method. That is, the set of keys will be the union of the
2475: * keys from the instance's hints and the hints parameter.
2476: * If the same key exists in both places, the value from the
2477: * hints parameter will be used.
2478: *
2479: * <p> This version of <code>createRenderableCollection</code> is
2480: * non-static; it may be used with a specific instance of the JAI
2481: * class.
2482: *
2483: * @param opName The name of the operation.
2484: * @param args The source(s) and/or parameter(s) for the operation.
2485: * @param hints The hints for the operation.
2486: *
2487: * @throws IllegalArgumentException if <code>opName</code> is <code>null</code>.
2488: * @throws IllegalArgumentException if <code>args</code> is <code>null</code>.
2489: * @throws IllegalArgumentException if no
2490: * <code>OperationDescriptor</code> is registered under the
2491: * specified operation name in the current operation registry.
2492: * @throws IllegalArgumentException if the
2493: * <code>OperationDescriptor</code> registered under the specified
2494: * operation name in the current operation registry does not
2495: * support renderable image mode.
2496: * @throws IllegalArgumentException if the specified operation does
2497: * not produce a
2498: * <code>java.awt.image.renderable.RenderableImage</code> or a
2499: * <code>javax.media.jai.CollectionImage</code>.
2500: * @throws IllegalArgumentException if the specified operation is
2501: * unable to handle the sources and parameters specified in
2502: * <code>args</code>.
2503: *
2504: * @return A <code>Collection</code> that represents the named
2505: * operation.
2506: *
2507: * @since JAI 1.1
2508: */
2509: public Collection createRenderableCollectionNS(String opName,
2510: ParameterBlock args, RenderingHints hints) {
2511: if (opName == null) {
2512: throw new IllegalArgumentException(JaiI18N
2513: .getString("JAI14"));
2514: } else if (args == null) {
2515: throw new IllegalArgumentException(JaiI18N
2516: .getString("JAI15"));
2517: }
2518:
2519: String modeName = "renderableCollection";
2520:
2521: // Get the OperationDescriptor registered under the specified name.
2522: OperationDescriptor odesc = (OperationDescriptor) operationRegistry
2523: .getDescriptor(modeName, opName);
2524:
2525: if (odesc == null) {
2526: throw new IllegalArgumentException(opName + ": "
2527: + JaiI18N.getString("JAI0"));
2528: }
2529:
2530: Class destClass = odesc.getDestClass(modeName);
2531:
2532: if (!RenderableImage.class.isAssignableFrom(destClass)
2533: && !CollectionImage.class.isAssignableFrom(destClass)) {
2534: throw new IllegalArgumentException(opName + ": "
2535: + JaiI18N.getString("JAI6"));
2536: }
2537:
2538: // Validate input arguments. The ParameterBlock is cloned here
2539: // because OperationDescriptor.validateRenderableArguments()
2540: // may change its content.
2541:
2542: StringBuffer msg = new StringBuffer();
2543: args = (ParameterBlock) args.clone();
2544: RenderingHints mergedHints = mergeRenderingHints(
2545: renderingHints, hints);
2546: if (odesc.validateArguments(modeName, args, msg)) {
2547: if (RenderableImage.class.isAssignableFrom(destClass)) {
2548: Vector v = new Vector(1);
2549: RenderableOp op = new RenderableOp(operationRegistry,
2550: opName, args, mergedHints);
2551: v.add(op);
2552: return v;
2553: } else {
2554: CollectionOp cOp = new CollectionOp(operationRegistry,
2555: opName, args, mergedHints, true);
2556:
2557: // If the operation requests immediate rendering, do so.
2558: if (odesc.isImmediate()) {
2559: Collection coll = null;
2560: coll = cOp.getCollection();
2561: if (coll == null) {
2562: return null;
2563: }
2564: }
2565:
2566: return cOp;
2567: }
2568:
2569: } else {
2570: int numSources = odesc.getNumSources();
2571: Vector sources = args.getSources();
2572:
2573: // Get the iterator of all the sources that are collection.
2574: // Get the iterator for the collection that has the least elements.
2575:
2576: Iterator[] iters = new Iterator[numSources];
2577: Iterator iter = null;
2578: int size = Integer.MAX_VALUE;
2579: for (int i = 0; i < numSources; i++) {
2580: Object s = sources.elementAt(i);
2581: if (s instanceof Collection) {
2582: iters[i] = ((Collection) s).iterator();
2583: if (iter == null || ((Collection) s).size() < size) {
2584: iter = iters[i];
2585: size = ((Collection) s).size();
2586: }
2587: }
2588: }
2589:
2590: if (iter == null) {
2591:
2592: // None of the sources is a collection. The error is
2593: // with the input arguments.
2594:
2595: throw new IllegalArgumentException(msg.toString());
2596: }
2597:
2598: // Some sources are of type collection. Need to unwrap them.
2599: Collection col = null;
2600: for (int i = 0; i < numSources; i++) {
2601: Object s = sources.elementAt(i);
2602: if (s instanceof Collection) {
2603: try {
2604: col = (Collection) s.getClass().newInstance();
2605: break;
2606: } catch (Exception e) {
2607: // Unable to create this collection type, try next.
2608: sendExceptionToListener(JaiI18N
2609: .getString("JAI16")
2610: + s.getClass().getName(), e);
2611: }
2612: }
2613: }
2614: if (col == null) {
2615: col = new Vector();
2616: }
2617:
2618: // Get the source types.
2619: Class[] sourceClasses = odesc.getSourceClasses(modeName);
2620:
2621: while (iter.hasNext()) {
2622: ParameterBlock pb = new ParameterBlock();
2623: pb.setParameters(args.getParameters());
2624:
2625: for (int i = 0; i < numSources; i++) {
2626: // Get the next source.
2627: Object nextSource = null;
2628: if (iters[i] == null) {
2629: nextSource = sources.elementAt(i);
2630: } else {
2631: nextSource = iters[i].next();
2632: }
2633:
2634: // If the source is not of a compatible type and
2635: // is not a Collection then the 'false' value
2636: // returned by validateArguments() above must indicate
2637: // a real error.
2638: if (!sourceClasses[i].isAssignableFrom(nextSource
2639: .getClass())
2640: && !(nextSource instanceof Collection)) {
2641: throw new IllegalArgumentException(msg
2642: .toString());
2643: }
2644: pb.addSource(nextSource);
2645: }
2646:
2647: Collection c = createRenderableCollectionNS(opName, pb,
2648: mergedHints);
2649: if (c instanceof Vector
2650: && c.size() == 1
2651: && ((Vector) c).elementAt(0) instanceof RenderableOp) {
2652: col.add(((Vector) c).elementAt(0));
2653: } else {
2654: col.add(c);
2655: }
2656: }
2657:
2658: return col;
2659: }
2660: }
2661:
2662: // Rendering hints.
2663:
2664: /** An inner class defining rendering hint keys. */
2665: static class RenderingKey extends RenderingHints.Key {
2666: //cache the class of JAI to keep JAI.class in memory unless
2667: //the class RenderingKey is GC'ed. In this case, the
2668: // WeakReferences in the map of RenderingHints.Key will release
2669: // the instances of RenderingKey. So when JAI is loaded next
2670: // time, the keys can be recreated without any exception.
2671: // Fix bug: 4754807
2672: private static Class JAIclass = JAI.class;
2673:
2674: private Class objectClass;
2675:
2676: RenderingKey(int privateKey, Class objectClass) {
2677: super (privateKey);
2678: this .objectClass = objectClass;
2679: }
2680:
2681: public boolean isCompatibleValue(Object val) {
2682: return objectClass.isInstance(val);
2683: }
2684: }
2685:
2686: /**
2687: * Returns the <code>RenderingHints</code> associated with this
2688: * <code>JAI</code> instance. These rendering hints will be
2689: * merged with any hints supplied as an argument to the
2690: * <code>createNS()</code>, <code>createRenderableNS()</code>,
2691: * or <code>createCollectionNS()</code> methods.
2692: */
2693: public RenderingHints getRenderingHints() {
2694: return renderingHints;
2695: }
2696:
2697: /**
2698: * Sets the <code>RenderingHints</code> associated with this
2699: * <code>JAI</code> instance. These rendering hints will be
2700: * merged with any hints supplied as an argument to the
2701: * <code>createNS()</code>, <code>createRenderableNS()</code>,
2702: * or <code>createCollectionNS()</code> methods.
2703: *
2704: * <p> The <code>hints</code> argument must be non-null, otherwise
2705: * a <code>IllegalArgumentException</code> will be thrown.
2706: */
2707: public void setRenderingHints(RenderingHints hints) {
2708: if (hints == null) {
2709: throw new IllegalArgumentException(JaiI18N
2710: .getString("Generic0"));
2711: }
2712: this .renderingHints = hints;
2713: }
2714:
2715: /**
2716: * Clears the <code>RenderingHints</code> associated with this
2717: * <code>JAI</code> instance.
2718: */
2719: public void clearRenderingHints() {
2720: this .renderingHints = new RenderingHints(null);
2721: }
2722:
2723: /**
2724: * Returns the hint value associated with a given key
2725: * in this <code>JAI</code> instance, or <code>null</code>
2726: * if no value is associated with the given key.
2727: *
2728: * @throws IllegalArgumentException if <code>key</code> is
2729: * <code>null</code>.
2730: */
2731: public Object getRenderingHint(RenderingHints.Key key) {
2732: if (key == null) {
2733: throw new IllegalArgumentException(JaiI18N
2734: .getString("JAI7"));
2735: }
2736: return renderingHints.get(key);
2737: }
2738:
2739: /**
2740: * Sets the hint value associated with a given key
2741: * in this <code>JAI</code> instance.
2742: *
2743: * @throws IllegalArgumentException if <code>key</code> is
2744: * <code>null</code>.
2745: * @throws IllegalArgumentException if <code>value</code> is
2746: * <code>null</code>.
2747: * @throws IllegalArgumentException if <code>value</code> is
2748: * not of the correct type for the given hint.
2749: */
2750: public void setRenderingHint(RenderingHints.Key key, Object value) {
2751: if (key == null) {
2752: throw new IllegalArgumentException(JaiI18N
2753: .getString("JAI7"));
2754: }
2755: if (value == null) {
2756: throw new IllegalArgumentException(JaiI18N
2757: .getString("JAI9"));
2758: }
2759: try {
2760: renderingHints.put(key, value);
2761: } catch (Exception e) {
2762: throw new IllegalArgumentException(e.toString());
2763: }
2764: }
2765:
2766: /**
2767: * Removes the hint value associated with a given key
2768: * in this <code>JAI</code> instance.
2769: */
2770: public void removeRenderingHint(RenderingHints.Key key) {
2771: renderingHints.remove(key);
2772: }
2773:
2774: /**
2775: * Sets an <code>ImagingListener</code> object on this
2776: * <code>JAI</code>.
2777: *
2778: * @param imagingListener The <code>ImagingListener</code> to be used. If
2779: * the provided <code>ImagingListener</code> is
2780: * <code>null</code>, the default
2781: * <code>ImagingListener</code>, which rethrows the
2782: * <code>RuntimeException</code>s and prints
2783: * the stack trace of the other types to the stream
2784: * <code>System.err</code>, will be set.
2785: */
2786: public void setImagingListener(ImagingListener listener) {
2787: if (listener == null)
2788: listener = ImagingListenerImpl.getInstance();
2789: this .renderingHints.put(KEY_IMAGING_LISTENER, listener);
2790: this .imagingListener = listener;
2791: }
2792:
2793: /**
2794: * Gets the <code>ImagingListener</code> object from this
2795: * <code>JAI</code>.
2796: *
2797: * @return The <code>ImagingListener</code> object that currently
2798: * resides in this <code>JAI</code>.
2799: */
2800: public ImagingListener getImagingListener() {
2801: return imagingListener;
2802: }
2803:
2804: private void sendExceptionToListener(String message, Exception e) {
2805: ImagingListener listener = getImagingListener();
2806: listener.errorOccurred(message, e, this , false);
2807: }
2808: }
|