From c48af5acc7bb302325d025109902844313772fed Mon Sep 17 00:00:00 2001 From: Harald Kuhr Date: Wed, 22 Jan 2020 20:35:41 +0100 Subject: [PATCH] #490: Minor API clean-up and documentation. --- .../imageio/path/AdobePathReader.java | 2 +- .../imageio/path/AdobePathWriter.java | 31 +++++++++++++------ .../com/twelvemonkeys/imageio/path/Paths.java | 9 ++++-- 3 files changed, 30 insertions(+), 12 deletions(-) diff --git a/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/AdobePathReader.java b/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/AdobePathReader.java index fefc07c5..88e24d6e 100755 --- a/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/AdobePathReader.java +++ b/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/AdobePathReader.java @@ -44,7 +44,7 @@ import static com.twelvemonkeys.lang.Validate.isTrue; import static com.twelvemonkeys.lang.Validate.notNull; /** - * Creates a {@code Shape} object from an Adobe Photoshop Path resource. + * Reads a {@code Shape} object from an Adobe Photoshop Path resource. * * @see Adobe Photoshop Path resource format * @author Jason Palmer, itemMaster LLC diff --git a/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/AdobePathWriter.java b/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/AdobePathWriter.java index f3f01baf..b7916e31 100755 --- a/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/AdobePathWriter.java +++ b/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/AdobePathWriter.java @@ -49,7 +49,10 @@ import static com.twelvemonkeys.lang.Validate.isTrue; import static com.twelvemonkeys.lang.Validate.notNull; /** - * AdobePathWriter + * Writes a {@code Shape} object to an Adobe Photoshop Path or Path resource. + * + * @see Adobe Photoshop Path resource format + * @author Harald Kuhr */ public final class AdobePathWriter { @@ -181,14 +184,15 @@ public final class AdobePathWriter { } /** - * Writes the path as a complete Photoshop clipping path resource to the given stream. + * Writes the path as a complete Adobe Photoshop clipping path resource to the given stream. * * @param output the stream to write to. + * @param resourceId the resource id, typically {@link PSD#RES_CLIPPING_PATH} (0x07D0). * @throws IOException if an I/O exception happens during writing. */ - void writePathResource(final DataOutput output) throws IOException { + public void writePathResource(final DataOutput output, int resourceId) throws IOException { output.writeInt(PSD.RESOURCE_TYPE); - output.writeShort(PSD.RES_CLIPPING_PATH); + output.writeShort(resourceId); output.writeShort(0); // Path name (Pascal string) empty + pad output.writeInt(segments.size() * 26); // Resource size @@ -196,7 +200,7 @@ public final class AdobePathWriter { } /** - * Writes the path as a set of Adobe path segments to the given stream. + * Writes the path as a set of Adobe Photoshop path segments to the given stream. * * @param output the stream to write to. * @throws IOException if an I/O exception happens during writing. @@ -235,13 +239,17 @@ public final class AdobePathWriter { } } - // TODO: Do we need to care about endianness for TIFF files? - // TODO: Better name? - byte[] writePathResource() { + /** + * Transforms the path to a byte array, containing a complete Adobe Photoshop path resource. + * + * @param resourceId the resource id, typically {@link PSD#RES_CLIPPING_PATH} (0x07D0). + * @return a new byte array, containing the clipping path resource. + */ + public byte[] writePathResource(int resourceId) { ByteArrayOutputStream bytes = new ByteArrayOutputStream(); try (DataOutputStream stream = new DataOutputStream(bytes)) { - writePathResource(stream); + writePathResource(stream, resourceId); } catch (IOException e) { throw new AssertionError("ByteArrayOutputStream threw IOException", e); @@ -250,6 +258,11 @@ public final class AdobePathWriter { return bytes.toByteArray(); } + /** + * Transforms the path to a byte array, containing a set of Adobe Photoshop path segments. + * + * @return a new byte array, containing the path segments. + */ public byte[] writePath() { ByteArrayOutputStream bytes = new ByteArrayOutputStream(); diff --git a/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/Paths.java b/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/Paths.java index ce95a4f8..6e908def 100755 --- a/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/Paths.java +++ b/imageio/imageio-clippath/src/main/java/com/twelvemonkeys/imageio/path/Paths.java @@ -260,7 +260,7 @@ public final class Paths { } /** - * Writes the image along with a clipping path resource, in the given format to the supplied output. + * Writes the image along with a clipping path resource, in the given format, to the supplied output. * The image is written to the * {@code ImageOutputStream} starting at the current stream * pointer, overwriting existing stream data from that point @@ -270,6 +270,11 @@ public final class Paths { * not close the output stream. * It is the responsibility of the caller to close the stream, if desired. *

+ *

+ * Implementation note: Only JPEG (using the "javax_imageio_jpeg_image_1.0" metadata format) and + * TIFF (using the "javax_imageio_tiff_image_1.0" or "com_sun_media_imageio_plugins_tiff_image_1.0" metadata formats) + * formats are currently supported. + *

* * @param image the image to be written, may not be {@code null}. * @param clipPath the clip path, may not be {@code null}. @@ -303,7 +308,7 @@ public final class Paths { IIOMetadata metadata = writer.getDefaultImageMetadata(type, param); List metadataFormats = asList(metadata.getMetadataFormatNames()); - byte[] pathResource = new AdobePathWriter(clipPath).writePathResource(); + byte[] pathResource = new AdobePathWriter(clipPath).writePathResource(PSD.RES_CLIPPING_PATH); if (metadataFormats.contains("javax_imageio_tiff_image_1.0") || metadataFormats.contains("com_sun_media_imageio_plugins_tiff_image_1.0")) { param.setCompressionMode(ImageWriteParam.MODE_EXPLICIT);