1 /*
2 * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.awt.image;
27
28 import java.util.Arrays;
29 import java.util.List;
30
31 /**
32 * The interface for objects which can produce the image data for Images.
33 * Each image contains an ImageProducer which is used to reconstruct
34 * the image whenever it is needed, for example, when a new size of the
35 * Image is scaled, or when the width or height of the Image is being
36 * requested.
37 *
38 * @see ImageConsumer
39 *
40 * @author Jim Graham
41 */
42 public interface ImageProducer {
43 /**
44 * Registers an {@code ImageConsumer} with the
45 * {@code ImageProducer} for access to the image data
46 * during a later reconstruction of the {@code Image}.
47 * The {@code ImageProducer} may, at its discretion,
48 * start delivering the image data to the consumer
49 * using the {@code ImageConsumer} interface immediately,
50 * or when the next available image reconstruction is triggered
51 * by a call to the {@code startProduction} method.
52 * @param ic the specified {@code ImageConsumer}
53 * @see #startProduction
54 */
55 public void addConsumer(ImageConsumer ic);
56
57 /**
58 * Determines if a specified {@code ImageConsumer}
59 * object is currently registered with this
60 * {@code ImageProducer} as one of its consumers.
61 * @param ic the specified {@code ImageConsumer}
62 * @return {@code true} if the specified
63 * {@code ImageConsumer} is registered with
64 * this {@code ImageProducer};
65 * {@code false} otherwise.
66 */
67 public boolean isConsumer(ImageConsumer ic);
68
69 /**
70 * Removes the specified {@code ImageConsumer} object
71 * from the list of consumers currently registered to
72 * receive image data. It is not considered an error
73 * to remove a consumer that is not currently registered.
74 * The {@code ImageProducer} should stop sending data
75 * to this consumer as soon as is feasible.
76 * @param ic the specified {@code ImageConsumer}
77 */
78 public void removeConsumer(ImageConsumer ic);
79
80 /**
81 * Registers the specified {@code ImageConsumer} object
82 * as a consumer and starts an immediate reconstruction of
83 * the image data which will then be delivered to this
84 * consumer and any other consumer which might have already
85 * been registered with the producer. This method differs
86 * from the addConsumer method in that a reproduction of
87 * the image data should be triggered as soon as possible.
88 * @param ic the specified {@code ImageConsumer}
89 * @see #addConsumer
90 */
91 public void startProduction(ImageConsumer ic);
92
93 /**
94 * Requests, on behalf of the {@code ImageConsumer},
95 * that the {@code ImageProducer} attempt to resend
96 * the image data one more time in TOPDOWNLEFTRIGHT order
97 * so that higher quality conversion algorithms which
98 * depend on receiving pixels in order can be used to
99 * produce a better output version of the image. The
100 * {@code ImageProducer} is free to
101 * ignore this call if it cannot resend the data in that
102 * order. If the data can be resent, the
103 * {@code ImageProducer} should respond by executing
104 * the following minimum set of {@code ImageConsumer}
105 * method calls:
106 * <pre>{@code
107 * ic.setHints(TOPDOWNLEFTRIGHT | < otherhints >);
108 * ic.setPixels(...); // As many times as needed
109 * ic.imageComplete();
110 * }</pre>
111 * @param ic the specified {@code ImageConsumer}
112 * @see ImageConsumer#setHints
113 */
114 public void requestTopDownLeftRightResend(ImageConsumer ic);
115
116 /**
117 * Returns {@code true} if {@code ImageProducer} consist of a set of
118 * image producers which can be used for {@code MultiResolutionImage}
119 * construction.
120 *
121 * @return {@code true} if {@code ImageProducer} consist of a set of
122 * image producers
123 *
124 * @see #getResolutionVariantItems
125 * @see MultiResolutionImage
126 *
127 * @since 9
128 */
129 default boolean isMultiResolutionImageProducer() {
130 return false;
131 }
132
133 /**
134 * Gets a readable list of all resolution variant items consisting of
135 * {@code ImageProducer} and associated scale factors. The provided
136 * resolution variant items can be used for {@code MultiResolutionImage}
137 * construction.
138 * The list must be nonempty and contain at least one resolution variant item.
139 * <p>
140 * Note that many implementations might return an unmodifiable list.
141 *
142 * @return list of resolution variant items.
143 * @see #isMultiResolutionImageProducer
144 * @see MultiResolutionImage
145 *
146 * @since 9
147 */
148 default List<ResolutionVariantItem<ImageProducer>> getResolutionVariantItems() {
149 return Arrays.asList(new ResolutionVariantItem<>(this, 1, 1));
150 }
151 }