diff --git a/components/display/images/display_rendering_colors.png b/components/display/images/display_rendering_colors.png new file mode 100644 index 000000000..df5830179 Binary files /dev/null and b/components/display/images/display_rendering_colors.png differ diff --git a/components/display/images/display_rendering_graph.png b/components/display/images/display_rendering_graph.png new file mode 100644 index 000000000..9c2c30d45 Binary files /dev/null and b/components/display/images/display_rendering_graph.png differ diff --git a/components/display/images/display_rendering_line.png b/components/display/images/display_rendering_line.png new file mode 100644 index 000000000..633c0d42a Binary files /dev/null and b/components/display/images/display_rendering_line.png differ diff --git a/components/display/images/display_rendering_shapes.png b/components/display/images/display_rendering_shapes.png new file mode 100644 index 000000000..b6a034710 Binary files /dev/null and b/components/display/images/display_rendering_shapes.png differ diff --git a/components/display/images/display_rendering_text.png b/components/display/images/display_rendering_text.png new file mode 100644 index 000000000..3e5fb7834 Binary files /dev/null and b/components/display/images/display_rendering_text.png differ diff --git a/components/display/images/graph_dualtrace.png b/components/display/images/graph_dualtrace.png deleted file mode 100644 index 4beeacf91..000000000 Binary files a/components/display/images/graph_dualtrace.png and /dev/null differ diff --git a/components/display/images/graph_screen.png b/components/display/images/graph_screen.png deleted file mode 100644 index a47ed6ca5..000000000 Binary files a/components/display/images/graph_screen.png and /dev/null differ diff --git a/components/display/index.rst b/components/display/index.rst index 55b38afc6..3f8ef5a40 100644 --- a/components/display/index.rst +++ b/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 ` 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(, , , [color=COLOR_ON], [align], , [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.