1. /*
  2. * @(#)ImageConsumer.java 1.23 04/07/16
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.awt.image;
  8. import java.util.Hashtable;
  9. /**
  10. * The interface for objects expressing interest in image data through
  11. * the ImageProducer interfaces. When a consumer is added to an image
  12. * producer, the producer delivers all of the data about the image
  13. * using the method calls defined in this interface.
  14. *
  15. * @see ImageProducer
  16. *
  17. * @version 1.23 07/16/04
  18. * @author Jim Graham
  19. */
  20. public interface ImageConsumer {
  21. /**
  22. * The dimensions of the source image are reported using the
  23. * setDimensions method call.
  24. * @param width the width of the source image
  25. * @param height the height of the source image
  26. */
  27. void setDimensions(int width, int height);
  28. /**
  29. * Sets the extensible list of properties associated with this image.
  30. * @param props the list of properties to be associated with this
  31. * image
  32. */
  33. void setProperties(Hashtable<?,?> props);
  34. /**
  35. * Sets the ColorModel object used for the majority of
  36. * the pixels reported using the setPixels method
  37. * calls. Note that each set of pixels delivered using setPixels
  38. * contains its own ColorModel object, so no assumption should
  39. * be made that this model will be the only one used in delivering
  40. * pixel values. A notable case where multiple ColorModel objects
  41. * may be seen is a filtered image when for each set of pixels
  42. * that it filters, the filter
  43. * determines whether the
  44. * pixels can be sent on untouched, using the original ColorModel,
  45. * or whether the pixels should be modified (filtered) and passed
  46. * on using a ColorModel more convenient for the filtering process.
  47. * @param model the specified <code>ColorModel</code>
  48. * @see ColorModel
  49. */
  50. void setColorModel(ColorModel model);
  51. /**
  52. * Sets the hints that the ImageConsumer uses to process the
  53. * pixels delivered by the ImageProducer.
  54. * The ImageProducer can deliver the pixels in any order, but
  55. * the ImageConsumer may be able to scale or convert the pixels
  56. * to the destination ColorModel more efficiently or with higher
  57. * quality if it knows some information about how the pixels will
  58. * be delivered up front. The setHints method should be called
  59. * before any calls to any of the setPixels methods with a bit mask
  60. * of hints about the manner in which the pixels will be delivered.
  61. * If the ImageProducer does not follow the guidelines for the
  62. * indicated hint, the results are undefined.
  63. * @param hintflags a set of hints that the ImageConsumer uses to
  64. * process the pixels
  65. */
  66. void setHints(int hintflags);
  67. /**
  68. * The pixels will be delivered in a random order. This tells the
  69. * ImageConsumer not to use any optimizations that depend on the
  70. * order of pixel delivery, which should be the default assumption
  71. * in the absence of any call to the setHints method.
  72. * @see #setHints
  73. */
  74. int RANDOMPIXELORDER = 1;
  75. /**
  76. * The pixels will be delivered in top-down, left-to-right order.
  77. * @see #setHints
  78. */
  79. int TOPDOWNLEFTRIGHT = 2;
  80. /**
  81. * The pixels will be delivered in (multiples of) complete scanlines
  82. * at a time.
  83. * @see #setHints
  84. */
  85. int COMPLETESCANLINES = 4;
  86. /**
  87. * The pixels will be delivered in a single pass. Each pixel will
  88. * appear in only one call to any of the setPixels methods. An
  89. * example of an image format which does not meet this criterion
  90. * is a progressive JPEG image which defines pixels in multiple
  91. * passes, each more refined than the previous.
  92. * @see #setHints
  93. */
  94. int SINGLEPASS = 8;
  95. /**
  96. * The image contain a single static image. The pixels will be defined
  97. * in calls to the setPixels methods and then the imageComplete method
  98. * will be called with the STATICIMAGEDONE flag after which no more
  99. * image data will be delivered. An example of an image type which
  100. * would not meet these criteria would be the output of a video feed,
  101. * or the representation of a 3D rendering being manipulated
  102. * by the user. The end of each frame in those types of images will
  103. * be indicated by calling imageComplete with the SINGLEFRAMEDONE flag.
  104. * @see #setHints
  105. * @see #imageComplete
  106. */
  107. int SINGLEFRAME = 16;
  108. /**
  109. * Delivers the pixels of the image with one or more calls
  110. * to this method. Each call specifies the location and
  111. * size of the rectangle of source pixels that are contained in
  112. * the array of pixels. The specified ColorModel object should
  113. * be used to convert the pixels into their corresponding color
  114. * and alpha components. Pixel (m,n) is stored in the pixels array
  115. * at index (n * scansize + m + off). The pixels delivered using
  116. * this method are all stored as bytes.
  117. * @param x, y the coordinates of the upper-left corner of the
  118. * area of pixels to be set
  119. * @param w the width of the area of pixels
  120. * @param h the height of the area of pixels
  121. * @param model the specified <code>ColorModel</code>
  122. * @param pixels the array of pixels
  123. * @param off the offset into the <code>pixels</code> array
  124. * @param scansize the distance from one row of pixels to the next in
  125. * the <code>pixels</code> array
  126. * @see ColorModel
  127. */
  128. void setPixels(int x, int y, int w, int h,
  129. ColorModel model, byte pixels[], int off, int scansize);
  130. /**
  131. * The pixels of the image are delivered using one or more calls
  132. * to the setPixels method. Each call specifies the location and
  133. * size of the rectangle of source pixels that are contained in
  134. * the array of pixels. The specified ColorModel object should
  135. * be used to convert the pixels into their corresponding color
  136. * and alpha components. Pixel (m,n) is stored in the pixels array
  137. * at index (n * scansize + m + off). The pixels delivered using
  138. * this method are all stored as ints.
  139. * this method are all stored as ints.
  140. * @param x, y the coordinates of the upper-left corner of the
  141. * area of pixels to be set
  142. * @param w the width of the area of pixels
  143. * @param h the height of the area of pixels
  144. * @param model the specified <code>ColorModel</code>
  145. * @param pixels the array of pixels
  146. * @param off the offset into the <code>pixels</code> array
  147. * @param scansize the distance from one row of pixels to the next in
  148. * the <code>pixels</code> array
  149. * @see ColorModel
  150. */
  151. void setPixels(int x, int y, int w, int h,
  152. ColorModel model, int pixels[], int off, int scansize);
  153. /**
  154. * The imageComplete method is called when the ImageProducer is
  155. * finished delivering all of the pixels that the source image
  156. * contains, or when a single frame of a multi-frame animation has
  157. * been completed, or when an error in loading or producing the
  158. * image has occured. The ImageConsumer should remove itself from the
  159. * list of consumers registered with the ImageProducer at this time,
  160. * unless it is interested in successive frames.
  161. * @param status the status of image loading
  162. * @see ImageProducer#removeConsumer
  163. */
  164. void imageComplete(int status);
  165. /**
  166. * An error was encountered while producing the image.
  167. * @see #imageComplete
  168. */
  169. int IMAGEERROR = 1;
  170. /**
  171. * One frame of the image is complete but there are more frames
  172. * to be delivered.
  173. * @see #imageComplete
  174. */
  175. int SINGLEFRAMEDONE = 2;
  176. /**
  177. * The image is complete and there are no more pixels or frames
  178. * to be delivered.
  179. * @see #imageComplete
  180. */
  181. int STATICIMAGEDONE = 3;
  182. /**
  183. * The image creation process was deliberately aborted.
  184. * @see #imageComplete
  185. */
  186. int IMAGEABORTED = 4;
  187. }