Committing P0267R4.

Author: mikebmcl

papers/P0267R4.pdf

@@ -61,25 +61,25 @@
 \item If the result of \tcode{b.type()} is \tcode{brush_type::radial} then \tcode{b} is a \term{radial gradient brush}.
 \end{enumerate}
 
-\rSec2 [brush.sampling.color] {Sampling from a color brush}
+\rSec2 [brush.sampling.color] {Sampling from a solid color brush}
 
 \pnum
-When \tcode{b} is a color brush, then when sampling from \tcode{b}, the visual data returned shall always be the visual data equivalent \tcode{rgba_code} which was passed in when \tcode{b} was created, regardless of the point which is to be sampled and regardless of the return values of \tcode{b.wrap_mode()}, \tcode{b.filter()}, and \tcode{b.matrix()}.
+When \tcode{b} is a solid color brush, then when sampling from \tcode{b}, the visual data returned shall always be the visual data equivalent \tcode{bgra_color} used to construct \tcode{b}, regardless of the point which is to be sampled and regardless of the return values of Wrap Mode, Filter, and Matrix.
 
 \rSec2 [brush.sampling.linear] {Sampling from a linear gradient brush}
 
 \pnum
-When \tcode{b} is a linear gradient brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the rendered linear gradient, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords} and the rendered linear gradient is created as specified by \ref{gradients.linear} and \ref{gradients.sampling}, taking into account the value of \tcode{b.wrap_mode()}.
+When \tcode{b} is a linear gradient brush, when sampling point \tcode{pt}, where \tcode{pt} is the return value of calling the \tcode{transform_point} member function of Matrix using the requested point, from \tcode{b}, the visual data returned shall be as specified by \ref{gradients.linear} and \ref{gradients.sampling}.
 
 \rSec2 [brush.sampling.radial] {Sampling from a radial gradient brush}
 
 \pnum
-When \tcode{b} is a radial gradient brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the rendered radial gradient, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords} and the rendered radial gradient is created as specified by \ref{gradients.radial} and \ref{gradients.sampling}, taking into account the value of \tcode{b.wrap_mode()}.
+When \tcode{b} is a radial gradient brush, when sampling point \tcode{pt}, where \tcode{pt} is the return value of calling the \tcode{transform_point} member function of Matrix using the requested point, from \tcode{b}, the visual data returned shall be as specified by \ref{gradients.radial} and \ref{gradients.sampling}.
 
 \rSec2 [brush.sampling.surface] {Sampling from a surface brush}
 
 \pnum
-When \tcode{b} is a surface brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the graphics data of the brush, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords}, taking into account the value of \tcode{b.wrap_mode()} and \tcode{b.filter()}.
+When \tcode{b} is a surface brush, when sampling point \tcode{pt}, where \tcode{pt} is the return value of calling the \tcode{transform_point} member function of Matrix using the requested point, from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the graphics data of the brush, taking into account the values of Wrap Mode and Filter.
 
 \rSec1 [brush.cons] {\tcode{brush} constructors and assignment operators}
 
@@ -96,7 +96,7 @@
 The brush's brush type shall be set to the value \tcode{brush_type::solid_color}.
 
 \pnum
-The graphics data of the brush shall be created from the return value of \tcode{f.color()}. The visual data format of the graphics data shall be as-if it is that specified by \tcode{format::argb}.
+The graphics data of the brush shall be created from the value of \tcode{c}. The visual data format of the graphics data shall be as-if it is that specified by \tcode{format::argb}.
 
 \pnum
 \remarks

source/brush.tex

@@ -7,9 +7,10 @@
 \pnum
 Brushes contain visual data and serve as sources of visual data for rendering and composing operations.
 
+\pnum
 There are four types of brushes:
 \begin{itemize}
-	\item color;
+	\item solid color;
 	\item linear gradient;
 	\item radial gradient; and,
 	\item surface.
@@ -27,7 +28,11 @@
 A brush is used either as a Source Brush or a Mask Brush (\ref{surface.rendering.brushes}).
 
 \pnum
