1. /*
  2. * @(#)ImageTranscoder.java 1.19 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.imageio;
  8. import javax.imageio.metadata.IIOMetadata;
  9. /**
  10. * An interface providing metadata transcoding capability.
  11. *
  12. * <p> Any image may be transcoded (written to a different format
  13. * than the one it was originally stored in) simply by performing
  14. * a read operation followed by a write operation. However, loss
  15. * of data may occur in this process due to format differences.
  16. *
  17. * <p> In general, the best results will be achieved when
  18. * format-specific metadata objects can be created to encapsulate as
  19. * much information about the image and its associated metadata as
  20. * possible, in terms that are understood by the specific
  21. * <code>ImageWriter</code> used to perform the encoding.
  22. *
  23. * <p> An <code>ImageTranscoder</code> may be used to convert the
  24. * <code>IIOMetadata</code> objects supplied by the
  25. * <code>ImageReader</code> (representing per-stream and per-image
  26. * metadata) into corresponding objects suitable for encoding by a
  27. * particular <code>ImageWriter</code>. In the case where the methods
  28. * of this interface are being called directly on an
  29. * <code>ImageWriter</code>, the output will be suitable for that
  30. * writer.
  31. *
  32. * <p> The internal details of converting an <code>IIOMetadata</code>
  33. * object into a writer-specific format will vary according to the
  34. * context of the operation. Typically, an <code>ImageWriter</code>
  35. * will inspect the incoming object to see if it implements additional
  36. * interfaces with which the writer is familiar. This might be the
  37. * case, for example, if the object was obtained by means of a read
  38. * operation on a reader plug-in written by the same vendor as the
  39. * writer. In this case, the writer may access the incoming object by
  40. * means of its plug-in specific interfaces. In this case, the
  41. * re-encoding may be close to lossless if the image file format is
  42. * kept constant. If the format is changing, the writer may still
  43. * attempt to preserve as much information as possible.
  44. *
  45. * <p> If the incoming object does not implement any additional
  46. * interfaces known to the writer, the writer has no choice but to
  47. * access it via the standard <code>IIOMetadata</code> interfaces such
  48. * as the tree view provided by <code>IIOMetadata.getAsTree</code>.
  49. * In this case, there is likely to be significant loss of
  50. * information.
  51. *
  52. * <p> An independent <code>ImageTranscoder</code> essentially takes
  53. * on the same role as the writer plug-in in the above examples. It
  54. * must be familiar with the private interfaces used by both the
  55. * reader and writer plug-ins, and manually instantiate an object that
  56. * will be usable by the writer. The resulting metadata objects may
  57. * be used by the writer directly.
  58. *
  59. * <p> No independent implementations of <code>ImageTranscoder</code>
  60. * are provided as part of the standard API. Instead, the intention
  61. * of this interface is to provide a way for implementations to be
  62. * created and discovered by applications as the need arises.
  63. *
  64. * @version 0.5
  65. */
  66. public interface ImageTranscoder {
  67. /**
  68. * Returns an <code>IIOMetadata</code> object that may be used for
  69. * encoding and optionally modified using its document interfaces
  70. * or other interfaces specific to the writer plug-in that will be
  71. * used for encoding.
  72. *
  73. * <p> An optional <code>ImageWriteParam</code> may be supplied
  74. * for cases where it may affect the structure of the stream
  75. * metadata.
  76. *
  77. * <p> If the supplied <code>ImageWriteParam</code> contains
  78. * optional setting values not understood by this writer or
  79. * transcoder, they will be ignored.
  80. *
  81. * @param inData an <code>IIOMetadata</code> object representing
  82. * stream metadata, used to initialize the state of the returned
  83. * object.
  84. * @param param an <code>ImageWriteParam</code> that will be used to
  85. * encode the image, or <code>null</code>.
  86. *
  87. * @return an <code>IIOMetadata</code> object, or
  88. * <code>null</code> if the plug-in does not provide metadata
  89. * encoding capabilities.
  90. *
  91. * @exception IllegalArgumentException if <code>inData</code> is
  92. * <code>null</code>.
  93. */
  94. IIOMetadata convertStreamMetadata(IIOMetadata inData,
  95. ImageWriteParam param);
  96. /**
  97. * Returns an <code>IIOMetadata</code> object that may be used for
  98. * encoding and optionally modified using its document interfaces
  99. * or other interfaces specific to the writer plug-in that will be
  100. * used for encoding.
  101. *
  102. * <p> An optional <code>ImageWriteParam</code> may be supplied
  103. * for cases where it may affect the structure of the image
  104. * metadata.
  105. *
  106. * <p> If the supplied <code>ImageWriteParam</code> contains
  107. * optional setting values not understood by this writer or
  108. * transcoder, they will be ignored.
  109. *
  110. * @param inData an <code>IIOMetadata</code> object representing
  111. * image metadata, used to initialize the state of the returned
  112. * object.
  113. * @param imageType an <code>ImageTypeSpecifier</code> indicating
  114. * the layout and color information of the image with which the
  115. * metadata will be associated.
  116. * @param param an <code>ImageWriteParam</code> that will be used to
  117. * encode the image, or <code>null</code>.
  118. *
  119. * @return an <code>IIOMetadata</code> object,
  120. * or <code>null</code> if the plug-in does not provide
  121. * metadata encoding capabilities.
  122. *
  123. * @exception IllegalArgumentException if either of
  124. * <code>inData</code> or <code>imageType</code> is
  125. * <code>null</code>.
  126. */
  127. IIOMetadata convertImageMetadata(IIOMetadata inData,
  128. ImageTypeSpecifier imageType,
  129. ImageWriteParam param);
  130. }