Blendend.Canvas.Stroke (blendend v0.2.0)

View Source

Stroke functions for Blendend.Canvas to stroke a geometry on the canvas with a style (color, gradient or pattern).

Prefer the Blendend.Draw macros; they call into this module under the hood.

use Blendend.Draw

draw 240, 160, "stroke_example.png" do
  clear fill: rgb(250, 250, 250)

  line 20, 20, 220, 140, stroke: rgb(30, 30, 30), stroke_width: 4
  circle 120, 80, 40, stroke: rgb(200, 60, 60), stroke_width: 3
end

Summary

Types

canvas()
opts()

Functions

arc(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

Strokes an elliptical arc.

arc!(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

Same as arc/8, but returns the canvas and raises on error.

box(canvas, x0, y0, x1, y1, opts \\ [])

Strokes a box {x0, y0, x1, y1}.

box!(canvas, x0, y0, x1, y1, opts \\ [])

Same as box/6, but returns the canvas and raises on error.

box_array(canvas, boxes, opts \\ [])

Strokes multiple boxes in one call.

box_array!(canvas, boxes, opts \\ [])

Same as box_array/3, but returns the canvas and raises on error.

chord(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

Strokes a chord/segment of an ellipse (arc + straight line between endpoints).

chord!(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

Same as chord/8, but returns the canvas and raises on error.

circle(canvas, cx, cy, r, opts \\ [])

Strokes a circle at (cx, cy) with radius r.

circle!(canvas, cx, cy, r, opts \\ [])

Same as circle/5, but returns the canvas and raises on error.

ellipse(canvas, cx, cy, rx, ry, opts \\ [])

Strokes an ellipse at (cx, cy) with radii rx and ry.

ellipse!(canvas, cx, cy, rx, ry, opts \\ [])

Same as ellipse/6, but returns the canvas and raises on error.

line(canvas, x0, y0, x1, y1, opts \\ [])

Strokes a line from (x0, y0) to (x1, y1).

line!(canvas, x0, y0, x1, y1, opts \\ [])

Same as line/6, but returns the canvas and raises on error.

path(canvas, path, opts \\ [])

Strokes path on canvas using the given stroke options.

path!(canvas, path, opts \\ [])

Same as path/3, but returns the canvas and raises on error.

pie(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

Strokes a pie/sector shape.

pie!(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

Same as pie/8, but returns the canvas and raises on error.

polygon(canvas, points, opts \\ [])

Strokes a closed polygon given as a list of {x, y} points.

polygon!(canvas, points, opts \\ [])

Same as polygon/3, but returns the canvas and raises on error.

polyline(canvas, points, opts \\ [])

Strokes a polyline given as a list of {x, y} points.

polyline!(canvas, points, opts \\ [])

Same as polyline/3, but returns the canvas and raises on error.

rect(canvas, x, y, w, h, opts \\ [])

Strokes a rectangle (x, y, w, h).

rect!(canvas, x, y, w, h, opts \\ [])

Same as rect/6, but returns the canvas and raises on error.

rect_array(canvas, rects, opts \\ [])

Strokes multiple rectangles in one call.

rect_array!(canvas, rects, opts \\ [])

Same as rect_array/3, but returns the canvas and raises on error.

round_rect(canvas, x, y, w, h, rx, ry, opts \\ [])

Strokes a rounded rectangle (x, y, w, h) with corner radii (rx, ry).

round_rect!(canvas, x, y, w, h, rx, ry, opts \\ [])

Same as round_rect/8, but returns the canvas and raises on error.

triangle(canvas, x0, y0, x1, y1, x2, y2, opts \\ [])

Strokes a triangle specified by its three vertices.

triangle!(canvas, x0, y0, x1, y1, x2, y2, opts \\ [])

Same as triangle/8, but returns the canvas and raises on error.

utf8_text(canvas, font, x, y, text, opts \\ [])

Strokes a UTF-8 text string on canvas using font.

utf8_text!(canvas, font, x, y, text, opts \\ [])

Same as utf8_text/6, but returns the canvas and raises on error.

Types

canvas()

@type canvas() :: Blendend.Canvas.t()

opts()

@type opts() :: keyword()

Functions

arc(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

@spec arc(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) :: :ok | {:error, term()}

Strokes an elliptical arc.

Parameters describe an ellipse centered at (cx, cy) with radii rx, ry and angles start_angle / sweep_angle in radians.

Uses the same stroke options as path/3.

arc!(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

@spec arc!(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) :: canvas()

Same as arc/8, but returns the canvas and raises on error.

box(canvas, x0, y0, x1, y1, opts \\ [])

@spec box(canvas(), number(), number(), number(), number(), opts()) ::
  :ok | {:error, term()}

Strokes a box {x0, y0, x1, y1}.

Uses the same stroke options as path/3.

box!(canvas, x0, y0, x1, y1, opts \\ [])

@spec box!(canvas(), number(), number(), number(), number(), opts()) :: canvas()

Same as box/6, but returns the canvas and raises on error.

box_array(canvas, boxes, opts \\ [])

@spec box_array(canvas(), [{number(), number(), number(), number()}], opts()) ::
  :ok | {:error, term()}

Strokes multiple boxes in one call.

boxes is a list of {x0, y0, x1, y1} tuples.

Uses the same stroke options as path/3.

box_array!(canvas, boxes, opts \\ [])

@spec box_array!(canvas(), [{number(), number(), number(), number()}], opts()) ::
  canvas()

Same as box_array/3, but returns the canvas and raises on error.

chord(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

@spec chord(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) :: :ok | {:error, term()}

Strokes a chord/segment of an ellipse (arc + straight line between endpoints).

Uses the same stroke options as path/3.

chord!(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

@spec chord!(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) :: canvas()

Same as chord/8, but returns the canvas and raises on error.

circle(canvas, cx, cy, r, opts \\ [])

@spec circle(canvas(), number(), number(), number(), opts()) :: :ok | {:error, term()}

Strokes a circle at (cx, cy) with radius r.

Uses the same stroke options as path/3.

circle!(canvas, cx, cy, r, opts \\ [])

@spec circle!(canvas(), number(), number(), number(), opts()) :: canvas()

Same as circle/5, but returns the canvas and raises on error.

ellipse(canvas, cx, cy, rx, ry, opts \\ [])

@spec ellipse(canvas(), number(), number(), number(), number(), opts()) ::
  :ok | {:error, term()}

Strokes an ellipse at (cx, cy) with radii rx and ry.

Uses the same stroke options as path/3.

ellipse!(canvas, cx, cy, rx, ry, opts \\ [])

@spec ellipse!(canvas(), number(), number(), number(), number(), opts()) :: canvas()

Same as ellipse/6, but returns the canvas and raises on error.

line(canvas, x0, y0, x1, y1, opts \\ [])

@spec line(canvas(), number(), number(), number(), number(), opts()) ::
  :ok | {:error, term()}

Strokes a line from (x0, y0) to (x1, y1).

Uses the same stroke options as path/3.

line!(canvas, x0, y0, x1, y1, opts \\ [])

@spec line!(canvas(), number(), number(), number(), number(), opts()) :: canvas()

Same as line/6, but returns the canvas and raises on error.

path(canvas, path, opts \\ [])

@spec path(canvas(), Blendend.Path.t(), opts()) :: :ok | {:error, term()}

Strokes path on canvas using the given stroke options.

path must be a Blendend.Path.t().

Stroke options

The opts keyword list controls the stroke appearance. Common keys:

  • :stroke

    • stroke brush (solid color), from Blendend.Style.Color.* – gradient stroke brush, from Blendend.Style.Gradient.* – pattern stroke brush, from Blendend.Style.Pattern.create/1 (default is black color)

  • :width – stroke width as a float (default: 1.0)

  • :cap – cap style at both ends, or :start_cap / :end_cap to set independently:

    • :butt (default)
    • :square
    • :round
    • :round_rev
    • :triangle
    • :triangle_rev

  • :join – join style between segments:

    • :miter_clip (default)
    • :miter_bevel
    • :miter_round
    • :bevel
    • :round

  • :miter_limit – miter limit as float (only for :miter joins)

  • :comp_op – compositing operator atom. See Blendend.Canvas.Fill.path/3 for viable options.

  • :alpha - extra stroke opacity multiplier (values are 0.0..1.0) If you omit brush options, default values are set.

Examples

alias Blendend.{Canvas, Path, Style}
alias Blendend.Canvas.Stroke

canvas = Canvas.new!(200, 200)

path =
  Path.new!()
  |> Path.move_to!(20, 20)
  |> Path.line_to!(180, 180)

:ok =
  Stroke.path(canvas, path,
    stroke_color: Style.color(0, 0, 0),
    width: 2.0,
    cap: :round
  )

On success, returns :ok.

On failure, returns {:error, reason}.

path!(canvas, path, opts \\ [])

@spec path!(canvas(), Blendend.Path.t(), opts()) :: canvas()

Same as path/3, but returns the canvas and raises on error.

On success, returns canvas.

On failure, raises Blendend.Error.

pie(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

@spec pie(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) :: :ok | {:error, term()}

Strokes a pie/sector shape.

Same parameters as chord/8, but the arc is also connected back to the ellipse center.

Uses the same stroke options as path/3.

pie!(canvas, cx, cy, rx, ry, start_angle, sweep_angle, opts \\ [])

@spec pie!(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) :: canvas()

Same as pie/8, but returns the canvas and raises on error.

polygon(canvas, points, opts \\ [])

@spec polygon(canvas(), [{number(), number()}], opts()) :: :ok | {:error, term()}

Strokes a closed polygon given as a list of {x, y} points.

Uses the same stroke options as path/3.

polygon!(canvas, points, opts \\ [])

@spec polygon!(canvas(), [{number(), number()}], opts()) :: canvas()

Same as polygon/3, but returns the canvas and raises on error.

polyline(canvas, points, opts \\ [])

@spec polyline(canvas(), [{number(), number()}], opts()) :: :ok | {:error, term()}

Strokes a polyline given as a list of {x, y} points.

Uses the same stroke options as path/3.

polyline!(canvas, points, opts \\ [])

@spec polyline!(canvas(), [{number(), number()}], opts()) :: canvas()

Same as polyline/3, but returns the canvas and raises on error.

rect(canvas, x, y, w, h, opts \\ [])

@spec rect(canvas(), number(), number(), number(), number(), opts()) ::
  :ok | {:error, term()}

Strokes a rectangle (x, y, w, h).

Uses the same stroke options as path/3.

rect!(canvas, x, y, w, h, opts \\ [])

@spec rect!(canvas(), number(), number(), number(), number(), opts()) :: canvas()

Same as rect/6, but returns the canvas and raises on error.

rect_array(canvas, rects, opts \\ [])

@spec rect_array(canvas(), [{number(), number(), number(), number()}], opts()) ::
  :ok | {:error, term()}

Strokes multiple rectangles in one call.

rects is a list of {x, y, w, h} tuples.

Uses the same stroke options as path/3.

rect_array!(canvas, rects, opts \\ [])

@spec rect_array!(canvas(), [{number(), number(), number(), number()}], opts()) ::
  canvas()

Same as rect_array/3, but returns the canvas and raises on error.

round_rect(canvas, x, y, w, h, rx, ry, opts \\ [])

@spec round_rect(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) ::
  :ok | {:error, term()}

Strokes a rounded rectangle (x, y, w, h) with corner radii (rx, ry).

Uses the same stroke options as path/3.

round_rect!(canvas, x, y, w, h, rx, ry, opts \\ [])

@spec round_rect!(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) :: canvas()

Same as round_rect/8, but returns the canvas and raises on error.

triangle(canvas, x0, y0, x1, y1, x2, y2, opts \\ [])

@spec triangle(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) ::
  :ok | {:error, term()}

Strokes a triangle specified by its three vertices.

Uses the same stroke options as path/3.

triangle!(canvas, x0, y0, x1, y1, x2, y2, opts \\ [])

@spec triangle!(
  canvas(),
  number(),
  number(),
  number(),
  number(),
  number(),
  number(),
  opts()
) :: canvas()

Same as triangle/8, but returns the canvas and raises on error.

utf8_text(canvas, font, x, y, text, opts \\ [])

@spec utf8_text(
  canvas(),
  Blendend.Text.Font.t(),
  number(),
  number(),
  String.t(),
  opts()
) :: :ok | {:error, term()}

Strokes a UTF-8 text string on canvas using font.

Draws the text with its origin at (x, y).

opts reuses the same stroke options as path/3 (:stroke_color, :stroke_width, etc.).

On success, returns :ok.

On failure, returns {:error, reason}.

utf8_text!(canvas, font, x, y, text, opts \\ [])

@spec utf8_text!(
  canvas(),
  Blendend.Text.Font.t(),
  number(),
  number(),
  String.t(),
  opts()
) :: canvas()

Same as utf8_text/6, but returns the canvas and raises on error.

On success, returns canvas.

On failure, raises Blendend.Error.