-When a brush is used in a rendering and composing operation, a \tcode{brush_props} object or \tcode{mask_props} object can modify the result of sampling the brush.
+When a brush is used in a rendering and composing operation, if it is used as a Source Brush, it has a \tcode{brush_props} object that describes how the brush is interpreted for purposes of sampling. If it is used as a Mask Brush, it has a \tcode{mask_props} object that describes how the brush is interpreted for purposes of sampling.
+
+\pnum
+The \tcode{brush_props} and \tcode{mask_props} classes both have a Wrap Mode, Filter and Matrix (\ref{brushprops.summary} and \ref{maskprops.summary}). Where necessary, these shall be referenced using those terms without regard to whether the brush is being used as a Source Brush or a Mask Brush.
+
 
 %\pnum
 %A brush has its own coordinate space.

source/brushes.tex

@@ -20,12 +20,12 @@
     constexpr color_stop(double o, const bgra_color& c);
 
     // \ref{colorstops.colorstop.modifiers}, modifiers:
-    void offset(double val) noexcept;
-	void color(const bgra_color& val) noexcept;
+    constexpr void offset(double val) noexcept;
+	constexpr void color(const bgra_color& val) noexcept;
 
     // \ref{colorstops.colorstop.observers}, observers:
-	double offset() const noexcept;
-	bgra_color color() const noexcept;
+	constexpr double offset() const noexcept;
+	constexpr bgra_color color() const noexcept;
   };
 } } } }
 \end{codeblock}
@@ -53,7 +53,7 @@
 \indexlibrary{\idxcode{color_stop}!\idxcode{offset}}
 \indexlibrary{\idxcode{offset}!\idxcode{color_stop}}
 \begin{itemdecl}
-	void offset(double val) noexcept;
+	constexpr void offset(double val) noexcept;
 \end{itemdecl}
 \begin{itemdescr}
 	\pnum
@@ -64,7 +64,7 @@
 \indexlibrary{\idxcode{color_stop}!\idxcode{color}}
 \indexlibrary{\idxcode{color}!\idxcode{color_stop}}
 \begin{itemdecl}
-	void color(double val) noexcept;
+	constexpr void color(double val) noexcept;
 \end{itemdecl}
 \begin{itemdescr}
 	\pnum
@@ -77,7 +77,7 @@
 \indexlibrary{\idxcode{color_stop}!\idxcode{offset}}
 \indexlibrary{\idxcode{offset}!\idxcode{color_stop}}
 \begin{itemdecl}
-	double offset() const noexcept;
+	constexpr double offset() const noexcept;
 \end{itemdecl}
 \begin{itemdescr}
 	\pnum
@@ -88,7 +88,7 @@
 \indexlibrary{\idxcode{color_stop}!\idxcode{color}}
 \indexlibrary{\idxcode{color}!\idxcode{color_stop}}
 \begin{itemdecl}
-	bgra_color color() const noexcept;
+	constexpr bgra_color color() const noexcept;
 \end{itemdecl}
 \begin{itemdescr}
 	\pnum

source/color-stop.tex

@@ -1,13 +1,13 @@
 %!TEX root = io2d.tex
 %%--------------------------------------------------
 %% Version numbers
-\newcommand{\docno}{D0267R4}
+\newcommand{\docno}{P0267R4}
 \newcommand{\prevdocno}{P0267R3}
-\newcommand{\cppver}{201402L}
+\newcommand{\cppver}{201703L}
 
 %% Release date
-%\newcommand{\reldate}{2017-02-06} % Fixed date
-\newcommand{\reldate}{\today} % Relative date
+\newcommand{\reldate}{2017-03-20} % Fixed date
+%\newcommand{\reldate}{\today} % Relative date
 
 %% Library chapters
 % %\newcommand{\firstlibchapter}{language.support}

source/config.tex

@@ -128,9 +128,6 @@
 \pnum
 Table~\ref{tab:displaysurface.state.listing} specifies the name, type, function, and default value for each item of a display surface's observable state.
 
