\section{Decoration: Soft Clipping}

\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}
