Skip to content

Commit f269f6c

Browse files
committed
P0267R3 revision accepted for pre-Kona mailing. Fixed up various errors, added nullvalue_t type and replaced nullopt_t with it. Made surface virtual functions (except dtor) non-virtual per LEWG Oulu feedback. Renamed surface::save and surface::restore to surface::push_state and surface::pop_state, respectively. Changed display_surface::exit_show to take a std::chrono::duration instead of an int and made it compliant with the exception/noexceptions design. Also added an overload for that which takes no parameters. Switched the dashes typedef to a using dashes = ... version.
1 parent df64401 commit f269f6c

File tree

8 files changed

+102
-149
lines changed

8 files changed

+102
-149
lines changed

papers/P0267R3.pdf

-3.81 KB
Binary file not shown.

papers/P0267R3_orig.pdf

1.6 MB
Binary file not shown.

source/display-surface.tex

Lines changed: 36 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,26 @@
11
%!TEX root = io2d.tex
22
\rSec0 [displaysurface] {Class \tcode{display_surface}}
33

4+
\rSec1 [displaysurface.intro] {\tcode{display_surface} Description}
5+
6+
\pnum
7+
\indexlibrary{\idxcode{display_surface}}
8+
The class \tcode{display_surface} derives from the \tcode{surface} class and provides an interface to a raster graphics data graphics resource called the \tcode{Back Buffer} and to a second raster graphics data graphics resource called the \tcode{Display Buffer}.
9+
10+
\pnum
11+
The pixel data of the Display Buffer can never be accessed by the user except through a native handle, if one is provided. As such, its pixel format need not equate to any of the pixel formats described by the \tcode{experimental::io2d::format} enumerators. This is meant to give implementors more flexibility in trying to display the pixels of the Back Buffer in a way that is visually as close as possible to the colors of those pixels.
12+
13+
\pnum
14+
The Draw Callback (Table~\ref{tab:displaysurface.state.listing}) is called by \tcode{display_surface::show} as required by the Refresh Rate and when otherwise needed by the implementation in order to update the pixel content of the Back Buffer.
15+
16+
\pnum
17+
After each execution of the Draw Callback, the contents of the Back Buffer are transferred using sampling with an \unspecnorm filter to the Display Buffer. The Display Buffer is then shown to the user via the \term{output device}.
18+
\enternote
19+
The filter is \unspecnorm to allow implementations to achieve the best possible result, including by changing filters at runtime depending on factors such as whether scaling is required and by using specialty hardware if available, while maintaining a balance between quality and performance that the implementer deems acceptable.
20+
21+
In the absence of specialty hardware, implementers are encouraged to use a filter that is the equivalent of a nearest neighbor interpolation filter if no scaling is required and otherwise to use a filter that produces results that are at least as good as those that would be obtained by using a bilinear interpolation filter.
22+
\exitnote
23+
424
\rSec1 [displaysurface.synopsis] {\tcode{display_surface} synopsis}
525

626
\begin{codeblock}
@@ -43,11 +63,6 @@
4363
virtual ~display_surface();
4464

4565
// \ref{displaysurface.modifiers}, modifiers:
46-
virtual void save() override;
47-
virtual void save(error_code& ec) noexcept override;
48-
virtual void restore() override;
49-
virtual void restore(error_code& ec) noexcept override;
50-
5166
void draw_callback(const function<void(display_surface& sfc)>& fn) noexcept;
5267
void size_change_callback(const function<void(display_surface& sfc)>& fn)
5368
noexcept;
@@ -66,7 +81,7 @@
6681
void scaling(experimental::io2d::scaling scl) noexcept;
6782
void user_scaling_callback(const function<experimental::io2d::rectangle(
6883
const display_surface&, bool&)>& fn) noexcept;
69-
void letterbox_brush(experimental::nullopt_t) noexcept;
84+
void letterbox_brush(experimental::nullvalue_t) noexcept;
7085
void letterbox_brush(const rgba_color& c);
7186
void letterbox_brush(const rgba_color& c, error_code& ec) noexcept;
7287
void letterbox_brush(const experimental::io2d::brush& b);
@@ -77,9 +92,11 @@
7792
bool desired_frame_rate(double fps) noexcept;
7893
void redraw_required() noexcept;
7994
int show();
80-
int show(error_code& ec);
81-
void exit_show(int milliseconds);
82-
void exit_show(int milliseconds, error_code& ec);
95+
int show(error_code& ec) noexcept;
96+
void exit_show();
97+
void exit_show(error_code& ec) noexcept;
98+
void exit_show(std::chrono::duration d);
99+
void exit_show(std::chrono::duration d, error_code& ec) noexcept;
83100

