1 /*
2 * Copyright (c) 1997, 2014, 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;
27
28 import java.beans.ConstructorProperties;
29
30 import java.lang.annotation.Native;
31
32 /**
33 * The {@code BasicStroke} class defines a basic set of rendering
34 * attributes for the outlines of graphics primitives, which are rendered
35 * with a {@link Graphics2D} object that has its Stroke attribute set to
36 * this {@code BasicStroke}.
37 * The rendering attributes defined by {@code BasicStroke} describe
38 * the shape of the mark made by a pen drawn along the outline of a
39 * {@link Shape} and the decorations applied at the ends and joins of
40 * path segments of the {@code Shape}.
41 * These rendering attributes include:
42 * <dl>
43 * <dt><i>width</i>
44 * <dd>The pen width, measured perpendicularly to the pen trajectory.
45 * <dt><i>end caps</i>
46 * <dd>The decoration applied to the ends of unclosed subpaths and
47 * dash segments. Subpaths that start and end on the same point are
48 * still considered unclosed if they do not have a CLOSE segment.
49 * See {@link java.awt.geom.PathIterator#SEG_CLOSE SEG_CLOSE}
50 * for more information on the CLOSE segment.
51 * The three different decorations are: {@link #CAP_BUTT},
52 * {@link #CAP_ROUND}, and {@link #CAP_SQUARE}.
53 * <dt><i>line joins</i>
54 * <dd>The decoration applied at the intersection of two path segments
55 * and at the intersection of the endpoints of a subpath that is closed
56 * using {@link java.awt.geom.PathIterator#SEG_CLOSE SEG_CLOSE}.
57 * The three different decorations are: {@link #JOIN_BEVEL},
58 * {@link #JOIN_MITER}, and {@link #JOIN_ROUND}.
59 * <dt><i>miter limit</i>
60 * <dd>The limit to trim a line join that has a JOIN_MITER decoration.
61 * A line join is trimmed when the ratio of miter length to stroke
62 * width is greater than the miterlimit value. The miter length is
63 * the diagonal length of the miter, which is the distance between
64 * the inside corner and the outside corner of the intersection.
65 * The smaller the angle formed by two line segments, the longer
66 * the miter length and the sharper the angle of intersection. The
67 * default miterlimit value of 10.0f causes all angles less than
68 * 11 degrees to be trimmed. Trimming miters converts
69 * the decoration of the line join to bevel.
70 * <dt><i>dash attributes</i>
71 * <dd>The definition of how to make a dash pattern by alternating
72 * between opaque and transparent sections.
73 * </dl>
74 * All attributes that specify measurements and distances controlling
75 * the shape of the returned outline are measured in the same
76 * coordinate system as the original unstroked {@code Shape}
77 * argument. When a {@code Graphics2D} object uses a
78 * {@code Stroke} object to redefine a path during the execution
79 * of one of its {@code draw} methods, the geometry is supplied
80 * in its original form before the {@code Graphics2D} transform
81 * attribute is applied. Therefore, attributes such as the pen width
82 * are interpreted in the user space coordinate system of the
83 * {@code Graphics2D} object and are subject to the scaling and
84 * shearing effects of the user-space-to-device-space transform in that
85 * particular {@code Graphics2D}.
86 * For example, the width of a rendered shape's outline is determined
87 * not only by the width attribute of this {@code BasicStroke},
88 * but also by the transform attribute of the
89 * {@code Graphics2D} object. Consider this code:
90 * <blockquote><pre>{@code
91 * // sets the Graphics2D object's Transform attribute
92 * g2d.scale(10, 10);
93 * // sets the Graphics2D object's Stroke attribute
94 * g2d.setStroke(new BasicStroke(1.5f));
95 * }</pre></blockquote>
96 * Assuming there are no other scaling transforms added to the
97 * {@code Graphics2D} object, the resulting line
98 * will be approximately 15 pixels wide.
99 * As the example code demonstrates, a floating-point line
100 * offers better precision, especially when large transforms are
101 * used with a {@code Graphics2D} object.
102 * When a line is diagonal, the exact width depends on how the
103 * rendering pipeline chooses which pixels to fill as it traces the
104 * theoretical widened outline. The choice of which pixels to turn
105 * on is affected by the antialiasing attribute because the
106 * antialiasing rendering pipeline can choose to color
107 * partially-covered pixels.
108 * <p>
109 * For more information on the user space coordinate system and the
110 * rendering process, see the {@code Graphics2D} class comments.
111 * @see Graphics2D
112 * @author Jim Graham
113 */
114 public class BasicStroke implements Stroke {
115
116 /**
117 * Joins path segments by extending their outside edges until
118 * they meet.
119 */
120 @Native public static final int JOIN_MITER = 0;
121
122 /**
123 * Joins path segments by rounding off the corner at a radius
124 * of half the line width.
125 */
126 @Native public static final int JOIN_ROUND = 1;
127
128 /**
129 * Joins path segments by connecting the outer corners of their
130 * wide outlines with a straight segment.
131 */
132 @Native public static final int JOIN_BEVEL = 2;
133
134 /**
135 * Ends unclosed subpaths and dash segments with no added
136 * decoration.
137 */
138 @Native public static final int CAP_BUTT = 0;
139
140 /**
141 * Ends unclosed subpaths and dash segments with a round
142 * decoration that has a radius equal to half of the width
143 * of the pen.
144 */
145 @Native public static final int CAP_ROUND = 1;
146
147 /**
148 * Ends unclosed subpaths and dash segments with a square
149 * projection that extends beyond the end of the segment
150 * to a distance equal to half of the line width.
151 */
152 @Native public static final int CAP_SQUARE = 2;
153
154 float width;
155
156 int join;
157 int cap;
158 float miterlimit;
159
160 float dash[];
161 float dash_phase;
162
163 /**
164 * Constructs a new {@code BasicStroke} with the specified
165 * attributes.
166 * @param width the width of this {@code BasicStroke}. The
167 * width must be greater than or equal to 0.0f. If width is
168 * set to 0.0f, the stroke is rendered as the thinnest
169 * possible line for the target device and the antialias
170 * hint setting.
171 * @param cap the decoration of the ends of a {@code BasicStroke}
172 * @param join the decoration applied where path segments meet
173 * @param miterlimit the limit to trim the miter join. The miterlimit
174 * must be greater than or equal to 1.0f.
175 * @param dash the array representing the dashing pattern
176 * @param dash_phase the offset to start the dashing pattern
177 * @throws IllegalArgumentException if {@code width} is negative
178 * @throws IllegalArgumentException if {@code cap} is not either
179 * CAP_BUTT, CAP_ROUND or CAP_SQUARE
180 * @throws IllegalArgumentException if {@code miterlimit} is less
181 * than 1 and {@code join} is JOIN_MITER
182 * @throws IllegalArgumentException if {@code join} is not
183 * either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
184 * @throws IllegalArgumentException if {@code dash_phase}
185 * is negative and {@code dash} is not {@code null}
186 * @throws IllegalArgumentException if the length of
187 * {@code dash} is zero
188 * @throws IllegalArgumentException if dash lengths are all zero.
189 */
190 @ConstructorProperties({ "lineWidth", "endCap", "lineJoin", "miterLimit", "dashArray", "dashPhase" })
191 public BasicStroke(float width, int cap, int join, float miterlimit,
192 float dash[], float dash_phase) {
193 if (width < 0.0f) {
194 throw new IllegalArgumentException("negative width");
195 }
196 if (cap != CAP_BUTT && cap != CAP_ROUND && cap != CAP_SQUARE) {
197 throw new IllegalArgumentException("illegal end cap value");
198 }
199 if (join == JOIN_MITER) {
200 if (miterlimit < 1.0f) {
201 throw new IllegalArgumentException("miter limit < 1");
202 }
203 } else if (join != JOIN_ROUND && join != JOIN_BEVEL) {
204 throw new IllegalArgumentException("illegal line join value");
205 }
206 if (dash != null) {
207 if (dash_phase < 0.0f) {
208 throw new IllegalArgumentException("negative dash phase");
209 }
210 boolean allzero = true;
211 for (int i = 0; i < dash.length; i++) {
212 float d = dash[i];
213 if (d > 0.0) {
214 allzero = false;
215 } else if (d < 0.0) {
216 throw new IllegalArgumentException("negative dash length");
217 }
218 }
219 if (allzero) {
220 throw new IllegalArgumentException("dash lengths all zero");
221 }
222 }
223 this.width = width;
224 this.cap = cap;
225 this.join = join;
226 this.miterlimit = miterlimit;
227 if (dash != null) {
228 this.dash = dash.clone();
229 }
230 this.dash_phase = dash_phase;
231 }
232
233 /**
234 * Constructs a solid {@code BasicStroke} with the specified
235 * attributes.
236 * @param width the width of the {@code BasicStroke}
237 * @param cap the decoration of the ends of a {@code BasicStroke}
238 * @param join the decoration applied where path segments meet
239 * @param miterlimit the limit to trim the miter join
240 * @throws IllegalArgumentException if {@code width} is negative
241 * @throws IllegalArgumentException if {@code cap} is not either
242 * CAP_BUTT, CAP_ROUND or CAP_SQUARE
243 * @throws IllegalArgumentException if {@code miterlimit} is less
244 * than 1 and {@code join} is JOIN_MITER
245 * @throws IllegalArgumentException if {@code join} is not
246 * either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
247 */
248 public BasicStroke(float width, int cap, int join, float miterlimit) {
249 this(width, cap, join, miterlimit, null, 0.0f);
250 }
251
252 /**
253 * Constructs a solid {@code BasicStroke} with the specified
254 * attributes. The {@code miterlimit} parameter is
255 * unnecessary in cases where the default is allowable or the
256 * line joins are not specified as JOIN_MITER.
257 * @param width the width of the {@code BasicStroke}
258 * @param cap the decoration of the ends of a {@code BasicStroke}
259 * @param join the decoration applied where path segments meet
260 * @throws IllegalArgumentException if {@code width} is negative
261 * @throws IllegalArgumentException if {@code cap} is not either
262 * CAP_BUTT, CAP_ROUND or CAP_SQUARE
263 * @throws IllegalArgumentException if {@code join} is not
264 * either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
265 */
266 public BasicStroke(float width, int cap, int join) {
267 this(width, cap, join, 10.0f, null, 0.0f);
268 }
269
270 /**
271 * Constructs a solid {@code BasicStroke} with the specified
272 * line width and with default values for the cap and join
273 * styles.
274 * @param width the width of the {@code BasicStroke}
275 * @throws IllegalArgumentException if {@code width} is negative
276 */
277 public BasicStroke(float width) {
278 this(width, CAP_SQUARE, JOIN_MITER, 10.0f, null, 0.0f);
279 }
280
281 /**
282 * Constructs a new {@code BasicStroke} with defaults for all
283 * attributes.
284 * The default attributes are a solid line of width 1.0, CAP_SQUARE,
285 * JOIN_MITER, a miter limit of 10.0.
286 */
287 public BasicStroke() {
288 this(1.0f, CAP_SQUARE, JOIN_MITER, 10.0f, null, 0.0f);
289 }
290
291
292 /**
293 * Returns a {@code Shape} whose interior defines the
294 * stroked outline of a specified {@code Shape}.
295 * @param s the {@code Shape} boundary be stroked
296 * @return the {@code Shape} of the stroked outline.
297 */
298 public Shape createStrokedShape(Shape s) {
299 sun.java2d.pipe.RenderingEngine re =
300 sun.java2d.pipe.RenderingEngine.getInstance();
301 return re.createStrokedShape(s, width, cap, join, miterlimit,
302 dash, dash_phase);
303 }
304
305 /**
306 * Returns the line width. Line width is represented in user space,
307 * which is the default-coordinate space used by Java 2D. See the
308 * {@code Graphics2D} class comments for more information on
309 * the user space coordinate system.
310 * @return the line width of this {@code BasicStroke}.
311 * @see Graphics2D
312 */
313 public float getLineWidth() {
314 return width;
315 }
316
317 /**
318 * Returns the end cap style.
319 * @return the end cap style of this {@code BasicStroke} as one
320 * of the static {@code int} values that define possible end cap
321 * styles.
322 */
323 public int getEndCap() {
324 return cap;
325 }
326
327 /**
328 * Returns the line join style.
329 * @return the line join style of the {@code BasicStroke} as one
330 * of the static {@code int} values that define possible line
331 * join styles.
332 */
333 public int getLineJoin() {
334 return join;
335 }
336
337 /**
338 * Returns the limit of miter joins.
339 * @return the limit of miter joins of the {@code BasicStroke}.
340 */
341 public float getMiterLimit() {
342 return miterlimit;
343 }
344
345 /**
346 * Returns the array representing the lengths of the dash segments.
347 * Alternate entries in the array represent the user space lengths
348 * of the opaque and transparent segments of the dashes.
349 * As the pen moves along the outline of the {@code Shape}
350 * to be stroked, the user space
351 * distance that the pen travels is accumulated. The distance
352 * value is used to index into the dash array.
353 * The pen is opaque when its current cumulative distance maps
354 * to an even element of the dash array and transparent otherwise.
355 * @return the dash array.
356 */
357 public float[] getDashArray() {
358 if (dash == null) {
359 return null;
360 }
361
362 return dash.clone();
363 }
364
365 /**
366 * Returns the current dash phase.
367 * The dash phase is a distance specified in user coordinates that
368 * represents an offset into the dashing pattern. In other words, the dash
369 * phase defines the point in the dashing pattern that will correspond to
370 * the beginning of the stroke.
371 * @return the dash phase as a {@code float} value.
372 */
373 public float getDashPhase() {
374 return dash_phase;
375 }
376
377 /**
378 * Returns the hashcode for this stroke.
379 * @return a hash code for this stroke.
380 */
381 public int hashCode() {
382 int hash = Float.floatToIntBits(width);
383 hash = hash * 31 + join;
384 hash = hash * 31 + cap;
385 hash = hash * 31 + Float.floatToIntBits(miterlimit);
386 if (dash != null) {
387 hash = hash * 31 + Float.floatToIntBits(dash_phase);
388 for (int i = 0; i < dash.length; i++) {
389 hash = hash * 31 + Float.floatToIntBits(dash[i]);
390 }
391 }
392 return hash;
393 }
394
395 /**
396 * Returns true if this BasicStroke represents the same
397 * stroking operation as the given argument.
398 */
399 /**
400 * Tests if a specified object is equal to this {@code BasicStroke}
401 * by first testing if it is a {@code BasicStroke} and then comparing
402 * its width, join, cap, miter limit, dash, and dash phase attributes with
403 * those of this {@code BasicStroke}.
404 * @param obj the specified object to compare to this
405 * {@code BasicStroke}
406 * @return {@code true} if the width, join, cap, miter limit, dash, and
407 * dash phase are the same for both objects;
408 * {@code false} otherwise.
409 */
410 public boolean equals(Object obj) {
411 if (!(obj instanceof BasicStroke)) {
412 return false;
413 }
414
415 BasicStroke bs = (BasicStroke) obj;
416 if (width != bs.width) {
417 return false;
418 }
419
420 if (join != bs.join) {
421 return false;
422 }
423
424 if (cap != bs.cap) {
425 return false;
426 }
427
428 if (miterlimit != bs.miterlimit) {
429 return false;
430 }
431
432 if (dash != null) {
433 if (dash_phase != bs.dash_phase) {
434 return false;
435 }
436
437 if (!java.util.Arrays.equals(dash, bs.dash)) {
438 return false;
439 }
440 }
441 else if (bs.dash != null) {
442 return false;
443 }
444
445 return true;
446 }
447 }
448