Images with examples of gradient fills

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.
@@ -1566,7 +1631,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
 \begin{semantics}
 The \lstinline{preferredView} annotation defines the default view when selecting the class.
 The value \lstinline!"info"! means class documentation (``information''), \lstinline!"diagram"! means diagram view, \lstinline!"icon"! means icon view, and \lstinline!"text"! means Modelica source code (``text'').
-If not specified the default view is tool-specific.
+If not specified the default view is tool specific.
 \end{semantics}
 \end{annotationdefinition}
 

chapters/functions.tex

@@ -1700,7 +1700,7 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve
 
 If {\lstinline!Inline = false!}, the model developer proposes to not inline the function.
 
-The default for inlining is tool-specific.
+The default for inlining is tool specific.
 
 \begin{nonnormative}
 {\lstinline!Inline = true!} is for example used in {\lstinline!Modelica.Mechanics.MultiBody.Frames!} and in functions of {\lstinline!Modelica.Media!} to have no overhead for function calls such as resolving a vector in a different coordinate system and at the same time the function can be analytically differentiated, e.g., for index reduction needed for mechanical systems.
@@ -1723,7 +1723,7 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve
 
 If {\lstinline!LateInline = false!}, the model developer proposes to not inline the function after symbolic transformations have been performed.
 
-The default for late inlining is tool-specific.
+The default for late inlining is tool specific.
 In particular, tools may automatically delay inlining in order to take advantage of function annotations for derivatives and inverses.
 
 {\lstinline!Inline = true, LateInline = false!} is identical to {\lstinline!Inline = true!}.