-\pnum
-Because the \tcode{display_surface} class publicly derives from the \tcode{surface} class, the observable state of a display surface also includes the observable state of a surface, as specified at \ref{surface.state.default}.
-
 \begin{libreqtab4b}
 	{Display surface observable state}
 	{tab:displaysurface.state.listing}
@@ -147,6 +144,11 @@
 	This is the brush that shall be used as specified by \tcode{scaling::letterbox} (Table~\ref{tab:scaling.meanings}) &
 	\tcode{brush\{ \{ bgra_color::black() \} \}} \\ \rowsep
 
+	\term{Letterbox Brush Props} &
+	\tcode{brush_props} &
+	This is the brush properties for the Letterbox Brush &
+	\tcode{brush_props\{ \}} \\ \rowsep
+	
 	\term{Scaling Type} &
 	\tcode{scaling} &
 	When the User Scaling Callback is equal to its default value, this is the type of scaling that shall be used when transferring the Back Buffer to the Display Buffer &
@@ -211,7 +213,7 @@
 
 	\term{User Scaling Callback} &
 	\tcode{function<\br
-	\tcode{experimental::}%%\br
+	\tcode{experimental::}\br
 	\tcode{io2d::}\br
 	\tcode{rectangle(}\br
 	\tcode{const display_surface\&,}\br
@@ -252,6 +254,17 @@
   noexcept;
 \end{itemdecl}
 \begin{itemdescr}
+\pnum
+\preconditions
+\tcode{preferredWidth > 0}.
+
+\pnum
+\tcode{preferredHeight > 0}.
+
+\pnum
+\tcode{preferredFormat != experimental::io2d::format::invalid}.
+
+
 \pnum
 \effects
 Constructs an object of type \tcode{display_surface}.
@@ -280,8 +293,6 @@
 
 \pnum
 \errors
-\tcode{errc::invalid_argument} if \tcode{preferredWidth <= 0}, \tcode{preferredHeight <= 0}, or \tcode{preferredFormat == experimental::io2d::format::invalid}.
-
 \tcode{io2d::device_error} if successful creation of the \tcode{display_surface} object would exceed the maximum number of simultaneous valid \tcode{display_surface} objects that the implementation supports.
 
 \pnum
@@ -305,6 +316,22 @@
   noexcept;
 \end{itemdecl}
 \begin{itemdescr}
+\pnum
+\preconditions
+\tcode{preferredWidth > 0}.
+
+\pnum
+\tcode{preferredHeight > 0}.
+
+\pnum
+\tcode{preferredDisplayWidth > 0}.
+
+\pnum
+\tcode{preferredDisplayHeight > 0}.
+
+\pnum
+\tcode{preferredFormat != experimental::io2d::format::invalid}.
+
 \pnum
 \effects
 Constructs an object of type \tcode{display_surface}.
@@ -333,8 +360,6 @@
 
 \pnum
 \errors
-\tcode{errc::invalid_argument} if \tcode{preferredWidth <= 0}, \tcode{preferredHeight <= 0}, \tcode{preferredDisplayWidth <= 0}, \tcode{preferredDisplayHeight <= 0}, or \tcode{preferredFormat == experimental::io2d::format::invalid}.
-
 \tcode{io2d::device_error} if successful creation of the \tcode{display_surface} object would exceed the maximum number of simultaneous valid \tcode{display_surface} objects that the implementation supports.
 
 \pnum
@@ -641,45 +666,18 @@
 \indexlibrary{\idxcode{display_surface}!\idxcode{letterbox_brush}}
 \indexlibrary{\idxcode{letterbox_brush}!\idxcode{display_surface}}
 \begin{itemdecl}
-void letterbox_brush(experimental::nullvalue_t) noexcept;
+void letterbox_brush(const optional<brush&>b,
+  const optional<brush_props>& bp = nullopt);
+void letterbox_brush(const optional<brush&>b, error_code& ec,
+  const optional<brush_props>& bp = nullopt) noexcept;
 \end{itemdecl}
 \begin{itemdescr}
 \pnum
 \effects
-Sets the Letterbox Brush to its default value.
-\end{itemdescr}
+Sets the Letterbox Brush to the value contained in \tcode{b} if it contains a value, otherwise set Letterbox Brush to its default value.
 
-\indexlibrary{\idxcode{display_surface}!\idxcode{letterbox_brush}}
-\indexlibrary{\idxcode{letterbox_brush}!\idxcode{display_surface}}
-\begin{itemdecl}
-void letterbox_brush(const bgra_color& c);
-void letterbox_brush(const bgra_color& c, error_code& ec) noexcept;
-\end{itemdecl}
-\begin{itemdescr}
-\pnum
-\effects
-Sets the Letterbox Brush to a value as-if \tcode{experimental::io2d::brush\{ solid_color_brush_factory\{ \} \}}.
-
-\pnum
-\throws
-As specified in Error reporting (\ref{\iotwod.err.report}).
-
-\pnum
-\errors
-The errors, if any, produced by this function are \impldef{display_surface!letterbox_brush}.
-\end{itemdescr}
-
-\indexlibrary{\idxcode{display_surface}!\idxcode{letterbox_brush}}
-\indexlibrary{\idxcode{letterbox_brush}!\idxcode{display_surface}}
-\begin{itemdecl}
-void letterbox_brush(const experimental::io2d::brush& b);
-void letterbox_brush(const experimental::io2d::brush& b, error_code& ec) 
-  noexcept;
-\end{itemdecl}
-\begin{itemdescr}
 \pnum
-\effects
-Sets the Letterbox Brush to \tcode{b}.
+Sets the Letterbox Brush Props to the value contained in \tcode{bp} if it contains a value, otherwise sets it Letterbox Brush Props to its default value.
 
 \pnum
 \throws
@@ -738,14 +736,12 @@
 \begin{itemdescr}
 \pnum
 \effects
-When \tcode{display_surface::show} is executing, informs the implementation that it shall call the Draw Callback as soon as possible.
+When \tcode{display_surface::begin_show} is executing, informs the implementation that the Draw Callback must be called as soon as possible.
 \end{itemdescr}
 
-\indexlibrary{\idxcode{display_surface}!\idxcode{show}}
-\indexlibrary{\idxcode{show}!\idxcode{display_surface}}
+\indexlibrary{\idxcode{display_surface}!\idxcode{begin_show}}
 \begin{itemdecl}
-int show();
-int show(error_code& ec) noexcept;
+int begin_show();
 \end{itemdecl}
 \begin{itemdescr}
 \pnum
@@ -764,7 +760,7 @@
 \end{enumeraten}
 
 \pnum
-If \tcode{display_surface::exit_show} is called from the Draw Callback, the implementation shall finish executing the Draw Callback and shall immediately cease to perform any actions in the continuous loop other than handling any implementation and host environment matters.
+If \tcode{display_surface::end_show} is called from the Draw Callback, the implementation shall finish executing the Draw Callback and shall immediately cease to perform any actions in the continuous loop other than handling any implementation and host environment matters needed to exit the loop properly.
 
 \pnum
 No later than when this function returns, the output device shall cease to display the contents of the Display Buffer.
@@ -793,41 +789,23 @@
 Other errors, if any, produced by this function are \impldef{display_surface!show}.
 \end{itemdescr}
 
-\indexlibrary{\idxcode{display_surface}!\idxcode{exit_show}}
-\indexlibrary{\idxcode{exit_show}!\idxcode{display_surface}}
+\indexlibrary{\idxcode{display_surface}!\idxcode{end_show}}
 \begin{itemdecl}
-void exit_show();
-void exit_show(error_code& ec) noexcept;
-void exit_show(std::chrono::duration d);
-void exit_show(std::chrono::duration d, error_code& ec) noexcept;
+void end_show();
 \end{itemdecl}
 \begin{itemdescr}
-\pnum
-\requires
-This function shall only be called from the Draw Callback; no diagnostic is required.
-
 \pnum
 \effects
-The implementation shall initiate the process of exiting the \tcode{display_surface::show} function's continuous loop.
-
-\pnum
-Implementations shall not wait until the \tcode{display_surface::show} function's continuous loop ends before returning from this function.
-
-\pnum
-Implementations should follow any procedures that the host environment requires in order to cause the \tcode{display_surface::show} function's continuous loop to stop executing without error.
+If this function is called outside of the Draw Callback while it is being executed in the \tcode{display_surface::begin_show} function's continuous loop, it does nothing.
 
 \pnum
-A \term{termination time duration} shall then be determined as follows:
-\begin{itemize}
-\item If no \tcode{std::chrono::duration} is provided, the termination time duration is \unspecnorm. Implementations should exit the \tcode{display_surface::show} function's continuous loop as soon as the host environment allows.
-\item Otherwise, implementations shall exit the \tcode{display_surface::show} function's continuous loop as soon as the host environment allows once the \tcode{std::chrono::duration} value has elapsed.
-\end{itemize}
+Otherwise, the implementation initiates the process of exiting the \tcode{display_surface::begin_show} function's continuous loop.
 
 \pnum
-The implementation shall continue to execute the \tcode{display_surface::show} function until it returns or until termination time duration milliseconds have passed since the termination time duration was determined, whichever comes first.
+If possible, any procedures that the host environment requires in order to cause the \tcode{display_surface::show} function's continuous loop to stop executing without error should be followed.
 
 \pnum
-If the \tcode{display_surface::show} function has not returned before termination time duration milliseconds have passed since the termination time duration was determined the implementation shall force the \tcode{display_surface::show} function's continuous loop to stop executing and shall then cause \tcode{display_surface::show} to return.
+The \tcode{display_surface::begin_show} function's loop continues execution until it returns.
 \end{itemdescr}
 
 \rSec1 [displaysurface.observers]{\tcode{display_surface} observers}
@@ -890,23 +868,23 @@
 \indexlibrary{\idxcode{display_surface}!\idxcode{dimensions}}
 \indexlibrary{\idxcode{dimensions}!\idxcode{display_surface}}
 \begin{itemdecl}
-tuple<int, int> dimensions() const noexcept;
+vector_2d dimensions() const noexcept;
 \end{itemdecl}
 \begin{itemdescr}
 \pnum
 \returns
-A \tcode{tuple<int, int>} where the first element is the Draw Width and the second element is the Draw Height.
+A \tcode{vector_2d} constructed using the Draw Width as the first argument and the Draw Height as the second argument.
 \end{itemdescr}
 
 \indexlibrary{\idxcode{display_surface}!\idxcode{display_dimensions}}
 \indexlibrary{\idxcode{display_dimensions}!\idxcode{display_surface}}
 \begin{itemdecl}
-tuple<int, int> display_dimensions() const noexcept;
+vector_2d display_dimensions() const noexcept;
 \end{itemdecl}
 \begin{itemdescr}
 \pnum
 \returns
-A \tcode{tuple<int, int>} where the first element is the Display Width and the second element is the Display Height.
+A \tcode{vector_2d} constructed using the Display Width as the first argument and the Display Height as the second argument.
 \end{itemdescr}
 
 \indexlibrary{\idxcode{display_surface}!\idxcode{scaling}}
@@ -945,12 +923,12 @@
 \indexlibrary{\idxcode{display_surface}!\idxcode{letterbox_brush}}
 \indexlibrary{\idxcode{letterbox_brush}!\idxcode{display_surface}}
 \begin{itemdecl}
-experimental::io2d::brush letterbox_brush() const noexcept;
+optional<brush> letterbox_brush() const noexcept;
 \end{itemdecl}
 \begin{itemdescr}
 \pnum
 \returns
-The Letterbox Brush.
+A \tcode{optional<brush>} object constructed using the user-provided Letterbox Brush or, if no user-provided Letterbox Brush is set, an empty \tcode{optional<brush>} object.
 \end{itemdescr}
 
 \indexlibrary{\idxcode{display_surface}!\idxcode{auto_clear}}