Package icyllis.arc3d.sketch

Class Paint

java.lang.Object
icyllis.arc3d.sketch.Paint
All Implemented Interfaces:
AutoCloseable
public class Paint extends Object implements AutoCloseable
Paint controls options applied when drawing. Paint collects all options outside the Canvas clip and Canvas matrix, such as style and color information, applied to geometries and images.

Paint collects effects and filters that describe single-pass and multiple-pass algorithms that alter the drawing geometry, color, and transparency. For instance, Paint does not directly implement dashing or blur, but contains the objects that do so.

A Paint object must be closed or reset if it has Shader, ColorFilter, or Blender installed.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Paint.Align
    The Align specifies the treatment where the stroke is placed in relation to the object edge, this only applies to closed contours.
    static @interface 
    Paint.Cap
    The Cap specifies the treatment for the beginning and ending of stroked lines and paths.
    static @interface 
    Paint.Join
    The Join specifies the treatment where lines and curve segments join on a stroked path.
    static @interface 
    Paint.Style
    Set Style to fill, stroke, or both fill and stroke geometry.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    ALIGN_CENTER
    The stroke is aligned to center.
    static final int
    ALIGN_COUNT
    The number of align types.
    static final int
    ALIGN_INSIDE
    The stroke is aligned to inside.
    static final int
    ALIGN_OUTSIDE
    The stroke is aligned to outside.
    static final int
    CAP_BUTT
    The stroke ends with the path, and does not project beyond it.
    static final int
    CAP_COUNT
    The number of cap types.
    static final int
    CAP_ROUND
    The stroke projects out as a semicircle, with the center at the end of the path.
    static final int
    CAP_SQUARE
    The stroke projects out as a square, with the center at the end of the path.
    static final int
    FILL
    Geometry drawn with this style will be filled, ignoring all stroke-related settings in the paint.
    static final int
    FILL_AND_STROKE
     
    static final int
    JOIN_BEVEL
    The outer edges of a join meet with a straight line
    static final int
    JOIN_COUNT
    The number of join types.
    static final int
    JOIN_MITER
    The outer edges of a join meet at a sharp angle
    static final int
    JOIN_ROUND
    The outer edges of a join meet in a circular arc.
    static final int
    STROKE
    Geometry drawn with this style will be stroked, respecting the stroke-related fields on the paint.
    static final int
    STROKE_AND_FILL
    Geometry (path) drawn with this style will be both filled and stroked at the same time, respecting the stroke-related fields on the paint.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Paint()
    Creates a new Paint with defaults.
    Paint(@Nullable Paint paint)
    Create a new paint, initialized with the attributes in the specified paint parameter.

  • Method Summary

    Modifier and Type
    Method
    Description
    final float
    a()
    Returns the value of the alpha component.
    final float
    b()
    Returns the value of the blue component.
    final boolean
    canComputeFastBounds(@RawPtr @Nullable ImageFilter imageFilter)
    Returns true if Paint does not include elements requiring extensive computation to compute BaseDevice bounds of drawn geometry.
    void
    close()
     
    final void
    computeFastBounds(@RawPtr @Nullable ImageFilter imageFilter, Rect2fc orig, Rect2f storage)
    Only call this if canComputeFastBounds() returned true.
    protected final boolean
    equals(Paint paint)
     
    boolean
    equals(Object o)
     
    final float
    g()
    Returns the value of the green component.
    int
    getAlpha()
    Helper to getColor() that just returns the color's alpha value.
    static int
    getAlphaDirect(@Nullable Paint paint)
     
    float
    getAlphaF()
    Retrieves alpha/opacity from the color used when stroking and filling.
    final @Nullable Blender
    getBlender()
    Returns the user-supplied blend function, if one has been set.
    @Nullable BlendMode
    getBlendMode()
    If the current blender can be represented as a BlendMode enum, this returns that enum object.
    static BlendMode
    getBlendModeDirect(@Nullable Paint paint)
     
    int
    getColor()
    Return the paint's solid color in sRGB.
    final void
    getColor4f(float @NonNull [] dst)
    Returns the color used when stroking and filling.
    @Nullable ColorFilter
    getColorFilter()
    Returns ColorFilter if set, or null.
    final PathEffect
    getPathEffect()
    Returns PathEffect if set, or null.
    @Nullable @RawPtr Shader
    getShader()
    Returns optional colors used when filling a path, such as a gradient.
    final int
    getStrokeAlign()
    Returns the paint's stroke align type.
    int
    getStrokeCap()
    Returns the paint's cap type, controlling how the start and end of stroked lines and paths are treated, except where noted.
    int
    getStrokeJoin()
    Returns the paint's stroke join type.
    float
    getStrokeMiter()
    Returns the miter limit at which a sharp corner is drawn beveled.
    float
    getStrokeWidth()
    Returns the thickness of the pen for stroking shapes.
    int
    getStyle()
    Returns the paint's style, used for controlling how primitives' geometries are interpreted, except where noted.
    int
    hashCode()
     
    final boolean
    isAntiAlias()
    Returns true if antialiasing should be used.
    static boolean
    isBlendedColorFilter(@Nullable ColorFilter filter)
     
    static boolean
    isBlendedImageFilter(@Nullable ImageFilter filter)
     
    static boolean
    isBlendedShader(@Nullable Shader shader)
     
    final boolean
    isDither()
    Returns true if color error may be distributed to smooth color transition.
    static boolean
    isOpaquePaint(@Nullable Paint paint)
     
    final boolean
    isSrcOver()
    Returns true if BlendMode claims to be equivalent to BlendMode.SRC_OVER, the default.
    boolean
    nothingToDraw()
    Returns true if the paint prevents all drawing; otherwise, the paint may or may not allow drawing.
    final float
    r()
    Returns the value of the red component.
    @Nullable @SharedPtr Shader
    refShader()
    Returns optional colors used when filling a path, such as a gradient.
    void
    reset()
    Set all contents of this paint to their initial values.
    void
    set(Paint paint)
    Set all contents of this paint from the specified paint.
    void
    setAlpha(int a)
    Helper to setColor(), that only assigns the color's alpha value, leaving its r,g,b values unchanged.
    void
    setAlphaF(float a)
    Replaces alpha, leaving RGB unchanged.
    final void
    setAntiAlias(boolean aa)
    Sets a hint that indicates if antialiasing should be used.
    void
    setARGB(int a, int r, int g, int b)
    Sets color used when drawing solid fills.
    final void
    setBlender(@Nullable Blender blender)
    Sets the current blender.
    void
    setBlendMode(@Nullable BlendMode mode)
    Helper method for calling setBlender().
    void
    setColor(int color)
    Set the paint's solid color in sRGB.
    final void
    setColor4f(float r, float g, float b, float a)
    Sets alpha and RGB used when stroking and filling.
    final void
    setColor4f(float r, float g, float b, float a, @Nullable ColorSpace colorSpace)
    Sets alpha and RGB used when stroking and filling.
    void
    setColorFilter(@Nullable ColorFilter colorFilter)
    Sets ColorFilter to filter, pass null to clear ColorFilter.
    final void
    setDither(boolean dither)
    Sets a hint that indicates if color error may be distributed to smooth color transition.
    final void
    setPathEffect(@Nullable PathEffect pathEffect)
    Sets PathEffect to pathEffect.
    final void
    setRGB(int r, int g, int b)
    Helper to setColor(), that only assigns the color's r,g,b values, leaving its alpha value unchanged.
    final void
    setRGBA(int r, int g, int b, int a)
    Sets color used when drawing solid fills.
    void
    setShader(@Nullable @SharedPtr Shader shader)
    Sets optional colors used when filling a path, such as a gradient.
    final void
    setStroke(boolean stroke)
    Sets paint's style to STROKE if true, or FILL if false.
    final void
    setStrokeAlign(int align)
    Sets the paint's stroke align type.
    void
    setStrokeCap(int cap)
    Sets the paint's cap type, controlling how the start and end of stroked lines and paths are treated, except where noted.
    void
    setStrokeJoin(int join)
    Sets the paint's stroke join type.
    void
    setStrokeMiter(float miter)
    Sets the miter limit at which a sharp corner is drawn beveled.
    void
    setStrokeWidth(float width)
    Sets the thickness of the pen for stroking shapes.
    void
    setStyle(int style)
    Sets the paint's style, used for controlling how primitives' geometries are interpreted, except where noted.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • FILL

      public static final int FILL
      Geometry drawn with this style will be filled, ignoring all stroke-related settings in the paint.
      See Also:

    • STROKE

      public static final int STROKE
      Geometry drawn with this style will be stroked, respecting the stroke-related fields on the paint.
      See Also:

    • STROKE_AND_FILL

      public static final int STROKE_AND_FILL
      Geometry (path) drawn with this style will be both filled and stroked at the same time, respecting the stroke-related fields on the paint. This shares all paint attributes; for instance, they are drawn with the same color. Use this to avoid hitting the same pixels twice with a stroke draw and a fill draw.
      See Also:

    • FILL_AND_STROKE

      public static final int FILL_AND_STROKE
      See Also:

    • CAP_BUTT

      public static final int CAP_BUTT
      The stroke ends with the path, and does not project beyond it.
      See Also:

    • CAP_ROUND

      public static final int CAP_ROUND
      The stroke projects out as a semicircle, with the center at the end of the path.
      See Also:

    • CAP_SQUARE

      public static final int CAP_SQUARE
      The stroke projects out as a square, with the center at the end of the path.
      See Also:

    • CAP_COUNT

      @Internal public static final int CAP_COUNT
      The number of cap types.
      See Also:

    • JOIN_MITER

      public static final int JOIN_MITER
      The outer edges of a join meet at a sharp angle
      See Also:

    • JOIN_ROUND

      public static final int JOIN_ROUND
      The outer edges of a join meet in a circular arc.
      See Also:

    • JOIN_BEVEL

      public static final int JOIN_BEVEL
      The outer edges of a join meet with a straight line
      See Also:

    • JOIN_COUNT

      @Internal public static final int JOIN_COUNT
      The number of join types.
      See Also:

    • ALIGN_CENTER

      public static final int ALIGN_CENTER
      The stroke is aligned to center.
      See Also:

    • ALIGN_INSIDE

      public static final int ALIGN_INSIDE
      The stroke is aligned to inside.
      See Also:

    • ALIGN_OUTSIDE

      public static final int ALIGN_OUTSIDE
      The stroke is aligned to outside.
      See Also:

    • ALIGN_COUNT

      @Internal public static final int ALIGN_COUNT
      The number of align types.
      See Also:

  • Constructor Details

    • Paint

      public Paint()
      Creates a new Paint with defaults.

    • Paint

      public Paint(@Nullable Paint paint)
      Create a new paint, initialized with the attributes in the specified paint parameter.
      Parameters:
      paint - Existing paint used to initialize the attributes of the new paint.

  • Method Details

    • reset

      public void reset()
      Set all contents of this paint to their initial values.

    • set

      public void set(Paint paint)
      Set all contents of this paint from the specified paint.
      Parameters:
      paint - the paint to set this paint from

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • getColor

      @ColorInt public int getColor()
      Return the paint's solid color in sRGB. Note that the color is a 32-bit value containing alpha as well as r,g,b. This 32-bit value is not premultiplied, meaning that its alpha can be any value, regardless of the values of r,g,b.
      Returns:
      the paint's color (and alpha).

    • setColor

      public void setColor(@ColorInt int color)
      Set the paint's solid color in sRGB. Note that the color is a 32-bit value containing alpha as well as r,g,b. This 32-bit value is not premultiplied, meaning that its alpha can be any value, regardless of the values of r,g,b.
      Parameters:
      color - the new color (including alpha) to set in the paint.

    • r

      public final float r()
      Returns the value of the red component.
      See Also:

    • g

      public final float g()
      Returns the value of the green component.
      See Also:

    • b

      public final float b()
      Returns the value of the blue component.
      See Also:

    • a

      public final float a()
      Returns the value of the alpha component.
      See Also:

    • getColor4f

      public final void getColor4f(@Size(4L) float @NonNull [] dst)
      Returns the color used when stroking and filling. Color is stored in dst array in sRGB space, un-premultiplied form.
      Parameters:
      dst - an array that receives R,G,B,A color components

    • setColor4f

      public final void setColor4f(float r, float g, float b, float a)
      Sets alpha and RGB used when stroking and filling. The color is four floating point values, un-premultiplied. The color values are interpreted as being in the sRGB color space.
      Parameters:
      r - the new red component (0..1) of the paint's color.
      g - the new green component (0..1) of the paint's color.
      b - the new blue component (0..1) of the paint's color.
      a - the new alpha component (0..1) of the paint's color.

    • setColor4f

      public final void setColor4f(float r, float g, float b, float a, @Nullable ColorSpace colorSpace)
      Sets alpha and RGB used when stroking and filling. The color is four floating point values, un-premultiplied. The color values are interpreted as being in the colorSpace. If colorSpace is null, then color is assumed to be in the sRGB color space.
      Parameters:
      r - the new red component of the paint's color.
      g - the new green component of the paint's color.
      b - the new blue component of the paint's color.
      a - the new alpha component (0..1) of the paint's color.
      colorSpace - ColorSpace describing the encoding of color

    • getAlphaF

      public float getAlphaF()
      Retrieves alpha/opacity from the color used when stroking and filling.
      Returns:
      alpha ranging from zero, fully transparent, to one, fully opaque

    • getAlpha

      public int getAlpha()
      Helper to getColor() that just returns the color's alpha value. This is the same as calling getColor() >>> 24. It always returns a value between 0 (completely transparent) and 255 (completely opaque).
      Returns:
      the alpha component of the paint's color.

    • setAlphaF

      public void setAlphaF(float a)
      Replaces alpha, leaving RGB unchanged. a is a value from 0.0 to 1.0. a set to 0.0 makes color fully transparent; a set to 1.0 makes color fully opaque.
      Parameters:
      a - the alpha component [0..1] of the paint's color

    • setAlpha

      public void setAlpha(int a)
      Helper to setColor(), that only assigns the color's alpha value, leaving its r,g,b values unchanged.
      Parameters:
      a - the alpha component [0..255] of the paint's color

    • setRGB

      public final void setRGB(int r, int g, int b)
      Helper to setColor(), that only assigns the color's r,g,b values, leaving its alpha value unchanged.
      Parameters:
      r - the new red component (0..255) of the paint's color.
      g - the new green component (0..255) of the paint's color.
      b - the new blue component (0..255) of the paint's color.

    • setRGBA

      public final void setRGBA(int r, int g, int b, int a)
      Sets color used when drawing solid fills. The color components range from 0 to 255. The color is un-premultiplied; alpha sets the transparency independent of RGB.
      Parameters:
      r - amount of red, from no red (0) to full red (255)
      g - amount of green, from no green (0) to full green (255)
      b - amount of blue, from no blue (0) to full blue (255)
      a - amount of alpha, from fully transparent (0) to fully opaque (255)

    • setARGB

      public void setARGB(int a, int r, int g, int b)
      Sets color used when drawing solid fills. The color components range from 0 to 255. The color is un-premultiplied; alpha sets the transparency independent of RGB.
      Parameters:
      a - amount of alpha, from fully transparent (0) to fully opaque (255)
      r - amount of red, from no red (0) to full red (255)
      g - amount of green, from no green (0) to full green (255)
      b - amount of blue, from no blue (0) to full blue (255)

    • isAntiAlias

      public final boolean isAntiAlias()
      Returns true if antialiasing should be used. The default value is true.
      Returns:
      anti-aliasing state
      See Also:

    • setAntiAlias

      public final void setAntiAlias(boolean aa)
      Sets a hint that indicates if antialiasing should be used. An implementation may use analytic method by computing geometry's coverage, distance-to-edge method by computing signed distance field, or multisampling to do antialiasing. If true, the AA step is calculated in screen space. The default value is true.
      Parameters:
      aa - setting for anti-aliasing

    • isDither

      public final boolean isDither()
      Returns true if color error may be distributed to smooth color transition. An implementation may use a bayer matrix or blue noise texture to do dithering. The default value is false.
      Returns:
      dithering state
      See Also:

    • setDither

      public final void setDither(boolean dither)
      Sets a hint that indicates if color error may be distributed to smooth color transition. An implementation may use a bayer matrix or blue noise texture to do dithering. The default value is false.
      Parameters:
      dither - setting for dithering

    • getStyle

      public int getStyle()
      Returns the paint's style, used for controlling how primitives' geometries are interpreted, except where noted. The default is FILL.
      Returns:
      the paint's style setting (fill, stroke or both)
      See Also:

    • setStyle

      public void setStyle(int style)
      Sets the paint's style, used for controlling how primitives' geometries are interpreted, except where noted. The default is FILL.
      Parameters:
      style - the new style to set in the paint

    • setStroke

      public final void setStroke(boolean stroke)
      Sets paint's style to STROKE if true, or FILL if false.
      Parameters:
      stroke - true to stroke shapes, false to fill shapes

    • getStrokeCap

      public int getStrokeCap()
      Returns the paint's cap type, controlling how the start and end of stroked lines and paths are treated, except where noted. The default is CAP_ROUND.
      Returns:
      the line cap style for the paint
      See Also:

    • setStrokeCap

      public void setStrokeCap(int cap)
      Sets the paint's cap type, controlling how the start and end of stroked lines and paths are treated, except where noted. The default is CAP_ROUND.
      Parameters:
      cap - set the paint's line cap style

    • getStrokeJoin

      public int getStrokeJoin()
      Returns the paint's stroke join type. The default is JOIN_ROUND.
      Returns:
      the paint's Join
      See Also:

    • setStrokeJoin

      public void setStrokeJoin(int join)
      Sets the paint's stroke join type. The default is JOIN_ROUND.
      Parameters:
      join - set the paint's Join

    • getStrokeAlign

      public final int getStrokeAlign()
      Returns the paint's stroke align type. The default is ALIGN_CENTER. Note that this only applies to closed contours, otherwise stroking behaves as ALIGN_CENTER.
      Returns:
      the paint's Align
      See Also:

    • setStrokeAlign

      public final void setStrokeAlign(int align)
      Sets the paint's stroke align type. The default is ALIGN_CENTER. Note that this only applies to closed contours, otherwise stroking behaves as ALIGN_CENTER.
      Parameters:
      align - set the paint's Align

    • getStrokeWidth

      public float getStrokeWidth()
      Returns the thickness of the pen for stroking shapes. The default value is 1.0 px.
      Returns:
      the paint's stroke width; zero for hairline, greater than zero for pen thickness
      See Also:

    • setStrokeWidth

      public void setStrokeWidth(float width)
      Sets the thickness of the pen for stroking shapes. The default value is 1.0 px. A stroke width of zero is treated as "hairline" width. Hairlines are always exactly one pixel wide in screen space (their thickness does not change as the canvas is scaled).
      Parameters:
      width - set the paint's stroke width; zero for hairline, greater than zero for pen thickness

    • getStrokeMiter

      public float getStrokeMiter()
      Returns the miter limit at which a sharp corner is drawn beveled. The default value is 4.0 px.
      Returns:
      zero and greater miter limit
      See Also:

    • setStrokeMiter

      public void setStrokeMiter(float miter)
      Sets the miter limit at which a sharp corner is drawn beveled. The default value is 4.0 px.
      Parameters:
      miter - zero and greater miter limit

    • getShader

      @RawPtr public @Nullable @RawPtr Shader getShader()
      Returns optional colors used when filling a path, such as a gradient.
      Returns:
      Shader if previously set, null otherwise

    • refShader

      @SharedPtr public @Nullable @SharedPtr Shader refShader()
      Returns optional colors used when filling a path, such as a gradient.
      Returns:
      Shader if previously set, null otherwise

    • setShader

      public void setShader(@SharedPtr @Nullable @SharedPtr Shader shader)
      Sets optional colors used when filling a path, such as a gradient.
      Parameters:
      shader - how geometry is filled with color; if null, solid color is used instead

    • getColorFilter

      public @Nullable ColorFilter getColorFilter()
      Returns ColorFilter if set, or null.
      Returns:
      ColorFilter if previously set, null otherwise

    • setColorFilter

      public void setColorFilter(@Nullable ColorFilter colorFilter)
      Sets ColorFilter to filter, pass null to clear ColorFilter.
      Parameters:
      colorFilter - ColorFilter to apply to subsequent draw

    • getBlendMode

      public @Nullable BlendMode getBlendMode()
      If the current blender can be represented as a BlendMode enum, this returns that enum object. If it cannot, then this returns null.

    • isSrcOver

      public final boolean isSrcOver()
      Returns true if BlendMode claims to be equivalent to BlendMode.SRC_OVER, the default.
      Returns:
      true if BlendMode is BlendMode.SRC_OVER

    • setBlendMode

      public void setBlendMode(@Nullable BlendMode mode)
      Helper method for calling setBlender().

    • getBlender

      public final @Nullable Blender getBlender()
      Returns the user-supplied blend function, if one has been set.

      A null blender signifies the default BlendMode.SRC_OVER behavior.

      Returns:
      the blender assigned to this paint, otherwise null
      See Also:

    • setBlender

      public final void setBlender(@Nullable Blender blender)
      Sets the current blender.

      A null blender signifies the default BlendMode.SRC_OVER behavior.

      For convenience, you can pass BlendMode if the blend effect can be expressed as one of those values. A blend mode defines how source pixels (generated by a drawing command) are composited with the destination pixels (content of the render target).

      Parameters:
      blender - the blender to be installed in the paint, may be null
      See Also:

    • getPathEffect

      public final PathEffect getPathEffect()
      Returns PathEffect if set, or null.
      Returns:
      PathEffect if previously set, null otherwise

    • setPathEffect

      public final void setPathEffect(@Nullable PathEffect pathEffect)
      Sets PathEffect to pathEffect. Pass null to leave the path geometry unaltered.
      Parameters:
      pathEffect - replace Path with a modification when drawn

    • nothingToDraw

      public boolean nothingToDraw()
      Returns true if the paint prevents all drawing; otherwise, the paint may or may not allow drawing.

      Returns true if, for example, blend mode combined with alpha computes a new alpha of zero.

      Returns:
      true if the paint prevents all drawing

    • canComputeFastBounds

      @Internal public final boolean canComputeFastBounds(@RawPtr @RawPtr @Nullable ImageFilter imageFilter)
      Returns true if Paint does not include elements requiring extensive computation to compute BaseDevice bounds of drawn geometry.
      Returns:
      true if Paint allows for fast computation of bounds

    • computeFastBounds

      @Internal public final void computeFastBounds(@RawPtr @RawPtr @Nullable ImageFilter imageFilter, Rect2fc orig, Rect2f storage)
      Only call this if canComputeFastBounds() returned true. This takes a raw rectangle (the raw bounds of a shape), and adjusts it for stylistic effects in the paint (e.g. stroking). If needed, it uses the storage parameter. It returns the adjusted bounds that can then be used for Canvas.quickReject(Rect2fc) tests.

      This method ensures that orig will not be modified, and the result will always be stored into the storage rect.

      Parameters:
      orig - geometry modified by Paint when drawn
      storage - fast computed bounds of geometry

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • equals

      protected final boolean equals(Paint paint)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getAlphaDirect

      @Internal public static int getAlphaDirect(@Nullable Paint paint)

    • getBlendModeDirect

      @Internal public static BlendMode getBlendModeDirect(@Nullable Paint paint)

    • isBlendedShader

      @Internal public static boolean isBlendedShader(@Nullable Shader shader)

    • isBlendedColorFilter

      @Internal public static boolean isBlendedColorFilter(@Nullable ColorFilter filter)

    • isBlendedImageFilter

      @Internal public static boolean isBlendedImageFilter(@Nullable ImageFilter filter)

    • isOpaquePaint

      @Internal public static boolean isOpaquePaint(@Nullable Paint paint)