Skip to content

Commit 4c57c9b

Browse files
mikebmclmikebmcl
committed
Eliminated flush and mark_dirty member functions for the reasons stated in history.tex.
1 parent 375cdb3 commit 4c57c9b

File tree

4 files changed

+3
-282
lines changed

4 files changed

+3
-282
lines changed

‎source/history.tex

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,9 @@
6464
\pnum
6565
Added \tcode{GraphicsSurfaces::additional_formats} This allows implementations to support additional visual data formats.
6666

67+
\pnum
68+
Eliminated all \tcode{flush} and \tcode{mark_dirty} member functions. These only existed to allow users to modify surfaces externally. Implementations that wish to allow users to modify surfaces externally should provide and document their own functionality for how to do that. The errors, etc., are all implementation dependent anyway so a uniform calling interface provides no benefit at all in the current templated-design.
69+
6770
\rSec1 [\iotwod.revisionhistory.r7] {Revision 7}
6871

6972
\pnum

‎source/image-surface.tex

Lines changed: 0 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,6 @@
4545

4646
// \ref{\iotwod.imagesurface.mofifiers}, modifiers:
4747
void clear();
48-
void flush();
49-
void flush(error_code& ec) noexcept;
50-
void mark_dirty();
51-
void mark_dirty(error_code& ec) noexcept;
52-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents);
53-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents,
54-
error_code& ec) noexcept;
5548
void paint(const basic_brush<GraphicsSurfaces>& b,
5649
const optional<basic_brush_props<GraphicsSurfaces>>& bp = nullopt,
5750
const optional<basic_render_props<GraphicsSurfaces>>& rp = nullopt,
@@ -259,93 +252,6 @@
259252
<TODO>
260253
\end{itemdescr}
261254

262-
\indexlibrarymember{flush}{basic_image_surface}%
263-
\begin{itemdecl}
264-
void flush();
265-
void flush(error_code& ec) noexcept;
266-
\end{itemdecl}
267-
\begin{itemdescr}
268-
\pnum
269-
\effects
270-
If the implementation does not provide a native handle to the surface's visual data, this function does nothing.
271-
272-
\pnum
273-
If the implementation does provide a native handle to the surface's visual data, then the implementation performs every action necessary to ensure that all operations on the surface that produce observable effects occur.
274-
275-
\pnum
276-
The implementation performs any other actions necessary to ensure that the surface will be usable again after a call to \tcode{basic_image_surface::mark_dirty}.
277-
278-
\pnum
279-
Once a call to \tcode{basic_image_surface::flush} is made, \tcode{basic_image_surface::mark_dirty} shall be called before any other member function of the surface is called or the surface is used as an argument to any other function.
280-
281-
\pnum
282-
\throws
283-
As specified in Error reporting (\ref{\iotwod.err.report}).
284-
285-
\pnum
286-
\remarks
287-
This function exists to allow the user to take control of the underlying surface using an implementation-provided native handle without introducing a race condition. The implementation's responsibility is to ensure that the user can safely use the underlying surface.
288-
289-
\pnum
290-
\errors
291-
The potential errors are \impldefplain{basic_image_surface::flush errors}.
292-
293-
\pnum
294-
Implementations should avoid producing errors here.
295-
296-
\pnum
297-
If the implementation does not provide a native handle to the \tcode{basic_image_surface} object's visual data, this function shall not produce any errors.
298-
299-
\pnum
300-
\begin{note}
301-
There are several purposes for \tcode{basic_image_surface::flush} and \tcode{basic_image_surface::mark_dirty}.
302-
303-
\pnum
304-
One is to allow implementation wide latitude in how they implement the rendering and composing operations (\ref{\iotwod.surface.rendering}), such as batching calls and then sending them to graphics acceleration hardware at appropriate times.
305-
306-
\pnum
307-
Another is to give implementations the chance during the call to \tcode{basic_image_surface::flush} to save any internal state that might be modified by the user and then restore it during the call to \tcode{basic_image_surface::mark_dirty}.
308-
309-
\pnum
310-
Other uses of this pair of calls are also possible.
311-
\end{note}
312-
\end{itemdescr}
313-
314-
\indexlibrarymember{mark_dirty}{basic_image_surface}%
315-
\begin{itemdecl}
316-
void mark_dirty();
317-
void mark_dirty(error_code& ec) noexcept;
318-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents);
319-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents, error_code& ec) noexcept;
320-
\end{itemdecl}
321-
\begin{itemdescr}
322-
\pnum
323-
\effects
324-
If the implementation does not provide a native handle to the \tcode{basic_image_surface} object's visual data, this function shall do nothing.
325-
326-
\pnum
327-
If the implementation does provide a native handle to the \tcode{basic_image_surface} object's visual data, then:
328-
\begin{itemize}
329-
\item If called without a \tcode{basic_bounding_box} argument, informs the implementation that external changes using a native handle potentially modified all of the surface's visual data.
330-
\item If called with a \tcode{basic_bounding_box} argument, informs the implementation that external changes using a native handle potentially modified the surface's visual data only within the bounds specified by the \term{bounding rectangle} \tcode{basic_bounding_box\{ round(extents.x()), round (extents.y()), round(extents.width()), round(extents.height())\}}. No part of the bounding rectangle shall be outside of the bounds of the surface's visual data; no diagnostic is required.
331-
\end{itemize}
332-
333-
\pnum
334-
\throws
335-
As specified in Error reporting (\ref{\iotwod.err.report}).
336-
337-
\pnum
338-
\remarks
339-
After external changes are made to this \tcode{basic_image_surface} object's visual data using a native pointer, this function shall be called before using this \tcode{basic_image_surface} object; no diagnostic is required.
340-
341-
\pnum
342-
\errors
343-
The errors, if any, produced by this function are \impldefplain{basic_image_surface!mark_dirty}.
344-
345-
\pnum
346-
If the implementation does not provide a native handle to the \tcode{basic_image_surface} object's visual data, this function shall not produce any errors.
347-
\end{itemdescr}
348-
349255
\indexlibrarymember{paint}{basic_image_surface}%
350256
\begin{itemdecl}
351257
void paint(const basic_brush<GraphicsSurfaces>& b,

‎source/output-surface.tex

Lines changed: 0 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -49,13 +49,6 @@
4949
int begin_show();
5050
void end_show();
5151
void clear();
52-
void flush();
53-
void flush(error_code& ec) noexcept;
54-
void mark_dirty();
55-
void mark_dirty(error_code& ec) noexcept;
56-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents);
57-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents, error_code& ec)
58-
noexcept;
5952
void paint(const basic_brush<GraphicsSurfaces>& b,
6053
const optional<basic_brush_props<GraphicsSurfaces>>& bp = nullopt,
6154
const optional<basic_render_props<GraphicsSurfaces>>& rp = nullopt,
@@ -316,93 +309,6 @@
316309
<TODO>
317310
\end{itemdescr}
318311

319-
\indexlibrarymember{flush}{basic_output_surface}%
320-
\begin{itemdecl}
321-
void flush();
322-
void flush(error_code& ec) noexcept;
323-
\end{itemdecl}
324-
\begin{itemdescr}
325-
\pnum
326-
\effects
327-
If the implementation does not provide a native handle to the surface's visual data, this function does nothing.
328-
329-
\pnum
330-
If the implementation does provide a native handle to the surface's visual data, then the implementation performs every action necessary to ensure that all operations on the surface that produce observable effects occur.
331-
332-
\pnum
333-
The implementation performs any other actions necessary to ensure that the surface will be usable again after a call to \tcode{basic_output_surface::mark_dirty}.
334-
335-
\pnum
336-
Once a call to \tcode{basic_output_surface::flush} is made, \tcode{basic_output_surface::mark_dirty} shall be called before any other member function of the surface is called or the surface is used as an argument to any other function.
337-
338-
\pnum
339-
\throws
340-
As specified in Error reporting (\ref{\iotwod.err.report}).
341-
342-
\pnum
343-
\remarks
344-
This function exists to allow the user to take control of the underlying surface using an implementation-provided native handle without introducing a race condition. The implementation's responsibility is to ensure that the user can safely use the underlying surface.
345-
346-
\pnum
347-
\errors
348-
The potential errors are \impldefplain{basic_output_surface::flush errors}.
349-
350-
\pnum
351-
Implementations should avoid producing errors here.
352-
353-
\pnum
354-
If the implementation does not provide a native handle to the \tcode{basic_output_surface} object's visual data, this function shall not produce any errors.
355-
356-
\pnum
357-
\begin{note}
358-
There are several purposes for \tcode{basic_output_surface::flush} and \tcode{basic_output_surface::mark_dirty}.
359-
360-
\pnum
361-
One is to allow implementation wide latitude in how they implement the rendering and composing operations (\ref{\iotwod.surface.rendering}), such as batching calls and then sending them to graphics acceleration hardware at appropriate times.
362-
363-
\pnum
364-
Another is to give implementations the chance during the call to \tcode{basic_output_surface::flush} to save any internal state that might be modified by the user and then restore it during the call to \tcode{basic_output_surface::mark_dirty}.
365-
366-
\pnum
367-
Other uses of this pair of calls are also possible.
368-
\end{note}
369-
\end{itemdescr}
370-
371-
\indexlibrarymember{mark_dirty}{basic_output_surface}%
372-
\begin{itemdecl}
373-
void mark_dirty();
374-
void mark_dirty(error_code& ec) noexcept;
375-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents);
376-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents, error_code& ec) noexcept;
377-
\end{itemdecl}
378-
\begin{itemdescr}
379-
\pnum
380-
\effects
381-
If the implementation does not provide a native handle to the \tcode{basic_output_surface} object's visual data, this function shall do nothing.
382-
383-
\pnum
384-
If the implementation does provide a native handle to the \tcode{basic_output_surface} object's visual data, then:
385-
\begin{itemize}
386-
\item If called without a \tcode{basic_bounding_box} argument, informs the implementation that external changes using a native handle potentially modified all of the surface's visual data.
387-
\item If called with a \tcode{basic_bounding_box} argument, informs the implementation that external changes using a native handle potentially modified the surface's visual data within the bounds specified by the \term{bounding rectangle} \tcode{basic_bounding_box\{ round(extents.x()), round (extents.y()), round(extents.width()), round(extents.height())\}}. No part of the bounding rectangle shall be outside of the bounds of the surface's visual data; no diagnostic is required.
388-
\end{itemize}
389-
390-
\pnum
391-
\throws
392-
As specified in Error reporting (\ref{\iotwod.err.report}).
393-
394-
\pnum
395-
\remarks
396-
After external changes are made to this \tcode{basic_output_surface} object's visual data using a native pointer, this function shall be called before using this \tcode{basic_output_surface} object; no diagnostic is required.
397-
398-
\pnum
399-
\errors
400-
The errors, if any, produced by this function are \impldefplain{basic_output_surface!mark_dirty}.
401-
402-
\pnum
403-
If the implementation does not provide a native handle to the \tcode{basic_output_surface} object's visual data, this function shall not produce any errors.
404-
\end{itemdescr}
405-
406312
\indexlibrarymember{paint}{basic_output_surface}%
407313
\begin{itemdecl}
408314
void paint(const basic_brush<GraphicsSurfaces>& b,

‎source/unmanaged-output-surface.tex

Lines changed: 0 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,6 @@
4040
basic_bounding_box<graphics_math_type> invoke_user_scaling_callback(bool& useLetterbox);
4141
void draw_to_output();
4242
void clear();
43-
void flush();
44-
void flush(error_code& ec) noexcept;
45-
void mark_dirty();
46-
void mark_dirty(error_code& ec) noexcept;
47-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents);
48-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents, error_code& ec)
49-
noexcept;
5043
void paint(const basic_brush<GraphicsSurfaces>& b,
5144
const optional<basic_brush_props<GraphicsSurfaces>>& bp = nullopt,
5245
const optional<basic_render_props<GraphicsSurfaces>>& rp = nullopt,
@@ -247,93 +240,6 @@
247240
<TODO>
248241
\end{itemdescr}
249242

250-
\indexlibrarymember{flush}{basic_unmanaged_output_surface}%
251-
\begin{itemdecl}
252-
void flush();
253-
void flush(error_code& ec) noexcept;
254-
\end{itemdecl}
255-
\begin{itemdescr}
256-
\pnum
257-
\effects
258-
If the implementation does not provide a native handle to the surface's visual data, this function does nothing.
259-
260-
\pnum
261-
If the implementation does provide a native handle to the surface's visual data, then the implementation performs every action necessary to ensure that all operations on the surface that produce observable effects occur.
262-
263-
\pnum
264-
The implementation performs any other actions necessary to ensure that the surface will be usable again after a call to \tcode{basic_unmanaged_output_surface::mark_dirty}.
265-
266-
\pnum
267-
Once a call to \tcode{basic_unmanaged_output_surface::flush} is made, \tcode{basic_unmanaged_output_surface::mark_dirty} shall be called before any other member function of the surface is called or the surface is used as an argument to any other function.
268-
269-
\pnum
270-
\throws
271-
As specified in Error reporting (\ref{\iotwod.err.report}).
272-
273-
\pnum
274-
\remarks
275-
This function exists to allow the user to take control of the underlying surface using an implementation-provided native handle without introducing a race condition. The implementation's responsibility is to ensure that the user can safely use the underlying surface.
276-
277-
\pnum
278-
\errors
279-
The potential errors are \impldefplain{basic_unmanaged_output_surface::flush errors}.
280-
281-
\pnum
282-
Implementations should avoid producing errors here.
283-
284-
\pnum
285-
If the implementation does not provide a native handle to the \tcode{basic_unmanaged_output_surface} object's visual data, this function shall not produce any errors.
286-
287-
\pnum
288-
\begin{note}
289-
There are several purposes for \tcode{basic_unmanaged_output_surface::flush} and \tcode{basic_unmanaged_output_surface::mark_dirty}.
290-
291-
\pnum
292-
One is to allow implementation wide latitude in how they implement the rendering and composing operations (\ref{\iotwod.surface.rendering}), such as batching calls and then sending them to graphics acceleration hardware at appropriate times.
293-
294-
\pnum
295-
Another is to give implementations the chance during the call to \tcode{basic_unmanaged_output_surface::flush} to save any internal state that might be modified by the user and then restore it during the call to \tcode{basic_unmanaged_output_surface::mark_dirty}.
296-
297-
\pnum
298-
Other uses of this pair of calls are also possible.
299-
\end{note}
300-
\end{itemdescr}
301-
302-
\indexlibrarymember{mark_dirty}{basic_unmanaged_output_surface}%
303-
\begin{itemdecl}
304-
void mark_dirty();
305-
void mark_dirty(error_code& ec) noexcept;
306-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents);
307-
void mark_dirty(const basic_bounding_box<graphics_math_type>& extents, error_code& ec) noexcept;
308-
\end{itemdecl}
309-
\begin{itemdescr}
310-
\pnum
311-
\effects
312-
If the implementation does not provide a native handle to the \tcode{basic_unmanaged_output_surface} object's visual data, this function shall do nothing.
313-
314-
\pnum
315-
If the implementation does provide a native handle to the \tcode{basic_unmanaged_output_surface} object's visual data, then:
316-
\begin{itemize}
317-
\item If called without a \tcode{basic_bounding_box} argument, informs the implementation that external changes using a native handle potentially modified all of the surface's visual data.
318-
\item If called with a \tcode{basic_bounding_box} argument, informs the implementation that external changes using a native handle potentially modified the surface's visual data within the bounds specified by the \term{bounding rectangle} \tcode{basic_bounding_box\{ round(extents.x()), round (extents.y()), round(extents.width()), round(extents.height())\}}. No part of the bounding rectangle shall be outside of the bounds of the surface's visual data; no diagnostic is required.
319-
\end{itemize}
320-
321-
\pnum
322-
\throws
323-
As specified in Error reporting (\ref{\iotwod.err.report}).
324-
325-
\pnum
326-
\remarks
327-
After external changes are made to this \tcode{basic_unmanaged_output_surface} object's visual data using a native pointer, this function shall be called before using this \tcode{basic_unmanaged_output_surface} object; no diagnostic is required.
328-
329-
\pnum
330-
\errors
331-
The errors, if any, produced by this function are \impldefplain{basic_unmanaged_output_surface!mark_dirty}.
332-
333-
\pnum
334-
If the implementation does not provide a native handle to the \tcode{basic_unmanaged_output_surface} object's visual data, this function shall not produce any errors.
335-
\end{itemdescr}
336-
337243
\indexlibrarymember{paint}{basic_unmanaged_output_surface}%
338244
\begin{itemdecl}
339245
void paint(const basic_brush<GraphicsSurfaces>& b,

0 commit comments

Comments
 (0)