84101
// \ref{displaysurface.observers}, observers:
85102
experimental::io2d::format format() const noexcept;
@@ -103,25 +120,7 @@
103120
} } } }
104121
\end{codeblock}
105122

106-
\rSec1 [displaysurface.intro] {\tcode{display_surface} Description}
107-
108-
\pnum
109-
\indexlibrary{\idxcode{display_surface}}
110-
The class \tcode{display_surface} derives from the \tcode{surface} class and provides an interface to a raster graphics data graphics resource called the \tcode{Back Buffer} and to a second raster graphics data graphics resource called the \tcode{Display Buffer}.
111-
112-
\pnum
113-
The pixel data of the Display Buffer can never be accessed by the user except through a native handle, if one is provided. As such, its pixel format need not equate to any of the pixel formats described by the \tcode{experimental::io2d::format} enumerators. This is meant to give implementors more flexibility in trying to display the pixels of the Back Buffer in a way that is visually as close as possible to the colors of those pixels.
114-
115-
\pnum
116-
The Draw Callback (Table~\ref{tab:displaysurface.state.listing}) is called by \tcode{display_surface::show} as required by the Refresh Rate and when otherwise needed by the implementation in order to update the pixel content of the Back Buffer.
117-
118-
\pnum
119-
After each execution of the Draw Callback, the contents of the Back Buffer are transferred using sampling with an \unspecnorm filter to the Display Buffer. The Display Buffer is then shown to the user via the \term{output device}.
120-
\enternote
121-
The filter is \unspecnorm to allow implementations to achieve the best possible result, including by changing filters at runtime depending on factors such as whether scaling is required and by using specialty hardware if available, while maintaining a balance between quality and performance that the implementer deems acceptable.
122-
123-
In the absence of specialty hardware, implementers are encouraged to use a filter that is the equivalent of a nearest neighbor interpolation filter if no scaling is required and otherwise to use a filter that produces results that are at least as good as those that would be obtained by using a bilinear interpolation filter.
124-
\exitnote
123+
\rSec1 [displaysurface.misc] {\tcode{display_surface} miscellaneou behavior}
125124

126125
\pnum
127126
What constitutes an output device is \impldef{output device}, with the sole constraint being that an output device shall allow the user to see the dynamically-updated contents of the Display Buffer.
@@ -355,59 +354,6 @@
355354

356355
\rSec1 [displaysurface.modifiers]{\tcode{display_surface} modifiers}
357356

358-
\indexlibrary{\idxcode{display_surface}!\idxcode{save}}
359-
\indexlibrary{\idxcode{save}!\idxcode{display_surface}}
360-
\begin{itemdecl}
361-
virtual void save() override;
362-
virtual void save(error_code& ec) noexcept override;
363-
\end{itemdecl}
364-
\begin{itemdescr}
365-
\pnum
366-
\effects
367-
Calls \tcode{surface::save}.
368-
369-
\pnum
370-
Implementations may save additional data provided that it does not alter the observable state of the \tcode{display_surface} object.
371-
372-
\pnum
373-
\throws
374-
As specified in Error reporting (\ref{\iotwod.err.report}).
375-
376-
\pnum
377-
\errors
378-
\tcode{errc::not_enough_memory} if the state cannot be saved.
379-
\end{itemdescr}
380-
381-
\indexlibrary{\idxcode{display_surface}!\idxcode{restore}}
382-
\indexlibrary{\idxcode{restore}!\idxcode{display_surface}}
383-
\begin{itemdecl}
384-
virtual void restore() override;
385-
virtual void restore(error_code& ec) noexcept override;
386-
\end{itemdecl}
387-
\begin{itemdescr}
388-
\pnum
389-
\effects
390-
Calls \tcode{surface::restore}.
391-
392-
\pnum
393-
If the implementation saved additional data as per \tcode{display_surface::save}, it should restore that data. Otherwise it shall discard that data.
394-
395-
\pnum
396-
\throws
397-
As specified in Error reporting (\ref{\iotwod.err.report}).
398-
399-
\pnum
400-
\remarks
401-
Because this function is only restoring previously saved state, except where the conditions for \tcode{io2d_error::invalid_restore} are met, implementations should not generate errors.
402-
403-
\pnum
404-
\errors
405-
\tcode{io2d_error::invalid_restore} if this function is called without a previous matching call to \tcode{surface::save}. Implementations shall not produce \tcode{io2d_error::invalid_restore} except under the conditions stated in this paragraph.
406-
407-
\pnum
408-
Excluding the previously specified error, any errors produced by calling this function are \impldef{display_surface!restore}.
409-
\end{itemdescr}
410-
411357
\indexlibrary{\idxcode{display_surface}!\idxcode{draw_callback}}
412358
\indexlibrary{\idxcode{draw_callback}!\idxcode{display_surface}}
413359
\begin{itemdecl}
@@ -706,7 +652,7 @@
706652
\indexlibrary{\idxcode{display_surface}!\idxcode{letterbox_brush}}
707653
\indexlibrary{\idxcode{letterbox_brush}!\idxcode{display_surface}}
708654
\begin{itemdecl}
709-
void letterbox_brush(experimental::nullopt_t) noexcept;
655+
void letterbox_brush(experimental::nullvalue_t) noexcept;
710656
\end{itemdecl}
711657
\begin{itemdescr}
712658
\pnum
@@ -810,7 +756,7 @@
810756
\indexlibrary{\idxcode{show}!\idxcode{display_surface}}
811757
\begin{itemdecl}
812758
int show();
813-
int show(error_code& ec);
759+
int show(error_code& ec) noexcept;
814760
\end{itemdecl}
815761
\begin{itemdescr}
816762
\pnum
@@ -855,13 +801,16 @@
855801
\tcode{errc::operation_would_block} if the value of Draw Callback is equivalent to its default value or if it becomes equivalent to its default value before this function returns.
856802

