Linear gradient logic

Implementation of linear gradient builders for low level build and strategy based build. Add background image support for linear gradient for layout module. Add css parsing of linear gradient. Base svg implementation of linear gradient parsing and using for most types of svg objects.

DEVSIX-2086

Author: BezrukovM

io/src/main/java/com/itextpdf/io/LogMessageConstant.java

@@ -188,6 +188,7 @@ public final class LogMessageConstant {
     public static final String TOUNICODE_CMAP_MORE_THAN_2_BYTES_NOT_SUPPORTED = "ToUnicode CMap more than 2 bytes not supported.";
     public static final String TYPE3_FONT_CANNOT_BE_ADDED = "Type 3 font cannot be added to FontSet. Custom FontProvider class may be created for this purpose.";
     public static final String TYPE3_FONT_ISSUE_TAGGED_PDF = "Type 3 font issue. Font Descriptor is required for tagged PDF. FontName shall be specified.";
+    public static final String UNABLE_TO_INVERT_GRADIENT_TRANSFORMATION = "Unable to invert gradient transformation, ignoring it";
     public static final String UNABLE_TO_APPLY_PAGE_DEPENDENT_PROP_UNKNOWN_PAGE_ON_WHICH_ELEMENT_IS_DRAWN = "Unable to apply page dependent property, because the page on which element is drawn is unknown. Usually this means that element was added to the Canvas instance that was created not with constructor taking PdfPage as argument. Not processed property: {0}";
     public static final String UNABLE_TO_REGISTER_EVENT_DATA_HANDLER_SHUTDOWN_HOOK = "Unable to register event data handler shutdown hook because of security reasons.";
     public static final String UNABLE_TO_SEARCH_FOR_EVENT_CONTEXT = "It is impossible to retrieve event context because of the security reasons. Event counting may behave in unexpected way";

kernel/src/main/java/com/itextpdf/kernel/colors/gradients/AbstractLinearGradientBuilder.java

@@ -0,0 +1,231 @@
+package com.itextpdf.kernel.colors.gradients;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+/**
+ * The gradient stop color structure representing the stop color configuration.
+ * The stop color consists of:
+ * - {@code float[]} rgb color array. Values should be in [0, 1] range. All values outside of
+ * this range would be adjusted to the nearest corner of the range.
+ * - {@code double} offset and {@link OffsetType} offset type specifies the coordinate of
+ * the stop color on the targeting gradient coordinates vector
+ * - {@code double} hint offset and {@link HintOffsetType} hint offset type specifies the color
+ * transition mid point offset between the current color and the next color
+ */
+public class GradientColorStop {
+    private final float[] rgb;
+    private final float opacity;
+
+    private OffsetType offsetType;
+    private double offset;
+    private double hintOffset = 0d;
+    private HintOffsetType hintOffsetType = HintOffsetType.NONE;
+
+    /**
+     * Constructor of stop color with with specified rgb color and default ({@link OffsetType#AUTO})
+     * offset
+     *
+     * @param rgb the color value
+     */
+    public GradientColorStop(float[] rgb) {
+        this(rgb, 1f, 0d, OffsetType.AUTO);
+    }
+
+    /**
+     * Constructor of stop color with with specified rgb color and offset
+     *
+     * @param rgb        the color value
+     * @param offset     the offset value. Makes sense only if the {@code offsetType} is not {@link OffsetType#AUTO}
+     * @param offsetType the offset's type
+     */
+    public GradientColorStop(float[] rgb, double offset, OffsetType offsetType) {
+        this(rgb, 1f, offset, offsetType);
+    }
+
+    /**
+     * Constructor that creates the stop with the same color as the another stop and new offset
+     *
+     * @param gradientColorStop the gradient stop color from which the color value would be copied
+     * @param offset            the new offset. Makes sense only if the {@code offsetType} is not {@link OffsetType#AUTO}
+     * @param offsetType        the new offset's type
+     */
+    public GradientColorStop(GradientColorStop gradientColorStop, double offset, OffsetType offsetType) {
+        this(gradientColorStop.getRgbArray(), gradientColorStop.getOpacity(), offset, offsetType);
+    }
+
+    private GradientColorStop(float[] rgb, float opacity, double offset, OffsetType offsetType) {
+        this.rgb = copyRgbArray(rgb);
+
+        this.opacity = normalize(opacity);
+
+        setOffset(offset, offsetType);
+    }
+
+    /**
+     * Get the stop color rgb value
+     *
+     * @return the copy of stop's rgb value
+     */
+    public float[] getRgbArray() {
+        return copyRgbArray(this.rgb);
+    }
+
+    // TODO: DEVSIX-4136 make public with opacity logic implementation
+    /**
+     * Get the stop color opacity value
+     *
+     * @return the stop color opacity value
+     */
+    private float getOpacity() {
+        return this.opacity;
+    }
+
+    /**
+     * Get the offset type
+     *
+     * @return the offset type
+     */
+    public OffsetType getOffsetType() {
+        return offsetType;
+    }
+
+    /**
+     * Get the offset value
+     *
+     * @return the offset value
+     */
+    public double getOffset() {
+        return this.offset;
+    }
+
+    /**
+     * Get the hint offset value
+     *
+     * @return the hint offset value
+     */
+    public double getHintOffset() {
+        return hintOffset;
+    }
+
+    /**
+     * Get the hint offset type
+     *
+     * @return the hint offset type
+     */
+    public HintOffsetType getHintOffsetType() {
+        return hintOffsetType;
+    }
+
+    /**
+     * Set the offset specified by its value and type
+     *
+     * @param offset     the offset's value to be set. Makes sense only if the {@code offsetType}
+     *                   is not {@link OffsetType#AUTO}
+     * @param offsetType the offset's type to be set
+     * @return the current {@link GradientColorStop} instance
+     */
+    public GradientColorStop setOffset(double offset, OffsetType offsetType) {
+        this.offsetType = offsetType != null ? offsetType : OffsetType.AUTO;
+        this.offset = this.offsetType != OffsetType.AUTO ? offset : 0d;
+        return this;
+    }
+
+    /**
+     * Set the color hint specified by its value and type ({@link GradientColorStop more details}).
+     *
+     * @param hintOffset     the hint offset's value to be set. Makes sense only
+     *                       if the {@code hintOffsetType} is not {@link HintOffsetType#NONE}
+     * @param hintOffsetType the hint offset's type to be set
+     * @return the current {@link GradientColorStop} instance
+     */
+    public GradientColorStop setHint(double hintOffset, HintOffsetType hintOffsetType) {
+        this.hintOffsetType = hintOffsetType != null ? hintOffsetType : HintOffsetType.NONE;
+        this.hintOffset = this.hintOffsetType != HintOffsetType.NONE ? hintOffset : 0d;
+        return this;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        GradientColorStop that = (GradientColorStop) o;
+        return Float.compare(that.opacity, opacity) == 0 &&
+                Double.compare(that.offset, offset) == 0 &&
+                Double.compare(that.hintOffset, hintOffset) == 0 &&
+                Arrays.equals(rgb, that.rgb) &&
+                offsetType == that.offsetType &&
+                hintOffsetType == that.hintOffsetType;
+    }
+
+    @Override
+    public int hashCode() {
+        int result = Objects.hash(opacity, offset, hintOffset);
+        result = 31 * result + offsetType.hashCode();
+        result = 31 * result + hintOffsetType.hashCode();
+        result = 31 * result + Arrays.hashCode(rgb);
+        return result;
+    }
+
+    private static float normalize(float toNormalize) {
+        return toNormalize > 1f ? 1f : toNormalize > 0f ? toNormalize : 0f;
+    }
+
+    private static float[] copyRgbArray(float[] toCopy) {
+        if (toCopy == null || toCopy.length < 3) {
+            return new float[] {0f, 0f, 0f};
+        }
+        return new float[] {normalize(toCopy[0]), normalize(toCopy[1]), normalize(toCopy[2])};
+    }
+
+    /**
+     * Represents the possible offset type
+     */
+    public enum OffsetType {
+        /**
+         * The absolute offset value from the target coordinates vector's start
+         */
+        ABSOLUTE,
+        /**
+         * The automatic offset evaluation. The offset value should be evaluated automatically
+         * based on the whole stop colors list specified for the gradient. The general auto offset
+         * logic should be the next:
+         * - find the previous and the next specified offset or hint offset values
+         * - the sublist of sequent auto offsets should spread evenly between the found values
+         */
+        AUTO,
+        /**
+         * The relative offset value to the target coordinates vector. The {@code 0} value means
+         * the target vector start, the {@code 1} value means the target vector end.
+         */
+        RELATIVE
+    }
+
+    /**
+     * Represents the possible hint offset type
+     */
+    public enum HintOffsetType {
+        /**
+         * The absolute hint offset value on the target gradient value
+         */
+        ABSOLUTE_ON_GRADIENT,
+        /**
+         * The relative hint offset value to the target coordinates vector. The {@code 0} value
+         * means the target vector start, the {@code 1} value means the target vector end.
+         */
+        RELATIVE_ON_GRADIENT,
+        /**
+         * The relative hint offset value to the interval between the current gradient stop color
+         * and the next one.
+         */
+        RELATIVE_BETWEEN_COLORS,
+        /**
+         * None hint offset specified
+         */
+        NONE
+    }
+}

kernel/src/main/java/com/itextpdf/kernel/colors/gradients/GradientColorStop.java

@@ -0,0 +1,23 @@
+package com.itextpdf.kernel.colors.gradients;
+
+/**
+ * Represents possible spreading methods for gradient color outside of the coordinates vector
+ */
+public enum GradientSpreadMethod {
+    /**
+     * Pad the corner colors to fill the necessary area
+     */
+    PAD,
+    /**
+     * Reflect the coloring to fill the necessary area
+     */
+    REFLECT,
+    /**
+     * Repeat the coloring to fill the necessary area
+     */
+    REPEAT,
+    /**
+     * No coloring outside of the coordinates vector
+     */
+    NONE
+}

kernel/src/main/java/com/itextpdf/kernel/colors/gradients/GradientSpreadMethod.java

@@ -0,0 +1,63 @@
+package com.itextpdf.kernel.colors.gradients;
+
+import com.itextpdf.kernel.geom.AffineTransform;
+import com.itextpdf.kernel.geom.Point;
+import com.itextpdf.kernel.geom.Rectangle;
+
+/**
+ * The linear gradient builder implementation with direct target gradient vector
+ * and shading transformation ({@link AbstractLinearGradientBuilder more info})
+ */
+public class LinearGradientBuilder extends AbstractLinearGradientBuilder {
+
+    private final Point[] coordinates = new Point[] {new Point(), new Point()};
+    private AffineTransform transformation = null;
+
+    /**
+     * Constructs the builder instance
+     */
+    public LinearGradientBuilder() {
+    }
+
+    /**
+     * Set coordinates for gradient vector ({@link AbstractLinearGradientBuilder more info})
+     *
+     * @param x0 the x coordinate of the vector start
+     * @param y0 the y coordinate of the vector start
+     * @param x1 the x coordinate of the vector end
+     * @param y1 the y coordinate of the vector end
+     * @return the current builder instance
+     */
+    public LinearGradientBuilder setGradientVector(double x0, double y0, double x1, double y1) {
+        this.coordinates[0].setLocation(x0, y0);
+        this.coordinates[1].setLocation(x1, y1);
+        return this;
+    }
+
+    /**
+     * Set the linear gradient space transformation which specifies the transformation from
+     * the current coordinates space to gradient vector space
+     * <p>
+     * The current space is the one on which linear gradient will be drawn (as a fill or stroke
+     * color for shapes on PDF canvas). This transformation mainly used for color lines skewing.
+     *
+     * @param transformation the {@link AffineTransform} representing the transformation to set
+     * @return the current builder instance
+     */
+    public LinearGradientBuilder setCurrentSpaceToGradientVectorSpaceTransformation(
+            AffineTransform transformation) {
+        this.transformation = transformation;
+        return this;
+    }
+
+    @Override
+    public Point[] getGradientVector(Rectangle targetBoundingBox, AffineTransform contextTransform) {
+        return this.coordinates;
+    }
+
+    @Override
+    public AffineTransform getCurrentSpaceToGradientVectorSpaceTransformation(
+            Rectangle targetBoundingBox, AffineTransform contextTransform) {
+        return this.transformation;
+    }
+}