From 35eb9e77a0a2d481444b79c9ceab7b0470799e7f Mon Sep 17 00:00:00 2001
From: Hajime Hoshi <hajimehoshi@gmail.com>
Date: Tue, 31 Mar 2020 01:56:22 +0900
Subject: [PATCH] ui: Improve comments about Game interface

This change also fixes comments in uiConttext, which seems pretty
old.
---
 run.go       | 11 +++++++++--
 uicontext.go |  7 ++++---
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/run.go b/run.go
index cd63fb67f..d044054ea 100644
--- a/run.go
+++ b/run.go
@@ -28,16 +28,23 @@ type Game interface {
 	// Basically Update updates the game logic, and whether Update draws the screen depends on the existence of
 	// Draw implementation.
 	//
+	// The give argument represents a screen image. Whether the updated content is used or not
+	// depends on the existence of Draw definition.
+	//
 	// With Draw, Update updates only the game logic and Draw draws the screen. This is recommended.
+	// In this case, the argument screen's updated content is not adopted and is always cleared.
 	//
 	// Without Draw, Update updates the game logic and also draws the screen. This is a legacy way.
-	Update(*Image) error
+	// In this case, the argument screen's updated content is adopted as the actual game screen.
+	Update(screen *Image) error
 
 	// Draw draws the game screen by one frame.
 	//
+	// The give argument represents a screen image. The updated content is adopted as the game screen.
+	//
 	// Draw is an optional function for backward compatibility.
 	//
-	// Draw(*Image) error
+	// Draw(screen *Image) error
 
 	// Layout accepts a native outside size in device-independent pixels and returns the game's logical screen
 	// size.
diff --git a/uicontext.go b/uicontext.go
index 1bb8cc774..daba86085 100644
--- a/uicontext.go
+++ b/uicontext.go
@@ -259,6 +259,10 @@ func (c *uiContext) update(afterFrameUpdate func()) error {
 			if err := hooks.RunBeforeUpdateHooks(); err != nil {
 				return err
 			}
+
+			// Multiple successive Clear call should be integrated into one graphics command, then
+			// calling Clear on every Update should not affect the performance.
+			c.offscreen.Clear()
 			if err := c.game.Update(c.offscreen); err != nil {
 				return err
 			}
@@ -266,15 +270,12 @@ func (c *uiContext) update(afterFrameUpdate func()) error {
 			afterFrameUpdate()
 		}
 
-		// Mipmap images should be disposed by Clear.
 		c.offscreen.Clear()
-
 		game.Draw(c.offscreen)
 	} else {
 		for i := 0; i < updateCount; i++ {
 			c.updateOffscreen()
 
-			// Mipmap images should be disposed by Clear.
 			c.offscreen.Clear()
 
 			setDrawingSkipped(i < updateCount-1)