@spec add_stop(t(), float(), term()) :: :ok | {:error, term()}

Adds a color stop to a gradient.

• grad – a gradient resource
• offset – a numeric position along the gradient (usually 0.0..1.0)
• color – a color resource created with Blendend.Style.Color.rgb/3 or /4

On success, returns :ok.

On failure, returns {:error, reason}.

@spec add_stop!(t(), float(), term()) :: t()

Same as add_stop/3, but returns the gradient directly.

On success, returns gradient.

On failure, raises Blendend.Error.

@spec conic(number(), number(), number()) :: {:ok, t()} | {:error, term()}

Creates a conic (angular) gradient.

The gradient is defined by:

• cx, cy – center of rotation
• angle – starting angle in radians

On success, returns {:ok, gradient}.

On failure, returns {:error, reason}.

@spec conic!(number(), number(), number()) :: t()

Same as conic/3, but returns the gradient directly.

On success, returns gradient.

On failure, raises Blendend.Error.

@spec conic_from_stops(
  {number(), number(), number()},
  [{float(), Blended.Style.Color.t()}],
  keyword()
) :: t()

Creates a conic gradient and adds stops.

• {cx, cy, angle} – center and angle in radians
• stops – list of {offset, color}

Options:

• :extend – extend mode (:pad | :repeat | :reflect), defaults to :pad.

@spec linear(number(), number(), number(), number()) :: {:ok, t()} | {:error, term()}

Creates a linear gradient between two points.

The gradient line goes from (x0, y0) to (x1, y1).

On success, returns {:ok, gradient} where gradient is a gradient resource.

On failure, returns {:error, reason}.

Use add_stop/3 to populate the gradient with one or more color stops, then pass the gradient as gradient: or stroke_gradient: in drawing options.

Offsets given to add_stop/3 are typically in the range 0.0..1.0 (start to end).

Examples

iex> {:ok, grad} = Blendend.Style.Gradient.linear(0.0, 0.0, 0.0, 200.0)
iex> :ok = Blendend.Style.Gradient.add_stop(grad, 0.0, Blendend.Style.Color.rgb!(255, 0, 0))
iex> :ok = Blendend.Style.Gradient.add_stop(grad, 1.0, Blendend.Style.Color.rgb!(0, 0, 255))
iex> rect 0, 0, 200, 200, gradient: grad

@spec linear!(number(), number(), number(), number()) :: t()

Same as linear/4, but on success, returns the gradient.

On failure, raises Blendend.Error.

@spec linear_from_stops(
  {number(), number(), number(), number()},
  [{float(), Blended.Style.Color.t()}],
  keyword()
) :: t()

Creates a linear gradient for the given line and adds stops in one go.

• line – {x0, y0, x1, y1}
• stops – list of {offset, color} where offset is 0.0..1.0

Options:

• :extend – :pad | :repeat | :reflect (default: :pad)

Returns a gradient resource suitable for use as fill or stroke.

@spec radial(number(), number(), number(), number(), number(), number()) ::
  {:ok, t()} | {:error, term()}

Creates a radial gradient.

The gradient is defined by:

• cx0, cy0, r0 – inner circle center and radius
• cx1, cy1, r1 – outer circle center and radius

On success, returns {:ok, gradient}.

On failure, returns {:error, reason}.

@spec radial!(number(), number(), number(), number(), number(), number()) :: t()

Same as radial/6, but returns the gradient directly.

On success, returns gradient.

On failure, raises Blendend.Error.

@spec radial_from_stops(
  {number(), number(), number(), number(), number(), number()},
  [{float(), Blended.Style.Color.t()}],
  keyword()
) :: t()

Creates a radial gradient and adds stops.

• cx0, cy0, r0 – inner circle center and radius
• cx1, cy1, r1 – outer circle center and radius
• stops – list of {offset, color}

Options:

• :extend – extend mode (:pad | :repeat | :reflect), defaults to :pad.

@spec reset_transform(t()) :: :ok | {:error, term()}

Resets a gradient’s transform to the identity matrix.

After calling this function, the gradient is mapped directly in canvas coordinates using the positions it was created with, without any extra rotation / scaling / translation.

On success, returns :ok.

On failure, returns {:error, reason}.

@spec reset_transform!(t()) :: t()

Same as reset_transform/1, but returns the gradient directly.

On success, returns gradient.

On failure, raises Blendend.Error.

@spec set_extend(t(), extend_mode()) :: :ok | {:error, term()}

Sets the extend mode of a gradient.

The extend mode controls how the gradient behaves outside the range covered by its stops (typically offsets 0.0..1.0). Supported modes:

• :pad – clamp to the edge colors (default)
• :repeat – repeat the gradient pattern
• :reflect – repeat the gradient, flipping direction every cycle

On success, returns :ok.

On failure, returns {:error, reason}.

@spec set_extend!(t(), extend_mode()) :: t()

Same as set_extend/2, but returns the gradient directly.

On success, returns gradient.

On failure, raises Blendend.Error.

@spec set_transform(t(), Blendend.Matrix2D.t()) :: :ok | {:error, term()}

Sets the transform matrix used when sampling a gradient.

The matrix is expressed in canvas coordinates and controls how the gradient is positioned, rotated, or scaled relative to the canvas.

On success, returns :ok.

On failure, returns {:error, reason}.

@spec set_transform!(t(), Blendend.Matrix2D.t()) :: t()

Same as set_transform/2, but returns the gradient directly.

On success, returns gradient.

On failure, raises Blendend.Error.