xod/graphics library provides the standard set of nodes to create graphics and graphic interfaces. This library describes various geometric and graphical objects and contains their rasterization and rendering methods, which are required for their further presentation on displays such as LCDs and OLEDs.
graphics library only can build images and has to be used with a particular display library to show it on the screen.
A digital image consists of pixels. A pixel is the smallest logical element of an image in raster graphics, as well as a physical element of the display matrix. Pixel is a two-dimensional element. It has two coordinates (X, Y) in a two-dimensional coordinate system. Traditionally, the origin (0, 0) of the coordinate system for an image or graphic display is at the top-left corner.
Pixel coordinates are integer values. In XOD, pixel coordinate values have the Number type. Floating-point values are truncated down to integers. For example, a pixel specified as (5.89, 2.02) is displayed on the screen at (5, 2).
In addition to coordinates, each pixel has its color. In XOD the color of a pixel is set by the Color type value stored as 24 bits, one for each component R, G, and B. This color type has a color depth named True color and has a palette of 2²⁴ = 16,777,216 colors. However, not every display can handle so many color variations. For example, the ST7735 display operates the High color color depth with the palette of 65,536 colors, while the SSD1306 display is monochrome and operates only with black and white color. In XOD, the pixel color is automatically reduced to the acceptable resolution for a particular display.
The building process of any scene begins with the
canvas node. It is the entry point and the first object in the tree of graphic elements of the scene. Physically
canvas defines a specific area on the screen that is subjected to the rendering process.
Сanvas has a rectangular shape. It is defined by the pivot point (
Y), which is its upper-left vertex, width
W , and height
H in pixels. The pivot point of the canvas is a specific pixel on the matrix of a display and its coordinates are related to the display matrix coordinate system.
Canvas can take up the entire display matrix or be a part of it. The display matrix may contain several
canvas at the same time. When initialized, the canvas creates a new coordinate system within itself. This new system is used to position all child graphic elements in a tree of the scene.
A value at the
BG pin of the
canvas node sets the background color for all pixels in the selected area of the screen. The
FG pin value sets the foreground color of the scene. This color is the default for all child graphic elements located on the canvas.
The image scene is a tree of various graphic elements (geometric objects, text, bitmap images, and icons) that reside on a
A tree may have no elements, be strictly linear, or expand and form new branches. The order in which the elements of the graphical tree are located determines the order in which these elements are displayed on the screen. Amongst themselves, tree elements link through the
GFX node pins.
To show the image on the screen of the device, it should be rendered. For this, the
render node is used. The rendering process is different for each specific display device so in XOD, each display library contains its own
render node is a kind of “end of the tree branch”. On a
pulse signal this node processes one branch of the graphic tree for a given
canvas and displays the resulting image on the screen.
Each branch of the tree can be rendered independently of other branches. A single tree branch can be linked to multiple
render nodes to be displayed on different devices.
Each graphic element has its node. Graphical elements in XOD are dynamic; i.e., they can change all their properties in real-time.
It is the most basic graphic element. Point is set on canvas by coordinates (
point node describes a point with a thickness of 1 pixel and the default foreground color of the scene. You can set any color for a point using the
The line is set on canvas by two points, the start point (
Y0) and the endpoint (
Y1). Any point order is OK.
line node describes a line with a thickness of 1 pixel and the default foreground color of the scene. You can set any color for a line using the
The rectangle is set on canvas by a pivot point (
Y), which is its upper-left vertex, width
W, and height
A rectangle can be filled with a solid color or represent an unfilled rectangle frame. Filled and non-filled rectangles have different sets of nodes.
rect-outline node describes a rectangle frame with a thickness of 1 pixel and the default foreground color of the scene. You can set any color for a frame using the
rect-solid node describes a rectangle filled with a solid default foreground color of the scene. You can fill a rectangle with any color using the
The circle is set on canvas by a center point (
Y), and radius
A circle can be filled with a solid color or represent an unfilled circle frame. Filled and non-filled circles have different sets of nodes.
circle-outline node describes a circle frame with a thickness of 1 pixel and the default foreground color of the scene. You can set any color for a frame using the
circle-solid node describes a circle filled with a solid default foreground color of the scene. You can fill a circle with any color using the
The triangle is set on canvas by three points (
Y1), and (
Y2). The order of points can be any.
A triangle can be filled in with a solid color or represent an unfilled triangle frame. Filled and non-filled triangles have different sets of nodes.
triangle-outline node describes a triangle frame with a thickness of 1 pixel and the default foreground color of the scene. You can set any color for a frame using the
triangle-solid node describes a triangle filled with a solid default foreground color of the scene. You can fill a triangle with any color using the
You can display various text strings on the screen.
Currently, the only supported text font is one that is used in the firmware of sign-generating displays. This font has a dimension of 5x7 pixels.
The text string is set on canvas by the start point (
Y), which is the upper-left vertex of the first character in a string.
To define the text string the
text-colored nodes are used.
text node displays a String specified at the
S pin with the default foreground color of the scene.
text-colored node you can set a string of any color.
Text can be scaled using the
SCL pin. A simple pixel-based magnification algorithm is used, so the value should be an integer greater or equal to 1. The resulting text is scaled N times, where N is the value specified at the
You can display bitmap images and icons on the display screen.
Read more in the loading images article.
XOD provides display device libraries to render graphics. For more information about working with a library of a specific display, see the article on this display’s library. Currently, there are libraries for the following displays devices:
xod-dev/ssd1306-displaylibrary to work with SSD1306 displays.
xod-dev/st7735-displaylibrary to work with ST7735 displays.
rendernode with a bound device to render it.
canvasbounds is not rendered and shown on the screen.