module Prawn::SoftMask

# File lib/prawn/soft_mask.rb, line 42
def soft_mask(&block)
  renderer.min_version(1.4)

  group_attrs = ref!(
    Type: :Group,
    S: :Transparency,
    CS: :DeviceRGB,
    I: false,
    K: false,
  )

  group = ref!(
    Type: :XObject,
    Subtype: :Form,
    BBox: state.page.dimensions,
    Group: group_attrs,
  )

  state.page.stamp_stream(group, &block)

  mask = ref!(
    Type: :Mask,
    S: :Luminosity,
    G: group,
  )

  g_state = ref!(
    Type: :ExtGState,
    SMask: mask,

    AIS: false,
    BM: :Normal,
    OP: false,
    op: false,
    OPM: 1,
    SA: true,
  )

  registry_key = {
    bbox: state.page.dimensions,
    mask: [group.stream.filters.normalized, group.stream.filtered_stream],
    page: state.page_count,
  }.hash

  if soft_mask_registry[registry_key]
    renderer.add_content("/#{soft_mask_registry[registry_key]} gs")
  else
    masks = page.resources[:ExtGState] ||= {}
    id = masks.empty? ? 'GS1' : masks.keys.max.succ
    masks[id] = g_state

    soft_mask_registry[registry_key] = id

    renderer.add_content("/#{id} gs")
  end
end

Apply soft mask.

You must group soft mask and graphics it’s applied to under ‘save_graphics_state` because soft mask is a part of graphic state in PDF.

Note that soft mask is applied only to the following content in the graphic state. Anything that comes before ‘soft_mask` is drawn without mask.

Conceptually, soft mask is an alpha channel. Luminosity of the drawing in the soft mask defines the transparency of the drawing the mask is applied to. 0.0 mask luminosity (“black”) results in a fully opaque target image and 1.0 mask luminosity (“white”) results in a fully transparent target image. Grey values result in some semi-transparent target image.

Note: you can use color in mask drawings but it makes harder to reason about the resulting value of alpha channel as it requires an additional luminosity calculation. However, this also allows achieving some advanced artistic effects (e.g. full-color photos in masks to get an effect similar to double exposure).

@example

pdf.save_graphics_state do
  pdf.soft_mask do
    pdf.fill_color "444444"
    pdf.fill_polygon [0, 40], [60, 10], [120, 40], [60, 68]
  end
  pdf.fill_color '000000'
  pdf.fill_rectangle [0, 50], 120, 68
end

@yield Mask content. @return [void]