Update README

README.md

@@ -111,10 +111,10 @@ Controlling the aesthetic appearance of the shapes.
 
 Adding primitives, vertices, and curves to app.
 
-- [app.**point**](#app-point)
-- [app.**line**](#app-line)
-- [app.**rect**](#app-rect)
-- [app.**pixels**](#app-pixels)
+- [app.**point**](#app-point) - Draws a single cell at the specified coordinates (x, y) and returns this app.
+- [app.**line**](#app-line) - Draws a straight path from the specified coordinates (_x_, _y_) to coordinates (_x1_, _y1_) and returns this app.
+- [app.**rect**](#app-rect) - Draws a rectangle at the specified coordinates (_x_, _y_) with specified _width_ and _height_ and returns this app.
+- [app.**pixels**](#app-pixels) - Draws pixels specified by the _render_ function at the specified coordinates (_x_, _y_) and returns this app.
 
 ### [Applying Transformations](#applying-transformations-1)
 
@@ -242,38 +242,50 @@ cm.wide("🚀");
 
 <a name="app-point" href="#app-point">#</a> app.**point**(_x, y_)
 
+Draws a single cell at the specified coordinates (_x_, _y_) and returns this app. To color a point, use [_app_.stroke](#app-stroke). A point can't be filled, so [_app_.fill](#app-fill) does not affect the color of a point. If [_app_.noStroke](#app-nostroke) is called, the point will not be drawn to the app. For example, to draw a `'@'` character at the middle cell:
+
 ```js
-app.point(0, 0);
+app.stroke("@", "steelblue", "orange");
+app.point(app.cols() / 2, app.rows() / 2);
 ```
 
 <a name="app-line" href="#app-line">#</a> app.**line**(_x, y, x1, y1_)
 
+Draws a straight path from the specified coordinates (_x_, _y_) to coordinates (_x1_, _y1_) and returns this app. To color a line, use [_app_.stroke](#app-stroke). A line can't be filled, so [_app_.fill](#app-fill) does not affect the color of a line. If [_app_.noStroke](#app-nostroke) is called, the line will not be drawn to the app. For example, to draw a line from top-left to bottom-right:
+
 ```js
-app.line(0, 0, 10, 10);
+app.stroke("@", "steeblue", "orange");
+app.line(1, 1, 5, 5);
 ```
 
 <a name="app-rect" href="#app-rect">#</a> app.**rect**(_x, y, width, height_)
 
+Draws a rectangle at the specified coordinates (_x_, _y_) with specified _width_ and _height_ and returns this app. To stroke and fill a rect, use [_app_.stroke](#app-stroke) and [_app_.fill](#app-fill) respectively. For example, to draw a rectangle filled with `'X'` and stroked with `'O'`:
+
 ```js
+app.stroke("O");
+app.fill("X");
 app.rect(0, 0, 10, 10);
 ```
 
-<a name="app-pixels" href="#app-pixels">#</a> app.**pixels**(_x, y, render_)
+<a name="app-pixels" href="#app-pixels">#</a> app.**pixels**(_x, y, top, render_)
 
-```js
-for (let i = 0; i < app.cols() * app.rows(); i++) {
-  app.stroke(" ", "#fff", i % 2 === 0 ? "#000" : "#fff");
-  app.point(i % app.cols(), (i / app.cols()) | 0);
-}
+Draws pixels specified by the _render_ function at the specified coordinates (_x_, _y_) and returns this app. Unlike other shape APIs to draw shapes in cell coordinates, this method is intended for when you want to draw something to the app's [rendering context](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D), say for annotation.
 
-app.pixels(5, 5, (context) => {
-  const r = Math.max(app.cellWidth(), app.cellHeight()) / 2;
-  context.fillStyle = "orange";
-  context.beginPath();
-  context.arc(-r, -r, r, 0, 2 * Math.PI);
-  context.closePath();
-  context.fill();
-});
+The _render_ function is passed the app's rendering context. Before calling the _render_ function, the context calls [_context_.save](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save) and translate to the pixels coordinates transformed from the specified cell coordinates (_x_, _y_). And the context calls [_context_.restore](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/restore) after the _render_ function being called. This guarantees every _app_.pixels calls having independent rendering context and sharing the same coordinates system with other shape APIs.
+
+If _top_ is true, the _render_ function is called after drawing cells, say for drawing pixels on top of cells. Otherwise, the _render_ function is called before drawing cells, say for drawing pixels at bottom of cells. For example, to draw two four-cells rectangles before and after cells.
+
+```js
+app
+  .pixels(2, 2, true, (context) => {
+    context.fillStyle = "orange";
+    context.fillRect(0, 0, app.cellWidth() * 2, app.cellHeight() * 2);
+  })
+  .pixels(5, 5, false, (context) => {
+    context.fillStyle = "orange";
+    context.fillRect(0, 0, app.cellWidth() * 2, app.cellHeight() * 2);
+  });
 ```
 
 ## Applying Transformations