ui: Improve comments about Game interface

This change also fixes comments in uiConttext, which seems pretty
old.

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.

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)