# Class Gradient

java.lang.Object
com.codename1.ui.Gradient

All Implemented Interfaces:
  `Paint`

Direct Known Subclasses:
  `ConicGradient, LinearGradient, RadialGradient`

public abstract class Gradient extends Object implements Paint

Abstract description of a CSS-style gradient that can be used as a background or painted directly via `Graphics#fillGradient`. Three concrete subclasses mirror the corresponding CSS functions:

- `LinearGradient` for `linear-gradient(<angle>, <stops>)`
- `RadialGradient` for `radial-gradient([shape] [extent] [at pos], <stops>)`
- `ConicGradient` for `conic-gradient([from <angle>] [at pos], <stops>)`

A Gradient is a `Paint`, so it can also be assigned via `Graphics#setColor(Paint)` and consumed by `fillRect` / `fillShape`. The dedicated `Graphics#fillGradient(Gradient, int, int, int, int)` entry point gives the platform port the rectangle bounds up front so it can pick the fastest native shader path (Java2D `LinearGradientPaint` / `RadialGradientPaint`, Android `LinearGradient` / `RadialGradient` / `SweepGradient`, Core Graphics `CGGradient`).

Subclass instances are intended to be immutable after construction; modify via builder-style setters before handing the gradient off to `Graphics` or `Style`. `copy()` produces a defensive deep clone for places that must outlive caller mutation (e.g. async paint queues).

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final byte`
  `CYCLE_NONE`
  Cycle modes mirroring `MultipleGradientPaint.CycleMethod`.
  `static final byte`
  `CYCLE_REFLECT`
  `static final byte`
  `CYCLE_REPEAT`
  `static final byte`
  `KIND_CONIC`
  Sentinel returned by `getKind()` for `ConicGradient` instances.
  `static final byte`
  `KIND_LINEAR`
  Sentinel returned by `getKind()` for `LinearGradient` instances.
  `static final byte`
  `KIND_RADIAL`
  Sentinel returned by `getKind()` for `RadialGradient` instances.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract Gradient`
  `copy()`
  Returns a defensive deep copy.
  `final Image`
  `getCachedRaster(int width, int height)`
  Returns a software-rasterized image of this gradient at the requested rectangle size, reusing a weakly-cached bitmap when possible.
  `final int[]`
  `getColors()`
  ARGB stop colors (length >= 2).
  `final byte`
  `getCycleMethod()`
  One of `CYCLE_NONE` / `CYCLE_REPEAT` / `CYCLE_REFLECT`.
  `abstract byte`
  `getKind()`
  Returns one of `KIND_LINEAR`, `KIND_RADIAL`, `KIND_CONIC`.
  `final float[]`
  `getPositions()`
  Stop positions in [0,1] aligned with `getColors()`.
  `protected final void`
  `invalidateRasterCache()`
  Drops the weak cached raster - call after any mutation that changes the painted pixels (cycle method change, subclass parameter change).
  `final void`
  `paint(Graphics g, double x, double y, double w, double h)`
  Paints in the given bounds.
  `final void`
  `paint(Graphics g, Rectangle2D bounds)`
  Paints in the given bounds.
  `static Gradient`
  `parseCss(String css)`
  Parses a CSS gradient function string and returns the corresponding `Gradient` subclass.
  `abstract int`
  `sampleArgb(int px, int py, int width, int height)`
  Software-rasterizer hook used by the default port implementation when no native gradient shader is available.
  `protected final int`
  `sampleStops(float t)`
  Samples one of the stops at fractional position t.
  `final Gradient`
  `setCycleMethod(byte cycleMethod)`
  Sets the cycle method.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### KIND_LINEAR

    public static final byte KIND_LINEAR
    Sentinel returned by `getKind()` for `LinearGradient` instances.
    See Also:
      - Constant Field Values

  - ### KIND_RADIAL

    public static final byte KIND_RADIAL
    Sentinel returned by `getKind()` for `RadialGradient` instances.
    See Also:
      - Constant Field Values

  - ### KIND_CONIC

    public static final byte KIND_CONIC
    Sentinel returned by `getKind()` for `ConicGradient` instances.
    See Also:
      - Constant Field Values

  - ### CYCLE_NONE

    public static final byte CYCLE_NONE
    Cycle modes mirroring `MultipleGradientPaint.CycleMethod`. Repeated as byte constants here so that this class (and the .res serializer) does not pull the enum across the resource format boundary.
    See Also:
      - Constant Field Values

  - ### CYCLE_REPEAT

    public static final byte CYCLE_REPEAT
    See Also:
      - Constant Field Values

  - ### CYCLE_REFLECT

    public static final byte CYCLE_REFLECT
    See Also:
      - Constant Field Values

