# `Image.BlendMode`
[🔗](https://github.com/elixir-image/image/blob/v0.65.0/lib/image/enum/blend_mode.ex#L1)

Functions to define and validate the blending
modes that can be applied when composing images.

# `t`

```elixir
@type t() ::
  :colour_burn
  | :colour_dodge
  | :saturate
  | :dest_atop
  | :dest_out
  | :dest_in
  | :dest_over
  | :atop
  | :over
  | :exclusion
  | :soft_light
  | :hard_light
  | :lighten
  | :darken
  | :overlay
  | :screen
  | :multiply
  | :dest
  | :source
  | :difference
  | :add
  | :xor
  | :out
  | :in
  | :clear
```

Blend mode to use when compositing images. See `Image.compose/3`.

* `:over` the image shows what you would expect if you held two
  semi-transparent slides on top of each other. This is the default
  when composing images
* `:clear` where the second image is drawn, the first is removed
* `:source` the second image is drawn as if nothing were below
* `:in` the first image is removed completely, the second is only
  drawn where the first was
* `:out` the second is drawn only where the first isn't
* `:atop` this leaves the first image mostly intact, but mixes
  both images in the overlapping area
* `:dest` leaves the first image untouched, the second is discarded
  completely
* `:dest_over` like `:over`, but swaps the arguments
* `:dest_in` like `:in`, but swaps the arguments
* `:dest_out` like `:out`, but swaps the arguments
* `:dest_atop` like `:atop`, but swaps the arguments
* `:xor` something like a difference operator
* `:add` a bit like adding the two images
* `:saturate` a bit like the darker of the two
* `:multiply` at least as dark as the darker of the two inputs
* `:screen` at least as light as the lighter of the inputs
* `:overlay` multiplies or screens colors, depending on the lightness
* `:darken` the darker of each component
* `:lighten` the lighter of each component
* `:colour_dodge` brighten first by a factor second
* `:colour_burn` darken first by a factor of second
* `:hard_light` multiply or screen, depending on lightness
* `:soft_light` darken or lighten, depending on lightness
* `:difference` difference of the two
* `:exclusion` somewhat like :difference, but lower-contrast

# `default_blend_mode`

Returns the default blend mode

### Example

    iex> Image.BlendMode.default_blend_mode
    :VIPS_BLEND_MODE_OVER

# `known_blend_modes`

Returns the known blending modes.

See `t:Image.BlendMode.t/0` for a description
of each mode.

# `validate_blend_mode`

```elixir
@spec validate_blend_mode(t() | nil) :: {:ok, atom()} | {:error, Image.error()}
```

Normalizes and validates a blend mode.

### Argument

* `blend_mode` is one of `Image.BlendMode.known_blend_modes/0`
  as either a `t:String.t/0` or an `atom`.

### Returns

* `{:ok, atom_blend_mode}` where `atom_blend_mode` is
  a valid blend mode for `libvips`

* `{:error, reason}`

### Examples

    iex> Image.BlendMode.validate_blend_mode :clear
    {:ok, :VIPS_BLEND_MODE_CLEAR}

    iex> Image.BlendMode.validate_blend_mode "Over"
    {:ok, :VIPS_BLEND_MODE_OVER}

    iex> Image.BlendMode.validate_blend_mode :VIPS_BLEND_MODE_XOR
    {:ok, :VIPS_BLEND_MODE_XOR}

    iex> Image.BlendMode.validate_blend_mode :woops
    {:error, {:error, %Image.Error{message: "Unknown blend mode. Found :woops", reason: "Unknown blend mode. Found :woops"}}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*