Display rendering engine screenshots (#3738)

components/display/index.rst

@@ -45,6 +45,9 @@ this behavior by setting ``auto_clear_enabled: false``.
 In the lambda, you can write code like in any :ref:`lambda <config-lambda>` in ESPHome. Display
 lambdas are additionally passed a variable called ``it`` which represents the rendering engine object.
 
+.. figure:: images/display_rendering_line.png
+    :align: center
+
 .. code-block:: yaml
 
     display:
@@ -74,8 +77,10 @@ the rendering engine is always first specify the ``x`` coordinate and then the `
 Basic Shapes
 ------------
 
-Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles
-and circles:
+Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles, circles or even polygons:
+
+.. figure:: images/display_rendering_shapes.png
+    :align: center
 
 .. code-block:: yaml
 
@@ -85,27 +90,27 @@ and circles:
         lambda: |-
           // Draw a line from [0,0] to [100,50]
           it.line(0, 0, 100, 50);
-          // Draw the outline of a rectangle with the top left at [50,60], a width of 30 and a height of 42
-          it.rectangle(50, 60, 30, 42);
-          // Draw the same rectangle, but this time filled.
-          it.filled_rectangle(50, 60, 30, 42);
+          // Draw the outline of a rectangle with the top left at [5,20], a width of 30 and a height of 42
+          it.rectangle(5, 20, 30, 42);
+          // Draw the same rectangle a few pixels apart, but this time filled
+          it.filled_rectangle(40, 40, 30, 42);
 
-          // Circles! Let's draw one with the center at [25,25] and a radius of 10
-          it.circle(25, 25, 10);
+          // Circles! Let's draw one with the center at [20,40] and a radius of 10
+          it.circle(20, 40, 10);
           // ... and the same thing filled again
-          it.filled_circle(25, 25, 10);
+          it.filled_circle(20, 75, 10);
 
           // Triangles... Let's draw the outline of a triangle from the [x,y] coordinates of its three points
-          // [25,5], [5,25], [50,50]
-          it.triangle(25, 5, 5, 25, 50, 50);
+          // [25,5], [100,5], [80,25]
+          it.triangle(25, 5, 100, 5, 80, 25);
           // and a filled triangle !
-          it.filled_triangle(125, 5, 105, 25, 150, 50);
+          it.filled_triangle(115, 5, 95, 25, 125, 70);
 
-          // Regular Polygons? Let's draw the outline of a pointy-topped hexagon inscribed in a circle 
-          // centered on [x1=100,y1=100] with a radius of 50
-          it.regular_polygon(100, 100, 50, EDGES_HEXAGON);
-          // and a filled flat-topped octagon!
-          it.filled_regular_polygon(200, 200, 50, EDGES_OCTAGON, VARIATION_FLAT_TOP);
+          // Regular Polygons? Let's draw a filled, pointy-topped hexagon inscribed in a circle 
+          // centered on [170,45] with a radius of 20
+          it.filled_regular_polygon(170, 45, 20, EDGES_HEXAGON);
+          // and the outline of flat-topped octagon around it!
+          it.regular_polygon(170, 45, 40, EDGES_OCTAGON, VARIATION_FLAT_TOP);
           // Need to rotate the polygon, or retrieve the coordinates of its vertices? Check the API!
 
 All the above methods can optionally also be called with an argument at the end which specifies in which
@@ -117,33 +122,35 @@ color to draw. For monochrome displays, only ``COLOR_ON`` (the default if color
       - platform: ...
         # ...
         lambda: |-
-          // Turn the whole display on.
+          // Turn the whole display on
           it.fill(COLOR_ON);
-          // Turn the whole display off.
+          // Turn the whole display off
           it.fill(COLOR_OFF);
 
           // Turn a single pixel off at [50,60]
           it.draw_pixel_at(50, 60, COLOR_OFF);
 
-          // Turn off a whole display portion.
-          it.rectangle(50, 50, 30, 42, COLOR_OFF);
-
 For color displays (e.g. TFT displays), you can use the Color class.
 
+.. figure:: images/display_rendering_colors.png
+    :align: center
+
 .. code-block:: yaml
 
     display:
       - platform: ...
         # ...
         lambda: |-
+          auto black = Color(0, 0, 0);
           auto red = Color(255, 0, 0);
           auto green = Color(0, 255, 0);
           auto blue = Color(0, 0, 255);
           auto white = Color(255, 255, 255);
-          it.rectangle(20, 50, 30, 30, white);
-          it.rectangle(25, 55, 30, 30, red);
-          it.rectangle(30, 60, 30, 30, green);
-          it.rectangle(35, 65, 30, 30, blue);
+          it.filled_circle(20, 32, 15, black);
+          it.filled_circle(40, 32, 15, red);
+          it.filled_circle(60, 32, 15, green);
+          it.filled_circle(80, 32, 15, blue);
+          it.filled_circle(100, 32, 15, white);
 
 Additionally, you have access to two helper methods which will fetch the width and height of the display:
 
@@ -156,6 +163,8 @@ Additionally, you have access to two helper methods which will fetch the width a
           // Draw a circle in the middle of the display
           it.filled_circle(it.get_width() / 2, it.get_height() / 2, 20);
 
+          // Turn off bottom half of the screen
+          it.filled_rectangle(0, it.get_height()/2, it.get_width(), it.get_height()/2, COLOR_OFF);
 
 You can view the full API documentation for the rendering engine in the "API Reference" in the See Also section.
 
@@ -218,6 +227,10 @@ In case of fonts rendered at higher bit depths, the background color has to be s
           // Syntax is always: it.print(<x>, <y>, <font>, [color=COLOR_ON], [align], <text>, [color=COLOR_OFF]);
           it.print(0, 0, id(my_font_with_icons), COLOR_ON, TextAlign::CENTER, "Just\U000f05d4here. Already\U000F02D1this.", COLOR_OFF);
 
+
+.. figure:: images/display_rendering_text.png
+    :align: center
+
 .. _display-printf:
 
 Formatted Text
@@ -457,13 +470,8 @@ memory at the time the sensor updates and will be lost when the device reboots.
 
 Examples:
 
-.. figure:: images/graph_screen.png
+.. figure:: images/display_rendering_graph.png
     :align: center
-    :width: 60.0%
-
-.. figure:: images/graph_dualtrace.png
-    :align: center
-    :width: 60.0%
 
 Graph component with options for grids, border and line-types.