- ## Method Details

  - ### parseCss

    public static Gradient parseCss(String css)

    Parses a CSS gradient function string and returns the corresponding `Gradient` subclass. Supports `linear-gradient`, `radial-gradient`, `conic-gradient`, and the `repeating-*` variants. Mirrors the syntax accepted by the build-time CSS compiler so a string copied verbatim from a `.css` file produces the same gradient at runtime.

    Returns null if `css` is null/empty or does not look like a gradient function call. Throws `IllegalArgumentException` on hard parse errors (unknown direction, missing stops, malformed colors).

  - ### getKind

    public abstract byte getKind()
    Returns one of `KIND_LINEAR`, `KIND_RADIAL`, `KIND_CONIC`.

  - ### getColors

    public final int[] getColors()
    ARGB stop colors (length >= 2).

  - ### getPositions

    public final float[] getPositions()
    Stop positions in [0,1] aligned with `getColors()`.

  - ### getCycleMethod

    public final byte getCycleMethod()
    One of `CYCLE_NONE` / `CYCLE_REPEAT` / `CYCLE_REFLECT`. Defaults to NONE.

  - ### setCycleMethod

    public final Gradient setCycleMethod(byte cycleMethod)
    Sets the cycle method. Returns `this` for chaining.

  - ### getCachedRaster

    public final Image getCachedRaster(int width, int height)
    Returns a software-rasterized image of this gradient at the requested rectangle size, reusing a weakly-cached bitmap when possible. Ports without a hardware shader path can call this from their `fillGradient` override to avoid re-rasterizing on every frame; the cache is a `Display.createSoftWeakRef` so the bitmap is reclaimable when idle.

  - ### invalidateRasterCache

    protected final void invalidateRasterCache()
    Drops the weak cached raster - call after any mutation that changes the painted pixels (cycle method change, subclass parameter change). Public so subclass setters can keep the cache coherent.

  - ### copy

    public abstract Gradient copy()
    Returns a defensive deep copy. Implemented by each concrete subclass so async-paint queues can capture an immutable snapshot.

  - ### paint

    public final void paint(Graphics g, Rectangle2D bounds)
    Description copied from interface: `Paint`

    Paints in the given bounds.

    ###### Parameters

    - `g`: Graphics context to paint in.

    - `bounds`: Bounds to paint in. User coordinates.

    Specified by:
      `paint` in interface `Paint`

  - ### paint

    public final void paint(Graphics g, double x, double y, double w, double h)
    Description copied from interface: `Paint`

    Paints in the given bounds.

    ###### Parameters

    - `g`: Graphics context to paint in.

    - `x`: x coordinate. User space.

    - `y`: y coordinate. USer space.

    - `w`: width. User space.

    - `h`: Hight. User space.

    Specified by:
      `paint` in interface `Paint`

  - ### sampleArgb

    public abstract int sampleArgb(int px, int py, int width, int height)
    Software-rasterizer hook used by the default port implementation when no native gradient shader is available. Samples an ARGB color for the pixel at (px, py) within a rectangle of the given width / height. Ports overriding `fillGradient` directly do not call this.

  - ### sampleStops

    protected final int sampleStops(float t)

    Samples one of the stops at fractional position t. Honors the configured cycle method. Shared by the three subclasses' sampling implementations.

    CSS `repeating-*-gradient` stops define one period from `positions[0]` to `positions[last]`, not `[0, 1]`. For `white 0%, red 16%` the period is 0.16 of the gradient extent and the pattern must wrap on that range; collapsing to `t - floor(t)` would leak the final color across the rest of the rect.