Class Paint

java.lang.Object
icyllis.arc3d.core.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 
    The Align specifies the treatment where the stroke is placed in relation to the object edge, this only applies to closed contours.
    static @interface 
    The Cap specifies the treatment for the beginning and ending of stroked lines and paths.
    static @interface 
    The Join specifies the treatment where lines and curve segments join on a stroked path.
    static @interface 
    Set Style to fill, stroke, or both fill and stroke geometry.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    The stroke is aligned to center.
    static final int
    The number of align types.
    static final int
    The stroke is aligned to inside.
    static final int
    The stroke is aligned to outside.
    static final int
    The stroke ends with the path, and does not project beyond it.
    static final int
    The number of cap types.
    static final int
    The stroke projects out as a semicircle, with the center at the end of the path.
    static final int
    The stroke projects out as a square, with the center at the end of the path.
    static final int
    Geometry drawn with this style will be filled, ignoring all stroke-related settings in the paint.
    static final int
     
    static final int
    The outer edges of a join meet with a straight line
    static final int
    The number of join types.
    static final int
    The outer edges of a join meet at a sharp angle
    static final int
    The outer edges of a join meet in a circular arc.
    static final int
    Geometry drawn with this style will be stroked, respecting the stroke-related fields on the paint.
    static final int
    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
    Creates a new Paint with defaults.
    Paint(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
    Returns true if Paint does not include elements requiring extensive computation to compute BaseDevice bounds of drawn geometry.
    void
     
    final void
    computeFastBounds(@RawPtr ImageFilter imageFilter, Rect2fc orig, Rect2f storage)
    Only call this if canComputeFastBounds() returned true.
    protected final boolean
    equals(Paint paint)
     
    boolean
     
    final float
    g()
    Returns the value of the green component.
    int
    Helper to getColor() that just returns the color's alpha value.
    static int
     
    float
    Retrieves alpha/opacity from the color used when stroking and filling.
    Returns the user-supplied blend function, if one has been set.
    If the current blender can be represented as a BlendMode enum, this returns that enum object.
    static BlendMode
     
    int
    Return the paint's solid color in sRGB.
    final void
    getColor4f(float[] dst)
    Returns the color used when stroking and filling.
    Returns ColorFilter if set, or null.
    Returns PathEffect if set, or null.
    Returns optional colors used when filling a path, such as a gradient.
    final int
    Returns the paint's stroke align type.
    int
    Returns the paint's cap type, controlling how the start and end of stroked lines and paths are treated, except where noted.
    int
    Returns the paint's stroke join type.
    float
    Returns the miter limit at which a sharp corner is drawn beveled.
    float
    Returns the thickness of the pen for stroking shapes.
    int
    Returns the paint's style, used for controlling how primitives' geometries are interpreted, except where noted.
    int
     
    final boolean
    Returns true if antialiasing should be used.
    static boolean
     
    static boolean
     
    static boolean
     
    final boolean
    Returns true if color error may be distributed to smooth color transition.
    static boolean
     
    final boolean
    Returns true if BlendMode claims to be equivalent to BlendMode.SRC_OVER, the default.
    boolean
    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.
    Returns the user-supplied blend function, if one has been set.
    Returns ColorFilter if set, or null.
    Returns optional colors used when filling a path, such as a gradient.
    void
    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
    Sets the current blender.
    void
    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, ColorSpace colorSpace)
    Sets alpha and RGB used when stroking and filling.
    void
    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
    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
    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.
     

    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(@Nonnull @Size(4L) float[] 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

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

      @Nullable @SharedPtr public @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(@Nullable @SharedPtr @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

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

      @Nullable @SharedPtr public @SharedPtr ColorFilter refColorFilter()
      Returns ColorFilter if set, or null.
      Returns:
      ColorFilter if previously set, null otherwise
    • setColorFilter

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

      @Nullable public 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

      @Nullable @RawPtr public final @RawPtr 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:
    • refBlender

      @Nullable @SharedPtr public @SharedPtr Blender refBlender()
      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 @SharedPtr @SharedPtr 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 @Nullable @RawPtr 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 @Nullable @RawPtr 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)