# Escher

## Overview

Escher is a C++/Vulkan library that is used primarily by the Scenic implementation; it is not
exposed by the Fuchsia SDK. It provides utilities for:

1. Abstracting and optimizing simple operations with Vulkan, such as:

   - Pipeline reuse
   - Color correction with less memory bandwidth
     - Specification of sub-passes (and render-passes in general) is a bit more convenient in Escher than raw Vulkan, but it's pretty much the same idea, not significantly abstracted.
     - For example, Escher supports sub-passes within a single Vulkan render-pass. That is, when a second sub-pass needs to access a pixel at the same location, then it performs the transform inside the cached data without leaving the GPU memory hierarchy.
   - Updating buffers and sending draw commands directly
   - Resource lifetime management
     - For example, if you submit a Vulkan command-buffer which renders using a texture, and then delete the texture before rendering is complete, the result is undefined; a crash is likely. Escher doesn't delete the texture (or buffer) until it is no longer referenced by any active command buffers.
2. Higher-level domain-specific renderers specific to Scenic, such as:

   a. `RectangleCompositor`, a simple compositor used by Flatland's `VkRenderer` to load display list contents into a single output image known as a framebuffer
   - RectangleCompositor leverages:
     - Flatland-specific Color Correction Vertex and Fragment Shaders, for use when Scenic performs color-correction using Vulkan
     - Flatland-specific Vertex and Fragment Shaders, for use when color correction is delegated to the display driver or not required at all
   - See the [`rainfall` example](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/ui/examples/escher/README.md) for use of RectangleCompositor.

   b. `PaperRenderer`, a deprecated compositor used by Gfx which builds the abstraction for performing efficient 3D UX computations that were envisioned at the time. See the [`waterfall`](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/ui/examples/escher/README.md) example for use of PaperRenderer.

Together, these libraries support rapid iteration and resource lifecycle management beyond what would be sustainably achievable when using Vulkan alone.

## Cross-platform support

With a few exceptions, Escher is not platform-dependent. For example, the Escher examples can also
be run on Linux. This provides two distinct benefits:

- Faster iteration in development. Recompiling Escher and running to debug is much faster on Linux than on Fuchsia.
- On other platforms, the Vulkan ecosystem provides a wide variety of development tools which are not available on Fuchsia. For example, the [RenderDoc graphics debugger](http://renderdoc.org) was very useful during the development of Escher.

## GLSL support

Vulkan only accepts shader source code in the SPIR-V format. Escher optionally supports consuming GLSL, the human-readable format, then calls `shaderc::Compiler` to compile it to SPIR-V before loading into Vulkan.

## Source Code

The source code lives in [//src/ui/lib/escher/](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/ui/lib/escher).
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/graphics/escher/README.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/graphics/escher/README.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/graphics/escher/README.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/graphics/escher/README.md "Edit the source code of this page")