Provide images to complement the textual specification of gradient fills

Author: henrikt-ma

chapters/annotations.tex

@@ -1009,6 +1009,7 @@ \subsubsection{Graphical Properties}\label{graphical-properties}
 
 The attributes \lstinline!HorizontalCylinder!, \lstinline!VerticalCylinder! and \lstinline!Sphere! specify gradients that represent a horizontal cylinder, a vertical cylinder and a sphere, respectively.
 The gradient goes from line color to fill color.
+Examples of gradient fills are given in \cref{fig:cylinder-gradient,fig:sphere-gradient,fig:sphere-gradient}.
 
 The border pattern attributes \lstinline!Raised!, \lstinline!Sunken! and \lstinline!Engraved! represent frames which are rendered in a tool-dependent way --- inside the extent of the filled shape.
 
@@ -1058,6 +1059,70 @@ \subsubsection{Graphical Properties}\label{graphical-properties}
 \annotationindex{FilledShape}
 The extent/points of the filled shape describe the theoretical zero-thickness filled shape, and the actual rendered border is then half inside and half outside the extent.
 
+\begin{example}
+Gradient fill patterns.
+
+\Cref{fig:cylinder-gradient} shows the use of \lstinline!FillPattern.HorizontalCylinder!.
+Since the gradient fill is determined before applying rotation, the line where \lstinline!fillColor! is attained gets rotated together with the rectangle.
+It is also seen that the \lstinline!lineColor! is attained where the ellipse touches the the enclosing rectangle.
+
+\Cref{fig:sphere-gradient} shows the use of \lstinline!FillPattern.Sphere! on a \lstinline!Rectangle!.
+It is seen that the \lstinline!fillColor! is attained at the center of the enclosing ellipse (coinciding with the center of the rectangle), and that the \lstinline!lineColor! is attained at the corners of the rectangle, which all lie on the enclosing ellipse.
+If the rectangle would have had rounded corners (by specifying a positive \lstinline!radius!), the geometry of the gradient fill would not change, meaning that the \lstinline!lineColor! would not be attained.
+While the \lstinline!FillPattern.Sphere! name suggests that it is used to make circles look like spheres, this example also illustrates how it can be used to give a less flat look to other shapes.
+
+\Cref{fig:sphere-gradient-triangle} shows the use of \lstinline!FillPattern.Sphere! on a \lstinline!Polygon!.
+Determining the minimal area enclosing ellipse is a non-trivial but computationally tractable problem.
+In practice, it will be difficult for the naked eye to tell the difference between a gradient based on the minimal area enclosing ellipse, and a gradient based on a nearby ellipse, especially if the \lstinline!fillColor! is used in the areas which fail to be enclosed by the ellipse.
+Hence, accurate application of the gradient fill is a quality of implementation.
+\end{example}
+
+\begin{figure}[H]
+  \begin{center}
+% Workaround for unreliable support for linear gradients in at least some popular PDF viewers (Apple).
+\ifpdf
+    \includegraphics{cylinder-gradient.png}
+\else
+    \includegraphics{cylinder-gradient}
+\fi
+  \end{center}
+  \caption{
+    Applying \lstinline!FillPattern.HorizontalCylinder! to an \lstinline!Ellipse! with \lstinline!startAngle!, \lstinline!endAngle!, \lstinline!rotation!, and \lstinline!closure = EllipseClosure.Chord!.
+    The \lstinline!fillColor! (darker) and the \lstinline!lineColor! (brighter) are shown in two circles behind the ellipse.
+    The dashed line shows the minimal enclosing axis-aligned rectangle, after rotating it together with the ellipse.
+    Since lighting and reflective properties of the imaginary cylinder are not defined by the specification, many details of the rendering are tool specific.
+    Here, a more shiny cylinder is shown to the left, and a more matte cylinder to the right.
+  }
+  \label{fig:cylinder-gradient}
+\end{figure}
+
+\begin{figure}[H]
+  \begin{center}
+% Warning: Is there really no need for a workaround here, similar to the one in \cref{fig:cylinder-gradient}?
+    \includegraphics{sphere-gradient}
+  \end{center}
+  \caption{
+    Applying \lstinline!FillPattern.Sphere! to a \lstinline!Rectangle! with \lstinline!rotation!.
+    The \lstinline!fillColor! is shown in the triangle on top of the rectangle, and the \lstinline!lineColor! is shown in the circle behind one of the rectangle's corners.
+    The dashed line shows the minimal area enclosing ellipse, after rotating it together with the rectangle.
+    Similar to the cylinder gradients, many details of the rendering are tool specific.
+  }
+  \label{fig:sphere-gradient}
+\end{figure}
+
+\begin{figure}[H]
+  \begin{center}
+% Warning: Is there really no need for a workaround here, similar to the one in \cref{fig:cylinder-gradient}?
+    \includegraphics{sphere-gradient-triangle}
+  \end{center}
+  \caption{
+    Applying \lstinline!FillPattern.Sphere! to a \lstinline!Polygon! with three points.
+    The dashed line shows the minimal area enclosing ellipse.
+    In addition to tool-specific design choices when gradient fills are applied to simpler shapes, application to a \lstinline!Polygon! also involves a quality of implementation aspect.
+  }
+  \label{fig:sphere-gradient-triangle}
+\end{figure}
+
 \subsection{Component Instance}\label{component-instance}
 
 A component instance can be represented within the diagram and/or icon layer of the enclosing class.