From 13f0eec948b71c2bcc529139526668aa3be6611f Mon Sep 17 00:00:00 2001 From: "valery.bokov" Date: Mon, 27 Jul 2026 18:09:12 +0200 Subject: [PATCH 1/2] PDFBOX-6077: combine stencil mask alpha with the pattern's own alpha A stencil image filled with a pattern draws the paint and the mask into separate scratch images and then combines them. The combine step unconditionally overwrote the paint's alpha with the mask's alpha, so any pixel the pattern itself never painted into (e.g. the gaps between tiles of a tiling pattern) turned opaque black instead of staying transparent. Co-Authored-By: Claude Sonnet 5 --- .../main/java/org/apache/pdfbox/rendering/PageDrawer.java | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/pdfbox/src/main/java/org/apache/pdfbox/rendering/PageDrawer.java b/pdfbox/src/main/java/org/apache/pdfbox/rendering/PageDrawer.java index 7374b404b5f..10279fb7032 100644 --- a/pdfbox/src/main/java/org/apache/pdfbox/rendering/PageDrawer.java +++ b/pdfbox/src/main/java/org/apache/pdfbox/rendering/PageDrawer.java @@ -1225,7 +1225,11 @@ else if (scaleX != 0 && scaleY != 0) { alphaPixel = alpha.getPixel(x, y, alphaPixel); rasterPixel = raster.getPixel(x, y, rasterPixel); - rasterPixel[3] = alphaPixel[0]; + // PDFBOX-6077: combine with the paint's own alpha instead of + // overwriting it, so gaps the paint never drew into (e.g. between + // tiles of a tiling pattern) stay transparent instead of turning + // into opaque black. + rasterPixel[3] = rasterPixel[3] * alphaPixel[0] / 255; raster.setPixel(x, y, rasterPixel); } } From 0189b278b5c440bee1e9d50441d5f10a9709e1d1 Mon Sep 17 00:00:00 2001 From: "valery.bokov" Date: Mon, 27 Jul 2026 18:12:14 +0200 Subject: [PATCH 2/2] PDFBOX-6077: fix soft-masked patterns used as a stencil mask fill A soft mask's Paint/PaintContext looks up its backing raster using absolute page-device pixel coordinates, fixed when the soft mask group was rendered. The stencil-mask-with-pattern code renders into an isolated scratch image rather than directly onto the page graphics, so those coordinates no longer lined up and the soft mask silently applied zero alpha everywhere, making the pattern disappear. Unwrap the soft mask, fill the scratch image with its plain underlying paint instead, and apply the soft mask's own alpha afterwards by directly looking up its backing raster through a per-pixel device transform, rather than relying on the Paint/PaintContext machinery that assumed it was rendering onto the real page raster. Co-Authored-By: Claude Sonnet 5 --- .../apache/pdfbox/rendering/PageDrawer.java | 88 ++++++++++++++++++- .../org/apache/pdfbox/rendering/SoftMask.java | 29 ++++++ 2 files changed, 116 insertions(+), 1 deletion(-) diff --git a/pdfbox/src/main/java/org/apache/pdfbox/rendering/PageDrawer.java b/pdfbox/src/main/java/org/apache/pdfbox/rendering/PageDrawer.java index 10279fb7032..93a50e380f9 100644 --- a/pdfbox/src/main/java/org/apache/pdfbox/rendering/PageDrawer.java +++ b/pdfbox/src/main/java/org/apache/pdfbox/rendering/PageDrawer.java @@ -1135,6 +1135,15 @@ public void drawImage(PDImage pdImage) throws IOException // draw the paint Paint paint = getNonStrokingPaint(); + // PDFBOX-6077: a soft mask's Paint/PaintContext machinery (see + // applySoftMaskToPaint()) assumes it is asked to render directly onto the real + // page raster, using its own cached absolute page-device coordinates. This + // stencil-mask-with-pattern case instead renders into an isolated scratch image + // (see the note above about "device scale is not used"), so unwrap any soft mask + // here, fill with the plain underlying paint below, and apply the soft mask's own + // alpha afterwards by directly looking up its backing raster (applySoftMaskAlpha). + SoftMask softMask = paint instanceof SoftMask ? (SoftMask) paint : null; + Paint innerPaint = softMask != null ? softMask.getPaint() : paint; Rectangle2D unitRect = new Rectangle2D.Float(0, 0, 1, 1); Rectangle2D bounds = at.createTransformedShape(unitRect).getBounds2D(); int w = (int) Math.ceil(bounds.getWidth()); @@ -1142,11 +1151,16 @@ public void drawImage(PDImage pdImage) throws IOException BufferedImage renderedPaint = new BufferedImage(w, h, BufferedImage.TYPE_INT_ARGB); Graphics2D g = (Graphics2D) renderedPaint.getGraphics(); g.translate(-bounds.getMinX(), -bounds.getMinY()); - g.setPaint(paint); + g.setPaint(innerPaint); g.setRenderingHints(graphics.getRenderingHints()); g.fill(bounds); g.dispose(); + if (softMask != null) + { + applySoftMaskAlpha(renderedPaint, bounds, softMask); + } + // draw the mask BufferedImage mask = pdImage.getImage(); AffineTransform imageTransform = new AffineTransform(at); @@ -1271,6 +1285,78 @@ else if (scaleX != 0 && scaleY != 0) } } + /** + * PDFBOX-6077: applies a soft mask's alpha directly to "image", which was filled with the + * soft mask's underlying paint but not yet masked by it. This re-implements + * {@link SoftMask}'s own alpha lookup (see its SoftPaintContext.getRaster()) rather than + * relying on the Paint/PaintContext machinery, because "image" is a small scratch buffer - + * not the real page raster that the soft mask's absolute device coordinates are relative to + * - and unlike a plain coordinate offset, transforming each pixel individually stays correct + * even though this scratch buffer isn't rendered at the page's actual device scale (see the + * "device scale is not used" note where this method is called from). + * + * @param image the ARGB image to apply the soft mask's alpha to, in place. + * @param bounds the device-independent bounds (see "at" in drawImage()) that image's pixel + * (0, 0) to (image.getWidth(), image.getHeight()) covers. + * @param softMask the soft mask to apply. + */ + private void applySoftMaskAlpha(BufferedImage image, Rectangle2D bounds, SoftMask softMask) throws IOException + { + AffineTransform deviceTransform = graphics.getTransform(); + Raster maskRaster = softMask.getMask().getRaster(); + Rectangle2D bboxDevice = softMask.getBBoxDevice(); + int backdropColorValue = softMask.getBackdropColorValue(); + PDFunction transferFunction = softMask.getTransferFunction(); + Float[] map = transferFunction != null ? new Float[256] : null; + float[] input = transferFunction != null ? new float[1] : null; + + WritableRaster raster = image.getRaster(); + int width = image.getWidth(); + int height = image.getHeight(); + Point2D.Double point = new Point2D.Double(); + int[] gray = new int[1]; + int[] rasterPixel = null; + for (int y = 0; y < height; y++) + { + for (int x = 0; x < width; x++) + { + point.setLocation(bounds.getMinX() + x, bounds.getMinY() + y); + deviceTransform.transform(point, point); + int maskX = (int) Math.floor(point.getX() - bboxDevice.getX()); + int maskY = (int) Math.floor(point.getY() - bboxDevice.getY()); + + int alphaScale; + if (maskX >= 0 && maskY >= 0 && maskX < maskRaster.getWidth() && maskY < maskRaster.getHeight()) + { + maskRaster.getPixel(maskX, maskY, gray); + if (transferFunction != null) + { + Float f = map[gray[0]]; + if (f == null) + { + input[0] = gray[0] / 255f; + f = transferFunction.eval(input)[0]; + map[gray[0]] = f; + } + alphaScale = Math.round(255 * f); + } + else + { + alphaScale = gray[0]; + } + } + else + { + alphaScale = backdropColorValue; + } + + rasterPixel = raster.getPixel(x, y, rasterPixel); + rasterPixel[3] = rasterPixel[3] * alphaScale / 255; + raster.setPixel(x, y, rasterPixel); + } + } + } + /** * Calculates the subsampling frequency for a given PDImage based on the current transformation * and its calculated transform. Extend this method if you want to use your own strategy. diff --git a/pdfbox/src/main/java/org/apache/pdfbox/rendering/SoftMask.java b/pdfbox/src/main/java/org/apache/pdfbox/rendering/SoftMask.java index 4dbc5da8c1e..3ddc031faee 100644 --- a/pdfbox/src/main/java/org/apache/pdfbox/rendering/SoftMask.java +++ b/pdfbox/src/main/java/org/apache/pdfbox/rendering/SoftMask.java @@ -98,6 +98,35 @@ class SoftMask implements Paint } } + // PDFBOX-6077: accessors used by PageDrawer to re-implement this soft mask's alpha lookup + // directly (with its own, correctly-scaled device coordinates) when this Paint is rendered + // into a scratch image that isn't the real page raster, e.g. for a stencil mask filled with + // a pattern. + Paint getPaint() + { + return paint; + } + + BufferedImage getMask() + { + return mask; + } + + Rectangle2D getBBoxDevice() + { + return bboxDevice; + } + + int getBackdropColorValue() + { + return bc; + } + + PDFunction getTransferFunction() + { + return transferFunction; + } + @Override public PaintContext createContext(ColorModel cm, Rectangle deviceBounds, Rectangle2D userBounds, AffineTransform xform,