Brush
public final class Brush
Defines how stroke inputs are interpreted to create the visual representation of a stroke.
The type completely describes how inputs are used to create stroke meshes, and how those meshes should be drawn by stroke renderers. In an analogous way to "font" and "font family", a Brush can be considered an instance of a BrushFamily with a particular color, size, and an extra parameter controlling visual fidelity, called epsilon.
Summary
Nested types |
|---|
public final class Brush.BuilderBuilder for |
public static class Brush.Companion |
Public constructors |
|---|
Brush(@NonNull BrushFamily family, float size, float epsilon)The default color of a |
Public methods |
|
|---|---|
static final @NonNull Brush.Builder |
builder()Returns a new |
final @NonNull Brush |
copy(@NonNull BrushFamily family, float size, float epsilon)Creates a copy of |
final @NonNull Brush |
copyWithColorIntArgb(Creates a copy of |
final @NonNull Brush |
copyWithColorLong(Creates a copy of |
static final @NonNull Brush |
createWithColorIntArgb(Returns a new |
static final @NonNull Brush |
createWithColorLong(Returns a new |
boolean |
|
final @ColorInt int |
The brush color as a |
final @ColorLong long |
The brush color as a |
final float |
The smallest distance for which two points should be considered visually distinct for stroke generation geometry purposes. |
final @NonNull BrushFamily |
The |
final float |
getSize()The overall thickness of strokes created with a given brush, in the same units as the stroke coordinate system. |
int |
hashCode() |
final @NonNull Brush.Builder |
Returns a |
@NonNull String |
toString() |
Protected methods |
|
|---|---|
final void |
finalize()Delete native Brush memory. |
Extension functions |
|
|---|---|
final @NonNull Brush |
@RequiresApi(value = 26)Creates a copy of |
final @NonNull Color |
@RequiresApi(value = 26)The brush color as an |
final @NonNull Brush.Builder |
@RequiresApi(value = 26)Returns a |
Public constructors
Brush
public Brush(@NonNull BrushFamily family, float size, float epsilon)
The default color of a Brush is pure black. To set a custom color, use createWithColorLong or createWithColorIntArgb.
Public methods
builder
public static final @NonNull Brush.Builder builder()
Returns a new Brush.Builder.
copy
public final @NonNull Brush copy(@NonNull BrushFamily family, float size, float epsilon)
Creates a copy of this and allows named properties to be altered while keeping the rest unchanged. To change the color, use copyWithColorLong or copyWithColorIntArgb.
copyWithColorIntArgb
public final @NonNull Brush copyWithColorIntArgb(
@ColorInt int colorIntArgb,
@NonNull BrushFamily family,
float size,
float epsilon
)
Creates a copy of this and allows named properties to be altered while keeping the rest unchanged. The color is specified as a ColorInt, which is in the sRGB color space by definition. Note that the ColorInt channel order puts alpha first (in the most significant byte).
Kotlin interprets integer literals greater than 0x7fffffff as Longs, so callers that want to specify a literal ColorInt with alpha >= 0x80 must call Long.toInt on the literal.
copyWithColorLong
public final @NonNull Brush copyWithColorLong(
@ColorLong long colorLong,
@NonNull BrushFamily family,
float size,
float epsilon
)
Creates a copy of this and allows named properties to be altered while keeping the rest unchanged. The color is specified as a ColorLong, which can encode several different color spaces. sRGB and Display P3 are supported; a color in any other color space will be converted to Display P3.
Some libraries (notably Jetpack UI Graphics) use ULong for ColorLongs, so the caller must call ULong.toLong on such a value before passing it to this method.
createWithColorIntArgb
public static final @NonNull Brush createWithColorIntArgb(
@NonNull BrushFamily family,
@ColorInt int colorIntArgb,
float size,
float epsilon
)
Returns a new Brush with the color specified by a ColorInt, which is in the sRGB color space by definition. Note that the ColorInt channel order puts alpha first (in the most significant byte).
Kotlin interprets integer literals greater than 0x7fffffff as Longs, so callers that want to specify a literal ColorInt with alpha >= 0x80 must call Long.toInt on the literal.
createWithColorLong
public static final @NonNull Brush createWithColorLong(
@NonNull BrushFamily family,
@ColorLong long colorLong,
float size,
float epsilon
)
Returns a new Brush with the color specified by a ColorLong, which can encode several different color spaces. sRGB and Display P3 are supported; a color in any other color space will be converted to Display P3.
Some libraries (notably Jetpack UI Graphics) use ULong for ColorLongs, so the caller must call ULong.toLong on such a value before passing it to this method.
getColorIntArgb
public final @ColorInt int getColorIntArgb()
The brush color as a ColorInt, which can only express colors in the sRGB color space. For clients that want to support wide-gamut colors, use colorLong.
getColorLong
public final @ColorLong long getColorLong()
The brush color as a ColorLong, which can express colors in several different color spaces. sRGB and Display P3 are supported; a color in any other color space will be converted to Display P3.
getEpsilon
public final float getEpsilon()
The smallest distance for which two points should be considered visually distinct for stroke generation geometry purposes. Effectively, it is the visual fidelity of strokes created with this brush, where any (lack of) visual fidelity can be observed by a user the further zoomed in they are on the stroke. Lower values of epsilon result in higher fidelity strokes at the cost of somewhat higher memory usage. This value, like size, is in the same units as the stroke coordinate system. A size of 0.1 physical pixels at the default zoom level is a good starting point that can tolerate a reasonable amount of zooming in with high quality visual results.
getFamily
public final @NonNull BrushFamily getFamily()
The BrushFamily for this brush. See StockBrushes for available BrushFamily values.
getSize
public final float getSize()
The overall thickness of strokes created with a given brush, in the same units as the stroke coordinate system. This must be at least as big as epsilon.
toBuilder
public final @NonNull Brush.Builder toBuilder()
Returns a Builder with values set equivalent to this. Java developers, use the returned builder to build a copy of a Brush. Kotlin developers, see copy method.
Protected methods
Extension functions
BrushUtil.copyWithAndroidColor
@RequiresApi(value = 26)
public final @NonNull Brush BrushUtil.copyWithAndroidColor(
@NonNull Brush receiver,
@NonNull Color color,
@NonNull BrushFamily family,
float size,
float epsilon
)
Creates a copy of this Brush and allows named properties to be altered while keeping the rest unchanged. The color is specified as an android.graphics.Color instance, which can encode several different color spaces. sRGB and Display P3 are supported; a color in any other color space will be converted to Display P3.
BrushUtil.createAndroidColor
@RequiresApi(value = 26)
public final @NonNull Color BrushUtil.createAndroidColor(@NonNull Brush receiver)
The brush color as an android.graphics.Color instance, which can express colors in several different color spaces. sRGB and Display P3 are supported; a color in any other color space will be converted to Display P3.
Unless an instance of android.graphics.Color is actually needed, prefer to use Brush.colorLong to get the color without causing an allocation, especially in performance-sensitive code. Brush.colorLong is fully compatible with the Long representation of android.graphics.Color.
BrushUtil.toBuilderWithAndroidColor
@RequiresApi(value = 26)
public final @NonNull Brush.Builder BrushUtil.toBuilderWithAndroidColor(
@NonNull Brush receiver,
@NonNull Color color
)
Returns a Brush.Builder with values set equivalent to the Brush and the color specified by an android.graphics.Color instance, which can encode several different color spaces. sRGB and Display P3 are supported; a color in any other color space will be converted to Display P3. Java developers, use the returned builder to build a copy of a Brush. Kotlin developers, see copyWithAndroidColor method.
In Kotlin, calling this is equivalent to calling Brush.toBuilder followed by Brush.Builder.setAndroidColor. For Java callers, this function allows more fluent call chaining.