On 2020-09-15 23:34 +0800, Vladimir Nikishkin wrote:
> Could people have a look at the last commit/pull request once again?
>
> I have added two quite large pieces of text to explain why
> (canvas-refresh) and (canvas-reset) are needed. I am still not sure
> that the wording is good enough.

Some important information which appears deep in the explanation of
canvas-refresh could be moved to the specification; In general, I
think the points could be made clearer.  Here's my attempt.  Feel free
to use anything from the following, if I haven't misunderstood
everything:

Procedure: (canvas-refresh)

Updates the display in an implementation-defined manner to reflect the
state of the canvas.  Returns a system-dependent identifier (not to be
confused with Scheme identifiers) of the canvas.  The canvas may not
exist unless it has been drawn on.

Explanation: canvas-refresh is an attempt to reconcile as many drawing
approaches as possible.  After a call to (canvas-refresh), the state
of the display (whatever it may be) is expected to be a faithful
representation of the image drawn by a previous sequence of calls to
the drawing routines, regardless of the underlying approach that a
system is using.

Many systems are likely to use a so-called "double-buffering" or
"delayed drawing" technique, in which drawing and displaying are two
different operations.  In these implementations, canvas-refresh might
be called to "flush" drawing operations to the display.  Other systems
may use other routines not specified by this SRFI to display the
"picture value" returned by canvas-refresh.  (This is the approach
used by the Kawa sample implementation, which displays the "picture
value" returned by canvas-refresh in a graphical REPL.)  canvas-refresh
thus has both "pure" and side-effecting semantics: it may change the
display, or it may simply return a value which can be displayed.

A "canvas" is anything that the drawing procedures draw on.  It may be
a window, or a file, or some other drawing device.

If canvas-refresh is called and no canvas exists, the implementation
is expected to do something reasonable.  In the case of the reference
implementation, canvas-refresh returns a file name that could have
been used for drawing; the file may or may not exist.  In case of a
window-based implementation, it is reasonable to return a value that
could serve as a window indentifier.  If an implementation displays
images in the REPL, canvas-refresh might return an empty picture
value.

--
Wolfgang Corcoran-Mathe  <xxxxxx@sigwinch.xyz>

"All this currying's just a phase, though it seldom hinders."
--Fritz Ruehr