Write down the steps during rendering.

server/render.c

@@ -66,6 +66,22 @@ static int render_scroller(Widget *w, int left, int top, int right, int bottom,
 static int render_num(Widget *w, int left, int top, int right, int bottom);
 
 
+/**
+ * Renders a screen. The following actions are taken in order:
+ *
+ * \li  Clear the screen.
+ * \li  Set the backlight.
+ * \li  Set out-of-band data (output).
+ * \li  Render the frame contents.
+ * \li  Set the cursor.
+ * \li  Draw the heartbeat.
+ * \li  Show any server message.
+ * \li  Flush all output to screen.
+ *
+ * \param s      The screen to render.
+ * \param timer  A value increased with every call.
+ * \return  -1 on error, 0 on success.
+ */
 int
 render_screen(Screen *s, long timer)
 {
@@ -76,15 +92,18 @@ render_screen(Screen *s, long timer)
 	if (s == NULL)
 		return -1;
 
-	/* Clear the LCD screen... */
+	/* 1. Clear the LCD screen... */
 	drivers_clear();
 
-	/* FIXME drivers_backlight --
+	/* 2. Set up the backlight */
-	 *
+	/*-
-	 * If the screen's backlight isn't set (default) then we
+	 * 2.1:
-	 * inherit the backlight state from the parent client. This allows
+	 * First we find out who has set the backlight:
-	 * the client to override it's childrens settings.
+	 *   a) the screen,
-	 * The server can also override the clients and screens settings.
+	 *   b) the client, or
+	 *   c) the server core
+	 * with the latter taking precedence over the earlier. If the
+	 * backlight is not set on/off then use the fallback (set it ON).
 	 */
 	if (backlight != BACKLIGHT_OPEN) {
 		tmp_state = backlight;
@@ -99,7 +118,11 @@ render_screen(Screen *s, long timer)
 		tmp_state = backlight_fallback;
 	}
 
-	/* Set up backlight to the correct state... */
+	/*-
+	 * 2.2:
+	 * If one of the backlight options (FLASH or BLINK) has been set turn
+	 * it on/off based on a timed algorithm.
+	 */
 	/* NOTE: dirty stripping of other options... */
 	/* Backlight flash: check timer and flip backlight as appropriate */
 	if (tmp_state & BACKLIGHT_FLASH) {
@@ -122,17 +145,18 @@ render_screen(Screen *s, long timer)
 		drivers_backlight(tmp_state & BACKLIGHT_ON);
 	}
 
-	/* Output ports from LCD - outputs depend on the current screen */
+	/* 3. Output ports from LCD - outputs depend on the current screen */
 	drivers_output(output_state);
 
-	/* Draw a frame... */
+	/* 4. Draw a frame... */
 	render_frame(s->widgetlist, 0, 0,
 			display_props->width, display_props->height,
 			s->width, s->height, 'v', max(s->duration / s->height, 1), timer);
 
-	/* Set the cursor */
+	/* 5. Set the cursor */
 	drivers_cursor(s->cursor_x, s->cursor_y, s->cursor);
 
+	/* 6. Set the heartbeat */
 	if (heartbeat != HEARTBEAT_OPEN) {
 		tmp_state = heartbeat;
 	}
@@ -147,7 +171,7 @@ render_screen(Screen *s, long timer)
 	}
 	drivers_heartbeat(tmp_state);
 
-	/* If there is an server message that is not expired, display it */
+	/* 7. If there is an server message that is not expired, display it */
 	if (server_msg_expire > 0) {
 		drivers_string(display_props->width - strlen(server_msg_text) + 1,
 				display_props->height, server_msg_text);
@@ -157,7 +181,7 @@ render_screen(Screen *s, long timer)
 		}
 	}
 
-	/* flush display out, frame and all... */
+	/* 8. Flush display out, frame and all... */
 	drivers_flush();
 
 	debug(RPT_DEBUG, "==== END RENDERING ====");