JavaFX on E-Paper

This project builds a Java application to test the new support in JavaFX for devices with electronic paper, also known as electronic ink. The project website contains videos of the application running on an actual e-paper display.

The application uses only the javafx.base and javafx.graphics modules of the JavaFX SDK. Because it's written in Java, it runs without modification on desktop computers running Windows, macOS, or Linux. The Apache NetBeans IDE makes it easy to run, debug, and profile the application both locally on a development workstation and remotely on an e-paper device.

The goal is to be able to run JavaFX applications on e-paper devices simply by creating a chroot environment with a small Ubuntu Base image and installing JavaFX with:

$ sudo apt-get install openjfx

Background

The support is added to JavaFX as a new Monocle platform called EPD, for E-Paper Display. The design of the EPD platform is described by the Request for Enhancement in Issue #339, "JDK-8217605: Add support for e-paper displays." The implementation for JavaFX 13 is found in Pull Request #369.

Licenses

The content of this project is licensed under the GNU General Public License v3.0 except for the video files in the docs/videos directory, which are licensed under the Creative Commons Attribution-ShareAlike 4.0 International license.

Building

The application is a project of the Apache NetBeans IDE with the following settings:

• the Java platform is the default (JDK 12 on my system),
• the source and binary format is JDK 12,
• a global library named "JavaFX 12" contains the JavaFX SDK version 12.0.1,
• the JavaFX JAR files are in ${user.home}/lib/javafx-sdk-12.0.1/lib, and
• the JavaFX source files in the archive lib/src.zip are unzipped into ${user.home}/lib/javafx-sdk-12.0.1/src.

Usage

The program accepts the parameters listed below, specified in the format: --name=value.

• width – the width of the JavaFX scene in pixels. The minimum width is 400. The default width is the width of the primary screen.
• height – the height of the JavaFX scene in pixels. The minimum height is 300. The default height is the height of the primary screen.
• pattern – the number of the pattern to display (see the examples below). There are three patterns: 1 (move), 2 (sweep), and 3 (image). The default pattern is 1 (move).
• levels – the number of gray levels when the pattern is 2 (sweep). There are four levels: 1 (black), 2 (1-bit monochrome), 4 (2-bit grayscale), and 16 (4-bit grayscale). The default is 1 (black).
• loops – The number of animation loops. A value of 0 (zero) means to loop until the application is terminated.
• image – The name of a bilevel and coalesced animated GIF file when the pattern is 3 (image). The default file name is duke-waving.gif, bundled with the application. The default file name for the unit tests is doll-dancing.gif, found under the test directory. Any other image file must be located in the same directory as the epd-javafx.jar file.
• patrol – The type of loop cycle when the pattern is 3 (image): true to cycle back and forth between the first and last frames of the animation, called a patrol cycle; otherwise false to loop back to the first frame after the last. The default is false.

The animation patterns are implemented as subclasses of the JavaFX AnimationTimer class:

• The move pattern is displayed by the MoveAnimation timer.
• The sweep pattern is displayed by the SweepAnimation timer.
• The image pattern is displayed by the ImageAnimation timer.

Examples

Variations of the application parameters and system properties are shown below. The timing of the image on the left is set to approximate the speed of the animation on an actual e-paper display. See the videos for examples of these patterns on e-paper, including pattern 3 (image).

Pattern	Description
	Pattern 1, waveform mode 4, with wait, at 7.7 fps (130 ms/frame) java ... -Dmonocle.epd.waveformMode=4 -jar epd-javafx.jar
	Pattern 2, waveform mode 4, no wait, at 20 fps (50 ms/frame) java ... -Dmonocle.epd.waveformMode=4 -Dmonocle.epd.noWait=true -jar epd-javafx.jar --pattern=2
	Pattern 2, auto waveform mode, one gray level, at 4.3 fps (230 ms/frame) java ... -jar epd-javafx.jar --pattern=2 --levels=1
	Pattern 2, auto waveform mode, two gray levels, at 4.8 fps (210 ms/frame) java ... -jar epd-javafx.jar --pattern=2 --levels=2
	Pattern 2, auto waveform mode, four gray levels, at 1.9 fps (520 ms/frame) java ... -jar epd-javafx.jar --pattern=2 --levels=4
	Pattern 2, auto waveform mode, 16 gray levels, at 1.9–2.2 fps (470–520 ms/frame), depending on the waveform mode selected java ... -jar epd-javafx.jar --pattern=2 --levels=16