[Impeller] Document how to use Impeller as a standalone library with OpenGL ES and EGL. #52473
Conversation
|
Patched up the EGL toolkit headerdocs in #52469 |
chinmaygarde
added
the
autosubmit
auto-submit
bot
removed
the
autosubmit
|
auto label is removed for flutter/engine/52473, due to - The status or check suite Linux mac_android_aot_engine has failed. Please fix the issues identified (or deflake) before re-applying this label. |
chinmaygarde
added
the
autosubmit
auto-submit
bot
removed
the
autosubmit
|
auto label is removed for flutter/engine/52473, due to - The status or check suite Linux mac_android_aot_engine has failed. Please fix the issues identified (or deflake) before re-applying this label. |
chinmaygarde
force-pushed
the
impeller_gl_porting_guide
branch
from
2ea87f3 to
6d708a3
Compare
chinmaygarde
added
the
autosubmit
|
auto label is removed for flutter/engine/52473, due to - The status or check suite Linux linux_host_engine has failed. Please fix the issues identified (or deflake) before re-applying this label. |
auto-submit
bot
removed
the
autosubmit
impeller/docs/standalone_gles.md
Outdated
|
|
||
| ## Render to the Surface | ||
|
|
||
| Give the surface to the rendere along with a callback that details how you will populate the render target the renderer sets up that is directed at that surface. |
There was a problem hiding this comment.
| Give the surface to the rendere along with a callback that details how you will populate the render target the renderer sets up that is directed at that surface. | |
| Give the surface to the renderer along with a callback that details how you will populate the render target the renderer sets up that is directed at that surface. |
impeller/docs/standalone_gles.md
Outdated
| }); | ||
| ``` | ||
|
|
||
| And that's it. Now you have functional WSI and render loop. Higher level frameworks like Aiks and DisplayList that use the render target to render their rendering into to the surface. |
There was a problem hiding this comment.
| And that's it. Now you have functional WSI and render loop. Higher level frameworks like Aiks and DisplayList that use the render target to render their rendering into to the surface. | |
| And that's it. Now you have a functional WSI and render loop. Higher level frameworks like Aiks and DisplayList use the render target to render their rendering into the surface. |
chinmaygarde
added
the
autosubmit
auto-submit
bot
removed
the
autosubmit
|
auto label is removed for flutter/engine/52473, due to - The status or check suite Mac mac_unopt has failed. Please fix the issues identified (or deflake) before re-applying this label.
|
| First create an EGL display connection: | ||
|
|
||
| ```c++ | ||
| egl::Display display; |
There was a problem hiding this comment.
nit: would be nice to include headers for the various symbols referenced, although that would make this doc a bit more fragile.
There was a problem hiding this comment.
Yeah, I figured linking the patch would be sufficient and leaving the includes for brevity.
There was a problem hiding this comment.
fwiw (not saying we need to do this here), what we do in the flutter/flutter repo is literally extract out the ``` bits of code and statically analyze them, and what we do in the flutter/packages repo is have the README files explicitly link to actual code that is tested and then enforce that the README file snippets match the actual code. In both cases the result is that code in documentation is checked on every commit.
There was a problem hiding this comment.
I spoke to @yjbanov and I may just check in the code (in a separate patch). Previously, I didn't want to setup the toolchain and testing for a target just for documentation.
impeller/docs/standalone_gles.md
Outdated
|
|
||
| This guide describes how to use Impeller as a standalone rendering library using OpenGL ES. Additionally, some form of WSI (Window System Integration) is essential. Since EGL is the most the most popular form of performing WSI on platforms with OpenGL ES, Impeller has a toolkit that assists in working with EGL. This guide will use that toolkit. | ||
|
|
||
| While this guide focuses on OpenGL ES with EGL, the steps to setup rendering with another client rendering API (Metal and Vulkan) are fairly similar and you should be able to follow the same pattern for other backends. |
There was a problem hiding this comment.
setup rendering -> set up rendering or maybe even set rendering up
impeller/docs/standalone_gles.md
Outdated
|
|
||
| While this guide focuses on OpenGL ES with EGL, the steps to setup rendering with another client rendering API (Metal and Vulkan) are fairly similar and you should be able to follow the same pattern for other backends. | ||
|
|
||
| This guide details extremely low-level setup and the `//impeller/renderer` API directly above the HAL. Most users of Impeller will likely use the API using convenience wrappers already written for the platform. Interacting directly with the HAL is extremely powerful but also verbose. Applications are likely to also use higher level frameworks like Aiks or Display Lists. |
There was a problem hiding this comment.
can Aiks and Display Lists link to documentation for them?
| Building Impeller for the target platform is outside the scope of this guide. | ||
|
|
||
| > [!CAUTION] | ||
| > The code provided inline is pseudo-code and doesn't include error handling. See the headerdocs for more on error handling and failure modes. All classes are assumed to be in the `impeller` namespace. For a more complete example of setting up standalone Impeller, see [this patch](https://github.com/flutter/engine/pull/52472/files) that adds support for Impeller rendering via Wasm [in the browser and WebGL 2](https://public.chinmaygarde.com/impeller/wasm/wasm.html). |
There was a problem hiding this comment.
the patch will bit rot over time, is there some way we can link to tested code that will remain up to date?
There was a problem hiding this comment.
In a separate patch, I'm going to check it in. I didn't want to setup the toolchain and testing for a target that was a toy.
impeller/docs/standalone_gles.md
Outdated
|
|
||
| ## Setup the Swap Callback | ||
|
|
||
| The swap callback will get invoked when the renderer presents the surface. Remember in our list of things to do, we need to first tell the reactor worker to flush all pending OpenGL operations and then present the surface. Setup the swap callback appropriately. |
There was a problem hiding this comment.
actually Set the swap callback up
|
This is great, so happy to see these kinds of docs. I hope you don't mind the nitpicky nature of my grammar comments. |
Not at all. Want to add to these docs at a regular cadence. |
chinmaygarde
force-pushed
the
impeller_gl_porting_guide
branch
from
6d708a3 to
59ad8d7
Compare
|
@Hixie PTAL. |
chinmaygarde
added
the
autosubmit
…rary with OpenGL ES and EGL. (flutter/engine#52473)
…147904) flutter/engine@4cb9e02...b64e230 2024-05-06 [email protected] [Impeller] Document how to use Impeller as a standalone library with OpenGL ES and EGL. (flutter/engine#52473) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-engine-flutter-autoroll Please CC [email protected],[email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Flutter: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
5 participants
Preview: https://github.com/chinmaygarde/flutter_engine/blob/impeller_gl_porting_guide/impeller/docs/standalone_gles.md