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

Applies the given matrix to the canvas' user transform.

This composes the current transform with the provided Blendend.Matrix2D.t(), using blend2d's BLContext::applyTransform. The canvas is mutated in-place.

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

Same as apply_transform/2, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

@spec blit_image(t(), Blendend.Image.t(), number(), number()) ::
  :ok | {:error, term()}

Blits an image onto the canvas at the given coordinates.

This copies the pixels of image so its top-left lands on {x, y} without scaling or tiling.

@spec blit_image(t(), Blendend.Image.t(), number(), number(), number(), number()) ::
  :ok | {:error, term()}

Blits an image scaled to the rectangle {x, y, w, h}.

The image is resampled to fit the destination rectangle.

@spec blit_image!(t(), Blendend.Image.t(), number(), number()) :: t()

Same as blit_image/4, but raises on failure and returns the canvas.

@spec blit_image!(t(), Blendend.Image.t(), number(), number(), number(), number()) ::
  t()

Same as blit_image/6, but raises on failure and returns the canvas.

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

Clears the entire canvas.

Without options, the canvas is cleared to whatever blend2d considers the default (transparent black).

With options, the call behaves like a full–canvas fill using the given style (for example a solid background color):

iex> c = Blendend.Canvas.new!(100, 100)
iex> :ok = Blendend.Canvas.clear(c, fill: Blendend.Style.Color.rgb!(255, 255, 255))

The exact shape of the options is the same as the shape–drawing functions in Blendend.Canvas.Fill.path/3.

@spec clear!(
  t(),
  keyword()
) :: t()

Same as clear/2, but returns the canvas on success.

On failure, raises Blendend.Error.

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

Creates a new canvas of size width × height pixels.

The dimensions are given in device pixels and must be positive integers.

Returns {:ok, canvas} on success, where canvas is a reference that you pass to the other functions in this module.

@spec new!(pos_integer(), pos_integer()) :: t()

Same as new/2, but returns the canvas directly.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Post-multiplies the canvas transform by a rotation of angle radians.

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

Same as post_rotate/2, but returns the canvas or raises on error.

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

Post-multiplies the canvas transform by a rotation of angle radians around {cx, cy}.

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

Same as post_rotate_at/4, but returns the canvas or raises on error.

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

Applies a translation after the current transform (post-translate).

M = M · T(x, y) (apply translation in the already-transformed/user space).

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

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

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

Resets the user transformation matrix to identity.

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

Same as reset_transform/1, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Restores the most recently saved context state.

This pops from the internal state stack created by save_state/1.

Returns :ok on success, or {:error, reason} if there is no state to restore or the context is invalid.

@spec restore_state!(t()) :: t()

Same as restore_state/1, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Rotates the canvas' user transform by angle radians.

The rotation is around the origin (0, 0) of the canvas coordinate system. This mutates the canvas in-place.

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

Same as rotate/2, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Rotates the canvas' user transform by angle radians around the point {cx, cy}.

Mutates the canvas in-place.

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

Same as rotate_at/4, but returns the canvas or raises on error.

@spec save(t(), String.t()) :: :ok | {:error, term()}

Saves the contents of a canvas to a png image file on disk.

The path is a filename (e.g. "out.png").

Returns :ok on success or {:error, reason} if the image could not be written.

Examples

iex> {:ok, c} = Blendend.Canvas.new(100, 100)
iex> :ok = Blendend.Canvas.clear(c)
iex> :ok = Blendend.Canvas.save(c, "test_output.png")

@spec save!(t(), String.t()) :: :ok

Same as save/2, but raises on failure.

On success, returns :ok.

On failure, raises Blendend.Error.

@spec save_qoi(t(), String.t()) :: :ok | {:error, term()}

Saves the contents of a canvas to an image file on disk in QOI format.

The path is a filename (e.g. "out.qoi").

Returns :ok on success or {:error, reason} if writing fails.

Examples

iex> {:ok, c} = Blendend.Canvas.new(100, 100)
iex> :ok = Blendend.Canvas.clear(c)
iex> :ok = Blendend.Canvas.save_qoi(c, "test_output.qoi")

@spec save_qoi!(t(), String.t()) :: :ok

Same as save_qoi/2, but raises on failure.

On success, returns :ok.

On failure, raises Blendend.Error.

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

Stores the current rendering context state on an internal stack.

This captures:

• current transform,
• clip,
• stroke/fill styles,
• and other blend2d context state.

You can later restore it with restore_state/1.

@spec save_state!(t()) :: t()

Same as save_state/1, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Scales the canvas' user transform by sx (x-axis) and sy (y-axis).

This mutates the canvas in-place.

Examples

{:ok, c} = Canvas.new(600, 400)
:ok = Canvas.scale(c, 2, 3)
# subsequent drawing is stretched (2x horizontally, 3x vertically)

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

Same as scale/3, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

@spec set_fill_rule(t(), :non_zero | :even_odd) :: :ok | {:error, term()}

Sets the fill rule for subsequent fill operations on the canvas.

Supported rules:

• :non_zero / :nonzero – non–zero winding rule
• :even_odd / :evenodd – even/odd rule

Returns :ok on success, or {:error, reason} if the rule is invalid.

@spec set_fill_rule!(t(), :non_zero | :even_odd) :: t()

Same as set_fill_rule/2, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Sets the user transformation matrix to matrix.

This replaces the current user transform.

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

Same as set_transform/2, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Skews (shears) the canvas' user transform by kx and ky radians along the X and Y axes.

This mutates the canvas in-place.

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

Same as skew/3, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Encodes the current canvas contents as PNG.

On success, returns {:ok, binary} where binary is a valid PNG stream.

On failure, returns {:error, reason}.

@spec to_png!(t()) :: binary()

Same as to_png/1, but returns the PNG binary directly.

On success, returns the PNG binary.

On failure, raises Blendend.Error.

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

Encodes the canvas as PNG and returns a Base64–encoded string.

On success, returns {:ok, base64} where base64 is the PNG encoded as a Base64 binary (no data URL prefix is added).

On failure, returns {:error, reason}.

@spec to_png_base64!(t()) :: binary()

Same as to_png_base64/1, but returns the Base64 string directly.

On success, returns the Base64-encoded PNG binary.

On failure, raises Blendend.Error.

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

Encodes the canvas as a QOI image and returns the raw .qoi binary.

On success returns {:ok, binary} where binary is the file contents you could write directly to image.qoi.

@spec to_qoi!(t()) :: binary()

Same as to_qoi/1, but returns the QOI binary directly.

On success, returns the QOI binary.

On failure, raises Blendend.Error.

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

Translates the canvas' user transform by (tx, ty) in user coordinates. M = T(x, y) · M (apply translation in user space before the current transform). This mutates the canvas in-place.

Examples

{:ok, c} = Canvas.new(600, 400)
:ok = Canvas.translate(c, 10, 5)
# all shapes drawn afterwards are offset by (10, 5)

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

Same as translate/3, but returns the canvas.

On success, returns canvas.

On failure, raises Blendend.Error.

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

Returns a snapshot of the canvas' current user transform.

On success, returns {:ok, matrix} where matrix is a Blendend.Matrix2D.t().

On failure, returns {:error, reason}.

@spec user_transform!(t()) :: Blendend.Matrix2D.t()

Same as user_transform/1, but returns the matrix directly.

On success, returns a Blendend.Matrix2D.t().

On failure, raises Blendend.Error.