[Impeller] libImpeller: Tinker on the README. (flutter/engine#56761)
Also adds references to the C++ wrapper and examples.
This commit is contained in:
Chinmay Garde
GitHub
parent
4a17eac8a1
commit
219060790d
@ -1,57 +1,36 @@
|
||||
# Impeller Standalone SDK
|
||||
|
||||
## Goals
|
||||
A single-header C API for 2D graphics and text rendering. [Impeller](../../README.md) is used by Flutter for rendering but can be consumed by non-Flutter applications and projects.
|
||||
|
||||
This Impeller Standalone API is a single-header C API with no external dependencies.
|
||||
|
||||
### Full-featured
|
||||
|
||||
The library supports all rendering operations supported by Flutter with few exceptions. An optional text-layout and shaping engine is included by default.
|
||||
|
||||
### Easy to Embed
|
||||
|
||||
The entire library is distributed as a single dynamic library. The public API can be found in a single C header with no dependencies.
|
||||
|
||||
For the common platforms, prebuilt artifacts are generated per Flutter Engine commit.
|
||||
|
||||
### Easy Interoperability
|
||||
|
||||
The C API allows for explicit management of object lifecycle and is well suited for the generation of automated bindings to languages like Rust, Dart, Lua, etc…
|
||||
|
||||
### Lightweight
|
||||
|
||||
The core rendering engine is less than 200 KB compressed.
|
||||
|
||||
The text layout and shaping engine along with the bundled ICU data tables brings the size up to ~2.5 MB. If the application does not need text layout and shaping, or can interface with an existing library on the target platform, it is recommended to generate the SDK without built-in support for typography. Impeller is a rendering engine but typography is really hard to get right and needed by most users of a rendering engine. That is why one is included by default. But it is optional.
|
||||
|
||||
> [!CAUTION]
|
||||
> Users of the prebuilt artifacts should strip the binaries before deployment as these contain debug symbols.
|
||||
|
||||
### Performant
|
||||
|
||||
Built to perform the best when using a modern graphics API like Metal or Vulkan (not all may be available to start) and when running on mobile tiler GPUs like the ones found in smartphones and AppleSilicon/ARM desktops.
|
||||
|
||||
Impeller does need a GPU. Performance will likely be inadequate for interactive use cases when using software rendering. Software rendering can be enabled using projects like SwiftShader, Angle, LLVMPipe, etc… If you are using software rendering in your projects, restrict its use to testing on CI. Impeller will likely never have a dedicated software renderer.
|
||||
|
||||
# API Stability
|
||||
|
||||
Unlike the Flutter Embedder API which has a stable API as well as ABI, the Impeller API does **not** currently have stability guarantees.
|
||||
|
||||
The API does look similar to the one used by Flutter in Dart so major overhauls are not realistically on the horizon.
|
||||
|
||||
The API is also versioned and there may be stability guarantees between specific versions in the future.
|
||||
* **Full-featured**
|
||||
* The library supports all rendering operations supported by Flutter with few exceptions.
|
||||
* An optional text-layout and shaping engine is included by default.
|
||||
* **Easy to Embed**
|
||||
* The entire library is distributed as a single library with a C API.
|
||||
* The C API is single-header with no platform dependencies.
|
||||
* For the common platforms, [prebuilt artifacts](#prebuilt-artifacts) are generated per Flutter Engine commit.
|
||||
* **Easy Interoperability**
|
||||
* The C API allows for explicit management of object lifecycle and is well suited for the generation of automated bindings to languages like Rust, Dart, Lua, etc…
|
||||
* **Lightweight**
|
||||
* The core rendering engine is less than 200 KB compressed.
|
||||
* The text layout and shaping engine along with the bundled ICU data tables brings the size up to ~2.5 MB.
|
||||
* If the application does not need text layout and shaping, or can interface with an existing library on the target platform, it is recommended to generate the SDK without built-in support for typography.
|
||||
* **Performant**
|
||||
* Built to perform the best when using a modern graphics API like Metal or Vulkan (not all may be available to start) and when running on mobile tiler GPUs like the ones found in smartphones and AppleSilicon/ARM desktops.
|
||||
* Impeller does need a GPU. Performance will likely be inadequate for interactive use cases when using software rendering. Software rendering can be enabled using projects like SwiftShader, Angle, LLVMPipe, etc… If you are using software rendering in your projects, restrict its use to testing on CI. Impeller will likely never have a dedicated software renderer.
|
||||
|
||||
# Prebuilt Artifacts
|
||||
|
||||
Users may plug in any toolchain into the Flutter Engine build system to build the libimpeller.so dynamic library. However, for the common platforms, the CI bots upload a tarball containing the library and headers. This URL for the SDK tarball for a particular platform can be constructed as follows:
|
||||
> [!IMPORTANT]
|
||||
> Users of these prebuilt artifacts should strip the binaries before deployment as these contain debug symbols.
|
||||
|
||||
Users may plug in a custom toolchain into the Flutter Engine build system to build the `libimpeller.so` dynamic library. However, for the common platforms, the CI bots upload a tarball containing the library and headers. This URL for the SDK tarball for a particular platform can be constructed as follows:
|
||||
|
||||
```sh
|
||||
https://storage.googleapis.com/flutter_infra_release/flutter/$FLUTTER_ENGINE_SHA/$PLATFORM_ARCH/impeller_sdk.zip
|
||||
```
|
||||
|
||||
The `$FLUTTER_ENGINE_SHA` is the Git hash in the Flutter Engine repository. To make sure all artifacts for a specific hash have been successfully generated, look up the Flutter Engine SHA currently used by the Flutter Framework in the [engine.version](https://github.com/flutter/flutter/blob/master/bin/internal/engine.version) file.
|
||||
|
||||
The `$PLATFORM_ARCH` can be determined from the table below.
|
||||
The `$FLUTTER_ENGINE_SHA` is the Git hash in the Flutter Engine repository. To make sure all artifacts for a specific hash have been successfully generated, look up the Flutter Engine SHA currently used by the Flutter Framework in the [engine.version](https://github.com/flutter/flutter/blob/master/bin/internal/engine.version) file. The `$PLATFORM_ARCH` can be determined from the table below.
|
||||
|
||||
| | macOS | Linux | Android | Windows |
|
||||
|:-----:|:------------:|:-----------:|:--------------:|:-------------:|
|
||||
@ -61,11 +40,54 @@ The `$PLATFORM_ARCH` can be determined from the table below.
|
||||
| x64 | darwin-x64 | linux-x64 | android-x64 | windows-x64 |
|
||||
|
||||
|
||||
For example, the SDK for `Linux x64` at engine SHA `31aaaaad868743b38ac3b7165f0d58eca94e521b` would be https://storage.googleapis.com/flutter_infra_release/flutter/31aaaaad868743b38ac3b7165f0d58eca94e521b/linux-x64/impeller_sdk.zip
|
||||
_For example, the SDK for `Linux x64` at engine SHA `202506d686e317862d81548b8afcae9c9eecaa90` would be [this link](https://storage.googleapis.com/flutter_infra_release/flutter/202506d686e317862d81548b8afcae9c9eecaa90/linux-x64/impeller_sdk.zip)_
|
||||
|
||||
# Example
|
||||
# Examples
|
||||
|
||||
A fully functional example of using Impeller to draw using GLFW is available in [`example.c`](example.c). This example is also present in the `impeller_sdk.zip` prebuilts along with necessary artifacts.
|
||||
A quick peek at the API that shows rendering different shapes using the provided [C++ wrapper to the C API](#c-wrapper) is as follows:
|
||||
|
||||
```c++
|
||||
DisplayListBuilder builder;
|
||||
|
||||
Paint red_paint;
|
||||
red_paint.SetColor({1.0, 0.0, 0.0, 1.0});
|
||||
red_paint.SetStrokeWidth(10.0);
|
||||
|
||||
builder.Translate(10, 10);
|
||||
builder.DrawRect({0, 0, 100, 100}, red_paint);
|
||||
builder.Translate(100, 100);
|
||||
builder.DrawOval({0, 0, 100, 100}, red_paint);
|
||||
builder.Translate(100, 100);
|
||||
builder.DrawLine({0, 0}, {100, 100}, red_paint);
|
||||
|
||||
builder.Translate(100, 100);
|
||||
ImpellerRoundingRadii radii = {};
|
||||
radii.top_left = {10, 10};
|
||||
radii.bottom_right = {10, 10};
|
||||
builder.DrawRoundedRect({0, 0, 100, 100}, radii, red_paint);
|
||||
|
||||
builder.Translate(100, 100);
|
||||
builder.DrawPath(hpp::PathBuilder{}.AddOval({0, 0, 100, 100}).Build(),
|
||||
red_paint);
|
||||
|
||||
auto dl = builder.Build();
|
||||
|
||||
// Per frame
|
||||
hpp::Surface window(surface);
|
||||
window.Draw(dl);
|
||||
```
|
||||
|
||||
### Standalone
|
||||
|
||||
A fully functional example of using Impeller to draw using GLFW is available in [`example.c`](example.c). This example is also present in the `impeller_sdk.zip` [prebuilts](#prebuilt-artifacts) along with necessary artifacts.
|
||||
|
||||
### CMake
|
||||
|
||||
A demo of using CMake to fetch prebuilt artifacts and build the demo is [available here](https://github.com/chinmaygarde/impeller_cmake_demo).
|
||||
|
||||
## C++ Wrapper
|
||||
|
||||
For users of the library using C++, a single-header-only C++ 17 library is provided that wraps the single-header C API ([`impeller.h`](impeller.h)). This headers ([`impeller.hpp`](impeller.hpp)) is distributed as part of the [prebuilt artifacts](#prebuilt-artifacts) as well.
|
||||
|
||||
# API Fundamentals
|
||||
|
||||
@ -97,3 +119,11 @@ Methods in the Impeller API follow a very strict convention. This makes it easy
|
||||
## Null Safety
|
||||
|
||||
The Impeller API passes [nullability completeness](https://clang.llvm.org/docs/DiagnosticsReference.html#wnullability-completeness) checks. All pointer arguments and return values are decorated with `IMPELLER_NULLABLE` and `IMPELLER_NONNULL`. Passing a null pointer to an argument decorated with `IMPELLER_NONNULL` will very likely result in a null pointer dereference. When generating automated bindings to other languages, it is recommended that these decorations be used to inform the API and perform additional checks.
|
||||
|
||||
## API Stability
|
||||
|
||||
Unlike the [Flutter Embedder API]([url](https://docs.flutter.dev/embedded)) which has a stable API as well as ABI, the Impeller API does **not** currently have stability guarantees.
|
||||
|
||||
However, the API does look similar to the one used by Flutter in Dart. So major overhauls are not realistically on the horizon.
|
||||
|
||||
The API is also versioned and there may be stability guarantees between specific versions in the future.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user