857803
\pnum
858-
Other errors, if any, produced by this function are \impldef{display_surface!letterbox_brush}.
804+
Other errors, if any, produced by this function are \impldef{display_surface!show}.
859805
\end{itemdescr}
860806

861807
\indexlibrary{\idxcode{display_surface}!\idxcode{exit_show}}
862808
\indexlibrary{\idxcode{exit_show}!\idxcode{display_surface}}
863809
\begin{itemdecl}
864-
void exit_show(int ms) noexcept;
810+
void exit_show();
811+
void exit_show(error_code& ec) noexcept;
812+
void exit_show(std::chrono::duration d);
813+
void exit_show(std::chrono::duration d, error_code& ec) noexcept;
865814
\end{itemdecl}
866815
\begin{itemdescr}
867816
\pnum
@@ -881,8 +830,8 @@
881830
\pnum
882831
A \term{termination time duration} shall then be determined as follows:
883832
\begin{itemize}
884-
\item If the value \tcode{ms} is negative, the termination time duration shall be an \unspecnorm number of milliseconds.
885-
\item Otherwise the termination time duration shall be \tcode{ms} milliseconds.
833+
\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.
834+
\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.
886835
\end{itemize}
887836

888837
\pnum

source/experimental-io2d.tex

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,12 @@
66
\begin{codeblock}
77

88
namespace std { namespace experimental {
9-
// From C++ Extensions for Library Fundamentals, N4335
10-
struct nullopt_t;
11-
constexpr nullopt_t nullopt{ @\impdef@ };
12-
139
namespace io2d { inline namespace v1 {
1410

15-
typedef tuple<vector<double>, double> dashes;
11+
struct nullvalue_t;
12+
constexpr nullvalue_t nullvalue{ @\impdef@ };
13+
14+
using dashes = tuple<vector<double>, double>;
1615

1716
enum class io2d_error;
1817
enum class antialias;

source/io2d-error.tex

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
namespace std { namespace experimental { namespace io2d { inline namespace v1 {
1515
enum class io2d_error {
1616
success,
17-
invalid_restore,
17+
invalid_pop_state,
1818
no_current_point,
1919
invalid_matrix,
2020
invalid_status,
@@ -58,9 +58,9 @@
5858
\tcode{success}
5959
& The operation completed successfully.
6060
\\
61-
\tcode{invalid_restore}
62-
& A call was made to \tcode{surface::restore} for which no prior call to
63-
\tcode{surface::save} was made.
61+
\tcode{invalid_pop_state}
62+
& A call was made to \tcode{surface::pop_state} for which no prior call to
63+
\tcode{surface::push_state} was made.
6464
\\
6565
\tcode{no_current_point}
6666
& A path segment or path instruction encountered during path processing requires a value for current point but current point has no value.

source/path-factory.tex

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -739,7 +739,7 @@
739739
The destructor of \tcode{value_type} is called the number of times equal to
740740
the number of the elements erased, but the assignment operator
741741
of \tcode{value_type} is called the number of times equal to the number of
742-
elements in the vector after the erased elements.
742+
elements in the path factory after the erased elements.
743743

744744
\pnum
745745
\throws

source/path.tex

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
\pnum
55
\indexlibrary{\idxcode{path_group}}
6-
The class \tcode{path_group} contains the result of processing \ref{paths.processing} a \tcode{path_factory} object. How it stores the resulting data is \unspec.
6+
The class \tcode{path_group} contains the result of processing \ref{paths.processing} a \tcode{path_factory} object. How it stores the resulting data is \unspecnorm.
77

88
\pnum
99
A \tcode{path_group} object is used by a \tcode{surface}-derived object for rendering and composing operations.

0 commit comments

Comments
 (0)