|
1 | 1 | %!TEX root = io2d.tex
|
2 | 2 | \rSec0 [displaysurface] {Class \tcode{display_surface}}
|
3 | 3 |
|
| 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 | + |
4 | 24 | \rSec1 [displaysurface.synopsis] {\tcode{display_surface} synopsis}
|
5 | 25 |
|
6 | 26 | \begin{codeblock}
|
|
43 | 63 | virtual ~display_surface();
|
44 | 64 |
|
45 | 65 | // \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 |
| - |
51 | 66 | void draw_callback(const function<void(display_surface& sfc)>& fn) noexcept;
|
52 | 67 | void size_change_callback(const function<void(display_surface& sfc)>& fn)
|
53 | 68 | noexcept;
|
|
66 | 81 | void scaling(experimental::io2d::scaling scl) noexcept;
|
67 | 82 | void user_scaling_callback(const function<experimental::io2d::rectangle(
|
68 | 83 | const display_surface&, bool&)>& fn) noexcept;
|
69 |
| - void letterbox_brush(experimental::nullopt_t) noexcept; |
| 84 | + void letterbox_brush(experimental::nullvalue_t) noexcept; |
70 | 85 | void letterbox_brush(const rgba_color& c);
|
71 | 86 | void letterbox_brush(const rgba_color& c, error_code& ec) noexcept;
|
72 | 87 | void letterbox_brush(const experimental::io2d::brush& b);
|
|
77 | 92 | bool desired_frame_rate(double fps) noexcept;
|
78 | 93 | void redraw_required() noexcept;
|
79 | 94 | 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; |
83 | 100 |
|
84 | 101 | // \ref{displaysurface.observers}, observers:
|
85 | 102 | experimental::io2d::format format() const noexcept;
|
|
103 | 120 | } } } }
|
104 | 121 | \end{codeblock}
|
105 | 122 |
|
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} |
125 | 124 |
|
126 | 125 | \pnum
|
127 | 126 | 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 | 354 |
|
356 | 355 | \rSec1 [displaysurface.modifiers]{\tcode{display_surface} modifiers}
|
357 | 356 |
|
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 |
| - |
411 | 357 | \indexlibrary{\idxcode{display_surface}!\idxcode{draw_callback}}
|
412 | 358 | \indexlibrary{\idxcode{draw_callback}!\idxcode{display_surface}}
|
413 | 359 | \begin{itemdecl}
|
|
706 | 652 | \indexlibrary{\idxcode{display_surface}!\idxcode{letterbox_brush}}
|
707 | 653 | \indexlibrary{\idxcode{letterbox_brush}!\idxcode{display_surface}}
|
708 | 654 | \begin{itemdecl}
|
709 |
| -void letterbox_brush(experimental::nullopt_t) noexcept; |
| 655 | +void letterbox_brush(experimental::nullvalue_t) noexcept; |
710 | 656 | \end{itemdecl}
|
711 | 657 | \begin{itemdescr}
|
712 | 658 | \pnum
|
|
810 | 756 | \indexlibrary{\idxcode{show}!\idxcode{display_surface}}
|
811 | 757 | \begin{itemdecl}
|
812 | 758 | int show();
|
813 |
| -int show(error_code& ec); |
| 759 | +int show(error_code& ec) noexcept; |
814 | 760 | \end{itemdecl}
|
815 | 761 | \begin{itemdescr}
|
816 | 762 | \pnum
|
|
855 | 801 | \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.
|
856 | 802 |
|
857 | 803 | \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}. |
859 | 805 | \end{itemdescr}
|
860 | 806 |
|
861 | 807 | \indexlibrary{\idxcode{display_surface}!\idxcode{exit_show}}
|
862 | 808 | \indexlibrary{\idxcode{exit_show}!\idxcode{display_surface}}
|
863 | 809 | \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; |
865 | 814 | \end{itemdecl}
|
866 | 815 | \begin{itemdescr}
|
867 | 816 | \pnum
|
|
881 | 830 | \pnum
|
882 | 831 | A \term{termination time duration} shall then be determined as follows:
|
883 | 832 | \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. |
886 | 835 | \end{itemize}
|
887 | 836 |
|
888 | 837 | \pnum
|
|
0 commit comments