Class Paint

java.lang.Object
icyllis.modernui.graphics.Paint
Direct Known Subclasses:
TextPaint

public class Paint extends Object
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.

  • Nested Class Summary

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

    Fields
    Modifier and Type
    Field
    Description
    static final int
    The stroke is aligned to center.
    static final int
    The stroke is aligned to inside.
    static final int
    The stroke is aligned to outside.
    static final int
    Font style constant to request the bold style
    static final int
    Font style constant to request the bold and italic style
    static final int
    The stroke ends with the path, and does not project beyond it.
    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
    Font style constant to request the italic style
    static final int
    The outer edges of a join meet with a straight line
    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.
    protected int
     
    static final int
    Font style constant to request the plain/regular/normal style
    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
    boolean
     
    int
    Helper to getColor() that just returns the color's alpha value.
    float
    Retrieves alpha/opacity from the color used when stroking and filling.
    Get the paint's blend mode.
    int
    Return the paint's solid color in sRGB.
    float[]
    Returns alpha and RGB used when stroking and filling.
    float[]
    getColor4f(float[] dst)
    Returns alpha and RGB used when stroking and filling.
    Returns ColorFilter if set, or null.
    final int
    Returns the current filter.
    final int
    Returns the mipmap mode.
    Returns optional colors used when filling a path, such as a gradient.
    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.
    float
    Return the paint's text size in pixel units.
    int
    Get desired text's style, combination of NORMAL, BOLD and ITALIC.
    int
     
    boolean
    Returns true if antialiasing should be used.
    boolean
    Returns true if color error may be distributed to smooth color transition.
    boolean
    Returns the current filter.
    boolean
     
    boolean
     
    static Paint
    Returns a paint from the shared pool, if any, or creates a new one.
    The attributes of the paint are guaranteed to be defaults according to this class.
    void
    Releases this paint object to the shared pool.
    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.
    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.
    void
    Set or clear the blend mode.
    void
    setColor(int color)
    Set the paint's solid color in sRGB.
    void
    setColor4f(float r, float g, float b, float a)
    Sets alpha and RGB used when stroking and filling.
    void
    Sets ColorFilter to filter, pass null to clear ColorFilter.
    void
    setDither(boolean dither)
    Sets a hint that indicates if color error may be distributed to smooth color transition.
    void
    setFilter(boolean filter)
    Set the interpolation method for sampling textures images.
    final void
    setFilterMode(int filter)
    Set the interpolation method for sampling texture images.
    void
    setLinearText(boolean linearText)
    Paint flag that enables smooth linear scaling of text.
    final void
    setMipmapMode(int mipmap)
    Set the mipmap mode for sampling texture images.
    final void
    setRGBA(float r, float g, float b, float a)
    Sets alpha and RGB used when stroking and filling.
    void
    setRGBA(int r, int g, int b, int a)
    Sets color used when drawing solid fills.
    void
    setShader(Shader shader)
    Sets optional colors used when filling a path, such as a gradient.
    void
    setStroke(boolean stroke)
    Sets paint's style to STROKE if true, or FILL if false.
    void
    setStrokeAlign(int align)
    Sets the paint's stroke align type.
    void
    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
    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
    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.
    void
    Sets the paint's style, used for controlling how primitives' geometries are interpreted, except where noted.
    void
    setTextAntiAlias(boolean textAA)
     
    void
    setTextSize(float textSize)
    Set the paint's text size in pixel units.
    void
    setTextStyle(int textStyle)
    Set desired text's style, combination of NORMAL, BOLD and ITALIC.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, 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:
    • 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:
    • ALIGN_CENTER

      @Experimental public static final int ALIGN_CENTER
      The stroke is aligned to center.
      See Also:
    • ALIGN_INSIDE

      @Experimental public static final int ALIGN_INSIDE
      The stroke is aligned to inside.
      See Also:
    • ALIGN_OUTSIDE

      @Experimental public static final int ALIGN_OUTSIDE
      The stroke is aligned to outside.
      See Also:
    • NORMAL

      public static final int NORMAL
      Font style constant to request the plain/regular/normal style
      See Also:
    • BOLD

      public static final int BOLD
      Font style constant to request the bold style
      See Also:
    • ITALIC

      public static final int ITALIC
      Font style constant to request the italic style
      See Also:
    • BOLD_ITALIC

      public static final int BOLD_ITALIC
      Font style constant to request the bold and italic style
      See Also:
    • mFlags

      protected int mFlags
  • Constructor Details

    • Paint

      public Paint()
      Creates a new Paint with defaults.
      See Also:
    • 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

    • obtain

      @NonNull public static Paint obtain()
      Returns a paint from the shared pool, if any, or creates a new one.
      The attributes of the paint are guaranteed to be defaults according to this class. A call to recycle() is expected (not strictly necessary) after use.

      For example:

      
       @Override
       protected void onDraw(Canvas canvas) {
           var paint = Paint.obtain();
      
           paint.setColor(mColorA);
           canvas.drawRect(mRectA, paint);
      
           paint.setColor(mColorB);
           canvas.drawRect(mRectB, paint);
      
           paint.recycle(); // recycle it before method return
       }
       
      In most cases, you'll need to cache a paint object in its owner object, such as a View or a Drawable. Thus this method is not really recommended.
      Returns:
      a pooled paint object
      See Also:
    • recycle

      public void recycle()
      Releases this paint object to the shared pool. You can't touch this paint anymore after recycling.
      See Also:
    • reset

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

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

      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.
    • getColor4f

      @NonNull @Size(4L) public float[] getColor4f()
      Returns 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.
      Returns:
      a new float array that contains r,g,b,a values
    • getColor4f

      @NonNull @Size(4L) public float[] getColor4f(@NonNull @Size(4L) float[] dst)
      Returns 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:
      dst - a non-null array of 4 floats that will hold the result of the method
      Returns:
      the passed float array that contains r,g,b,a values
    • setColor4f

      public 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.
    • 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.
    • 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
    • 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
    • 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
    • setRGBA

      public final void setRGBA(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.
    • setRGBA

      public 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 boolean isAntiAlias()
      Returns true if antialiasing should be used. The default value is true.
      Returns:
      anti-aliasing state
      See Also:
    • setAntiAlias

      public 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 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 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(@NonNull Paint.Style style)
      Sets the paint's style, used for controlling how primitives' geometries are interpreted, except where noted. The default is Paint.Style.FILL.
      Parameters:
      style - the new style to set in the paint
    • 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 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(@NonNull Paint.Cap 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 Paint.Cap.ROUND.
      Parameters:
      cap - set the paint's line cap style
    • 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(@NonNull Paint.Join join)
      Sets the paint's stroke join type. The default is Paint.Join.ROUND.
      Parameters:
      join - set the paint's Join
    • 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 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

      @Experimental public void setStrokeAlign(@NonNull Paint.Align align)
      Sets the paint's stroke align type. The default is Paint.Align.CENTER. Note that this only applies to closed contours, otherwise stroking behaves as Paint.Align.CENTER.
      Parameters:
      align - set the paint's Align
    • setStrokeAlign

      @Experimental public 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 public Shader getShader()
      Returns optional colors used when filling a path, such as a gradient.
      Returns:
      Shader if previously set, null otherwise
    • setShader

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

      @Nullable public BlendMode getBlendMode()
      Get the paint's blend mode. By default, returns BlendMode.SRC_OVER. A null value means a custom blend.
      Returns:
      the paint's blend mode used to combine source color with destination color
    • setBlendMode

      public void setBlendMode(@Nullable BlendMode mode)
      Set or clear the blend mode. A blend mode defines how source pixels (generated by a drawing command) are composited with the destination pixels (content of the render target).

      A null blend mode signifies the default BlendMode.SRC_OVER behavior.

      Parameters:
      mode - the blend mode to be installed in the paint, may be null
      See Also:
    • getTextStyle

      public int getTextStyle()
      Get desired text's style, combination of NORMAL, BOLD and ITALIC.
      Returns:
      the desired style of the font
    • setTextStyle

      public void setTextStyle(int textStyle)
      Set desired text's style, combination of NORMAL, BOLD and ITALIC. If the font family does not support this style natively, our engine will use a simulation algorithm, also known as fake bold and fake italic. The default value is NORMAL.
      Parameters:
      textStyle - the desired style of the font
    • getTextSize

      public float getTextSize()
      Return the paint's text size in pixel units.

      The default value is 16.

      Returns:
      the paint's text size in pixel units.
      See Also:
    • setTextSize

      public void setTextSize(float textSize)
      Set the paint's text size in pixel units. For example, a text size of 16 (1em) means the letter 'M' is 16 pixels high in device space. Very large or small sizes will impact rendering performance, and the rendering system might not render text at these sizes. For now, text sizes will clamp to 1 and 2184. You can have even larger glyphs through matrix transformation, and our engine will attempt to use SDF text rendering. This method has no effect if size is not greater than or equal to zero.

      The default value is 16.

      Parameters:
      textSize - set the paint's text size in pixel units.
    • isTextAntiAlias

      public boolean isTextAntiAlias()
    • setTextAntiAlias

      public void setTextAntiAlias(boolean textAA)
    • isLinearText

      public boolean isLinearText()
      Returns:
      whether to enable linear text
    • setLinearText

      public void setLinearText(boolean linearText)
      Paint flag that enables smooth linear scaling of text.

      Enabling this flag does not actually scale text, but rather adjusts text draw operations to deal gracefully with smooth adjustment of scale. When this flag is enabled, font hinting is disabled to prevent shape deformation between scale factors, and glyph caching is disabled due to the large number of glyph images that will be generated.

      The default value is false.

      Parameters:
      linearText - whether to enable linear text
    • getFilterMode

      public final int getFilterMode()
      Returns the current filter. The default is ImageShader.FILTER_MODE_LINEAR. The value is ignored when anisotropic filtering is used.
      Returns:
      the current filter
      See Also:
    • setFilterMode

      public final void setFilterMode(int filter)
      Set the interpolation method for sampling texture images. The default is ImageShader.FILTER_MODE_LINEAR. Calling this method does NOT affect anisotropic filtering.
      Parameters:
      filter - the paint's filter
      See Also:
    • isFilter

      public boolean isFilter()
      Returns the current filter. True will use ImageShader.FILTER_MODE_LINEAR, false will use ImageShader.FILTER_MODE_NEAREST. The value is ignored when anisotropic filtering is used.
      Returns:
      the current filter, true means bilinear sampling, false means nearest neighbor sampling
    • setFilter

      public void setFilter(boolean filter)
      Set the interpolation method for sampling textures images. True to use ImageShader.FILTER_MODE_LINEAR, false to use ImageShader.FILTER_MODE_NEAREST.
      Parameters:
      filter - true to use bilinear sampling, false to use nearest neighbor sampling
    • getMipmapMode

      public final int getMipmapMode()
      Returns the mipmap mode. The value is ignored when anisotropic filtering is used. The default is ImageShader.MIPMAP_MODE_NONE.
      Returns:
      the mipmap mode
    • setMipmapMode

      public final void setMipmapMode(int mipmap)
      Set the mipmap mode for sampling texture images. The value is ignored when anisotropic filtering is used. The default is ImageShader.MIPMAP_MODE_NONE.
      Parameters:
      mipmap - the mipmap mode
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • equals

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