.. index::
   single: COMPOSITE

.. _composite:

*****************************************************************************
 COMPOSITE
*****************************************************************************

Background
==========

The `COMPOSITE` block is used to achieve blending effects with
MapServer.

Some cartographic renderings benefit from the addition of advanced
blending modes, as explained in detail in `Blend Modes`_.  This
functionality is essential for more pleasant renderings of raster
hillshadings over vector surfaces.  It is also useful for simulating
different kinds of overprinting effects.

.. seealso::

   :ref:`rfc113`

Performance is affected by advanced blending (all modes except
`src-over`).

Parameters
==========

.. index::
   pair: COMPOSITE; OPACITY
    
.. _opacity:

OPACITY [integer]
    Sets the opacity level (or the inability to see through the layer) of all
    classed pixels for a given layer.  A value of 100 is opaque and 
    0 is fully transparent.

.. index::
	pair: COMPOSITE; COMPOP
   
COMPOP [string]
    Name of the compositing operator to use when blending the temporary image
    onto the main map image. See `http://en.wikipedia.org/wiki/Blend_modes`.
    The default compositing operator is "src-over".

    Available operators are:

    - clear
       Both the color and the alpha of the destination are cleared.
       Neither the source nor the destination are used. This is an
       unusual compose method that essentially ignores the overlay
       image completely, and just clears the background image.
    - color-burn
       Divides the inverted bottom layer by the top layer, and then
       inverts the result. This darkens the top layer increasing the
       contrast to reflect the color of the bottom layer. The darker
       the bottom layer, the more its color is used.
    - color-dodge
       Divides the bottom layer by the inverted top layer. This
       lightens the bottom layer depending on the value of the top
       layer: the brighter the top layer, the more its color affects
       the bottom layer. Blending any color with white gives
       white. Blending with black does not change the image.
    - contrast*
    - darken
       Creates a image that retains the smallest components of the
       foreground and background pixels. If the foreground pixel has
       the components r1, g1, and b1, and the background has r2, g2,
       b2, the resultant pixel is [min(r1,r2), min(g1,g2), min(b1,b2)]
    - difference
       Subtracts the bottom layer from the top layer or the other way
       round, to always get a positive value. Blending with black
       produces no change, as values for all colors are 0. (The RGB
       value for black is 0,0,0.) Blending with white inverts the
       picture.
    - dst
       This operator does nothing. The source, or overlay image, is
       completely ignored and the destination, or background image, is
       left unchanged. The method's real use is as a means of 'turning
       off' an alpha composition operation in other image operators.
    - dst-atop
       The part of the source lying inside of the destination is
       composited onto the destination.
    - dst-in
       The part of the destination lying inside of the source replaces
       the destination. Areas not overlaid are cleared. Will remove
       the overlay image's shape from the background image like a
       cookie cutter which cuts out a cookie's shape from cookie dough
       (result is the cookie).
    - dst-out
       The part of the destination lying outside of the source
       replaces the destination. Using the 'cookie dough' metaphor of
       'dst-in' the result of the 'dst-out' method is the dough that
       was left behind once a cookie has been cut out. It can be used
       to cut holes, or take bites out of the background image, using
       the shape of the overlay. Any color in the overlay is again
       completely ignored.
    - dst-over
       The destination is composited over the source and the result
       replaces the destination.  Equivalent to placing the source
       overlay image 'under' the destination. The result is that only
       the parts of our source or overlay image not hidden by the
       destination or background image will be visible as they peek
       out from underneath.
    - exclusion
       This is sort of an averaged difference. White on white will
       produce black (no difference), the same with black on
       black. However grey on grey will produce a grey result. White
       and black naturally still produce white (maximum difference).
    - hard-light
       Hard Light is a combination of Multiply and Screen, each at
       half strength. Hard Light effects the blend layer's
       relationship to the base layer in the same way Overlay effects
       the base layer's relationship to the blend layer.
    - invert*
    - invert-rgb*
    - lighten
       Lighten has the opposite action of Darken. It selects the
       maximum of each component from the foreground and background
       pixels. If the foreground pixel has the components r1, g1, and
       b1, and the background has r2, g2, b2, the resultant pixel is
       [max(r1,r2), max(g1,g2), max(b1,b2)]
    - minus*
       Subtract the colors in the source image from the destination
       image. When transparency is involved, opaque areas is
       subtracted from any destination opaque areas.
    - multiply
       A simple multiply of the two images. Its formula is: [Src *
       Dest]. This means that if one of the images is pure white, the
       result will be the other image. On the other hand if one image
       is black the result will be black. Between these extremes one
       image will darken the destination image by the amount
       given. Note that 'Multiply' will only darken an image, it will
       never brighten it. That is, it 'attenuates' an image toward
       black, which makes this compose method a 'Burn' style of
       composition.
    - overlay
       Overlay combines Multiply and Screen blend modes, at half
       strength. The parts of the top layer where the base layer is
       light become lighter, the parts where the base layer is dark
       become darker. Areas where the top layer are mid grey are
       unaffected.
    - plus
       The source is added to the destination and replaces the
       destination. This operator is useful for averaging or a
       controlled merger of two images, rather than a direct overlay.
    - screen
       The source and destination are complemented and then multiplied
       and then replace the destination. The resultant color is always
       at least as light as either of the two constituent
       colors. Screening any color with white produces
       white. Screening any color with black leaves the original color
       unchanged.
    - soft-light
       Soft light is most closely related to Overlay and is only
       similar to Hard Light by name. Will add highlights and shadows
       to an existing color image. However, the colors of the
       destination image are modified to produce a softer contrast,
       and smoother gradient in lighting effects.
    - src
       The source is copied to the destination. The destination is not
       used as input, though it is cleared. This operator completely
       replaces the background image with the overlay image. The
       colors and transparency in the background are completely junked
       leaving a blank image the same size as the original destination
       over which is applied the source image.
    - src-atop
       The part of the source lying inside of the destination is
       composited onto the destination. Like 'src-over' but limits the
       result to the original shape of the background image. In other
       words, the alpha channel on the destination is unchanged but
       the image colors are overlaid by any non-transparent parts of
       the source image. If the background image is fully opaque (no
       transparency), this operation will act exactly like the normal
       'src-over' composition. It only differs when the background
       contains transparency which also clips the overlay. What makes
       this useful is for overlaying lighting and shading effects that
       are limited to the object (shape) of the destination.
    - src-in
       The part of the source lying inside of the destination replaces
       the destination.
    - src-out
       The part of the source lying outside of the destination
       replaces the destination.
    - src-over
       The source is composited over the destination. This is the
       default composite option if no other is specified.
    - xor
       The part of the source that lies outside of the destination is
       combined with the part of the destination that lies outside of
       the source. Source or Destination, but not both.

    Operators marked with a star (*) will only be supported when using an AGG
    backends *and* when pixman support is not enabled, and will fall back to
    "src-over" when this is not the case.

Usage
=====

Simple transparency / opacity is achieved by only specifying the
`OPACITY` parameter (this achieves the same effect as the legacy
`LAYER` `OPACITY` parameter):

.. code-block:: mapfile

  LAYER
    COMPOSITE
      OPACITY 70
    END # COMPOSITE
  ...
  END # LAYER

The darkening effect is achieved by adding the `COMPOP` parameter with
the value `darken`:

.. code-block:: mapfile

  LAYER
    COMPOSITE
      OPACITY 100
      COMPOP "darken"
    END # COMPOSITE
  ...
  END # LAYER


.. _`Blend Modes`: http://en.wikipedia.org/wiki/Blend_modes
