9 files changed, 98 insertions(+), 0 deletions(-)

A module-services/service-gui/doc/README.md
A module-services/service-gui/doc/display_environment_init.png
A module-services/service-gui/doc/display_environment_init.pu
A module-services/service-gui/doc/handle_draw_request.png
A module-services/service-gui/doc/handle_draw_request.pu
A module-services/service-gui/doc/update_eink_if_busy.png
A module-services/service-gui/doc/update_eink_if_busy.pu
A module-services/service-gui/doc/update_eink_if_idle.png
A module-services/service-gui/doc/update_eink_if_idle.pu

@@ 0,0 1,46 @@
+# GUI service
+
+The GUI service is responsible for rendering frames and sharing them with the E Ink service. This includes:
+- Managing the pool of contexts
+- Dropping frames that are not needed anymore
+- Rendering frames
+- Controlling the flow of sharing frames with the E Ink service
+
+## Pool of contexts
+
+The context is a drawing area. It is used by a renderer to render a frame, which is then forwarded by the GUI service to the E Ink service.
+
+The pool of contexts provides exclusive access to a context in a multithreaded environment. The renderer service locks the context during rendering process. The context is unlocked and available for the renderer service again once it's not used by any other object, e.g. it was displayed by the E Ink service, or cached by the GUI service for later use.
+
+## Initialization
+
+The GUI service is initialized on the E Ink service demand. It uses information received from the E Ink service in order to initialize its resources, e.g. ContextPool.
+
+![](display_environment_init.png)
+
+## Handling draw requests
+
+Draw request is an application's request used to render the screen.
+
+![](handle_draw_request.png)
+
+### Dropping expired draw requests
+
+If a consecutive request comes to the GUI service, all awaiting requests which deal with the same display area are marked as expired and dropped.
+This solution makes the display more responsive. Removing it from the current implementation may introduce a latency visible to a user when e.g. writing a message.
+
+## Sharing the frame with the E Ink service
+
+### Idle state
+
+If the GUI service is not busy waiting for the previous frame to be displayed by the E Ink service, it immediately sends the rendered frame to the E Ink service.
+
+![](update_eink_if_idle.png)
+
+### Busy state
+
+The GUI service may render a few next frames while the E Ink service is updating the display. If so, the GUI service caches the last rendered frame and immediately sends it to the E Ink service once it finishes its job.
+
+![](update_eink_if_busy.png)
+
+

@@ 0,0 1,12 @@
+@startuml
+participant "Service E Ink" as eink
+participant "Service GUI" as gui
+participant "Context Pool" as pool
+
+eink -> gui: DisplayReadyNotification()
+activate gui
+
+gui -> gui: setState(Idle)
+gui -> pool ** : create
+
+@enduml

@@ 0,0 1,18 @@
+@startuml
+participant "Application" as app
+participant "Service GUI" as gui
+participant "Context Pool" as pool
+participant "Rendering Worker" as worker
+participant "Service E Ink" as eink
+
+app -> gui: Draw request
+gui -> eink: Prepare display
+gui -> worker: Drop awaiting requests
+gui -> worker: Add new request
+activate worker
+
+worker -> pool: Borrow context
+worker -> worker: Render
+return Finished(contextId)
+
+@enduml

@@ 0,0 1,8 @@
+@startuml
+participant "Service GUI" as gui
+participant "Context Pool" as pool
+
+gui -> gui: Cache frame
+gui -> pool: Return context
+
+@enduml

@@ 0,0 1,14 @@
+@startuml
+participant "Service GUI" as gui
+participant "Context Pool" as pool
+participant "Service E Ink" as eink
+
+gui -> pool: Peek processed context
+gui -> eink: Display context
+return FinishedNotification
+gui -> pool: Return context
+group If next frame ready
+	gui -> eink: Display context
+end
+
+@enduml