001: /*
002: * $RCSfile: OperationDescriptor.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:12 $
010: * $State: Exp $
011: */
012: package javax.media.jai;
013:
014: import java.awt.RenderingHints;
015: import java.awt.image.renderable.ParameterBlock;
016: import java.util.Locale;
017: import java.util.ResourceBundle;
018:
019: /**
020: * This interface provides a comprehensive description of a specific
021: * image operation. All information regarding the operation, such as
022: * its name, version, input, and properties should be listed. Any
023: * conditions placed on the operation, such as its source class types and
024: * legal parameter range, should also be included, and the methods to
025: * enforce these conditions should be implemented. A set of
026: * <code>PropertyGenerator</code>s may be specified to be used as a
027: * basis for the operation's property management.
028: *
029: * <p> Each image operation in JAI must have a descriptor
030: * that implements this interface. The following basic resource data
031: * must be provided:
032: * <ul>
033: * <li> A global operation name that is visible to all and is the same
034: * in all <code>Locale</code>s. </li>
035: * <li> A localized operation name that may be used as a synonym for
036: * the global operation name. </li>
037: * <li> The name of the vendor defining this operation. </li>
038: * <li> A brief description of this operation. </li>
039: * <li> An URL where additional documentation on this operation may be
040: * found. </li>
041: * <li> The version of this operation. </li>
042: * </ul>
043: * Additional information must be provided when appropriate. Only then
044: * can this operation be added to an <code>OperationRegistry</code>.
045: * Furthermore, it is recommended that a detailed description of the
046: * operation's functionality be included in the class comments.
047: *
048: * <p> JAI currently knows about the following operation modes :
049: * "rendered", "renderable", "collection" and "renderableCollection"
050: * (these form a subset of the known registry modes returned by
051: * <code>RegistryMode.getModes()</code>). All mode names are dealt
052: * with in a case insensitive (but retentive) manner. All modes have
053: * to accept the same number of source images and the same number of
054: * parameters. All the source names and parameter names are also the
055: * same across all modes. The class types of the sources and parameters
056: * can be different for each mode.
057: *
058: * <p> For example an operation supporting the "rendered" mode
059: * takes <code>RenderedImage</code>s as its sources, can only
060: * be used in a rendered operation chain, and produces a
061: * <code>RenderedImage</code>. An operation supporting the renderable
062: * mode takes <code>RenderableImage</code>s as its sources, can
063: * only be used in a renderable operation chain, and produces a
064: * <code>RenderableImage</code>.
065: *
066: * @see JAI
067: * @see OperationDescriptorImpl
068: *
069: */
070: public interface OperationDescriptor extends RegistryElementDescriptor {
071:
072: /**
073: * An <code>Object</code> that signifies that
074: * a parameter has no default value. Same as
075: * <code>ParameterListDescriptor.NO_PARAMETER_DEFAULT</code>
076: */
077: public static final Object NO_PARAMETER_DEFAULT = ParameterListDescriptor.NO_PARAMETER_DEFAULT;
078:
079: /**
080: * Returns the resource data for this operation in the specified
081: * <code>Locale</code>. It must contain <code>String</code> data
082: * for the following tags:
083: * <ul>
084: * <li> "GlobalName" - A global operation name that is visible to all
085: * and is the same in all <code>Locale</code>s. </li>
086: * <li> "LocalName" - A localized operation name that may be used as a
087: * synonym for the "GlobalName". </li>
088: * <li> "Vendor" - The name of the vendor defining this operation.
089: * Vendors are encouraged to use the Java convention
090: * of reversed Internet addresses. </li>
091: * <li> "Description" - A brief description of this operation. </li>
092: * <li> "DocURL" - An URL where additional documentation on this
093: * operation may be found. </li>
094: * <li> "Version" - A free-form version indicator of this operation. </li>
095: * </ul>
096: * In addition, it may contain <code>String</code> data for the
097: * following tags when appropriate:
098: * <ul>
099: * <li> "arg0Desc", "arg1Desc", ... - Description of the input
100: * parameters. </li>
101: * <li> "hint0Desc", hint1Desc", ... - Description of the rendering
102: * hints. </li>
103: * </ul>
104: *
105: * @param locale The <code>Locale</code> for which the information
106: * should be localized. It may be different from the default
107: * <code>Locale</code>.
108: *
109: * @return A two-dimensional array of <code>String</code>s containing
110: * the mandatory and optional resource tags and their
111: * corresponding resource data. (String[i][0] is
112: * the tag for the i-th resource and String[i][1] is the
113: * corresponding data)
114: */
115: String[][] getResources(Locale locale);
116:
117: /**
118: * Returns the resource data for this operation in the specified
119: * <code>Locale</code> in a <code>ResourceBundle</code>. The
120: * resource data values are taken from the
121: * <code>getResources()</code> method which must be implemented
122: * by each operation descriptor.
123: *
124: * @param locale The <code>Locale</code> for which the information
125: * should be localized. It may be different from the default
126: * <code>Locale</code>.
127: *
128: * @return A <code>ResourceBundle</code> containing the mandatory
129: * and optional resource information.
130: */
131: ResourceBundle getResourceBundle(Locale locale);
132:
133: /**
134: * Returns the number of sources required by this operation.
135: * All modes have the same number of sources.
136: */
137: int getNumSources();
138:
139: /**
140: * Returns an array of <code>Class</code>es that describe the types
141: * of sources required by this operation for the specified mode.
142: * If this operation has no sources, this method returns <code>null</code>.
143: *
144: * @param modeName the operation mode name
145: *
146: * @throws IllegalArgumentException if modeName is <code>null</code>
147: * or if it is not one of the supported modes.
148: *
149: * @since JAI 1.1
150: */
151: Class[] getSourceClasses(String modeName);
152:
153: /**
154: * Returns an array of <code>String</code>s that are the names
155: * of the sources of this operation. If this operation has no
156: * sources, this method returns <code>null</code>.
157: *
158: * @since JAI 1.1
159: */
160: String[] getSourceNames();
161:
162: /**
163: * Returns a <code>Class</code> that describes the type of
164: * destination this operation produces for the specified mode.
165: *
166: * @param modeName the operation mode name
167: *
168: * @throws IllegalArgumentException if modeName is <code>null</code>
169: * or if it is not one of the supported modes.
170: *
171: * @since JAI 1.1
172: */
173: Class getDestClass(String modeName);
174:
175: /**
176: * Returns <code>true</code> if this operation/mode is capable of
177: * handling the input source(s) and/or parameter(s)
178: * specified in the <code>ParameterBlock</code>, or
179: * <code>false</code> otherwise, in which case an explanatory
180: * message may be appended to the <code>StringBuffer</code>.
181: *
182: * <p> This method is the standard place where input arguments are
183: * validated against this operation's specification for the specified
184: * mode. It is called by <code>JAI.create()</code> as a part of its
185: * validation process. Thus it is strongly recommended that the
186: * application programs use the <code>JAI.create()</code> methods to
187: * instantiate all the rendered operations.
188: *
189: * <p> This method sets all the undefined parameters in the
190: * <code>ParameterBlock</code> to their default values, if the default
191: * values are specified.
192: *
193: * <p> Note that <code>DeferredData</code> parameters will not be
194: * recognized as valid unless the parameter is defined to have class
195: * <code>DeferredData.class</code>.
196: *
197: * @param modeName the operation mode name
198: * @param args Input arguments, including source(s) and/or parameter(s).
199: * @param msg A string that may contain error messages.
200: *
201: * @throws IllegalArgumentException if modeName is <code>null</code>
202: *
203: * @since JAI 1.1
204: */
205: boolean validateArguments(String modeName, ParameterBlock args,
206: StringBuffer msg);
207:
208: /**
209: * Returns <code>true</code> if the operation should be computed
210: * immediately for all supported modes of this operation during
211: * the call to <code>JAI.create()</code>; that is, the operation
212: * is placed in immediate mode. If <code>true</code>, and
213: * the computation fails, <code>null</code> will be returned
214: * from <code>JAI.create()</code>. If <code>false</code>,
215: * <code>JAI.create()</code> will return an instance of the
216: * appropriate destination class that may be asked to compute itself
217: * at a later time; this computation may fail at that time.
218: *
219: * <p> Operations that rely on an external resource, such as
220: * a source file, or that produce externally-visible side
221: * effects, such as writing to an output file, should return
222: * <code>true</code> from this method. Operations that rely
223: * only on their sources and parameters usually wish to return
224: * <code>false</code> in order to defer rendering as long as
225: * possible.
226: */
227: boolean isImmediate();
228:
229: /************************ Generic Methods ************************/
230:
231: /**
232: * Calculates the region over which two distinct renderings
233: * of an operation may be expected to differ.
234: *
235: * <p> The class of the returned object will vary as a function of
236: * the mode of the operation. For rendered and renderable two-
237: * dimensional images this should be an instance of a class which
238: * implements <code>java.awt.Shape</code>.
239: *
240: * @param registryModeName The name of the mode.
241: * @param oldParamBlock The previous sources and parameters.
242: * @param oldHints The previous hints.
243: * @param newParamBlock The current sources and parameters.
244: * @param newHints The current hints.
245: * @param node The affected node in the processing chain.
246: *
247: * @return The region over which the data of two renderings of this
248: * operation may be expected to be invalid or <code>null</code>
249: * if there is no common region of validity. If an empty
250: * <code>java.awt.Shape</code> is returned, this indicates
251: * that all pixels within the bounds of the old rendering
252: * remain valid.
253: *
254: * @throws IllegalArgumentException if <code>registryModeName</code>
255: * is <code>null</code> or if the operation requires either
256: * sources or parameters and either <code>oldParamBlock</code>
257: * or <code>newParamBlock</code> is <code>null</code>.
258: * @throws IllegalArgumentException if <code>oldParamBlock</code> or
259: * <code>newParamBlock</code> do not contain sufficient sources
260: * or parameters for the operation in question.
261: *
262: * @since JAI 1.1
263: */
264: Object getInvalidRegion(String registryModeName,
265: ParameterBlock oldParamBlock, RenderingHints oldHints,
266: ParameterBlock newParamBlock, RenderingHints newHints,
267: OperationNode node);
268:
269: /********************** DEPRECATED METHODS *************************/
270:
271: // All mode specific methods are deprecated since JAI 1.1
272: // in favor of the equivalent methods which accept a modeName
273: // as a parameter.
274: /**
275: * Returns an array of <code>PropertyGenerator</code>s implementing
276: * the property inheritance for this operation. They may be used
277: * as a basis for the operation's property management.
278: *
279: * @return An array of <code>PropertyGenerator</code>s, or
280: * <code>null</code> if this operation does not have any of
281: * its own <code>PropertyGenerator</code>s.
282: *
283: * @deprecated as of JAI 1.1 in favor of the equivalent method
284: * that specifies the mode name.
285: */
286: PropertyGenerator[] getPropertyGenerators();
287:
288: /********************** Rendered Mode Methods (deprecated) *********/
289:
290: /**
291: * Returns <code>true</code> if this operation supports the rendered
292: * image mode. That is, it may be performed on <code>RenderedImage</code>
293: * sources in a rendered operation chain, and produces a rendered result.
294: * The <code>JAI.create()</code> and the
295: * <code>JAI.createCollection()</code> methods should be used to
296: * instantiate the operation.
297: *
298: * <p> If this method returns <code>true</code>, all the additional
299: * methods that supply the rendered mode information must be
300: * implemented.
301: *
302: * @deprecated as of JAI 1.1 in favor of <code>isModeSupported("rendered")</code>
303: */
304: boolean isRenderedSupported();
305:
306: /**
307: * Returns an array of <code>Class</code>es that describe the types
308: * of sources required by this operation in the rendered image mode.
309: * If this operation has no source, this method returns <code>null</code>.
310: *
311: * @deprecated as of JAI 1.1 in favor of <code>getSourceClasses("rendered")</code>
312: */
313: Class[] getSourceClasses();
314:
315: /**
316: * Returns a <code>Class</code> that describes the type of
317: * destination this operation produces in the rendered image
318: * mode. Currently JAI supports two destination class types:
319: * <code>java.awt.image.RenderedImage.class</code> and
320: * <code>java.util.Collection.class</code>.
321: *
322: * @deprecated as of JAI 1.1 in favor of <code>getDestClass("rendered")</code>
323: */
324: Class getDestClass();
325:
326: /**
327: * Returns <code>true</code> if this operation is capable of
328: * handling the input rendered source(s) and/or parameter(s)
329: * specified in the <code>ParameterBlock</code>, or
330: * <code>false</code> otherwise, in which case an explanatory
331: * message may be appended to the <code>StringBuffer</code>.
332: *
333: * <p> This method is the standard place where input arguments are
334: * validated against this operation's specification for the rendered
335: * mode. It is called by <code>JAI.create()</code> as a part of its
336: * validation process. Thus it is strongly recommended that the
337: * application programs use the <code>JAI.create()</code> methods to
338: * instantiate all the rendered operations.
339: *
340: * <p> This method sets all the undefined parameters in the
341: * <code>ParameterBlock</code> to their default values, if the default
342: * values are specified.
343: *
344: * <p> Note that <code>DeferredData</code> parameters will not be
345: * recognized as valid unless the parameter is defined to have class
346: * <code>DeferredData.class</code>.
347: *
348: * @param args Input arguments, including source(s) and/or parameter(s).
349: * @param msg A string that may contain error messages.
350: *
351: * @deprecated as of JAI 1.1 in favor of <code>validateArguments("rendered", ...)</code>
352: */
353: boolean validateArguments(ParameterBlock args, StringBuffer msg);
354:
355: /********************* Renderable Mode Methods (deprecated) ********/
356:
357: /**
358: * Returns <code>true</code> if this operation supports the renderable
359: * image mode. That is, it may be performed on <code>RenderableImage</code>
360: * sources in a renderable operation chain, and produces a renderable
361: * result. The <code>JAI.createRenderable()</code> and the
362: * <code>JAI.createCollection()</code> methods should be used to
363: * instantiate the operation.
364: *
365: * <p> If this method returns <code>true</code>, all the additional
366: * methods that supply the renderable mode information must be
367: * implemented.
368: *
369: * @deprecated as of JAI 1.1 in favor of <code>isModeSupported("renderable")</code>
370: */
371: boolean isRenderableSupported();
372:
373: /**
374: * Returns an array of <code>Class</code>es that describe the types
375: * of sources required by this operation in the renderable image mode.
376: * If this operation does not support the renderable mode, or if it
377: * has no source, this method returns <code>null</code>.
378: *
379: * @deprecated as of JAI 1.1 in favor of <code>getSourceClasses("renderable")</code>
380: */
381: Class[] getRenderableSourceClasses();
382:
383: /**
384: * Returns a <code>Class</code> that describes the type of
385: * destination this operation produces in the renderable image
386: * mode. Currently JAI supports two destination class types:
387: * <code>java.awt.image.renderable.RenderableImage.class</code> and
388: * <code>java.util.Collection.class</code>.
389: *
390: * @deprecated as of JAI 1.1 in favor of <code>getDestClass("renderable")</code>
391: */
392: Class getRenderableDestClass();
393:
394: /**
395: * Returns <code>true</code> if this operation is capable of handling
396: * the input renderable source(s) and/or parameter(s) specified
397: * in the <code>ParameterBlock</code>, or <code>false</code>
398: * otherwise, in which case an explanatory message may be appended
399: * to the <code>StringBuffer</code>.
400: *
401: * <p> This method is the standard place where input arguments are
402: * validated against this operation's specification for the renderable
403: * mode. It is called by <code>JAI.createRenderable()</code> as a
404: * part of its validation process. Thus it is strongly recommended
405: * that the application programs use the
406: * <code>JAI.createRenderable()</code> method to instantiate all
407: * the renderable operations.
408: *
409: * <p> This method sets all the undefined parameters in the
410: * <code>ParameterBlock</code> to their default values, if the default
411: * values are specified.
412: *
413: * <p> Note that <code>DeferredData</code> parameters will not be
414: * recognized as valid unless the parameter is defined to have class
415: * <code>DeferredData.class</code>.
416: *
417: * <p> If this operation does not support the renderable mode,
418: * this method returns <code>false</code> regardless of the input
419: * arguments
420: *
421: * @param args Input arguments, including source(s) and/or parameter(s).
422: * @param msg A string that may contain error messages.
423: *
424: * @deprecated as of JAI 1.1 in favor of <code>validateArguments("renderable", ...)</code>
425: */
426: boolean validateRenderableArguments(ParameterBlock args,
427: StringBuffer msg);
428:
429: /************************ Parameter Methods (deprecated) ***********/
430:
431: /**
432: * Returns the number of parameters (not including the sources)
433: * required by this operation.
434: *
435: * @deprecated as of JAI 1.1 in favor of <code>
436: * getParameterListDescriptor(modeName).getNumParameters()</code>
437: * This will for the time being return the above value for
438: * modeName = getSupportedModes()[0]
439: */
440: int getNumParameters();
441:
442: /**
443: * Returns an array of <code>Class</code>es that describe the types
444: * of parameters required by this operation. If this operation
445: * has no parameter, this method returns <code>null</code>.
446: *
447: * @deprecated as of JAI 1.1 in favor of <code>
448: * getParameterListDescriptor(modeName).getParamClasses()</code>
449: * This will for the time being return the above value for
450: * modeName = getSupportedModes()[0]
451: */
452: Class[] getParamClasses();
453:
454: /**
455: * Returns an array of <code>String</code>s that are the localized
456: * parameter names of this operation. If this operation has no
457: * parameter, this method returns <code>null</code>.
458: *
459: * @deprecated as of JAI 1.1 in favor of <code>
460: * getParameterListDescriptor(modeName).getParamNames()</code>
461: * This will for the time being return the above value for
462: * modeName = getSupportedModes()[0]
463: */
464: String[] getParamNames();
465:
466: /**
467: * Returns an array of <code>Object</code>s that define the default
468: * values of the parameters for this operation. Default values may
469: * be <code>null</code>. When instantiating the operation, the
470: * default values may be used for those parameters whose values are
471: * not supplied. The <code>NO_PARAMETER_DEFAULT</code> static
472: * <code>Object</code> indicates that a parameter has no default
473: * value. If this operation has no parameter, this method returns
474: * <code>null</code>.
475: *
476: * @deprecated as of JAI 1.1 in favor of <code>
477: * getParameterListDescriptor(modeName).getParamDefaults()</code>
478: * This will for the time being return the above value for
479: * modeName = getSupportedModes()[0]
480: */
481: Object[] getParamDefaults();
482:
483: /**
484: * Returns the default value of a specified parameter. The default
485: * value may be <code>null</code>. If a parameter has no default
486: * value, this method returns <code>NO_PARAMETER_DEFAULT</code>.
487: *
488: * @param index The index of the parameter whose default
489: * value is queried.
490: *
491: * @throws NullPointerException if this operation has no parameter.
492: * @throws ArrayIndexOutOfBoundsException if there is no parameter
493: * corresponding to the specified <code>index</code>.
494: *
495: * @deprecated as of JAI 1.1 in favor of <code>
496: * getParameterListDescriptor(modeName).getParamDefaultValue()</code>
497: * This will for the time being return the above value for
498: * modeName = getSupportedModes()[0]
499: */
500: Object getParamDefaultValue(int index);
501:
502: /**
503: * Returns the minimum legal value of a specified numeric parameter
504: * for this operation. If the specified parameter is non-numeric,
505: * this method returns <code>null</code>.
506: *
507: * <p> The return value should be of the class type appropriate for
508: * the parameter's type, that is, <code>Byte</code> for a
509: * <code>byte</code> parameter, <code>Integer</code> for an
510: * <code>int</code> parameter, and so forth.
511: *
512: * @param index The index of the numeric parameter whose minimum
513: * value is queried.
514: *
515: * @return A <code>Number</code> representing the minimum legal value
516: * of the queried parameter, or <code>null</code>.
517: *
518: * @throws NullPointerException if this operation has no parameter.
519: * @throws ArrayIndexOutOfBoundsException if there is no parameter
520: * corresponding to the specified <code>index</code>.
521: *
522: * @deprecated as of JAI 1.1 in favor of <code>
523: * getParameterListDescriptor(modeName).getParamValueRange()</code>
524: * This will for the time being return "getMinValue" of the above
525: * return value for modeName = getSupportedModes()[0]
526: */
527: Number getParamMinValue(int index);
528:
529: /**
530: * Returns the maximum legal value of a specified numeric parameter
531: * for this operation. If the specified parameter is non-numeric,
532: * this method returns <code>null</code>.
533: *
534: * <p> The return value should be of the class type appropriate for
535: * the parameter's type, that is, <code>Byte</code> for a
536: * <code>byte</code> parameter, <code>Integer</code> for an
537: * <code>int</code> parameter, and so forth.
538: *
539: * @param index The index of the numeric parameter whose maximum
540: * value is queried.
541: *
542: * @return A <code>Number</code> representing the maximum legal value
543: * of the queried parameter, or <code>null</code>.
544: *
545: * @throws NullPointerException if this operation has no parameter.
546: * @throws ArrayIndexOutOfBoundsException if there is no parameter
547: * corresponding to the specified <code>index</code>.
548: *
549: * @deprecated as of JAI 1.1 in favor of <code>
550: * getParameterListDescriptor(modeName).getParamValueRange()</code>
551: * This will for the time being return "getMaxValue" of the above
552: * return value for modeName = getSupportedModes()[0]
553: */
554: Number getParamMaxValue(int index);
555: }
|