
\section{Decoration: Soft Clipping}

\begingroup
\def\pgfplotsmanualcurlibrary{decorations.softclip}

\begin{pgfplotslibrary}{decorations.softclip}
    Activates |decoration=softclip|.

    A ``soft clip'' is a part of an input path, namely that part which is
    inside of the ``clip path''. This is typically known as clipping: you set
    |\clip |\meta{path}|;| and all following paths are clipped against
    \meta{path}. Soft-clipping is similar, but instead of installing a
    low-level clip path, it modifies the input path in a way such that only
    parts inside of \meta{path} remain. This makes a difference if decorations
    are to be applied. It also makes a difference for |fill between/soft clip|.

    Note that this library is loaded implicitly by the |fillbetween| library in
    order to address its |fill between/soft clip| key.

    \textsc{Attention}: this library is considered to be experimental. It will
    work for paths which are similar to a plot, i.e.\@ paths which do not
    intersect themselves and which have a clear direction. The library might
    fail, in general.

    An application could be to draw a path twice, but the second time should
    only affect portions of the path:
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \draw [
        postaction={decorate,draw,ultra thick},
        decoration={
            soft clip,soft clip path={
                (1.5,-1) rectangle (4,2)
            },
        },
    ]
        (0,0) -- (1,1) -- (2,1) -- (3,0);
\end{tikzpicture}
\end{codeexample}

    The |soft clip| feature is tailored for use with |fill between|. Please
    refer to the documentation of |fill between/soft clip| for more examples
    and explanation on soft-clipping.
\end{pgfplotslibrary}

\begin{key}{/pgf/decoration/soft clip path=\meta{corner1} rectangle \meta{corner2}}
    Assigns the path which is to be used for the |soft clip| decoration. This
    argument is mandatory in order to apply a |soft clip| decoration.

    Please refer to the documentation of |fill between/soft clip| for details;
    it has the same syntax and a similar motivation.
\end{key}

\begin{stylekey}{/pgf/decoration/every soft clipped path}
    A style which is applied just before the reduced path is generated.
\end{stylekey}
\endgroup
